@defdone/annon 0.0.0-stage → 0.1.0-alpha.0

package/dist/pay/store-node.d.ts

@@ -0,0 +1,8 @@
+/** Atomic, synced records with per-key CAS locks and exclusive service-directory ownership. */
+import { type Store, type Versioned } from './store.js';
+export declare function fileStore<T extends Versioned>(dir: string, o?: {
+    lockWaitMs?: number;
+    recoverDeadLocks?: boolean;
+}): Store<T>;
+/** Call before opening service stores; release only after all in-flight writes have drained. */
+export declare function ownDirectory(dir: string): Promise<() => Promise<void>>;

package/dist/pay/store-node.js

@@ -0,0 +1,224 @@
+/** Atomic, synced records with per-key CAS locks and exclusive service-directory ownership. */
+import { createHash, randomBytes } from 'node:crypto';
+import { link, mkdir, open, readdir, readFile, rename, rmdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sleep } from '../net/retry.js';
+import { syncDir } from '../node/sync-dir.js';
+import { checkNext, holds } from './store.js';
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM: it runs, as another user.
+        return e.code !== 'ESRCH';
+    }
+};
+const started = async (pid) => {
+    try {
+        const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+        const boot = await readFile('/proc/sys/kernel/random/boot_id', 'utf8');
+        return `${boot.trim()}|${stat
+            .slice(stat.lastIndexOf(')') + 1)
+            .trim()
+            .split(/\s+/)[19]}`;
+    }
+    catch {
+        return '';
+    }
+};
+const ownerOf = (text) => {
+    try {
+        const value = JSON.parse(text);
+        return typeof value === 'number' ? { pid: value } : value;
+    }
+    catch {
+        return { pid: 0 };
+    }
+};
+const ownerAlive = async (o) => alive(o.pid) && (!o.started || o.started === (await started(o.pid)));
+export function fileStore(dir, o = {}) {
+    const wait = o.lockWaitMs ?? 5_000;
+    const fileOf = (key) => join(dir, `${createHash('sha256').update(key).digest('hex')}.json`);
+    const load = async (file) => {
+        try {
+            return JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+    };
+    /** Writes `data` to a new temporary file, synced, and returns its name. */
+    const temp = async (file, data) => {
+        const t = `${file}.${randomBytes(6).toString('hex')}.tmp`;
+        // Owner only: a record holds a signed authorization anyone could submit.
+        const h = await open(t, 'wx', 0o600);
+        try {
+            await h.writeFile(data);
+            await h.sync();
+        }
+        finally {
+            await h.close();
+        }
+        return t;
+    };
+    const lock = async (file) => {
+        const l = `${file}.lock`;
+        // The lock appears with its owner's pid already in it: `link` of a complete file is atomic and
+        // fails if the lock exists.
+        const metadata = { pid: process.pid, started: await started(process.pid) };
+        const mine = await temp(file, JSON.stringify(metadata));
+        try {
+            for (const until = Date.now() + wait;;) {
+                try {
+                    await link(mine, l);
+                    return l;
+                }
+                catch (e) {
+                    if (e.code !== 'EEXIST')
+                        throw e;
+                }
+                if (o.recoverDeadLocks) {
+                    const owner = ownerOf(await readFile(l, 'utf8').catch(() => ''));
+                    if (Number.isSafeInteger(owner.pid) && owner.pid > 0 && !(await ownerAlive(owner))) {
+                        // Each contender has its own atomic choosing/ticket file. A dead contender can be
+                        // removed without ever unlinking a successor's coordination file.
+                        const prefix = `${file.slice(file.lastIndexOf('/') + 1)}.recovery.`;
+                        const participant = `${l.slice(0, -5)}.recovery.${process.pid}.${randomBytes(8).toString('hex')}.participant`;
+                        const peers = async () => {
+                            const result = [];
+                            for (const name of await readdir(dir)) {
+                                if (!name.startsWith(prefix) || !name.endsWith('.participant'))
+                                    continue;
+                                const path = join(dir, name);
+                                let peer;
+                                try {
+                                    peer = JSON.parse(await readFile(path, 'utf8'));
+                                }
+                                catch (e) {
+                                    if (e.code === 'ENOENT')
+                                        continue;
+                                    throw e;
+                                }
+                                if (!Number.isSafeInteger(peer.pid) ||
+                                    peer.pid <= 0 ||
+                                    !Number.isSafeInteger(peer.ticket) ||
+                                    peer.ticket < 0 ||
+                                    typeof peer.choosing !== 'boolean')
+                                    throw new Error('invalid store recovery state');
+                                if (!(await ownerAlive(peer))) {
+                                    await unlink(path).catch((e) => {
+                                        if (e.code !== 'ENOENT')
+                                            throw e;
+                                    });
+                                    continue;
+                                }
+                                result.push({ ...peer, name });
+                            }
+                            return result;
+                        };
+                        const choosing = await temp(file, JSON.stringify({ ...metadata, choosing: true, ticket: 0 }));
+                        await rename(choosing, participant);
+                        try {
+                            const ticket = 1 + Math.max(0, ...(await peers()).map((p) => p.ticket));
+                            await rename(await temp(file, JSON.stringify({ ...metadata, choosing: false, ticket })), participant);
+                            const name = participant.slice(participant.lastIndexOf('/') + 1);
+                            while ((await peers()).some((p) => p.name !== name &&
+                                (p.choosing || p.ticket < ticket || (p.ticket === ticket && p.name < name)))) {
+                                if (Date.now() > until)
+                                    throw new Error('the store is busy: recovery is running');
+                                await sleep(20);
+                            }
+                            const current = ownerOf(await readFile(l, 'utf8').catch(() => ''));
+                            if (Number.isSafeInteger(current.pid) &&
+                                current.pid > 0 &&
+                                !(await ownerAlive(current)))
+                                await unlink(l).catch((e) => {
+                                    if (e.code !== 'ENOENT')
+                                        throw e;
+                                });
+                        }
+                        finally {
+                            await unlink(participant).catch(() => { });
+                        }
+                        continue;
+                    }
+                }
+                if (Date.now() > until) {
+                    const owner = ownerOf(await readFile(l, 'utf8').catch(() => ''));
+                    throw new Error(Number.isSafeInteger(owner.pid) && owner.pid > 0 && !(await ownerAlive(owner))
+                        ? `the store is locked by ${l}, left by process ${owner.pid}, which is not running: remove that file once no other process uses the store`
+                        : `the store is busy: ${l} is held by a running process`);
+                }
+                await sleep(20);
+            }
+        }
+        finally {
+            await unlink(mine).catch(() => { });
+        }
+    };
+    return {
+        load: (key) => load(fileOf(key)),
+        compareAndSet: async (key, expected, next) => {
+            checkNext(expected, next);
+            const file = fileOf(key);
+            const l = await lock(file);
+            try {
+                if (!holds(await load(file), expected))
+                    return false;
+                if (next === null)
+                    await unlink(file);
+                else
+                    await rename(await temp(file, JSON.stringify(next)), file);
+                await syncDir(dir);
+                return true;
+            }
+            finally {
+                await unlink(l);
+            }
+        },
+    };
+}
+/** Call before opening service stores; release only after all in-flight writes have drained. */
+export async function ownDirectory(dir) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const store = fileStore(dir, {
+        lockWaitMs: 0,
+        recoverDeadLocks: true,
+    });
+    const key = 'exclusive-process-owner';
+    const old = await store.load(key);
+    if (old && (await ownerAlive(old)))
+        throw new Error('the store is busy: another process owns it');
+    const mine = {
+        id: key,
+        revision: (old?.revision ?? -1) + 1,
+        pid: process.pid,
+        started: await started(process.pid),
+    };
+    if (!(await store.compareAndSet(key, old, mine)))
+        throw new Error('the store is busy: another process owns it');
+    const sweep = async (path) => {
+        for (const entry of await readdir(path, { withFileTypes: true })) {
+            const file = join(path, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name.endsWith('.lock.recovery'))
+                    await rmdir(file);
+                else
+                    await sweep(file);
+            }
+            else if (entry.name.endsWith('.lock') ||
+                entry.name.endsWith('.tmp') ||
+                entry.name.endsWith('.participant'))
+                await unlink(file);
+        }
+    };
+    await sweep(dir);
+    let released;
+    return () => (released ??= (async () => {
+        await store.compareAndSet(key, mine, null);
+    })());
+}

