> 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/roadmap/sdk-v2.md).

# SDK v2

SDK v2 is three things at once.

| Component                      | What it adds                                                                                                                                                               |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chain anchoring**            | Asynchronous pipeline that reads the v1 persistent store, computes Merkle roots, uploads to a data availability layer, and submits anchor transactions to an L1 blockchain |
| **Chain-reader SDK component** | Lets partners verify anchor state directly from chain without trusting the Trace Service                                                                                   |
| **Language ports**             | Python at v1 alongside TypeScript; Go at v2                                                                                                                                |
| **Agent-skill distribution**   | Reasoning Ledger as a dev-time and runtime skill                                                                                                                           |

## v1 → v2 migration

```mermaid
graph LR
  V1A["v1: Agent → SDK → Trace Service → Persistent Store"]
  V1A --> V1B["Records durable, no chain interaction"]
  V1B --> V2["v2 adds: separate anchoring pipeline reads store"]
  V2 --> V2A["Anchoring → DA layer → L1"]
  V2 --> V2B["Chain-reader SDK reads from chain directly"]
```

Record submission stays synchronous and unchanged. Anchoring runs as a separate backend process. From the partner's perspective:

| What changes          | How                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------- |
| Record submission API | Unchanged                                                                           |
| Record schema         | Unchanged                                                                           |
| Wallet provisioning   | Already collected in v1; v2 begins using the wallet to sign anchor transactions     |
| BYOW signer callback  | Already defined in v1 SDK API; v2 begins invoking it when anchors are ready to sign |
| Verification          | New chain-reader SDK component; existing Trace Service reads remain available       |

**Anchoring trigger.** A session is anchored when its terminal `Acting` record has been persisted. `Reflecting` records anchor as a separate, linked commitment after the original anchor. Records arriving after a session is anchored are stored with `post_anchor: true` and excluded from that session's tree.

## Chain-reader SDK component

A separate package (`@stairai/chain-reader-sdk`) for partners verifying anchor state directly from chain.

```typescript
import { ChainReader } from "@stairai/chain-reader-sdk";

const reader = new ChainReader({ network: "sui_mainnet" });

// Fetch the on-chain anchor for a session
const anchor = await reader.getAnchor({ agent_id, session_id });
// {
//   merkle_root,
//   walrus_blob_id,
//   anchor_author_address,
//   anchored_at_utc,
//   sui_tx_id,
// }

// Fetch the bundle from the DA layer
const bundle = await reader.fetchBundle(anchor.walrus_blob_id);

// Verify locally
const ok = reader.verifyMerkle(bundle, anchor.merkle_root);
```

Three things travel together: the anchor (proves the bundle existed at a public timestamp), the bundle (the trace bytes themselves), and the proof (any verifier can recompute). None require Stair AI to be online.

## Language ports

| SDK        | Status                    |
| ---------- | ------------------------- |
| TypeScript | v1 (now)                  |
| Python     | v1 (alongside TypeScript) |
| Go         | v2                        |

All three are generated from the canonical JSON Schema (Draft 2020-12) at `schemas/records.schema.json`. Adding a new behavior or field is a JSON Schema edit followed by regeneration; no parallel hand-edits across language bindings.

The Go SDK targets performance-critical infrastructure (relayers, indexers, enclave-resident agents) where TypeScript and Python overhead is unacceptable.

## Agent-skill distribution

The Reasoning Ledger as an agent skill in two senses:

| Mode               | What it means                                                                                                                                                                                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dev-time skill** | Integration into Claude Code, Codex, Cursor, similar IDEs. The skill surfaces correct schemas and call patterns into generated agent code so partners do not have to read the API reference.                                                                                                   |
| **Runtime skill**  | Consumed by an LLM-driven agent so reasoning records are emitted at the right phases of execution (Observing on trigger arrival, Thinking on inference, Acting on commit). The skill drives the SDK from the agent's reasoning loop, rather than the partner manually instrumenting each call. |

Same SDK underneath; the skill is a wrapper that automates the call-site decisions partners would otherwise make manually.

## Other v2 changes

| Capability                                | Notes                                                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Multi-chain adapter**                   | Celestia, EigenDA, Ethereum L2s, Solana — chain-agnostic anchor backend                                                  |
| **Blind Sequencer**                       | Independent timestamping service that defends against post-hoc trace fabrication                                         |
| **Use-case-specific frameworks**          | Opinionated wrappers for trading, research, coding, and operations agents — pre-wired Observing/Thinking/Acting patterns |
| **Scoring integration**                   | Stair AI Score consumption surface in the SDK; score retrieval, threshold subscription, score-aware client-side logging  |
| **Field-level encryption**                | For sensitive payloads (`output_payload`, `tool_meta` regions); partner-held keys                                        |
| **Schema versioning + migration tooling** | Declared schema versions, server-side multi-version acceptance, partner migration helpers                                |