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> takes the same wallet arguments and resolves them the same way, including the fallback to the active wallet.
Pick whichever fits your script. The on-chain effect is identical.

​
Lifecycle in one flow

The longest possible flow uses every command in sequence:
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 been submitted. Building still reaches the network to fetch the target component’s ABI (and, unless you pass --valid-until-block, the current block index for the expiry window); it only stops short of broadcasting.
Specify the call one of three mutually exclusive ways: --component-id with --method and one of --params/--args; a single --request JSON blob; or --request-file pointing at that same JSON. The [NAME] positional (or --wallet) selects the wallet whose public key is the signer (and, by default, the target), falling back to the active wallet when omitted; gen client build-activation takes the same flags and resolves the wallet the same way.
  • [NAME] (positional): Wallet to act on; defaults to the active wallet.
  • --wallet <NAME>: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet.
  • --valid-until-block <BLOCK_INDEX>: Explicit valid-until block index; set it to skip fetching the current block when building the unsigned activation.
  • --component-id <COMPONENT_ID>: Target component ID when building from flags.
  • --method <METHOD>: Contract method name when building from flags.
  • --params <JSON_OBJECT>: Method parameters as a JSON object with parameter names as keys.
  • --args <JSON_ARRAY>: Method parameters as a JSON array in ABI parameter order.
  • --request <JSON_OBJECT>: Build request as JSON with component_id, function, and optional params or args.
  • --request-file <PATH>: Read the build request JSON from a file.
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.
Supply the activation bytes one of two ways (one is required): inline with --unsigned-activation, or from a file with --unsigned-activation-file.
  • --unsigned-activation <HEX_OR_BASE64>: Unsigned activation bytes encoded as 0x-prefixed hex or base64.
  • --unsigned-activation-file <PATH>: Read unsigned activation bytes from a file containing 0x-prefixed hex or base64 text.
  • --block-index <BLOCK_INDEX>: Optional block index to simulate against. Defaults to the latest finalized block when omitted.
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.
Supply the unsigned bytes one of two ways (one is required): inline with --unsigned-activation, or from a file with --unsigned-activation-file. The [NAME] positional (or --wallet) selects the signing wallet, defaulting to the active wallet. Override --activation-tag 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.
  • [NAME] (positional): Wallet to act on; defaults to the active wallet.
  • --wallet <NAME>: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet.
  • --unsigned-activation <HEX_OR_BASE64>: Unsigned activation bytes encoded as 0x-prefixed hex or base64.
  • --unsigned-activation-file <PATH>: Read unsigned activation bytes from a file containing 0x-prefixed hex or base64 text.
  • --activation-tag <U32>: Override the activation tag before signing to make an otherwise-identical activation unique.
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 and resolves the wallet the same way, including the active-wallet fallback.

​
submit-activation

Send a pre-signed activation to the network.
Supply the signed bytes one of two ways (one is required): inline with --signed-activation, or from a file with --signed-activation-file. With --no-wait the call returns as soon as the validator acknowledges the submission; the response still contains the activation_id, so follow up with get-activation to confirm the final outcome.
  • --signed-activation <HEX_OR_BASE64>: Pre-signed activation bytes encoded as 0x-prefixed hex or base64.
  • --signed-activation-file <PATH>: Read a pre-signed activation from a file containing 0x-prefixed hex or base64 text.
  • --no-wait: Return immediately after sending without waiting for the activation to complete.
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.
Supply the unsigned bytes one of two ways (one is required): inline with --unsigned-activation, or from a file with --unsigned-activation-file. The [NAME] positional (or --wallet) selects the signing wallet, defaulting to the active wallet on both surfaces; gen client sign-and-submit-activation is otherwise the same call.
  • [NAME] (positional): Wallet to act on; defaults to the active wallet.
  • --wallet <NAME>: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet.
  • --unsigned-activation <HEX_OR_BASE64>: Unsigned activation bytes encoded as 0x-prefixed hex or base64.
  • --unsigned-activation-file <PATH>: Read unsigned activation bytes from a file containing 0x-prefixed hex or base64 text.
  • --no-wait: Return immediately after sending without waiting for the activation to complete.
  • --activation-tag <U32>: Override the activation tag before signing to make an otherwise-identical activation unique.

​
get-activation

Fetch the on-chain record for an activation: status, gas used, emitted events, and the block range it occupied.
  • --activation-id <ACTIVATION_ID>: Activation ID (128 hex characters with 0x prefix) (required).
In --json mode the activation details are nested under .result.activation:
  • status: pending, running, success, or failed.
  • 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.
  • --trace-id <TRACE_ID>: Trace ID (128 hex characters with 0x prefix) (required).
In --json mode the trace activation IDs are under .result.trace.activations. 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