package/dist/pay/store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Where a purchase in progress is kept (x402-annon.md sections 5 and 10): by the buyer's client, and by a seller
+ * for the payments it settles. A store has two operations; `compareAndSet` stops a stale tab or process from overwriting a newer record. Ready-made stores: `memoryStore` (one process), `indexedDbStore` (a browser), `fileStore`
+ * in `store-node.ts` (Node, CLI, agents), and `fromKeyValue` for a store you already have.
+ */
+/** A record a store keeps: its id, and how often it was written since it was created (from 0). */
+export interface Versioned {
+    id: string;
+    revision: number;
+}
+export interface Store<T extends Versioned> {
+    load(key: string): Promise<T | null>;
+    /**
+     * Writes `next` under `key`, or removes the key when `next` is null, only if the key holds the
+     * record `expected` names (its id and revision), or nothing when `expected` is null. Atomic: of
+     * two writers that read the same state, one gets true. Resolves only once the write is durable.
+     */
+    compareAndSet(key: string, expected: Versioned | null, next: T | null): Promise<boolean>;
+}
+export interface StoreWrite<T extends Versioned> {
+    key: string;
+    expected: Versioned | null;
+    next: T | null;
+}
+export interface AtomicStore<T extends Versioned> extends Store<T> {
+    /** All comparisons and writes commit together, or none do. */
+    compareAndSetMany(writes: readonly StoreWrite<T>[]): Promise<boolean>;
+}
+/** `next` must be `expected`'s next revision: a create starts at 0, an update adds 1. */
+export declare function checkNext(expected: Versioned | null, next: Versioned | null): void;
+export declare const holds: (current: Versioned | null, expected: Versioned | null) => boolean;
+/** One process, in memory: for tests, a short-lived agent, or a server with one instance. */
+export declare function memoryStore<T extends Versioned>(): Store<T>;
+export interface KeyValue {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/**
+ * A store over a plain key-value store. `runExclusive` must run `fn` with no other `runExclusive`
+ * for the same key running anywhere that shares the store (e.g. a database row lock, or the Web
+ * Locks API for the tabs of one origin): the whole read, check and write run inside it.
+ */
+export declare function fromKeyValue<T extends Versioned>(kv: KeyValue, runExclusive: <R>(key: string, fn: () => Promise<R>) => Promise<R>): Store<T>;
+/**
+ * A browser store: one IndexedDB object store, each check and write in one `readwrite`
+ * transaction (IndexedDB runs those one at a time for a store, across the tabs of an origin),
+ * committed with `durability: 'strict'`. What a browser keeps is still the user's: clearing site
+ * data removes it.
+ */
+export declare function indexedDbStore<T extends Versioned>(o?: {
+    name?: string;
+    factory?: IDBFactory;
+}): AtomicStore<T>;

package/dist/pay/store.js

@@ -0,0 +1,135 @@
+/**
+ * Where a purchase in progress is kept (x402-annon.md sections 5 and 10): by the buyer's client, and by a seller
+ * for the payments it settles. A store has two operations; `compareAndSet` stops a stale tab or process from overwriting a newer record. Ready-made stores: `memoryStore` (one process), `indexedDbStore` (a browser), `fileStore`
+ * in `store-node.ts` (Node, CLI, agents), and `fromKeyValue` for a store you already have.
+ */
+/** `next` must be `expected`'s next revision: a create starts at 0, an update adds 1. */
+export function checkNext(expected, next) {
+    if (next === null) {
+        if (expected === null)
+            throw new TypeError('nothing to remove');
+        return;
+    }
+    if (next.revision !== (expected === null ? 0 : expected.revision + 1)) {
+        throw new TypeError("next must be the expected record's next revision");
+    }
+    if (expected !== null && next.id !== expected.id) {
+        throw new TypeError('next must keep the id of the record it replaces');
+    }
+}
+export const holds = (current, expected) => expected === null
+    ? current === null
+    : current !== null && current.id === expected.id && current.revision === expected.revision;
+const read = (s) => s === null || s === undefined ? null : JSON.parse(s);
+/** One process, in memory: for tests, a short-lived agent, or a server with one instance. */
+export function memoryStore() {
+    const m = new Map();
+    return {
+        load: async (key) => read(m.get(key)),
+        compareAndSet: async (key, expected, next) => {
+            checkNext(expected, next);
+            if (!holds(read(m.get(key)), expected))
+                return false;
+            if (next === null)
+                m.delete(key);
+            else
+                m.set(key, JSON.stringify(next));
+            return true;
+        },
+    };
+}
+/**
+ * A store over a plain key-value store. `runExclusive` must run `fn` with no other `runExclusive`
+ * for the same key running anywhere that shares the store (e.g. a database row lock, or the Web
+ * Locks API for the tabs of one origin): the whole read, check and write run inside it.
+ */
+export function fromKeyValue(kv, runExclusive) {
+    return {
+        load: async (key) => read(await kv.get(key)),
+        compareAndSet: async (key, expected, next) => {
+            checkNext(expected, next);
+            return runExclusive(key, async () => {
+                if (!holds(read(await kv.get(key)), expected))
+                    return false;
+                if (next === null)
+                    await kv.remove(key);
+                else
+                    await kv.set(key, JSON.stringify(next));
+                return true;
+            });
+        },
+    };
+}
+/**
+ * A browser store: one IndexedDB object store, each check and write in one `readwrite`
+ * transaction (IndexedDB runs those one at a time for a store, across the tabs of an origin),
+ * committed with `durability: 'strict'`. What a browser keeps is still the user's: clearing site
+ * data removes it.
+ */
+export function indexedDbStore(o = {}) {
+    const factory = o.factory ?? globalThis.indexedDB;
+    if (!factory)
+        throw new TypeError('no IndexedDB here: pass a factory or use another store');
+    const name = o.name ?? 'annon';
+    let db;
+    const open = () => {
+        db ??= new Promise((resolve, reject) => {
+            const r = factory.open(name, 1);
+            r.onupgradeneeded = () => r.result.createObjectStore('records');
+            r.onsuccess = () => resolve(r.result);
+            r.onerror = () => reject(r.error);
+        });
+        return db;
+    };
+    const tx = async (mode) => (await open()).transaction('records', mode, { durability: 'strict' }).objectStore('records');
+    const compareAndSetMany = async (writes) => {
+        if (!writes.length || new Set(writes.map((w) => w.key)).size !== writes.length)
+            throw new TypeError('empty or duplicate CAS keys');
+        for (const write of writes)
+            checkNext(write.expected, write.next);
+        const s = await tx('readwrite');
+        return new Promise((resolve, reject) => {
+            let remaining = writes.length;
+            let matches = true;
+            let wrote = false;
+            for (const write of writes) {
+                const r = s.get(write.key);
+                r.onsuccess = () => {
+                    try {
+                        if (!holds(read(r.result), write.expected))
+                            matches = false;
+                        if (--remaining !== 0 || !matches)
+                            return;
+                        for (const item of writes) {
+                            if (item.next === null)
+                                s.delete(item.key);
+                            else
+                                s.put(JSON.stringify(item.next), item.key);
+                        }
+                        wrote = true;
+                    }
+                    catch (error) {
+                        reject(error);
+                        s.transaction.abort();
+                    }
+                };
+            }
+            s.transaction.oncomplete = () => resolve(wrote);
+            const failed = () => reject(s.transaction.error ?? new Error('the IndexedDB transaction was aborted'));
+            s.transaction.onerror = failed;
+            s.transaction.onabort = failed;
+        });
+    };
+    return {
+        load: async (key) => {
+            const s = await tx('readonly');
+            return new Promise((resolve, reject) => {
+                const r = s.get(key);
+                r.onsuccess = () => resolve(read(r.result));
+                r.onerror = () => reject(r.error);
+            });
+        },
+        compareAndSet: (key, expected, next) => compareAndSetMany([{ key, expected, next }]),
+        compareAndSetMany,
+    };
+}

package/dist/pay/x402.d.ts

@@ -0,0 +1,95 @@
+import { type Purchase } from '../settle-near/purchase.js';
+import type { Authorization } from './eip3009.js';
+/** CAIP-2 id of Base mainnet. */
+export declare const BASE_NETWORK = "eip155:8453";
+/**
+ * The scheme of an Annon offer: plain EIP-3009 `TransferWithAuthorization` to the file's `pay_to`,
+ * under its own name so a client without Annon has no handler for it and signs nothing (checked
+ * against the official x402 client: it signs any `exact` offer with a random nonce, which could
+ * never release the key). The seller settles it through any standard facilitator as `exact`
+ * (`forFacilitator`): the scheme label is not part of what the buyer signs.
+ */
+export declare const ANNON_EXACT = "annon-exact";
+export declare const ANNON_NEAR_USDC = "annon-near-usdc";
+/** The x402 idempotency extension (x402-annon.md section 10). */
+export declare const PAYMENT_IDENTIFIER = "payment-identifier";
+/** As the x402 extension declares it, optional: the official `declarePaymentIdentifierExtension`. */
+export declare const paymentIdentifierDeclaration: () => {
+    info: {
+        required: boolean;
+    };
+    schema: {
+        $schema: string;
+        type: string;
+        properties: {
+            required: {
+                type: string;
+            };
+            id: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                pattern: string;
+            };
+        };
+        required: string[];
+    };
+};
+/** x402 builder codes (ERC-8021 attribution); the Annon SDK's own service code. */
+export declare const BUILDER_CODE = "builder-code";
+export declare const BUILDER_CODE_PATTERN: RegExp;
+/** At most this many service codes echoed by a client: its 5 and the server's 5. */
+export declare const MAX_ECHOED_SERVICE_CODES = 10;
+/** Service codes as a list: the extension allows one code as a plain string. */
+export declare const codes: (s: unknown) => unknown[];
+/** x402 discovery (x402-annon.md section 11); never sent to a facilitator. */
+export declare const BAZAAR = "bazaar";
+/** A payment id the extension allows: 16 to 128 letters, digits, `-` and `_`. */
+export declare const isPaymentId: (id: unknown) => id is string;
+export interface Offer {
+    scheme: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown>;
+}
+/** `extensions.annon` as a server advertises it. */
+interface AnnonExtension {
+    info: {
+        version?: unknown;
+        network?: unknown;
+        contract?: unknown;
+        fileId?: unknown;
+        header?: unknown;
+        download?: unknown;
+        public?: unknown;
+    };
+    schema?: unknown;
+}
+export interface PaymentRequired {
+    x402Version: 2;
+    resource?: unknown;
+    accepts: Offer[];
+    extensions?: {
+        annon?: AnnonExtension;
+    } & Record<string, unknown>;
+}
+/** The `PAYMENT-REQUIRED` header (base64 JSON), with only its shape checked. */
+export declare function readPaymentRequired(header: string): PaymentRequired;
+/**
+ * The Annon contract and file a payment request sells, from its `annon` extension. Only a
+ * contract in the required `trusted` list is ever returned.
+ */
+export declare function discover(pr: PaymentRequired, trusted: readonly string[]): {
+    contractId: string;
+    fileId: string;
+};
+/**
+ * The `PAYMENT-SIGNATURE` header: the chosen offer echoed, the EIP-3009 authorization, and the
+ * `annon` extension echoed with the buyer's one-time key, from which the server recomputes the
+ * nonce before it settles. With `paymentId`, the advertised `payment-identifier` gets its id.
+ */
+export declare function paymentSignature(pr: PaymentRequired, offer: Offer, a: Authorization, signature: string, purchase: Purchase, paymentId?: string): string;
+export {};

