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

package/dist/pay/base.js

@@ -0,0 +1,386 @@
+import { AnnonError } from '../errors.js';
+/**
+ * Reading Base over JSON-RPC: what the buyer's checks need before signing (balance, code, the
+ * head block), a dry run of the signed authorization against USDC itself, and, after the payment,
+ * the logs `unlock` takes. The RPC is trusted to report the chain, as on the NEAR side; a payment
+ * it misreports is caught by NEAR MPC, which reads Base itself.
+ */
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { RPC_TIMEOUT_MS } from '../near/rpc.js';
+import { addressWord, fromHex, toHex, word } from './eip3009.js';
+export class PayError extends AnnonError {
+    code;
+    /**
+     * Set when the wallet had already signed: the authorization may have reached an RPC and could
+     * still be settled. The purchase stays open: follow `nextStep`.
+     */
+    purchase;
+    retryAfterSeconds;
+    constructor(code, message = code) {
+        super(code, message);
+        this.code = code;
+        this.name = 'PayError';
+    }
+}
+/** A typed RPC rate limit; callers retry through isTransient. */
+export class BaseRpcRateLimited extends PayError {
+    constructor() {
+        super('base_rpc_rate_limited', 'Base RPC rate limited (429)');
+        this.name = 'BaseRpcRateLimited';
+    }
+}
+export const fail = (code, message) => {
+    throw new PayError(code, message);
+};
+const malformed = (what) => fail('transport', `malformed Base RPC answer: ${what}`);
+let nextId = 0;
+async function rpc(url, method, params) {
+    const id = `annon-base-${++nextId}`;
+    let body;
+    try {
+        const res = await fetch(url, {
+            credentials: 'omit',
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+            signal: AbortSignal.timeout(RPC_TIMEOUT_MS),
+        });
+        const httpFailure = () => {
+            if (res.status === 429)
+                throw new BaseRpcRateLimited();
+            return fail('transport', `Base RPC HTTP ${res.status}`);
+        };
+        try {
+            body = await res.json();
+        }
+        catch (error) {
+            if (!res.ok)
+                return httpFailure();
+            throw error;
+        }
+        if (res.status === 429)
+            return httpFailure();
+        // Preserve structured RPC replies on non-2xx responses, as on NEAR.
+        if (!res.ok &&
+            (!body ||
+                typeof body !== 'object' ||
+                Array.isArray(body) ||
+                (body.jsonrpc !== '2.0' && body.id !== id) ||
+                (!('result' in body) && !('error' in body))))
+            return httpFailure();
+    }
+    catch (e) {
+        if (e instanceof PayError)
+            throw e;
+        return fail('transport', `Base RPC unreachable: ${e.message}`);
+    }
+    if (body?.id !== id)
+        return malformed('a reply to another request');
+    return body;
+}
+async function ask(url, method, params) {
+    const body = await rpc(url, method, params);
+    if (body.error)
+        fail(method === 'eth_call' && body.error.code === 3 ? 'refused' : 'transport', `Base RPC error: ${JSON.stringify(body.error)}`);
+    if (body.result === undefined)
+        return malformed(`no result for ${method}`);
+    return body.result;
+}
+const isHexData = (v) => typeof v === 'string' && /^0x([0-9a-fA-F]{2})*$/.test(v);
+const quantity = (v, what) => {
+    if (typeof v !== 'string' || !/^0x(0|[1-9a-f][0-9a-f]*)$/i.test(v))
+        return malformed(what);
+    const n = Number.parseInt(v, 16);
+    return Number.isSafeInteger(n) ? n : malformed(what);
+};
+const qty = (n) => `0x${n.toString(16)}`;
+const selector = (signature) => keccak_256(new TextEncoder().encode(signature)).subarray(0, 4);
+const call = (...parts) => toHex(Uint8Array.from(parts.flatMap((p) => Array.from(p))));
+/** The latest block, after checking the RPC is on Base mainnet. */
+export async function head(url) {
+    if ((await ask(url, 'eth_chainId', [])) !== '0x2105') {
+        fail('network_mismatch', 'the Base RPC is not on Base mainnet (chain 8453)');
+    }
+    return block(url, 'latest');
+}
+/** A block by number or tag (`latest`, `safe`, `finalized`). */
+export async function block(url, at) {
+    const b = (await ask(url, 'eth_getBlockByNumber', [
+        typeof at === 'number' ? qty(at) : at,
+        false,
+    ]));
+    return {
+        number: quantity(b?.number, 'block number'),
+        timestamp: quantity(b?.timestamp, 'timestamp'),
+        ...(typeof b?.hash === 'string' ? { hash: b.hash.toLowerCase() } : {}),
+    };
+}
+/** A transaction's receipt as the RPC returns it; null while the transaction is unknown. */
+export const getReceipt = (url, txHash) => ask(url, 'eth_getTransactionReceipt', [txHash]);
+/** A view call at `block` that returns one 32-byte word. */
+export async function viewWord(url, to, data, block) {
+    const r = await ask(url, 'eth_call', [{ to, data }, qty(block)]);
+    if (!isHexData(r) || r.length !== 66)
+        return malformed('eth_call result');
+    return r.toLowerCase();
+}
+const uint = async (url, to, data, block) => BigInt(await viewWord(url, to, data, block));
+export const balanceOf = (url, usdc, owner, block) => uint(url, usdc, call(selector('balanceOf(address)'), addressWord(owner)), block);
+/** USDC's `authorizationState`: true once the nonce was used *or* canceled. A hint, not proof. */
+export const authorizationState = async (url, usdc, authorizer, nonce, block) => (await uint(url, usdc, call(selector('authorizationState(address,bytes32)'), addressWord(authorizer), fromHex(nonce, 32, 'nonce')), block)) !== 0n;
+/** Whether an address has code: a contract, or an EOA delegated with EIP-7702. */
+/** The runtime code at `address`, lowercase hex; `0x` for none. */
+export async function getCode(url, address, block) {
+    const r = await ask(url, 'eth_getCode', [address, qty(block)]);
+    if (!isHexData(r))
+        return malformed('eth_getCode result');
+    return r.toLowerCase();
+}
+export const hasCode = async (url, address, block) => (await getCode(url, address, block)) !== '0x';
+/** `transferWithAuthorization(from, to, value, after, before, nonce, v, r, s)`. */
+export function authorizationCall(a, signature) {
+    const sig = fromHex(signature, 65, 'signature');
+    return call(selector('transferWithAuthorization(address,address,uint256,uint256,uint256,bytes32,uint8,bytes32,bytes32)'), addressWord(a.from), addressWord(a.to), word(a.value), word(a.validAfter), word(a.validBefore), fromHex(a.nonce, 32, 'nonce'), word(BigInt(sig[64] ?? 0)), sig.subarray(0, 32), sig.subarray(32, 64));
+}
+/**
+ * Runs the signed authorization against USDC without sending it: signature, nonce, validity
+ * window, balance and blacklist, all by USDC's own code.
+ */
+export async function dryRun(url, usdc, a, signature) {
+    const body = await rpc(url, 'eth_call', [
+        { from: a.from, to: usdc, data: authorizationCall(a, signature) },
+        'latest',
+    ]);
+    if (body.error) {
+        const message = String(body.error.message ?? '');
+        if (body.error.code === 3) {
+            fail('payment_rejected', `USDC refused the authorization: ${message}`);
+        }
+        fail('transport', `Base RPC error: ${JSON.stringify(body.error)}`);
+    }
+    if (!isHexData(body.result))
+        malformed('eth_call result');
+}
+// ---------- the payment's block header ----------
+/** Header fields in RLP order (London to Prague / Isthmus); integers are minimal big-endian. */
+const HEADER_FIELDS = [
+    ['parentHash', 'bytes'],
+    ['sha3Uncles', 'bytes'],
+    ['miner', 'bytes'],
+    ['stateRoot', 'bytes'],
+    ['transactionsRoot', 'bytes'],
+    ['receiptsRoot', 'bytes'],
+    ['logsBloom', 'bytes'],
+    ['difficulty', 'int'],
+    ['number', 'int'],
+    ['gasLimit', 'int'],
+    ['gasUsed', 'int'],
+    ['timestamp', 'int'],
+    ['extraData', 'bytes'],
+    ['mixHash', 'bytes'],
+    ['nonce', 'bytes'],
+    ['baseFeePerGas', 'int'],
+    ['withdrawalsRoot', 'bytes'],
+    ['blobGasUsed', 'int'],
+    ['excessBlobGas', 'int'],
+    ['parentBeaconBlockRoot', 'bytes'],
+    ['requestsHash', 'bytes'],
+];
+const rlpLength = (n, offset) => {
+    if (n < 56)
+        return [offset + n];
+    const b = [];
+    for (let x = n; x > 0; x = Math.floor(x / 256))
+        b.unshift(x % 256);
+    return [offset + 55 + b.length, ...b];
+};
+const rlpString = (b) => b.length === 1 && (b[0] ?? 0) < 0x80 ? [...b] : [...rlpLength(b.length, 0x80), ...b];
+const minimal = (h) => {
+    const n = BigInt(h);
+    if (n === 0n)
+        return new Uint8Array();
+    const s = n.toString(16);
+    return Uint8Array.from((s.length % 2 ? `0${s}` : s).match(/../g) ?? [], (x) => Number.parseInt(x, 16));
+};
+const bytesOf = (h, what) => {
+    if (!isHexData(h))
+        return malformed(`header ${what}`);
+    return Uint8Array.from(h.slice(2).match(/../g) ?? [], (x) => Number.parseInt(x, 16));
+};
+/**
+ * The RLP header of the block `hash`, rebuilt from the RPC's fields and checked to hash to it.
+ * `unlock` takes it for a file whose sales were stopped: the contract reads the payment's time
+ * from it. A header with a field this SDK doesn't know fails here, never on NEAR.
+ */
+export async function blockHeader(url, hash) {
+    const b = (await ask(url, 'eth_getBlockByHash', [hash, false]));
+    const present = HEADER_FIELDS.filter(([k]) => b?.[k] !== undefined);
+    const body = present.flatMap(([k, kind]) => rlpString(kind === 'int' ? minimal(String(b[k])) : bytesOf(b[k], k)));
+    const rlp = Uint8Array.from([...rlpLength(body.length, 0xc0), ...body]);
+    if (toHex(keccak_256(rlp)) !== hash.toLowerCase()) {
+        return fail('transport', `block ${hash}: the rebuilt header does not hash to it`);
+    }
+    return toHex(rlp);
+}
+// ---------- after the payment ----------
+const topic = (signature) => toHex(keccak_256(new TextEncoder().encode(signature)));
+const TOPICS = {
+    authorizationUsed: topic('AuthorizationUsed(address,bytes32)'),
+    authorizationCanceled: topic('AuthorizationCanceled(address,bytes32)'),
+    transfer: topic('Transfer(address,address,uint256)'),
+};
+const hash = (v, what) => typeof v === 'string' && /^0x[0-9a-fA-F]{64}$/.test(v) ? v.toLowerCase() : malformed(what);
+function evmLog(l) {
+    if (typeof l?.address !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(l.address)) {
+        return malformed('log address');
+    }
+    if (!Array.isArray(l.topics) || !isHexData(l.data) || typeof l.removed !== 'boolean') {
+        return malformed('log');
+    }
+    return {
+        address: l.address.slice(2).toLowerCase(),
+        block_hash: hash(l.blockHash, 'log blockHash').slice(2),
+        block_number: quantity(l.blockNumber, 'log blockNumber'),
+        data: l.data.toLowerCase(),
+        log_index: quantity(l.logIndex, 'log logIndex'),
+        removed: l.removed,
+        topics: l.topics.map((t) => hash(t, 'log topic').slice(2)),
+        transaction_hash: hash(l.transactionHash, 'log transactionHash').slice(2),
+        transaction_index: quantity(l.transactionIndex, 'log transactionIndex'),
+    };
+}
+const strip = (h) => h.slice(2).toLowerCase();
+const topicOf = (address) => strip(toHex(addressWord(address)));
+/**
+ * The logs of this purchase in a transaction receipt, exactly as `unlock` checks them: USDC's
+ * `AuthorizationUsed` for the nonce and the `Transfer` to `pay_to` right after it. Null when the
+ * receipt holds no such payment.
+ */
+export function paymentLogs(receipt, e) {
+    const r = receipt;
+    if (r?.status !== '0x1' || !Array.isArray(r.logs))
+        return null;
+    const tx = hash(r.transactionHash, 'receipt transactionHash').slice(2);
+    const logs = r.logs.map(evmLog);
+    const at = (address, t0) => (l) => l.transaction_hash === tx &&
+        !l.removed &&
+        l.address === strip(address) &&
+        l.topics.length === 3 &&
+        l.topics[0] === strip(t0);
+    const amount = (data, offset) => BigInt(`0x${data.slice(2 + offset * 64, 2 + (offset + 1) * 64) || '0'}`);
+    // EIP-3009 nonces are per authorizer: another payer's log with the same nonce in the same
+    // transaction must not hide this one.
+    const i = logs.findIndex((l) => at(e.usdc, TOPICS.authorizationUsed)(l) &&
+        l.topics[1] === topicOf(e.from) &&
+        l.topics[2] === strip(e.nonce));
+    const [auth, transfer] = [logs[i], logs[i + 1]];
+    if (i < 0 || !auth || !transfer || !at(e.usdc, TOPICS.transfer)(transfer))
+        return null;
+    if (transfer.log_index !== auth.log_index + 1 ||
+        transfer.topics[1] !== topicOf(e.from) ||
+        transfer.topics[2] !== topicOf(e.to) ||
+        transfer.data.length !== 2 + 64) {
+        return null;
+    }
+    return amount(transfer.data, 0) === e.price ? [auth, transfer] : null;
+}
+/**
+ * The last block the payment could be in: the first at or past `validBefore` (USDC refuses it
+ * there and after), or the head. Searched forward, so it holds whatever Base's block time is.
+ */
+async function lastBlock(url, from, validBefore, now) {
+    // Note: a first guess of 5 blocks a second (Base since Denim, 5 Nov 2026), doubled on a miss.
+    let step = Math.max(1, (Number(validBefore) - (await block(url, from)).timestamp) * 5);
+    for (let at = from + step;; at += step, step *= 2) {
+        if (at >= now.number)
+            return now.number;
+        if (BigInt((await block(url, at)).timestamp) >= validBefore)
+            return at;
+    }
+}
+/** Note: blocks per eth_getLogs, the common RPC limit (QuickNode refuses a wider range). */
+const LOG_RANGE = 10_000;
+/**
+ * USDC's logs for `topics` (a list in a position matches any of it) in `[from, to]`, read in
+ * chunks of `LOG_RANGE` blocks, earliest first. Each chunk's logs must answer that chunk's query.
+ * Stops after the first chunk with a log `enough` accepts; an empty range reads nothing.
+ */
+async function usdcLogs(url, usdc, topics, from, to, enough) {
+    const all = [];
+    for (let at = from; at <= to; at += LOG_RANGE) {
+        const end = Math.min(to, at + LOG_RANGE - 1);
+        const found = await ask(url, 'eth_getLogs', [
+            { address: usdc, fromBlock: qty(at), toBlock: qty(end), topics },
+        ]);
+        if (!Array.isArray(found))
+            return malformed('eth_getLogs result');
+        const logs = found.map(evmLog).filter((l) => !l.removed);
+        // Every log must answer the query; anything else is an RPC that can't be believed.
+        for (const l of logs) {
+            if (l.address !== strip(usdc) ||
+                l.topics.length !== topics.length ||
+                !topics.every((t, i) => [t].flat().some((x) => strip(x) === l.topics[i])) ||
+                l.block_number < at ||
+                l.block_number > end) {
+                return malformed('eth_getLogs returned a log the query did not ask for');
+            }
+        }
+        all.push(...logs);
+        if (logs.some(enough))
+            break;
+    }
+    return all;
+}
+/** The block of an `AuthorizationCanceled` for this nonce in `[from, to]`. */
+async function canceledAfter(url, e, from, to) {
+    const topics = [TOPICS.authorizationCanceled, toHex(addressWord(e.from)), e.nonce.toLowerCase()];
+    const [first] = await usdcLogs(url, e.usdc, topics, from, to, () => true);
+    return first ? first.block_number : null;
+}
+/**
+ * Where a signed purchase stands, found by its nonce alone, so a lost transaction hash loses
+ * nothing. `block` is the head when it was signed. A payment counts as soon as it is in a block;
+ * `expired` and `canceled` only from the finalized chain, because a new purchase follows them and
+ * a reorg must not turn that into a second payment. `authorizationState` is only read to catch an
+ * RPC that misses logs.
+ */
+export async function paymentStatus(url, e) {
+    // Finalized first: the head read after it is at least as far, so a payment in any block the
+    // expiry below relies on is inside the search.
+    const final = await block(url, 'finalized');
+    const now = await head(url);
+    const last = await lastBlock(url, e.block, e.validBefore, now);
+    // A used authorization in any chunk wins over a cancellation, so only that ends the search.
+    const usedTopic = strip(TOPICS.authorizationUsed);
+    const logs = await usdcLogs(url, e.usdc, [
+        [TOPICS.authorizationUsed, TOPICS.authorizationCanceled],
+        toHex(addressWord(e.from)),
+        e.nonce.toLowerCase(),
+    ], e.block, last, (l) => l.topics[0] === usedTopic);
+    const used = logs.find((l) => l.topics[0] === usedTopic);
+    if (used) {
+        const receipt = await ask(url, 'eth_getTransactionReceipt', [`0x${used.transaction_hash}`]);
+        const paid = paymentLogs(receipt, e);
+        if (!paid?.[0] || paid[0].transaction_hash !== used.transaction_hash) {
+            return fail('transport', 'the authorization was used, but not for this purchase as expected');
+        }
+        return {
+            state: 'paid',
+            txHash: `0x${paid[0].transaction_hash}`,
+            logIndex: paid[0].log_index,
+            logs: paid,
+        };
+    }
+    const canceled = logs.find((l) => l.topics[0] === strip(TOPICS.authorizationCanceled));
+    if (canceled)
+        return canceled.block_number <= final.number ? { state: 'canceled' } : { state: 'pending' };
+    if (await authorizationState(url, e.usdc, e.from, e.nonce, now.number)) {
+        // USDC takes a cancellation after the deadline too: look for one up to the head.
+        const late = await canceledAfter(url, e, last + 1, now.number);
+        if (late !== null)
+            return late <= final.number ? { state: 'canceled' } : { state: 'pending' };
+        return fail('transport', 'USDC marks the authorization used, but the RPC returned no log for it');
+    }
+    // Blocks after the finalized one are later still, so none of them can take the payment.
+    return BigInt(final.timestamp) >= e.validBefore ? { state: 'expired' } : { state: 'pending' };
+}

