annon

NEAR settlement (draft 3)

How a file is sold for native USDC on NEAR, paid directly from a NEAR account or from any chain NEAR Intents 1Click supports, with a per-file split to recipients on EVM, Solana or NEAR, wallet based recovery, and no human power over money. Every file has the NEAR route and, optionally, the Base route (specs/x402-annon.md); both use the purchase commitment of §5.

One model (decision 10 Nov 2026): this document replaces the earlier registration, unlock, reopen and PAY2 version 1. The contract has one set of entry points (no _v2 names) and accepts nothing in the old formats; there is no backward compatibility, as nothing was in production.

Status: draft for implementation (11 Nov 2026). Byte layouts, texts and hashes here are normative: the contract (Rust) and the SDK (TypeScript) must produce identical vectors (vectors/near-settlement.json).

1. Encodings

  • Borsh as in borsh-js / borsh-rs: integers little-endian, String = u32 length + UTF-8, Vec<T> = u32 count + items, Option<T> = 0 or 1 then T, enums = u8 discriminant then the variant, fixed arrays without a length.
  • Hex in JSON and texts: lowercase, 0x prefix, except Solana ids in JSON (§2).
  • Domain-separated hashes: SHA256(tag ‖ 0x00 ‖ Borsh(…)) where tag is the ASCII string given.
  • NEAR USDC: 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1 (asset below). Amounts are USDC base units (6 decimals) as canonical decimal strings in JSON.

2. Identity

One type for sellers, split recipients, refund and recovery identities.

kind Borsh discriminant Borsh payload JSON id Text form
evm 0 [u8;20] 0x + 40 hex EVM 0x… (lowercase)
solana 1 [u8;32] (ed25519 public key) 64 hex, no 0x Solana <base58>
near 2 String (canonical NEAR AccountId) the account id NEAR <account>

JSON: {"kind":"evm","id":"0x…"}, keys in that order. The SDK accepts Solana base58 at its API and converts it. The Intents account of an identity is: EVM → the 0x address; Solana → the 64-hex key; NEAR → the account id (near/intents contracts/defuse/core/src/public_key.rs).

Authorization of an identity over an authoritative text T (UTF-8, \n line ends, no trailing newline):

  • evm: EIP-191 personal_sign of T; 65 bytes r ‖ s ‖ v, v ∈ {27, 28}, low s; recovers to the address. The SDK requires this strict signature encoding.
  • solana: Ed25519 over exactly UTF8(T) (no prefix, no prehash), 64 bytes; checked with env::ed25519_verify. The SDK refuses a wallet whose returned signed bytes differ from UTF8(T).
  • near: no signature; the call's predecessor must be the account (wallet transaction, 1 yocto attached where noted).

Signatures travel as {"kind":"evm"|"solana","sig":"0x…"}; near sends no auth object. The contract additionally accepts EVM recovery bytes v = 0/1, uppercase hex and EVM signatures without 0x; Solana signature hex may also be uppercase. The SDK deliberately requires lowercase 0x signature hex and EVM v = 27/28. Identity JSON on the wire remains canonical on both sides. The SDK uses strict Ed25519 verification (zip215: false); the NEAR host uses dalek non-strict verification. Adversarial small-order or noncanonical owner-created signatures may therefore be accepted by the host and refused by the SDK.

Distinct Identity kinds can share an Intents account: an implicit NEAR account equal to an EVM address or Solana hex key credits the same balance. They remain separate Borsh identities, split slots and recovery indexes (purchases_of indexes by Borsh Identity). This does not merge grants or authorizations.

Smart-contract wallets (Safe, ERC-1271, PDAs) cannot authorize; they can still pay (§5).

3. Registration (register)

3.1 Terms

Code
NearTerms   = { token: AccountId, price: u128, recipients: Vec<(Identity, u16 bps)>, remainder: u8 }
BaseTerms   = { usdc: [u8;20], price: u128, pay_to: [u8;20] }
Terms       = { network: String, contract: AccountId, file_id: [u8;32], seller: Identity,
                pay2_version: u8, cipher_hash: [u8;32], moderator: Option<AccountId>,
                near: NearTerms, base: Option<BaseTerms> }
terms_hash  = SHA256("annon/terms/v2" ‖ 0x00 ‖ Borsh(Terms))

