> For the complete documentation index, see [llms.txt](https://stair-ai.gitbook.io/stair-ai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stair-ai.gitbook.io/stair-ai-docs/protocol/on-chain.md).

# On-chain infrastructure

Glass Box Protocol uses two on-chain components and one identity primitive. A *data availability layer* stores trace bytes; an *L1 blockchain* stores anchors that point at them; *BYOI* lets agents reuse whatever cryptographic identifier they already have.

| Component               | Role                                                                    | Today's deployment          |
| ----------------------- | ----------------------------------------------------------------------- | --------------------------- |
| Data availability layer | Stores full trace JSON; content-addressed, erasure-coded, immutable     | Walrus (testnet integrated) |
| L1 blockchain           | Stores Merkle root + DA Blob ID per anchor in the Trace Ledger contract | SUI (testnet; mainnet next) |
| Identity (BYOI)         | Any cryptographic identifier — EVM address, Solana keypair, W3C DID     | —                           |

{% hint style="info" %}
**Data availability layer.** Storage infrastructure that holds the full record bytes and guarantees they can be retrieved later by anyone, without depending on a single server. Content-addressed: any change to the bytes produces a different ID. Today's deployment uses Walrus.
{% endhint %}

{% hint style="info" %}
**L1 blockchain.** The settlement-layer blockchain that anchors records. Each Merkle root is committed as a small transaction, where it cannot be altered without detection. Today's deployment uses SUI.
{% endhint %}

{% hint style="info" %}
**BYOI (Bring Your Own Identity).** Letting partners use any cryptographic identifier they already have rather than issuing a new one specific to the protocol.
{% endhint %}

The architecture is platform-agnostic. The v2 multi-chain adapter targets additional L1s and DA layers (Celestia, EigenDA, Ethereum L2s, Solana).

## Data flow

Records are persisted by the Trace Service first; chain anchoring runs as a separate v2 pipeline that reads from the same store.

```mermaid
graph LR
  Agent --> SDK
  SDK -->|HTTPS| TS[Trace Service]
  TS --> Store[(Persistent Store)]
  Store --> AP[Anchoring Pipeline v2]
  AP -->|blob upload| DA[DA layer]
  AP -->|anchor tx| L1[L1 blockchain]
  DA -.Blob ID.-> L1
```

The pipeline reads completed sessions, computes the *Merkle root*, uploads the bundle to the DA layer to obtain a Blob ID, and submits a single L1 transaction recording (Merkle root, Blob ID, signing wallet, server timestamps). Record submission stays synchronous and never blocks on chain availability.

{% hint style="info" %}
**Merkle root.** A single cryptographic hash that summarizes a set of records. Any change to any record produces a different root, so the root acts as a tamper-detection fingerprint for the whole set.
{% endhint %}

## Trace Ledger contract surface

The Trace Ledger is a smart contract on the L1 blockchain. It holds one anchor entry per session, keyed by `(agent_id, session_id)`:

| Field                   | Type       | Source                             |
| ----------------------- | ---------- | ---------------------------------- |
| `agent_id`              | UUID       | Trace Service                      |
| `session_id`            | string     | Agent-supplied                     |
| `merkle_root`           | hash       | Computed over session records      |
| `walrus_blob_id`        | bytes      | Returned by the DA layer on upload |
| `anchor_author_address` | L1 address | Per-agent or owner-default wallet  |
| `anchored_at_utc`       | epoch ms   | L1 block timestamp                 |

A session is anchored when its terminal `Acting` record has been persisted.

Records that arrive after a session is anchored are flagged `post_anchor: true` and excluded from that session's tree; they would form their own anchor on a subsequent eligible event. `Reflecting` records anchor as a separate, linked commitment after the original anchor.

## Wallets

Each owner has two tiers of wallet, chosen at owner registration:

| Mode                    | Owner default wallet | Per-agent wallet                     | Signing                                    | Gas      |
| ----------------------- | -------------------- | ------------------------------------ | ------------------------------------------ | -------- |
| **Custodial** (default) | Stair AI generates   | Stair AI generates per agent         | Stair AI KMS                               | Stair AI |
| **BYOW**                | Owner supplies       | Owner supplies (or inherits default) | Partner via SDK callback; Stair AI submits | Partner  |

The mode is locked at owner registration and applies to every agent under that owner. In v1 anchoring, the per-agent wallet signs anchors for that agent's sessions; the owner default is the fallback when an agent has no wallet of its own. The `anchor_author_address` field on each anchor reflects which wallet actually signed.

## v1 vs v2

| Capability            | v1 (today)                    | v2                                                                         |
| --------------------- | ----------------------------- | -------------------------------------------------------------------------- |
| Record submission     | Synchronous to Trace Service  | Unchanged                                                                  |
| Persistence           | Server-side append-only store | Unchanged                                                                  |
| Hash chain on records | In-store                      | Unchanged                                                                  |
| DA layer upload       | None                          | Asynchronous, per session                                                  |
| L1 anchor commit      | None                          | Asynchronous, per session                                                  |
| Chain-reader SDK      | None                          | Separate component for partners verifying anchor state directly from chain |

Records are durable in v1 without chain interaction. Anchoring upgrades the trust model from "Stair AI's store" to "publicly verifiable" without changing the record format.