Lib.rs

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_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>
• sign(&self, message: &[u8]) -> Result<Vec<u8>>
• etc

grpc

Help you create/get connection with forge chain, then send messages to forge chain by the connection. Messages include GetInfo, SendTx, GetState, Subscribe/Unsubscribe, etc.

Connection Mod

Help you create/get connection with forge chain.

Transaction

Help you build transaction objects, then send it to forge chain.

Example Example how to create a local wallet, declare the wallet on forge chain, check in to get some tokens, then transfer some tokens to other. Example repo. More Examples

• 1.Set Cargo.toml

  [dependencies]
  forge_wallet = "^0.1.2"
  forge_grpc = "^0.1.3"
  

• 2.Add connection with forge chain.

  let chain_address = "127.0.0.1:28210";
  let chain_name = "chain_1";
  connection::add_connection(chain_name, chain_address)?;
  

• 3.Create two accounts: Alice, bob.

  // create two local wallets: Alice, Bob
  let alice = forge_wallet::Wallet::create_default_wallet()?;
  let bob = forge_wallet::Wallet::create_default_wallet()?;
  
  // declare Alice on forge 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 forge chain
  request.wallet = bob.clone();
  declare.moniker = Some(String::from("bob_01"));
  forge_grpc::declare(&request, &declare)?;
  

• 4.Alice checkin to get some tokens.

  request.wallet = alice.clone();
  forge_grpc::poke(&request)?;
  

• 5.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)?;
  

• 6.Alice, bob check balance.

  // sleep 5s to wait transfer transaction stable.
  std::thread::sleep(std::time::Duration::from_secs(5));
  let resp = forge_grpc::get_account_state(
      &vec![alice.address, bob.address],
      Some(chain_name.to_string()),
  )?;
  println!(
      "alice balance: {:#?}, bob balance: {:#?}",
      resp[0].get_state().get_balance().to_string(decimal),
      resp[1].get_state().get_balance().to_string(decimal)
  );
  

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