Forge SDK - Grpc Client

To develop applications on top of the forge, you shall pick up a SDK. Forge SDK is intended to make the interaction with the chain built by Forge as easy as possible. All SDK APIs are organized into the following categories:

• chain APIs: provide the client wrapper for chain related gRPC
• wallet APIs: provide the client wrapper for wallet related gRPC
• state APIs: provide the client wrapper for state related gRPC
• subscription APIs: provide the client wrapper for subscription related gRPC
• transaction APIs: the gRPC for transaction is send_tx, this set of APIs provide helper functions to make building and sending a tx easy.
• misc APIs: parsing configuration, initialize sdk and more.

For more information, please see: Forge SDK overview

Wallet

Wallet package will help user create local account, verify signature, etc. Functions as follows:

Wallet APIs as follows:

• create_default_wallet() -> Result<Wallet>
• from_wallet_type(w_type: &WalletType) -> Result<Wallet>
• from_address(addr: &str) -> Result<Wallet>
• from_pk(pk: &[u8], w_type: &WalletType) -> Result<Wallet>
• from_sk(sk: &[u8], w_type: &WalletType) -> Result<Wallet>
• from_json(j: Value) -> Result<Wallet>
• to_json(&self) -> Result<Value>
• verify(&self, message: &[u8], signature: &[u8]) -> Result<bool>
• hash(&self, message: &[u8]) -> Result<Vec<u8>>
• sign(&self, message: &[u8]) -> Result<Vec<u8>>
• format_wallet(&mut self) -> Result<()>
• is_valid(wallet: &Wallet) -> bool

Example

Create two local wallets by create_default_wallet, which types are Account, Sha3, Ed25519 ```rust let alice = Wallet::createdefaultwallet()?; let bob = Wallet::createdefaultwallet()?;

```

GRPC

Help user create/get connection with forge chain, and communicate with forge chain by the connection.

Connection

• create connection: if start a forge chain with 127.0.0.1:28210, then create a connection and set alias name forge_chain_a with the forge chain as follows: rust let clients = connection::add_connection("forge_chain_a", "127.0.0.1:28210")?;

• get connection: get the connection created above in two ways: rust // get the conn by alias name `forge_chain_a` let conn = connection::get_connection(Some(String::from("forge_chain_a")))?; rust // get the first connection. let conn = connection::get_connection(None)?;

• APIS

  GRPC expose apis to help users get_info, send_tx, subscribe\unsubscribe, wallets, etc. Details as lib.rs

  • Get Functions
  • get_chain_info(chain_name: Option<String>)
  • get_chain_id(chain_name: Option<String>)
  • get_net_info(chain_name: Option<String>)
  • get_node_info(chain_name: Option<String>)
  • get_validators_info(chain_name: Option<String>)
  • get_config(is_parsed: Option<bool>, chain_name: Option<String>)
  • get_tx(txs: &[String], chain_name: Option<String>)
  • get_unconfirmed_txs(paging: &chain_client::PageInput, chain_name: Option<String>)
  • get_block(height: u64, chain_name: Option<String>)
  • multisig(multisig: &chain_client::RequestMultisig, chain_name: Option<String>)

  • search(key: &str, value: &str, chain_name: Option<String>)

  • Wallet Functions

    • create_wallet(request: &wallet_client::CreateWallet, forge_name: Option<String>)
    • recover_wallet(request: &wallet_client::RecoverWallet, forge_name: Option<String>)
    • remove_wallet(request: &wallet_client::RemoveWallet, forge_name: Option<String>)
    • list_wallet(forge_name: Option<String>)
    • declare_node(forge_name: Option<String>, validator: bool)

  • State Functions

  • get_account_state(wallet_addresses: &[String], chain_name: Option<String>)
  • get_forge_state(request: &state_client::ForgeState, chain_name: Option<String>)
  • get_protocol_state(request: Arc<state_client::RequestState>, chain_name: Option<String>)
  • get_asset_state(request: Arc<state_client::RequestState>, chain_name: Option<String>)
  • get_delegate_state(request: Arc<state_client::RequestState>, chain_name: Option<String>)
  • get_swap_state(request: Arc<state_client::RequestState>, chain_name: Option<String>)
  • get_tether_state(request: Arc<state_client::RequestState>, chain_name: Option<String>)

  • get_stake_state(request: Arc<state_client::RequestState>, chain_name: Option<String>)

  • SendTx Functions

  • declare(request: &Request, dec: &build_itx::Declare)
  • poke(request: &Request)
  • transfer(request: &Request, transfer: &build_itx::Transfer)
  • create_asset(request: &Request, itx: &build_itx::CreateAsset)
  • update_asset(request: &Request, itx: &build_itx::UpdateAsset)
  • consume_asset(request: &Request, itx: &build_itx::ConsumeAsset, asset_address: &str, signers: &[Wallet])
  • acquire_asset(request: &Request, itx: &build_itx::AcquireAsset)
  • exchange(request: &Request, itx: &build_itx::Exchange, signers: &[Wallet])
  • delegate(request: &Request, itx: &build_itx::DelegateTx)
  • account_migrate(request: &Request, itx: &build_itx::AccountMigrate)
  • deposit_token(request: &Request, itx: &build_itx::DepositToken)
  • setup_swap(request: &Request, itx: &build_itx::SetupSwap)
  • revoke_swap(request: &Request, itx: &build_itx::RevokeSwap)
  • retrieve_swap(request: &Request, itx: &build_itx::RetrieveSwap)
  • create_tx(request: &build_tx::CreateTx, forge_name: Option<String>)
  • prepare_exchange_tx(request: &Request, itx: &build_itx::Exchange, signers: &[Wallet])

  • send_simple_tx(request: &TxRequest, forge_name: Option<String>)

  • Event Functions

  • subscribe(request: &event_client::Subscribe, forge_name: Option<String>)
  • unsubscribe(request: &event_client::UnSubscribe, forge_name: Option<String>)

• Transaction Example

  Example mod shows that how send a tx to forge, txs such as declare, poke, asset, etc. Besides, the mod show that how create wallet, add connection, get connection, etc. Details as mod grpc/src/example.

  Support Tx types:

  • 1.create wallet
  • 2.transfer
  • 3.asset
  • 4.exchange
  • 5.delegate
  • 6.exchange delegate both
  • 7.atomic swap
  • 8.subscribe/unsubscribe
  • 9.migrate account

Related crates

• forge_wallet: help you create local account, verify signature, etc. APIs as follows:
  • create_default_wallet() -> Result<Wallet>
  • from_wallet_type(w_type: &WalletType) -> Result<Wallet>
  • from_pk(pk: &[u8], w_type: &WalletType) -> Result<Wallet>
  • from_sk(sk: &[u8], w_type: &WalletType) -> Result<Wallet>
  • verify(&self, message: &[u8], signature: &[u8]) -> Result<bool>
  • hash(&self, message: &[u8]) -> Result<Vec<u8>>
  • sign(&self, message: &[u8]) -> Result<Vec<u8>>
  • etc
• forge_util: provide some help apis, such as save a json to local, etc.
• forge_did: generate forge did from pk, or sk, or pk hash. forge did example did:abt:zNYm1gM23ZGHNYDYyBwSaywzTqLKoj4WuTeC.
• forge_hasher: provide some hash algorithms, such as blake2b,keccak, sha2, sha3.
• forge_signer: provide some sign algorithms, such as ed25519,secp256k1.
• forge_crypter: provide some crypt algorithms, such as ed25519.