@loopprotocol/sdk-byoaa 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,1127 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentsNamespace: () => AgentsNamespace,
+  AttestedReceiptSubmitter: () => AttestedReceiptSubmitter,
+  AttestedReceiptVerifier: () => AttestedReceiptVerifier,
+  AuditNamespace: () => AuditNamespace,
+  DEVNET_PROGRAM_IDS: () => DEVNET_PROGRAM_IDS,
+  DecisionsNamespace: () => DecisionsNamespace,
+  LoopByoaaApiKeyError: () => LoopByoaaApiKeyError,
+  LoopByoaaClient: () => LoopByoaaClient,
+  LoopByoaaError: () => LoopByoaaError,
+  LoopByoaaNetworkError: () => LoopByoaaNetworkError,
+  LoopByoaaPermissionError: () => LoopByoaaPermissionError,
+  LoopByoaaQuotaError: () => LoopByoaaQuotaError,
+  LoopByoaaRateLimitError: () => LoopByoaaRateLimitError,
+  LoopByoaaServerError: () => LoopByoaaServerError,
+  LoopByoaaValidationError: () => LoopByoaaValidationError,
+  MAINNET_PROGRAM_IDS: () => MAINNET_PROGRAM_IDS,
+  MAX_MERCHANT_NAME_RAW_LEN: () => MAX_MERCHANT_NAME_RAW_LEN,
+  MAX_RECEIPT_AGE_SECONDS: () => MAX_RECEIPT_AGE_SECONDS,
+  MAX_RECEIPT_CENTS: () => MAX_RECEIPT_CENTS,
+  PermissionsNamespace: () => PermissionsNamespace,
+  ReceiptNotAuditedError: () => ReceiptNotAuditedError,
+  ReceiptNotFoundError: () => ReceiptNotFoundError,
+  SESSION_INSTRUCTION_INDEX_SUBMIT_ATTESTED_RECEIPT: () => SESSION_INSTRUCTION_INDEX_SUBMIT_ATTESTED_RECEIPT,
+  UnsupportedProofTypeError: () => UnsupportedProofTypeError,
+  decodeBankAttestedReceipt: () => decodeBankAttestedReceipt,
+  decodeRegistryPcr0Set: () => decodeRegistryPcr0Set,
+  defaultRpcUrl: () => defaultRpcUrl,
+  deriveAgentSessionPda: () => deriveAgentSessionPda,
+  deriveBankAttestedReceiptPda: () => deriveBankAttestedReceiptPda,
+  deriveBankTxnId: () => deriveBankTxnId,
+  deriveShoppingStatePda: () => deriveShoppingStatePda,
+  encodeAttestedReceiptArgs: () => encodeAttestedReceiptArgs,
+  encodeSubmitAttestedReceiptIxData: () => encodeSubmitAttestedReceiptIxData,
+  getProgramIds: () => getProgramIds,
+  instructionDiscriminator: () => instructionDiscriminator,
+  isMainnet: () => isMainnet,
+  normalizeMerchantName: () => normalizeMerchantName,
+  parseLoopByoaaSdkKey: () => parseLoopByoaaSdkKey,
+  resolveConfig: () => resolveConfig,
+  validateReceipt: () => validateReceipt,
+  verifyAttestedReceiptProof: () => verifyAttestedReceiptProof
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var import_node_crypto = require("crypto");
+var MAX_RECEIPT_CENTS = 10000000000n;
+var MAX_MERCHANT_NAME_RAW_LEN = 64;
+var MAX_RECEIPT_AGE_SECONDS = 365n * 24n * 60n * 60n;
+function normalizeMerchantName(raw) {
+  const ascii = raw.replace(/[^\x20-\x7E]/g, "");
+  return ascii.trim().replace(/\s+/g, " ").toUpperCase();
+}
+function deriveBankTxnId(input) {
+  const normalized = normalizeMerchantName(input.merchantNameRaw);
+  const payload = [
+    normalized,
+    input.amountCents.toString(),
+    input.postedAt.toString(),
+    input.accountLast4.toString()
+  ].join("|");
+  const hash = (0, import_node_crypto.createHash)("sha256").update(payload, "utf8").digest();
+  return new Uint8Array(hash);
+}
+function validateReceipt(receipt, nowSeconds = BigInt(Math.floor(Date.now() / 1e3))) {
+  if (receipt.bankTxnId.length !== 32) {
+    return { ok: false, error: "bank_txn_id_wrong_length" };
+  }
+  if (receipt.merchantNameRaw.length === 0) {
+    return { ok: false, error: "merchant_name_empty" };
+  }
+  if (receipt.merchantNameRaw.length > MAX_MERCHANT_NAME_RAW_LEN) {
+    return { ok: false, error: "merchant_name_too_long" };
+  }
+  if (!/^[\x20-\x7E]+$/.test(receipt.merchantNameRaw)) {
+    return { ok: false, error: "merchant_name_not_ascii" };
+  }
+  if (receipt.amountCents <= 0n) {
+    return { ok: false, error: "amount_zero" };
+  }
+  if (receipt.amountCents > MAX_RECEIPT_CENTS) {
+    return { ok: false, error: "amount_too_large" };
+  }
+  if (receipt.postedAt > nowSeconds) {
+    return { ok: false, error: "posted_at_in_future" };
+  }
+  if (nowSeconds - receipt.postedAt > MAX_RECEIPT_AGE_SECONDS) {
+    return { ok: false, error: "posted_at_too_old" };
+  }
+  return { ok: true };
+}
+
+// src/config.ts
+var import_web3 = require("@solana/web3.js");
+var DEVNET_PROGRAM_IDS = {
+  SHOPPING: new import_web3.PublicKey("FSqRkH7nkGHP3VpHwFE667PVAfLKfSGaPMgTrXpJZJoJ"),
+  VAULT: new import_web3.PublicKey("9gKRCrUpHv9CRHwYMmm2zP5bN1bUKgyi7BxuS5jifX4x")
+};
+var MAINNET_PROGRAM_IDS = {
+  // TODO(post-Bundle-2-deploy): replace with the live mainnet id.
+  SHOPPING: new import_web3.PublicKey("11111111111111111111111111111111"),
+  // Live mainnet vault id (already deployed). Fixed.
+  VAULT: new import_web3.PublicKey("J8HhLeRv5iQaSyYQBXJoDwDKbw4V8uA84WN93YrVSWQT")
+};
+function resolveConfig(input) {
+  const cfg = typeof input === "string" ? { network: input } : input;
+  const programIds = getProgramIds(cfg.network);
+  const rpcUrl = cfg.rpcUrl ?? defaultRpcUrl(cfg.network);
+  const commitment = cfg.commitment ?? "confirmed";
+  const connection = new import_web3.Connection(
+    rpcUrl,
+    cfg.connectionConfig ?? { commitment }
+  );
+  return {
+    network: cfg.network,
+    connection,
+    shoppingProgramId: cfg.shoppingProgramId ?? programIds.SHOPPING,
+    vaultProgramId: cfg.vaultProgramId ?? programIds.VAULT
+  };
+}
+function getProgramIds(network) {
+  switch (network) {
+    case "devnet":
+    case "localnet":
+      return DEVNET_PROGRAM_IDS;
+    case "mainnet-beta":
+      return MAINNET_PROGRAM_IDS;
+    default: {
+      const _exhaustive = network;
+      throw new Error(`Unknown network: ${_exhaustive}`);
+    }
+  }
+}
+function defaultRpcUrl(network) {
+  if (network === "localnet") return "http://127.0.0.1:8899";
+  return (0, import_web3.clusterApiUrl)(network);
+}
+function isMainnet(network) {
+  return network === "mainnet-beta";
+}
+
+// src/pda.ts
+var import_web32 = require("@solana/web3.js");
+function deriveBankAttestedReceiptPda(args) {
+  if (args.bankTxnId.length !== 32) {
+    throw new Error(
+      `bankTxnId must be exactly 32 bytes; got ${args.bankTxnId.length}`
+    );
+  }
+  const [pda, bump] = import_web32.PublicKey.findProgramAddressSync(
+    [
+      Buffer.from("attested_receipt"),
+      args.vault.toBuffer(),
+      Buffer.from(args.bankTxnId)
+    ],
+    args.shoppingProgramId
+  );
+  return { pda, bump };
+}
+function deriveShoppingStatePda(args) {
+  const [pda, bump] = import_web32.PublicKey.findProgramAddressSync(
+    [Buffer.from("state")],
+    args.shoppingProgramId
+  );
+  return { pda, bump };
+}
+function deriveAgentSessionPda(args) {
+  const [pda, bump] = import_web32.PublicKey.findProgramAddressSync(
+    [
+      Buffer.from("agent_session"),
+      args.vault.toBuffer(),
+      args.sessionPubkey.toBuffer()
+    ],
+    args.vaultProgramId
+  );
+  return { pda, bump };
+}
+
+// src/anchor-codec.ts
+var import_node_crypto2 = require("crypto");
+function instructionDiscriminator(snakeName) {
+  const h = (0, import_node_crypto2.createHash)("sha256").update(`global:${snakeName}`).digest();
+  return new Uint8Array(h.subarray(0, 8));
+}
+function encodeAttestedReceiptArgs(args) {
+  if (args.bankTxnId.length !== 32) {
+    throw new Error(
+      `bankTxnId must be exactly 32 bytes; got ${args.bankTxnId.length}`
+    );
+  }
+  const nameBytes = new TextEncoder().encode(args.merchantNameRaw);
+  const buf = new Uint8Array(32 + 4 + nameBytes.length + 2 + 8 + 8 + 2);
+  const view = new DataView(buf.buffer);
+  let off = 0;
+  buf.set(args.bankTxnId, off);
+  off += 32;
+  view.setUint32(
+    off,
+    nameBytes.length,
+    true
+    /* little-endian */
+  );
+  off += 4;
+  buf.set(nameBytes, off);
+  off += nameBytes.length;
+  view.setUint16(off, args.mcc & 65535, true);
+  off += 2;
+  setU64LE(view, off, args.amountCents);
+  off += 8;
+  setI64LE(view, off, args.postedAt);
+  off += 8;
+  view.setUint16(off, args.accountLast4 & 65535, true);
+  off += 2;
+  return buf;
+}
+function encodeSubmitAttestedReceiptIxData(args) {
+  const disc = instructionDiscriminator("submit_attested_receipt");
+  const argBytes = encodeAttestedReceiptArgs(args);
+  const out = new Uint8Array(disc.length + argBytes.length);
+  out.set(disc, 0);
+  out.set(argBytes, disc.length);
+  return out;
+}
+function setU64LE(view, offset, value) {
+  if (value < 0n || value > 0xffffffffffffffffn) {
+    throw new RangeError(`u64 out of range: ${value}`);
+  }
+  view.setBigUint64(offset, value, true);
+}
+function setI64LE(view, offset, value) {
+  const min = -(1n << 63n);
+  const max = (1n << 63n) - 1n;
+  if (value < min || value > max) {
+    throw new RangeError(`i64 out of range: ${value}`);
+  }
+  view.setBigInt64(offset, value, true);
+}
+
+// src/enclave.ts
+var import_web33 = require("@solana/web3.js");
+var SESSION_INSTRUCTION_INDEX_SUBMIT_ATTESTED_RECEIPT = 5;
+var AttestedReceiptSubmitter = class {
+  constructor(opts) {
+    /** Cached so we don't round-trip the enclave on every submit. */
+    this.cachedSessionPubkey = null;
+    this.resolvedConfig = resolveConfig(opts.network ?? "devnet");
+    this.enclaveSigner = opts.enclaveSigner;
+    this.vault = opts.vault;
+    this.sessionRegistrationPda = deriveAgentSessionPda({
+      vaultProgramId: this.resolvedConfig.vaultProgramId,
+      vault: opts.vault,
+      sessionPubkey: opts.sessionPubkey
+    }).pda;
+    this.commitment = opts.commitment ?? "confirmed";
+  }
+  /** Network selector this submitter was constructed against. */
+  get network() {
+    return this.resolvedConfig.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) {
+    return deriveBankAttestedReceiptPda({
+      shoppingProgramId: this.resolvedConfig.shoppingProgramId,
+      vault: this.vault,
+      bankTxnId
+    }).pda;
+  }
+  /**
+   * 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.
+   */
+  async submit(receipt) {
+    const validation = validateReceipt(receipt);
+    if (!validation.ok) {
+      return failV(validation.error);
+    }
+    let sessionSigner;
+    try {
+      sessionSigner = await this.getSessionPubkey();
+    } catch (err) {
+      return fail("enclave_sign_failed", errorMessage(err));
+    }
+    const receiptPda = this.deriveReceiptPda(receipt.bankTxnId);
+    const ix = this.buildSubmitIx({
+      receipt,
+      receiptPda,
+      sessionSigner
+    });
+    let blockhashCtx;
+    try {
+      blockhashCtx = await this.resolvedConfig.connection.getLatestBlockhash(
+        this.commitment
+      );
+    } catch (err) {
+      return fail("blockhash_fetch_failed", errorMessage(err));
+    }
+    const tx = new import_web33.Transaction({
+      feePayer: sessionSigner,
+      blockhash: blockhashCtx.blockhash,
+      lastValidBlockHeight: blockhashCtx.lastValidBlockHeight
+    }).add(ix);
+    const message = tx.serializeMessage();
+    let signature;
+    try {
+      signature = await this.enclaveSigner.signInstruction({
+        instructionIndex: SESSION_INSTRUCTION_INDEX_SUBMIT_ATTESTED_RECEIPT,
+        message,
+        policyInputs: {
+          amountCents: receipt.amountCents,
+          merchantNameRaw: receipt.merchantNameRaw,
+          postedAt: receipt.postedAt,
+          bankTxnId: receipt.bankTxnId
+        }
+      });
+    } catch (err) {
+      return fail("enclave_sign_failed", errorMessage(err));
+    }
+    if (signature.length !== 64) {
+      return fail(
+        "enclave_sign_failed",
+        `expected 64-byte ed25519 signature; got ${signature.length}`
+      );
+    }
+    tx.addSignature(sessionSigner, Buffer.from(signature));
+    if (!tx.verifySignatures()) {
+      return fail(
+        "session_pubkey_mismatch",
+        "enclave signature does not verify against session_signer pubkey"
+      );
+    }
+    let txSig;
+    try {
+      const sendOpts = {
+        skipPreflight: false,
+        preflightCommitment: this.commitment
+      };
+      txSig = await this.resolvedConfig.connection.sendRawTransaction(
+        tx.serialize(),
+        sendOpts
+      );
+    } catch (err) {
+      return fail("transaction_send_failed", errorMessage(err));
+    }
+    try {
+      await this.resolvedConfig.connection.confirmTransaction(
+        {
+          signature: txSig,
+          blockhash: blockhashCtx.blockhash,
+          lastValidBlockHeight: blockhashCtx.lastValidBlockHeight
+        },
+        this.commitment
+      );
+    } catch (err) {
+      return fail("transaction_confirm_failed", errorMessage(err));
+    }
+    return { ok: true, signature: txSig, receiptPda };
+  }
+  /**
+   * 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`.
+   */
+  async submitBatch(receipts, opts = {}) {
+    const concurrency = Math.max(1, opts.concurrency ?? 4);
+    const rateLimitMs = Math.max(0, opts.rateLimitMs ?? 0);
+    const total = receipts.length;
+    const results = new Array(total);
+    let nextIndex = 0;
+    const worker = async () => {
+      while (true) {
+        const i = nextIndex++;
+        if (i >= total) return;
+        if (rateLimitMs > 0 && i > 0) {
+          await sleep(rateLimitMs);
+        }
+        const r = await this.submit(receipts[i]);
+        results[i] = r;
+        opts.onProgress?.({ index: i, total, result: r });
+      }
+    };
+    await Promise.all(
+      Array.from({ length: Math.min(concurrency, total) }, () => worker())
+    );
+    return results;
+  }
+  // ────────────────────────────────────────────────────────────────────
+  // Internal
+  // ────────────────────────────────────────────────────────────────────
+  async getSessionPubkey() {
+    if (this.cachedSessionPubkey) return this.cachedSessionPubkey;
+    const pk = await this.enclaveSigner.getSessionPubkey();
+    this.cachedSessionPubkey = pk;
+    return pk;
+  }
+  buildSubmitIx(args) {
+    const data = encodeSubmitAttestedReceiptIxData({
+      bankTxnId: args.receipt.bankTxnId,
+      merchantNameRaw: args.receipt.merchantNameRaw,
+      mcc: args.receipt.mcc,
+      amountCents: args.receipt.amountCents,
+      postedAt: args.receipt.postedAt,
+      accountLast4: args.receipt.accountLast4
+    });
+    const statePda = deriveShoppingStatePda({
+      shoppingProgramId: this.resolvedConfig.shoppingProgramId
+    }).pda;
+    return new import_web33.TransactionInstruction({
+      programId: this.resolvedConfig.shoppingProgramId,
+      keys: [
+        { pubkey: args.sessionSigner, isSigner: true, isWritable: true },
+        { pubkey: statePda, isSigner: false, isWritable: false },
+        { pubkey: this.vault, isSigner: false, isWritable: false },
+        { pubkey: this.sessionRegistrationPda, isSigner: false, isWritable: false },
+        { pubkey: args.receiptPda, isSigner: false, isWritable: true },
+        { pubkey: import_web33.SystemProgram.programId, isSigner: false, isWritable: false }
+      ],
+      data: Buffer.from(data)
+    });
+  }
+};
+function fail(error, detail) {
+  return detail !== void 0 ? { ok: false, error, detail } : { ok: false, error };
+}
+function failV(error) {
+  return { ok: false, error: "validation_failed", detail: error };
+}
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/verifier.ts
+var import_web34 = require("@solana/web3.js");
+var import_node_crypto3 = require("crypto");
+var ReceiptNotAuditedError = class extends Error {
+  constructor(receipt) {
+    super(
+      `Receipt ${receipt.pda.toBase58()} produced by an unaudited enclave image (pcr0 not in EnclaveImageRegistry)`
+    );
+    this.receipt = receipt;
+    this.name = "ReceiptNotAuditedError";
+  }
+};
+var ReceiptNotFoundError = class extends Error {
+  constructor(pda) {
+    super(`No BankAttestedReceipt account at ${pda.toBase58()}`);
+    this.pda = pda;
+    this.name = "ReceiptNotFoundError";
+  }
+};
+var UnsupportedProofTypeError = class extends Error {
+  constructor(proofType) {
+    super(`Unsupported receipt proof type: ${proofType}`);
+    this.proofType = proofType;
+    this.name = "UnsupportedProofTypeError";
+  }
+};
+function verifyAttestedReceiptProof(receipt) {
+  switch (receipt.proof.proof_type) {
+    case "cose_sign1_x509":
+      verifyCoseSign1X509ProofShape(receipt);
+      return { ok: true, proof_type: "cose_sign1_x509" };
+    case "risc0_v1":
+    case "groth16_alt_bn128":
+      throw new UnsupportedProofTypeError(receipt.proof.proof_type);
+    default: {
+      const unreachable = receipt.proof;
+      throw new UnsupportedProofTypeError(
+        unreachable.proof_type
+      );
+    }
+  }
+}
+function verifyCoseSign1X509ProofShape(receipt) {
+  if (receipt.proof.proof_type !== "cose_sign1_x509") return;
+  if (!(receipt.proof.signature instanceof Uint8Array)) {
+    throw new Error("cose_sign1_x509 signature must be bytes");
+  }
+  if (!Array.isArray(receipt.proof.cert_chain)) {
+    throw new Error("cose_sign1_x509 cert_chain must be an array");
+  }
+  for (const cert of receipt.proof.cert_chain) {
+    if (!(cert instanceof Uint8Array)) {
+      throw new Error("cose_sign1_x509 cert_chain entries must be bytes");
+    }
+  }
+}
+var BANK_ATTESTED_RECEIPT_DISC = anchorAccountDiscriminator(
+  "BankAttestedReceipt"
+);
+var ENCLAVE_IMAGE_REGISTRY_DISC = anchorAccountDiscriminator(
+  "EnclaveImageRegistry"
+);
+function anchorAccountDiscriminator(typeName) {
+  const h = (0, import_node_crypto3.createHash)("sha256").update(`account:${typeName}`).digest();
+  return new Uint8Array(h.subarray(0, 8));
+}
+var AttestedReceiptVerifier = class {
+  constructor(opts = {}) {
+    /** Cache of approved PCR0s. */
+    this.approvedPcr0s = null;
+    this.approvedPcr0sExpiresAt = 0;
+    this.resolvedConfig = resolveConfig(opts.network ?? "devnet");
+    this.registryCacheMs = opts.registryCacheMs ?? 6e4;
+    this.skipImageAudit = opts.skipImageAudit ?? false;
+  }
+  get network() {
+    return this.resolvedConfig.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.
+   */
+  async fetch(pda, opts = {}) {
+    const account = await this.resolvedConfig.connection.getAccountInfo(
+      pda,
+      this.resolvedConfig.connection.commitment ?? "confirmed"
+    );
+    if (!account) throw new ReceiptNotFoundError(pda);
+    const decoded = decodeBankAttestedReceipt(pda, account);
+    const audited = await this.auditPcr0(decoded.pcr0);
+    decoded.imageAudited = audited;
+    if (opts.requireAuditedImage && audited === false) {
+      throw new ReceiptNotAuditedError(decoded);
+    }
+    return decoded;
+  }
+  /**
+   * 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`).
+   */
+  async *forVault(vault) {
+    const filters = [
+      // Discriminator filter — only BankAttestedReceipt accounts.
+      {
+        memcmp: {
+          offset: 0,
+          bytes: bs58Encode(BANK_ATTESTED_RECEIPT_DISC)
+        }
+      },
+      // Vault filter at offset 8 (immediately after discriminator).
+      {
+        memcmp: {
+          offset: 8,
+          bytes: bs58Encode(vault.toBytes())
+        }
+      }
+    ];
+    const accounts = await this.resolvedConfig.connection.getProgramAccounts(
+      this.resolvedConfig.shoppingProgramId,
+      { filters }
+    );
+    for (const { pubkey, account } of accounts) {
+      const decoded = decodeBankAttestedReceipt(pubkey, account);
+      decoded.imageAudited = await this.auditPcr0(decoded.pcr0);
+      yield decoded;
+    }
+  }
+  /**
+   * 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.
+   */
+  async *forMerchant(merchantNameNormalized) {
+    const target = normalizeMerchantName(merchantNameNormalized);
+    const filters = [
+      {
+        memcmp: {
+          offset: 0,
+          bytes: bs58Encode(BANK_ATTESTED_RECEIPT_DISC)
+        }
+      }
+    ];
+    const accounts = await this.resolvedConfig.connection.getProgramAccounts(
+      this.resolvedConfig.shoppingProgramId,
+      { filters }
+    );
+    for (const { pubkey, account } of accounts) {
+      const decoded = decodeBankAttestedReceipt(pubkey, account);
+      if (normalizeMerchantName(decoded.merchantNameRaw) !== target) continue;
+      decoded.imageAudited = await this.auditPcr0(decoded.pcr0);
+      yield decoded;
+    }
+  }
+  /**
+   * Force a refresh of the EnclaveImageRegistry cache. Useful in long-
+   * running daemons that want to pick up admin updates immediately.
+   */
+  async refreshImageRegistry() {
+    this.approvedPcr0sExpiresAt = 0;
+    await this.loadApprovedPcr0s();
+  }
+  // ────────────────────────────────────────────────────────────────────
+  // Internal
+  // ────────────────────────────────────────────────────────────────────
+  async auditPcr0(pcr0) {
+    if (this.skipImageAudit) return null;
+    const set = await this.loadApprovedPcr0s();
+    return set.has(toHex(pcr0));
+  }
+  async loadApprovedPcr0s() {
+    if (this.approvedPcr0s && Date.now() < this.approvedPcr0sExpiresAt) {
+      return this.approvedPcr0s;
+    }
+    const [registryPda] = import_web34.PublicKey.findProgramAddressSync(
+      [Buffer.from("enclave_image_registry")],
+      this.resolvedConfig.vaultProgramId
+    );
+    const account = await this.resolvedConfig.connection.getAccountInfo(
+      registryPda
+    );
+    const set = account ? decodeRegistryPcr0Set(account) : /* @__PURE__ */ new Set();
+    this.approvedPcr0s = set;
+    this.approvedPcr0sExpiresAt = Date.now() + this.registryCacheMs;
+    return set;
+  }
+};
+function decodeBankAttestedReceipt(pda, account) {
+  const data = account.data;
+  if (data.length < 8) {
+    throw new Error(`Account too small to be a BankAttestedReceipt: ${data.length} bytes`);
+  }
+  if (!bytesEqual(data.subarray(0, 8), BANK_ATTESTED_RECEIPT_DISC)) {
+    throw new Error(
+      `Discriminator mismatch at ${pda.toBase58()} \u2014 not a BankAttestedReceipt`
+    );
+  }
+  let off = 8;
+  const vault = new import_web34.PublicKey(data.subarray(off, off + 32));
+  off += 32;
+  const sessionPubkey = new import_web34.PublicKey(data.subarray(off, off + 32));
+  off += 32;
+  const pcr0 = new Uint8Array(data.subarray(off, off + 48));
+  off += 48;
+  const bankTxnId = new Uint8Array(data.subarray(off, off + 32));
+  off += 32;
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const nameLen = view.getUint32(off, true);
+  off += 4;
+  if (nameLen > 64) {
+    throw new Error(
+      `merchant_name_raw length ${nameLen} exceeds on-chain cap of 64`
+    );
+  }
+  const merchantNameRaw = new TextDecoder().decode(
+    data.subarray(off, off + nameLen)
+  );
+  off += nameLen;
+  const mcc = view.getUint16(off, true);
+  off += 2;
+  const amountCents = view.getBigUint64(off, true);
+  off += 8;
+  const postedAt = view.getBigInt64(off, true);
+  off += 8;
+  const accountLast4 = view.getUint16(off, true);
+  off += 2;
+  const submittedAt = view.getBigInt64(off, true);
+  off += 8;
+  const statusRaw = view.getUint8(off);
+  off += 1;
+  return {
+    pda,
+    vault,
+    sessionPubkey,
+    pcr0,
+    bankTxnId,
+    merchantNameRaw,
+    mcc,
+    amountCents,
+    postedAt,
+    accountLast4,
+    submittedAt,
+    status: statusFromByte(statusRaw),
+    imageAudited: null
+    // populated by the verifier
+  };
+}
+function statusFromByte(byte) {
+  switch (byte) {
+    case 0:
+      return "recorded";
+    case 1:
+      return "honored";
+    case 2:
+      return "invalidated";
+    default:
+      throw new Error(`Unknown receipt status byte: ${byte}`);
+  }
+}
+function decodeRegistryPcr0Set(account) {
+  const data = account.data;
+  if (data.length < 8) return /* @__PURE__ */ new Set();
+  if (!bytesEqual(data.subarray(0, 8), ENCLAVE_IMAGE_REGISTRY_DISC)) {
+    return /* @__PURE__ */ new Set();
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let off = 8;
+  off += 32;
+  const vecLen = view.getUint32(off, true);
+  off += 4;
+  const set = /* @__PURE__ */ new Set();
+  const ENTRY_SIZE = 48 + 48 + 48 + 32 + 8;
+  for (let i = 0; i < vecLen; i++) {
+    const pcr0 = data.subarray(off, off + 48);
+    set.add(toHex(pcr0));
+    off += ENTRY_SIZE;
+  }
+  return set;
+}
+function toHex(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) {
+    s += bytes[i].toString(16).padStart(2, "0");
+  }
+  return s;
+}
+function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+function bs58Encode(bytes) {
+  const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+  let n = 0n;
+  for (let i = 0; i < bytes.length; i++) {
+    n = (n << 8n) + BigInt(bytes[i]);
+  }
+  let out = "";
+  while (n > 0n) {
+    const rem = Number(n % 58n);
+    n = n / 58n;
+    out = ALPHABET[rem] + out;
+  }
+  for (let i = 0; i < bytes.length && bytes[i] === 0; i++) {
+    out = "1" + out;
+  }
+  return out;
+}
+
+// src/client/LoopByoaaClient.ts
+var LoopByoaaError = class extends Error {
+  constructor(code, message, context = {}) {
+    super(message);
+    this.name = "LoopByoaaError";
+    this.code = code;
+    this.status = context.status;
+    this.request_id = context.request_id;
+    this.documentation_url = context.documentation_url;
+    this.details = context.details;
+  }
+};
+var LoopByoaaApiKeyError = class extends LoopByoaaError {
+  constructor(code, message, context = {}) {
+    super(code, message, context);
+    this.name = "LoopByoaaApiKeyError";
+  }
+};
+var LoopByoaaPermissionError = class extends LoopByoaaError {
+  constructor(code, message, context = {}) {
+    super(code, message, context);
+    this.name = "LoopByoaaPermissionError";
+  }
+};
+var LoopByoaaRateLimitError = class extends LoopByoaaError {
+  constructor(code, message, context = {}) {
+    super(code, message, context);
+    this.name = "LoopByoaaRateLimitError";
+    this.retry_after_seconds = context.retry_after_seconds;
+  }
+};
+var LoopByoaaQuotaError = class extends LoopByoaaError {
+  constructor(code, message, context = {}) {
+    super(code, message, context);
+    this.name = "LoopByoaaQuotaError";
+    this.meter_name = context.meter_name;
+    this.upgrade_url = context.upgrade_url;
+  }
+};
+var LoopByoaaValidationError = class extends LoopByoaaError {
+  constructor(code, message, context = {}) {
+    super(code, message, context);
+    this.name = "LoopByoaaValidationError";
+  }
+};
+var LoopByoaaServerError = class extends LoopByoaaError {
+  constructor(code, message, context = {}) {
+    super(code, message, context);
+    this.name = "LoopByoaaServerError";
+  }
+};
+var LoopByoaaNetworkError = class extends LoopByoaaError {
+  constructor(message, context = {}) {
+    super("network_error", message, context);
+    this.name = "LoopByoaaNetworkError";
+  }
+};
+var ENV_BASE_URLS = {
+  dev: "https://dev-api.kya.looplocal.io",
+  staging: "https://staging-api.kya.looplocal.io",
+  prod: "https://prod-api.kya.loopprotocol.com"
+};
+function baseUrlForEnv(env) {
+  return ENV_BASE_URLS[env];
+}
+function parseLoopByoaaSdkKey(apiKey) {
+  const match = /^loop_byoaa_(dev|staging|prod)_([A-Za-z0-9]{32})$/.exec(apiKey);
+  if (!match) {
+    throw new LoopByoaaApiKeyError(
+      "invalid_api_key",
+      "Loop BYOAA SDK keys must match loop_byoaa_<dev|staging|prod>_<32 base62 characters>"
+    );
+  }
+  const env = match[1];
+  return {
+    env,
+    prefix: `loop_byoaa_${env}`,
+    hashable: apiKey
+  };
+}
+function envForKnownBaseUrl(baseUrl) {
+  const cleaned = cleanBaseUrl(baseUrl);
+  return Object.entries(ENV_BASE_URLS).find(
+    ([, knownUrl]) => cleanBaseUrl(knownUrl) === cleaned
+  )?.[0];
+}
+function cleanBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/+$/, "");
+}
+function encodeValue(value) {
+  if (value instanceof Date) return value.toISOString();
+  return String(value);
+}
+function toQuery(params) {
+  if (!params) return "";
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    query.set(key, encodeValue(value));
+  }
+  const encoded = query.toString();
+  return encoded ? `?${encoded}` : "";
+}
+function normalizeBody(value) {
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) return value.map(normalizeBody);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, normalizeBody(entry)])
+    );
+  }
+  return value;
+}
+function readHeader(headers, name) {
+  return headers.get(name) ?? headers.get(name.toLowerCase()) ?? void 0;
+}
+function errorFromResponse(status, payload, headers) {
+  const nested = payload.error && typeof payload.error === "object" && !Array.isArray(payload.error) ? payload.error : void 0;
+  const envelope = nested ?? payload;
+  const details = envelope.details && typeof envelope.details === "object" && !Array.isArray(envelope.details) ? envelope.details : void 0;
+  const code = String(envelope.code ?? (status >= 500 ? "server_error" : "unknown"));
+  const message = String(envelope.message ?? `Loop BYOAA request failed with HTTP ${status}`);
+  const retryAfterSeconds = typeof details?.retry_after_seconds === "number" ? details.retry_after_seconds : typeof envelope.retry_after_seconds === "number" ? envelope.retry_after_seconds : Number(readHeader(headers, "retry-after")) || void 0;
+  const context = {
+    status,
+    request_id: typeof envelope.request_id === "string" ? envelope.request_id : readHeader(headers, "x-request-id"),
+    documentation_url: typeof envelope.documentation_url === "string" ? envelope.documentation_url : void 0,
+    retry_after_seconds: retryAfterSeconds,
+    meter_name: typeof envelope.meter_name === "string" ? envelope.meter_name : void 0,
+    upgrade_url: typeof envelope.upgrade_url === "string" ? envelope.upgrade_url : void 0,
+    details: envelope.details
+  };
+  if (status === 401 || status === 403 || code === "auth" || code === "invalid_api_key") {
+    return status === 403 || code === "permission_denied" ? new LoopByoaaPermissionError(code, message, context) : new LoopByoaaApiKeyError(code, message, context);
+  }
+  if (status === 400 || status === 422 || code === "validation") return new LoopByoaaValidationError(code, message, context);
+  if (status === 429 || code === "rate_limit") return new LoopByoaaRateLimitError(code, message, context);
+  if (status === 402 || code === "quota") return new LoopByoaaQuotaError(code, message, context);
+  if (status >= 500) return new LoopByoaaServerError(code, message, context);
+  return new LoopByoaaError(code, message, context);
+}
+var HttpClient = class {
+  constructor(apiKey, baseUrl, fetchImpl, timeout) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+    this.fetchImpl = fetchImpl;
+    this.timeout = timeout;
+  }
+  async request(method, path, body, query) {
+    const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
+    const timer = controller ? setTimeout(() => controller.abort(), this.timeout) : void 0;
+    const hasBody = body !== void 0;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "application/json"
+    };
+    if (hasBody) headers["Content-Type"] = "application/json";
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}${path}${toQuery(query)}`, {
+        method,
+        headers,
+        body: hasBody ? JSON.stringify(normalizeBody(body)) : void 0,
+        signal: controller?.signal
+      });
+      if (timer) clearTimeout(timer);
+      const text = await response.text();
+      const payload = text ? JSON.parse(text) : void 0;
+      if (!response.ok) {
+        throw errorFromResponse(response.status, payload ?? {}, response.headers);
+      }
+      return payload;
+    } catch (error) {
+      if (timer) clearTimeout(timer);
+      if (error instanceof LoopByoaaError) throw error;
+      throw new LoopByoaaNetworkError(error instanceof Error ? error.message : "Loop BYOAA network request failed");
+    }
+  }
+};
+function unwrapGatewayEnvelope(payload, key) {
+  if (payload && typeof payload === "object" && !Array.isArray(payload) && key in payload) {
+    return payload[key];
+  }
+  return payload;
+}
+function unwrapGatewayList(payload, key) {
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    const record = payload;
+    if (Array.isArray(record[key])) return { items: record[key] };
+    if (Array.isArray(record.items)) return record;
+  }
+  return payload;
+}
+var LoopByoaaClient = class {
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new LoopByoaaApiKeyError("auth", "Loop BYOAA apiKey is required");
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new LoopByoaaNetworkError("Loop BYOAA requires a fetch implementation in this runtime");
+    }
+    const parsedKey = parseLoopByoaaSdkKey(options.apiKey);
+    const requestedBaseUrl = options.baseUrl ?? baseUrlForEnv(parsedKey.env);
+    const knownEnv = envForKnownBaseUrl(requestedBaseUrl);
+    if (knownEnv && knownEnv !== parsedKey.env) {
+      throw new LoopByoaaApiKeyError(
+        "cross_env_key_use",
+        `Loop BYOAA ${parsedKey.env} keys cannot call ${knownEnv} endpoints`,
+        { details: { key_env: parsedKey.env, endpoint_env: knownEnv } }
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.env = parsedKey.env;
+    this.parsedKey = parsedKey;
+    this.baseUrl = cleanBaseUrl(requestedBaseUrl);
+    const http = new HttpClient(this.apiKey, this.baseUrl, fetchImpl, options.timeout ?? 1e4);
+    this.agents = new AgentsNamespace(http);
+    this.permissions = new PermissionsNamespace(http);
+    this.decisions = new DecisionsNamespace(http);
+    this.audit = new AuditNamespace(http);
+  }
+};
+var AgentsNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  register(input) {
+    return this.http.request("POST", "/api/v1/kya/agents/register", input).then((payload) => unwrapGatewayEnvelope(payload, "agent"));
+  }
+  list(params = {}) {
+    return this.http.request("GET", "/api/v1/kya/agents", void 0, params).then((payload) => unwrapGatewayList(payload, "agents"));
+  }
+  get(agentIdOrExternalId) {
+    return this.http.request("GET", `/api/v1/kya/agents/${encodeURIComponent(agentIdOrExternalId)}`).then((payload) => unwrapGatewayEnvelope(payload, "agent"));
+  }
+  update(id, input) {
+    return this.http.request("PATCH", `/api/v1/kya/agents/${encodeURIComponent(id)}`, input);
+  }
+  suspend(id, reason) {
+    return this.http.request("POST", `/api/v1/kya/agents/${encodeURIComponent(id)}/suspend`, { reason });
+  }
+  revoke(id, reason) {
+    return this.http.request("POST", `/api/v1/kya/agents/${encodeURIComponent(id)}/revoke`, { reason });
+  }
+};
+var PermissionsNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  grant(input) {
+    return this.http.request("POST", "/api/v1/kya/permissions/grant", input).then((payload) => unwrapGatewayEnvelope(payload, "permission"));
+  }
+  list(params = {}) {
+    return this.http.request("GET", "/api/v1/kya/permissions", void 0, params).then((payload) => unwrapGatewayList(payload, "permissions"));
+  }
+  get(grantId) {
+    return this.http.request("GET", `/api/v1/kya/permissions/${encodeURIComponent(grantId)}`).then((payload) => unwrapGatewayEnvelope(payload, "permission"));
+  }
+  revoke(grantId, input) {
+    return this.http.request("POST", `/api/v1/kya/permissions/${encodeURIComponent(grantId)}/revoke`, input);
+  }
+};
+var DecisionsNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  request(input) {
+    return this.http.request("POST", "/api/v1/kya/decisions/request", input);
+  }
+  get(envelopeId) {
+    return this.http.request("GET", `/api/v1/kya/decisions/${encodeURIComponent(envelopeId)}`).then((payload) => unwrapGatewayEnvelope(payload, "decision"));
+  }
+  list(params = {}) {
+    return this.http.request("GET", "/api/v1/kya/decisions", void 0, params).then((payload) => unwrapGatewayList(payload, "decisions"));
+  }
+};
+var AuditNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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) {
+    return this.http.request("GET", "/api/v1/kya/audit/export-pack", void 0, { limit: 200 }).then((payload) => unwrapGatewayEnvelope(payload, "export_pack"));
+  }
+  export(input) {
+    return this.exportPack(input);
+  }
+  list(params = {}) {
+    return this.http.request("GET", "/api/v1/kya/audit/events", void 0, params).then((payload) => unwrapGatewayList(payload, "events"));
+  }
+  get(eventId) {
+    return this.http.request("GET", `/api/v1/kya/audit/events/${encodeURIComponent(eventId)}`).then((payload) => unwrapGatewayEnvelope(payload, "event"));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentsNamespace,
+  AttestedReceiptSubmitter,
+  AttestedReceiptVerifier,
+  AuditNamespace,
+  DEVNET_PROGRAM_IDS,
+  DecisionsNamespace,
+  LoopByoaaApiKeyError,
+  LoopByoaaClient,
+  LoopByoaaError,
+  LoopByoaaNetworkError,
+  LoopByoaaPermissionError,
+  LoopByoaaQuotaError,
+  LoopByoaaRateLimitError,
+  LoopByoaaServerError,
+  LoopByoaaValidationError,
+  MAINNET_PROGRAM_IDS,
+  MAX_MERCHANT_NAME_RAW_LEN,
+  MAX_RECEIPT_AGE_SECONDS,
+  MAX_RECEIPT_CENTS,
+  PermissionsNamespace,
+  ReceiptNotAuditedError,
+  ReceiptNotFoundError,
+  SESSION_INSTRUCTION_INDEX_SUBMIT_ATTESTED_RECEIPT,
+  UnsupportedProofTypeError,
+  decodeBankAttestedReceipt,
+  decodeRegistryPcr0Set,
+  defaultRpcUrl,
+  deriveAgentSessionPda,
+  deriveBankAttestedReceiptPda,
+  deriveBankTxnId,
+  deriveShoppingStatePda,
+  encodeAttestedReceiptArgs,
+  encodeSubmitAttestedReceiptIxData,
+  getProgramIds,
+  instructionDiscriminator,
+  isMainnet,
+  normalizeMerchantName,
+  parseLoopByoaaSdkKey,
+  resolveConfig,
+  validateReceipt,
+  verifyAttestedReceiptProof
+});