@loopprotocol/sdk-byoaa 0.1.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,1046 @@
+import { PublicKey, Commitment, ConnectionConfig, Connection, TransactionSignature, AccountInfo } from '@solana/web3.js';
+
+/**
+ * Core BYOAA types + helpers.
+ *
+ * Spec reference: docs/roadmap/08-byoaa-sdk.md § "SDK surface"
+ *
+ * `BankReceipt` is the in-memory shape an attested agent constructs from a
+ * single bank transaction. Helpers normalize the fields so the same
+ * underlying transaction collides on the same on-chain PDA across re-fetches.
+ */
+/** Receipt payload carried by an attested receipt proof. */
+type ReceiptPayload = BankReceipt;
+/** Stable proof discriminants for the BYOAA receipt wire contract. */
+type ReceiptProofType = "cose_sign1_x509" | "risc0_v1" | "groth16_alt_bn128";
+/** Today's implemented proof arm: COSE_Sign1 signature plus X.509 chain. */
+interface CoseSign1X509Proof {
+    proof_type: "cose_sign1_x509";
+    signature: Uint8Array;
+    cert_chain: Uint8Array[];
+}
+/** Reserved v1 ZK arm. The verifier dispatch is present; implementation throws today. */
+interface Risc0V1Proof {
+    proof_type: "risc0_v1";
+    receipt: Uint8Array;
+    image_id: Uint8Array;
+}
+/** Reserved compact on-chain proof arm. The verifier dispatch is present; implementation throws today. */
+interface Groth16AltBn128Proof {
+    proof_type: "groth16_alt_bn128";
+    proof: Uint8Array;
+    public_inputs: Uint8Array;
+}
+/**
+ * Wire shape for receipts whose payload proof may evolve without retargeting
+ * the published SDK contract. New proof systems append new proof_type arms;
+ * existing arms must not change meaning.
+ */
+interface AttestedReceipt {
+    payload: ReceiptPayload;
+    proof: CoseSign1X509Proof | Risc0V1Proof | Groth16AltBn128Proof;
+}
+/**
+ * One bank transaction, as constructed inside an attested agent and submitted
+ * to `loop-shopping::submit_attested_receipt`.
+ *
+ * All fields except `mcc` and `accountLast4` are required. The on-chain
+ * handler will reject submissions where `amountCents == 0`, where
+ * `merchantNameRaw` is non-ASCII or > 64 bytes, or where `postedAt` is
+ * outside the [now - 365d, now] window.
+ */
+interface BankReceipt {
+    /**
+     * 32-byte stable hash of the transaction. Derived from the deterministic
+     * normalize-then-hash recipe in `deriveBankTxnId()`. The PDA seeds
+     * `[b"attested_receipt", vault, bank_txn_id]` mean two submissions of the
+     * same underlying transaction collide on the same account, so the second
+     * `init` call fails with `AccountAlreadyInUse` — natural double-submit
+     * protection without per-vault dedupe state.
+     */
+    bankTxnId: Uint8Array;
+    /**
+     * Merchant name as it appeared on the bank statement, normalized via
+     * `normalizeMerchantName()` (uppercase, whitespace-collapsed). Must be
+     * ASCII and ≤ 64 bytes. The on-chain account stores this raw; off-chain
+     * matchers normalize further when joining to merchant claim names.
+     */
+    merchantNameRaw: string;
+    /** MCC (merchant category code) if the bank exposed it. 0 = unknown. */
+    mcc: number;
+    /** Transaction amount in cents. Must be > 0; capped server-side. */
+    amountCents: bigint;
+    /**
+     * ISO-8601 posted date as Unix seconds at midnight UTC. The on-chain
+     * handler enforces a [now - 365d, now] window.
+     */
+    postedAt: bigint;
+    /**
+     * Last 4 of the funding card/account, if the bank exposed it. 0 = unknown.
+     * Used by the off-chain matcher to disambiguate a user's connected
+     * accounts when there are multiple.
+     */
+    accountLast4: number;
+}
+/**
+ * Maximum receipt amount in cents enforced by the on-chain handler. Mirrors
+ * `MAX_RECEIPT_CENTS` in `programs/loop-shopping/src/lib.rs`. Clients may
+ * front-run this check to surface a clearer error.
+ */
+declare const MAX_RECEIPT_CENTS: bigint;
+/**
+ * Maximum merchant_name_raw length in bytes enforced on-chain. Mirrors
+ * `MAX_MERCHANT_NAME_RAW_LEN`.
+ */
+declare const MAX_MERCHANT_NAME_RAW_LEN = 64;
+/**
+ * Maximum age of a receipt's `postedAt` enforced on-chain (365 days).
+ */
+declare const MAX_RECEIPT_AGE_SECONDS: bigint;
+/**
+ * Normalize a bank-statement merchant name to the on-chain canonical form:
+ *
+ *   1. Trim leading/trailing whitespace.
+ *   2. Collapse internal whitespace runs to a single space.
+ *   3. Uppercase.
+ *   4. Strip any non-ASCII characters (accents, currency symbols, etc.).
+ *
+ * The result is what the on-chain handler stores and what off-chain
+ * matchers compare against `MerchantClaimableNames` entries.
+ *
+ * @example
+ *   normalizeMerchantName("  starbucks #12345  SEATTLE WA  ")
+ *   // → "STARBUCKS #12345 SEATTLE WA"
+ *
+ *   normalizeMerchantName("Café Du Monde — New Orleans")
+ *   // → "CAF DU MONDE NEW ORLEANS"  (accents + em-dash stripped; the
+ *   //                                whitespace they left collapses)
+ */
+declare function normalizeMerchantName(raw: string): string;
+/**
+ * Derive a stable 32-byte transaction id from the normalized fields of a
+ * bank transaction. The same underlying transaction across re-fetches MUST
+ * produce the same id, so:
+ *
+ *   - merchant name is run through `normalizeMerchantName` first
+ *   - amount is taken in cents (no float rounding)
+ *   - posted date is taken at midnight UTC seconds (caller is responsible
+ *     for snapping; we don't truncate here)
+ *   - account_last4 is included so two different cards at the same merchant
+ *     for the same amount on the same day produce different ids
+ *
+ * Hashing is sha256. Output is exactly 32 bytes.
+ */
+declare function deriveBankTxnId(input: {
+    merchantNameRaw: string;
+    amountCents: bigint;
+    postedAt: bigint;
+    accountLast4: number;
+}): Uint8Array;
+/**
+ * Validation result returned from `validateReceipt()`. `ok: true` means the
+ * receipt should pass the on-chain handler's pre-flight checks; `ok: false`
+ * surfaces the specific error so callers can present a clear message before
+ * paying RPC + rent.
+ */
+type ReceiptValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: ReceiptValidationError;
+};
+type ReceiptValidationError = "merchant_name_empty" | "merchant_name_too_long" | "merchant_name_not_ascii" | "amount_zero" | "amount_too_large" | "posted_at_in_future" | "posted_at_too_old" | "bank_txn_id_wrong_length";
+/**
+ * Validate a receipt against the same bounds the on-chain handler enforces.
+ * Cheap, no I/O. Run this before `AttestedReceiptSubmitter.submit()` to
+ * fail fast without paying network fees or enclave round-trips.
+ *
+ * `nowSeconds` defaults to `Math.floor(Date.now() / 1000)`. Callers
+ * targeting a specific clock (e.g. cluster slot time) can override.
+ */
+declare function validateReceipt(receipt: BankReceipt, nowSeconds?: bigint): ReceiptValidationResult;
+
+/**
+ * Network-switchable configuration for the BYOAA SDK.
+ *
+ * Mirrors the pattern in `@loopprotocol/sdk` `src/network.ts` so that
+ * flipping a deployment between devnet and mainnet is a single config
+ * change, never a code change. Same hot-swap discipline as the on-chain
+ * programs (per-network `declare_id`, per-network
+ * `LOOP_VAULT_PROGRAM_ID_BYTES`).
+ *
+ * The BYOAA SDK only needs three things to talk to the chain:
+ *   1. The Solana RPC connection
+ *   2. The loop-shopping program id (carries `submit_attested_receipt`)
+ *   3. The loop-vault program id (used for the `session.owner` cross-program
+ *      check; the shopping handler does the same check in Rust)
+ *
+ * Everything else is derived from these. Constructors accept either a
+ * `Network` literal (the convenience path) or a fully-resolved
+ * `LoopByoaaConfig` (the override path — RPC URL, custom program ids for
+ * a sandbox or a forked cluster).
+ */
+
+type Network = "devnet" | "mainnet-beta" | "localnet";
+/**
+ * Devnet program ids. Authoritative for BYOAA work today — all 6 anchor
+ * programs are deployed and the shopping binary on devnet contains
+ * `submit_attested_receipt` as of `81aa56e` (truthful 4/4 NO-SKIPS rehearsal).
+ *
+ * Pulled into this module rather than imported from the main SDK so that
+ * the SDK can ship without forcing a parent-SDK version match on every
+ * BYOAA point release. When the parent SDK rotates ids, bump here to match.
+ */
+declare const DEVNET_PROGRAM_IDS: {
+    readonly SHOPPING: PublicKey;
+    readonly VAULT: PublicKey;
+};
+/**
+ * Mainnet program ids. Placeholder until Bundle 2 deploys (loop-shopping
+ * program upgrade carrying spec 08 + 08a + 08b + 09). At that point this
+ * map flips to the live mainnet ids and consumers re-deploy with
+ * `network: "mainnet-beta"`.
+ *
+ * The on-chain BYOAA surface is **not on mainnet today** — the deployed
+ * binary at `b407bae` covers specs 01-05 only. Don't switch consumers to
+ * `mainnet-beta` until the upgrade lands AND the mainnet ShoppingState
+ * bump=0 corruption is repaired (Burt P0 brief 2026-05-03).
+ */
+declare const MAINNET_PROGRAM_IDS: {
+    readonly SHOPPING: PublicKey;
+    readonly VAULT: PublicKey;
+};
+interface LoopByoaaConfig {
+    /** Which Solana cluster the BYOAA SDK targets. */
+    network: Network;
+    /** RPC endpoint. Defaults to the public cluster RPC for `network`. */
+    rpcUrl?: string;
+    /**
+     * Override the loop-shopping program id. Useful for sandbox forks where
+     * you've redeployed the program at a custom address (see
+     * `scripts/sandbox/`).
+     */
+    shoppingProgramId?: PublicKey;
+    /** Override the loop-vault program id. Same use-case as above. */
+    vaultProgramId?: PublicKey;
+    /**
+     * Commitment level for confirmations + reads. Defaults to "confirmed".
+     * BYOAA receipts are fire-and-forget once confirmed; "finalized" only
+     * matters if you need rollback resistance against deep reorgs.
+     */
+    commitment?: Commitment;
+    /** Extra connection config (forwarded to web3.js Connection). */
+    connectionConfig?: ConnectionConfig;
+}
+/**
+ * Resolved internal shape — everything is a concrete value, never undefined.
+ * Internal modules use this; public APIs accept the looser
+ * `LoopByoaaConfig` and resolve via `resolveConfig`.
+ */
+interface ResolvedConfig {
+    network: Network;
+    connection: Connection;
+    shoppingProgramId: PublicKey;
+    vaultProgramId: PublicKey;
+}
+/**
+ * Resolve a public `LoopByoaaConfig` (or just a network literal) into a
+ * fully-populated internal config. Pure: no I/O, no side effects.
+ */
+declare function resolveConfig(input: LoopByoaaConfig | Network): ResolvedConfig;
+/**
+ * Look up the canonical program ids for a given network. Localnet reuses
+ * the devnet ids by convention — sandbox forks should override via
+ * `LoopByoaaConfig.shoppingProgramId` / `vaultProgramId` instead of
+ * adding a new network case.
+ */
+declare function getProgramIds(network: Network): {
+    readonly SHOPPING: PublicKey;
+    readonly VAULT: PublicKey;
+};
+/** Default public RPC for each cluster. */
+declare function defaultRpcUrl(network: Network): string;
+/**
+ * True iff this network is mainnet. Used by callers to gate "real-money"
+ * UX (extra confirmation modals, larger fonts on amounts, etc.).
+ */
+declare function isMainnet(network: Network): boolean;
+
+/**
+ * PDA derivations for BYOAA accounts.
+ *
+ * Authoritative seeds live in `programs/loop-shopping/src/lib.rs` next to
+ * the `BankAttestedReceipt` struct. Mirror them here exactly — drift would
+ * silently corrupt receipt addresses.
+ */
+
+/**
+ * `BankAttestedReceipt` PDA.
+ *
+ * Seeds: `[b"attested_receipt", vault.key().as_ref(), bank_txn_id.as_ref()]`
+ *
+ * Per-vault-per-txn uniqueness — same bank transaction can't be submitted
+ * twice for the same user (the second `init` collides with the first
+ * account and fails).
+ *
+ * @returns the receipt PDA + bump seed
+ */
+declare function deriveBankAttestedReceiptPda(args: {
+    shoppingProgramId: PublicKey;
+    vault: PublicKey;
+    bankTxnId: Uint8Array;
+}): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * `ShoppingState` PDA (loop-shopping).
+ *
+ * Seeds: `[b"state"]`
+ *
+ * Global state for the loop-shopping program. `submit_attested_receipt`
+ * takes this as a read-only input to gate on `is_paused`.
+ */
+declare function deriveShoppingStatePda(args: {
+    shoppingProgramId: PublicKey;
+}): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * `AgentSessionRegistration` PDA (loop-vault).
+ *
+ * Seeds: `[b"agent_session", vault.key().as_ref(), session_pubkey.as_ref()]`
+ *
+ * Mirrored from spec 07a so SDK consumers can resolve the session account
+ * without a separate import from `@loopprotocol/sdk`.
+ */
+declare function deriveAgentSessionPda(args: {
+    vaultProgramId: PublicKey;
+    vault: PublicKey;
+    sessionPubkey: PublicKey;
+}): {
+    pda: PublicKey;
+    bump: number;
+};
+
+/**
+ * Hand-rolled Anchor wire encoding for the BYOAA instructions.
+ *
+ * We intentionally do NOT depend on the loop-shopping IDL artifact:
+ *
+ *   1. The IDL goes stale every time the on-chain program upgrades, and
+ *      sdk-byoaa needs to ship + npm-publish independently of the
+ *      anchor-build cycle.
+ *   2. Anchor's BorshCoder pulls in @coral-xyz/anchor as a hard dep with a
+ *      large transitive footprint. sdk-byoaa stays lean.
+ *   3. The SDK only constructs ONE instruction (`submit_attested_receipt`).
+ *      Hand-rolling that one is ~30 lines of Borsh; cheaper than the IDL
+ *      machinery.
+ *
+ * This module covers:
+ *   - Anchor's instruction discriminator (`sha256("global:<name>")[0..8]`)
+ *   - Borsh primitive writers (u16, u64, i64, [u8; N], String)
+ *   - The `AttestedReceiptArgs` struct encoder
+ *
+ * Reference for the on-chain shape:
+ *   programs/loop-shopping/src/lib.rs
+ *     - `pub fn submit_attested_receipt(ctx, args: AttestedReceiptArgs)`
+ *     - `pub struct AttestedReceiptArgs { bank_txn_id, merchant_name_raw,
+ *        mcc, amount_cents, posted_at, account_last4 }`
+ */
+/**
+ * Compute the 8-byte Anchor instruction discriminator.
+ * Convention: `sha256("global:" + snake_case_name)[0..8]`.
+ */
+declare function instructionDiscriminator(snakeName: string): Uint8Array;
+/**
+ * Borsh-encode the `AttestedReceiptArgs` struct exactly as the on-chain
+ * handler will deserialize it. Field order is load-bearing.
+ *
+ *   pub struct AttestedReceiptArgs {
+ *     pub bank_txn_id: [u8; 32],     // raw 32 bytes
+ *     pub merchant_name_raw: String, // u32 LE length + UTF-8 bytes
+ *     pub mcc: u16,                  // 2 bytes LE
+ *     pub amount_cents: u64,         // 8 bytes LE
+ *     pub posted_at: i64,            // 8 bytes LE (two's complement)
+ *     pub account_last4: u16,        // 2 bytes LE
+ *   }
+ */
+declare function encodeAttestedReceiptArgs(args: {
+    bankTxnId: Uint8Array;
+    merchantNameRaw: string;
+    mcc: number;
+    amountCents: bigint;
+    postedAt: bigint;
+    accountLast4: number;
+}): Uint8Array;
+/**
+ * Build the full instruction payload (discriminator || args) for
+ * `submit_attested_receipt`. This is what goes into
+ * `TransactionInstruction.data`.
+ */
+declare function encodeSubmitAttestedReceiptIxData(args: {
+    bankTxnId: Uint8Array;
+    merchantNameRaw: string;
+    mcc: number;
+    amountCents: bigint;
+    postedAt: bigint;
+    accountLast4: number;
+}): Uint8Array;
+
+/**
+ * AttestedReceiptSubmitter — sign + submit `submit_attested_receipt` txs.
+ *
+ * Spec 08 § "Enclave-side API". This class is what an attested agent
+ * (running inside an AWS Nitro / GCP Confidential Space / Anthropic
+ * Claude Computer Use enclave) uses to publish bank receipts on-chain.
+ *
+ * Trust boundary:
+ *   - The session **secret** lives only in the enclave; this class never
+ *     holds it. Signing is delegated to an `EnclaveSigner` (typically
+ *     the `EnclaveClient` from `@loopprotocol/sdk`, which talks to the
+ *     enclave via vsock or an HTTPS broker).
+ *   - This class assembles transactions, derives PDAs, and shepherds
+ *     network I/O. It can run anywhere — host, browser, an unattested
+ *     proxy — without weakening the security model.
+ */
+
+/**
+ * Bit position of `SUBMIT_ATTESTED_RECEIPT` in the
+ * `AgentSessionRegistration::allowed_instructions` bitfield.
+ *
+ * Mirrors `loop-shopping::SESSION_BIT_SUBMIT_ATTESTED_RECEIPT = 1 << 5`.
+ * `loop-vault` writes the numeric bitmap during session registration; bit 5
+ * is reserved for shopping attested receipts and must not be retargeted.
+ * Drift here = enclave's policy filter rejects valid signing requests,
+ * or worse, accepts wrong ones. Keep in lockstep with the on-chain const.
+ */
+declare const SESSION_INSTRUCTION_INDEX_SUBMIT_ATTESTED_RECEIPT = 5;
+/**
+ * Signing requests passed to the enclave. The enclave's `policy.rs`
+ * uses the policy fields to verify the signature request matches a
+ * receipt the enclave actually scraped (defense in depth against a
+ * compromised host trying to inject forged receipts through the
+ * legitimate signing channel).
+ */
+interface PolicyInputs {
+    /** Amount in cents, mirrored from the receipt being signed. */
+    amountCents: bigint;
+    /** Normalized merchant name, mirrored from the receipt. */
+    merchantNameRaw: string;
+    /** Bank-side posted-at timestamp, mirrored from the receipt. */
+    postedAt: bigint;
+    /** 32-byte receipt id, mirrored from the receipt. */
+    bankTxnId: Uint8Array;
+}
+/**
+ * The minimal contract sdk-byoaa needs to sign a transaction message
+ * inside an attested enclave. Decoupled from any specific transport so
+ * the SDK works against:
+ *   - The Loop-operated HTTPS broker (production)
+ *   - A local vsock listener (developer running the EIF on-host)
+ *   - A test double (unit tests; see tests/enclave.test.ts)
+ *
+ * `signInstruction` MUST return a 64-byte ed25519 signature over `message`
+ * produced by the session keypair bound to `getSessionPubkey()`.
+ */
+interface EnclaveSigner {
+    /** The enclave's bound session public key (same one registered on-chain). */
+    getSessionPubkey(): Promise<PublicKey>;
+    /**
+     * Request the enclave to sign a transaction message. Returns the raw
+     * 64-byte ed25519 signature. The enclave is expected to enforce its
+     * own policy filter — instruction index allowlist, well-formedness,
+     * rate limits — before signing.
+     */
+    signInstruction(args: {
+        instructionIndex: number;
+        message: Uint8Array;
+        policyInputs: PolicyInputs;
+    }): Promise<Uint8Array>;
+}
+interface AttestedReceiptSubmitterOptions {
+    /** Network selector or fully-resolved config. Defaults to "devnet". */
+    network?: Network | LoopByoaaConfig;
+    /** Enclave signer abstraction (see `EnclaveSigner`). */
+    enclaveSigner: EnclaveSigner;
+    /** User vault that the receipts are for (must match the session's vault). */
+    vault: PublicKey;
+    /**
+     * The session ed25519 pubkey that was registered on-chain via
+     * `register_agent_session` — i.e. the public side of the keypair the
+     * enclave signs with. The submitter derives the on-chain
+     * `AgentSessionRegistration` PDA from `[b"agent_session", vault,
+     * sessionPubkey]` against the configured vault program; consumers
+     * never have to compute the PDA themselves.
+     */
+    sessionPubkey: PublicKey;
+    /** Confirmation level for `submit()`. Defaults to "confirmed". */
+    commitment?: Commitment;
+}
+/** Outcome of a single `submit()` call. */
+interface SubmitOk {
+    ok: true;
+    signature: TransactionSignature;
+    receiptPda: PublicKey;
+}
+interface SubmitFail {
+    ok: false;
+    error: SubmitError;
+    /** Optional underlying error message for diagnostics. */
+    detail?: string;
+}
+type SubmitResult = SubmitOk | SubmitFail;
+type SubmitError = "validation_failed" | "session_pubkey_mismatch" | "blockhash_fetch_failed" | "enclave_sign_failed" | "transaction_send_failed" | "transaction_confirm_failed";
+interface SubmitBatchOptions {
+    /** Maximum in-flight submissions. Defaults to 4. */
+    concurrency?: number;
+    /** Minimum ms between starting consecutive submissions. Defaults to 0. */
+    rateLimitMs?: number;
+    /** Per-attempt commitment override. */
+    commitment?: Commitment;
+    /** Optional progress callback fired after each receipt resolves. */
+    onProgress?: (event: {
+        index: number;
+        total: number;
+        result: SubmitResult;
+    }) => void;
+}
+/**
+ * Sign + submit BYOAA receipts to the Loop Protocol clearing rail.
+ *
+ * Standard usage:
+ *
+ * ```ts
+ * const submitter = new AttestedReceiptSubmitter({
+ *   network: "devnet",
+ *   enclaveSigner,                      // talks to your Nitro enclave
+ *   vault: userVaultPda,
+ *   session: agentSessionPda,
+ * });
+ *
+ * const r = await submitter.submit(receipt);
+ * if (r.ok) console.log("receipt:", r.receiptPda.toBase58(), "tx:", r.signature);
+ * ```
+ *
+ * For batched ingestion (a daily cron pulling N transactions), use
+ * `submitBatch` — it bounds concurrency + applies an inter-request delay
+ * so RPC rate limits don't trip mid-run.
+ */
+declare class AttestedReceiptSubmitter {
+    private readonly resolvedConfig;
+    private readonly enclaveSigner;
+    private readonly vault;
+    /**
+     * The on-chain `AgentSessionRegistration` PDA, derived once from
+     * `[b"agent_session", vault, sessionPubkey]` against the vault program.
+     * The on-chain handler reads it as `session_registration`.
+     */
+    private readonly sessionRegistrationPda;
+    private readonly commitment;
+    /** Cached so we don't round-trip the enclave on every submit. */
+    private cachedSessionPubkey;
+    constructor(opts: AttestedReceiptSubmitterOptions);
+    /** Network selector this submitter was constructed against. */
+    get network(): Network;
+    /**
+     * Resolve the receipt PDA for a given txn id without submitting.
+     * Useful for off-chain state checks ("have we already submitted X?")
+     * before paying RPC fees.
+     */
+    deriveReceiptPda(bankTxnId: Uint8Array): PublicKey;
+    /**
+     * Sign + submit one receipt. Returns the on-chain signature + the
+     * receipt's PDA on success. Failures are returned as discriminated
+     * unions rather than thrown — batch consumers want fail-isolation.
+     */
+    submit(receipt: BankReceipt): Promise<SubmitResult>;
+    /**
+     * Submit N receipts with bounded concurrency + optional inter-request
+     * spacing. Fail-isolated: one bad receipt does not poison the rest.
+     *
+     * Order of `results` matches the order of `receipts`.
+     */
+    submitBatch(receipts: BankReceipt[], opts?: SubmitBatchOptions): Promise<SubmitResult[]>;
+    private getSessionPubkey;
+    private buildSubmitIx;
+}
+
+/**
+ * AttestedReceiptVerifier — fetch + decode `BankAttestedReceipt` accounts.
+ *
+ * Spec 08 § "Consumer-side API". Used by:
+ *   - Merchant intel dashboards (joining receipts to merchant claim names)
+ *   - Off-chain indexers backfilling Supabase mirror tables
+ *   - Forensics / audit tooling cross-checking PCR0 against the
+ *     EnclaveImageRegistry to flag unaudited submissions
+ *
+ * This module talks to chain via the same `ResolvedConfig` the submitter
+ * uses, so verification is network-switchable in lockstep — devnet today,
+ * mainnet the moment Bundle 2 deploys.
+ *
+ * Hand-rolled decoder (no Anchor IDL dep) so the package ships
+ * independently of the protocol's anchor-build cycle. The decoder mirrors
+ * the on-chain struct field order in `programs/loop-shopping/src/lib.rs`
+ * (`BankAttestedReceipt`) and `programs/loop-vault/src/lib.rs`
+ * (`EnclaveImageRegistry`).
+ */
+
+type ReceiptStatus = "recorded" | "honored" | "invalidated";
+interface VerifiedReceipt extends BankReceipt {
+    /** Address of the on-chain `BankAttestedReceipt` PDA. */
+    pda: PublicKey;
+    /** Owner vault — should match the user's vault you queried for. */
+    vault: PublicKey;
+    /** The enclave session pubkey that signed the submission. */
+    sessionPubkey: PublicKey;
+    /** PCR0 of the enclave image that produced the receipt. */
+    pcr0: Uint8Array;
+    /** Block timestamp at submission (Solana clock). */
+    submittedAt: bigint;
+    /**
+     * Lifecycle:
+     *   - "recorded" — submitted, not yet honored
+     *   - "honored" — a merchant claimed + paid via spec 08a
+     *   - "invalidated" — admin-revoked (fraud signal)
+     */
+    status: ReceiptStatus;
+    /**
+     * `true` iff this receipt's `pcr0` matches a currently-approved entry in
+     * the on-chain `EnclaveImageRegistry`. Always populated by `fetch()` —
+     * pass `requireAuditedImage: true` to throw when false.
+     *
+     * `null` when the verifier was constructed with `skipImageAudit: true`
+     * (lighter-weight; useful when the caller already knows audit state).
+     */
+    imageAudited: boolean | null;
+}
+interface AttestedReceiptVerifierOptions {
+    network?: Network | LoopByoaaConfig;
+    /**
+     * Cache the EnclaveImageRegistry decode for this many ms between
+     * fetches. Defaults to 60s — short enough to pick up admin updates
+     * within a minute, long enough that bulk verification doesn't
+     * hammer the RPC.
+     */
+    registryCacheMs?: number;
+    /**
+     * Skip the EnclaveImageRegistry cross-check entirely. `imageAudited`
+     * on returned receipts will be `null`. Use only when you don't care
+     * about audit state and want to save an RPC round-trip.
+     */
+    skipImageAudit?: boolean;
+}
+interface FetchOptions {
+    /**
+     * If `true`, throw `ReceiptNotAuditedError` when the receipt's PCR0
+     * doesn't match a current `EnclaveImageRegistry` entry. Default `false`
+     * — the field is populated and the caller decides.
+     */
+    requireAuditedImage?: boolean;
+}
+declare class ReceiptNotAuditedError extends Error {
+    readonly receipt: VerifiedReceipt;
+    constructor(receipt: VerifiedReceipt);
+}
+declare class ReceiptNotFoundError extends Error {
+    readonly pda: PublicKey;
+    constructor(pda: PublicKey);
+}
+declare class UnsupportedProofTypeError extends Error {
+    readonly proofType: ReceiptProofType;
+    constructor(proofType: ReceiptProofType);
+}
+type AttestedReceiptProofVerification = {
+    ok: true;
+    proof_type: "cose_sign1_x509";
+};
+/**
+ * Dispatch verifier for the BYOAA attested-receipt proof wire contract.
+ *
+ * Today only the COSE+X.509 arm is accepted. Reserved ZK arms are part of the
+ * wire shape now so future SDKs can implement them without retargeting the
+ * published contract; until then they fail closed with UnsupportedProofTypeError.
+ */
+declare function verifyAttestedReceiptProof(receipt: AttestedReceipt): AttestedReceiptProofVerification;
+declare class AttestedReceiptVerifier {
+    private readonly resolvedConfig;
+    private readonly registryCacheMs;
+    private readonly skipImageAudit;
+    /** Cache of approved PCR0s. */
+    private approvedPcr0s;
+    private approvedPcr0sExpiresAt;
+    constructor(opts?: AttestedReceiptVerifierOptions);
+    get network(): Network;
+    /**
+     * Fetch one receipt by PDA. Throws `ReceiptNotFoundError` if the
+     * account is missing or `ReceiptNotAuditedError` when
+     * `requireAuditedImage` is set and the PCR0 doesn't match the registry.
+     */
+    fetch(pda: PublicKey, opts?: FetchOptions): Promise<VerifiedReceipt>;
+    /**
+     * Stream every receipt for a given vault. Uses `getProgramAccounts`
+     * with a memcmp filter on the `vault` field at fixed offset 8 (right
+     * after the 8-byte Anchor discriminator).
+     *
+     * Order is undefined — sort client-side if you need deterministic
+     * ordering (e.g. by `submittedAt` or `postedAt`).
+     */
+    forVault(vault: PublicKey): AsyncIterable<VerifiedReceipt>;
+    /**
+     * Stream receipts whose `merchantNameRaw` (after `normalizeMerchantName`)
+     * matches the given normalized name.
+     *
+     * **Implementation note:** `merchant_name_raw` lives at variable byte
+     * offset (it follows a 4-byte length prefix that varies per receipt),
+     * so memcmp filtering on-chain is impractical. This method therefore
+     * fetches every `BankAttestedReceipt` account from the program and
+     * filters client-side. **Use the off-chain `attested_receipt_index`
+     * Supabase mirror (loop-site-v2 PR #27) for production-scale
+     * merchant queries.** This SDK method is fine for low-volume audits
+     * + correctness testing.
+     */
+    forMerchant(merchantNameNormalized: string): AsyncIterable<VerifiedReceipt>;
+    /**
+     * Force a refresh of the EnclaveImageRegistry cache. Useful in long-
+     * running daemons that want to pick up admin updates immediately.
+     */
+    refreshImageRegistry(): Promise<void>;
+    private auditPcr0;
+    private loadApprovedPcr0s;
+}
+/**
+ * Decode a `BankAttestedReceipt` account.
+ *
+ * On-chain layout (per programs/loop-shopping/src/lib.rs):
+ *   0..8     disc                     8 bytes
+ *   8..40    vault                    Pubkey (32)
+ *   40..72   session_pubkey           Pubkey (32)
+ *   72..120  pcr0                     [u8; 48]
+ *   120..152 bank_txn_id              [u8; 32]
+ *   152..156 merchant_name length     u32 LE
+ *   156..    merchant_name bytes      N bytes (variable)
+ *   then     mcc                      u16 LE
+ *            amount_cents             u64 LE
+ *            posted_at                i64 LE
+ *            account_last4            u16 LE
+ *            submitted_at             i64 LE
+ *            status                   u8
+ *            bump                     u8
+ *
+ * Anchor's `#[max_len(64)]` allocates space for the maximum but the
+ * serialized form uses the actual length, so we read sequentially.
+ */
+declare function decodeBankAttestedReceipt(pda: PublicKey, account: AccountInfo<Buffer>): VerifiedReceipt;
+/**
+ * Decode the EnclaveImageRegistry account into a Set of approved PCR0
+ * hex strings.
+ *
+ * On-chain layout (per programs/loop-vault/src/lib.rs):
+ *   0..8     disc
+ *   8..40    admin                    Pubkey
+ *   40..44   approved_images vec len  u32 LE
+ *   then     N entries of ApprovedImage:
+ *              pcr0   [u8; 48]
+ *              pcr1   [u8; 48]
+ *              pcr2   [u8; 48]
+ *              label  [u8; 32]
+ *              approved_at  i64 LE
+ *   end      bump (u8)
+ */
+declare function decodeRegistryPcr0Set(account: AccountInfo<Buffer>): Set<string>;
+
+type LoopByoaaErrorCode = "auth" | "validation" | "rate_limit" | "quota" | "permission_denied" | "not_found" | "conflict" | "server_error" | "network_error" | "unknown";
+interface LoopByoaaErrorContext {
+    status?: number;
+    request_id?: string;
+    documentation_url?: string;
+    retry_after_seconds?: number;
+    meter_name?: string;
+    upgrade_url?: string;
+    details?: unknown;
+}
+/** Base SDK error. Catch this when you want one branch for all Loop BYOAA failures. */
+declare class LoopByoaaError extends Error {
+    readonly code: LoopByoaaErrorCode | string;
+    readonly status?: number;
+    readonly request_id?: string;
+    readonly documentation_url?: string;
+    readonly details?: unknown;
+    constructor(code: LoopByoaaErrorCode | string, message: string, context?: LoopByoaaErrorContext);
+}
+declare class LoopByoaaApiKeyError extends LoopByoaaError {
+    constructor(code: LoopByoaaErrorCode | string, message: string, context?: LoopByoaaErrorContext);
+}
+declare class LoopByoaaPermissionError extends LoopByoaaError {
+    constructor(code: LoopByoaaErrorCode | string, message: string, context?: LoopByoaaErrorContext);
+}
+declare class LoopByoaaRateLimitError extends LoopByoaaError {
+    readonly retry_after_seconds?: number;
+    constructor(code: LoopByoaaErrorCode | string, message: string, context?: LoopByoaaErrorContext);
+}
+declare class LoopByoaaQuotaError extends LoopByoaaError {
+    readonly meter_name?: string;
+    readonly upgrade_url?: string;
+    constructor(code: LoopByoaaErrorCode | string, message: string, context?: LoopByoaaErrorContext);
+}
+declare class LoopByoaaValidationError extends LoopByoaaError {
+    constructor(code: LoopByoaaErrorCode | string, message: string, context?: LoopByoaaErrorContext);
+}
+declare class LoopByoaaServerError extends LoopByoaaError {
+    constructor(code: LoopByoaaErrorCode | string, message: string, context?: LoopByoaaErrorContext);
+}
+declare class LoopByoaaNetworkError extends LoopByoaaError {
+    constructor(message: string, context?: LoopByoaaErrorContext);
+}
+type AgentRiskTier = "low" | "medium" | "high" | "critical";
+type AgentStatus = "active" | "suspended" | "revoked" | "test" | "archived";
+interface AgentAttestation {
+    type: string;
+    issuer?: string;
+    evidence?: Record<string, unknown>;
+    issued_at?: string;
+}
+interface AgentRegisterInput {
+    external_id: string;
+    display_name: string;
+    purpose: string;
+    risk_tier: AgentRiskTier;
+    attestations?: AgentAttestation[];
+    metadata?: Record<string, unknown>;
+}
+interface AgentRecord {
+    id: string;
+    external_id?: string;
+    agent_key?: string;
+    display_name: string;
+    purpose?: string;
+    risk_tier: AgentRiskTier | string;
+    status: AgentStatus | string;
+    attestations?: AgentAttestation[];
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    updated_at?: string;
+}
+interface AgentListParams {
+    status?: AgentStatus | string;
+    page?: number;
+    limit?: number;
+}
+type AgentUpdateInput = Partial<Pick<AgentRegisterInput, "display_name" | "purpose" | "risk_tier" | "attestations" | "metadata">>;
+interface PermissionConditions {
+    [key: string]: unknown;
+}
+interface PermissionGrantInput {
+    agent_id: string;
+    on_behalf_of_user_id: string;
+    layer: string;
+    action_class: string;
+    amount_cap_cents?: number;
+    amount_cap_period?: "day" | "week" | "month" | "total";
+    valid_from?: Date | string;
+    valid_until?: Date | string;
+    conditions?: PermissionConditions;
+    metadata?: Record<string, unknown>;
+}
+interface PermissionGrant {
+    id: string;
+    grant_id?: string;
+    agent_id: string;
+    on_behalf_of_user_id?: string;
+    layer?: string;
+    action_class?: string;
+    status: "active" | "suspended" | "revoked" | "expired" | string;
+    amount_cap_cents?: number;
+    amount_cap_period?: string;
+    valid_from?: string;
+    valid_until?: string;
+    conditions?: PermissionConditions;
+    created_at: string;
+    updated_at?: string;
+}
+interface PermissionListParams {
+    agent_id?: string;
+    user_id?: string;
+    status?: string;
+    page?: number;
+    limit?: number;
+}
+interface PermissionRevokeInput {
+    reason: string;
+    evidence?: string;
+}
+interface IntendedAction {
+    layer: string;
+    action_class: string;
+    amount_cents?: number;
+    target?: Record<string, unknown>;
+}
+interface StepUpEvidence {
+    type: string;
+    evidence_ref?: string;
+    payload?: Record<string, unknown>;
+}
+interface DecisionRequestInput {
+    agent_id: string;
+    on_behalf_of_user_id: string;
+    intended_action: IntendedAction;
+    step_up_evidence?: StepUpEvidence;
+    policy_mode?: "default" | "restricted" | "bounded" | "permissive";
+    metadata?: Record<string, unknown>;
+}
+interface DecisionEnvelope {
+    outcome: "allow" | "review" | "deny" | "review_required" | string;
+    envelope_id: string;
+    review_request_id?: string;
+    reason?: string;
+    reasons?: string[];
+    issued_at: string;
+    signature_ref?: string;
+    authority_bundle_ref?: string;
+    decision_envelope_ref?: string;
+    audit_ref?: string;
+    metadata?: Record<string, unknown>;
+}
+interface DecisionListParams {
+    agent_id?: string;
+    user_id?: string;
+    outcome?: string;
+    since?: Date | string;
+    until?: Date | string;
+    page?: number;
+    limit?: number;
+}
+interface AuditExportInput {
+    range: {
+        from: Date | string;
+        to: Date | string;
+    };
+    scope?: {
+        agent_ids?: string[];
+        include_authority_bundles?: boolean;
+        include_decision_envelopes?: boolean;
+        include_audit_events?: boolean;
+    };
+    countersign?: boolean;
+    format?: "zip" | "jsonl" | "json";
+}
+interface AuditPack {
+    pack_id?: string;
+    manifest: Record<string, unknown>;
+    body?: unknown;
+    format?: "zip" | "jsonl" | "json" | string;
+    signature_bundle?: unknown;
+    exported_at?: string;
+}
+interface AuditEvent {
+    id: string;
+    audit_ref: string;
+    decision_envelope_ref: string;
+    event_type: string;
+    payload_digest?: string;
+    signature_bundle?: unknown;
+    prev_audit_hash?: string;
+    this_audit_hash?: string;
+    nonce?: string;
+    created_at: string;
+}
+interface AuditListParams {
+    since?: Date | string;
+    until?: Date | string;
+    agent_id?: string;
+    page?: number;
+    limit?: number;
+}
+interface Paginated<T> {
+    items: T[];
+    page?: number;
+    limit?: number;
+    total?: number;
+    next_cursor?: string;
+}
+type LoopByoaaEnvironment = "dev" | "staging" | "prod";
+interface ParsedLoopByoaaSdkKey {
+    env: LoopByoaaEnvironment;
+    prefix: string;
+    hashable: string;
+}
+interface LoopByoaaClientOptions {
+    /** Customer SDK key. Parsed at construction time and sent as bearer auth. */
+    apiKey: string;
+    /** OAR API root. Explicit overrides are kept for tests and federated tiers. */
+    baseUrl?: string;
+    timeout?: number;
+    fetch?: typeof fetch;
+}
+/**
+ * Parse a customer SDK key without making a network call.
+ *
+ * The suffix is intentionally restricted to 32 base62 characters for E.2 so
+ * malformed keys fail before the first request. Server-side key hashing can
+ * use `hashable` directly without the SDK needing to understand key storage.
+ */
+declare function parseLoopByoaaSdkKey(apiKey: string): ParsedLoopByoaaSdkKey;
+type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeout;
+    constructor(apiKey: string, baseUrl: string, fetchImpl: typeof fetch, timeout: number);
+    request<T>(method: HttpMethod, path: string, body?: unknown, query?: object): Promise<T>;
+}
+declare class LoopByoaaClient {
+    readonly apiKey: string;
+    readonly env: LoopByoaaEnvironment;
+    readonly parsedKey: ParsedLoopByoaaSdkKey;
+    readonly baseUrl: string;
+    readonly agents: AgentsNamespace;
+    readonly permissions: PermissionsNamespace;
+    readonly decisions: DecisionsNamespace;
+    readonly audit: AuditNamespace;
+    constructor(options: LoopByoaaClientOptions);
+}
+declare class AgentsNamespace {
+    private readonly http;
+    constructor(http: HttpClient);
+    register(input: AgentRegisterInput): Promise<AgentRecord>;
+    list(params?: AgentListParams): Promise<Paginated<AgentRecord>>;
+    get(agentIdOrExternalId: string): Promise<AgentRecord>;
+    update(id: string, input: AgentUpdateInput): Promise<AgentRecord>;
+    suspend(id: string, reason: string): Promise<AgentRecord>;
+    revoke(id: string, reason: string): Promise<AgentRecord>;
+}
+declare class PermissionsNamespace {
+    private readonly http;
+    constructor(http: HttpClient);
+    grant(input: PermissionGrantInput): Promise<PermissionGrant>;
+    list(params?: PermissionListParams): Promise<Paginated<PermissionGrant>>;
+    get(grantId: string): Promise<PermissionGrant>;
+    revoke(grantId: string, input: PermissionRevokeInput): Promise<PermissionGrant>;
+}
+declare class DecisionsNamespace {
+    private readonly http;
+    constructor(http: HttpClient);
+    request(input: DecisionRequestInput): Promise<DecisionEnvelope>;
+    get(envelopeId: string): Promise<DecisionEnvelope>;
+    list(params?: DecisionListParams): Promise<Paginated<DecisionEnvelope>>;
+}
+declare class AuditNamespace {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Export a tamper-evident KYA audit pack.
+     *
+     * TODO(F.5): switch this to the public audit-pack REST route once the
+     * customer-facing endpoint ships. E.1 intentionally points at the current
+     * internal export bridge so the method shape is stable for quickstart code.
+     */
+    exportPack(input: AuditExportInput): Promise<AuditPack>;
+    export(input: AuditExportInput): Promise<AuditPack>;
+    list(params?: AuditListParams): Promise<Paginated<AuditEvent>>;
+    get(eventId: string): Promise<AuditEvent>;
+}
+
+export { type AgentAttestation, type AgentListParams, type AgentRecord, type AgentRegisterInput, type AgentRiskTier, type AgentStatus, type AgentUpdateInput, AgentsNamespace, type AttestedReceipt, AttestedReceiptSubmitter, type AttestedReceiptSubmitterOptions, AttestedReceiptVerifier, type AttestedReceiptVerifierOptions, type AuditEvent, type AuditExportInput, type AuditListParams, AuditNamespace, type AuditPack, type BankReceipt, type CoseSign1X509Proof, DEVNET_PROGRAM_IDS, type DecisionEnvelope, type DecisionListParams, type DecisionRequestInput, DecisionsNamespace, type EnclaveSigner, type FetchOptions, type Groth16AltBn128Proof, type IntendedAction, LoopByoaaApiKeyError, LoopByoaaClient, type LoopByoaaClientOptions, type LoopByoaaConfig, type LoopByoaaEnvironment, LoopByoaaError, type LoopByoaaErrorCode, type LoopByoaaErrorContext, LoopByoaaNetworkError, LoopByoaaPermissionError, LoopByoaaQuotaError, LoopByoaaRateLimitError, LoopByoaaServerError, LoopByoaaValidationError, MAINNET_PROGRAM_IDS, MAX_MERCHANT_NAME_RAW_LEN, MAX_RECEIPT_AGE_SECONDS, MAX_RECEIPT_CENTS, type Network, type Paginated, type ParsedLoopByoaaSdkKey, type PermissionConditions, type PermissionGrant, type PermissionGrantInput, type PermissionListParams, type PermissionRevokeInput, PermissionsNamespace, type PolicyInputs, ReceiptNotAuditedError, ReceiptNotFoundError, type ReceiptPayload, type ReceiptProofType, type ReceiptStatus, type ReceiptValidationError, type ReceiptValidationResult, type ResolvedConfig, type Risc0V1Proof, SESSION_INSTRUCTION_INDEX_SUBMIT_ATTESTED_RECEIPT, type StepUpEvidence, type SubmitBatchOptions, type SubmitError, type SubmitFail, type SubmitOk, type SubmitResult, UnsupportedProofTypeError, type VerifiedReceipt, decodeBankAttestedReceipt, decodeRegistryPcr0Set, defaultRpcUrl, deriveAgentSessionPda, deriveBankAttestedReceiptPda, deriveBankTxnId, deriveShoppingStatePda, encodeAttestedReceiptArgs, encodeSubmitAttestedReceiptIxData, getProgramIds, instructionDiscriminator, isMainnet, normalizeMerchantName, parseLoopByoaaSdkKey, resolveConfig, validateReceipt, verifyAttestedReceiptProof };