> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genlabs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> A trace is the full spawn-tree of activations produced by one externally submitted activation, identified by a trace ID and queryable as a single unit.

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](/user-guide/concepts/activations) and [Activation structure](/user-guide/concepts/activation-structure). For why activations spawn follow-up work, see [continuations](/user-guide/concepts/activations#operations).

## 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 how a single activation can trigger follow-up work on other entities, including entities that live on other [shards](/user-guide/concepts/shards-and-clusters).

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) 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, components, 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 `ActivationId`s: 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](/user-guide/concepts/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:

```bash theme={null}
gen client get-trace --trace-id 0x<128 hex chars>
```

From JSON-RPC:

```bash theme={null}
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 `ActivationId`s; 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

|                 | Activation                                                | Trace                                                                        |
| --------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Scope           | One signed input, one target entity, one shard, one block | Root activation plus every continuation it spawned, across-shards and blocks |
| Identifier      | `ActivationId`                                            | `TraceId` (equals the root's `ActivationId`)                                 |
| Lookup          | `gen_getActivation`                                       | `gen_getTrace` (returns activation IDs); then `gen_getActivation` per step   |
| Receipt content | Status, result, events, child continuation IDs            | The set of activation IDs sharing the trace                                  |
| When to use     | You need the result of one step                           | You need the full graph of cross-entity work                                 |

## Related

* [Activations](/user-guide/concepts/activations): the unit of work that roots a trace.
* [Activation structure](/user-guide/concepts/activation-structure): the signed shape of every activation in the trace.
* [Shards and clusters](/user-guide/concepts/shards-and-clusters): why a trace can cross-shard boundaries.
* [Finality](/user-guide/concepts/finality): when activations in a trace are settled.
* [CLI: `get-trace`](/reference/cli/activations#get-trace): the command-line surface.
* [JSON-RPC: `gen_getTrace`](/reference/rpc/overview): the RPC surface.