Forge SDK

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

How to communicate with forge chains by Rust SDK?

Prepare

• 1.Install forge, and create a chain.
  • Install forge cli by $ npm install -g @arcblock/forge-cli. Details.
  • Create a chain by forge cli

• 2.Install Rust development environment.

  • Install Rustup by cmd curl https://sh.rustup.rs -sSf | sh. Details
  • Install rustc
  • Install cargo

    Coding your application

• 3.Create your own Rust project.

  • $ cargo new demo to create rust project names demo.
  • Set Dependencies of Cargo.toml rust [dependencies] forge_wallet = "^0.1.2" forge_grpc = "^0.1.3"
  • Use forge crates in main.rs or lib.rs rust extern crate forge_grpc; extern crate forge_wallet; Details as rustsdkexample

• 4.Coding you Rust project. Example as follows:

  • Create grpc connection with the chain created above: rust let chain_address = "127.0.0.1:28210"; let chain_name = "chain_1"; connection::add_connection(chain_name, chain_address)?;
  • Get the chain config: rust forge_grpc::get_chain_info(Some(chain_name.to_string()))?;

  • Declare wallet: ```rust use forgegrpc::transaction; // -.create two wallets: alice, bob let alice = forgewallet::Wallet::createdefaultwallet()?; let bob = forgewallet::Wallet::createdefault_wallet()?;

    // -.declare alice on chain let mut request = transaction::buildrequest::Request { wallet: alice.clone(), forgename: Some(chainname.tostring()), ..Default::default() }; let mut declare = transaction::builditx::Declare { moniker: Some(String::from("alice")), ..Default::default() }; forgegrpc::declare(&request, &declare)?;

    // -.declare bob on chain request.wallet = bob.clone(); declare.moniker = Some(String::from("bob01")); let resp = forgegrpc::declare(&request, &declare)?; ```

  • Alice checkin to get some tokens: rust request.wallet = alice.clone(); forge_grpc::poke(&request)?;
  • Alice transfer 1.0 token to bob: rust let decimal = connection::get_connection(Some(chain_name.to_string())).unwrap().get_decimal() as usize; let transfer_itx = transaction::build_itx::Transfer { to: Some(bob.address.to_owned()), value: Some(forge_grpc::BigUint::from_string("1", decimal)?), ..Default::default() }; forge_grpc::transfer(&request, &transfer_itx)?;
  • Then you can check transactions sent above on forge_web. forge_web default address 127.0.0.1:8210.

  Details as rustsdkexample

More examples see grpc_example

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_grpc: help you get connection with forge chain, search sth from chain, send txs to forge chain, etc.

  • 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>)
  • 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>)
  • 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)
  • 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.