@agentauditai/mcp-server 0.0.0-stage → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog — @agentauditai/mcp-server
+
+All notable changes to this package. Versions follow [SemVer](https://semver.org/).
+
+## 3.0.0 — 2026-11-08
+
+AgentAudit provides evidence, not certification. This release removes every tool
+output that read as a compliance verdict.
+
+### Breaking
+- **`check_conformity` removed.** The server no longer reads ConformityAssessment.
+  The deployed contract is unchanged; read it directly if you need the record.
+- **Evidence report output changed.** The ConformityAssessment section is gone and
+  the report lists on-chain records with a disclaimer instead of a verdict.
+- **`report_incident` no longer prints a reporting deadline.** Deadlines depend on
+  the type of incident; confirm them with your legal team. The tool states that it
+  creates an on-chain record, not a report to an authority.
+
+### Added
+- `get_evidence_report`. `get_compliance_report` stays as a deprecated alias and
+  will be removed in a future major version.
+- **Base Builder Code attribution (ERC-8021), on by default** for `audit_action`
+  and `report_incident`, on Base (8453) and Base Sepolia (84532) only. Appends a
+  29-byte suffix for `bc_pd681w25`; evidence bytes are unchanged, only the tx hash
+  differs. Turn it off with `AGENTAUDIT_BUILDER_CODE=false` (also `off`, `0`), or
+  set your own code. An invalid value stops the server at startup.
+- "Not legal advice." in evidence and incident tool descriptions and output.
+
+### Changed
+- MCP handshake version `3.0.0`.
+- `CHANGELOG.md` now ships in the package.
+
+## 2.0.0 — 2026-10-30
+
+First npm release: `audit_action` (AuditVault v2 `commitBatch` on Base),
+`get_audit_log`, `verify_proof`, `report_incident` (IncidentRegistry v2, 5
+networks), `get_compliance_report`, `get_risk_score`, `check_conformity`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentauditAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @agentauditai/mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP (Model Context Protocol) server for [AgentAudit](https://github.com/agentauditAI/AgentAudit): on-chain audit logging and incident records for AI agents, providing evidence that supports EU AI Act record-keeping. It does not determine whether any legal obligation is satisfied. Works with Claude, Cursor and any MCP client over stdio.
+
+| What | Where it is live |
+|---|---|
+| Audit logging: `audit_action`, `get_audit_log`, `verify_proof` (AuditVault v2, Art. 12, 19) | **Base only**: AuditVault v2 `0xCeE831070aa9081422f30df5559c125aa47A75DB` |
+| Incident records: `report_incident` (IncidentRegistry v2, related to Art. 73) | **5 networks**: mantle, base, arbitrum, optimism, polygon |
+| Evidence reads: `get_evidence_report`, `get_risk_score` (related to Art. 9, 73) | mantle, base, arbitrum, optimism, polygon |
+
+## Install and run
+
+```bash
+npx -y @agentauditai/mcp-server        # starts the stdio server (bin: agentaudit-mcp)
+```
+
+The package is compiled JavaScript and needs Node.js 18 or newer; it does not use ts-node at runtime.
+
+Example MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "agentaudit": {
+      "command": "npx",
+      "args": ["-y", "@agentauditai/mcp-server"],
+      "env": { "PRIVATE_KEY": "0x…", "RPC_BASE": "https://…" }
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable | Used by | Notes |
+|---|---|---|
+| `PRIVATE_KEY` | `audit_action`, `report_incident` | Signer for write tools. Not needed for read tools. Never commit it. |
+| `RPC_MANTLE`, `RPC_BASE`, `RPC_ARBITRUM`, `RPC_OPTIMISM`, `RPC_POLYGON` | all tools | Optional RPC overrides; public RPCs are used by default |
+| `AUDIT_VAULT_<NETWORK>` | `audit_action`, `get_audit_log`, `verify_proof` | Points a network at an AuditVault v2 deployment. Without it, every network except Base returns an error. |
+| `AGENTAUDIT_BUILDER_CODE` | `audit_action`, `report_incident` | Base Builder Code attribution, on Base / Base Sepolia only. Unset or empty: AgentAudit's code `bc_pd681w25`. `false`, `off` or `0` (any case): no suffix. Any other value: your own code. See below. |
+
+The server also loads a `.env` file from the working directory (dotenv). Variables already set in the environment take precedence.
+
+## Tools
+
+### `audit_action` (write, Base)
+
+Anchors one or more agent actions in **one** `commitBatch` transaction on AuditVault v2. Each call commits immediately; nothing is buffered between calls, so a restart cannot lose entries.
+
+- Input: `agent_id`, `entries[]` (`action_type`, `payload`, optional `risk_level` default `HIGH`, optional `timestamp_ms`), optional `agent_address` (defaults to the signer), `compliance_score` (0–100), `network` (default `base`).
+- Payloads are SHA-256 hashed (JCS for objects). Raw content never leaves the process. Each entry becomes an Evidence Schema v1 preimage with scope `agent_action:mcp:record_hash:<sha256>`.
+- Returns `txHash`, `batchIndex`, `merkle_root`, each entry's `action_ref` + `proof`, and the full evidence bundle. **Keep the bundle**: the batch payload is not stored anywhere else (`contentURI` is `memory://<root>`).
+- Errors (never a silent skip): the network has no AuditVault v2, the vault has no code, or the transaction emitted no `LogBatchCommitted` for the root.
+
+### `get_audit_log` (read, Base)
+
+Reads committed batches, either by `tx_hash` or by `agent_address` + `batch_index`. Returns the root, contentURI, event count, compliance score, submitter, timestamp and block.
+
+### `verify_proof` (read, Base)
+
+Checks one entry's inclusion proof with AuditVault v2 `verifyLog`. The leaf is always recomputed from the preimage, never taken from the caller (KI-2). Returns `valid`, the batch `submitter` and per-check results. Pass `expected_submitter` to pin the submitter (see the caveat below).
+
+### `report_incident` (write, 5 networks)
+
+Records a serious incident on IncidentRegistry v2 (related to Art. 73). This is an on-chain record, not a report to any authority. Before sending, it checks the registry has code. After mining, it requires an `IncidentRegistered` event from the registry address; otherwise it returns an error and never reports success. It does not calculate reporting deadlines: they depend on the type of incident, so confirm them with your legal team.
+
+### `get_evidence_report`, `get_risk_score` (read)
+
+Read the Phase 7 contracts: RiskManagementSystem (related to Art. 9) and IncidentRegistry (related to Art. 73). If a contract has no code on the selected network, the tool returns an error naming the network and address.
+
+These tools list on-chain records. They do not determine whether any obligation under the EU AI Act or any other law is satisfied.
+
+`get_compliance_report` is a deprecated alias of `get_evidence_report` and will be removed in a future major version.
+
+## Evidence, not certification
+
+AgentAudit provides on-chain evidence. It does not certify AI systems, issue conformity assessments or replace an assessment under the EU AI Act. `check_conformity` was removed for this reason.
+
+## Base Builder Code attribution
+
+On **Base mainnet (8453) and Base Sepolia (84532) only**, the write tools (`audit_action`,
+`report_incident`) append a [Base Builder Code](https://docs.base.org/base-chain/builder-codes/builder-codes)
+suffix (ERC-8021, schema 0) to their transaction calldata. It is on by default with
+AgentAudit's code `bc_pd681w25`, so Base can attribute these transactions to AgentAudit.
+
+- **What is appended:** 29 bytes, `0x62635f70643638317732350b0080218021802180218021802180218021`
+  (`"bc_pd681w25"`, length `0x0b`, schema `0x00`, then the marker `0x8021` × 8).
+- **What stays the same:** the contracts ignore the suffix, so events and state are
+  identical, and no evidence changes (`action_ref`, Merkle root, bundle). Only the tx hash differs.
+- **The code is public** on-chain. The chain is read from the RPC (`eth_chainId`);
+  other chains never get a suffix.
+- **Turn it off:** `AGENTAUDIT_BUILDER_CODE=false`. **Use your own code:**
+  `AGENTAUDIT_BUILDER_CODE=bc_yourcode` (ERC-8021 rules: 7-bit ASCII, no comma, ≤ 255 bytes;
+  an invalid value stops the server at startup).
+
+## Caveat: AuditVault v2 does not authenticate submitters
+
+`commitBatch` on AuditVault v2 has no access control. **Anyone can commit a batch under any agent address.** A batch existing under an agent address therefore does not prove that agent's operator committed it, and batch counts can be inflated by third parties ([THREAT_MODEL KI-1](https://github.com/agentauditAI/AgentAudit/blob/main/docs/THREAT_MODEL.md)).
+
+When you verify, check the batch `submitter`: `get_audit_log` and `verify_proof` both return it, and `verify_proof` takes `expected_submitter` to enforce it. Accept a batch only if the submitter is an address you have authorized for that agent. For full bundles, the `agentaudit-verify` CLI in the repo does the same with `--submitter`.
+
+## License
+
+MIT

package/dist/deployments/phase7-arbitrumOne.json

@@ -0,0 +1,15 @@
+{
+  "network": "arbitrumOne",
+  "chainId": "42161",
+  "deployedAt": "2026-05-18T19:23:02.624Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x6B5BebC2f9172c6E17Df5ea59C1753D360866bDB",
+    "RiskManagementSystem": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "HumanOversightRegistry": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "IncidentRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "ConformityAssessment": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "DataGovernanceRegistry": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "QualityManagementSystem": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210"
+  }
+}

package/dist/deployments/phase7-base.json

@@ -0,0 +1,15 @@
+{
+  "network": "base",
+  "chainId": "8453",
+  "deployedAt": "2026-05-18T19:22:22.838Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x6B5BebC2f9172c6E17Df5ea59C1753D360866bDB",
+    "RiskManagementSystem": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "HumanOversightRegistry": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "IncidentRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "ConformityAssessment": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "DataGovernanceRegistry": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "QualityManagementSystem": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210"
+  }
+}

package/dist/deployments/phase7-mantle.json

@@ -0,0 +1,15 @@
+{
+  "network": "mantle",
+  "chainId": "5000",
+  "deployedAt": "2026-05-18T19:22:09.579Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x6B5BebC2f9172c6E17Df5ea59C1753D360866bDB",
+    "RiskManagementSystem": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "HumanOversightRegistry": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "IncidentRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "ConformityAssessment": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "DataGovernanceRegistry": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "QualityManagementSystem": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210"
+  }
+}

package/dist/deployments/phase7-optimism.json

@@ -0,0 +1,15 @@
+{
+  "network": "optimism",
+  "chainId": "10",
+  "deployedAt": "2026-05-18T19:24:39.428Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "RiskManagementSystem": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "HumanOversightRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "IncidentRegistry": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "ConformityAssessment": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "DataGovernanceRegistry": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210",
+    "QualityManagementSystem": "0xCeE831070aa9081422f30df5559c125aa47A75DB"
+  }
+}

