@x1id/resolve 0.23.0 → 0.43.0

package/dist/x402Receipt.js

@@ -0,0 +1,374 @@
+/**
+ * x402 payment receipts on chain (#8324, wired by [Pay 10] / WP 8833):
+ * `record_x402_receipt`, its `X402ReceiptRecorded` event and the per-handle
+ * `AgentPaymentStats` tally.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. The builder returns the transport-neutral
+ * {@link BuiltInstruction} (`delegate.ts` has the two-line web3.js adapter).
+ *
+ * # What a receipt proves (and what it does not)
+ *
+ * The instruction is ATTESTOR-SIGNED (`has_one = attestor` on
+ * `["attestor_config"]`). The program does NOT look at the payment itself: it
+ * does not introspect the Instructions sysvar, does not read `settled_sig`'s
+ * transaction, and does not check `amount` / `mint` against anything. A
+ * receipt therefore proves exactly one thing — "the configured attestor key
+ * stamped this payment" — and the attestor is trusted to have confirmed the
+ * settlement off chain first (`docs/x402-receipts.md`, option B). The
+ * `settled_sig` it carries is the audit anchor: anyone can fetch that
+ * transaction and check it. Never present a receipt as more than that.
+ *
+ * Both handles must be live `Handle` accounts and must differ
+ * (`X402SelfReceipt`, 6085). A scoped handle (`["handle", [len], label,
+ * name]`) needs its `["namespace", label]` account in `namespaces` (the
+ * program scans remaining accounts for it); a bare handle needs nothing.
+ *
+ * Cost: the attestor is the fee payer and pays the rent of each
+ * `AgentPaymentStats` account the first time a handle is touched (81 bytes
+ * each). On X1 the fee is 10 lamports per REQUESTED compute unit plus 1,500
+ * per signature, so always set a compute-unit limit: simulate and use
+ * {@link x402ReceiptCuLimitFromSimulation}, or fall back to
+ * {@link RECORD_X402_RECEIPT_CU_LIMIT}.
+ */
+import { decodeBase58, decodeBase58_32, encodeBase58 } from "./base58.js";
+import { sha256 } from "./sha256.js";
+/** Anchor instruction discriminator: `sha256("global:record_x402_receipt")[0..8]`. */
+export const RECORD_X402_RECEIPT_DISCRIMINATOR = Uint8Array.from([196, 39, 64, 88, 117, 200, 163, 232]);
+/** Anchor event discriminator: `sha256("event:X402ReceiptRecorded")[0..8]`.
+ *  An emitted event is logged as `Program data: <base64(disc ‖ borsh)>`. */
+export const X402_RECEIPT_RECORDED_EVENT_DISCRIMINATOR = Uint8Array.from([37, 68, 174, 195, 241, 126, 162, 223]);
+/** Anchor account discriminator: `sha256("account:AgentPaymentStats")[0..8]`. */
+export const AGENT_PAYMENT_STATS_DISCRIMINATOR = Uint8Array.from([80, 161, 55, 40, 220, 73, 56, 65]);
+/** Seed prefix of the stats PDA: `["x402_stats", handleAccount]`. */
+export const AGENT_PAYMENT_STATS_SEED = "x402_stats";
+/** `AgentPaymentStats` size: disc(8) + handle(32) + 4×u64(32) + last_at(8) + bump(1). */
+export const AGENT_PAYMENT_STATS_LEN = 81;
+/** `X402ReceiptRecorded` encoded size: disc(8) + payer(32) + payee(32) +
+ *  amount(8) + mint(32) + resource_hash(32) + settled_sig(64) + timestamp(8). */
+export const X402_RECEIPT_EVENT_LEN = 216;
+/** `record_x402_receipt` instruction data size: disc + amount + mint +
+ *  resource_hash + settled_sig. */
+export const RECORD_X402_RECEIPT_DATA_LEN = 8 + 8 + 32 + 32 + 64;
+/** `X402SelfReceipt`: payer and payee handle are the same account. */
+export const X402_SELF_RECEIPT_ERROR = 6085;
+/**
+ * Static compute-unit CEILING for a transaction carrying ONE
+ * `record_x402_receipt` (plus its compute-budget instruction), for callers
+ * that cannot simulate first. Measured in litesvm against the built program
+ * (programs/x1-handles/tests/x402_receipt_sdk_e2e.rs): ~40.0k CU when both
+ * stats accounts are created (first touch), ~28.7k CU after, with stats-PDA
+ * bumps 255/254. The cost is not constant: Anchor re-derives each stats PDA
+ * with `find_program_address` on every call, so a handle whose stats bump is
+ * lower costs ~1.5k CU more per step below 255. X1 charges the REQUESTED
+ * limit (10 lamports per CU), so the better practice — what dev-api does — is
+ * to simulate and request {@link x402ReceiptCuLimitFromSimulation} of the
+ * measured units, using this only as the fallback / upper bound.
+ */
+export const RECORD_X402_RECEIPT_CU_LIMIT = 60_000;
+/** A tight limit from a simulation's `unitsConsumed`: +10% (at least 2,000
+ *  CU), rounded up to a thousand, never above `ceiling`. */
+export function x402ReceiptCuLimitFromSimulation(unitsConsumed, ceiling = RECORD_X402_RECEIPT_CU_LIMIT * 2) {
+    if (!Number.isFinite(unitsConsumed) || unitsConsumed <= 0)
+        return Math.min(RECORD_X402_RECEIPT_CU_LIMIT, ceiling);
+    const padded = unitsConsumed + Math.max(2_000, Math.ceil(unitsConsumed * 0.1));
+    return Math.min(Math.ceil(padded / 1_000) * 1_000, ceiling);
+}
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const TE = new TextEncoder();
+const U64_MAX = 0xffffffffffffffffn;
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+/** A transaction signature as its 64 raw bytes (from base58 or bytes). */
+export function x402SettledSigBytes(sig) {
+    if (typeof sig !== "string") {
+        if (sig.length !== 64)
+            throw new Error("settledSig must be exactly 64 bytes");
+        return sig;
+    }
+    const b = decodeSig(sig);
+    if (!b)
+        throw new Error("settledSig is not a base58 64-byte transaction signature");
+    return b;
+}
+function decodeSig(s) {
+    if (!/^[1-9A-HJ-NP-Za-km-z]{64,88}$/.test(s))
+        return null;
+    return decodeBase58(s, 64);
+}
+/**
+ * The `resource_hash` x1id stamps: sha256 of the x402 `resource` URL the
+ * payment bought, e.g. `https://api.x1id.io/v1/resolve`. The ENDPOINT, not the
+ * exact request — a receipt is public forever, and hashing the full request
+ * (`/v1/resolve/alice`) would let anyone brute-force what an agent looked up.
+ */
+export function x402ResourceHash(resource) {
+    if (typeof resource !== "string" || resource.length === 0)
+        throw new Error("resource must be a non-empty string");
+    return sha256(TE.encode(resource));
+}
+/** `["x402_stats", handleAccount]` — the second seed is the 32 raw bytes of
+ *  the Handle ACCOUNT address. */
+export async function findAgentPaymentStatsPda(find, programId, handle) {
+    return find([TE.encode(AGENT_PAYMENT_STATS_SEED), toBytes32(handle, "handle")], toBase58(programId, "programId"));
+}
+/** Borsh args after the discriminator: amount u64, mint, resource_hash[32], settled_sig[64]. */
+export function encodeRecordX402ReceiptArgs(a) {
+    if (typeof a.amount !== "bigint" || a.amount < 0n || a.amount > U64_MAX)
+        throw new Error("amount must be a u64 bigint");
+    if (!(a.resourceHash instanceof Uint8Array) || a.resourceHash.length !== 32)
+        throw new Error("resourceHash must be exactly 32 bytes");
+    const out = new Uint8Array(RECORD_X402_RECEIPT_DATA_LEN);
+    out.set(RECORD_X402_RECEIPT_DISCRIMINATOR, 0);
+    new DataView(out.buffer).setBigUint64(8, a.amount, true);
+    out.set(toBytes32(a.mint, "mint"), 16);
+    out.set(a.resourceHash, 48);
+    out.set(x402SettledSigBytes(a.settledSig), 80);
+    return out;
+}
+/**
+ * Build `record_x402_receipt`. Accounts in `RecordX402Receipt` order:
+ * attestor(s,w) attestor_config payer_handle payee_handle payer_stats(w)
+ * payee_stats(w) system_program, then any namespace accounts.
+ */
+export function buildRecordX402ReceiptIx(p) {
+    const payerHandle = toBase58(p.payerHandle, "payerHandle");
+    const payeeHandle = toBase58(p.payeeHandle, "payeeHandle");
+    if (payerHandle === payeeHandle)
+        throw new Error("payerHandle and payeeHandle must differ (X402SelfReceipt)");
+    const data = encodeRecordX402ReceiptArgs(p);
+    const keys = [
+        { pubkey: toBase58(p.attestor, "attestor"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.attestorConfig, "attestorConfig"), isSigner: false, isWritable: false },
+        { pubkey: payerHandle, isSigner: false, isWritable: false },
+        { pubkey: payeeHandle, isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.payerStats, "payerStats"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.payeeStats, "payeeStats"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    for (const [i, ns] of (p.namespaces ?? []).entries()) {
+        keys.push({ pubkey: toBase58(ns, `namespaces[${i}]`), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+function eq(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/** Decode one event payload (the bytes of a `Program data:` line). null when
+ *  it is not an `X402ReceiptRecorded`. */
+export function decodeX402ReceiptRecorded(raw) {
+    if (raw.length !== X402_RECEIPT_EVENT_LEN || !eq(raw.subarray(0, 8), X402_RECEIPT_RECORDED_EVENT_DISCRIMINATOR))
+        return null;
+    const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    return {
+        payerHandle: encodeBase58(raw.slice(8, 40)),
+        payeeHandle: encodeBase58(raw.slice(40, 72)),
+        amount: dv.getBigUint64(72, true),
+        mint: encodeBase58(raw.slice(80, 112)),
+        resourceHash: raw.slice(112, 144),
+        settledSig: encodeBase58(raw.slice(144, 208)),
+        timestamp: dv.getBigInt64(208, true),
+    };
+}
+/** Encode an event the way the program emits it (tests / fixtures). */
+export function encodeX402ReceiptRecorded(e) {
+    const out = new Uint8Array(X402_RECEIPT_EVENT_LEN);
+    const dv = new DataView(out.buffer);
+    out.set(X402_RECEIPT_RECORDED_EVENT_DISCRIMINATOR, 0);
+    out.set(toBytes32(e.payerHandle, "payerHandle"), 8);
+    out.set(toBytes32(e.payeeHandle, "payeeHandle"), 40);
+    dv.setBigUint64(72, e.amount, true);
+    out.set(toBytes32(e.mint, "mint"), 80);
+    if (e.resourceHash.length !== 32)
+        throw new Error("resourceHash must be exactly 32 bytes");
+    out.set(e.resourceHash, 112);
+    out.set(x402SettledSigBytes(e.settledSig), 144);
+    dv.setBigInt64(208, e.timestamp, true);
+    return out;
+}
+function b64decode(s) {
+    try {
+        return Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Every `X402ReceiptRecorded` among a transaction's log lines, attributed to
+ * `programId`'s OWN invoke frames only (a look-alike `Program data:` line
+ * printed by another program is ignored).
+ */
+export function parseX402ReceiptEvents(logs, programId) {
+    const pid = toBase58(programId, "programId");
+    const stack = [];
+    const out = [];
+    for (const line of logs) {
+        const inv = /^Program (\S+) invoke \[\d+\]$/.exec(line);
+        if (inv) {
+            stack.push(inv[1]);
+            continue;
+        }
+        if (/^Program \S+ (success|failed: )/.test(line)) {
+            stack.pop();
+            continue;
+        }
+        if (line.startsWith("Program data: ") && stack[stack.length - 1] === pid) {
+            const raw = b64decode(line.slice("Program data: ".length).trim());
+            const ev = raw ? decodeX402ReceiptRecorded(raw) : null;
+            if (ev)
+                out.push(ev);
+        }
+    }
+    return out;
+}
+/** Decode an `AgentPaymentStats` account (discriminator + exact length
+ *  checked); null for anything else. */
+export function decodeAgentPaymentStats(raw) {
+    if (raw.length !== AGENT_PAYMENT_STATS_LEN || !eq(raw.subarray(0, 8), AGENT_PAYMENT_STATS_DISCRIMINATOR))
+        return null;
+    const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    return {
+        handle: encodeBase58(raw.slice(8, 40)),
+        paymentsMadeCount: dv.getBigUint64(40, true),
+        totalPaid: dv.getBigUint64(48, true),
+        paymentsReceivedCount: dv.getBigUint64(56, true),
+        totalReceived: dv.getBigUint64(64, true),
+        lastAt: dv.getBigInt64(72, true),
+        bump: raw[80],
+    };
+}
+/** Encode an `AgentPaymentStats` account (tests / fixtures). */
+export function encodeAgentPaymentStats(s) {
+    const out = new Uint8Array(AGENT_PAYMENT_STATS_LEN);
+    const dv = new DataView(out.buffer);
+    out.set(AGENT_PAYMENT_STATS_DISCRIMINATOR, 0);
+    out.set(toBytes32(s.handle, "handle"), 8);
+    dv.setBigUint64(40, s.paymentsMadeCount, true);
+    dv.setBigUint64(48, s.totalPaid, true);
+    dv.setBigUint64(56, s.paymentsReceivedCount, true);
+    dv.setBigUint64(64, s.totalReceived, true);
+    dv.setBigInt64(72, s.lastAt, true);
+    out[80] = s.bump;
+    return out;
+}
+/** Fee (lamports) of one receipt transaction on X1: 10 lamports per
+ *  requested CU + 1,500 per signature (rent of new stats accounts excluded). */
+export function x402ReceiptTxFeeLamports(cuLimit = RECORD_X402_RECEIPT_CU_LIMIT, signatures = 1) {
+    return cuLimit * 10 + 1_500 * signatures;
+}
+// ===================== dedicated receipt signer (upgrade 5) =====================
+//
+// `record_x402_receipt_v2` (signed by the dedicated receipt signer OR the
+// attestor) and the admin's `set_receipt_signer`. Both are routed through the
+// program's `fallback` (`extra_ix`) and need the registry upgrade that adds
+// them (until then: `InstructionFallbackNotFound`, 101). v1
+// ({@link buildRecordX402ReceiptIx}) is unchanged and stays attestor-only.
+// docs/x402-receipts.md "Dedicated receipt signer (upgrade 5)".
+/** Seed of the receipt-signer singleton: `["receipt_signer_config"]`. */
+export const RECEIPT_SIGNER_CONFIG_SEED = "receipt_signer_config";
+/** Seed of a handle's O(1) payment tally (alias of {@link AGENT_PAYMENT_STATS_SEED}). */
+export const X402_STATS_SEED = AGENT_PAYMENT_STATS_SEED;
+/** `sha256("global:record_x402_receipt_v2")[..8]`. */
+export const RECORD_X402_RECEIPT_V2_DISCRIMINATOR = Uint8Array.from([99, 60, 56, 81, 186, 214, 82, 72]);
+/** `sha256("global:set_receipt_signer")[..8]`. */
+export const SET_RECEIPT_SIGNER_DISCRIMINATOR = Uint8Array.from([40, 114, 51, 32, 33, 184, 70, 80]);
+/** `sha256("account:ReceiptSignerConfig")[..8]`. */
+export const RECEIPT_SIGNER_CONFIG_DISCRIMINATOR = Uint8Array.from([154, 248, 63, 199, 144, 203, 157, 2]);
+/** `RegistryError::NotReceiptSigner`: v2 signed by neither role. */
+export const X402_NOT_RECEIPT_SIGNER_ERROR = 6157;
+/** `RegistryError::X402ReceiptPayerIsSigner`: v2 with `payer == signer`
+ *  (Sentinel run-011: the X1ID receipt key never pays). */
+export const X402_RECEIPT_PAYER_IS_SIGNER_ERROR = 6232;
+/** `["receipt_signer_config"]`. */
+export async function findReceiptSignerConfigPda(find, programId) {
+    return find([TE.encode(RECEIPT_SIGNER_CONFIG_SEED)], toBase58(programId, "programId"));
+}
+/** `["x402_stats", handle]` (alias of {@link findAgentPaymentStatsPda}). */
+export async function findX402StatsPda(find, programId, handle) {
+    return findAgentPaymentStatsPda(find, programId, handle);
+}
+/** Decode a `ReceiptSignerConfig` (`signer` base58; the default key
+ *  `11111111111111111111111111111111` means the role is disabled). */
+export function decodeReceiptSignerConfig(data) {
+    if (data.length < 8 + 32 + 1)
+        return null;
+    for (let i = 0; i < 8; i++)
+        if (data[i] !== RECEIPT_SIGNER_CONFIG_DISCRIMINATOR[i])
+            return null;
+    return { signer: encodeBase58(data.slice(8, 40)), bump: data[40] };
+}
+/**
+ * Build `record_x402_receipt_v2`: the same args as v1. Accounts
+ * (`RecordX402ReceiptV2`): signer(s), payer(s,w), attestor_config,
+ * receipt_signer_config, payer_handle, payee_handle, payer_stats(w),
+ * payee_stats(w), system_program, then any namespaces. Make `payer` the
+ * transaction fee payer so the receipt signer's key holds no XNT. Throws when
+ * `payer` is missing or equals `signer`.
+ */
+export function buildRecordX402ReceiptV2Ix(p) {
+    if (p.receiptSignerConfig === undefined)
+        throw new Error("receiptSignerConfig is required for v2");
+    if (p.payer === undefined || p.payer === null) {
+        throw new Error("payer is required for v2 (the receipt signer only co-signs; X1ID pays nothing)");
+    }
+    const signer = toBase58(p.signer, "signer");
+    const payer = toBase58(p.payer, "payer");
+    if (payer === signer)
+        throw new Error("payer must differ from signer (X402ReceiptPayerIsSigner)");
+    const payerHandle = toBase58(p.payerHandle, "payerHandle");
+    const payeeHandle = toBase58(p.payeeHandle, "payeeHandle");
+    if (payerHandle === payeeHandle)
+        throw new Error("payerHandle and payeeHandle must differ (X402SelfReceipt)");
+    const data = encodeRecordX402ReceiptArgs(p);
+    data.set(RECORD_X402_RECEIPT_V2_DISCRIMINATOR, 0);
+    const keys = [
+        { pubkey: signer, isSigner: true, isWritable: false },
+        { pubkey: payer, isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.attestorConfig, "attestorConfig"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.receiptSignerConfig, "receiptSignerConfig"), isSigner: false, isWritable: false },
+        { pubkey: payerHandle, isSigner: false, isWritable: false },
+        { pubkey: payeeHandle, isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.payerStats, "payerStats"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.payeeStats, "payeeStats"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    for (const [i, ns] of (p.namespaces ?? []).entries()) {
+        keys.push({ pubkey: toBase58(ns, `namespaces[${i}]`), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/** `set_receipt_signer(signer)`. Accounts (`SetReceiptSigner`): admin(s,w),
+ *  config, receipt_signer_config(w), system_program. */
+export function buildSetReceiptSignerIx(p) {
+    const data = new Uint8Array(40);
+    data.set(SET_RECEIPT_SIGNER_DISCRIMINATOR, 0);
+    data.set(toBytes32(p.signer, "signer"), 8);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: true },
+            { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+            { pubkey: toBase58(p.receiptSignerConfig, "receiptSignerConfig"), isSigner: false, isWritable: true },
+            { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+        ],
+        data,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.23.0",
+  "version": "0.43.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,18 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./messaging": {
+      "types": "./dist/messaging.d.ts",
+      "default": "./dist/messaging.js"
+    },
+    "./oidc": {
+      "types": "./dist/oidc.d.ts",
+      "default": "./dist/oidc.js"
+    },
+    "./login-button": {
+      "types": "./dist/loginButton.d.ts",
+      "default": "./dist/loginButton.js"
+    },
     "./wasm/x1_resolve_wasm.wasm": "./wasm/x1_resolve_wasm.wasm",
     "./wasm/*": "./wasm/*",
     "./package.json": "./package.json"
@@ -47,6 +59,11 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "@noble/ciphers": "^1.3.0",
+    "@noble/curves": "^1.8.0",
+    "@noble/hashes": "^1.4.0"
+  },
   "devDependencies": {
     "typescript": "^5.6.0",
     "@types/node": "^22.0.0",

package/schema/agent-manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://x1id.io/schema/agent-manifest.json",
   "title": "x1id agent manifest",
-  "description": "A machine-readable description of an @handle operating as an AI agent — what it does, how to reach it, and how to pay it. Nothing here is a payment fact: payment.addresses[] is a mirror of the on-chain address Record(s) and payment.x402 is a pre-flight hint; the chain and the live 402 response always win. See docs/agent-records.md.",
+  "description": "A machine-readable description of an @handle operating as an AI agent — what it does, how to reach it, and how to pay it. Versions 1 and 2 are both valid; v2 adds per-capability / per-endpoint pricing, accepted payment methods and a name-bound payTo. Nothing here is a payment fact: v2's payment.payTo names an @name whose address is resolved from the chain (the W16 / name_pays_to rule), payment.addresses[] is a mirror of the on-chain address Record(s), and payment.x402 is a pre-flight hint; the chain and the live 402 response always win. See docs/agent-records.md. The SDK's validateManifest additionally checks cross-references (endpoint/capability ids), that x1id.name/handle/network match the handle being read, that payTo.name equals x1id.name, and that every priced mint is settled by a listed method.",
   "type": "object",
   "additionalProperties": false,
   "required": ["x1id"],
@@ -12,17 +12,17 @@
       "additionalProperties": false,
       "required": ["version", "name", "network", "handle"],
       "properties": {
-        "version": { "const": 1 },
+        "version": { "enum": [1, 2] },
         "name": { "type": "string", "minLength": 1, "maxLength": 260, "description": "The canonical @handle name, without the @." },
         "network": { "type": "string", "enum": ["testnet", "mainnet"] },
-        "handle": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The Handle PDA account address, base58 — the uniqueness anchor. A manifest served for the wrong name/handle is discarded on read." }
+        "handle": { "$ref": "#/$defs/Base58", "description": "The Handle PDA account address, base58 — the uniqueness anchor. A manifest served for the wrong name/handle is discarded on read." }
       }
     },
     "identity": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "attestation": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Base58 address of a non-stale Attestation account on this handle (kind DNS or SOCIAL). See docs/agent-records.md §4 for what L1 does and does not prove." },
+        "attestation": { "$ref": "#/$defs/Base58", "description": "Base58 address of a non-stale Attestation account on this handle (kind DNS or SOCIAL). See docs/agent-records.md §4 for what L1 does and does not prove." },
         "description": { "type": "string", "maxLength": 2048 }
       }
     },
@@ -34,24 +34,69 @@
         "additionalProperties": false,
         "required": ["type", "url"],
         "properties": {
+          "id": { "$ref": "#/$defs/Id", "description": "v2: stable id referenced from capabilities.items[].endpoint." },
           "type": { "type": "string", "enum": ["x402", "mcp", "a2a", "http"] },
-          "url": { "$ref": "#/$defs/HttpsUrl" }
+          "url": { "$ref": "#/$defs/HttpsUrl" },
+          "capabilities": { "type": "array", "maxItems": 64, "items": { "$ref": "#/$defs/Id" }, "description": "v2: capability ids served here." },
+          "pricing": { "$ref": "#/$defs/Pricing", "description": "v2: this endpoint's own price(s)." }
         }
       }
     },
     "capabilities": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["url"],
       "properties": {
         "schema": { "$ref": "#/$defs/HttpsUrl" },
-        "url": { "$ref": "#/$defs/HttpsUrl" }
+        "url": { "$ref": "#/$defs/HttpsUrl" },
+        "items": {
+          "type": "array",
+          "maxItems": 64,
+          "description": "v2: the searchable capability list (the directory indexes items[].id).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id"],
+            "properties": {
+              "id": { "$ref": "#/$defs/Id" },
+              "description": { "type": "string", "maxLength": 512 },
+              "endpoint": { "$ref": "#/$defs/Id" },
+              "pricing": { "$ref": "#/$defs/Pricing" }
+            }
+          }
+        }
       }
     },
     "payment": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "payTo": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name"],
+          "description": "v2: WHO gets paid — an @name (must equal x1id.name), never an address. Readers resolve the address from the chain under the W16 rule (live verified record for the method's chain, else the name's current authority on SVM chains). Required whenever anything is priced.",
+          "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 261 } }
+        },
+        "methods": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "description": "v2: accepted payment methods. Required whenever anything is priced.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["type", "rail", "network"],
+            "properties": {
+              "id": { "$ref": "#/$defs/Id" },
+              "type": { "const": "x402" },
+              "rail": { "enum": ["x1", "cdp"], "description": "x1 = the X1-native x402 rail (self-sponsored, settled on X1); cdp = the Coinbase CDP facilitator rail." },
+              "network": { "type": "string", "pattern": "^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,64}$", "description": "CAIP-2. For rail x1 it must be the X1 network id of x1id.network (solana:C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWw testnet, solana:4SvBP3omtvcCVWdxq1zBY5cDp4wndjsT mainnet)." },
+              "scheme": { "const": "exact" },
+              "facilitator": { "$ref": "#/$defs/HttpsUrl" },
+              "assets": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/$defs/Mint" } }
+            }
+          }
+        },
         "addresses": {
           "type": "array",
           "maxItems": 16,
@@ -81,11 +126,49 @@
       }
     }
   },
+  "allOf": [
+    {
+      "if": { "properties": { "x1id": { "properties": { "version": { "const": 1 } } } } },
+      "then": {
+        "properties": {
+          "capabilities": { "required": ["url"], "properties": { "items": false } },
+          "endpoints": { "items": { "properties": { "id": false, "capabilities": false, "pricing": false } } },
+          "payment": { "properties": { "payTo": false, "methods": false } }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "x1id": { "properties": { "version": { "const": 2 } } } } },
+      "then": {
+        "properties": {
+          "capabilities": { "anyOf": [{ "required": ["url"] }, { "required": ["items"] }] }
+        }
+      }
+    }
+  ],
   "$defs": {
     "HttpsUrl": {
       "type": "string",
       "pattern": "^https://[^\\s@/]+(/[^\\s]*)?$",
       "maxLength": 2048
-    }
+    },
+    "Base58": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$" },
+    "Id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$" },
+    "Mint": {
+      "type": "string",
+      "description": "\"XNT\" (native), an SPL mint (base58), or — CDP rail only — an EVM token address.",
+      "anyOf": [{ "const": "XNT" }, { "$ref": "#/$defs/Base58" }, { "pattern": "^0x[0-9a-fA-F]{40}$" }]
+    },
+    "Price": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["amount", "mint", "unit"],
+      "properties": {
+        "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Decimal string of the asset's smallest units (u64)." },
+        "mint": { "$ref": "#/$defs/Mint" },
+        "unit": { "enum": ["per-call", "per-1k-tokens", "per-1k-chars", "per-minute", "per-mb"] }
+      }
+    },
+    "Pricing": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/$defs/Price" } }
   }
 }