Skip to main content
A trace is the complete spawn-tree of work produced by one externally submitted activation: the original activation plus every continuation it spawned, transitively, across every entity, shard, and block those continuations touched. You submit one signed activation. Its operations may emit continuations against other entities; each of those may emit more. The trace is the closure of that tree, identified by a single TraceId and queryable as one object. For the per-activation shape, see Activations and Activation structure. For why activations spawn follow-up work, see continuations.

​
Why traces exist

An activation only ever touches one entity directly. Anything cross-entity (paying another account, calling a contract on a different entity, fanning out to several recipients) happens through continuations: protocol-generated follow-up activations that run on a different target. Continuations are also how a single submission moves across shards, since each entity lives on exactly one shard at a time. This means the visible effect of “one submission” is rarely one activation. A typical real flow looks like:
  • Sync, within one activation. Operations inside an activation run in order against components on the target entity. Component-to-component calls on the same entity are synchronous and share the activation’s atomic outcome: revert one, revert all.
  • Async, across entities. Anything that needs to act on a different entity emits a continuation. Continuations are independent activations from the protocol’s perspective: each has its own ActivationId, its own admission, its own per-step status, and may execute in a later block and on a different shard than its parent.
The trace is how Grid exposes that whole tree (root + every continuation, sync and async) as a single addressable unit. Concretely, you reach for a trace to answer:
  • Did this submission do everything I expected, end to end, across every entity it touched?
  • Which entities, shards, and blocks were involved, and in what order?
  • For a multi-step flow that failed: which step reverted, and which earlier steps already settled?
  • For audit and reconciliation: what is the full record of work attributable to one signed input?

​
Trace ID

Every activation belongs to exactly one trace. The trace is identified by a TraceId, which is the ActivationId of the root activation: the externally submitted activation that started the tree. Every continuation the protocol spawns inherits its parent’s trace ID, so the entire spawn-tree shares one value. TraceId is a 64-byte value (the same shape as ActivationId: a 32-byte hash plus a 32-byte resolved target). CLI and RPC render it as a 128-character hex string with a 0x prefix. For a root activation, ActivationId == TraceId. For any continuation, the ActivationId is its own, but its trace pointer is the root’s ActivationId.

​
What a trace contains

The on-chain trace is a set of activations sharing a trace_id. The gen_getTrace RPC and gen client get-trace CLI return a flat list of ActivationIds: the root plus every continuation in the tree. To get per-step detail (status, result bytes, events, continuation pointers to children), look up each ID with gen_getActivation or gen client get-activation. The activation receipt is where the substantive data lives; the trace tells you which receipts belong together. Derived views (call graph, ordered activation flow, aggregated balance changes across the whole trace) are produced client-side by walking the activation list and inspecting each receipt. The block explorer renders these as the Trace Graph and Activation Flow views; SDKs can synthesize the same shape over the RPC surface. A trace inherits the finality properties of its activations: each activation in the trace is independently finalized, and once finalized, stays final. There is no separate “trace finalization” event.

​
Traces span shards and blocks

A trace is not bound to one shard or one block:
  • Shards. The root activation executes on the shard hosting its target entity. When it emits a continuation against an entity on a different shard, the continuation is routed there and executed locally. A single trace can fan across many shards.
  • Blocks. Continuations execute in subsequent blocks relative to their parent, not in the parent’s block. A trace’s first block is the root’s block; its last block is whenever the deepest continuation finalizes. Block explorers that render traces typically display the full block range, not a single block number.
This is why “the result of my submission” is a trace-shaped question, not an activation-shaped one.

​
Fetching a trace

From the CLI: 
gen client get-trace --trace-id 0x<128 hex chars>
From JSON-RPC: 
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getTrace", "params": {"trace_id": "0x..."}}'
The Rust SDK exposes the same call as get_trace(...). The result is a list of ActivationIds; pair it with get-activation to assemble per-step detail. The typical post-submission pattern:
  1. Submit the activation. The ActivationId you get back is also the TraceId for the trace it roots.
  2. Poll get-activation until status is success or failed.
  3. If the activation produced continuations (its receipt’s continuations field is non-empty), call get-trace with the TraceId to enumerate the full tree, then get-activation on each ID for receipts.
For single-activation flows that emit no continuations, the trace is a one-element list and adds nothing beyond the activation receipt. Reach for traces when something fanned out.

​
Activations vs. traces

ActivationTrace
ScopeOne signed input, one target entity, one shard, one blockRoot activation plus every continuation it spawned, across-shards and blocks
IdentifierActivationIdTraceId (equals the root’s ActivationId)
Lookupgen_getActivationgen_getTrace (returns activation IDs); then gen_getActivation per step
Receipt contentStatus, result, events, child continuation IDsThe set of activation IDs sharing the trace
When to useYou need the result of one stepYou need the full graph of cross-entity work