package/dist/deployments/phase7-polygon.json

@@ -0,0 +1,15 @@
+{
+  "network": "polygon",
+  "chainId": "137",
+  "deployedAt": "2026-05-18T19:24:57.683Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x6B5BebC2f9172c6E17Df5ea59C1753D360866bDB",
+    "RiskManagementSystem": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "HumanOversightRegistry": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "IncidentRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "ConformityAssessment": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "DataGovernanceRegistry": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "QualityManagementSystem": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210"
+  }
+}

package/dist/sdk/src/attribution.d.ts

@@ -0,0 +1,42 @@
+import { ethers } from "ethers";
+/** AgentAudit's Base Builder Code, used unless the integrator passes `builderCode`. */
+export declare const AGENTAUDIT_BUILDER_CODE = "bc_pd681w25";
+/** Chains on which the suffix is appended: Base mainnet and Base Sepolia. */
+export declare const BUILDER_CODE_CHAIN_IDS: readonly bigint[];
+/** ERC-8021 marker: 0x8021 repeated 8 times (16 bytes), at the very end of the calldata. */
+export declare const ERC8021_MARKER = "0x80218021802180218021802180218021";
+/**
+ * Checks a code against the ERC-8021 rules: non-empty, 7-bit ASCII, no comma
+ * (0x2C, the delimiter), at most 255 bytes. Returns the code unchanged.
+ */
+export declare function validateBuilderCode(code: string): string;
+/**
+ * ERC-8021 schema-0 data suffix: `codes ‖ codesLength (1 B) ‖ schemaId 0x00 ‖ 0x8021×8`,
+ * where `codes` is the ASCII codes joined by commas.
+ */
+export declare function erc8021DataSuffix(codes: readonly string[]): string;
+/**
+ * Resolves the `builderCode` option: `undefined` → AgentAudit's code,
+ * `false` → no attribution (`null`), a string → that code (validated).
+ */
+export declare function resolveBuilderCode(option: string | false | undefined): string | null;
+/**
+ * Reads AGENTAUDIT_BUILDER_CODE semantics: unset or "" → `undefined` (default, on);
+ * "false" / "off" / "0" (any case) → `false`; anything else → that string, to be
+ * validated by `resolveBuilderCode`.
+ */
+export declare function builderCodeFromEnv(value: string | undefined): string | false | undefined;
+/** The suffix for `chainId`: the code's ERC-8021 suffix on Base / Base Sepolia, else "0x". */
+export declare function attributionSuffix(code: string | null, chainId: bigint): string;
+/**
+ * The chain id the RPC actually reports (`provider.getNetwork()`), cached per
+ * provider. A failed lookup is not cached. The configured network name is never used.
+ */
+export declare function providerChainId(provider: ethers.Provider): Promise<bigint>;
+/**
+ * Sends `contract.method(...args)` like ethers' own contract call, with the
+ * attribution suffix appended to the calldata when it applies. The signer
+ * populates the final transaction, so gas is estimated on the calldata incl.
+ * the suffix. Returns the same `ContractTransactionResponse` ethers would.
+ */
+export declare function sendAttributed(contract: ethers.Contract, method: string, args: readonly unknown[], builderCode: string | null): Promise<ethers.ContractTransactionResponse>;

