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

# On-Chain Verification

> How Mnemom anchors reputation Merkle roots and score batches to Base L2, what that buys you, and its honest scope limits.

## Why on-chain?

The Mnemom Trust Rating is computed and stored on Mnemom's own infrastructure. The scoring methodology is transparent and the underlying [checkpoints are cryptographically verifiable via Merkle proofs](/concepts/reputation-scores#cryptographic-verification), but the canonical data still lives on Mnemom's servers. On-chain anchoring adds an external, append-only checkpoint of that data on a public blockchain:

* **Tamper-evident** -- once a Merkle root or a batch of scores is anchored, a later mismatch between what Mnemom serves and what was anchored is detectable.
* **Independent of Mnemom's uptime** -- an anchored root or score record persists on-chain even if Mnemom's API is unavailable.

On-chain anchoring does not replace the off-chain scoring system. It periodically commits a snapshot of it to an external, immutable ledger.

***

## What gets anchored

Mnemom runs two related on-chain operations, both on **Base** (Coinbase's Ethereum L2), on the same **6-hour cron** that recomputes reputation scores:

1. **Merkle root anchoring.** Each agent's integrity checkpoints form a per-agent Merkle tree; the per-agent roots are aggregated into one global root, which is anchored on-chain.
2. **Score batch publishing.** Each cycle publishes the `(agent_id, score, grade)` of every eligible agent whose score or grade changed since its last confirmed publication, plus agents never published before, in batches (currently up to 100 entries per transaction, chunked as needed). An agent whose score and grade are unchanged keeps its previously published value on-chain. The commitment for each entry binds the agent id, score and grade. The commitment format also has a slot for a hash of the alignment card version the score was computed against, but that slot is not populated today, so a card change on its own does not change the on-chain commitment.

Both operations write to Base using `viem`, targeting either `base` (mainnet) or `base-sepolia` (testnet) depending on the environment -- the same two values the API reports in the `chain` field of on-chain responses.

<Note>
  Anchoring and publishing are **fail-open and opt-in per environment**: a failure never blocks the reputation-scoring cron, and an environment must explicitly enable anchoring and configure its contract addresses before any transaction is attempted. Anchoring is not something a customer triggers -- see the [On-Chain guide](/guides/on-chain-verification) for the three read-only endpoints customers actually call.
</Note>

<Warning>
  **Honest scope limit.** This publishes a periodic snapshot of *current state* (the latest `reputation_scores` row per agent), not an ordered log of every score-changing event. It cannot, by itself, reveal a value that was published and then reverted between two 6-hour cycles -- that is a stronger guarantee (an ordered, append-only event log) that this snapshot mechanism does not provide today.
</Warning>

***

## Verifying against the anchor

The customer-facing verification endpoint, `GET /v1/on-chain/verify-proof/{agent_id}`, does the following:

1. Recomputes the agent's Merkle root from its **stored leaf hashes** (not from the stored root alone) and checks the stored leaf count against the actual number of leaves -- catching silent truncation or a root that doesn't match its own leaves.
2. If a `leaf_index` is supplied, generates and verifies a real inclusion proof for that leaf against the recomputed root, and returns it so the caller can independently replay the check.
3. Looks up the confirming anchor by the **recomputed** root -- so an anchor row can never vouch for a root nobody can rebuild from the stored data.

`verified: true` requires every one of those steps to succeed, including a confirmed anchor existing for the recomputed root; any failure returns `verified: false` with a machine-readable `reason` (see the [API reference](/api-reference/on-chain-overview) for the full list).

<Warning>
  **Scope limit, stated rather than hidden:** the anchored root that step 3 checks against is read from **Mnemom's own anchor record**, not from a live Base RPC call. A `verified: true` result means "this tree is internally consistent and matches the root Mnemom recorded as anchored" -- it does not, on its own, prove that Mnemom's record of what was anchored agrees with the chain. The response's `verification.anchored_root_source` field reports this (`mnemom_database`) so the limitation is visible in the payload, not just in prose.
</Warning>

### Private agents

The three on-chain read endpoints follow the same privacy rule as the reputation API. For an agent whose reputation visibility is `private`, `GET /v1/on-chain/status/{agent_id}`, `GET /v1/on-chain/verify-proof/{agent_id}` and `GET /v1/on-chain/history?agent_id=…` return `403` with code `reputation_private` unless the caller is authenticated as a member of the agent's organization. Public, unlisted and unscored agents stay readable without authentication. If the visibility check itself fails, the request fails closed with `500` instead of serving the data.

A customer wanting a fully trust-minimized check today can take the `tx_hash`, `block_number`, and `chain` the API returns for a confirmed anchor and inspect that transaction directly on a Base block explorer -- the transaction itself is public. Reading the registry contract's state directly is not yet part of the documented customer surface.

***

## See also

* [On-Chain Verification Guide](/guides/on-chain-verification) -- the three read endpoints, with request/response examples
* [On-Chain API Reference](/api-reference/on-chain-overview) -- full endpoint reference
* [Mnemom Trust Rating](/concepts/reputation-scores) -- how reputation scores are computed
* [Cryptographic Verification](/concepts/reputation-scores#cryptographic-verification) -- the off-chain proof chain (certificate hash, Merkle root, hash chain) this anchoring builds on
* [Integrity Checkpoints](/concepts/integrity-checkpoints) -- the data source for the Merkle trees


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.