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

# Cryptographic Audit Ledger: Tamper-Proof Agent Records

> How Tavryn's append-only SHA-256 hash chain makes every agent action permanently verifiable and tamper-evident — verify the chain yourself at /audit.

Every action Tavryn takes — every negotiation round, every policy evaluation, every escrow operation, every supervisor override — is written to a cryptographically linked audit ledger that you can verify independently at any time. The design borrows the core insight from blockchain technology: each new record includes a hash of the previous record, so any attempt to alter historical data breaks the chain at the point of tampering and makes the breach immediately visible. Unlike a blockchain, this ledger lives in your database — verifiable, queryable, and completely under your control.

## How the hash chain works

Each entry in the audit ledger is an **action block**. When a new block is inserted, the application computes a SHA-256 hash over the previous block's content and embeds it in the new block as `previous_hash`. This creates a sequential chain where every block is cryptographically bound to every block before it.

```text theme={null}
Block N−1: { id, action, data, hash: SHA256(block N−1 content) }
                                          ↓
Block N:   { id, action, data, previous_hash: hash of block N−1, hash: SHA256(block N content) }
                                          ↓
Block N+1: { id, action, data, previous_hash: hash of block N, hash: SHA256(block N+1 content) }
```

To verify the chain, the `/audit` page recomputes each block's expected hash from scratch and checks it against the stored value. If any block's computed hash doesn't match its stored hash — or if any block's `previous_hash` doesn't match the preceding block's hash — the chain is broken and the dashboard immediately flags the compromised block index and ID.

## Database-level immutability

The hash chain alone isn't sufficient — an attacker with database write access could recompute the hashes after altering data. Tavryn adds a second layer of protection: Tavryn maintains an **append-only audit record** enforced by a database-level constraint that fires on any attempt to update or delete audit entries, aborting the operation immediately.

This protection operates at the database engine level, below the application layer. Even if your application server were fully compromised, a direct database connection cannot silently alter or remove audit records — the mutation attempt is blocked and leaves a visible error in the database logs.

> [!WARNING]
>
> The immutability guarantee applies to audit ledger entries only. Other records (negotiations, transactions, contracts) represent mutable operational state. If you require immutable evidence for a specific transaction, confirm it exists in the Audit Ledger under the linked negotiation ID before relying on it for compliance purposes.

## What gets recorded

Tavryn writes an action block at every meaningful decision point. The following events generate audit entries:

| Event type | What's captured |
| - | - |
| Waste detection | Contract ID, seat counts, usage decline metrics, calculated savings |
| Switching matrix evaluation | NPV comparisons, competitor quotes, recommendation |
| Negotiation round | Round number, offer price, vendor response, walk-away ceiling |
| Reviewer audit | Reviewer verdict (AGREE/CHALLENGE/REJECT), concerns list, reasoning |
| Policy check | All 7 check results, final decision, reasons |
| Escrow creation | Agreement ID, amount, fee, idempotency key, ArcScan link |
| Milestone approval | 4-field document match result, verification engine output |
| Payment release | On-chain transaction hash, vendor address, amounts |
| Supervisor override | Override reason code, supervisor ID, injected feedback text |

Each block also records a `confidence` score (0.0–1.0), the agent model identifier, and a full `input`/`result` JSON payload so you can reconstruct the agent's reasoning for any decision.

## Simulated vs. confirmed transactions

Tavryn operates transparently about its execution mode. When Circle and Arc credentials are fully configured, escrow transactions execute on-chain and generate real transaction hashes. When running in mock or demo mode without live credentials, the system records `is_simulated = true` on the transaction row.

In the Audit Ledger:

* **Simulated transactions** display a **"Simulated (testnet mock)"** badge in amber. The ArcScan link column is empty — there is no on-chain transaction to link to, and Tavryn never fabricates a hash.
* **Confirmed on-chain transactions** display a working **ArcScan link** that resolves to the live transaction on `testnet.arcscan.app`. You can independently verify the amount, recipient, and block timestamp without trusting Tavryn's records.

> [!NOTE]
>
> There are zero 404 links in the Audit Ledger. ArcScan links appear only for transactions that have a confirmed on-chain hash. Tavryn will never render a link to a transaction that doesn't exist.

## Verifying the chain yourself

Navigate to **/audit** in your Tavryn dashboard. The page performs a full server-side chain verification on every page load — no cached results — and displays one of two states:

> [card] Chain: 100% Verified
>
> All action blocks are sequentially linked with valid SHA-256 hashes. The total block count is displayed alongside the verification algorithm. Your audit history is intact.

> [card] Chain: Compromised
>
> A hash mismatch was detected. The dashboard surfaces the exact block ID and sequential index where the chain breaks, giving you a precise forensic starting point for investigation.

The interactive table below the status banner lets you expand any individual block to inspect its full payload, hash, and `previous_hash`. You can copy any hash value to manually verify it with `echo -n "<block content>" | sha256sum` or equivalent tooling.

> [!TIP]
>
> For compliance workflows, you can export the full audit ledger from your Tavryn dashboard as a JSON or CSV file. The exported data contains all hash values, so you can run an independent chain verification offline without accessing the Tavryn application at all.


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