Skip to main content
This page is the CLI reference for the activation lifecycle: build an unsigned activation, optionally simulate it, sign it (in-process or on a separate machine), submit it, and then inspect the result. For the conceptual model (what an activation is, what is signed, how IDs are computed), see Activations and Activation structure. For the ready-made transfer and faucet wrappers, see Sending transfers. All commands accept the global --rpc-url <URL> (-s), --header <NAME=VALUE>, and --json (-j) flags. JSON mode emits a single envelope ({ ok, command, timestamp, result | error }).

​
Two surfaces: gen wallet and gen client

The activation commands are mirrored under both gen wallet and gen client:
  • gen wallet <cmd> resolves the signing wallet via the usual precedence (positional NAME, --wallet, then the active wallet recorded in ~/.gen/wallets/config.toml).
  • gen client <cmd> is the lower-level form. It accepts the same flags but does not fall back to the active wallet for commands that need one.
Pick whichever fits your script. The on-chain effect is identical.

​
Lifecycle in one flow

The longest possible flow uses every command in sequence: 
# 1. Build the unsigned activation against a component method.
gen wallet build-activation alice \
  --component-id grd@<entity+index>,grd@<contract> \
  --method transfer \
  --params '{"to": "grd@...", "amount": ["1000"]}' \
  > unsigned.txt

# 2. (Optional) Dry-run against current state before broadcasting.
gen client simulate-activation --unsigned-activation-file unsigned.txt

# 3. Sign locally (or move unsigned.txt to a signer machine and sign there).
gen wallet sign-activation alice --unsigned-activation-file unsigned.txt > signed.txt

# 4. Submit the signed activation from anywhere.
gen client submit-activation --signed-activation-file signed.txt

# 5. Inspect the on-chain result.
gen client get-activation --activation-id 0x...
For the common case where you want all five steps in one call, use sign-and-submit-activation.

​
build-activation

Construct an unsigned activation against a component method. The output is the canonical pre-image bytes; nothing has been signed and nothing has touched the network. 
gen wallet build-activation alice \
  --component-id grd@<entity+index>,grd@<contract> \
  --method transfer \
  --params '{"to": "grd@...", "amount": ["1000"]}'

gen wallet build-activation alice \
  --component-id grd@<entity+index>,grd@<contract> \
  --method transfer \
  --args '["grd@...", ["1000"]]'

gen wallet build-activation alice \
  --request '{"component_id":"grd@...,grd@...","function":"transfer","params":{"to":"grd@...","amount":["1000"]}}'

gen wallet --json build-activation alice --request-file ./activation-request.json
Three mutually exclusive ways to specify the call:
  • --component-id + --method + --params or --args (one of --params/--args).
  • --request <JSON_OBJECT>: a single JSON blob with component_id, function, and one of params or args.
  • --request-file <PATH>: the same JSON blob read from a file.
Optional wallet selection:
  • [NAME] (positional) or --wallet <NAME> selects the wallet whose public key is used as the signer (and, by default, the target).
gen client build-activation accepts the same flags but does not fall back to the active wallet. The output is the unsigned activation bytes (0x-prefixed hex by default; or inside the JSON envelope under --json). Treat it as opaque: pass it to sign-activation or simulate-activation unchanged.

​
simulate-activation

Dry-run an unsigned activation against the validator without broadcasting. Returns the same execution result the network would produce: per-operation storage changes, emitted events, continuations, and the outcome. 
gen client simulate-activation --unsigned-activation 0x...
gen client simulate-activation --unsigned-activation-file ./unsigned.txt --block-index 42
gen client --json simulate-activation --unsigned-activation-file ./unsigned.txt
Required (one of):
  • --unsigned-activation <HEX_OR_BASE64>: bytes inline.
  • --unsigned-activation-file <PATH>: bytes read from a file (hex or base64 text).
Optional:
  • --block-index <BLOCK_INDEX>: simulate against state at a specific block. Defaults to the latest finalized block.
Simulation does not check signatures and does not consume any tag or expiry; it is purely a state read. Use it before signing to verify parameters, surface ABI mismatches, and estimate gas.

​
sign-activation

Sign an unsigned activation with a wallet’s private key. The signature covers the 82-byte pre-image derived from the activation; see What is signed. 
gen wallet sign-activation --unsigned-activation-file ./unsigned.txt
gen wallet sign-activation alice --unsigned-activation 0x...
gen wallet sign-activation alice --unsigned-activation-file ./unsigned.txt --activation-tag 77
gen wallet --json sign-activation alice --unsigned-activation-file ./unsigned.txt
Required (one of):
  • --unsigned-activation <HEX_OR_BASE64>: bytes inline.
  • --unsigned-activation-file <PATH>: bytes read from a file.