package/dist/sdk/src/attribution.js

@@ -0,0 +1,133 @@
+"use strict";
+// Base Builder Code attribution (ERC-8021 schema 0) for AgentAudit contract calls.
+//
+// What: a 29-byte suffix appended to the calldata of the SDK's own contract
+// calls, on Base mainnet (8453) and Base Sepolia (84532) only. Contracts ignore
+// trailing calldata; Base indexers read the code from the end of the calldata.
+// The code is public on-chain. No audit evidence changes: action_ref, Merkle
+// root, scope, contentURI and payload hashes are computed before the call is
+// ABI-encoded, and the suffix goes after the encoding (only the tx hash differs).
+//
+// Opt out: `builderCode: false` (SDK) / AGENTAUDIT_BUILDER_CODE=false (MCP).
+// Own code: `builderCode: "<your code>"`. See README "Base Builder Code attribution".
+//
+// The encoding is implemented here (no runtime dependency); test/sdk/attribution.test.ts
+// checks it byte for byte against the ERC-8021 test vector and against `ox/erc8021`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC8021_MARKER = exports.BUILDER_CODE_CHAIN_IDS = exports.AGENTAUDIT_BUILDER_CODE = void 0;
+exports.validateBuilderCode = validateBuilderCode;
+exports.erc8021DataSuffix = erc8021DataSuffix;
+exports.resolveBuilderCode = resolveBuilderCode;
+exports.builderCodeFromEnv = builderCodeFromEnv;
+exports.attributionSuffix = attributionSuffix;
+exports.providerChainId = providerChainId;
+exports.sendAttributed = sendAttributed;
+const ethers_1 = require("ethers");
+/** AgentAudit's Base Builder Code, used unless the integrator passes `builderCode`. */
+exports.AGENTAUDIT_BUILDER_CODE = "bc_pd681w25";
+/** Chains on which the suffix is appended: Base mainnet and Base Sepolia. */
+exports.BUILDER_CODE_CHAIN_IDS = [8453n, 84532n];
+/** ERC-8021 marker: 0x8021 repeated 8 times (16 bytes), at the very end of the calldata. */
+exports.ERC8021_MARKER = "0x80218021802180218021802180218021";
+const SCHEMA_ID_0 = "00";
+const MAX_CODES_LENGTH = 255; // codesLength is a single byte
+/**
+ * Checks a code against the ERC-8021 rules: non-empty, 7-bit ASCII, no comma
+ * (0x2C, the delimiter), at most 255 bytes. Returns the code unchanged.
+ */
+function validateBuilderCode(code) {
+    if (typeof code !== "string" || code.length === 0) {
+        throw new Error("Invalid builder code: must be a non-empty string");
+    }
+    if (!/^[\x00-\x7f]*$/.test(code)) {
+        throw new Error(`Invalid builder code ${JSON.stringify(code)}: ERC-8021 codes are 7-bit ASCII`);
+    }
+    if (code.includes(",")) {
+        throw new Error(`Invalid builder code ${JSON.stringify(code)}: ERC-8021 codes must not contain a comma`);
+    }
+    if (code.length > MAX_CODES_LENGTH) {
+        throw new Error(`Invalid builder code: ${code.length} bytes, ERC-8021 allows at most ${MAX_CODES_LENGTH}`);
+    }
+    return code;
+}
+/**
+ * ERC-8021 schema-0 data suffix: `codes ‖ codesLength (1 B) ‖ schemaId 0x00 ‖ 0x8021×8`,
+ * where `codes` is the ASCII codes joined by commas.
+ */
+function erc8021DataSuffix(codes) {
+    if (codes.length === 0)
+        throw new Error("ERC-8021 suffix needs at least one code");
+    const joined = codes.map(validateBuilderCode).join(",");
+    if (joined.length > MAX_CODES_LENGTH) {
+        throw new Error(`ERC-8021 codes are ${joined.length} bytes with delimiters; at most ${MAX_CODES_LENGTH} allowed`);
+    }
+    const lengthByte = joined.length.toString(16).padStart(2, "0");
+    return ethers_1.ethers.hexlify(ethers_1.ethers.toUtf8Bytes(joined)) + lengthByte + SCHEMA_ID_0 + exports.ERC8021_MARKER.slice(2);
+}
+/**
+ * Resolves the `builderCode` option: `undefined` → AgentAudit's code,
+ * `false` → no attribution (`null`), a string → that code (validated).
+ */
+function resolveBuilderCode(option) {
+    if (option === undefined)
+        return exports.AGENTAUDIT_BUILDER_CODE;
+    if (option === false)
+        return null;
+    if (typeof option !== "string") {
+        throw new Error("builderCode must be a string, false, or omitted");
+    }
+    return validateBuilderCode(option);
+}
+/**
+ * Reads AGENTAUDIT_BUILDER_CODE semantics: unset or "" → `undefined` (default, on);
+ * "false" / "off" / "0" (any case) → `false`; anything else → that string, to be
+ * validated by `resolveBuilderCode`.
+ */
+function builderCodeFromEnv(value) {
+    const v = value?.trim();
+    if (!v)
+        return undefined;
+    if (/^(false|off|0)$/i.test(v))
+        return false;
+    return v;
+}
+/** The suffix for `chainId`: the code's ERC-8021 suffix on Base / Base Sepolia, else "0x". */
+function attributionSuffix(code, chainId) {
+    if (code === null || !exports.BUILDER_CODE_CHAIN_IDS.includes(chainId))
+        return "0x";
+    return erc8021DataSuffix([code]);
+}
+const chainIds = new WeakMap();
+/**
+ * The chain id the RPC actually reports (`provider.getNetwork()`), cached per
+ * provider. A failed lookup is not cached. The configured network name is never used.
+ */
+function providerChainId(provider) {
+    let p = chainIds.get(provider);
+    if (!p) {
+        p = provider.getNetwork().then((n) => n.chainId);
+        p.catch(() => chainIds.delete(provider));
+        chainIds.set(provider, p);
+    }
+    return p;
+}
+/**
+ * Sends `contract.method(...args)` like ethers' own contract call, with the
+ * attribution suffix appended to the calldata when it applies. The signer
+ * populates the final transaction, so gas is estimated on the calldata incl.
+ * the suffix. Returns the same `ContractTransactionResponse` ethers would.
+ */
+async function sendAttributed(contract, method, args, builderCode) {
+    const signer = contract.runner;
+    if (!signer || typeof signer.sendTransaction !== "function" || !signer.provider) {
+        throw new Error("sendAttributed needs a contract connected to a signer with a provider");
+    }
+    const tx = await contract.getFunction(method).populateTransaction(...args);
+    if (builderCode !== null) {
+        const suffix = attributionSuffix(builderCode, await providerChainId(signer.provider));
+        if (suffix !== "0x")
+            tx.data = ethers_1.ethers.concat([tx.data, suffix]);
+    }
+    const sent = await signer.sendTransaction(tx);
+    return new ethers_1.ethers.ContractTransactionResponse(contract.interface, signer.provider, sent);
+}

