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

package/dist/pay/settle.js

@@ -0,0 +1,308 @@
+/**
+ * A seller settles each purchase once (x402-annon.md section 10). Two records in the seller's store: the
+ * payment id bound to the payload it first came with, and the purchase `(network, asset, from,
+ * nonce)` with its state. The answer always follows the purchase's state now; a purchase the store
+ * doesn't know, or whose settlement is unclear, is read from Base by its nonce before anything is
+ * decided. Settlement itself goes through the server's facilitator, any standard x402 one.
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+import { getConfig, getFile } from '../near/rpc.js';
+import { authorizationState, balanceOf, block, fail, head, PayError, paymentStatus, } from './base.js';
+import { toHex } from './eip3009.js';
+import { checkTerms, forFacilitator, readPayload, verifyPayment, } from './seller.js';
+import { BASE_NETWORK } from './x402.js';
+/** A facilitator call is aborted after this; the lease outlasts it, so no two overlap. */
+const FACILITATOR_TIMEOUT_MS = 50_000;
+const LEASE_MARGIN_SECONDS = 10;
+/** After a facilitator call that did not settle, the next one waits this long. */
+export const RETRY_SECONDS = 10;
+/** The longest window a payload this seller accepts can have (x402-annon.md section 4). */
+const MAX_WINDOW_SECONDS = 240;
+const canonical = (v) => Array.isArray(v)
+    ? v.map(canonical)
+    : v !== null && typeof v === 'object'
+        ? Object.fromEntries(Object.keys(v)
+            .sort()
+            .map((k) => [k, canonical(v[k])]))
+        : v;
+/** The payload as data, key order aside: the same payload always gives the same fingerprint. */
+const fingerprint = (header) => {
+    const json = new TextDecoder().decode(Uint8Array.from(atob(header.trim()), (c) => c.charCodeAt(0)));
+    return toHex(sha256(new TextEncoder().encode(JSON.stringify(canonical(JSON.parse(json))))));
+};
+const now = () => Math.floor(Date.now() / 1000);
+/** The first block at or before Unix time `t`, from the head back at about five blocks a second. */
+async function blockAt(url, t) {
+    const h = await head(url);
+    let n = Math.max(0, h.number - Math.max(0, h.timestamp - t) * 5);
+    for (;;) {
+        const b = await block(url, n);
+        if (b.timestamp <= t || n === 0)
+            return n;
+        n = Math.max(0, n - (b.timestamp - t) * 5 - 1);
+    }
+}
+/**
+ * Settles a payload, or answers it from the state of its purchase. Throws `PayError`:
+ * `taken_down` (410) first, whatever the state; `bad_requirements`, `bad_signature` for a payload
+ * whose purchase terms are wrong; `payment_id_conflict` (409); the refusals of `verifyPayment` for
+ * a new payment (`sales_stopped`, a deadline too long, a changed offer); `payment_expired` for a
+ * purchase that can no longer be paid; `settlement_pending` when it is under way or unclear: send
+ * the same payload again later.
+ */
+/** Where `settle` keeps a purchase: its identity (x402-annon.md section 10). */
+export const purchaseRecordKey = (usdc, payer, nonce) => `annon/seller/purchase/${BASE_NETWORK}/${usdc}/${payer}/${nonce}`;
+export async function settle(header, o) {
+    const file = await getFile(o.nearRpc, o.contractId, o.fileId);
+    if (!file)
+        return fail('unknown_file', 'the file is not registered on the Annon contract');
+    if (file.takenDown)
+        fail('taken_down', `the file was taken down (${file.takenDown})`);
+    if (!file.terms.base)
+        fail('route_unavailable', 'This file does not support the selected payment route.');
+    const { usdc } = await getConfig(o.nearRpc, o.contractId);
+    const c = checkTerms(header, {
+        contractId: o.contractId,
+        fileId: o.fileId,
+        usdc,
+        price: file.price,
+        payTo: file.payTo,
+        termsHash: file.termsHash,
+    });
+    const scope = o.scope ?? `${o.contractId}/${o.fileId}/${o.url}`;
+    const bindId = async () => {
+        if (c.paymentId)
+            await bind(o, `annon/seller/id/${scope}/${c.paymentId}`, header, c, purchaseRecordKey(usdc, c.payer, c.nonce));
+    };
+    const timeout = o.facilitatorTimeoutMs ?? FACILITATOR_TIMEOUT_MS;
+    const lease = Math.ceil(timeout / 1000) + LEASE_MARGIN_SECONDS;
+    const key = purchaseRecordKey(usdc, c.payer, c.nonce);
+    const payTo = file.payTo;
+    const price = file.price;
+    const onBase = (r) => paymentStatus(o.baseRpc, {
+        usdc,
+        to: payTo,
+        from: c.payer,
+        nonce: c.nonce,
+        price,
+        block: r.searchFromBlock,
+        validBefore: BigInt(r.validBefore),
+    });
+    const answerOf = (r) => r.state === 'settled'
+        ? {
+            state: 'settled',
+            transaction: r.transaction,
+            network: BASE_NETWORK,
+            payer: c.payer,
+            buyerKey: c.buyerKey,
+            nonce: c.nonce,
+        }
+        : { state: 'pending', transaction: r.transaction, network: BASE_NETWORK };
+    /**
+     * The answer a record gives without another facilitator call: settled, pending with its hash, or
+     * expired; anything else is still being settled.
+     */
+    const answerFrom = (r, why = 'this purchase is being settled') => {
+        if (r?.state === 'settled' || (r?.state === 'submitted' && r.transaction))
+            return answerOf(r);
+        if (r?.state === 'unpaid')
+            return fail('payment_expired', 'this purchase can no longer be paid');
+        return fail('settlement_pending', `${why}; send it again shortly`);
+    };
+    /** After a write that lost: the record that won decides the answer. */
+    const winner = async () => answerFrom((await o.store.load(key)));
+    /** The purchase as Base shows it, written to the store; null if another writer came first. */
+    const fromChain = async (r, s, base) => {
+        let next;
+        if (s.state === 'paid') {
+            // Settled only if the payment's own block is on the chain at or below Base safe: its height
+            // alone could belong to a block a reorg replaced.
+            const safe = await block(o.baseRpc, 'safe');
+            const log = s.logs[0];
+            const canonical = log && log.block_number <= safe.number ? await block(o.baseRpc, log.block_number) : null;
+            const onSafe = !!log && canonical?.hash === `0x${log.block_hash}`;
+            next = { ...base, state: onSafe ? 'settled' : 'submitted', transaction: s.txHash };
+        }
+        else {
+            next = { ...base, state: 'unpaid' };
+        }
+        next = { ...next, revision: r ? r.revision + 1 : 0, leaseUntil: base.leaseUntil };
+        // A purchase first seen already on Base is recorded here: indexed first, as in the loop.
+        if (s.state === 'paid')
+            await bindId();
+        if (!r)
+            await o.beforeRecord?.(key, c.payer);
+        if (!(await o.store.compareAndSet(key, r, next)))
+            return null;
+        if (next.state === 'unpaid')
+            fail('payment_expired', 'this purchase can no longer be paid');
+        return answerOf(next);
+    };
+    for (let tries = 0; tries < 4; tries++) {
+        const r = (await o.store.load(key));
+        if (r)
+            await bindId();
+        if (r?.state === 'settled')
+            return answerOf(r);
+        if (r?.state === 'submitted' && r.leaseUntil > now())
+            return answerOf(r);
+        if (r?.state === 'unpaid')
+            return fail('payment_expired', 'this purchase can no longer be paid');
+        // A purchase already recorded is settled with its recorded payload, never another one: another
+        // payload of the same nonce has not passed the checks of a new payment (x402-annon.md section 10).
+        const base = {
+            kind: 'purchase',
+            id: key,
+            revision: 0,
+            state: 'processing',
+            header: r ? r.header : header,
+            validBefore: r ? r.validBefore : c.validBefore.toString(),
+            searchFromBlock: r?.searchFromBlock ??
+                (await blockAt(o.baseRpc, Number(c.validBefore) - MAX_WINDOW_SECONDS)),
+            leaseUntil: 0,
+            submissionAttempted: r?.submissionAttempted ?? false,
+            ...(r?.transaction ? { transaction: r.transaction } : {}),
+        };
+        const s = await onBase(base);
+        if (!r && s.state !== 'paid' && s.state !== 'pending')
+            fail('payment_expired');
+        if (s.state !== 'pending') {
+            const answer = await fromChain(r, s, { ...base, leaseUntil: r?.leaseUntil ?? 0 });
+            if (answer)
+                return answer;
+            continue;
+        }
+        // Another request's facilitator call may be running: not a second one now.
+        if (r && r.leaseUntil > now())
+            return answerFrom(r);
+        // A purchase never seen before is a new payment: every check of section 4.
+        if (!r) {
+            await verifyPayment(header, o);
+            const checkedHead = await head(o.baseRpc);
+            if ((await balanceOf(o.baseRpc, usdc, c.payer, checkedHead.number)) < price)
+                fail('insufficient_balance');
+            if (await authorizationState(o.baseRpc, usdc, c.payer, c.nonce, checkedHead.number))
+                fail('payment_rejected');
+            await o.beforeSettle?.(file);
+            await bindId();
+            await o.beforeRecord?.(key, c.payer);
+        }
+        const claimed = {
+            ...base,
+            revision: r ? r.revision + 1 : 0,
+            state: r?.state ?? 'processing',
+            leaseUntil: now() + lease,
+        };
+        if (!(await o.store.compareAndSet(key, r, claimed)))
+            continue;
+        // The lease started before the write: what is left of it, less the margin, bounds the call.
+        const left = (claimed.leaseUntil - LEASE_MARGIN_SECONDS - now()) * 1000;
+        if (left <= 0)
+            return answerFrom(claimed);
+        return submit(claimed, Math.min(timeout, left));
+    }
+    // Every write lost to another request: its record decides the answer.
+    return winner();
+    async function submit(r, budget) {
+        const attempted = { ...r, revision: r.revision + 1, submissionAttempted: true };
+        if (!(await o.store.compareAndSet(key, r, attempted)))
+            return winner();
+        r = attempted;
+        let res;
+        // The recorded payload with its own offer, exactly as it was accepted.
+        const offer = readPayload(r.header).accepted;
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(new Error('facilitator timed out')), budget);
+        try {
+            res = await Promise.race([
+                o.facilitator(forFacilitator(r.header, offer), { signal: abort.signal }),
+                new Promise((_, no) => abort.signal.addEventListener('abort', () => no(abort.signal.reason))),
+            ]);
+        }
+        catch {
+        }
+        finally {
+            clearTimeout(timer);
+            abort.abort();
+        }
+        const hash = res?.transaction;
+        if (hash && (res?.success || res?.errorReason === 'settlement_pending')) {
+            const submitted = {
+                ...r,
+                revision: r.revision + 1,
+                state: 'submitted',
+                leaseUntil: now() + (o.settlementPollSeconds ?? RETRY_SECONDS),
+                transaction: hash,
+            };
+            if (!(await o.store.compareAndSet(key, r, submitted)))
+                return winner();
+            const s = await onBase(submitted);
+            if (s.state === 'pending')
+                return answerOf(submitted);
+            return (await fromChain(submitted, s, submitted)) ?? winner();
+        }
+        // Unclear or refused: Base is still read on every request, but the facilitator is called
+        // again only after RETRY_SECONDS, the Retry-After a host sends, so retries and repeated downloads can't
+        // turn one purchase into a call per request. A purchase already broadcast keeps its answer:
+        // pending, with its hash.
+        const released = {
+            ...r,
+            revision: r.revision + 1,
+            leaseUntil: now() + RETRY_SECONDS,
+            submissionAttempted: res?.submissionAttempted === false ? false : (r.submissionAttempted ?? true),
+        };
+        if (!(await o.store.compareAndSet(key, r, released)))
+            return winner();
+        if (res?.errorReason === 'facilitator_busy' || res?.errorReason === 'payer_busy')
+            fail('facilitator_busy');
+        if (res?.errorReason === 'unavailable' || res?.errorReason === 'gas_price_too_high') {
+            const error = new PayError('unavailable');
+            if (typeof res.retryAfterSeconds === 'number' &&
+                Number.isSafeInteger(res.retryAfterSeconds) &&
+                res.retryAfterSeconds >= 0)
+                error.retryAfterSeconds = res.retryAfterSeconds;
+            throw error;
+        }
+        if (res?.errorReason === 'payment_expired')
+            fail('payment_expired');
+        if (res?.errorReason === 'payment_rejected' ||
+            res?.errorReason === 'invalid_authorization' ||
+            res?.errorReason === 'authorization_used')
+            fail('payment_rejected');
+        return answerFrom(released, `the facilitator did not settle it${res?.errorReason ? ` (${res.errorReason})` : ''}`);
+    }
+}
+/** The payment id bound to this payload, or `payment_id_conflict` if it came with another. */
+async function bind(o, key, header, c, purchaseKey) {
+    const fp = fingerprint(header);
+    for (;;) {
+        const b = (await o.store.load(key));
+        if (b) {
+            if (b.fingerprint !== fp) {
+                throw new PayError('payment_id_conflict', 'this payment id came with another payload');
+            }
+            return;
+        }
+        const created = {
+            kind: 'id',
+            id: key,
+            revision: 0,
+            fingerprint: fp,
+            keepUntil: c.validBefore.toString(),
+            purchaseKey,
+        };
+        if (await o.store.compareAndSet(key, null, created))
+            return;
+    }
+}
+/** The x402 v2 `SettleResponse` for a settlement: the `PAYMENT-RESPONSE` header's content. */
+export function paymentResponse(s) {
+    return s.state === 'settled'
+        ? { success: true, transaction: s.transaction, network: s.network, payer: s.payer }
+        : {
+            success: false,
+            errorReason: 'settlement_pending',
+            transaction: s.transaction,
+            network: s.network,
+        };
+}