Optional:
  • [NAME] (positional) or --wallet <NAME>: signing wallet. Defaults to the active wallet.
  • --activation-tag <U32>: override the tag field before signing. Use this when you need to resubmit a structurally identical activation without tripping replay protection. Two activations with the same signer, target, and operations but different tags get different IDs.
The same wallet that built the activation must sign it (the signer public key is baked into the unsigned bytes). The output is the signed activation, ready for submit-activation. gen client sign-activation is the same command without the active-wallet fallback.

​
submit-activation

Send a pre-signed activation to the network. 
gen client submit-activation --signed-activation 0x...
gen client submit-activation --signed-activation-file ./signed.txt
gen client submit-activation --signed-activation-file ./signed.txt --no-wait
Required (one of):
  • --signed-activation <HEX_OR_BASE64>: bytes inline.
  • --signed-activation-file <PATH>: bytes read from a file.
Optional:
  • --no-wait: return as soon as the validator acknowledges the submission, instead of waiting for the activation to complete. The response still contains the activation_id; follow up with get-activation to confirm the final outcome.
submit-activation does not need a wallet: the activation is already signed, and the signer is recorded in the signed bytes. This is the command you run on an internet-connected machine after signing on an isolated one.

​
sign-and-submit-activation

Sign and submit in a single call. Convenience for the common in-process flow. 
gen wallet sign-and-submit-activation alice --unsigned-activation 0x...
gen wallet sign-and-submit-activation alice --unsigned-activation-file ./unsigned.txt --activation-tag 77 --no-wait
gen wallet --json sign-and-submit-activation alice --unsigned-activation-file ./unsigned.txt
Required (one of):
  • --unsigned-activation <HEX_OR_BASE64>
  • --unsigned-activation-file <PATH>
Optional:
  • [NAME] (positional) or --wallet <NAME>: signing wallet. Defaults to the active wallet for gen wallet; required for gen client.
  • --activation-tag <U32>: override the tag before signing.
  • --no-wait: return after the validator acknowledges submission.
gen client sign-and-submit-activation is the same call without the active-wallet fallback.

​
get-activation

Fetch the on-chain record for an activation: status, gas used, emitted events, and the block range it occupied. 
gen client get-activation --activation-id 0x<128 hex chars>
gen client --json get-activation --activation-id 0x...
Required flags:
  • --activation-id <0x...>: activation ID (128 hex characters, 0x-prefixed).
The JSON result includes:
  • status: success, failed, or pending.
  • start_block / end_block: the block range the activation occupied. end_block is final once status is success or failed.
  • gas_used: { cpu, network, storage_io }, each as a decimal u128 string. See Gas and fees.
  • events: domain events emitted during execution, with payloads as base64.
  • continuations: the IDs of any follow-up activations this one triggered.
  • from / to: signer entity and target entity.
get-activation returns a JSON-RPC NOT_FOUND error if the ID is unknown.

​
Tracing

​
get-trace

A trace groups an activation with every continuation it produced across entities. Use it when you need the full graph an activation kicked off, not just the activation itself. See Traces for the concept. 
gen client get-trace --trace-id 0x<128 hex chars>
gen client --json get-trace --trace-id 0x...
Required flags:
  • --trace-id <0x...>: trace ID (128 hex characters, 0x-prefixed).
The result is a flat list of activation IDs. Inspect each one with get-activation to assemble the per-step detail.

​
When to use which

  • Online, single machine. Use sign-and-submit-activation directly, or skip the activation primitives entirely and use the wrappers in Sending transfers.
  • Sign offline, submit elsewhere. build-activation on the online machine, copy the unsigned bytes to the air-gapped signer, sign-activation there, copy the signed bytes back, submit-activation from anywhere on the network.
  • Dry-run first. Insert simulate-activation between build-activation and sign-activation. Cheap and signature-free, and it surfaces ABI mismatches and reverts before you commit to broadcasting.
  • Submit and poll. Pass --no-wait to submit-activation or sign-and-submit-activation when you want the activation ID immediately and will check the final state later with get-activation.
  • Resubmit an identical-looking activation. Override the tag with --activation-tag <U32> on sign-activation or sign-and-submit-activation. This produces a different activation ID and bypasses dedup.

​
See also