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

---
## 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](https://docs.arcblock.io/forge/latest/tools/forge_cli.html#install-forge-cli).
    - [Create a chain by forge cli](https://docs.arcblock.io/forge/latest/tools/forge_cli.html#install-forge-cli)
- 2.Install Rust development environment.
    - Install Rustup by cmd `curl https://sh.rustup.rs -sSf | sh`. [Details](https://www.rust-lang.org/tools/install)
    - [Install rustc](https://www.rust-lang.org/tools/install)
    - [Install cargo](https://www.rust-lang.org/tools/install)
### 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 [rust_sdk_example](https://github.com/ArcBlock/rust-sdk-example)
- 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 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:
      ```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](http://127.0.0.1:8210). `forge_web` default address `127.0.0.1:8210`.
    
    Details as [rust_sdk_example](https://github.com/ArcBlock/rust-sdk-example)
    
    More examples see [grpc_example](https://github.com/ArcBlock/forge-rust-sdk/tree/master/grpc/src/example)
---

### 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_grpc](https://crates.io/crates/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](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`.