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

package/dist/relay/relay-checks.js

@@ -0,0 +1,244 @@
+/** Relay authorization, file eligibility and payment evidence checks. */
+import { isTransient } from '../errors.js';
+import { getFile, getGrant, getPurchase } from '../near/rpc.js';
+import { fileFundingText, reopenSellerText, reopenText, stopSalesText } from '../near/texts.js';
+import { block, blockHeader, getReceipt, paymentLogs } from '../pay/base.js';
+import { createSplit, readSplitState } from '../pay/split.js';
+import { identityJson, verifyAuthorization } from '../settle-near/identity.js';
+import { baseNonceV2, parsePurchaseMessage, purchaseId } from '../settle-near/purchase.js';
+import { termsHash } from '../settle-near/terms.js';
+import { checkProtocolFee } from './fees.js';
+import { asRelayError, refusedBaseTerms, signedByItsWallet, verifiedBaseTerms } from './relay.js';
+import { fail } from './relay-types.js';
+import { verifyReservation } from './reservation.js';
+import { admitTerms, checkedDecision, temporary } from './sponsorship.js';
+export async function checkRelay(r, o) {
+    try {
+        if ('deadline' in r.args) {
+            const now = o.now ?? Math.floor(Date.now() / 1000);
+            if ((r.method === 'fund_file_storage' ? r.args.deadline <= now : r.args.deadline < now) ||
+                r.args.deadline >
+                    now +
+                        (r.method === 'fund_file_storage'
+                            ? (o.policy.topupMaxDeadlineSeconds ?? 600)
+                            : o.policy.maxDeadlineSeconds))
+                fail('bad_deadline');
+        }
+        const fileId = r.method === 'register'
+            ? r.args.terms.file_id
+            : r.method === 'unlock'
+                ? parsePurchaseMessage(r.args.purchase, { baseUsdc: o.usdc }).file_id
+                : 'file_id' in r.args
+                    ? r.args.file_id
+                    : undefined;
+        const p = r.method === 'reopen' || r.method === 'claim_key'
+            ? await getPurchase(o.nearRpc, o.contractId, r.args.purchase_id)
+            : null;
+        if ((r.method === 'reopen' || r.method === 'claim_key') && !p)
+            fail('not_buyer');
+        const target = fileId ?? p?.file_id;
+        if (!target)
+            return fail('not_buyer');
+        const file = await getFile(o.nearRpc, o.contractId, target);
+        if (r.method === 'register') {
+            if (r.args.terms.contract !== o.contractId ||
+                BigInt(r.args.terms.near.price) < o.policy.minPrice ||
+                (r.args.terms.base !== null && BigInt(r.args.terms.base.price) < o.policy.minPrice))
+                fail('not_sponsored');
+            if (file)
+                fail('already_registered');
+            signedByItsWallet(r, o.contractId, {
+                baseUsdc: o.usdc,
+                ...(o.nearUsdc ? { nearUsdc: o.nearUsdc } : {}),
+            });
+            if (o.policy.fee) {
+                try {
+                    checkProtocolFee(r.args.terms, o.policy.fee);
+                }
+                catch {
+                    fail('not_sponsored', 'required treasury share missing or invalid');
+                }
+            }
+            if (r.args.terms.base) {
+                const provenance = r.baseSplit;
+                if (o.policy.baseSponsorship === false || !provenance)
+                    return fail('not_sponsored');
+                try {
+                    if (r.args.terms.near.recipients.some((r) => r.identity.kind !== 'evm'))
+                        throw new Error();
+                    const split = createSplit(provenance.kind, {
+                        recipients: r.args.terms.near.recipients.map((r) => r.identity.id),
+                        allocations: r.args.terms.near.recipients.map((r) => BigInt(r.bps)),
+                        totalAllocation: 10000n,
+                        distributionIncentive: 0,
+                    }, provenance.salt);
+                    if (split.address !== r.args.terms.base.pay_to)
+                        throw new Error();
+                }
+                catch {
+                    fail('not_sponsored', 'Base split does not match recipients');
+                }
+            }
+            if (o.ledger) {
+                const listed = await o.policy.sellerAllowed?.(identityJson(r.args.terms.seller));
+                if (!listed && o.policy.openPoolEnabled === false)
+                    temporary();
+                await admitTerms(r.args.terms, o, listed ? 'listed' : 'pool');
+                if (r.hostingReservation) {
+                    if (!o.reservation)
+                        return fail('not_sponsored');
+                    await verifyReservation(r.hostingReservation, r.args.terms, {
+                        ...o.reservation,
+                        now: o.now ?? Math.floor(Date.now() / 1000),
+                    }).catch(() => fail('not_sponsored'));
+                }
+                else if (!listed)
+                    fail('not_sponsored', 'A hosting reservation is required.');
+            }
+            return;
+        }
+        if (!file)
+            return fail('unknown_file');
+        if (file.takenDown)
+            fail('taken_down');
+        if (r.method === 'fund_file_storage') {
+            if (!verifyAuthorization(file.seller, fileFundingText({
+                ...r.args,
+                network: file.terms.network,
+                contract: o.contractId,
+                seller: file.seller,
+            }), r.auth))
+                fail('bad_signature');
+            if (file.salesStoppedAt !== null)
+                fail('sales_stopped');
+            if (!o.ledger || !(await o.ledger.decision(r.args.file_id, file.termsHash)))
+                fail('not_sponsored');
+            return;
+        }
+        if (r.method === 'claim_key') {
+            const price = p?.route === 'base-usdc' ? file.terms.base?.price : file.terms.near.price;
+            if (price === undefined || BigInt(price) < o.policy.minPrice)
+                fail('not_sponsored');
+            if (!(await getGrant(o.nearRpc, o.contractId, r.args.purchase_id, r.args.grant)))
+                fail('not_buyer');
+            return;
+        }
+        if (r.method === 'reopen') {
+            if (!p)
+                return fail('not_buyer');
+            if (!verifyAuthorization(p.recovery, reopenText({
+                ...r.args,
+                contract: o.contractId,
+                file_id: p.file_id,
+                recovery: p.recovery,
+            }), r.auth))
+                fail('bad_signature');
+            return;
+        }
+        if (r.method === 'reopen_seller' || r.method === 'stop_sales') {
+            const text = r.method === 'stop_sales'
+                ? stopSalesText(o.contractId, r.args, file.seller)
+                : reopenSellerText(o.contractId, r.args, file.seller);
+            if (!verifyAuthorization(file.seller, text, r.auth))
+                fail('bad_signature');
+            if (r.method === 'stop_sales' && file.salesStoppedAt !== null)
+                fail('sales_stopped');
+            return;
+        }
+        if (r.method !== 'unlock')
+            return;
+        if (!o.ledger && o.policy.baseSponsorship === false)
+            fail('not_sponsored');
+        const a = r.args;
+        const purchase = parsePurchaseMessage(a.purchase, { baseUsdc: o.usdc });
+        if (!o.ledger && BigInt(purchase.price) < o.policy.minPrice)
+            fail('not_sponsored');
+        const id = purchaseId(purchase, { baseUsdc: o.usdc });
+        if (purchase.route !== 'base-usdc' ||
+            purchase.contract !== o.contractId ||
+            !file.terms.base ||
+            purchase.terms_hash !== file.termsHash ||
+            purchase.price !== file.terms.base.price ||
+            purchase.asset !== o.usdc)
+            return fail('bad_request');
+        if (o.ledger)
+            await checkedDecision(file, o, true);
+        else {
+            try {
+                if (file.terms.near.recipients.some((r) => r.identity.kind !== 'evm'))
+                    fail('not_sponsored', 'Base split recipients must be EVM identities');
+                if (o.policy.fee)
+                    checkProtocolFee(file.terms, o.policy.fee);
+            }
+            catch {
+                fail('not_sponsored', 'required treasury share missing or invalid');
+            }
+            const verifiedKey = JSON.stringify([
+                o.baseRpc,
+                o.nearRpc,
+                o.contractId,
+                termsHash(file.terms),
+            ]);
+            const now = Date.now();
+            for (const [key, until] of refusedBaseTerms) {
+                if (until <= now)
+                    refusedBaseTerms.delete(key);
+            }
+            if (refusedBaseTerms.has(verifiedKey))
+                fail('not_sponsored', 'Base split code or state does not match registered recipients');
+            if (!verifiedBaseTerms.has(verifiedKey)) {
+                try {
+                    await readSplitState(o.baseRpc, file.terms.base.pay_to, {
+                        recipients: file.terms.near.recipients.map((r) => r.identity.id),
+                        allocations: file.terms.near.recipients.map((r) => BigInt(r.bps)),
+                        totalAllocation: 10000n,
+                        distributionIncentive: 0,
+                    });
+                }
+                catch (error) {
+                    if (isTransient(error))
+                        fail('unavailable', 'Base split verification unavailable; retry later');
+                    // Bound attacker-controlled refusals; transient RPC failures are never cached.
+                    if (refusedBaseTerms.size >= 1024) {
+                        const oldest = refusedBaseTerms.keys().next().value;
+                        if (oldest !== undefined)
+                            refusedBaseTerms.delete(oldest);
+                    }
+                    refusedBaseTerms.set(verifiedKey, Date.now() + 60000);
+                    fail('not_sponsored', 'Base split code or state does not match registered recipients');
+                }
+                verifiedBaseTerms.add(verifiedKey);
+            }
+        }
+        if (await getPurchase(o.nearRpc, o.contractId, id))
+            fail('payment_used');
+        const auth = a.logs[0];
+        if (!auth)
+            return fail('bad_request');
+        const found = paymentLogs(await getReceipt(o.baseRpc, `0x${auth.transaction_hash}`), {
+            usdc: o.usdc,
+            to: file.payTo,
+            from: `0x${auth.topics[1]?.slice(-40)}`,
+            nonce: baseNonceV2(id),
+            price: BigInt(purchase.price),
+        });
+        if (!found || JSON.stringify(found) !== JSON.stringify(a.logs))
+            fail('payment_not_found');
+        const safe = await block(o.baseRpc, 'safe');
+        if (safe.number < auth.block_number ||
+            (await block(o.baseRpc, auth.block_number)).hash !== `0x${auth.block_hash}`)
+            fail('settlement_pending');
+        if (a.header !== null && (await blockHeader(o.baseRpc, `0x${auth.block_hash}`)) !== a.header)
+            fail('bad_header');
+        if (file.salesStoppedAt !== null) {
+            if (a.header === null)
+                fail('bad_header');
+            const paidAt = (await block(o.baseRpc, auth.block_number)).timestamp;
+            if (BigInt(paidAt) > BigInt(file.salesStoppedAt) + 300n)
+                fail('sales_stopped');
+        }
+    }
+    catch (e) {
+        asRelayError(e);
+    }
+}