package/dist/pay/eip3009.d.ts

@@ -0,0 +1,59 @@
+/**
+ * EIP-3009 on Base USDC: the authorization a buyer signs, its EIP-712 digest, the checks on the
+ * signature a wallet sends back. Nonces as in `specs/nonce.md`.
+ */
+export declare const BASE_CHAIN_ID = 8453;
+export interface Authorization {
+    from: string;
+    to: string;
+    value: bigint;
+    validAfter: bigint;
+    validBefore: bigint;
+    nonce: string;
+}
+/** The typed data in the shape `signTypedData` takes (viem, ethers' `_signTypedData` minus domain types). */
+export declare const typedData: (usdc: string, a: Authorization) => {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: string;
+    };
+    types: {
+        TransferWithAuthorization: readonly [{
+            readonly name: "from";
+            readonly type: "address";
+        }, {
+            readonly name: "to";
+            readonly type: "address";
+        }, {
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly name: "validAfter";
+            readonly type: "uint256";
+        }, {
+            readonly name: "validBefore";
+            readonly type: "uint256";
+        }, {
+            readonly name: "nonce";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: string;
+    message: Authorization;
+};
+export type TypedData = ReturnType<typeof typedData>;
+export declare const toHex: (b: Uint8Array) => string;
+export declare function fromHex(s: string, bytes: number, name: string): Uint8Array;
+/** A uint256 word. */
+export declare function word(n: bigint): Uint8Array;
+/** An address as a 32-byte word. */
+export declare const addressWord: (a: string) => Uint8Array<ArrayBuffer>;
+/** The EIP-712 digest a wallet signs for `typedData(usdc, a)`. */
+export declare function digest(usdc: string, a: Authorization): Uint8Array;
+/**
+ * The address that signed `digest`, or null. Only what USDC itself accepts: 65 bytes r ‖ s ‖ v,
+ * v 27 or 28, low s (FiatToken's ECRecover refuses the rest).
+ */
+export declare function signer(digestBytes: Uint8Array, signature: string): string | null;

package/dist/pay/eip3009.js

@@ -0,0 +1,72 @@
+/**
+ * EIP-3009 on Base USDC: the authorization a buyer signs, its EIP-712 digest, the checks on the
+ * signature a wallet sends back. Nonces as in `specs/nonce.md`.
+ */
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { concatParts, prefixedHex } from '../bytes.js';
+export const BASE_CHAIN_ID = 8453;
+/** What the buyer signs: USDC `TransferWithAuthorization` straight to the file's `pay_to`. */
+const PRIMARY_TYPE = 'TransferWithAuthorization';
+const FIELDS = [
+    { name: 'from', type: 'address' },
+    { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+];
+/** The typed data in the shape `signTypedData` takes (viem, ethers' `_signTypedData` minus domain types). */
+export const typedData = (usdc, a) => ({
+    domain: { name: 'USD Coin', version: '2', chainId: BASE_CHAIN_ID, verifyingContract: usdc },
+    types: { [PRIMARY_TYPE]: FIELDS },
+    primaryType: PRIMARY_TYPE,
+    message: a,
+});
+const utf8 = new TextEncoder();
+const concat = (...parts) => concatParts(parts);
+export const toHex = (b) => prefixedHex(b);
+export function fromHex(s, bytes, name) {
+    if (!new RegExp(`^0x[0-9a-fA-F]{${2 * bytes}}$`).test(s)) {
+        throw new TypeError(`${name} must be 0x and ${bytes} bytes of hex`);
+    }
+    return Uint8Array.from(s.slice(2).match(/../g) ?? [], (x) => Number.parseInt(x, 16));
+}
+/** A uint256 word. */
+export function word(n) {
+    if (n < 0n || n >= 2n ** 256n)
+        throw new RangeError('not a uint256');
+    return fromHex(`0x${n.toString(16).padStart(64, '0')}`, 32, 'word');
+}
+/** An address as a 32-byte word. */
+export const addressWord = (a) => concat(new Uint8Array(12), fromHex(a, 20, 'address'));
+/** The EIP-712 digest a wallet signs for `typedData(usdc, a)`. */
+export function digest(usdc, a) {
+    const domainType = keccak_256(utf8.encode('EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)'));
+    const domain = keccak_256(concat(domainType, keccak_256(utf8.encode('USD Coin')), keccak_256(utf8.encode('2')), word(BigInt(BASE_CHAIN_ID)), addressWord(usdc)));
+    const type = keccak_256(utf8.encode(`${PRIMARY_TYPE}(${FIELDS.map((f) => `${f.type} ${f.name}`)})`));
+    const struct = keccak_256(concat(type, addressWord(a.from), addressWord(a.to), word(a.value), word(a.validAfter), word(a.validBefore), fromHex(a.nonce, 32, 'nonce')));
+    return keccak_256(concat(new Uint8Array([0x19, 0x01]), domain, struct));
+}
+/**
+ * The address that signed `digest`, or null. Only what USDC itself accepts: 65 bytes r ‖ s ‖ v,
+ * v 27 or 28, low s (FiatToken's ECRecover refuses the rest).
+ */
+export function signer(digestBytes, signature) {
+    if (!/^0x[0-9a-fA-F]{130}$/.test(signature))
+        return null;
+    const sig = fromHex(signature, 65, 'signature');
+    const v = sig[64] ?? 0;
+    const s = BigInt(toHex(sig.subarray(32, 64)));
+    if ((v !== 27 && v !== 28) || s > secp256k1.Point.Fn.ORDER / 2n)
+        return null;
+    try {
+        const pub = secp256k1.Point.fromBytes(secp256k1.recoverPublicKey(concat(new Uint8Array([v - 27]), sig.subarray(0, 64)), digestBytes, {
+            prehash: false,
+        }));
+        return toHex(keccak_256(pub.toBytes(false).subarray(1)).subarray(12));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/pay/pay.d.ts

@@ -0,0 +1,86 @@
+import { type FileInfo } from '../near/rpc.js';
+import type { Identity } from '../settle-near/identity.js';
+import { type Purchase } from '../settle-near/purchase.js';
+import { type PaymentStatus } from './base.js';
+import { type TypedData } from './eip3009.js';
+import { type PurchaseRecord } from './purchase.js';
+import type { Store } from './store.js';
+import { type Offer, type PaymentRequired } from './x402.js';
+/** Bound the lifetime of an outstanding payment authorization. */
+export declare const MAX_VALIDITY_SECONDS = 180;
+/** How far the Base RPC's clock may be from ours. */
+export declare const MAX_CLOCK_SKEW_SECONDS = 60;
+interface PreflightOptions {
+    nearRpc: string;
+    baseRpc: string;
+    /** The Annon contract the client trusts. */
+    contractId: string;
+    /** The file being bought, 0x and 32 bytes, from the link, not from the payment request. */
+    fileId: string;
+    /** The wallet that pays and later opens the file. */
+    buyer: string;
+    /** The 402's `PAYMENT-REQUIRED`, read with `readPaymentRequired`. */
+    paymentRequired: PaymentRequired;
+    /**
+     * The URL of the request that got that 402. Its `resource.url` must be this URL, so the buyer
+     * proof is never made for a URL another endpoint advertised (download.md section 3).
+     */
+    url: string;
+    /**
+     * The PAY2 header served at `extensions.annon.info.header`; the whole file when the offer says
+     * `public`. Checked against the registration before anything is signed (x402-annon.md section 7).
+     */
+    pay2: Uint8Array;
+    /** USDC base units: refused above it. */
+    maxPrice: bigint;
+    /** Moderators the buyer trusts to take a file down. A file with any other is refused. */
+    moderators?: readonly string[];
+}
+/** A purchase that passed every check, ready to sign. */
+interface Quote {
+    nearRpc: string;
+    baseRpc: string;
+    contractId: string;
+    fileId: string;
+    buyer: string;
+    seller: Identity;
+    /** The registered `pay_to`. */
+    to: string;
+    usdc: string;
+    price: bigint;
+    /** What the request allows; capped at `MAX_VALIDITY_SECONDS`. */
+    validity: number;
+    file: FileInfo;
+    paymentRequired: PaymentRequired;
+    offer: Offer;
+    /** The checked PAY2 header; `authorize` checks it again and the download names its hash. */
+    header: Uint8Array;
+}
+/** Every check that can refuse a purchase before the wallet is asked to sign. */
+export declare function preflight(o: PreflightOptions): Promise<Quote>;
+interface Wallet {
+    address: string;
+    /** EIP-712, as viem's `signTypedData`: returns the 65-byte signature as 0x hex. */
+    signTypedData(t: TypedData): Promise<string>;
+}
+interface AuthorizeOptions {
+    /** The canonical purchase binding its terms, buyer key, refund and recovery identities. */
+    purchase: Purchase;
+    buyerSecret: Uint8Array;
+    wallet: Wallet;
+    /** Where the purchase is recorded by purchase_id (x402-annon.md section 5). */
+    store: Store<PurchaseRecord>;
+}
+/**
+ * Asks the wallet to sign and returns the `PAYMENT-SIGNATURE` header. The purchase is recorded
+ * first (refused if this purchase_id already has a record); the signature is checked
+ * to be the buyer's, in the form USDC takes; the payload is recorded, and only then run against
+ * USDC and returned.
+ */
+export declare function authorize(q: Quote, o: AuthorizeOptions): Promise<{
+    header: string;
+    purchase: PurchaseRecord;
+}>;
+/** Where a recorded purchase stands on Base, over all its attempts. */
+export declare const status: (baseRpc: string, r: PurchaseRecord) => Promise<PaymentStatus>;
+export {};