diff --git a/README.md b/README.md index 8026b94..1ad4f07 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ Base Agent Meter answers one production question: It is a focused assurance tool for teams operating x402-paid APIs on Base. It provides an unpaid pre-deploy check, an explicitly gated real-buyer canary, and Base-native settlement proof. +**Live read-only interface:** [Base Agent Meter](https://base-receipt-six.vercel.app/meter) · **MCP:** `https://base-receipt-six.vercel.app/meter/mcp` · [Hosted capabilities and pinned source revision](https://base-receipt-six.vercel.app/api/meter). + ## 1. Pre-deploy and CI check The checker contacts a public seller endpoint without providing payment and validates reachability, x402 v2 negotiation, Base Mainnet, Base USDC, positive atomic amount, valid `payTo`, pinned expectation drift, Bazaar metadata, and declared ERC-8021 builder attribution. @@ -106,11 +108,15 @@ Retries are not automatic because repeating a paid request may create another se After a completed canary, Base Agent Meter verifies transaction inclusion and status, Base USDC `Transfer` evidence, expected payer, recipient, and amount, and the ERC-8021 calldata suffix when present. The result distinguishes declared, observed, and verified builder attribution. +Settlement attribution recognizes both the flat code list in ERC-8021 schema 0 (used by direct Base Receipt transfers) and the application code in x402 schema 2. Schema-2 service codes do not count as the seller's application code. Custom-registry schema-1 codes may be observed but are not verified by a string match alone. The returned `builderAttribution.format` identifies the decoded format. Implementations: [Ox ERC-8021](https://github.com/wevm/ox/blob/main/src/erc8021/Attribution.ts) and [x402 builder-code extension](https://github.com/x402-foundation/x402/blob/main/specs/extensions/builder_code.md). + The canary writes a JSON artifact under `artifacts/` containing endpoint, timestamp, payment terms, payer, transaction hash, response status, latency, response body hash, USDC evidence, and builder-attribution evidence. Existing transactions can be checked through `POST /api/proof/verify`. ## Deployment status and optional seller fixture -The previously configured Railway host returned **HTTP 404, Application not found**, on 2026-10-01. Public availability of `/health` and `/mcp` is not verified. A passing build or a merged commit is not evidence of a live service. +The read-only checker and MCP tools are hosted on the existing Base Receipt Vercel deployment at `/meter` and `/meter/mcp`. The host imports a pinned Git revision of this repository; `/api/meter` identifies that revision. The web page and public SDK access were checked on 2026-10-01. The paid snapshot fixture and paid canary are not hosted on that service. + +The old Railway host returned **HTTP 404, Application not found**, on 2026-10-01 and remains unavailable. Its `/health`, standalone `/mcp` and paid fixture are not served by that hostname. A passing build or a merged commit alone is not evidence of a live service. `railway.json` selects the Dockerfile, sets `/health` as the deployment health check, and configures up to three on-failure restarts. The Docker build and CI use the committed dependency lockfile. This configuration applies when an authorized Railway service deploys the repository; it does not create or reconnect that service. See [Railway's configuration reference](https://docs.railway.com/config-as-code/reference). diff --git a/package-lock.json b/package-lock.json index 7834cca..465f126 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19,7 +19,7 @@ "dotenv": "^16.4.7", "express": "^5.1.0", "express-rate-limit": "^8.7.0", - "ox": "^1.6.2", + "ox": "1.7.4", "viem": "^2.45.0", "zod": "^4.6.5" }, @@ -4104,9 +4104,9 @@ } }, "node_modules/ox": { - "version": "1.6.2", - "resolved": "https://registry.npmjs.org/ox/-/ox-1.6.2.tgz", - "integrity": "sha512-Jcll+tKlUV0sUPJ6YlmcpKRcefipswF5DI9lz+kn8Qc6fY5UrMEoeL+E9Y+9h6apKnvQ4N4anggJWNqFC7Vxiw==", + "version": "1.7.4", + "resolved": "https://registry.npmjs.org/ox/-/ox-1.7.4.tgz", + "integrity": "sha512-bpi/fBiftKb8aO4vHbvTq+pMRRTbzAML52ZRa+fH1gdwtLDCNE2VxpyASLeukltrDpXhzXQy69iNX3O0PtBWEw==", "funding": [ { "type": "github", diff --git a/package.json b/package.json index a286460..ac9c0da 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,10 @@ "import": "./dist/index.js" } }, - "files": ["dist", "README.md"], + "files": [ + "dist", + "README.md" + ], "scripts": { "dev": "tsx watch src/server.ts", "build": "tsc -p tsconfig.build.json", @@ -33,7 +36,7 @@ "dotenv": "^16.4.7", "express": "^5.1.0", "express-rate-limit": "^8.7.0", - "ox": "^1.6.2", + "ox": "1.7.4", "viem": "^2.45.0", "zod": "^4.6.5" }, diff --git a/src/proof.ts b/src/proof.ts index 34a8aff..4f47bd4 100644 --- a/src/proof.ts +++ b/src/proof.ts @@ -2,8 +2,23 @@ import { decodeEventLog, erc20Abi, getAddress, type Hex } from "viem"; import { createPublicClient, http } from "viem"; import { base } from "viem/chains"; import { parseBuilderCodeSuffixFromCalldata } from "@x402/extensions/builder-code"; +import { Attribution } from "ox/erc8021"; import { BASE_USDC } from "./assurance.js"; +export function inspectBuilderAttribution(calldata: Hex, declaredBuilderCode?: string) { + const x402 = parseBuilderCodeSuffixFromCalldata(calldata); + if (x402) { + return { declared: declaredBuilderCode ?? null, observed: x402, format: "erc8021-schema-2" as const, verified: Boolean(declaredBuilderCode && x402.a === declaredBuilderCode) }; + } + let legacy: ReturnType; + try { legacy = Attribution.fromData(calldata); } catch { legacy = undefined; } + if (legacy?.id === 0) { + return { declared: declaredBuilderCode ?? null, observed: legacy, format: "erc8021-schema-0" as const, verified: Boolean(declaredBuilderCode && legacy.codes.includes(declaredBuilderCode)) }; + } + // Schema 1 uses a custom registry. A matching string alone cannot establish its identity. + return { declared: declaredBuilderCode ?? null, observed: legacy ?? null, format: legacy ? `erc8021-schema-${legacy.id}` : null, verified: false }; +} + export async function verifyBaseSettlement( rpcUrl: string, input: { transactionHash: Hex; expectedPayer?: string; expectedPayTo: string; expectedAmount: string; declaredBuilderCode?: string }, @@ -30,8 +45,7 @@ export async function verifyBaseSettlement( && transfer.amount === input.expectedAmount && (!input.expectedPayer || transfer.from === getAddress(input.expectedPayer)), ); - const attribution = parseBuilderCodeSuffixFromCalldata(transaction.input); - const builderVerified = Boolean(input.declaredBuilderCode && attribution?.a === input.declaredBuilderCode); + const builderAttribution = inspectBuilderAttribution(transaction.input, input.declaredBuilderCode); const settlementVerified = receipt.status === "success" && Boolean(expectedTransfer); return { @@ -47,10 +61,6 @@ export async function verifyBaseSettlement( matchingTransfer: expectedTransfer ?? null, observedTransfers: transfers, }, - builderAttribution: { - declared: input.declaredBuilderCode ?? null, - observed: attribution ?? null, - verified: builderVerified, - }, + builderAttribution, }; } diff --git a/test/attribution.test.ts b/test/attribution.test.ts new file mode 100644 index 0000000..c78f1f8 --- /dev/null +++ b/test/attribution.test.ts @@ -0,0 +1,34 @@ +import { describe, expect, it } from "vitest"; +import { Attribution } from "ox/erc8021"; +import { concatHex } from "viem"; +import { encodeBuilderCodeSuffix } from "@x402/extensions/builder-code"; +import { inspectBuilderAttribution } from "../src/proof.js"; + +describe("settlement attribution formats", () => { + const legacy = concatHex(["0x12345678", Attribution.toDataSuffix({ codes: ["bc_87fjmj1l"] })]); + const x402 = concatHex(["0x12345678", encodeBuilderCodeSuffix({ a: "seller_code", s: ["service_code"] })]); + + it("recognizes the schema-0 format used by direct Base Receipt payments", () => { + expect(inspectBuilderAttribution(legacy, "bc_87fjmj1l")).toMatchObject({ verified: true, format: "erc8021-schema-0", observed: { id: 0, codes: ["bc_87fjmj1l"] } }); + }); + it("does not verify an unexpected legacy code", () => { + expect(inspectBuilderAttribution(legacy, "another_code").verified).toBe(false); + }); + it("reports observed codes without silently selecting an expected code", () => { + expect(inspectBuilderAttribution(legacy)).toMatchObject({ declared: null, verified: false, observed: { codes: ["bc_87fjmj1l"] } }); + }); + it("continues verifying schema-2 application codes", () => { + expect(inspectBuilderAttribution(x402, "seller_code")).toMatchObject({ format: "erc8021-schema-2", observed: { a: "seller_code" }, verified: true }); + }); + it("does not mistake a schema-2 service code for the application code", () => { + expect(inspectBuilderAttribution(x402, "service_code").verified).toBe(false); + }); + it("does not verify a code with an unvalidated custom registry", () => { + const custom = Attribution.toDataSuffix({ codes: ["bc_87fjmj1l"], codeRegistry: { address: "0x1111111111111111111111111111111111111111", chainId: 8453 } }); + expect(inspectBuilderAttribution(custom, "bc_87fjmj1l").verified).toBe(false); + }); + it("does not verify missing or truncated suffixes", () => { + expect(inspectBuilderAttribution("0x12345678", "bc_87fjmj1l").verified).toBe(false); + expect(inspectBuilderAttribution(legacy.slice(0, -2) as `0x${string}`, "bc_87fjmj1l").verified).toBe(false); + }); +});