package/dist/pay/split.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Revenue splits through the registered Base payment address: when a file's `pay_to` is
+ * an 0xSplits v2 split, the integrator shows the seller where the money goes before they sign. The
+ * split keeps only `keccak256(abi.encode(split))` on chain, so the caller supplies the split and how
+ * it was created (both from its `SplitCreated` event, or its own config).
+ *
+ * The address alone proves the rest: an 0xSplits V2.2 factory deploys each split with CREATE2 from
+ * a salt that commits to the split and its owner, and initializes it in the same transaction. If the
+ * address recomputed for `owner = 0` is `pay_to` and its code is the factory's clone, the canonical
+ * factory made it with these terms and nobody ever controlled it (no left-over USDC approvals from a
+ * former owner). Code that merely answers `splitHash()` and `owner()` correctly does not pass.
+ */
+/** An 0xSplits v2 split, as `SplitV2Lib.Split`. */
+export interface Split {
+    recipients: string[];
+    /** Shares, in any unit below 2^128 in total; each recipient gets `amount * allocation / total`. */
+    allocations: bigint[];
+    totalAllocation: bigint;
+    /** Reward to the distributor the `distribute` caller names, in millionths (at most 65 535, 6.5535%). */
+    distributionIncentive: number;
+}
+/** `abi.encode(split)`: the struct as one dynamic tuple (offset, then head, then the two arrays). */
+export declare function encodeSplit(s: Split): Uint8Array;
+export declare const splitHash: (s: Split) => string;
+export interface SplitTerms {
+    /** `push`: `distribute` pays the wallets; `pull`: it credits them in the SplitsWarehouse. */
+    kind: 'push' | 'pull';
+    /** Each recipient and its share of a payment, after the distribution reward, in percent. */
+    shares: {
+        recipient: string;
+        percent: number;
+    }[];
+    /** The reward to the distributor the `distribute` caller names, in percent. */
+    distributorPercent: number;
+}
+/** How the factory named the split: `createSplitDeterministic`'s salt or `createSplit`'s nonce. */
+export type SplitOrigin = {
+    salt: string;
+} | {
+    nonce: bigint;
+};
+/**
+ * The 0xSplits V2.2 factories on Base (`deployments/8453.json` at 0159376) and the implementation
+ * each clones (`SPLIT_WALLET_IMPLEMENTATION()`, read 6 Nov 2026). Push pays recipients' wallets at
+ * `distribute`; pull credits them in the SplitsWarehouse, from which they withdraw.
+ * Note: V2.2 only; older factories after their clones are checked on chain.
+ */
+export declare const SPLIT_FACTORIES: readonly [{
+    readonly kind: "push";
+    readonly factory: "0x8e8eb0cc6ae34a38b67d5cf91aca38f60bc3ecf4";
+    readonly implementation: "0x1e2086a7e84a32482ac03000d56925f607ccb708";
+}, {
+    readonly kind: "pull";
+    readonly factory: "0x6b9118074ab15142d7524e8c4ea8f62a3bdb98f1";
+    readonly implementation: "0x98254aedb6b2c30b70483064367f0ba24ca86244";
+}];
+/** The 89-byte runtime of `Clone.sol` (a minimal proxy with an ETH `receive`) for `implementation`. */
+export declare const cloneCode: (implementation: string) => string;
+/** Where `factory` deploys `split` for `owner` (`SplitFactoryV2._getSalt`, `Clone.initCodeHash`). */
+export declare function splitAddress(f: {
+    factory: string;
+    implementation: string;
+}, split: Split, owner: string, origin: SplitOrigin): string;
+/**
+ * Most recipients a split may have here. A push `distribute` makes one USDC transfer (about 30k to
+ * 60k gas) per recipient in one transaction; 100 stays far below Base's gas limits.
+ */
+export declare const MAX_RECIPIENTS = 100;
+/** Canonical hosted v1 salt. Complete ordered split parameters determine reuse. */
+export declare function hostedSplitSalt(): string;
+/** A transaction to send from any wallet on Base. */
+export interface SplitCall {
+    to: string;
+    data: string;
+}
+/**
+ * The transaction that creates `split` as an ownerless (immutable) split of `kind` at the address
+ * it returns. Send it from any wallet on Base. Keep `split` and `salt`: `readSplit` needs them, and
+ * the same terms and salt always give the same address (sent again, the factory just returns it).
+ */
+export declare function createSplit(kind: 'push' | 'pull', split: Split, salt: string): SplitCall & {
+    address: string;
+};
+/**
+ * The calls that pay out what the split at `address` holds in `token`: `distribute` first, then
+ * for a pull split one SplitsWarehouse withdrawal per recipient (and for `distributor`, if the
+ * split pays a reward), each paying that address's wallet. Anyone may send them; the sender pays
+ * the gas and `distributor` gets the split's distribution reward. `payoutCall` sends them as one
+ * transaction. Sent one by one, each goes after the one before it is in a block: a wallet
+ * estimates a withdrawal on the current state, and before `distribute` lands there is nothing to
+ * withdraw.
+ */
+/** Multicall3, at the same address on Base as on every chain it is deployed to. */
+export declare const MULTICALL3 = "0xca11bde05977b3631167028862be2a173976ca11";
+/**
+ * The payout as one transaction through Multicall3 `aggregate3`. `distribute` must succeed or the
+ * whole transaction reverts; each withdrawal may fail on its own (nothing to pay, a USDC-blacklisted
+ * or paused recipient) without stopping the others. A push split's payout is already one call.
+ * Check the receipt's warehouse events for who was paid: a transaction that succeeded may still
+ * hold a failed withdrawal.
+ */
+export declare function payoutCall(kind: 'push' | 'pull', address: string, split: Split, token: string, distributor: string): SplitCall;
+export declare function payoutCalls(kind: 'push' | 'pull', address: string, split: Split, token: string, distributor: string): SplitCall[];
+/**
+ * Checks that `address` on Base is the ownerless 0xSplits V2.2 split `split`, created as `origin`
+ * says, and returns what it pays whom. Throws `PayError` `bad_requirements` otherwise.
+ * It proves the terms, not that a payout will go through: Circle can blacklist a recipient (a push
+ * split then pays nobody, a pull split only not that one) or the split itself, and shares round down.
+ */
+export declare function readSplit(baseRpc: string, address: string, split: Split, origin: SplitOrigin): Promise<SplitTerms>;
+/**
+ * Reads an ownerless, unpaused V2.2 clone with these exact terms without its creation salt or
+ * nonce. This checks current code and state only; `readSplit` also proves ownerless creation.
+ */
+export declare function readSplitState(baseRpc: string, address: string, split: Split): Promise<SplitTerms>;