package/dist/sdk/src/batch.d.ts

@@ -0,0 +1,175 @@
+/**
+ * RFC 8785 JSON Canonicalization Scheme.
+ * Strings and numbers use ECMAScript JSON.stringify serialization (as RFC 8785
+ * specifies); object keys are sorted by UTF-16 code units (Array#sort default).
+ */
+export declare function canonicalize(value: unknown): string;
+/** Lowercase hex SHA-256 of the UTF-8 bytes of `value`, no prefix */
+export declare function sha256Hex(value: string): string;
+export declare const EVIDENCE_SCHEMA = "agentaudit-evidence-v1";
+export interface ActionPreimage {
+    action_type: string;
+    agent_id: string;
+    scope: string;
+    timestamp_ms: number;
+}
+/** action_ref = SHA-256(JCS(preimage)), as 0x-prefixed bytes32 hex */
+export declare function computeActionRef(preimage: ActionPreimage): string;
+/** Percent-encode the characters that would break a scope segment */
+export declare function encodeScopeSegment(segment: string): string;
+/** §2.1 — tool_call:<tool>:result_hash:<sha256> */
+export declare function toolCallScope(tool: string, resultHash: string): string;
+/** §2.2 — data_read:<endpoint>:<dataset_version>:<result_hash> */
+export declare function dataReadScope(endpoint: string, datasetVersion: string, resultHash: string): string;
+/** §2.3 — llm_call:<model>:record_hash:<sha256(JCS(record))> */
+export declare function llmCallScope(model: string, record: object): string;
+/** Preimage for an LLM decision logged by the SDK wrappers */
+export declare function llmDecisionPreimage(agentId: number | string, model: string, record: object, timestampMs?: number): ActionPreimage;
+export declare function hashPair(a: string, b: string): string;
+/** All tree levels, leaves first, root level last */
+export declare function buildMerkleLevels(leaves: string[]): string[][];
+export declare function merkleRoot(leaves: string[]): string;
+/** Sibling path for leaf `index`; levels where the node was promoted are skipped */
+export declare function merkleProof(levels: string[][], index: number): string[];
+/** Off-chain mirror of AuditVault._verifyMerkle */
+export declare function verifyMerkleProof(leaf: string, proof: string[], root: string): boolean;
+export interface BatchEntry {
+    action_ref: string;
+    preimage: ActionPreimage;
+    /** Hashed audit record the scope commits to — never raw prompt/response content */
+    record?: object;
+}
+export interface BatchRecord {
+    schema: typeof EVIDENCE_SCHEMA;
+    batch_id: string;
+    agent_address: string;
+    merkle_root: string;
+    leaf_hash: "sha256(jcs(preimage))";
+    node_hash: "keccak256(sorted_pair)";
+    odd_node: "promote";
+    created_at_ms: number;
+    entries: BatchEntry[];
+}
+export interface BatchStore {
+    /** Persist the batch and return the contentURI to anchor on-chain */
+    put(record: BatchRecord): Promise<string>;
+    get(batchId: string): Promise<BatchRecord | null>;
+}
+export declare class MemoryBatchStore implements BatchStore {
+    private readonly records;
+    put(record: BatchRecord): Promise<string>;
+    get(batchId: string): Promise<BatchRecord | null>;
+}
+/** Writes one JSON file per batch: <dir>/<batch_id>.json */
+export declare class FileBatchStore implements BatchStore {
+    private readonly dir;
+    constructor(dir: string);
+    private file;
+    put(record: BatchRecord): Promise<string>;
+    get(batchId: string): Promise<BatchRecord | null>;
+}
+export interface CommitBatchParams {
+    agentAddress: string;
+    merkleRoot: string;
+    contentURI: string;
+    eventCount: number;
+    complianceScore: number;
+}
+export interface CommitBatchResult {
+    txHash: string;
+    /** Per-agent batch index from LogBatchCommitted; null if not found in receipt */
+    batchIndex: number | null;
+}
+/** Anything that can call AuditVault v2 commitBatch — AgentAudit implements it */
+export interface BatchCommitter {
+    commitBatch(params: CommitBatchParams): Promise<CommitBatchResult>;
+    /** Optional fail-fast check, called before a buffer is built for this committer */
+    assertBatchAnchoring?(): void;
+}
+export interface BatchBufferConfig {
+    committer: BatchCommitter;
+    /** Agent address the batch is committed under (AuditVault v2 keys agents by address) */
+    agentAddress: string;
+    store?: BatchStore;
+    /** Flush when this many entries are buffered (default 50) */
+    maxEntries?: number;
+    /** Flush this many seconds after the first buffered entry (default 60) */
+    maxAgeSeconds?: number;
+    /** uint8 0–100 passed to commitBatch (default 0 = not assessed by SDK) */
+    complianceScore?: number;
+    /** Receives errors from timer-triggered flushes (default console.error) */
+    onError?: (err: Error) => void;
+}
+export interface FlushResult {
+    batchId: string;
+    merkleRoot: string;
+    contentURI: string;
+    eventCount: number;
+    txHash: string;
+    batchIndex: number | null;
+}
+export interface InclusionProof {
+    leaf: string;
+    proof: string[];
+    root: string;
+    batchId: string;
+    /** Pass to AuditVault.verifyLog(agentAddress, batchIndex, leaf, proof) */
+    batchIndex: number | null;
+    agentAddress: string;
+    txHash: string;
+}
+/**
+ * Collects action_refs and anchors them as one Merkle root per batch.
+ * Flushes on maxEntries, on maxAgeSeconds after the first entry, or on flush().
+ * Flushes are serialized; a failed flush re-queues its entries for retry.
+ */
+export declare class BatchBuffer {
+    readonly agentAddress: string;
+    private readonly committer;
+    private readonly store;
+    private readonly maxEntries;
+    private readonly maxAgeMs;
+    private readonly complianceScore;
+    private readonly onError;
+    private pending;
+    private timer?;
+    private flushChain;
+    private readonly index;
+    private readonly batches;
+    constructor(config: BatchBufferConfig);
+    /** Number of entries waiting for the next flush */
+    get size(): number;
+    /**
+     * Buffer one action. Resolves once buffered — or, if this entry fills the
+     * batch, once that flush completes (so commit errors reach the caller).
+     */
+    add(preimage: ActionPreimage, record?: object): Promise<{
+        actionRef: string;
+    }>;
+    /** Anchor everything buffered now. Resolves null if there was nothing to flush. */
+    flush(): Promise<FlushResult | null>;
+    /** Stop the timer and flush whatever is left */
+    close(): Promise<FlushResult | null>;
+    /** Proof for a committed action_ref; null if unknown or still pending */
+    getInclusionProof(actionRef: string): InclusionProof | null;
+    private _flush;
+    private _armTimer;
+    private _clearTimer;
+}
+/** "batch" (default): buffer + commitBatch. "per_action": legacy one tx per call */
+export type AuditMode = "batch" | "per_action";
+export interface BatchOptions {
+    /** Share one buffer across several wrappers; other options are then ignored */
+    buffer?: BatchBuffer;
+    /** Defaults to the SDK signer's address */
+    agentAddress?: string;
+    store?: BatchStore;
+    maxEntries?: number;
+    maxAgeSeconds?: number;
+    complianceScore?: number;
+    onError?: (err: Error) => void;
+}
+/** Build (or reuse) the buffer a wrapper logs into */
+export declare function resolveBatchBuffer(sdk: BatchCommitter & {
+    getAddress(): string;
+}, options?: BatchOptions): BatchBuffer;