Transfer between two accounts

gen v0.14.0 — get-account’s response no longer exposes a flat token_holder_component_id; the holder lives under result.account.components[] with component_type_index == 2. The CLI tab below uses wallet transfer, which wraps the build / sign / submit primitive and resolves the holder for you. The Rust SDK tab shows the primitive directly, because ActivationPayload::builder() still gives you full control over each call.

This is the lesson where you learn the one workflow that powers every state change on the Grid: build an unsigned activation → sign and submit it. Every contract call you’ll ever make follows this same shape. A transfer is just the smallest meaningful example.

Prerequisites · Your first account + Fund from the faucet done. $ALICE is funded. You’re back on local (or still on DevNet — either works).

Running against local or DevNet

Pick the tab for the environment you’re targeting and paste once. The commands further down the lesson use $SERVER_URL and (on DevNet) the persisted auth header, so they don’t need per-environment edits.

Local
DevNet

Make sure a local validator is running (gen service validator local --embedded-config in another terminal), then:

export SERVER_URL="http://127.0.0.1:30001"

DevNet access. Ask your Gen Labs contact for the RPC URL and a bearer token; substitute them for <DEVNET_RPC_URL> and <your-jwt> below. Persisting the header with gen config set means the rest of the lesson runs without --header on each command.

export SERVER_URL="<DEVNET_RPC_URL>"

"$GEN" config set header authorization "Bearer <your-jwt>"

Set up a second account

We need a recipient. Repeat lesson 1 with a new name:

"$GEN" wallet --rpc-url "$SERVER_URL" --json create bob --plaintext
BOB=$("$GEN" wallet --rpc-url "$SERVER_URL" --json show bob | jq -r '.result.account')
echo "$BOB"

Bob has no balance and no on-chain presence yet. The transfer we’re about to do will give him both.

Steps

CLI
Rust SDK

Send 0.5 USDG from alice to bob

The CLI ships wallet transfer as a one-liner that wraps the build / sign / submit primitive internally — it resolves both accounts’ token- holder components, encodes the transfer_with_confirmation call, signs it with the source wallet, and submits the activation.

"$GEN" wallet --rpc-url "$SERVER_URL" --json transfer \
  --wallet alice \
  --to "$BOB" \
  --amount 500000000 \
  --yes

Flags:

--to "$BOB" — recipient account in grd@... form (NOT a token-holder component; the CLI resolves that for you).
--amount — subunits, same convention as the faucet (1_000_000_000 subunits = 1 USDG).
--yes — skip the interactive confirmation prompt (useful in scripts).

Behind this one command, the CLI is doing exactly the build-activation → sign-and-submit-activation flow you’ll see in the Rust tab. Splitting those two steps is how Grid lets you build agentic systems where the signer (a wallet the user controls) doesn’t have to trust the builder (your backend, an MCP server). The Rust example below shows the primitives directly.

Confirm the move

"$GEN" client --rpc-url "$SERVER_URL" --json balance --account "$ALICE"
"$GEN" client --rpc-url "$SERVER_URL" --json balance --account "$BOB"

Alice should be down 500 000 000 subunits; Bob should be up the same. The universe is in balance.

Uses the client you built in lesson 3.

Resolve each account's token-holder component

use vm_primitives::gvm::{GvmAccount, GvmComponentId};
use std::str::FromStr;

let alice = GvmAccount::from_str(&std::env::var("ALICE")?)?;
let bob   = GvmAccount::from_str(&std::env::var("BOB")?)?;

let sender_holder = client.get_account(alice).await?
    .components.iter()
    .find(|c| c.header().component_code_id().component_type_index().as_u32() == 2)
    .expect("alice has no token holder — run lesson 2 first")
    .clone();
let recipient_holder = client.get_account(bob).await?
    .components.iter()
    .find(|c| c.header().component_code_id().component_type_index().as_u32() == 2)
    .expect("bob has no token holder")
    .clone();

Same shape as the CLI’s client get-account | jq — pick the component with component_type_index == 2 (the token-holder).

Build the unsigned activation

use client_sdk::{encode_args_from_object, ActivationOptions};
use client_sdk::payload::ActivationPayload;
use serde_json::json;

let component_id: GvmComponentId = sender_holder.header().id().clone();
let abi = client.get_abi_by_contract_code_id(
    sender_holder.header().component_code_id().contract_code_id().clone()
).await?;

let params = json!({
    "amount":      ["500000000"],
    "destination": recipient_holder.header().id().to_string(),
}).as_object().unwrap().clone();
let args_bytes = encode_args_from_object(
    &abi, "transfer_with_confirmation", &params,
)?;

let payload = ActivationPayload::builder()
    .component_id(component_id)
    .function("transfer_with_confirmation".to_string())
    .args_bytes(args_bytes)
    .build();

ActivationPayload::builder().build() is the off-chain build — equivalent to the CLI’s client build-activation.

Sign and submit it

