# On-Chain Ledger

Every TherosAI transaction is inscribed on Solana Mainnet. This is not an optional feature — it is a fundamental property of the architecture.

The on-chain ledger means:

* **Immutability.** Once confirmed, a transaction record cannot be altered by TherosAI, by you, or by anyone else. The chain does not forget.
* **Public verifiability.** Any transaction can be inspected independently using Solana block explorers — no trust in TherosAI's reporting is required.
* **Cryptographic proof.** Transaction signatures are cryptographic — operators can prove to auditors, regulators, or counterparties exactly what their agents spent, when, and with whom.
* **Permissionless access.** Any party with a transaction signature can verify it on-chain. TherosAI cannot selectively hide or modify records.

***

## What is inscribed on-chain

Each transaction instruction emitted by the TherosAI on-chain program includes:

| Field                    | Description                                                |
| ------------------------ | ---------------------------------------------------------- |
| `wallet_id`              | The TherosAI vault identifier (derived from the PDA seeds) |
| `policy_id`              | The policy that governed this transaction                  |
| `recipient`              | The destination Solana address                             |
| `amount`                 | USDC amount in lamports                                    |
| `timestamp`              | Unix timestamp at slot confirmation                        |
| `agent_attestation_hash` | SHA-256 hash of the agent-signed request payload           |
| `tx_signature`           | The Solana transaction signature                           |

Human-readable memos (e.g. `"Perplexity query batch #8821"`) are stored off-chain in TherosAI's indexed database and linked to the on-chain `tx_signature`. Memos are surfaced in the dashboard and API but are not part of the immutable on-chain record.

***

## Viewing transactions on-chain

Every transaction in the TherosAI dashboard includes direct links to:

* **Solscan** — `https://solscan.io/tx/{signature}`
* **SolanaFM** — `https://solana.fm/tx/{signature}`

These links open the raw on-chain record independently of TherosAI's systems.

***

## Indexing via Helius

Raw Solana RPC provides eventual consistency and is not suitable for real-time dashboards or webhooks. TherosAI uses **Helius** as its indexing layer:

* Helius monitors TherosAI program accounts and delivers webhooks on every state change in under 100ms.
* The TherosAI API serves transaction history from the Helius-indexed database, not from direct RPC calls — this provides fast, consistent query performance at any scale.
* Balance subscriptions are maintained via Helius's WebSocket API, powering live balance updates in the dashboard.

***

## Transaction finality on Solana

Solana uses a single-slot confirmation model. A transaction reaches **finality** in approximately 400ms — one Solana slot. TherosAI marks a transaction as `confirmed` at single-slot confirmation. Reorgs on Solana are extremely rare and architecturally constrained by the protocol.

TherosAI does not wait for additional confirmations beyond single-slot for standard transactions. For A2A escrow releases, two-slot confirmation is required before funds are released to the receiving agent.

***

## Querying transaction history

```typescript
// All transactions for a vault
const txs = await client.wallets.transactions.list("wal_9f3a2b", {
  limit: 50,
  cursor: "cursor_abc123",
});

// Filter by date range
const txs = await client.wallets.transactions.list("wal_9f3a2b", {
  from: "2026-04-01T00:00:00Z",
  to: "2026-04-30T23:59:59Z",
});

// All transactions across the organisation
const txs = await client.transactions.list({
  limit: 100,
  status: "confirmed",
});
```

→ See [Transactions API](/api-reference/transactions.md) for full query options.

***

## Audit exports

Transaction history can be exported from the dashboard as CSV or JSON:

**Dashboard → Transactions → Export**

Exports include all indexed fields plus the Solscan URL for each transaction. For compliance or audit purposes, the on-chain record is the primary source of truth — the export is a convenience view of that record.

***

## Data retention

TherosAI's indexed transaction database retains all records indefinitely. Because the on-chain record is immutable and public, there is no scenario in which historical transaction data is lost or modified.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.therosai.com/core-concepts/on-chain-ledger.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.