package/dist/pay/split.js

@@ -0,0 +1,256 @@
+/**
+ * Revenue splits through the registered Base payment address: when a file's `pay_to` is
+ * an 0xSplits v2 split, the integrator shows the seller where the money goes before they sign. The
+ * split keeps only `keccak256(abi.encode(split))` on chain, so the caller supplies the split and how
+ * it was created (both from its `SplitCreated` event, or its own config).
+ *
+ * The address alone proves the rest: an 0xSplits V2.2 factory deploys each split with CREATE2 from
+ * a salt that commits to the split and its owner, and initializes it in the same transaction. If the
+ * address recomputed for `owner = 0` is `pay_to` and its code is the factory's clone, the canonical
+ * factory made it with these terms and nobody ever controlled it (no left-over USDC approvals from a
+ * former owner). Code that merely answers `splitHash()` and `owner()` correctly does not pass.
+ */
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { concatParts as concat } from '../bytes.js';
+import { fail, getCode, head, PayError, viewWord } from './base.js';
+import { addressWord, fromHex, toHex, word } from './eip3009.js';
+/** `abi.encode(split)`: the struct as one dynamic tuple (offset, then head, then the two arrays). */
+export function encodeSplit(s) {
+    const n = s.recipients.length;
+    if (s.allocations.length !== n)
+        throw new TypeError('one allocation per recipient');
+    if (!Number.isInteger(s.distributionIncentive) ||
+        s.distributionIncentive < 0 ||
+        s.distributionIncentive > 0xffff) {
+        throw new RangeError('distributionIncentive is a uint16');
+    }
+    const recipients = concat([word(BigInt(n)), ...s.recipients.map(addressWord)]);
+    const allocations = concat([word(BigInt(n)), ...s.allocations.map(word)]);
+    const head = concat([
+        word(4n * 32n),
+        word(4n * 32n + BigInt(recipients.length)),
+        word(s.totalAllocation),
+        word(BigInt(s.distributionIncentive)),
+    ]);
+    return concat([word(32n), head, recipients, allocations]);
+}
+export const splitHash = (s) => toHex(keccak_256(encodeSplit(s)));
+/**
+ * The 0xSplits V2.2 factories on Base (`deployments/8453.json` at 0159376) and the implementation
+ * each clones (`SPLIT_WALLET_IMPLEMENTATION()`, read 6 Nov 2026). Push pays recipients' wallets at
+ * `distribute`; pull credits them in the SplitsWarehouse, from which they withdraw.
+ * Note: V2.2 only; older factories after their clones are checked on chain.
+ */
+export const SPLIT_FACTORIES = [
+    {
+        kind: 'push',
+        factory: '0x8e8eb0cc6ae34a38b67d5cf91aca38f60bc3ecf4',
+        implementation: '0x1e2086a7e84a32482ac03000d56925f607ccb708',
+    },
+    {
+        kind: 'pull',
+        factory: '0x6b9118074ab15142d7524e8c4ea8f62a3bdb98f1',
+        implementation: '0x98254aedb6b2c30b70483064367f0ba24ca86244',
+    },
+];
+/** The 89-byte runtime of `Clone.sol` (a minimal proxy with an ETH `receive`) for `implementation`. */
+export const cloneCode = (implementation) => `0x36602c57343d527f9e4ac34f21c619cefc926c8bd93b54bf5a39c7ab2127a895af1cc0691d7e3dff593da1005b3d3d3d3d363d3d37363d73${implementation.slice(2).toLowerCase()}5af43d3d93803e605757fd5bf3`;
+/** Where `factory` deploys `split` for `owner` (`SplitFactoryV2._getSalt`, `Clone.initCodeHash`). */
+export function splitAddress(f, split, owner, origin) {
+    // abi.encode(split, owner): the tuple's offset, the owner, then the tuple.
+    const params = concat([word(64n), addressWord(owner), encodeSplit(split).subarray(32)]);
+    let salt;
+    if ('salt' in origin) {
+        salt = keccak_256(concat([params, fromHex(origin.salt, 32, 'salt')]));
+    }
+    else {
+        salt = keccak_256(concat([keccak_256(params), word(origin.nonce)]));
+    }
+    // CREATE (9 bytes) + runtime (89) + 15 zero bytes: Clone.sol hashes 0x71 bytes from 0x0f.
+    const init = concat([
+        fromHex('0x60593d8160093d39f3', 9, 'init'),
+        fromHex(cloneCode(f.implementation), 89, 'clone'),
+        new Uint8Array(15),
+    ]);
+    const h = keccak_256(concat([Uint8Array.of(0xff), fromHex(f.factory, 20, 'factory'), salt, keccak_256(init)]));
+    return toHex(h.subarray(12));
+}
+const ZERO = `0x${'00'.repeat(20)}`;
+const selector = (sig) => toHex(keccak_256(new TextEncoder().encode(sig)).subarray(0, 4));
+const calldata = (sig, ...parts) => selector(sig) + toHex(concat(parts)).slice(2);
+const SPLIT_TUPLE = '(address[],uint256[],uint256,uint16)';
+/** The split's tuple without the leading offset word, for a call that has other arguments. */
+const tuple = (s) => encodeSplit(s).subarray(32);
+/** The SplitsWarehouse on Base, where a pull split credits its recipients. */
+const SPLITS_WAREHOUSE = '0x8fb66f38cf86a3d5e8768f8f1754a24a6c661fb8';
+/**
+ * Most recipients a split may have here. A push `distribute` makes one USDC transfer (about 30k to
+ * 60k gas) per recipient in one transaction; 100 stays far below Base's gas limits.
+ */
+export const MAX_RECIPIENTS = 100;
+/** Terms the SDK accepts, whether it creates the split or reads one. */
+function checkTerms(s) {
+    if (s.recipients.length > MAX_RECIPIENTS) {
+        fail('bad_requirements', `the split has more than ${MAX_RECIPIENTS} recipients`);
+    }
+    // USDC refuses any transfer to address 0: a push split could never pay anyone, a pull split
+    // would keep that share for good.
+    if (s.recipients.some((r) => BigInt(r) === 0n)) {
+        fail('bad_requirements', 'the split pays the zero address');
+    }
+    if (s.totalAllocation < 1n)
+        fail('bad_requirements', 'the split allocates nothing');
+    // `distribute` computes amount * allocation / total in uint256. With the total below 2^128 that
+    // cannot overflow for any amount below 2^128 (USDC's supply is far smaller); above, a large
+    // enough payment would, and the money would stay in the split.
+    if (s.totalAllocation >= 2n ** 128n) {
+        fail('bad_requirements', 'the split allocations are too large to distribute');
+    }
+}
+/** Canonical hosted v1 salt. Complete ordered split parameters determine reuse. */
+export function hostedSplitSalt() {
+    return `0x${'00'.repeat(32)}`;
+}
+/**
+ * The transaction that creates `split` as an ownerless (immutable) split of `kind` at the address
+ * it returns. Send it from any wallet on Base. Keep `split` and `salt`: `readSplit` needs them, and
+ * the same terms and salt always give the same address (sent again, the factory just returns it).
+ */
+export function createSplit(kind, split, salt) {
+    checkTerms(split);
+    if (split.allocations.reduce((a, b) => a + b, 0n) !== split.totalAllocation) {
+        throw new RangeError('the allocations must add up to totalAllocation');
+    }
+    const f = SPLIT_FACTORIES.find((f) => f.kind === kind);
+    if (!f)
+        throw new TypeError('kind is push or pull');
+    const data = calldata(`createSplitDeterministic(${SPLIT_TUPLE},address,address,bytes32)`, word(128n), addressWord(ZERO), addressWord(ZERO), fromHex(salt, 32, 'salt'), tuple(split));
+    return { to: f.factory, data, address: splitAddress(f, split, ZERO, { salt }) };
+}
+/**
+ * The calls that pay out what the split at `address` holds in `token`: `distribute` first, then
+ * for a pull split one SplitsWarehouse withdrawal per recipient (and for `distributor`, if the
+ * split pays a reward), each paying that address's wallet. Anyone may send them; the sender pays
+ * the gas and `distributor` gets the split's distribution reward. `payoutCall` sends them as one
+ * transaction. Sent one by one, each goes after the one before it is in a block: a wallet
+ * estimates a withdrawal on the current state, and before `distribute` lands there is nothing to
+ * withdraw.
+ */
+/** Multicall3, at the same address on Base as on every chain it is deployed to. */
+export const MULTICALL3 = '0xca11bde05977b3631167028862be2a173976ca11';
+/**
+ * The payout as one transaction through Multicall3 `aggregate3`. `distribute` must succeed or the
+ * whole transaction reverts; each withdrawal may fail on its own (nothing to pay, a USDC-blacklisted
+ * or paused recipient) without stopping the others. A push split's payout is already one call.
+ * Check the receipt's warehouse events for who was paid: a transaction that succeeded may still
+ * hold a failed withdrawal.
+ */
+export function payoutCall(kind, address, split, token, distributor) {
+    const calls = payoutCalls(kind, address, split, token, distributor);
+    if (kind === 'push')
+        return calls[0];
+    // aggregate3((address target, bool allowFailure, bytes callData)[]): the array's offset, its
+    // length, one offset per element (from after the length), then each element.
+    const elements = calls.map((c, i) => {
+        const data = fromHex(c.data, (c.data.length - 2) / 2, 'callData');
+        const padded = new Uint8Array(Math.ceil(data.length / 32) * 32);
+        padded.set(data);
+        return concat([
+            addressWord(c.to),
+            word(i === 0 ? 0n : 1n),
+            word(96n),
+            word(BigInt(data.length)),
+            padded,
+        ]);
+    });
+    const offsets = [];
+    let at = 32n * BigInt(elements.length);
+    for (const e of elements) {
+        offsets.push(word(at));
+        at += BigInt(e.length);
+    }
+    return {
+        to: MULTICALL3,
+        data: calldata(`aggregate3((address,bool,bytes)[])`, word(32n), word(BigInt(elements.length)), ...offsets, ...elements),
+    };
+}
+export function payoutCalls(kind, address, split, token, distributor) {
+    // A pull split would credit the reward to address 0 for good; push could never distribute.
+    if (BigInt(distributor) === 0n)
+        throw new TypeError('distributor is the address that sends them');
+    const calls = [
+        {
+            to: address.toLowerCase(),
+            data: calldata(`distribute(${SPLIT_TUPLE},address,address)`, word(96n), addressWord(token), addressWord(distributor), tuple(split)),
+        },
+    ];
+    if (kind === 'pull') {
+        const paid = [...split.recipients, ...(split.distributionIncentive > 0 ? [distributor] : [])];
+        for (const r of new Set(paid.map((r) => r.toLowerCase()))) {
+            calls.push({
+                to: SPLITS_WAREHOUSE,
+                data: calldata('withdraw(address,address)', addressWord(r), addressWord(token)),
+            });
+        }
+    }
+    return calls;
+}
+/**
+ * Checks that `address` on Base is the ownerless 0xSplits V2.2 split `split`, created as `origin`
+ * says, and returns what it pays whom. Throws `PayError` `bad_requirements` otherwise.
+ * It proves the terms, not that a payout will go through: Circle can blacklist a recipient (a push
+ * split then pays nobody, a pull split only not that one) or the split itself, and shares round down.
+ */
+export async function readSplit(baseRpc, address, split, origin) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address))
+        throw new TypeError('address must be 0x and 20 bytes');
+    checkTerms(split);
+    const to = address.toLowerCase();
+    const f = SPLIT_FACTORIES.find((f) => splitAddress(f, split, ZERO, origin) === to);
+    if (!f) {
+        return fail('bad_requirements', `${address} is not an ownerless 0xSplits V2.2 split of these terms`);
+    }
+    return inspectSplit(baseRpc, to, split, [f]);
+}
+/**
+ * Reads an ownerless, unpaused V2.2 clone with these exact terms without its creation salt or
+ * nonce. This checks current code and state only; `readSplit` also proves ownerless creation.
+ */
+export async function readSplitState(baseRpc, address, split) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address))
+        throw new TypeError('address must be 0x and 20 bytes');
+    checkTerms(split);
+    return inspectSplit(baseRpc, address.toLowerCase(), split, SPLIT_FACTORIES);
+}
+async function inspectSplit(baseRpc, address, split, factories) {
+    const at = (await head(baseRpc)).number;
+    const code = await getCode(baseRpc, address, at);
+    const f = factories.find((f) => code === cloneCode(f.implementation));
+    if (!f)
+        return fail('bad_requirements', `${address} is not deployed as a known V2.2 clone`);
+    const read = (sig) => viewWord(baseRpc, address, selector(sig), at).catch((e) => {
+        // A reverted view is an invalid split; malformed or unavailable RPC replies stay retryable.
+        if (e instanceof PayError && e.code === 'refused') {
+            fail('bad_requirements', `${address} does not answer ${sig}: not an 0xSplits v2 split`);
+        }
+        throw e;
+    });
+    if ((await read('splitHash()')) !== splitHash(split)) {
+        fail('bad_requirements', 'the split on chain is not the one described');
+    }
+    if (BigInt(await read('owner()')) !== 0n) {
+        fail('bad_requirements', 'the split has an owner who could change where the money goes');
+    }
+    if (BigInt(await read('paused()')) !== 0n)
+        fail('bad_requirements', 'the split is paused');
+    const pct = (part, whole) => Number((part * 1000000n) / whole) / 10_000;
+    const kept = 1_000_000 - split.distributionIncentive;
+    return {
+        kind: f.kind,
+        shares: split.recipients.map((r, i) => ({
+            recipient: r.toLowerCase(),
+            percent: (pct(split.allocations[i] ?? 0n, split.totalAllocation) * kept) / 1_000_000,
+        })),
+        distributorPercent: split.distributionIncentive / 10_000,
+    };
+}