use client_sdk::GenSigner;
use gen_rpc_wire::ActivationTag;

let signer: GenSigner = load_signer("alice")?;   // see lesson 1
let opts = ActivationOptions::builder()
    .tag(ActivationTag::new(rand::random::<u32>() & 0x7FFF_FFFF))
    .build();
let outcome = client
    .sign_and_submit_and_wait_activation_with_options(&signer, &payload, &opts)
    .await?;
println!("finalized: {outcome:?}");

Build-vs-sign split — serialize the ActivationPayload between a builder service and a signer process to get the agentic pattern. Use sign_and_submit_activation_with_options (no _and_wait) for the no-wait variant — returns immediately with an activation id. ActivationTag must be unique per submission to avoid on-chain dedup.

Confirm the move

let alice_after = client.get_balance(alice).await?;
let bob_after   = client.get_balance(bob).await?;
println!("alice: {} | bob: {}", alice_after.value(), bob_after.value());

What just happened

You executed the only write pattern the Grid has:

build-activation  →  sign-and-submit-activation
   (off-chain)       (one round-trip on-chain)

Every contract call in the deploy and call chapters, every transfer your production app will ever do — they all follow this exact shape. Internalize it once.

Receipt · 1 activation · 0.001¢ USDG · ~10 ms · And it’ll cost 0.001¢ next month, next quarter, next year. The price doesn’t move because the unit is USDG, not GEN.

The non-volatility moment, plainly

Imagine you’re building an agent that does 1 000 transfers per day. On chains that price gas in native token:

A 3× price spike means a 3× cost spike, with no warning.
You can either over-provision (waste capital) or under-provision (your agent stalls).
You spend engineering time building “wait for cheap gas” heuristics.

On Grid, 1 000 transfers/day is 1 000 × 0.001¢ = 1¢ per day. That number does not move. Budgeting becomes arithmetic, not forecasting.

From the Rust tab

The CLI tab and the Rust tab hit the same JSON-RPC. Two things the Rust path lets you control that wallet transfer doesn’t:

Authenticating to DevNet

DevNet’s RPC requires a bearer token. Build a ClientConfig so every request carries the Authorization header:

use std::collections::BTreeMap;
use client_sdk::{ClientConfig, GenClient};

let mut headers = BTreeMap::new();
headers.insert(
    "authorization".into(),
    format!("Bearer {}", std::env::var("GEN_DEVNET_BEARER_TOKEN")?),
);

let config = ClientConfig::builder()
    .server_url("<DEVNET_RPC_URL>".into())
    .headers(headers)
    .build();

let client = GenClient::new_http_with_rpc_config(config)?;

Header names are lowercased. Read the JWT from a secret store (env var, secret manager, KMS); don’t hardcode it.

The `SdkError` variants you’ll see in production

sign_and_submit_and_wait_activation_with_options returns Result<TraceOutcome, SdkError>. The variants worth branching on:

SdkError::Transport(_) — endpoint unreachable, TLS failed, or timeout. Retry with backoff, or fail over to a backup endpoint.
SdkError::Server { .. } — endpoint replied with HTTP error. 401/403 means the JWT is missing or expired (rotate it). 429 means rate-limited (back off).
SdkError::ActivationPolling(_) — submit succeeded but the trace took too long to finalize. Re-fetch by activation_id instead of resubmitting; duplicate submissions cost gas and may be rejected once valid_until_block lapses.
SdkError::EddsaSigner(_) — the signer failed (KMS down, key locked, hardware wallet timeout). The original error is preserved as the source.
Activation finalized with non-success status. This is not an Err; the call returns Ok(outcome) with the failure recorded in the trace (insufficient balance, contract-side error, etc.). Always inspect outcome before treating the transfer as done.

Insufficient balance surfaces in the activation status, not as a transport-level error; the validator simulates the call and records the failure on chain. For production deployments where the key must stay outside the process, see Sign with an external KMS.

Troubleshooting

`InsufficientBalance` despite a healthy balance

Check that --amount in subunits is what you think it is. 1 USDG is 1_000_000_000 subunits — easy to lose a zero.

`UnknownFunction: transfer_with_confirmation`

You resolved the holder component for a contract that doesn’t expose that function. The default token-holder used by the faucet does — but custom token contracts may use a different name. client get-account shows the available methods per component.

What’s next

Deploy a contract from ABI

Push, deploy, and install the simple-token contract you built in the Contract Development workshop.

​Running against local or DevNet

​Set up a second account

​Steps

​What just happened

​The non-volatility moment, plainly

​From the Rust tab

​Authenticating to DevNet

​The SdkError variants you’ll see in production

​Troubleshooting

​What’s next

Deploy a contract from ABI

Running against local or DevNet

Set up a second account

Steps

What just happened

The non-volatility moment, plainly

From the Rust tab

Authenticating to DevNet

The `SdkError` variants you’ll see in production

Troubleshooting

What’s next