package/dist/pay/x402.js

@@ -0,0 +1,136 @@
+import { buildPurchaseMessage, purchaseId } from '../settle-near/purchase.js';
+/**
+ * The x402 v2 envelope of an Annon purchase (`specs/x402-annon.md`): reading the `PAYMENT-REQUIRED`
+ * header, finding the file it sells, and building the `PAYMENT-SIGNATURE` header. Nothing read here
+ * is trusted: `preflight` compares it with the contract.
+ */
+import { fail } from './base.js';
+/** CAIP-2 id of Base mainnet. */
+export const BASE_NETWORK = 'eip155:8453';
+/**
+ * The scheme of an Annon offer: plain EIP-3009 `TransferWithAuthorization` to the file's `pay_to`,
+ * under its own name so a client without Annon has no handler for it and signs nothing (checked
+ * against the official x402 client: it signs any `exact` offer with a random nonce, which could
+ * never release the key). The seller settles it through any standard facilitator as `exact`
+ * (`forFacilitator`): the scheme label is not part of what the buyer signs.
+ */
+export const ANNON_EXACT = 'annon-exact';
+export const ANNON_NEAR_USDC = 'annon-near-usdc';
+/** The x402 idempotency extension (x402-annon.md section 10). */
+export const PAYMENT_IDENTIFIER = 'payment-identifier';
+/** As the x402 extension declares it, optional: the official `declarePaymentIdentifierExtension`. */
+export const paymentIdentifierDeclaration = () => ({
+    info: { required: false },
+    schema: {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: {
+            required: { type: 'boolean' },
+            id: { type: 'string', minLength: 16, maxLength: 128, pattern: '^[a-zA-Z0-9_-]+$' },
+        },
+        required: ['required'],
+    },
+});
+/** x402 builder codes (ERC-8021 attribution); the Annon SDK's own service code. */
+export const BUILDER_CODE = 'builder-code';
+const ANNON_SERVICE_CODE = 'bc_lq0mq0v9';
+export const BUILDER_CODE_PATTERN = /^[a-z0-9_]{1,32}$/;
+/** At most this many service codes echoed by a client: its 5 and the server's 5. */
+export const MAX_ECHOED_SERVICE_CODES = 10;
+/** Service codes as a list: the extension allows one code as a plain string. */
+export const codes = (s) => (s === undefined ? [] : Array.isArray(s) ? s : [s]);
+/** x402 discovery (x402-annon.md section 11); never sent to a facilitator. */
+export const BAZAAR = 'bazaar';
+/** A payment id the extension allows: 16 to 128 letters, digits, `-` and `_`. */
+export const isPaymentId = (id) => typeof id === 'string' && /^[a-zA-Z0-9_-]{16,128}$/.test(id);
+const utf8 = new TextEncoder();
+const b64encode = (s) => {
+    let bin = '';
+    for (const b of utf8.encode(s))
+        bin += String.fromCharCode(b);
+    return btoa(bin);
+};
+const b64decode = (s) => new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(atob(s), (c) => c.charCodeAt(0)));
+/** The `PAYMENT-REQUIRED` header (base64 JSON), with only its shape checked. */
+export function readPaymentRequired(header) {
+    let v;
+    try {
+        v = JSON.parse(b64decode(header.trim()));
+    }
+    catch {
+        return fail('bad_requirements', 'PAYMENT-REQUIRED is not base64 JSON');
+    }
+    if (v?.x402Version !== 2 || !Array.isArray(v.accepts)) {
+        return fail('bad_requirements', 'not an x402 v2 payment request');
+    }
+    return v;
+}
+/**
+ * The Annon contract and file a payment request sells, from its `annon` extension. Only a
+ * contract in the required `trusted` list is ever returned.
+ */
+export function discover(pr, trusted) {
+    const info = pr.extensions?.annon?.info;
+    if (!info)
+        return fail('file_mismatch', 'the payment request names no Annon file');
+    if (info.version !== 3 || info.network !== 'near:mainnet') {
+        fail('file_mismatch', 'the Annon extension is not version 3 on NEAR mainnet');
+    }
+    if (typeof info.contract !== 'string' || !trusted.includes(info.contract)) {
+        fail('untrusted_contract', `the Annon contract ${String(info.contract)} is not one this client trusts`);
+    }
+    if (typeof info.fileId !== 'string' || !/^0x[0-9a-f]{64}$/.test(info.fileId)) {
+        fail('file_mismatch', 'the Annon extension has no valid fileId');
+    }
+    return { contractId: info.contract, fileId: info.fileId };
+}
+/**
+ * The `PAYMENT-SIGNATURE` header: the chosen offer echoed, the EIP-3009 authorization, and the
+ * `annon` extension echoed with the buyer's one-time key, from which the server recomputes the
+ * nonce before it settles. With `paymentId`, the advertised `payment-identifier` gets its id.
+ */
+export function paymentSignature(pr, offer, a, signature, purchase, paymentId) {
+    const pid = pr.extensions?.[PAYMENT_IDENTIFIER];
+    // As x402's client merge: the Annon SDK's code first, then the declared codes, no duplicates.
+    const bc = pr.extensions?.[BUILDER_CODE];
+    const declaredS = codes(bc?.info?.s);
+    const builderCode = {
+        ...(bc ?? {}),
+        info: { ...(bc?.info ?? {}), s: [...new Set([ANNON_SERVICE_CODE, ...declaredS])] },
+    };
+    const advertised = pr.extensions?.annon;
+    buildPurchaseMessage(purchase, { baseUsdc: offer.asset });
+    const info = {
+        ...(advertised?.info ?? {}),
+        version: 3,
+        network: 'near:mainnet',
+        contract: purchase.contract,
+        fileId: purchase.file_id,
+        purchase: buildPurchaseMessage(purchase, { baseUsdc: offer.asset }),
+        purchase_id: purchaseId(purchase, { baseUsdc: offer.asset }),
+    };
+    return b64encode(JSON.stringify({
+        x402Version: 2,
+        ...(pr.resource === undefined ? {} : { resource: pr.resource }),
+        accepted: offer,
+        payload: {
+            signature,
+            authorization: {
+                from: a.from,
+                to: a.to,
+                value: a.value.toString(),
+                validAfter: a.validAfter.toString(),
+                validBefore: a.validBefore.toString(),
+                nonce: a.nonce,
+            },
+        },
+        extensions: {
+            ...(pr.extensions ?? {}),
+            annon: { ...(advertised ?? {}), info },
+            ...(pid && paymentId
+                ? { [PAYMENT_IDENTIFIER]: { ...pid, info: { ...pid.info, id: paymentId } } }
+                : {}),
+            [BUILDER_CODE]: builderCode,
+        },
+    }));
+}

package/dist/relay/admission.d.ts

@@ -0,0 +1,8 @@
+export interface AdmissionOptions {
+    admissionFloor?: bigint;
+    admissionBalance?: () => Promise<bigint>;
+    alert?: (type: string) => void;
+}
+/** Final liquid account funds, excluding required account storage stake. */
+export declare function admissionBalance(nearRpc: string, accountId: string): Promise<bigint>;
+export declare function checkAdmissionFloor(method: string, o: AdmissionOptions): Promise<void>;