import { type ContractTerms } from "./terms.js"; /** SHA-256 output width, and hence the width of every chain hash. */ export declare const RECEIPT_HASH_LEN = 32; /** * The chain's genesis link: 32 zero bytes. * * A distinguished value rather than "no field", so the first receipt is * hashed by the same rule as every other one and `verify` needs no special * case that could be made to accept a forged head. */ export declare const GENESIS_PREV_HASH: Uint8Array; /** * §7's three statuses. * * `settled` is a payment the resource server accepted; `refunded` is the * compensating entry appended when a merchant signs a refund (§6.7); * `failed` is a payment that was attempted and did not settle — no value * moved, which is why {@link ReceiptLog.reconcile} counts it as zero rather * than as an outflow. */ export type ReceiptStatus = "settled" | "refunded" | "failed"; /** * What the wallet saw of a bridge payment (v3 §26) when it was made: * * - `"delivered"` -- the merchant answered 2xx with a settlement header * saying `success: true`. * - `"undelivered"` -- the authorization was delivered and the merchant did * not confirm it (another status, no or a negative settlement header, or * no answer at all). * - `"no-relayer"` -- the facilitator committed the coins and no relayer * signed (`502 BRIDGE_NO_RELAYER`). * - `"rejected"` -- the facilitator's authorization failed the wallet's * checks (§26.8 step 4) and was never delivered. * - `"unknown"` -- `/settle`'s answer was lost; the commit is assumed. * * Every state but `"delivered"` carries a {@link BridgeRecourse}. */ export type BridgeState = "delivered" | "undelivered" | "no-relayer" | "rejected" | "unknown"; export declare const BRIDGE_STATES: readonly BridgeState[]; /** A bridge payment's facts (v3 §26.8 step 6): hashed with the receipt. */ export interface ReceiptBridge { /** The bridge facilitator the coins were committed through. */ readonly facilitator: string; /** * The relayer that signed: its payout address, the authorization's `from` * -- the address the merchant is paid from on chain. Absent when no relayer * signed, or the wallet never read a verified answer. */ readonly relayer?: string; /** The token the merchant is paid in, `0x`-prefixed. */ readonly asset: string; /** * The network the merchant is paid on, CAIP-2 (`eip155:8453`): the * wallet's own, or a foreign payout network (v3 §28.2). Absent on a * receipt written before §28, which was paid on the wallet's own network. */ readonly network?: string; /** The merchant's settlement transaction (`X-PAYMENT-RESPONSE`'s `transaction`). */ readonly merchantTransaction?: string; readonly state: BridgeState; } /** * Where the wallet's recourse for a bridge payment stands (v3 §26.8 step 7): * * - `"pending"` -- recorded; its first round runs at * `settledAt + LEASE_TTL + 2·RECORD_GRACE`. * - `"disputed"` -- the issuer was asked, and the wallet waits on what it * said (a revocation's refund, an operator's decision). * - `"cancel-requested"` -- no relayer recorded; the registry's cancel * fallback clock is running, and the wallet asks again after * `PAYOUT_DEADLINE`. * - `"closed"` -- nothing is left to do; {@link BridgeRecourse.outcome} says why. */ export type RecourseStage = "pending" | "disputed" | "cancel-requested" | "closed"; /** * The last thing a recourse round learned: * * - `"paid"` -- the facilitator or the issuer says the merchant was paid * (closed; a merchant that took the money and did not serve owes a §6.7 * refund, which is the merchant's to give). * - `"refunded"` -- the coins' value was restored; a `refunded` receipt was * appended (closed). * - `"not-committed"` -- the registry holds no commit for these terms: the * coins were never debited, and a `refunded` receipt for the presented * total was appended, as for `"refunded"` (closed). * - `"window-closed"` -- a relayer's record stands past `PAYOUT_DEADLINE`; * nothing more can be disputed (closed). * - `"revoked"` -- the issuer revoked the relayer's record; the cancel refund * follows. * - `"not-recorded"` -- no relayer recorded; the registry's cancel fallback * was requested. * - `"too-early"` -- the issuer asked for later (`not_before`). * - `"needs-operator"` -- the issuer's operator decides. * - `"unavailable"` -- a service did not answer usefully; retried later. */ export type RecourseOutcome = "paid" | "refunded" | "not-committed" | "window-closed" | "revoked" | "not-recorded" | "too-early" | "needs-operator" | "unavailable"; /** * The dispute intent of a bridge payment not confirmed delivered (v3 §26.8 * step 7). Kept beside the receipt, outside its hash: see the module docs. */ export interface BridgeRecourse { /** * The payment's preimage: the credential `/bridge/lookup`, `/disputes` and * the registry's cancel request take (§26.7). Its hash is the entry's * `contractTermsHash`. */ readonly contractTerms: ContractTerms; /** Unix seconds, the wallet's clock, when the coins were committed. */ readonly settledAt: number; readonly stage: RecourseStage; /** * When the next round runs, unix seconds. Absent before the first, which * runs at `settledAt + LEASE_TTL + 2·RECORD_GRACE`. */ readonly nextAt?: number; readonly outcome?: RecourseOutcome; } /** The fields a caller supplies; the chain adds the rest. */ export interface ReceiptEntry { /** Unix seconds. */ readonly ts: number; /** The resource that was paid for. Local only — see the module docs. */ readonly resourceUrl: string; /** The merchant's `payTo`, `0x`-prefixed (§6.14). */ readonly payTo: string; /** * What was paid, in USDC base units: the **presented total**, price plus * relayer fee (v3 §7). Kept under this name because it is what the coins * covered and what every pre-v3 reader of a receipt was reading. */ readonly amount: bigint; /** * The relayer's share of {@link amount} (v3 §7): the rate's fee plus the * rounding of the total to the smallest denomination (§25.1). Omitted means * zero, and zero leaves the hash exactly as it was before fees existed. */ readonly feeBaseUnits?: bigint; /** The coin public keys spent, in payload order. */ readonly coinPubs: readonly Uint8Array[]; /** The EIP-712 struct hash the deposit permissions bound to, 32 bytes. */ readonly contractTermsHash: Uint8Array; readonly status: ReceiptStatus; /** * Whether the resource arrived. Omitted means it did. * * §6.7's **paid, undelivered** annotation, and it is an annotation on a * `settled` receipt rather than a fourth status: the payment settled, so it * is an outflow and {@link ReceiptLog.reconcile} must count it as one. A * `failed` receipt is the different case — nothing settled, nothing moved. * * The distinction is the user's remedy. `settled` + `delivered: false` is a * refund request against `payTo` (§6.7); a retry would pay twice. */ readonly delivered?: boolean; /** A payment through the exact-scheme bridge (v3 §26): its facts. Hashed. */ readonly bridge?: ReceiptBridge; /** * The bridge payment's recourse, while one is kept (v3 §26.8 step 7). Not * hashed: it changes as the wallet pursues it ({@link ReceiptLog.setRecourse}). */ readonly recourse?: BridgeRecourse; } /** One link of the chain: a {@link ReceiptEntry} with its position and hashes. */ export interface Receipt extends ReceiptEntry { /** 0-based, and equal to the entry's index in the log. */ readonly seq: number; /** The predecessor's `hash`, or {@link GENESIS_PREV_HASH} at `seq === 0`. */ readonly prevHash: Uint8Array; /** `H(prevHash ‖ rest)`. */ readonly hash: Uint8Array; /** The relayer's share of `amount`, always present on a chained receipt. */ readonly feeBaseUnits: bigint; /** `amount − feeBaseUnits`: what the merchant received. */ readonly priceBaseUnits: bigint; } /** * A {@link Receipt} as a caller may have persisted it — possibly by a wallet * that predates the fee fields. {@link ReceiptLog.load} takes this shape and * fills the two in (`fee = 0`, `price = amount`) where they are absent. */ export type StoredReceipt = Omit & { readonly feeBaseUnits?: bigint; readonly priceBaseUnits?: bigint; }; /** The chain-level totals a wallet reconciles against its coin buffer. */ export interface ChainTotals { /** `Σ` USDC deposited into this wallet's reserves, in base units (§5.2.1). */ readonly deposits: bigint; /** `Σ` reclaimed out of them, in base units (§5.2.4, §5.2.5). */ readonly reclaims: bigint; /** `Σ` residual value of the coins still held. */ readonly liveCoinValue: bigint; } /** The result of §7's reconciliation. */ export interface Reconciliation extends ChainTotals { /** * `deposits − reclaims − liveCoinValue`: the value that left the reserve * and is no longer in a coin, i.e. what must have been spent. */ readonly settledOut: bigint; /** `Σ settled − Σ refunded` across the chain. `failed` contributes nothing. */ readonly receiptTotal: bigint; /** * `settledOut − receiptTotal`. Non-zero means value moved that the chain * does not account for: a coin lost between withdraw and store, a spend * that settled after the wallet crashed, or a truncated log. */ readonly difference: bigint; readonly balanced: boolean; } /** * The chain does not verify at some entry. * * Carries the sequence number and nothing else. The entry's own fields are * the user's purchase history, and an exception object is the thing that * ends up in a log aggregator. */ export declare class ReceiptChainError extends Error { /** The first entry that does not follow its predecessor. */ readonly seq: number; constructor(seq: number, detail: string); } /** * `H(prevHash ‖ rest)` — §7's chain rule, with `rest` laid out per §6.12's * conventions: variable-length fields carry a `be32` length prefix (without * one, `"ab" ‖ "c"` and `"a" ‖ "bc"` hash identically and the boundary is * forgeable), fixed-width fields carry none. */ export declare function receiptHash(prevHash: Uint8Array, seq: number, entry: ReceiptEntry): Uint8Array; /** * Check a whole chain, entry by entry. * * @throws ReceiptChainError naming the first entry that does not follow its * predecessor — by sequence number only. */ export declare function verifyChain(entries: readonly StoredReceipt[]): void; /** * The wallet's local receipt log: append-only, hash-chained, and never sent * anywhere. */ export declare class ReceiptLog { private readonly entries; /** * Rebuild a log from stored entries, **verifying the chain first**. * * Verification is not optional here on purpose. A log loaded without it * would answer `list()` and `reconcile()` from data that has no more * standing than the file it came out of, and the one property the chain * offers — that this history has not been rewritten — would be claimed * without ever being checked. */ static load(entries: readonly StoredReceipt[]): ReceiptLog; /** The chain head, or {@link GENESIS_PREV_HASH} for an empty log. */ get head(): Uint8Array; get length(): number; /** Append one entry and return it, chained. */ append(entry: ReceiptEntry): Receipt; /** * Every receipt, oldest first. * * A copy of the array: the log is append-only, and handing out the live * array would let a caller splice history out of it without going near the * hashes. */ list(): readonly Receipt[]; /** * Re-check the whole chain, throwing if any entry has been altered. * * Named `assertValid` rather than `verify` because it returns nothing: * `const ok = receipts.verify()` compiles, yields `undefined`, and lets a * caller believe they checked when they did not. The name has to carry * the contract when the return type cannot. * * @throws ReceiptChainError */ assertValid(): void; /** * Replace a bridge payment's recourse (v3 §26.8 step 7) -- the one part of * a receipt that changes after it is appended, and which is outside the * hash for exactly that reason (see the module docs). The entry's hash, and * every hash after it, are unchanged. * * @throws RangeError for a sequence number with no receipt, a receipt that * is not a bridge payment, or a recourse whose preimage does not hash to * the receipt's `contractTermsHash`. */ setRecourse(seq: number, recourse: BridgeRecourse): Receipt; /** * §7's reconciliation: `Σ deposits − Σ reclaims − Σ live coin value` * against `Σ settled − Σ refunded`. * * The two sides are computed from different places on purpose — the chain * totals come from the reserve contract and the coin buffer, the receipt * total from this log — so agreement is evidence and a difference is a * question worth asking. It is the only check here that a truncated log * cannot pass. */ reconcile(totals: ChainTotals): Reconciliation; /** * Serialize the log for the user, as a **string returned to the caller**. * * Field names are snake_case and byte strings follow §6.14: `payTo` and * the terms hash are `0x`-prefixed because they map to EVM words, while * coin public keys and the chain hashes are opaque protocol byte strings * and stay bare. `amount` and `ts` are `u64`s and are therefore decimal * **strings** — an export whose amounts round at 2^53 is a ledger that * disagrees with the chain it was reconciled against. */ export(format: "csv" | "json"): string; private jsonOf; private csvOf; } /** * The inverse of {@link ReceiptLog.export}`("json")`: the stored chain, in the * shape `px402.recover({ receipts })` and {@link ReceiptLog.load} take. * * It reads; it does not judge -- the chain is verified when it is loaded, * which is where a tampered file is refused. A file written before v3 (no * `price` or `fee`) or before the bridge (no `bridge` or `recourse`) reads as * the receipts it held. A bridge payment's recourse comes back with it, so a * wallet restarted from this file keeps pursuing it (v3 §26.8 step 7). * * @throws RangeError naming the first row that is not one `export` writes. */ export declare function receiptsFromJson(json: string): StoredReceipt[];