Rules: network = near:mainnet (or near:testnet/sandbox in tests); 1 to 8 recipients, distinct, sorted by Borsh(Identity) bytes ascending; every bps > 0, sum 10 000; remainder < count; price > 0; token = the configured NEAR USDC (get_config.near_usdc). Mainnet defaults to native USDC; testnet and sandbox use the deployment token. SDK commitment encoders accept explicit nearUsdc / baseUsdc expectations; payment flows compare with the final deployment config. base, when present, is the Base route of x402-annon.md for this file: pay_to is usually a 0xSplits split built by the SDK from the same recipients (only possible when all are EVM); the contract does not check that split.

3.2 Seller authorization text

Code
Annon: list a file for sale
Signing this lets whoever holds the seller key below open the file.
contract: <contract>
file: 0x<file_id>
seller: <seller text form>
price: <price as USDC, minimal decimals: 0.2, 1, 0.000001> USDC on NEAR
split: <recipient text form> <bps/100 with 2 decimals>%   (one line per recipient, sorted)
remainder: <recipient text form>
base: <price> USDC on Base to 0x<pay_to> | base: none
cipher: 0x<cipher_hash>
moderator: <account> | (none)
terms: 0x<terms_hash>
seller key: 0x<48-byte BLS key>
valid until: <UTC, YYYY-MM-DD HH:MM:SS UTC>

register(args, auth); near sellers call it themselves; EVM and Solana sellers sign and may use the relayer. Optional args.file_budget is a positive yoctoNEAR string allocated from the caller's prepaid balance atomically with registration. It is outside signed Terms and seller authorization. The call uses one FunctionCall action. It stores the terms and requests CKD for the seller key. The seller key, like every one-time key (reopen_seller, reopen, the buyer key), must be a compressed G1 point in the prime-order subgroup and not the point at infinity: MPC would publish the file key in the clear for the point at infinity.

3.3 Header publication

The PAY2 v2 header is authenticated after CKD (the finished header needs the CKD answer):

  • EVM / Solana: the header's 65-byte trailer carries the signature over
    Code
    Annon: publish a file
    contract: <contract>
    file: 0x<file_id>
    header: 0x<SHA256(header[0 .. headerLen-65])>
    
  • NEAR: publish_header(file_id, header_hash) called by the seller; stored once (same hash is a no-op, another fails). The NEAR route sells nothing for a NEAR seller's file before this.

4. PAY2 (version 2)

The layout in specs/pay2.md is PAY2 version 2. Version 1 is no longer produced or accepted (byte 4 = 1 fails as an unsupported version):

Field Rule
Byte 4 2
Byte 7 auth kind: 0 EVM, 1 Solana, 2 NEAR
Trailer (65 bytes) kind 0: EIP-191 sig; kind 1: 64-byte Ed25519 sig + 1 zero byte; kind 2: 65 zero bytes, authenticated by the published hash (§3.3)

The kind must match the registered seller identity; unknown kinds and non-zero padding fail. The body hash covers the version byte. Previews keep package v: 1; checking a preview needs the registered seller to check the kind.

5. Purchase

5.1 Message

Sent as the msg of a direct ft_transfer_call of NEAR USDC to the contract, or as 1Click's customRecipientMsg. Compact JSON, keys in exactly this order, at most 1 024 UTF-8 bytes:

JSON
{"annon":2,"refund":{"kind":"evm","id":"0x…"},"purchase":{"network":"near:mainnet",
"contract":"<contract>","route":"near-usdc","asset":"<NEAR USDC>","file_id":"0x…",
"terms_hash":"0x…","price":"200000","nonce":"0x<32 random bytes>","buyer_key":"0x<48 bytes>",
"recovery":{"kind":"solana","id":"…"},"expires_at":"1794350000","purchase_id":"0x…"}}

