gen CLI uses it under the hood, and so does every Rust integration. This page covers what to install, how to configure a client, and a worked example for the most common job: sending a transfer.
For the full API reference, see the rustdoc on docs.rs (when published) or build it locally with cargo doc -p client-sdk --open.
Crates
| Crate | What it is |
|---|---|
gen-rpc-client | Low-level JSON-RPC client. Implements every method on the JSON-RPC API. |
client-sdk | Runtime helpers for GenClient, GenSigner, shared payload types, account helpers, errors, and test utilities. |
client-sdk-macros | #[generate_component_client] and #[generate_contract_client] macros that generate typed payload clients from ABI or manifest inputs. |
dynamic-codecs | Dynamic ABI-driven encoding and decoding used by CLI tooling and runtime contract interaction without compile-time types. |
Install
The crates are not yet published to crates.io. Pull them from the gen-bc repo by Git tag:Cargo.toml directly:
v0.1.0 with the tag matching your target network.
Configure a client
GenClient owns RPC access, view execution, activation submission, and waiting. Most apps construct one and reuse it.
DevNet access. Ask your Gen Labs contact for the RPC URL and a bearer token, then substitute them for
<DEVNET_RPC_URL> and <your-jwt> in the examples below.new_http_with_rpc_config(...) accepts a ClientConfig if you need custom headers, timeouts, or a different RPC URL per request.
First call
Probe the validator to confirm connectivity:Send a transfer
Sending a transfer is a four-step flow: load a signer, build the activation payload, sign and submit it, await the result. The SDK collapses the last two into one call.- The example uses
build_transfer_payloadfromclient_sdk::faucet. That helper is the canonical path for moving the genesis token between accounts. To call a custom token contract, generate a typed client with#[generate_contract_client]and call itstransfermethod instead. sign_and_submit_and_wait_activationpolls until the activation reaches a terminal state. If you need fire-and-forget semantics usesign_and_submit_activationand follow up later withclient.wait(activation_id).AmountInSubunitsis the smallest unit of the token. The genesis token uses 18 decimals; convert as needed before passing.
Loading keys
GenSigner accepts raw bytes today. Most production agents will load from a wallet file written by the CLI or from a KMS. The CLI’s wallet store lives at ~/.gen/wallets/. To bridge from there programmatically, use gen wallet export (see gen wallet) and feed the result to GenSigner::from_private_key_bytes.
Never hard-code a private key in source. The example above uses [0u8; 32] only as a placeholder.
GenClient API surface
Every public method onGenClient, in source order. For full signatures and documentation, see the rustdoc.
| Method | Kind | Description |
|---|---|---|
new(...) | sync | |
new_http(...) | sync | Creates a new GenClient connected to the given HTTP RPC endpoint. |
new_http_with_rpc_config(...) | sync | Creates a new GenClient using a caller-provided transport configuration. |
rpc(...) | sync | Exposes the underlying GenRpcApiClient for direct RPC access. |
poll_config(...) | sync | |
wait_strategy(...) | sync | |
config(...) | sync | |
get_version(...) | async | Returns the server’s reported artifact release version and RPC protocol version. |
build_signable_activation(...) | sync | Builds the canonical unsigned activation that will later be signed, |
build_signable_activation_with_options(...) | sync | Builds the canonical unsigned activation that will later be signed. |
view(...) | async | Executes a read-only view call and returns the raw result bytes. |
simulate_activation(...) | async | Simulates a transaction without submitting it to the network. |
simulate_activation_with_options(...) | async | Simulates a transaction without submitting it to the network, using |
simulate_signable_activation(...) | async | Simulates a pre-built canonical unsigned activation without submitting it. |
submit_activation(...) | async | Submits a transaction and returns the activation ID. |
sign_and_submit_activation(...) | async | Builds, signs, and submits a transaction in one step. |
sign_and_submit_activation_with_options(...) | async | Builds, signs, and submits a transaction in one step, using |
wait(...) | async | Polls an already-submitted activation until it reaches a terminal state |
submit_activation_and_wait(...) | async | Submits a transaction and polls until the activation reaches a terminal |
sign_and_submit_and_wait_activation(...) | async | Builds, signs, submits, and waits for a transaction in one step. |
sign_and_submit_and_wait_activation_with_options(...) | async | Builds, signs, submits, and waits for a transaction in one step, using |
get_activation(...) | async | Queries the current status of an activation. |
get_account(...) | async | Returns entity information (owner, installed components). |
get_balance(...) | async | Returns the default GEN token balance for an account. |
get_balances(...) | async | Returns all fungible balances for an account. |
get_current_block_index(...) | async | Returns the latest finalized block index. |
get_block(...) | async | Returns an aggregated closed block for a given block index. |
get_component(...) | async | Returns component metadata and ABI. |
get_storage_at(...) | async | Returns the raw storage value for a component at a given key. |
get_contract(...) | async | Returns contract metadata and all component ABIs. |
get_abi_by_contract_id(...) | async | Returns contract ABIs by contract ID. |
get_abi_by_contract_code_id(...) | async | Returns contract ABIs by contract code ID. |
get_trace(...) | async | Returns every activation ID in a trace by its trace ID. |
create_account(...) | async | Submits a faucet-signed Account::create_entity_with_id(account) |
faucet(...) | async | Submits a faucet-signed transfer (or transfer_with_confirmation |
wait_for_tree_completion(...) | async | Waits for the entire activation tree rooted at activation_id to reach |
Errors
The SDK returns structuredSdkError variants. The ones you are likely to handle in production:
| Variant | When it fires |
|---|---|
Transport | Network error reaching the validator. Retry with backoff. |
Server | Validator returned a JSON-RPC error. Do not retry without inspecting code. |
ActivationPolling | Polling for activation status timed out. Re-check via get_activation. |
ActivationResult | The activation reached a non-success terminal state. The variant carries the failure reason. |
Encode / Decode | Borsh serialization failure on inputs or outputs. Almost always a type mismatch in your code. |
Next steps
- JSON-RPC reference: every wire-level method the SDK speaks.
- Send your first transfer (CLI): the same flow at the command line, useful for sanity-checking your setup.
- Programmatic transfers in Rust: full agent walkthrough that wraps this SDK.

