x402-trust-layer 5.1.0

package/dist/lib/erc8004/registry.js

@@ -0,0 +1,171 @@
+import { encodeFunctionData } from "viem";
+import { config } from "../../config.js";
+import { DEFAULT_IDENTITY_REGISTRY, DEFAULT_REPUTATION_REGISTRY, ERC8004_CHAIN_ID, } from "./constants.js";
+const identityRegistryAbi = [
+    {
+        inputs: [{ name: "tokenId", type: "uint256" }],
+        name: "ownerOf",
+        outputs: [{ name: "", type: "address" }],
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        inputs: [{ name: "tokenId", type: "uint256" }],
+        name: "tokenURI",
+        outputs: [{ name: "", type: "string" }],
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        inputs: [{ name: "agentId", type: "uint256" }],
+        name: "getAgentWallet",
+        outputs: [{ name: "", type: "address" }],
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        inputs: [{ name: "owner", type: "address" }],
+        name: "balanceOf",
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function",
+    },
+];
+const reputationRegistryAbi = [
+    {
+        inputs: [
+            { name: "agentId", type: "uint256" },
+            { name: "clientAddresses", type: "address[]" },
+            { name: "tag1", type: "string" },
+            { name: "tag2", type: "string" },
+        ],
+        name: "getSummary",
+        outputs: [
+            { name: "count", type: "uint64" },
+            { name: "summaryValue", type: "int128" },
+            { name: "summaryValueDecimals", type: "uint8" },
+        ],
+        stateMutability: "view",
+        type: "function",
+    },
+];
+async function ethCall(to, data) {
+    const res = await fetch(config.baseRpcUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "eth_call",
+            params: [{ to, data }, "latest"],
+        }),
+    });
+    if (!res.ok)
+        return null;
+    const json = (await res.json());
+    if (!json.result || json.result === "0x")
+        return null;
+    return json.result;
+}
+function decodeAddress(result) {
+    if (result.length < 66)
+        return null;
+    return `0x${result.slice(-40)}`;
+}
+function decodeUint256(result) {
+    return BigInt(result);
+}
+function decodeString(result) {
+    try {
+        const hex = result.slice(2);
+        if (hex.length < 128)
+            return null;
+        const offset = Number(BigInt(`0x${hex.slice(0, 64)}`)) * 2;
+        const len = Number(BigInt(`0x${hex.slice(offset, offset + 64)}`));
+        const data = hex.slice(offset + 64, offset + 64 + len * 2);
+        const bytes = new Uint8Array(len);
+        for (let i = 0; i < len; i++) {
+            bytes[i] = parseInt(data.slice(i * 2, i * 2 + 2), 16);
+        }
+        return new TextDecoder().decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+function decodeSummary(result) {
+    try {
+        const hex = result.slice(2);
+        if (hex.length < 192)
+            return null;
+        const count = BigInt(`0x${hex.slice(0, 64)}`);
+        const summaryValue = BigInt(`0x${hex.slice(64, 128)}`);
+        const summaryValueDecimals = Number(BigInt(`0x${hex.slice(128, 192)}`));
+        return { count, summaryValue, summaryValueDecimals };
+    }
+    catch {
+        return null;
+    }
+}
+export function identityRegistryAddress() {
+    return (config.erc8004IdentityRegistry || DEFAULT_IDENTITY_REGISTRY);
+}
+export function reputationRegistryAddress() {
+    return (config.erc8004ReputationRegistry || DEFAULT_REPUTATION_REGISTRY);
+}
+export async function readOwnerOf(agentId) {
+    const data = encodeFunctionData({
+        abi: identityRegistryAbi,
+        functionName: "ownerOf",
+        args: [agentId],
+    });
+    const result = await ethCall(identityRegistryAddress(), data);
+    return result ? decodeAddress(result) : null;
+}
+export async function readTokenUri(agentId) {
+    const data = encodeFunctionData({
+        abi: identityRegistryAbi,
+        functionName: "tokenURI",
+        args: [agentId],
+    });
+    const result = await ethCall(identityRegistryAddress(), data);
+    return result ? decodeString(result) : null;
+}
+export async function readAgentWallet(agentId) {
+    const data = encodeFunctionData({
+        abi: identityRegistryAbi,
+        functionName: "getAgentWallet",
+        args: [agentId],
+    });
+    const result = await ethCall(identityRegistryAddress(), data);
+    const wallet = result ? decodeAddress(result) : null;
+    if (!wallet || wallet === "0x0000000000000000000000000000000000000000")
+        return null;
+    return wallet;
+}
+export async function readBalanceOf(wallet) {
+    const data = encodeFunctionData({
+        abi: identityRegistryAbi,
+        functionName: "balanceOf",
+        args: [wallet],
+    });
+    const result = await ethCall(identityRegistryAddress(), data);
+    return result ? decodeUint256(result) : 0n;
+}
+export async function readReputationSummary(agentId) {
+    const data = encodeFunctionData({
+        abi: reputationRegistryAbi,
+        functionName: "getSummary",
+        args: [agentId, [], "", ""],
+    });
+    const result = await ethCall(reputationRegistryAddress(), data);
+    return result ? decodeSummary(result) : null;
+}
+export function chainMeta() {
+    return {
+        caip2: "eip155:8453",
+        chainId: ERC8004_CHAIN_ID,
+        identityRegistry: identityRegistryAddress(),
+        reputationRegistry: reputationRegistryAddress(),
+    };
+}

package/dist/lib/erc8004/resolve-agent.d.ts

@@ -0,0 +1,7 @@
+import type { Address } from "viem";
+export type AgentResolution = {
+    agentId: bigint | null;
+    source: "body" | "alchemy" | "none";
+    guidance: string | null;
+};
+export declare function resolveAgentId(wallet: Address, agentIdInput?: string | number | bigint): Promise<AgentResolution>;

package/dist/lib/erc8004/resolve-agent.js

@@ -0,0 +1,70 @@
+import { config } from "../../config.js";
+import { identityRegistryAddress, readBalanceOf, readOwnerOf } from "./registry.js";
+async function resolveViaAlchemy(wallet) {
+    const apiKey = config.alchemyApiKey;
+    if (!apiKey)
+        return null;
+    const registry = identityRegistryAddress();
+    const url = new URL(`https://base-mainnet.g.alchemy.com/nft/v3/${apiKey}/getNFTsForOwner`);
+    url.searchParams.set("owner", wallet);
+    url.searchParams.append("contractAddresses[]", registry);
+    url.searchParams.set("withMetadata", "false");
+    const res = await fetch(url.toString(), { signal: AbortSignal.timeout(8000) });
+    if (!res.ok)
+        return null;
+    const json = (await res.json());
+    const first = json.ownedNfts?.[0];
+    if (!first?.tokenId)
+        return null;
+    try {
+        return BigInt(first.tokenId);
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolveAgentId(wallet, agentIdInput) {
+    if (agentIdInput != null && agentIdInput !== "") {
+        try {
+            const agentId = BigInt(agentIdInput);
+            const owner = await readOwnerOf(agentId);
+            if (owner && owner.toLowerCase() === wallet.toLowerCase()) {
+                return { agentId, source: "body", guidance: null };
+            }
+            if (owner) {
+                return {
+                    agentId: null,
+                    source: "body",
+                    guidance: `agentId ${agentId} is owned by ${owner}, not ${wallet}`,
+                };
+            }
+            return {
+                agentId: null,
+                source: "body",
+                guidance: `agentId ${agentId} not found on ERC-8004 IdentityRegistry`,
+            };
+        }
+        catch {
+            return { agentId: null, source: "body", guidance: "Invalid agentId in request body" };
+        }
+    }
+    const balance = await readBalanceOf(wallet);
+    if (balance === 0n) {
+        return {
+            agentId: null,
+            source: "none",
+            guidance: config.alchemyApiKey
+                ? "No ERC-8004 agent NFT found for this wallet on Base mainnet"
+                : "Provide agentId in body or set ALCHEMY_API_KEY for wallet→agentId NFT lookup",
+        };
+    }
+    const fromAlchemy = await resolveViaAlchemy(wallet);
+    if (fromAlchemy != null) {
+        return { agentId: fromAlchemy, source: "alchemy", guidance: null };
+    }
+    return {
+        agentId: null,
+        source: "none",
+        guidance: "Wallet holds ERC-8004 NFT(s) but agentId could not be resolved — pass agentId explicitly or configure ALCHEMY_API_KEY",
+    };
+}

package/dist/lib/erc8004/trust-score.d.ts

@@ -0,0 +1,33 @@
+import { type TrustTier } from "./constants.js";
+import { chainMeta } from "./registry.js";
+export type TrustScoreBreakdown = {
+    onChainRegistration: number;
+    reputation: number;
+    walletVerified: number;
+    agentCard: number;
+    domainWellKnown: number;
+    paymentHistory: number;
+};
+export type TrustScoreResult = {
+    walletAddress: string;
+    agentId: string | null;
+    chain: ReturnType<typeof chainMeta>;
+    trustScore: number;
+    tier: TrustTier;
+    breakdown: TrustScoreBreakdown;
+    registered: boolean;
+    owner: string | null;
+    agentWallet: string | null;
+    agentUri: string | null;
+    reputationCount: number;
+    resolutionSource: "body" | "alchemy" | "none";
+    guidance: string | null;
+    cached: boolean;
+    flags: string[];
+};
+export declare function computeTrustScore(input: {
+    walletAddress: string;
+    agentId?: string | number;
+    skipCache?: boolean;
+}): Promise<TrustScoreResult>;
+export declare function meetsMinTier(current: TrustTier, required: TrustTier): boolean;

package/dist/lib/erc8004/trust-score.js

@@ -0,0 +1,136 @@
+import { config } from "../../config.js";
+import { fetchAgentCard, scoreAgentCard, verifyWellKnown, } from "./agent-card.js";
+import { cacheGet, cacheKey, cacheSet } from "./cache.js";
+import { isEvmAddress, tierForScore, TRUST_SCORE_WEIGHTS, } from "./constants.js";
+import { chainMeta, readAgentWallet, readOwnerOf, readReputationSummary, readTokenUri, } from "./registry.js";
+import { resolveAgentId } from "./resolve-agent.js";
+function reputationPoints(summary) {
+    if (!summary || summary.count === 0n)
+        return 0;
+    const max = TRUST_SCORE_WEIGHTS.reputation;
+    const decimals = summary.summaryValueDecimals;
+    const raw = Number(summary.summaryValue);
+    const normalized = decimals > 0 ? raw / 10 ** decimals : raw;
+    // ERC-8004 feedback is typically 0–100; clamp and scale to 0–25.
+    const clamped = Math.max(0, Math.min(100, normalized));
+    const volumeBoost = summary.count >= 5n ? 1 : Number(summary.count) / 5;
+    return Math.round((clamped / 100) * max * volumeBoost);
+}
+export async function computeTrustScore(input) {
+    const wallet = input.walletAddress.trim();
+    if (!isEvmAddress(wallet)) {
+        return {
+            walletAddress: wallet,
+            agentId: null,
+            chain: chainMeta(),
+            trustScore: 0,
+            tier: "UNKNOWN",
+            breakdown: {
+                onChainRegistration: 0,
+                reputation: 0,
+                walletVerified: 0,
+                agentCard: 0,
+                domainWellKnown: 0,
+                paymentHistory: 0,
+            },
+            registered: false,
+            owner: null,
+            agentWallet: null,
+            agentUri: null,
+            reputationCount: 0,
+            resolutionSource: "none",
+            guidance: "Invalid or missing EVM wallet address",
+            cached: false,
+            flags: ["invalid_wallet"],
+        };
+    }
+    const ttl = config.trustScoreCacheTtlSec;
+    const key = cacheKey(["trustscore", wallet.toLowerCase(), input.agentId ?? ""]);
+    if (!input.skipCache) {
+        const hit = cacheGet(key);
+        if (hit)
+            return { ...hit, cached: true };
+    }
+    const flags = [];
+    const resolved = await resolveAgentId(wallet, input.agentId);
+    const agentId = resolved.agentId;
+    let onChainRegistration = 0;
+    let owner = null;
+    let agentWallet = null;
+    let agentUri = null;
+    let reputationCount = 0;
+    let reputation = 0;
+    let walletVerified = 0;
+    let agentCardPts = 0;
+    let domainPts = 0;
+    if (agentId != null) {
+        onChainRegistration = TRUST_SCORE_WEIGHTS.onChainRegistration;
+        owner = (await readOwnerOf(agentId)) ?? null;
+        if (owner && owner.toLowerCase() !== wallet.toLowerCase()) {
+            flags.push("wallet_not_owner");
+            onChainRegistration = Math.round(TRUST_SCORE_WEIGHTS.onChainRegistration * 0.5);
+        }
+        const verifiedWallet = await readAgentWallet(agentId);
+        agentWallet = verifiedWallet;
+        if (verifiedWallet &&
+            verifiedWallet.toLowerCase() === wallet.toLowerCase()) {
+            walletVerified = TRUST_SCORE_WEIGHTS.walletVerified;
+        }
+        const rep = await readReputationSummary(agentId);
+        reputationCount = rep ? Number(rep.count) : 0;
+        reputation = reputationPoints(rep);
+        agentUri = await readTokenUri(agentId);
+        if (agentUri) {
+            const card = await fetchAgentCard(agentUri);
+            const cardScore = scoreAgentCard(card, agentUri);
+            agentCardPts = cardScore.points;
+            if (!cardScore.valid)
+                flags.push("incomplete_agent_card");
+            const wellKnown = await verifyWellKnown(cardScore.domain);
+            domainPts = wellKnown.points;
+            if (!wellKnown.verified && cardScore.domain)
+                flags.push("domain_not_verified");
+        }
+        else {
+            flags.push("missing_agent_uri");
+        }
+    }
+    else if (resolved.guidance) {
+        flags.push("unregistered");
+    }
+    // Phase 2 — payment history from Trust Layer ledger (stub 0).
+    const paymentHistory = 0;
+    const breakdown = {
+        onChainRegistration,
+        reputation,
+        walletVerified,
+        agentCard: agentCardPts,
+        domainWellKnown: domainPts,
+        paymentHistory,
+    };
+    const trustScore = Object.values(breakdown).reduce((a, b) => a + b, 0);
+    const tier = tierForScore(trustScore);
+    const result = {
+        walletAddress: wallet,
+        agentId: agentId != null ? agentId.toString() : null,
+        chain: chainMeta(),
+        trustScore,
+        tier,
+        breakdown,
+        registered: agentId != null,
+        owner,
+        agentWallet,
+        agentUri,
+        reputationCount,
+        resolutionSource: resolved.source,
+        guidance: resolved.guidance,
+        cached: false,
+        flags,
+    };
+    cacheSet(key, result, ttl);
+    return result;
+}
+export function meetsMinTier(current, required) {
+    const order = ["PLATINUM", "GOLD", "SILVER", "BRONZE", "UNVERIFIED", "UNKNOWN"];
+    return order.indexOf(current) <= order.indexOf(required);
+}

package/dist/lib/escrow-ledger.d.ts

@@ -0,0 +1,14 @@
+export type EscrowRecord = {
+    id: string;
+    payerAgentId: string;
+    payeeAgentId: string;
+    amountUsdc: number;
+    status: "pending" | "released" | "cancelled";
+    releaseCondition: string;
+    createdAt: string;
+    releasedAt: string | null;
+    metadata?: Record<string, unknown>;
+};
+export declare function createEscrow(input: Omit<EscrowRecord, "id" | "status" | "createdAt" | "releasedAt">): Promise<EscrowRecord>;
+export declare function getEscrow(id: string): Promise<EscrowRecord | null>;
+export declare function releaseEscrow(id: string): Promise<EscrowRecord | null>;

package/dist/lib/escrow-ledger.js

@@ -0,0 +1,54 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { getEscrowFromDb, saveEscrowToDb, } from "./db-persistence.js";
+import { syncLedgerEscrow } from "./escrow-unified.js";
+const DATA_DIR = path.join(process.cwd(), "data");
+async function readStore() {
+    await mkdir(DATA_DIR, { recursive: true });
+    const file = path.join(DATA_DIR, "escrow-ledger.json");
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+async function writeStore(store) {
+    const file = path.join(DATA_DIR, "escrow-ledger.json");
+    await writeFile(file, JSON.stringify(store, null, 2), "utf8");
+}
+export async function createEscrow(input) {
+    const store = await readStore();
+    const record = {
+        ...input,
+        id: randomUUID(),
+        status: "pending",
+        createdAt: new Date().toISOString(),
+        releasedAt: null,
+    };
+    store[record.id] = record;
+    await writeStore(store);
+    saveEscrowToDb(record);
+    syncLedgerEscrow(record);
+    return record;
+}
+export async function getEscrow(id) {
+    const fromDb = getEscrowFromDb(id);
+    if (fromDb)
+        return fromDb;
+    const store = await readStore();
+    return store[id] ?? null;
+}
+export async function releaseEscrow(id) {
+    const store = await readStore();
+    const record = store[id];
+    if (!record || record.status !== "pending")
+        return null;
+    record.status = "released";
+    record.releasedAt = new Date().toISOString();
+    await writeStore(store);
+    saveEscrowToDb(record);
+    syncLedgerEscrow(record);
+    return record;
+}

package/dist/lib/escrow-unified.d.ts

@@ -0,0 +1,15 @@
+import type { EscrowState } from "../protocol/escrow-fsm.js";
+import type { EscrowRecord } from "./escrow-ledger.js";
+export declare function syncProtocolEscrow(input: {
+    escrowId: string;
+    payerAgentId: string;
+    payeeId: string;
+    amountUsdc: number;
+    state: EscrowState | string;
+    resourceHash?: string;
+    sessionId?: string;
+    stateProof: string;
+    metadata?: Record<string, unknown>;
+}): void;
+export declare function recordEscrowTransition(escrowId: string, fromState: string, toState: string, note?: string, proof?: string): void;
+export declare function syncLedgerEscrow(record: EscrowRecord): void;

package/dist/lib/escrow-unified.js

@@ -0,0 +1,28 @@
+import { db } from "./db.js";
+const upsertEscrow = db.prepare(`
+  INSERT INTO escrows (
+    escrow_id, payer_agent_id, payee_id, amount_usdc, state,
+    resource_hash, session_id, release_condition, quality_score,
+    state_proof, metadata, updated_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, unixepoch())
+  ON CONFLICT(escrow_id) DO UPDATE SET
+    state = excluded.state,
+    state_proof = excluded.state_proof,
+    metadata = excluded.metadata,
+    updated_at = unixepoch(),
+    settled_at = CASE WHEN excluded.state = 'SETTLED' THEN unixepoch() ELSE settled_at END
+`);
+const insertTransition = db.prepare(`
+  INSERT INTO escrow_transitions (escrow_id, from_state, to_state, note, proof)
+  VALUES (?, ?, ?, ?, ?)
+`);
+export function syncProtocolEscrow(input) {
+    upsertEscrow.run(input.escrowId, input.payerAgentId, input.payeeId, input.amountUsdc, input.state, input.resourceHash ?? null, input.sessionId ?? null, null, null, input.stateProof, input.metadata ? JSON.stringify(input.metadata) : null);
+}
+export function recordEscrowTransition(escrowId, fromState, toState, note, proof) {
+    insertTransition.run(escrowId, fromState, toState, note ?? null, proof ?? null);
+}
+export function syncLedgerEscrow(record) {
+    const state = record.status === "released" ? "SETTLED" : record.status === "cancelled" ? "CANCELLED" : "LOCKED";
+    upsertEscrow.run(record.id, record.payerAgentId, record.payeeAgentId, record.amountUsdc, state, null, null, record.releaseCondition, null, `ledger:${record.status}`, JSON.stringify(record.metadata ?? {}));
+}

package/dist/lib/facilitator-extra.d.ts

@@ -0,0 +1,13 @@
+/** Load facilitator /supported extras (permit2 on Base, feePayer on Solana, etc.). */
+export declare function refreshFacilitatorExtras(facilitatorUrl?: string): Promise<void>;
+export declare function ensureFacilitatorExtras(): Promise<void>;
+/**
+ * Merge facilitator extras into 402 accepts so EVM clients use Permit2 on Base
+ * (Dexter facilitator returns 500 if payer signs EIP-712 but settle expects permit2).
+ */
+export declare function enrichAcceptFromFacilitator(accept: {
+    network?: string;
+    scheme?: string;
+    extra?: Record<string, unknown>;
+}): void;
+export declare function startFacilitatorExtrasRefresh(intervalMs?: number): void;

package/dist/lib/facilitator-extra.js

@@ -0,0 +1,52 @@
+import { config } from "../config.js";
+let extrasByNetworkScheme = new Map();
+let cacheLoadedAt = 0;
+const CACHE_TTL_MS = 60_000;
+function cacheKey(network, scheme) {
+    return `${network}|${scheme}`;
+}
+/** Load facilitator /supported extras (permit2 on Base, feePayer on Solana, etc.). */
+export async function refreshFacilitatorExtras(facilitatorUrl = config.facilitatorUrl) {
+    const base = facilitatorUrl.replace(/\/$/, "");
+    const res = await fetch(`${base}/supported`, {
+        signal: AbortSignal.timeout(Number(process.env.X402_FACILITATOR_TIMEOUT_MS ?? 90_000)),
+    });
+    if (!res.ok) {
+        throw new Error(`Facilitator /supported HTTP ${res.status}`);
+    }
+    const body = (await res.json());
+    const next = new Map();
+    for (const kind of body.kinds ?? []) {
+        if (kind.extra && kind.network && kind.scheme) {
+            next.set(cacheKey(kind.network, kind.scheme), kind.extra);
+        }
+    }
+    extrasByNetworkScheme = next;
+    cacheLoadedAt = Date.now();
+}
+export async function ensureFacilitatorExtras() {
+    if (Date.now() - cacheLoadedAt < CACHE_TTL_MS && extrasByNetworkScheme.size > 0)
+        return;
+    await refreshFacilitatorExtras();
+}
+/**
+ * Merge facilitator extras into 402 accepts so EVM clients use Permit2 on Base
+ * (Dexter facilitator returns 500 if payer signs EIP-712 but settle expects permit2).
+ */
+export function enrichAcceptFromFacilitator(accept) {
+    if (!accept.network)
+        return;
+    const scheme = accept.scheme ?? "exact";
+    const facilitatorExtra = extrasByNetworkScheme.get(cacheKey(accept.network, scheme));
+    if (!facilitatorExtra)
+        return;
+    accept.extra = { ...facilitatorExtra, ...accept.extra };
+}
+export function startFacilitatorExtrasRefresh(intervalMs = CACHE_TTL_MS) {
+    const tick = () => {
+        void refreshFacilitatorExtras().catch((err) => {
+            console.warn("[facilitator-extra] refresh failed:", err instanceof Error ? err.message : err);
+        });
+    };
+    setInterval(tick, intervalMs).unref?.();
+}

package/dist/lib/facilitators.d.ts

@@ -0,0 +1,20 @@
+export type FacilitatorHealth = {
+    id: string;
+    url: string;
+    healthy: boolean;
+    latencyMs: number | null;
+    supportedNetworks: string[];
+    error: string | null;
+    synthetic?: boolean;
+    note?: string;
+};
+declare const FACILITATORS: readonly [{
+    readonly id: "dexter";
+    readonly url: "https://x402.dexter.cash";
+}, {
+    readonly id: "coinbase";
+    readonly url: "https://api.cdp.coinbase.com/platform/v2/x402";
+}];
+export declare function checkFacilitatorHealth(facilitator: (typeof FACILITATORS)[number]): Promise<FacilitatorHealth>;
+export declare function rankFacilitators(preferNetwork?: string, fastCheck?: boolean): Promise<FacilitatorHealth[]>;
+export {};