> For the complete documentation index, see [llms.txt](https://docs.brain.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.brain.fi/build/audit-every-action.md).
# Audit Every Action
Goal: pull a complete, tamper-evident record of every meaningful event for a tenant. Useful for compliance review, customer disputes, internal reporting, and proving to auditors that the right thing happened.
### Reading the Trail
```typescript
const events = await brain.audit.list("acme", {
from: "2025-09-01",
to: "2025-09-30",
type: "action.executed", // optional filter
});
events.data.forEach((e) => {
console.log(e.timestamp, e.type, e.actor, e.summary);
});
```
| Type | When |
| --------------------- | ------------------------------------- |
| `source.connected` | A source connected for the tenant |
| `transaction.created` | A new transaction landed |
| `wiki.query` | A natural-language question was asked |
| `policy.evaluated` | A policy decision was rendered |
| `action.proposed` | An agent proposed an action |
| `action.approved` | A human signed approval |
| `action.executed` | An action settled on its rail |
| `audit.anchored` | A Merkle root was anchored on Base |
### Verifying a Specific Action
For any action, you can pull a Merkle proof verifiable on-chain.
```typescript
const proof = await brain.proof(actionId);
proof.event; // the event itself
proof.merklePath; // sibling hashes from leaf to root
proof.anchorRoot; // the Merkle root anchored on Base
proof.anchorTx; // the transaction that anchored it
proof.anchorBlock; // the Base block number
```
You can hand this to a counterparty or auditor. They can verify it without trusting Brain.
```solidity
// Public verifier on Base
bool valid = brainAuditAnchor.verify(
tenantIdHash,
batchIndex,
eventLeaf,
merklePath
);
```
### Pulling the Trace for One Action
Trace IDs link every event tied to one action.
```typescript
const trace = await brain.trace(actionId);
console.log(trace.events);
// [
// { type: "action.proposed", timestamp: "..." },
// { type: "policy.evaluated", decision: "needs_approval" },
// { type: "action.approved", actor: "user_cfo" },
// { type: "action.executed", rail: "ach", txHash: null },
// { type: "action.settled", receipt: "..." },
// { type: "audit.anchored", batchIndex: 4127 }
// ]
```
You can paste a trace ID into the Console to see the same view rendered visually.
### Exporting for Compliance Review
For SOC 2, ISO 27001, or any structured review, export the log as a file.
```typescript
const job = await brain.audit.export("acme", {
format: "ndjson", // or "csv"
from: "2025-01-01",
to: "2025-12-31",
});
console.log(job.jobId); // track this export job
```
The export contains every event in the range plus the Merkle proofs needed to verify any of them after the fact.
### Streaming Events Live
Use webhooks to receive audit events as they happen, then ship them to your SIEM, Datadog, Splunk, or wherever you centralize logs.
### Filtering by Actor
Useful for "what did agent X do today?"
```typescript
const today = await brain.audit.list("acme", {
actor: "agent:payments-v1",
from: new Date(Date.now() - 86400_000).toISOString(),
});
```
Or "what did user Y do?"
```typescript
const trail = await brain.audit.list("acme", {
actor: "user:user_cfo",
from: "2025-01-01",
});
```
### What You Don't Have to Worry About
| Concern | Why Brain handles it |
| --------------------- | --------------------------------------------------------------------------- |
| **Tamper resistance** | Every event is hashed and chained; Merkle roots anchor on Base hourly |
| **Per-event signing** | Anchorer keys live in HSMs; rotation is governed |
| **Reorg safety** | Reads wait for finality; cross-batch references catch dropped anchors |
| **Privacy** | Only Merkle roots and hashed tenant IDs are on-chain; no payload data leaks |
### What's Next
🔌 External Agent
Authorize an MCP-compatible agent and audit its actions the same way.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.brain.fi/build/audit-every-action.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.