package/dist/relay/relay-reconciliation.d.ts

@@ -0,0 +1,15 @@
+/** Durable relay status refresh and storage reconciliation. */
+import type { RelayLedger } from './ledger.js';
+import { type CheckOptions, type RelayRequest, type RelayResult, type Sender } from './relay-types.js';
+/** Reconcile final evidence and resume only previously signed transaction bytes. */
+export declare function reconcileRelayStorage(o: {
+    ledger?: RelayLedger;
+    nearRpc: string;
+    contractId: string;
+    sender?: Sender;
+    disabled?: boolean;
+    alert?: (type: string) => void;
+}): Promise<void>;
+/** Durable status never re-signs an unresolved operation. */
+declare function durableStatus(r: RelayRequest, o: CheckOptions): Promise<RelayResult | 'pending' | null>;
+export { durableStatus };

package/dist/relay/relay-reconciliation.js

@@ -0,0 +1,293 @@
+/** Durable relay status refresh and storage reconciliation. */
+import { sha256 } from '@noble/hashes/sha2.js';
+import { AnnonError } from '../errors.js';
+import { getFile, getGrant, getPurchase, readOutcome, rpcReply } from '../near/rpc.js';
+import { bytes } from '../settle-near/codec.js';
+import { parsePurchaseMessage, purchaseId } from '../settle-near/purchase.js';
+import { requestHash } from './ledger.js';
+import { enqueue, HOLD, identity, reconciliationCursor, requestBinding, signedByItsWallet, statusReads, } from './relay.js';
+import { lookUp, send, senderKey } from './relay-transactions.js';
+import { fail, } from './relay-types.js';
+/** Reconcile final evidence and resume only previously signed transaction bytes. */
+export async function reconcileRelayStorage(o) {
+    if (!o.ledger)
+        return;
+    const all = Object.values((await o.ledger.read()).operations).filter((op) => op.stage === 'submitted' && op.tx && !op.storageFinalized);
+    const offset = (reconciliationCursor.get(o.ledger) ?? 0) % (all.length || 1);
+    const pending = [...all.slice(offset), ...all.slice(0, offset)].slice(0, 32);
+    reconciliationCursor.set(o.ledger, (offset + pending.length) % (all.length || 1));
+    for (const op of pending) {
+        const tx = op.tx;
+        if (!tx)
+            continue;
+        const reply = await lookUp(o.nearRpc, tx.txHash, tx.signer);
+        if (!o.disabled &&
+            reply?.error?.cause?.name === 'UNKNOWN_TRANSACTION' &&
+            o.sender?.accountId === tx.signer) {
+            const resumed = { ...o, sender: o.sender };
+            let expired = false;
+            if (tx.referenceHash) {
+                try {
+                    const protocol = await rpcReply(o.nearRpc, 'EXPERIMENTAL_protocol_config', {
+                        finality: 'final',
+                    });
+                    const head = await rpcReply(o.nearRpc, 'block', { finality: 'final' });
+                    const reference = await rpcReply(o.nearRpc, 'block', { block_id: tx.referenceHash });
+                    const period = protocol.result
+                        ?.transaction_validity_period;
+                    const height = head.result?.header?.height;
+                    const from = reference.result?.header?.height;
+                    expired =
+                        !protocol.error &&
+                            !head.error &&
+                            !reference.error &&
+                            Number.isSafeInteger(period) &&
+                            Number.isSafeInteger(height) &&
+                            Number.isSafeInteger(from) &&
+                            (period ?? 0) > 0 &&
+                            (from ?? -1) >= 0 &&
+                            (height ?? 0) - (from ?? 0) > (period ?? 0);
+                }
+                catch {
+                    /* Missing expiry evidence keeps the original hold. */
+                }
+            }
+            const result = expired
+                ? { txHash: tx.txHash, rejected: true, reason: 'Expired' }
+                : await enqueue(() => send(resumed, senderKey(resumed), tx.txHash, tx.signed, false, true), senderKey(resumed));
+            if (result.rejected && ['Expired', 'InvalidNonce'].includes(result.reason ?? '')) {
+                // Check again after the refusal: a landed transaction always wins over fresh signing.
+                const final = await lookUp(o.nearRpc, tx.txHash, tx.signer);
+                if (final?.error?.cause?.name === 'UNKNOWN_TRANSACTION') {
+                    try {
+                        let landed = false;
+                        if (op.method === 'register' || op.method === 'stop_sales') {
+                            const file = await getFile(o.nearRpc, o.contractId, op.fileId);
+                            if (op.method === 'register' && file?.termsHash === op.termsHash) {
+                                await o.ledger.registered(op.fileId, op.termsHash);
+                                landed = true;
+                            }
+                            else if (op.method === 'stop_sales')
+                                landed = file?.salesStoppedAt != null;
+                        }
+                        else if (op.method === 'unlock') {
+                            const args = tx.args.args;
+                            const id = purchaseId(parsePurchaseMessage(args.purchase));
+                            landed = !!(await getPurchase(o.nearRpc, o.contractId, id));
+                        }
+                        else if (op.method === 'reopen') {
+                            const args = tx.args.args;
+                            const purchase = await getPurchase(o.nearRpc, o.contractId, args.purchase_id);
+                            landed = purchase?.buyer_key === args.fresh_key;
+                            const grants = purchase?.grants ?? 0;
+                            for (let grant = grants - 1; !landed && grant >= Math.max(1, grants - 32); grant--)
+                                landed =
+                                    (await getGrant(o.nearRpc, o.contractId, args.purchase_id, grant))?.buyer_key ===
+                                        args.fresh_key;
+                            // A bounded pass cannot disprove an older grant outside this window.
+                            if (!landed && (purchase?.grants ?? 0) > 33) {
+                                o.alert?.('reconcile_held');
+                                continue;
+                            }
+                        }
+                        if (op.method === 'claim_key') {
+                            const args = tx.args;
+                            // Claim has no persistent effect. An existing grant conservatively retains its quota.
+                            landed = !!(await getGrant(o.nearRpc, o.contractId, args.purchase_id, args.grant ?? 0));
+                        }
+                        else if (op.method === 'reopen_seller') {
+                            const args = tx.args.args;
+                            // The unchanged contract stores r || SHA256(domain || file_id || key) as a unit value.
+                            const marker = sha256(new Uint8Array([
+                                ...new TextEncoder().encode('annon/reopen-seller/v2\0'),
+                                ...bytes(args.file_id, 32),
+                                ...bytes(args.key ?? '', 48),
+                            ]));
+                            const prefix = btoa(String.fromCharCode(114, ...marker));
+                            const state = await rpcReply(o.nearRpc, 'query', {
+                                request_type: 'view_state',
+                                account_id: o.contractId,
+                                prefix_base64: prefix,
+                                finality: 'final',
+                            });
+                            const values = state.result
+                                ?.values;
+                            if (state.error ||
+                                !Array.isArray(values) ||
+                                values.length > 1 ||
+                                values.some((v) => v.key !== prefix || v.value !== '')) {
+                                o.alert?.('reconcile_held');
+                                continue;
+                            }
+                            landed = values.length === 1;
+                        }
+                        else if (op.method === 'fund_file_storage') {
+                            const file = await getFile(o.nearRpc, o.contractId, op.fileId);
+                            // Balance can be consumed by subsequent purchases. Absence cannot release this hold.
+                            if (op.fundingBalanceBefore === undefined || !file) {
+                                o.alert?.('reconcile_held');
+                                continue;
+                            }
+                            landed =
+                                file.purchaseStorageBalance >=
+                                    BigInt(op.fundingBalanceBefore) + BigInt(op.allocation);
+                            if (!landed) {
+                                o.alert?.('reconcile_held');
+                                continue;
+                            }
+                        }
+                        if (landed) {
+                            await o.ledger.finalizeStorage(op.id, tx.txHash, 'done');
+                            continue;
+                        }
+                        if (op.method === 'unlock')
+                            await o.ledger.defer(op.id, { method: 'unlock', args: tx.args.args }, op.requestHash, Date.now() + 30000);
+                        await o.ledger.reject(op.id);
+                        if (op.method === 'unlock')
+                            o.alert?.('paid_unlock_delayed');
+                    }
+                    catch (error) {
+                        o.alert?.(error instanceof AnnonError && error.code === 'settlement_pending'
+                            ? 'paid_work_full'
+                            : 'reconcile_held');
+                    }
+                    continue;
+                }
+            }
+            await o.ledger.result(op.id, result.rejected ? { txHash: tx.txHash, uncertain: true } : result);
+            continue;
+        }
+        if (reply?.result?.final_execution_status !== 'FINAL')
+            continue;
+        try {
+            const result = readOutcome(reply?.result, o.contractId, {
+                txHash: tx.txHash,
+                signer: tx.signer,
+                method: op.method,
+                args: tx.args,
+            });
+            if (result.state !== 'pending') {
+                if (op.method === 'register') {
+                    const file = await getFile(o.nearRpc, o.contractId, op.fileId);
+                    if (file?.termsHash === op.termsHash)
+                        await o.ledger.registered(op.fileId, op.termsHash);
+                    else {
+                        await o.ledger.reject(op.id, false);
+                        continue;
+                    }
+                }
+                await o.ledger.finalizeStorage(op.id, tx.txHash, result.state);
+            }
+        }
+        catch {
+            /* Unbound evidence cannot release a prepaid hold. */
+        }
+    }
+}
+/** Durable status never re-signs an unresolved operation. */
+async function durableStatus(r, o) {
+    const ledger = o.ledger;
+    if (!ledger)
+        return null;
+    const op = await ledger.operation(identity(r));
+    if (!op || op.stage === 'rejected')
+        return null;
+    if (op.requestHash !== requestHash(requestBinding(r)))
+        return fail('bad_request');
+    signedByItsWallet(r, o.contractId, {
+        baseUsdc: o.usdc,
+        ...(o.nearUsdc ? { nearUsdc: o.nearUsdc } : {}),
+    });
+    if (!op.tx)
+        return 'pending';
+    if (op.compact && op.stage === 'submitted')
+        return op.result ?? { txHash: op.tx.txHash };
+    if (r.method === 'register') {
+        const file = await getFile(o.nearRpc, o.contractId, op.fileId).catch(() => null);
+        if (file?.termsHash === op.termsHash)
+            await ledger.registered(op.fileId, op.termsHash);
+        else if (op.tx) {
+            const reply = await lookUp(o.nearRpc, op.tx.txHash, op.tx.signer);
+            if (reply?.result?.final_execution_status === 'FINAL') {
+                try {
+                    readOutcome(reply?.result, o.contractId, {
+                        txHash: op.tx.txHash,
+                        signer: op.tx.signer,
+                        method: r.method,
+                        args: op.tx.args,
+                    });
+                    // An unavailable file read does not prove rejection. Read final state again before releasing.
+                    const final = await getFile(o.nearRpc, o.contractId, op.fileId);
+                    if (final?.termsHash === op.termsHash)
+                        await ledger.registered(op.fileId, op.termsHash);
+                    else if (!final) {
+                        await ledger.reject(op.id, false);
+                        return null;
+                    }
+                }
+                catch {
+                    /* Preserve unresolved registration evidence. */
+                }
+            }
+        }
+    }
+    if (!op.tx)
+        return 'pending';
+    if (r.method === 'unlock' &&
+        op.storageFinalized &&
+        op.at + (o.policy.holdMs ?? HOLD) <= Date.now() &&
+        !(await getPurchase(o.nearRpc, o.contractId, identity(r).slice('unlock:'.length)))) {
+        await ledger.retire(op.id, op.tx.txHash);
+        return null;
+    }
+    if (r.method === 'claim_key' && op.at + (o.policy.holdMs ?? HOLD) <= Date.now()) {
+        const tx = op.tx;
+        if (op.finalState === 'released')
+            return op.result ?? { txHash: tx.txHash };
+        let reads = statusReads.get(ledger);
+        if (!reads) {
+            reads = new Map();
+            statusReads.set(ledger, reads);
+        }
+        const key = `${op.id}|${tx.txHash}`;
+        const previous = reads.get(key);
+        if (previous)
+            return previous;
+        const refresh = (async () => {
+            const reply = await lookUp(o.nearRpc, tx.txHash, tx.signer);
+            if (reply?.result?.final_execution_status === 'FINAL') {
+                try {
+                    const result = readOutcome(reply?.result, o.contractId, {
+                        txHash: tx.txHash,
+                        signer: tx.signer,
+                        method: r.method,
+                        args: tx.args,
+                    });
+                    if (result.state !== 'pending')
+                        await ledger.finalizeStorage(op.id, tx.txHash, result.state);
+                    if (result.state !== 'released' && result.state !== 'pending')
+                        await ledger.retire(op.id, tx.txHash);
+                }
+                catch {
+                    /* An unbound outcome cannot authorize a fresh send. */
+                }
+            }
+            const current = await ledger.operation(op.id);
+            if (!current || current.stage === 'rejected')
+                return null;
+            return (current.result ??
+                (current.tx
+                    ? { txHash: current.tx.txHash, uncertain: true }
+                    : 'pending'));
+        })();
+        reads.set(key, refresh);
+        try {
+            return await refresh;
+        }
+        finally {
+            reads.delete(key);
+        }
+    }
+    return op.result ?? { txHash: op.tx.txHash, uncertain: true };
+}
+export { durableStatus };

package/dist/relay/relay-request.d.ts

@@ -0,0 +1,6 @@
+/** Relay request canonicalization, contract arguments and operation identity. */
+import { type SettlementAssets } from '../settle-near/terms.js';
+import { type RelayRequest } from './relay-types.js';
+export declare function canonicalRequest(input: unknown, assets?: SettlementAssets): RelayRequest;
+/** Contract wire shape: unlock and identity calls wrap args; claim_key is flat. */
+export declare const contractArgs: (r: RelayRequest) => object;