Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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).

Expand Down
8 changes: 4 additions & 4 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 5 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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"
},
Expand Down
24 changes: 17 additions & 7 deletions src/proof.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<typeof Attribution.fromData>;
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 },
Expand All @@ -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 {
Expand All @@ -47,10 +61,6 @@ export async function verifyBaseSettlement(
matchingTransfer: expectedTransfer ?? null,
observedTransfers: transfers,
},
builderAttribution: {
declared: input.declaredBuilderCode ?? null,
observed: attribution ?? null,
verified: builderVerified,
},
builderAttribution,
};
}
34 changes: 34 additions & 0 deletions test/attribution.test.ts
Original file line number Diff line number Diff line change
@@ -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);
});
});
Loading