tersign 0.4.3 → 0.4.5

package/README.md

@@ -47,6 +47,8 @@ The text is digested **locally** (only the digest travels — data-minimization
 
 Every entry takes the same path: the seller **signs** the receipt (EIP-712, x402 offer-receipt extension) → Tersign computes the **keccak256 canonical digest** → the digest joins that **seller's hash chain**, each `seq n` bound to `seq n−1` → the neutral ledger **counter-signs** (secp256k1) → **anyone verifies**, and any venue gets a serialized envelope.
 
+Since 2026-08-28 each anchor stamps a chain commitment — an accumulator over every counter-signed link — so one anchored digest covers the whole prefix; rows anchored earlier bind the head record only and say so (`subjectSchema`).
+
 ```mermaid
 graph LR
     A["agent transaction<br/>x402"] --> B["seller-signed receipt<br/>EIP-712"]
@@ -137,7 +139,7 @@ The agent skill `tersign-evidence` ships at [tersignhq/skills](https://github.co
 - **Ledger + dashboard** — public verify page: https://tersign.ai/verify
 - **Census** — hash-chained observations across the live x402 seller catalog, probed autonomously; the numbers are served live, never quoted stale: https://prober.tersign.ai/v1/prober/stats
 - **Conformance** — RFC 8785 (JCS) canonical serialization, keccak256 digests, and the public two-sided vector suite (canonical bytes, number domain, content address, chain continuity, completeness, anchored existence, phase separation, offer binding, independence — every criterion carrying both an accepting and an adversarial vector): [tersignhq/evidence-record-conformance](https://github.com/tersignhq/evidence-record-conformance). Reproduce the bytes and your implementation is conformant — in any language.
-- **Standards** — the `compliance-fields` extension — a typed compliance-record schema plus four evaluator-side disqualifications (independence, completeness/existence, economic-phase separation, and commitment scope — an independence claim reaches exactly as far as the record's own commitments), each executable as a two-sided conformance vector — is under review upstream ([x402-foundation/x402#2853](https://github.com/x402-foundation/x402/pull/2853)) and referenced in the x402 TSC's evidence-record charter agenda ([tsc#4](https://github.com/x402-foundation/tsc/issues/4)). The merged offer-receipt spec already carries the completeness criterion at SHOULD strength (§4.5.1, [#2811](https://github.com/x402-foundation/x402/pull/2811)).
+- **Standards** — the `compliance-fields` extension — a typed compliance-record schema plus four evaluator-side disqualifications (independence, completeness/existence, economic-phase separation, and commitment scope — an independence claim reaches exactly as far as the record's own commitments), each executable as a two-sided conformance vector — is under review upstream ([x402-foundation/x402#2853](https://github.com/x402-foundation/x402/pull/2853)) and referenced in the x402 TSC's evidence-record charter agenda ([tsc#4](https://github.com/x402-foundation/tsc/issues/4)). The merged offer-receipt spec already carries post-session verification guidance — signer authorization evaluated as of `issuedAt`, with mutable-source rotation handled explicitly ([#2811](https://github.com/x402-foundation/x402/pull/2811), merged); the completeness, independence, existence and phase disqualifications are the open extension's normative core.
 
 ## Machine Surfaces
 

package/dist/canonical.d.ts

@@ -1,3 +1,4 @@
+import { type Hex } from 'viem';
 /** Deterministic JSON — RFC 8785 (JCS) conformant for JSON-domain inputs: keys sorted by
  * UTF-16 code units, no whitespace, JSON.stringify scalar/escape semantics. Arrays keep
  * order; undefined properties are dropped (matches JSON.stringify semantics).
@@ -9,3 +10,57 @@
  * digest and all pinned wire vectors are unchanged. */
 export declare function canonicalStringify(value: unknown): string;
 export declare function digestOf(value: unknown): `0x${string}`;
+/** Hash-chain link, byte-identical to the hosted ledger's recompute: the ledger
+ * counter-signs `keccak256(artifactDigest || prevDigest-or-32-zero-bytes || uint64be(seq))`.
+ * `prevDigest` is the PREVIOUS record's artifactDigest (null at seq 1). */
+export declare const GENESIS_DIGEST: Hex;
+export declare function chainLinkDigest(artifactDigest: Hex, prevDigest: Hex | null, seq: number): Hex;
+/** Chain commitment accumulator (anchored since 2026-08-28). DERIVED, never signed, never
+ * stored per row: acc_0 = keccak256(utf8("tersign-chain-commitment-v1")); acc_k =
+ * keccak256(acc_{k-1} || link_k). A pure function of (a_1..a_k, 1..k) — any omission,
+ * insertion, reordering or rewrite below k changes acc_k, so ONE anchored digest over acc_N
+ * commits to the whole prefix. The anchor stamps digestOf({acc, head, schema, seq}).
+ * Pinned cross-implementation (this SDK, the hosted ledger, the Python SDK and the evidence-bundle
+ * verifier share the same test vectors): edit all or none. */
+export declare const CHAIN_COMMITMENT_SCHEMA = "tersign-chain-commitment-v1";
+export declare const ACC_GENESIS: Hex;
+export declare function chainAccumulatorStep(acc: Hex, link: Hex): Hex;
+export type ChainCommitment = {
+    acc: Hex;
+    head: Hex;
+    schema: typeof CHAIN_COMMITMENT_SCHEMA;
+    seq: number;
+};
+export declare function chainCommitment(seq: number, head: Hex, acc: Hex): ChainCommitment;
+/** keccak256 over the JCS bytes of the commitment object — the anchored subject digest. */
+export declare function commitmentDigest(seq: number, head: Hex, acc: Hex): Hex;
+/** A set of records that does not re-walk (gap, prev ≠ previous artifact, wrong seq): no
+ * accumulator is derived over it — a value no independent recompute would reproduce. */
+export declare class ChainIntegrityError extends Error {
+}
+export type ChainRecordLike = {
+    artifactDigest: Hex;
+    prevDigest: Hex | null;
+    seq: number;
+};
+/** Fold records 1..N (in seq order, dense, prev-continuous). Returns acc_N and the head
+ * artifact digest a_N. Throws ChainIntegrityError on any discontinuity or on an empty set. */
+export declare function foldAccumulator(records: ChainRecordLike[]): {
+    acc: Hex;
+    head: Hex;
+};
+export type CommitmentVerifyResult = {
+    ok: boolean;
+    acc: Hex;
+    digest: Hex;
+    reason?: string;
+};
+/** Recompute the accumulator over `records` (seq 1..N as served by the ledger) and compare it
+ * to an anchored commitment (the `commitment` object from `/v1/receipts/{digest}/verify`, or
+ * any `{seq, acc, head?}`). `acc`/`digest` are the RECOMPUTED values — compare `digest` to the
+ * anchor's subjectDigest. A truncated, substituted, reordered or renumbered prefix fails. */
+export declare function verifyCommitment(records: ChainRecordLike[], commitment: {
+    seq: number;
+    acc: Hex | string;
+    head?: Hex | string;
+}): CommitmentVerifyResult;

package/dist/canonical.js

@@ -1,4 +1,4 @@
-import { keccak256, toBytes } from 'viem';
+import { concatHex, keccak256, numberToHex, stringToHex, toBytes } from 'viem';
 /** Deterministic JSON — RFC 8785 (JCS) conformant for JSON-domain inputs: keys sorted by
  * UTF-16 code units, no whitespace, JSON.stringify scalar/escape semantics. Arrays keep
  * order; undefined properties are dropped (matches JSON.stringify semantics).
@@ -33,3 +33,76 @@ function serialize(value) {
 export function digestOf(value) {
     return keccak256(toBytes(canonicalStringify(value)));
 }
+/** Hash-chain link, byte-identical to the hosted ledger's recompute: the ledger
+ * counter-signs `keccak256(artifactDigest || prevDigest-or-32-zero-bytes || uint64be(seq))`.
+ * `prevDigest` is the PREVIOUS record's artifactDigest (null at seq 1). */
+export const GENESIS_DIGEST = `0x${'0'.repeat(64)}`;
+export function chainLinkDigest(artifactDigest, prevDigest, seq) {
+    return keccak256(concatHex([artifactDigest, prevDigest ?? GENESIS_DIGEST, numberToHex(seq, { size: 8 })]));
+}
+/** Chain commitment accumulator (anchored since 2026-08-28). DERIVED, never signed, never
+ * stored per row: acc_0 = keccak256(utf8("tersign-chain-commitment-v1")); acc_k =
+ * keccak256(acc_{k-1} || link_k). A pure function of (a_1..a_k, 1..k) — any omission,
+ * insertion, reordering or rewrite below k changes acc_k, so ONE anchored digest over acc_N
+ * commits to the whole prefix. The anchor stamps digestOf({acc, head, schema, seq}).
+ * Pinned cross-implementation (this SDK, the hosted ledger, the Python SDK and the evidence-bundle
+ * verifier share the same test vectors): edit all or none. */
+export const CHAIN_COMMITMENT_SCHEMA = 'tersign-chain-commitment-v1';
+export const ACC_GENESIS = keccak256(stringToHex(CHAIN_COMMITMENT_SCHEMA));
+export function chainAccumulatorStep(acc, link) {
+    return keccak256(concatHex([acc, link]));
+}
+export function chainCommitment(seq, head, acc) {
+    return { acc, head, schema: CHAIN_COMMITMENT_SCHEMA, seq };
+}
+/** keccak256 over the JCS bytes of the commitment object — the anchored subject digest. */
+export function commitmentDigest(seq, head, acc) {
+    return digestOf(chainCommitment(seq, head, acc));
+}
+/** A set of records that does not re-walk (gap, prev ≠ previous artifact, wrong seq): no
+ * accumulator is derived over it — a value no independent recompute would reproduce. */
+export class ChainIntegrityError extends Error {
+}
+/** Fold records 1..N (in seq order, dense, prev-continuous). Returns acc_N and the head
+ * artifact digest a_N. Throws ChainIntegrityError on any discontinuity or on an empty set. */
+export function foldAccumulator(records) {
+    if (records.length < 1)
+        throw new ChainIntegrityError('no records to fold');
+    let acc = ACC_GENESIS;
+    let prev = null;
+    for (let i = 0; i < records.length; i++) {
+        const r = records[i];
+        if (r.seq !== i + 1)
+            throw new ChainIntegrityError(`seq ${r.seq} at position ${i + 1}`);
+        if ((r.prevDigest ?? null) !== prev)
+            throw new ChainIntegrityError(`prev mismatch at seq ${r.seq}`);
+        acc = chainAccumulatorStep(acc, chainLinkDigest(r.artifactDigest, prev, r.seq));
+        prev = r.artifactDigest;
+    }
+    return { acc, head: prev };
+}
+/** Recompute the accumulator over `records` (seq 1..N as served by the ledger) and compare it
+ * to an anchored commitment (the `commitment` object from `/v1/receipts/{digest}/verify`, or
+ * any `{seq, acc, head?}`). `acc`/`digest` are the RECOMPUTED values — compare `digest` to the
+ * anchor's subjectDigest. A truncated, substituted, reordered or renumbered prefix fails. */
+export function verifyCommitment(records, commitment) {
+    let folded;
+    try {
+        folded = foldAccumulator(records);
+    }
+    catch (err) {
+        const reason = err instanceof ChainIntegrityError ? err.message : String(err);
+        return { ok: false, acc: ACC_GENESIS, digest: GENESIS_DIGEST, reason: `records do not re-walk: ${reason}` };
+    }
+    const digest = commitmentDigest(records.length, folded.head, folded.acc);
+    if (records.length !== commitment.seq) {
+        return { ok: false, acc: folded.acc, digest, reason: `records cover seq ≤ ${records.length}, commitment covers seq ≤ ${commitment.seq}` };
+    }
+    if (folded.acc.toLowerCase() !== String(commitment.acc).toLowerCase()) {
+        return { ok: false, acc: folded.acc, digest, reason: 'accumulator mismatch: the commitment was not built over this prefix' };
+    }
+    if (commitment.head !== undefined && folded.head.toLowerCase() !== String(commitment.head).toLowerCase()) {
+        return { ok: false, acc: folded.acc, digest, reason: 'head mismatch: the commitment names a different head record' };
+    }
+    return { ok: true, acc: folded.acc, digest };
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * from './types.js';
-export { canonicalStringify, digestOf } from './canonical.js';
+export { canonicalStringify, digestOf, GENESIS_DIGEST, chainLinkDigest, CHAIN_COMMITMENT_SCHEMA, ACC_GENESIS, chainAccumulatorStep, chainCommitment, commitmentDigest, foldAccumulator, verifyCommitment, ChainIntegrityError, type ChainCommitment, type ChainRecordLike, type CommitmentVerifyResult, } from './canonical.js';
 export { RECEIPT_DOMAIN, RECEIPT_TYPES, OFFER_DOMAIN, OFFER_TYPES, signReceipt, signOffer, verifyReceipt, type VerifyResult, } from './receipt/eip712.js';
 export { COMPLIANCE_DOMAIN, COMPLIANCE_TYPES, COMPLIANCE_WIRE_VECTOR, buildMinimalRecord, recordDigest, signComplianceRecord, verifyComplianceRecord, type IssuerConfig, type MinimalRecordInput, } from './compliance/record.js';
 export { MemoryIdempotencyStore, checkIdempotency, extractPaymentId, fingerprint, REPLAY_HEADER, type IdempotencyStore, type IdempotencyOutcome, type IdempotencyOptions, type CachedResponse, type FingerprintParts, } from './idempotency/middleware.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export * from './types.js';
-export { canonicalStringify, digestOf } from './canonical.js';
+export { canonicalStringify, digestOf, GENESIS_DIGEST, chainLinkDigest, CHAIN_COMMITMENT_SCHEMA, ACC_GENESIS, chainAccumulatorStep, chainCommitment, commitmentDigest, foldAccumulator, verifyCommitment, ChainIntegrityError, } from './canonical.js';
 export { RECEIPT_DOMAIN, RECEIPT_TYPES, OFFER_DOMAIN, OFFER_TYPES, signReceipt, signOffer, verifyReceipt, } from './receipt/eip712.js';
 export { COMPLIANCE_DOMAIN, COMPLIANCE_TYPES, COMPLIANCE_WIRE_VECTOR, buildMinimalRecord, recordDigest, signComplianceRecord, verifyComplianceRecord, } from './compliance/record.js';
 export { MemoryIdempotencyStore, checkIdempotency, extractPaymentId, fingerprint, REPLAY_HEADER, } from './idempotency/middleware.js';

package/dist/mcp/server.d.ts

@@ -8,6 +8,6 @@ export declare function envDeps(env?: Record<string, string | undefined>): McpDe
  * every client; mcp.test.ts pins it against package.json so a release bump can't drift it. */
 export declare const MCP_SERVER_IDENTITY: {
     readonly name: "tersign";
-    readonly version: "0.4.3";
+    readonly version: "0.4.5";
 };
 export declare function buildServer(deps: McpDeps): McpServer;

package/dist/mcp/server.js

@@ -45,30 +45,47 @@ function json(value) {
 }
 /** MUST match package.json name/version — the MCP handshake self-reports this identity to
  * every client; mcp.test.ts pins it against package.json so a release bump can't drift it. */
-export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.4.3' };
+export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.4.5' };
 export function buildServer(deps) {
     const server = new McpServer(MCP_SERVER_IDENTITY);
     server.registerTool('issue_receipt', {
         title: 'Issue signed receipt',
-        description: 'Issue an x402 offer-receipt (EIP-712) plus an Tersign compliance record for a settled payment; counter-signs into the ledger when configured.',
+        description: 'Issue an x402 offer-receipt (EIP-712) plus a Tersign action record for a payment that has ALREADY settled, and counter-sign both into your hash chain when a ledger is configured. ' +
+            'Use this for money that moved; use record_disclosure for a non-payment agent action. ' +
+            'Side effects: signs with TERSIGN_SELLER_KEY, and performs ONE network write to the ledger when TERSIGN_LEDGER_URL/_API_KEY/_SELLER_ID are set (without them it signs locally and returns an unchained artifact). ' +
+            'Returns the signed receipt artifact, its keccak256 canonical digest, and — when chained — the ledger counter-signature and sequence number.',
         inputSchema: {
-            network: z.string().describe('CAIP-2, e.g. eip155:8453'),
-            resourceUrl: z.string().url(),
-            payer: z.string(),
-            supplyDescription: z.string(),
-            settledAt: z.number().int().optional(),
-            txHash: z.string().optional(),
-            taxScheme: z.enum(['none', 'vat', 'gst', 'jct', 'sales']).optional(),
-            currency: z.string().optional(),
-            principal: z.string().optional().describe('signed principal behind the paying agent'),
+            network: z.string().describe('settlement network as CAIP-2, e.g. "eip155:8453" for Base mainnet'),
+            resourceUrl: z.string().url().describe('absolute URL of the resource that was paid for; appears verbatim in the receipt'),
+            payer: z.string().describe('0x address that paid — the party who can later open a dispute against this receipt'),
+            supplyDescription: z.string().describe('what was supplied, in the seller\'s own words; the human-readable line an auditor or venue reads'),
+            settledAt: z.number().int().optional().describe('unix seconds when settlement occurred; defaults to now. Set it explicitly when back-filling'),
+            txHash: z.string().optional().describe('on-chain settlement transaction hash, when one exists; omit for off-chain or fiat settlement'),
+            taxScheme: z
+                .enum(['none', 'vat', 'gst', 'jct', 'sales'])
+                .optional()
+                .describe('tax regime the seller is accounting under; recorded, never computed — Tersign does not calculate tax'),
+            currency: z.string().optional().describe('settlement currency code, e.g. "USDC" or "USD"'),
+            principal: z
+                .string()
+                .optional()
+                .describe('the party on whose authority the paying agent acted (x402 sense: the buyer who delegated). Omit when a human paid directly'),
         },
     }, async (args) => json(await issueReceiptTool(deps, args)));
     server.registerTool('verify_receipt', {
         title: 'Verify signed receipt',
-        description: 'Verify an offer-receipt artifact (EIP-712) and optionally enforce an expected signer (payTo authorization).',
+        description: 'Verify an offer-receipt artifact: recover the EIP-712 signature and confirm the payload digest binds to it. ' +
+            'Fully OFFLINE — no network, no API key, no account; verifying someone else\'s receipt is the intended use. ' +
+            'Use this for a receipt (money); use verify_compliance_record for an action record (a non-payment action). ' +
+            'Returns { valid, signer, digest } and, when expectedSigner is supplied and does not match, valid:false with the recovered signer so you can see who actually signed.',
         inputSchema: {
-            artifact: z.record(z.unknown()).describe('the receipt artifact object {format, payload, signature}'),
-            expectedSigner: z.string().optional(),
+            artifact: z
+                .record(z.unknown())
+                .describe('the receipt artifact exactly as issued: { format, payload, signature }. Pass the object, not a JSON string'),
+            expectedSigner: z
+                .string()
+                .optional()
+                .describe('0x address the receipt MUST be signed by — obtain it out-of-band, never from the artifact. Omit to recover the signer without enforcing it'),
         },
     }, async ({ artifact, expectedSigner }) => json(await verifyReceiptTool(artifact, expectedSigner)));
     server.registerTool('record_disclosure', {
@@ -78,27 +95,49 @@ export function buildServer(deps) {
             text: z.string().optional().describe('the disclosure text as presented — digested locally, never transmitted'),
             textDigest: z.string().regex(/^0x[0-9a-fA-F]{64}$/).optional().describe('pre-computed digest (wins over text)'),
             medium: z.string().optional().describe("channel: 'chat' | 'api' | 'voice' | 'ui' …"),
-            kind: z.enum(['ai-interaction', 'synthetic-content']).optional(),
-            agentId: z.string().describe('stable identifier for the disclosing agent'),
-            resourceUrl: z.string().url().optional(),
+            kind: z
+                .enum(['ai-interaction', 'synthetic-content'])
+                .optional()
+                .describe("what was disclosed: 'ai-interaction' = the user was told they are talking to an AI; 'synthetic-content' = output was marked machine-generated. Defaults to 'ai-interaction'"),
+            agentId: z.string().describe('stable identifier for the disclosing agent — keep it constant across calls so one chain accumulates per agent'),
+            resourceUrl: z.string().url().optional().describe('absolute URL of the surface the disclosure was presented on, when there is one'),
         },
     }, async (args) => json(await recordDisclosureTool(deps, args)));
     server.registerTool('verify_compliance_record', {
         title: 'Verify compliance record',
-        description: 'Verify an Tersign compliance record + attestation (digest binding and signature).',
+        description: 'Verify a Tersign action record against its attestation: recompute the record\'s canonical digest, confirm the attestation commits to that exact digest, and recover the signature. ' +
+            'Fully OFFLINE — no network, no API key, no account. ' +
+            'Use this for an action record (a disclosure or other non-payment agent action); use verify_receipt for a payment receipt. ' +
+            'PASS proves integrity and internal consistency only. Authorship needs an out-of-band signer address: pass expectedSigner, or the identity is whatever the artifact claims about itself. ' +
+            'Returns { valid, signer, digest }; on mismatch, valid:false plus the recovered signer and the recomputed digest.',
         inputSchema: {
-            record: z.record(z.unknown()),
-            attestation: z.record(z.unknown()),
-            expectedSigner: z.string().optional(),
+            record: z
+                .record(z.unknown())
+                .describe('the action record object as issued (ComplianceRecordV1 shape). Pass the object, not a JSON string; any field edit changes the digest and fails verification — which is the point'),
+            attestation: z
+                .record(z.unknown())
+                .describe('the attestation that accompanies the record: the signature over the record digest, as returned alongside it at issuance'),
+            expectedSigner: z
+                .string()
+                .optional()
+                .describe('0x address the record MUST be signed by, obtained out-of-band (for the public ledger: https://tersign.ai/v1/ledger). Omit to recover the signer without enforcing it'),
         },
     }, async ({ record, attestation, expectedSigner }) => json(await verifyRecordTool(record, attestation, expectedSigner)));
     server.registerTool('record_refund', {
         title: 'Record refund',
-        description: 'Record a refund against a receipt digest in the Tersign ledger (requires ledger configuration).',
+        description: 'Record a refund against an already-chained receipt, as the SELLER. The refund becomes its own counter-signed entry that references the original — nothing is edited or deleted, so the chain stays append-only and both the charge and the refund remain visible. ' +
+            'Requires ledger configuration (TERSIGN_LEDGER_URL/_API_KEY/_SELLER_ID) and performs one network write; errors if the original digest is not on your chain. ' +
+            'This RECORDS a refund you have already made — it moves no money. ' +
+            'Returns the refund record, its digest, the ledger counter-signature and sequence number.',
         inputSchema: {
-            originalDigest: z.string().regex(/^0x[0-9a-fA-F]{64}$/),
-            amount: z.string(),
-            reason: z.string(),
+            originalDigest: z
+                .string()
+                .regex(/^0x[0-9a-fA-F]{64}$/)
+                .describe('0x-prefixed keccak256 digest of the receipt being refunded — the digest returned by issue_receipt, and it must already exist on your chain'),
+            amount: z
+                .string()
+                .describe('refunded amount as a decimal STRING in the original settlement currency, e.g. "12.50". A string, not a number, so no precision is lost. Partial refunds are allowed'),
+            reason: z.string().describe('why the refund was issued, in your own words; recorded verbatim for whoever reads the chain later'),
         },
     }, async ({ originalDigest, amount, reason }) => json(await recordRefundTool(deps, originalDigest, amount, reason)));
     const digestSchema = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
@@ -106,9 +145,13 @@ export function buildServer(deps) {
         title: 'Open dispute',
         description: 'Open an objective dispute against a counter-signed receipt as the PAYER (the configured key must be the receipt payer). Reasons: not_delivered, wrong_content, duplicate_charge. Contested non-mechanical claims escalate to the arbiter; duplicate_charge is decided instantly from ledger arithmetic.',
         inputSchema: {
-            receiptDigest: digestSchema,
-            reason: z.enum(['not_delivered', 'wrong_content', 'duplicate_charge']),
-            claimAmount: z.string().describe('claimed refund in the settlement currency'),
+            receiptDigest: digestSchema.describe('0x-prefixed keccak256 digest of the counter-signed receipt being disputed'),
+            reason: z
+                .enum(['not_delivered', 'wrong_content', 'duplicate_charge'])
+                .describe("grounds: 'not_delivered' nothing arrived · 'wrong_content' delivered but not what was bought · 'duplicate_charge' the same supply was billed twice (decided mechanically from the chain, no arbiter)"),
+            claimAmount: z
+                .string()
+                .describe('amount claimed back, as a decimal STRING in the receipt\'s settlement currency, e.g. "12.50"; must not exceed the receipt amount'),
             statement: z.string().optional().describe('for humans reading the record — never an adjudication input'),
         },
     }, async ({ receiptDigest, reason, claimAmount, statement }) => json(await openDisputeTool(deps, { receiptDigest: receiptDigest, reason, claimAmount, statement })));
@@ -116,16 +159,21 @@ export function buildServer(deps) {
         title: 'Submit dispute evidence',
         description: 'Submit signed evidence to an open dispute. Claimant evidence must be signed by the payer key; respondent evidence additionally requires the seller API key (TERSIGN_LEDGER_API_KEY).',
         inputSchema: {
-            disputeDigest: digestSchema,
-            role: z.enum(['claimant', 'respondent']),
+            disputeDigest: digestSchema.describe('0x-prefixed digest of the open dispute, as returned by open_dispute'),
+            role: z
+                .enum(['claimant', 'respondent'])
+                .describe("which side you are filing as: 'claimant' = the payer who opened it (payer key) · 'respondent' = the seller answering it (also needs TERSIGN_LEDGER_API_KEY)"),
             artifacts: z
                 .array(z.object({
-                kind: z.enum(['content-digest', 'delivery-attestation', 'payment-proof', 'transcript']),
-                digest: digestSchema,
-                at: z.number().int().optional(),
-                note: z.string().optional(),
+                kind: z
+                    .enum(['content-digest', 'delivery-attestation', 'payment-proof', 'transcript'])
+                    .describe('what this artifact is; the adjudicator treats each kind differently'),
+                digest: digestSchema.describe('0x-prefixed keccak256 digest of the artifact. Only the DIGEST is submitted — the content itself never leaves your side'),
+                at: z.number().int().optional().describe('unix seconds the artifact was produced; supply it when timing is part of your argument'),
+                note: z.string().optional().describe('short human-readable label for whoever reads the record; never an adjudication input'),
             }))
-                .min(1),
+                .min(1)
+                .describe('at least one evidence reference; submit every artifact you want considered in a single call'),
         },
     }, async ({ disputeDigest, role, artifacts }) => json(await submitEvidenceTool(deps, {
         disputeDigest: disputeDigest,
@@ -134,13 +182,20 @@ export function buildServer(deps) {
     })));
     server.registerTool('adjudicate_dispute', {
         title: 'Adjudicate dispute',
-        description: 'Trigger deterministic adjudication of an open dispute (public — the v0 rulebook is recomputable by anyone). Refund verdicts create refund records automatically.',
-        inputSchema: { disputeDigest: digestSchema },
+        description: 'Trigger deterministic adjudication of an open dispute. The v0 rulebook is public and the verdict is recomputable by anyone from the chain — no discretion, no model in the loop. ' +
+            'Side effects: writes a verdict entry, and a refund verdict automatically creates the corresponding refund record. Adjudicating twice is not meaningful; the first verdict stands. ' +
+            'Returns the verdict, the rationale naming the rule applied, and the ledger signature over both.',
+        inputSchema: {
+            disputeDigest: digestSchema.describe('0x-prefixed digest of the open dispute to adjudicate, as returned by open_dispute'),
+        },
     }, async ({ disputeDigest }) => json(await adjudicateDisputeTool(deps, disputeDigest)));
     server.registerTool('get_dispute', {
         title: 'Get dispute record',
-        description: 'Fetch a dispute record with its evidence, verdict, rationale, and ledger signature.',
-        inputSchema: { disputeDigest: digestSchema },
+        description: 'Fetch a dispute in full: its state, both sides\' evidence references, the verdict and rationale once adjudicated, and the ledger signature over the record. ' +
+            'Read-only — one network read, no key required, and safe to poll while a dispute is open.',
+        inputSchema: {
+            disputeDigest: digestSchema.describe('0x-prefixed digest of the dispute to fetch, as returned by open_dispute'),
+        },
     }, async ({ disputeDigest }) => json(await getDisputeTool(deps, disputeDigest)));
     return server;
 }

package/dist/verify-bin.js

@@ -48,6 +48,13 @@ async function checkLedger(digest, url) {
         fail('ledger record found but the counter-signed hash-chain does NOT verify');
     console.log(`ledger:    ${url}`);
     console.log(`           counter-signed OK (seller ${body.sellerId}, seq ${body.seq}, ledger key ${body.ledgerSigner})`);
+    // Present once the record sits under an anchored chain commitment (anchors since 2026-08-28):
+    // the accumulator covers every seq ≤ commitment.seq, so the anchor binds this record too.
+    const c = body.commitment;
+    if (c) {
+        const block = c.bitcoinBlockHeight ? ` block ${c.bitcoinBlockHeight}` : '';
+        console.log(`           commitment: seq ≤ ${c.seq} committed (acc ${c.acc.slice(0, 10)}…) — ${c.status}${block}`);
+    }
 }
 if (/^0x[0-9a-f]{64}$/i.test(target)) {
     await checkLedger(target, ledger ?? DEFAULT_LEDGER);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tersign",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Tersign \u2014 the evidence layer for the agent economy. Counter-signed receipts, agent action records, idempotency enforcement, refunds, disputes, and jury-ready evidence envelopes for x402/agent-commerce sellers.",
   "license": "MIT",
   "type": "module",