The prefix {"annon":2,"refund":{"kind":"…","id":"…"}, is parsed first by a bounded parser (at most 160 bytes). A valid refund identity there fixes where any refund goes before anything else is read (§6).

5.2 Commitment

Code
Purchase    = { version: u8 (2), refund: Identity, network: String, contract: AccountId,
                route: u8 (0 near-usdc, 1 base-usdc), asset: String, file_id: [u8;32],
                terms_hash: [u8;32], price: u128, nonce: [u8;32], buyer_key: [u8;48],
                recovery: Identity, expires_at: u64 }
purchase_id = SHA256("annon/purchase/v2" ‖ 0x00 ‖ Borsh(Purchase))

Computed from decoded values, not JSON bytes; purchase_id in the message must equal it. The SDK generates nonce and the buyer key locally, checks that the buyer controls recovery (a signature) before showing payment instructions, and saves the encrypted purchase record first (§9). Default expiry: 1 hour after local quote preparation. Anyone may pay for anyone's purchase.

The recovery challenge is exactly (no trailing newline):

Code
Annon: verify purchase recovery
contract: <contract>
purchase: 0x<purchase_id>
recovery: <identity text form>

For NEAR recovery, use NEP-413 signMessage: message is this challenge, recipient is the contract ID, and nonce is 32 fresh random bytes. Sign Ed25519 over SHA256 of Borsh u32(2^31+413), message: String, nonce: [u8;32], recipient: String, callbackUrl: Option<String> (absent in the SDK). Verify the signature and returned account, then query RPC view_access_key with finality: "final", that account and public key. Require permission: "FullAccess"; a function-call key or absent key is refused before payment instructions or a payment signature. This off-chain proof does not authorize a contract method; NEAR contract authorization still uses the predecessor.

5.3 Base route with the same commitment

For route = base-usdc the buyer signs EIP-3009 (x402-annon.md) with

Code
base_nonce = keccak256("annon/base-payment/v2" ‖ 0x00 ‖ purchase_id)

For this route the commitment's network is exactly eip155:8453 and asset the lowercase 0x address of Base USDC configured in the contract; anything else is refused. unlock({"args":{"purchase":"<canonical §5.1 MESSAGE string>","logs":[...],"header":null}}) verifies the Base logs through MPC (Safe finality) against terms.base and this nonce, and records the purchase with its recovery identity. refund is carried but unused on Base (EIP-3009 moves exactly the price). The purchase field is the same canonical message string used by the NEAR route, not a decoded Purchase object.

The SDK must set EIP-3009 validBefore <= expires_at and the seller checks that bound before settlement. The Base contract path does not check expires_at; USDC's authorization deadline bounds the payment. There is no unlock-time expiry check. While sales are open, header may be null. After sales stop, header must be "0x<RLP of the payment block header>", matching the proved log's block hash and number. A payment is allowed if its Base block time is at most sales_stopped_at + STOP_SETTLEMENT_SECONDS, where STOP_SETTLEMENT_SECONDS = 300 (inclusive). An allowed payment remains unlockable regardless of when unlock runs. A stop during the MPC callback can require a retry with the header. A takedown refuses every new key request (unlock, claim_key, reopen, reopen_seller); a request already sent to MPC before the takedown may still complete, because its answer is published on chain by MPC and cannot be withdrawn.

6. Receiving USDC (ft_on_transfer)

  1. The predecessor must be the configured NEAR USDC. Any other token: return the full amount.
  2. Parse the refund prefix. If missing or invalid: refuse (return the full amount). A direct NEAR payer gets the NEP-141 refund; a 1Click delivery goes back to the quote's own Intents account (not to the buyer). Only non-Annon or broken clients reach this.
  3. With a valid refund identity, the contract keeps the tokens (returns 0) and records a delivery with exactly one disposition:
Condition Disposition
Valid; amount = price accept the purchase; split the price
Valid; amount > price accept; split the price; refund the excess
Amount < price refund all; the purchase id is not consumed
Purchase id already accepted refund all
Unknown file, NEAR route absent, wrong terms hash/price/asset/route/contract/network refund all
Expired, sales stopped (by callback time), taken down refund all
Invalid body JSON, duplicate/unknown fields, bad commitment, invalid buyer key or recovery identity refund all

The buyer key must decode as a compressed BLS12-381 G1 point in the prime-order subgroup, not the identity. The receiver schedules no promise and never returns a promise.

  1. Storage. An otherwise valid acceptance requires 4 096 bytes' worth of the file's purchase_storage_balance, outside signed Terms. Acceptance debits actual flushed storage for the whole write, including permanent purchase/recovery and temporary delivery/index records. The receiver reserve is not an admission gate for funded files. If the file budget is short, emit file_storage_low and refund with reason 11 (FILE_STORAGE_LOW) without consuming the purchase ID. Rejected payments never spend file budgets. They create a refund-only delivery using receiver reserve working capital, or append a refund leaf (§8) with no variable-size write when that reserve is short. Claims, recovery and caller-funded Base unlock have no file-budget requirement.

7. Payouts and refunds

Every obligation (a split share or a refund) is paid by crediting the beneficiary's Intents balance, in two steps per delivery:

  1. Fund: ft_transfer_call(intents.near, amount, msg = <this contract's account>) moves the delivery's USDC into the contract's own Intents balance; the callback reads the final used amount (NEP-141) and records exactly that.
  2. Pay: per obligation, intents.near::mt_transfer(receiver_id = <beneficiary Intents id>, token_id = "nep141:<NEAR USDC>", amount, memo = "annon:<delivery>:<slot>:<attempt>"), 1 yocto. Success → paid; failure → pending again (the transfer is one synchronous step, so a failure moved nothing).

Shares: share[i] = floor(price × bps[i] / 10000), share[remainder] += price − Σ share. Zero shares complete without a transfer. A beneficiary equal to this contract completes locally.

States: Pending → InFlight(attempt) → Done | Pending for both steps. InFlight is never reset by time or by anyone. Entry points, permissionless and unable to change amounts or destinations: fund_delivery(delivery_id), pay_slot(delivery_id, slot), settle(delivery_id). Callbacks are private and check both state and attempt. Funding returns to Pending only for a readable used amount below the remaining obligation. An unreadable result (including a failed deposit promise) leaves funding InFlight: the tokens may already have moved. Payment returns to Pending only for an explicitly failed synchronous transfer; an unreadable successful result leaves it InFlight. Missing records and stale callbacks are harmless.

settle starts funding if Pending, then chains three separate stages: USDC ft_transfer_call → on_funded bookkeeping → dispatch_delivery. The original entry reserves the gas for both later receipts; bookkeeping never schedules payments. The private dispatcher re-reads the delivery and schedules only Pending slots, only if funding is Done. Its failure cannot roll back the earlier funding record: pay_slot or another settle can continue. An already funded delivery dispatches directly; missing/settled and funding-InFlight deliveries are no-ops. Before scheduling each transfer, the dispatcher records that slot's InFlight attempt. Parallel callbacks, legacy calls, duplicate keepers and delayed dispatchers cannot pay a slot twice.

Allowances, all with unused-gas weight zero: deposit 100 Tgas, each external transfer 30 Tgas, each bookkeeping/payment callback 15 Tgas, dispatcher 450 Tgas. Nine chains reserve 405 Tgas, leaving 45 Tgas for dispatcher execution and margin. Attach at least 600 Tgas to settle when funding is Pending (565 reserved downstream, 35 for entry execution and margin); 450 Tgas suffices when already funded. Calls below these thresholds are refused before changing state. Measurements with the real mainnet USDC and Intents bytecode, including final-callback first/middle/last index removal, are in contracts/annon/tests/mainnet_contracts.gas.txt. These are allowances, not burn estimates. Keepers still pay gas and the contract must have native NEAR for outbound 1-yocto calls.

Payout state never affects the buyer's entitlement. Once a delivery is funded and every slot is paid, its record is removed and freed delivery/index storage returns to the accepted purchase file budget, or to the receiver reserve for refund-only deliveries (delivery_settled event); get_delivery then returns null, the purchase keeps its delivery id. delivery_count() is the number of delivery ids ever assigned; ids without a record are refund leaves not yet materialized or settled deliveries. receiver_reserve() shows the reserve.

open_delivery_count() counts all stored deliveries, including InFlight. Ordinary creation and materialize_refund insert into the open index; only successful settlement removes from it. list_open_deliveries(from, limit) returns Delivery views at unordered index positions, capped at 50. Removal swaps the last entry into the hole. For a complete sweep, pin the count and every page to one finalized block hash/height using RPC block_id; advance by the number of entries returned. Concurrent removals cannot skip records in that snapshot, including every record that stays open throughout the sweep. New records after that block belong to the next sweep. Archive RPC may be needed if a sweep outlives the provider's retention. Across moving blocks a single forward offset scan can skip records; restarting at zero gives full coverage once mutations cease, but is not a guarantee under continuous churn. The count is not a cursor or a snapshot token.

Delivery and index insertion are flushed and charged together exactly once: ordinary acceptance debits its file budget, ordinary rejection debits the receiver reserve, and materialization charges its caller (attached or prepaid storage). Retirement credits actual freed delivery/index bytes to that file exactly once, or to the receiver reserve for refund-only deliveries, including caller-sponsored refunds. Purchases, recovery entries and materialization markers persist. Each index entry uses 130 bytes, reclaimed on retirement including swap-removal. Unit measurements: maximum-size acceptance including nine slots and 64-byte identities uses 1,484 bytes, below the unchanged 4,096-byte admission allowance; a materialized refund with a 10-byte NEAR beneficiary, index and permanent marker uses 332 bytes (0.00332 NEAR at 10^19 yoctoNEAR/byte).

Conditional liveness: open, actionable deliveries make automatic progress while dependencies permit transfers, receipts/callbacks execute successfully, native gas/storage sponsorship remains available and at least one funded keeper runs fair snapshot sweeps and retries Pending work. Refund leaves additionally need the history/proof prerequisite in §8. Keepers should back off retryable dependency failures and alert on InFlight uncertainty; backoff never changes contract state. Permissionless methods alone do not supply an executor, NEAR or dependency availability.

Known limit (SECURITY.md): a callback that fails leaves its step InFlight. A timeout, balance query, or keeper assertion cannot distinguish a completed transfer from a delayed receipt; resetting it could pay twice under another receipt ordering. No reset or administrative override is provided. On an upgradeable deployment a reviewed upgrade may repair a provable accounting issue; it cannot make an uncertain external effect known by itself. On a locked deployment an in-place upgrade is unavailable: a replacement account/version does not recover old obligations automatically.

8. Refund accumulator

For deliveries that cannot get storage: an append-only binary Merkle tree of depth 32, frontier and root preallocated at init.

Code
leaf  = SHA256("annon/refund-leaf/v1" ‖ 0x00 ‖ Borsh({ network: String, contract: AccountId,
        delivery_id: u64, refund: Identity, amount: u128 }))
node  = SHA256(0x01 ‖ left ‖ right);  empty subtree of height h: zero[0] = [0;32], zero[h+1] = SHA256(0x01 ‖ zero[h] ‖ zero[h])

Leaf indexes start at 0 and are appended left to right. A proof lists siblings from height 0 to 31; bit h of the index (least significant first) says whether the node at height h is a right child. The empty root is zero[32].

materialize_refund(leaf_fields, index, proof: Vec<[u8;32]>), payable (the caller funds storage): checks inclusion under one of the last 32 roots, the current one included (a proof stays valid while up to 31 more leaves are appended, so build it right before sending) and a one-time marker, then creates an ordinary refund obligation (§7). Events carry every leaf so anyone (the keeper) can build proofs.

Plain-RPC discovery remains a known gap: the frontier/root cannot recover leaf preimages or all sibling hashes. A keeper must retain/replay successful refund_leaf events from this executor to build proofs, even when it also scans the open index. Later reserve funding does not materialize old leaves automatically. Proofs can expire after 32 appends; rebuild against a recent root. No commitment format changes are made here.

Storage options were measured with the actual SDK collection and storage accounting. A readable map indexed by leaf index, storing (delivery_id, refund, amount) with network/contract implicit, adds 94 bytes for EVM, 106 for Solana, and 78 + account-length bytes for NEAR (88 for buyer.near, 142 at the 64-byte maximum). At the current storage-byte constant that is 0.00088 to 0.00142 NEAR per leaf for these NEAR examples, or 880 to 1,420 NEAR per million. Keeping all preimages enables proof reconstruction by RPC, but someone must pay when appended, exactly when the delivery reserve is empty. Silently charging the contract creates an unbounded storage-exhaustion vector. Deleting materialized preimages alone also loses proof data for other leaves; hashes/nodes must remain available. A separately sponsored preimage reserve is bounded and still needs an exhaustion policy; mandatory sender sponsorship changes the NEP-141 ingress/payment flow. Refusing unsponsored receipts returns tokens to the NEP-141 sender, which may be a bridge rather than the designated refund identity. Therefore no per-leaf storage is added in this change. An indexer-free guarantee requires an explicit ingress/storage funding decision; the existing constant-storage accumulator and permissionless, caller-funded materialize_refund remain available.

9. Key release and recovery

  • claim_key(purchase_id, grant: u32 = 0): anyone; requests CKD to the grant's buyer key for the file's unchanged derivation path; refused while taken down; repeatable. Grant 0 is the key from the purchase.
  • reopen({purchase_id, fresh_key, nonce, deadline}, auth): authorized by the purchase's recovery identity over
    Code
    Annon: open a purchased file again
    contract: <contract>
    purchase: 0x<purchase_id>
    file: 0x<file_id>
    recovery: <identity text form>
    new key: 0x<fresh 48-byte key>
    nonce: 0x<32 bytes>
    valid until: <UTC>
    
    creates the next grant (identical request → same grant) and requests CKD. Earlier grants stay.
  • Seller: reopen_seller and stop_sales with the same identity authorization (texts in the contract's reopen_seller_text / stop_sales_text, seller: before key/deadline, ending with valid until: <UTC>). Stop is final.
  • purchases_of(recovery: Identity, from, limit) finds purchases on a fresh device.
  • Downloads: the existing buyer proof (specs/download.md) plus purchase_id and grant; the host checks the proof against that grant's key at finality.
  • The SDK also writes an encrypted purchase file (buyer key secret, message, checked header hash, quote, recovery identity), encrypted with a user-held backup secret, never a wallet signature.

10. Events and views

Events (standard: "annon", version: "2.0.0"): file_registered, header_published, file_storage_funded, file_storage_low, delivery_received, purchase_accepted, refund_due, refund_leaf, delivery_refused (log only), funded, slot_paid, delivery_settled, funding_failed, payment_failed, key_requested, key_released, grant_created, sales_stopped. Never log secrets.

Failure event data (one object in the NEP-297 data array):

Event Fields Meaning
funding_failed delivery_id, attempt, state: "Pending", reason: "incomplete_deposit", used, remaining Readable partial/zero use; retry only the remainder. Also emits funded with the accounted progress.
funding_failed delivery_id, attempt, state: "InFlight", reason: "unreadable_result", remaining Unknown effect; alert, never resend this attempt.
payment_failed delivery_id, slot, attempt, state: "Pending", reason: "transfer_failed" Explicit synchronous transfer failure; safe to retry.
payment_failed delivery_id, slot, attempt, state: "InFlight", reason: "unreadable_result" Successful result could not be read within the bound; alert, never retry.

Amounts are decimal strings; IDs, slot and attempt are numbers. Stale callbacks emit no failure signal. A callback that never executes cannot emit one: reconcile InFlight state and transaction outcomes too. Accept events only from successful finalized receipts executed by the trusted Annon account; logs from failed receipts or other executors are not evidence of state transitions.

Views: get_file(file_id), get_purchase(purchase_id), get_grant, get_delivery(delivery_id), list_deliveries(from, limit), purchases_of(...), delivery_count(), list_open_deliveries(from, limit), open_delivery_count(), refund_root(), receiver_reserve(), file_storage_balance(file_id), get_config, storage_balance_of.

  • get_file → {terms, terms_hash, purchase_storage_balance, header_hash|null, sales_stopped_at|null, taken_down|null}.
  • file_storage_balance({file_id}) → {available, admission_requirement}, decimal yoctoNEAR strings.
  • Payable fund_file_storage({file_id, amount?}) allocates attached NEAR, with optional exactly matching amount; zero attached requires an explicit positive amount from the caller's prepaid balance. Allocations are nonwithdrawable; anyone can sponsor an active file. Stopped or taken-down files refuse funding. Optional register.args.file_budget is a positive yoctoNEAR string debited from the caller's prepaid balance atomically with registration; it does not change signed Terms or seller authorization. A leaked function-call key authorized for registration or funding can move all of its account's prepaid balance into arbitrary files. A gas allowance does not bound this allocation; limit prepaid balances and revoke compromised keys.
  • get_purchase → {purchase_id, file_id, terms_hash, buyer_key, recovery: Identity, route: "near-usdc"|"base-usdc", delivery: number|null, accepted_at: number, grants: number}.
  • get_grant({purchase_id, grant}) → {purchase_id, grant, buyer_key} or null.
  • claim_key({purchase_id, grant?}) defaults to grant 0.
  • purchases_of({recovery, from, limit}) → purchase ID strings, at most 100; offsets are u32.
  • get_config → {mpc, ckd_domain, foreign_tx_domain, usdc, network, near_usdc, intents}.
  • Keeper calls: fund_delivery({delivery_id}) with 150 Tgas, pay_slot({delivery_id, slot}) with 80 Tgas, settle({delivery_id}) with 600 Tgas; delivery views use numeric IDs, decimal-string USDC, and steps {state: 0|1|2, attempt: number}. list_deliveries({from, limit}) returns at most 50. list_open_deliveries({from, limit}) also returns at most 50, with snapshot semantics above. SDK listOpenDeliveries and openDeliveryCount accept an optional RPC block ID for this purpose. Existing keep() scheduling is unchanged; these bindings do not implement the next keeper design.
  • refund_root() → {root, count}. Payable materialize_refund({leaf:{delivery_id, refund: Identity, amount: string}, index, proof}) takes 32 sibling hashes and a storage deposit; network/contract come from the deployment. A zero attached deposit instead spends the caller's prepaid contract storage balance, including through the SDK binding, allowing a function-call key to materialize with sponsored storage.

Vectors label the SDK-only accumulator cache sdk_frontier; Rust keeps stale frontier slots. Only roots and proofs are cross-language wire commitments. Negative entries state expected.sdk and expected.contract; purchase parser outcomes are foreign (no valid refund prefix) or unusable (valid refund prefix, invalid body) under each entry's deployment context. UTC formatting follows Rust for all u64 seconds, including years beyond 9999.

11. Offer (x402 extension v3)

The 402 for a file lists annon-near-usdc (settlement on NEAR at this contract, asset NEAR USDC, amount = NEAR price, extra: contract, file_id, terms_hash) and, when base is present, annon-exact on Base with extra.nonceVersion: 2. 1Click is a way to pay annon-near-usdc, not a separate offer. Details in x402-annon.md §11 (to be updated).

12. File budgets and record economics

File state adds a fixed-width 16-byte purchase_storage_balance outside immutable Terms. Registration initializes it to zero or atomically credits optional args.file_budget from the caller's prepaid balance, in the same single-action call; funding, publishing, stopping and moderation never modify registered Terms. get_purchase.terms_hash derives from those Terms; no duplicate hash is kept in PurchaseRec. The recovery head stores (count, first_purchase_id) under the identity hash; positions 1 onward remain individual entries. Pagination and every existing signed encoding, cryptographic vector, event commitment and purchase view are unchanged. Base payment markers remain permanent. No migration is supplied: deploy fresh state.

file_storage_funded includes file_id, funder, amount, balance. file_storage_low includes file_id, available, admission_requirement, on admission refusal or when acceptance crosses below admission. purchase_accepted adds charged_bytes, charged_cost, remaining_budget. delivery_settled adds storage_credit and storage_destination (file ID or receiver_reserve). Costs and balances are yoctoNEAR strings.

Measured permanent bytes per purchase through actual collection writes, including entry overhead:

Recovery identity NEAR/1Click before first / later NEAR/1Click after any Base before first / later Base after any
EVM 413 / 336 304 494 / 417 385
Solana 425 / 348 316 506 / 429 397
NEAR, 10 characters 407 / 330 298 488 / 411 379
NEAR, 64 characters 461 / 384 352 542 / 465 433

The first purchase per recovery identity saves 109 bytes; later purchases save 32 bytes. At 10^19 yoctoNEAR per byte, multiply bytes by 0.00001 for NEAR storage stake. Temporary acceptance storage is initially charged to the file and recycled at retirement. Admission still requires 0.04096 NEAR; this allowance is not the measured purchase fee.

Relayer sponsorship policy is off-chain and published at /v1/capabilities. Its default fee is 30,000 USDC base units plus 100 bps of price; required treasury bps round up as ceil((fixed * 10000 + price * bps) / price). SDK sponsored sell inserts treasury shares, scales the others proportionally and assigns rounding to an original non-treasury recipient. The exact fee share rounds up by less than one basis point. Base terms require a single EVM treasury share at the larger of the two route requirements. Sponsored Base registration supplies split kind/salt; the relayer recomputes the ownerless split address locally and checks pay_to. For Base unlock sponsorship the relayer checks the deployed split against the registered terms and keeps each paid purchase's eligibility decision on durable storage. Direct self-funded registration has no compulsory fee. NEAR and 1Click clients check file_storage_balance before paying and refuse with file_storage_low when short; the contract rechecks on receipt because preflight reserves no budget.

Synced from specs/near-settlement.md at commit e649de1. Also asMarkdown.