## 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](https://docs.arcblock.io/forge/latest/sdk/)

---
### [Wallet](https://crates.io/crates/forge_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](https://github.com/ArcBlock/forge-rust-sdk/blob/master/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](https://github.com/ArcBlock/rust-sdk-example). [More Examples](https://github.com/ArcBlock/forge-rust-sdk/tree/master/grpc/src/example)

- 1.Set `Cargo.toml`
  ```rust
  [dependencies]
  forge_wallet = "^0.1.2"
  forge_grpc = "^0.1.3"
  ```
- 2.Add connection with forge chain.
  ```rust
  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.
  ```rust
  // 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.
  ```rust
  request.wallet = alice.clone();
  forge_grpc::poke(&request)?;
  ```
- 5.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)?;
  ```
- 6.Alice, bob check balance.
  ```rust
  // 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](https://github.com/ArcBlock/forge-rust-sdk/blob/master/grpc/src/lib.rs)** 
  
  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](https://github.com/ArcBlock/forge-rust-sdk/tree/master/grpc/src/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](https://crates.io/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](https://crates.io/crates/forge_util): provide some help apis, such as `save a json to local`, etc.
- [forge_did](https://crates.io/crates/forge_did): generate `forge did` from pk, or sk, or pk hash. `forge did` example `did:abt:zNYm1gM23ZGHNYDYyBwSaywzTqLKoj4WuTeC`.
- [forge_hasher](https://crates.io/crates/forge_hasher): provide some hash algorithms, such as `blake2b`,`keccak`, `sha2`, `sha3`.
- [forge_signer](https://crates.io/crates/forge_signer): provide some sign algorithms, such as `ed25519`,`secp256k1`.
- [forge_crypter](https://crates.io/crates/forge_crypter): provide some crypt algorithms, such as `ed25519`.