#forge #applications #interaction #api-client #grpc

forge_sdk

The rust language implementation of forge sdk

3 releases

0.1.3 Oct 21, 2019
0.1.2 Oct 16, 2019
0.1.0 Oct 12, 2019

#5 in #forge

Apache-2.0

3.5MB
78K SLoC

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

Coding your application

  • 3.Create your own Rust project.

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

    Details as rust_sdk_example

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

    • Create grpc connection with the chain created above:
      let chain_address = "127.0.0.1:28210";
      let chain_name = "chain_1";
      connection::add_connection(chain_name, chain_address)?;
      
    • Get the chain config:
      forge_grpc::get_chain_info(Some(chain_name.to_string()))?;
      
    • Declare wallet:
      use forge_grpc::transaction;
      // -.create two wallets: alice, bob
      let alice = forge_wallet::Wallet::create_default_wallet()?;
      let bob = forge_wallet::Wallet::create_default_wallet()?;
      
      // -.declare alice on chain
      let mut request = transaction::build_request::Request {
          wallet: alice.clone(),
          forge_name: Some(chain_name.to_string()),
          ..Default::default()
      };
      let mut declare = transaction::build_itx::Declare {
          moniker: Some(String::from("alice")),
          ..Default::default()
      };
      forge_grpc::declare(&request, &declare)?;
      
      // -.declare bob on chain
      request.wallet = bob.clone();
      declare.moniker = Some(String::from("bob_01"));
      let resp = forge_grpc::declare(&request, &declare)?;
      
    • Alice checkin to get some tokens:
      request.wallet = alice.clone();
      forge_grpc::poke(&request)?;
      
    • Alice transfer 1.0 token to bob:
      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 rust_sdk_example

    More examples see grpc_example


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

Dependencies

~67MB
~1M SLoC