@cloak.dev/sdk 0.2.2 → 0.2.3-staging.f2d7f2a

package/dist/index.d.cts

@@ -2931,6 +2931,27 @@ interface ExternalFeePayerAdapter {
      */
     getPaymentAccountHints?: () => Promise<PublicKey[]>;
 }
+/**
+ * Refuse a transaction whose input notes do not agree on a mint, or do not
+ * agree with the mint the caller says it is spending.
+ *
+ * TWO SEPARATE PROPERTIES, and they catch different mistakes:
+ *
+ *  1. HOMOGENEITY, always enforced. Every pool is a single mint, so a set of
+ *     inputs spanning two mints cannot be a valid spend of either. There is no
+ *     legitimate call that does this, so it needs no opt-in. Zero-amount
+ *     padding notes are exempt: they are placeholders, not value.
+ *
+ *  2. INTENT, enforced when `options.expectedMint` is given. Homogeneity alone
+ *     cannot catch the dangerous case — ONE note of the wrong mint is a
+ *     perfectly homogeneous set. Only the caller knows which asset the user
+ *     asked for, so only the caller can supply it, and this is where it is
+ *     checked.
+ *
+ * The error names both mints, because the whole failure mode is that the two
+ * were assumed to be the same.
+ */
+declare function assertInputMints(inputUtxos: Utxo[], expectedMint?: PublicKey): void;
 /**
  * Options for transact operation
  */
@@ -3184,6 +3205,31 @@ interface TransactOptions {
      * transaction. Omit for unchanged default behavior.
      */
     externalFeePayer?: ExternalFeePayerAdapter;
+    /**
+     * The mint the CALLER believes it is spending. When set, the SDK refuses the
+     * transaction if the input notes say otherwise.
+     *
+     * ── Why this exists ────────────────────────────────────────────────────────
+     * Every flow takes the pool from the notes it is handed
+     * (`inputUtxos[0].mintAddress`), which is correct — the notes are the source
+     * of truth for which pool they belong to. But it means the SDK cannot tell a
+     * deliberate USDC withdrawal from a SOL withdrawal that was handed a USDC
+     * note by mistake. Both are well-formed, both prove, and both settle.
+     *
+     * A consumer hit exactly that: its note selector sorted by RAW base units
+     * across a store holding every mint, so with 6-decimal USDC and 9-decimal
+     * SOL a stablecoin note outranked every SOL note whenever
+     * `usdc > 1000 * sol`. A user sending 0.05 SOL moved ~50 USDC to the
+     * recipient instead, and every layer reported SOL.
+     *
+     * Nothing about that is a protocol failure — the proof, the nullifier and the
+     * pool accounting are all correct, and the user spent their own note. It is a
+     * failure of INTENT, and intent is the one thing only the caller knows. So
+     * the caller may now state it, and the SDK will hold it.
+     *
+     * Optional for backward compatibility, but pass it on every flow you can.
+     */
+    expectedMint?: PublicKey;
 }
 /**
  * Switchboard-style response: a pre-built instruction.
@@ -4668,14 +4714,691 @@ declare class SimpleWallet {
     sync(): Promise<void>;
 }
 
+/**
+ * What a quote option attests, which is NOT the same question as whether the rail worked.
+ *
+ * Mirrors the service's `rails::Attestation` enum field-for-field (`services/api/bridge/src/rails/
+ * mod.rs`) rather than collapsing it into a boolean: 1Click signs the deposit address AND the
+ * recipient, so a substituted address is detectable by the client even if the service substituted
+ * it. Jupiter signs nothing, so on that rail the user is trusting Cloak — and a UI reading this
+ * union is forced to say so, where a UI reading a boolean could quietly treat both the same.
+ */
+type BridgeRailAttestation = {
+    kind: "ed25519";
+    verified: boolean;
+    signer: string;
+} | {
+    kind: "none";
+    checks: string[];
+    note: string;
+};
+interface BridgeRailQuoteOption {
+    /** `"oneclick" | "jupiter"` today; typed as `string` so a new rail the service adds is not a
+     *  compile error here — the attestation union is what a caller must actually branch on. */
+    rail: string;
+    /** False means a mis-sent or under-filled transfer has NO automated recovery on this rail. */
+    refunds: boolean;
+    /** Whether `depositAddress` is reusable, or fresh per order and expiring. */
+    addressLifetime: string;
+    /** What the rail expects to deliver. NOT a promise — never display this alone. */
+    amountOut: bigint;
+    /** The floor the rail commits to. This is the number a UI should lead with. */
+    minAmountOut: bigint;
+    timeEstimateSeconds?: number;
+    /** The rail's own expiry, when it returns one. Do not invent a value it attests to. */
+    expiresAt?: string;
+    /** Where the user sends funds on the origin chain. Absent on a dry quote (`allocate: false`),
+     *  where nothing has been reserved and there is nothing to send to yet. */
+    depositAddress?: string;
+    attestation: BridgeRailAttestation;
+}
+interface BridgeRailProblem {
+    rail: string;
+    reason: string;
+}
+interface BridgeRailQuoteRequest {
+    /** The derived receiving address R. Base58, on Solana. */
+    recipient: string;
+    originChain: string;
+    /** Base units on the origin chain, as a bigint — a JS `number` loses precision above 2^53 and
+     *  this can be an arbitrary token amount. */
+    amountBaseUnits: bigint;
+    /** Origin-chain address an unfillable 1Click order refunds to. Required for that rail. */
+    refundTo?: string;
+    rails?: string[];
+    /** False (the default) sends `dry: true` to 1Click and skips GUM's allocation probes: nothing is
+     *  reserved and no `depositAddress` comes back. Requesting an allocation for a deposit the quote
+     *  gate might still refuse is the wrong order of operations — leave this false until the caller
+     *  has already decided to proceed. */
+    allocate?: boolean;
+}
+interface BridgeRailQuoteResponse {
+    options: BridgeRailQuoteOption[];
+    /** Errors from rails that failed, so one rail being down does not hide the other's answer. */
+    unavailable: BridgeRailProblem[];
+}
+/**
+ * Mirrors the service's `api::status::DeliveryState` (`services/api/bridge/src/api/status.rs`),
+ * `snake_case` on the wire and identical here. `"unknown"` is a real answer, not a parse failure:
+ * Jupiter/GUM hands out permanent deposit addresses and has no per-transfer status API, so on
+ * that rail the service ALWAYS answers `"unknown"` and says so in `detail` — poll the recipient's
+ * on-chain balance instead. `"expired"` is derived by the service from the order deadline, not a
+ * value 1Click returns.
+ */
+type BridgeDeliveryState = "pending" | "delivered" | "refunded" | "expired" | "unknown";
+interface BridgeRailStatusResult {
+    /** The rail that answered, echoed from the service. */
+    rail: string;
+    state: BridgeDeliveryState;
+    /** The service's own explanation of `state`, e.g. why a `"jupiter"` query is `"unknown"`. */
+    detail: string;
+}
+interface BridgeRail {
+    readonly id: string;
+    quote(req: BridgeRailQuoteRequest): Promise<BridgeRailQuoteResponse>;
+    /**
+     * `rail` is the `rail` of the quote option whose `depositAddress` this is: the service keys its
+     * status lookup on (address, rail) because the two rails have unrelated status surfaces.
+     */
+    status(depositAddress: string, rail: string): Promise<BridgeRailStatusResult>;
+}
+/**
+ * The one constructor this package exposes for talking to the bridge rails — always through
+ * Cloak's own service, never through a rail's API or Kora.
+ *
+ * `relayUrl` is checked HERE, at construction, in addition to the check `relayFetch` repeats on
+ * every call: a caller who mistypes a rail's own base URL (or Kora's) finds out immediately rather
+ * than on first use, and `assertAllowedRelayOrigin` in this function's own body is what lets
+ * `relay-origin-lock.test.ts` enumerate this door the same way it enumerates `RelayService`'s
+ * constructor.
+ */
+declare function cloakBridgeRail(relayUrl: string): BridgeRail;
+
+/**
+ * The paymaster client — the SOL top-up that lets a bridge receiver R (which arrives holding only
+ * bridged tokens, no SOL) shield without the user's own wallet ever appearing on chain.
+ *
+ * Talks ONLY to Cloak's own bridge service (`api.cloak.ag/bridge/paymaster/*`), never to Kora
+ * directly: under fixed pricing (docs/00-DECISION-STATE.md, PAYMASTER ECONOMICS) the Kora API key is
+ * worth real money to whoever holds it, and a browser bundle is not a place that can keep a secret.
+ *
+ * ── The two-round-trip shape, and why it is not one call ─────────────────────────────────────
+ * `prepare` returns an UNSIGNED transaction the service built and priced, plus a voucher that MACs
+ * the exact message bytes. The client's receiving key R signs it — R never leaves the client, and
+ * this is the only place it signs anything for the paymaster flow — and hands the bytes back
+ * unchanged to `cosign`, which recognises them via the voucher and only THEN asks Kora to co-sign as
+ * fee payer. The paymaster's key never leaves the server; R's key never leaves the client; neither
+ * round trip needs the other's secret. See `services/api/bridge/src/api/paymaster.rs` for the
+ * server half of this contract.
+ *
+ * ── Why the shape check below is not optional ────────────────────────────────────────────────
+ * `cosign` answers exactly one question — "is this the message I built?" — and answers it by MAC,
+ * not by re-deriving policy from an arbitrary transaction. That makes `prepare`'s response the ONLY
+ * point where an unexpected instruction could sneak in (a compromised service, a MITM'd response, a
+ * bug that built the wrong thing), because nothing downstream re-checks it. `validate
+ * PaymasterTopUpTransaction` is that one check, and it runs BEFORE R signs anything: signing is the
+ * one irreversible step in this flow from the client's point of view, so the check that matters has
+ * to sit in front of it, not after.
+ */
+
+/** What `prepare`'s response is checked against before R ever signs it. */
+interface PaymasterTopUpExpectation {
+    /** R — the only account this transaction may fund or spend from. */
+    recipient: PublicKey;
+    /** The lamports we asked for. `ix0.lamports` may come in at or under this, never over. */
+    maxGrantLamports: bigint;
+    feeMint: PublicKey;
+    /** The fee Kora actually quoted at `prepare` time. `ix1.amount`, if `ix1` exists, must equal this
+     *  exactly — not "at most", because the fee is a quote the service already committed to, not a
+     *  ceiling. */
+    feeTokenAmount: bigint;
+    /** The paymaster's own token account owner, from `prepare`'s `payment_address`. `ix1`'s
+     *  destination must be exactly THIS address's ATA for `feeMint` — nothing else, and never an ATA
+     *  derived from `recipient` or from an address the caller does not already trust. */
+    paymentAddress: PublicKey;
+}
+/**
+ * The one check standing between `prepare`'s response and R's signature.
+ *
+ * Two instructions, and the shape IS the security story (`paymaster/topup.rs`'s own words, mirrored
+ * here on the verifying side):
+ *
+ *   ix0  System transfer, paymaster -> recipient, <= the lamports we asked for
+ *   ix1  (optional) SPL transfer, recipient's fee-mint ATA -> paymaster's fee-mint ATA, authority
+ *        = recipient, amount == the quoted fee
+ *
+ * Anything else — a third instruction, a different destination, a different authority, an amount
+ * that does not match the quote — is refused. This function throws rather than returning a verdict:
+ * there is no partial-trust path here, and a caller that wants to keep going after a refusal is a
+ * caller papering over a corrupted or hostile response.
+ */
+declare function validatePaymasterTopUpTransaction(tx: Transaction, expect: PaymasterTopUpExpectation): void;
+interface PaymasterTopUpResult {
+    /** Fully signed by both R and the paymaster. The caller submits it — Kora's own
+     *  `signAndSendTransaction` is disabled service-side, and the broadcast should not carry the
+     *  service's IP any more than the deposit itself should carry R's. */
+    transaction: Transaction;
+    feeTokenAmount: bigint;
+    feeMint: string;
+    paymentAddress: string;
+}
+/**
+ * The whole paymaster flow: prepare, verify the shape, sign as R, cosign, return the fully-signed
+ * transaction for the caller to submit.
+ *
+ * `receiver` is the derived bridge receiving key (`deriveBridgeReceiver`). It signs here and only
+ * here in this file's flow, and its secret never leaves this function — nothing above needs it, and
+ * nothing here sends it anywhere.
+ */
+declare function fundReceiverViaPaymaster(relayUrl: string, receiver: Keypair, grantLamports: bigint): Promise<PaymasterTopUpResult>;
+
+/**
+ * Deriving a bridge receiving address.
+ *
+ * One single-use address per deposit, from the wallet's own key material. Deterministic, offline,
+ * and stateless — which is what lets every other function here work on a device that has never
+ * seen this deposit before.
+ */
+
+declare const BRIDGE_ESCROW_LABEL = "cloak_bridge_escrow";
+/**
+ * The index MUST be a small sequential counter (0, 1, 2, …), never a timestamp.
+ *
+ * This is not a style preference: discovery works by deriving indices 0…N and reading each on
+ * chain. A timestamp index is unreachable by any scan, so a deposit made under one is invisible to
+ * every device except the one that made it — which is precisely the failure that made a resume
+ * link look necessary. The prototype harness used `Date.now()` for test hermeticity and those
+ * deposits are, correctly, undiscoverable.
+ */
+/**
+ * The largest index discovery could plausibly reach. A scan is one round of on-chain reads per
+ * index, so anything past a few thousand is not recoverable in practice — and a timestamp (~1.8e12)
+ * is not recoverable even in principle. Rejecting it here is the difference between the constraint
+ * being documented and it being enforced.
+ */
+declare const MAX_RECEIVER_INDEX = 10000;
+declare function deriveBridgeReceiver(nk: Uint8Array | Buffer, index: number): Keypair;
+
+/**
+ * Finding a user's bridge deposits from their key material alone.
+ *
+ * THIS IS THE FUNCTION THAT MAKES THE BRIDGE AN SDK CAPABILITY RATHER THAN A WEB FEATURE.
+ *
+ * Derive receivers for index 0…N and read each on chain. No stored state, no link to carry, no
+ * localStorage. It works on a device that has never seen the app, in a CLI, on mobile, after a
+ * browser wipe. An earlier design proposed a shareable URL to carry the deposit index to a second
+ * device; the index does not need carrying, it needs scanning, and the link it replaced was a
+ * packaged correlation between an origin payment and a Solana address about to enter the pool.
+ */
+
+type BridgeDepositState = 
+/** Nothing ever happened at this index. */
+"unused"
+/** Funded for a deposit, but no tokens have arrived. */
+ | "awaiting"
+/** Tokens are sitting at the receiver, in the open, not yet shielded. */
+ | "arrived"
+/** Shielded, and the receiver's token account has been closed. */
+ | "complete"
+/** Shielded, but the token account is still open and holding its rent. */
+ | "needs-cleanup"
+/**
+ * An RPC read failed while checking this index. This is NOT evidence of absence — it is the
+ * opposite of "unused" in every way that matters to a caller: a rate-limited or dropped read
+ * used to fall back to a zero/empty default, which reported a real deposit's index as nothing-
+ * here, indistinguishable from the index truly never having been touched. A user reading that
+ * concludes their money is gone. `error` on the deposit explains what failed; the fix is to
+ * retry, not to trust this entry's tokenBalance/lamports, which are placeholders.
+ */
+ | "unknown";
+interface BridgeDeposit {
+    index: number;
+    receiver: PublicKey;
+    tokenAccount: PublicKey;
+    state: BridgeDepositState;
+    /** Placeholder 0n when state is "unknown" — the read that would have set this failed. */
+    tokenBalance: bigint;
+    /** Placeholder 0 when state is "unknown" — the read that would have set this failed. */
+    lamports: number;
+    /** Signature of the shield-pool transaction, when one was found. Most recent, if more than one — see indexReused. */
+    shieldSignature?: string;
+    /**
+     * True when this receiver's own history holds more than one shield-pool transaction: this index
+     * was used for more than one deposit. Two deposits at the same index share one on-chain address,
+     * which links them to each other, and `shieldSignature` alone would silently pick one and hide
+     * that a second one exists. A caller MUST warn the user instead of treating this as a single
+     * ordinary deposit.
+     */
+    indexReused?: boolean;
+    /** Every shield-pool signature found at this receiver, most recent first. Present only when indexReused. */
+    shieldSignatures?: string[];
+    /** Set only when state is "unknown": the failure that made this index's status unconfirmable. */
+    error?: string;
+}
+interface DiscoverOptions {
+    /**
+     * How many indices to derive, starting at 0. Discovery is one to a few on-chain reads per index,
+     * so this bounds the cost of a scan — it is NOT a claim about where deposits can live. An index
+     * can be as large as MAX_RECEIVER_INDEX (10,000, see ./derive), and the default of 20 only covers
+     * indices allocated sequentially with the stopAfterUnused gap tolerance below. A caller with
+     * reason to believe a deposit landed further out (a CLI --index flag, a resumed session that
+     * knows its own counter) MUST pass a larger scanDepth explicitly — anything past the configured
+     * depth is simply never read, and reports as neither found nor absent, because it was not looked
+     * at. Clamped to MAX_RECEIVER_INDEX + 1 (the count of valid indices, 0 through MAX_RECEIVER_INDEX
+     * inclusive): deriveBridgeReceiver throws past that ceiling, and without the clamp a caller who
+     * over-estimates scanDepth turns that into a mid-scan crash that discards every deposit already
+     * found in the same call.
+     */
+    scanDepth?: number;
+    /** Stop after this many consecutive unused indices. An "unknown" index (RPC failure) neither
+     *  counts toward nor resets this run — it carries no information about presence or absence, so
+     *  letting it break a real run of unused indices early would reintroduce the same false-absence
+     *  failure this file exists to prevent. */
+    stopAfterUnused?: number;
+    programId: PublicKey;
+    mint: PublicKey;
+}
+/**
+ * A terminal state needs TWO conjuncts, never one.
+ *
+ * After the rent cleanup runs, "the receiver's token balance is zero" is indistinguishable from
+ * "nothing ever happened at this address". Deriving completion from balance alone overwrites a
+ * real completion record with an empty one — observed live, and it crashed the view that read it.
+ * Completion therefore requires the shield-pool transaction to be present in the receiver's own
+ * history as well.
+ */
+declare function listBridgeDeposits(conn: Connection, nk: Uint8Array | Buffer, opts: DiscoverOptions): Promise<BridgeDeposit[]>;
+
+/**
+ * The client half of a bridge deposit, from "tokens have arrived at R" onwards.
+ *
+ * This module is deliberately RAIL-AGNOSTIC. It is imported unchanged by:
+ *   - phase1-deposit.ts, where a seeded account plays the rail with a direct SPL transfer
+ *   - phase2-e2e.ts,     where the rail stand-in delivers over HTTP
+ *   - phase3-e2e.ts,     where a real Polygon fork drives the whole thing
+ *
+ * That import graph IS the proof of 11-E2E-PLAN.md Phase 2's pass criterion — "the client code
+ * from Phase 1 runs unchanged against the stand-in" — enforced structurally rather than by
+ * eyeballing two copies.
+ *
+ * It was NOT true when first written: phase1-deposit.ts kept its own inline copy, and so never
+ * received the CLEANUP_FEE_BUDGET fix that landed here and in funder.ts. A reviewer caught both
+ * the stale copy and the false claim. Keep every phase importing this file; do not fork it.
+ */
+
+interface DepositOutcome {
+    signature: string;
+    noteIndex: number;
+    amount: bigint;
+    txSize: number;
+    rBefore: number;
+    rAfter: number;
+    rentExempt: boolean;
+    /** The proof's two input nullifiers (zero-value padding for a pure deposit, but each one is a
+     *  genuine Poseidon hash over a random salt — NOT the literal zero sentinel the program treats
+     *  as "no PDA needed". See phase4-adversarial.ts case (c). */
+    inputNullifiers: bigint[];
+    /** The three program accounts the funding seam read off the built tx, and what it sent each —
+     *  0 if the account already held enough. Exposed so a caller can independently verify their
+     *  on-chain state afterward, including after a thrown error (see `DepositError` below). */
+    fundedAccounts: {
+        name: string;
+        address: string;
+        lamportsSent: number;
+    }[];
+}
+/** Thrown by `depositFromDerivedKey` in place of a bare `Error` whenever the funding seam ran
+ *  before the failure, so a caller can see exactly what already landed on chain despite the
+ *  overall deposit failing. `fundedAccounts` / `measuredSize` are `undefined` only if the seam
+ *  never ran at all (failure before signTransaction was called). */
+declare class DepositError extends Error {
+    readonly fundedAccounts: DepositOutcome["fundedAccounts"];
+    readonly measuredTxSize: number;
+    constructor(message: string, fundedAccounts: DepositOutcome["fundedAccounts"], measuredTxSize: number);
+}
+/**
+ * Fund R minimally, then deposit with R as the only signer.
+ *
+ * The funding seam is the SDK's `signTransaction`: by the time it is called the proof and the
+ * relay's risk quote both exist, so the three program accounts are READ OFF the built
+ * transaction rather than re-derived, and cannot drift from what the program will touch.
+ *
+ * `grantOverride` replaces the computed grant (rent floor + deposit fee + cleanup fee) with an
+ * arbitrary lamport amount. Only phase4-adversarial.ts case (a) passes it, to reproduce the
+ * "funded R with just its fee, not its floor" mistake deliberately; every other caller omits it
+ * and gets the same grant this function has always sent.
+ */
+declare function depositFromDerivedKey(conn: Connection, R: Keypair, funder: Keypair, amount: bigint, log: ((s: string) => void) | undefined, grantOverride: number | undefined, 
+/**
+ * relayUrl, programId and mint are all REQUIRED — no default, for any of the three, on any
+ * environment. They used to fall back to the module-level RELAY/PROGRAM/MINT constants above,
+ * each evaluated once at import time, and that is exactly how a live mainnet deposit got built
+ * against the local program id while the banner said api.cloak.ag: the default filled the hole
+ * silently instead of the caller having to say so. There is nothing left to fall into.
+ */
+opts: {
+    relayUrl: string;
+    programId: PublicKey;
+    mint: PublicKey;
+    noteSpendKey: Uint8Array;
+}): Promise<DepositOutcome>;
+
+/**
+ * Recover the receiving address's token-account rent, even when someone has dusted it.
+ *
+ * THE PROBLEM (found by testing, docs/11-E2E-PLAN.md Phase 4): the rail creates R's token account
+ * and pays its 2,039,280 rent. After the deposit that account is empty and closing it returns the
+ * rent TO THE USER. But SPL Token refuses to close a non-empty account, and dust below the
+ * program's 1,000,000-base-unit deposit minimum cannot be swept by re-depositing it — the program
+ * correctly rejects it with DepositTooSmall. So one base unit from anyone permanently strands
+ * about forty cents of somebody else's money, for free.
+ *
+ * THE FIX, in two parts. Dust that arrives BEFORE the deposit is not a problem at all: the deposit
+ * shields R's whole balance, so it goes into the pool with everything else. The griefing only bites
+ * when dust lands AFTER the deposit, and then the honest answer is to leave it.
+ *
+ * WHY LEAVE IT — this reverses an earlier decision, deliberately. Sweeping the dust to the user's
+ * own wallet publishes `R -> user` on a public ledger, and R has just deposited into the shielded
+ * pool. Anyone can join those two facts and learn that this user made that deposit. That is the
+ * precise inference the pool exists to prevent, and it is the same leak that funding R from the
+ * user's wallet used to cause at the other end of the flow — moved to the end, not removed. It is
+ * not worth about twenty-two cents of rent. Sweeping to Cloak instead is not an option either:
+ * capturing user funds off-chain is an off-chain fee, which the team rule forbids.
+ *
+ * So the default is privacy-first: close when empty, and when dusted, leave the account open and
+ * say so. `dustDestination` lets a caller sweep anyway, with the linkage stated in its doc comment.
+ * Burning stays out: dust can be up to 999,999 base units, and destroying a dollar to recover
+ * twenty-two cents is a worse outcome than the griefing it answers.
+ */
+
+interface CleanupResult {
+    closed: boolean;
+    dustSwept: bigint;
+    rentReturned: number;
+    destination: string | null;
+    signature: string | null;
+    note: string;
+}
+/**
+ * @param dustDestination where post-deposit dust goes, if the caller wants it swept at all.
+ *   LEAVE IT UNDEFINED unless the user has been told the cost: any destination they control
+ *   publishes `R -> them` and deanonymises the deposit R just made. It is never Cloak's, because
+ *   capturing user funds off-chain would be an off-chain fee, which the team rule forbids.
+ *   Undefined means "close if empty, otherwise leave it alone and report it".
+ * @param mint the shielded asset R was funded for. Defaults to mainnet USDC so a caller written
+ *   before this parameter existed keeps compiling and keeps recovering the same account it always
+ *   has; a bridge for any other asset MUST pass its own mint, since R's token account and the
+ *   dust sitting in it both belong to whatever mint the rail actually delivered, not to this
+ *   default.
+ */
+declare function cleanupReceivingAddress(conn: Connection, R: Keypair, dustDestination?: PublicKey, mint?: PublicKey): Promise<CleanupResult>;
+
+/**
+ * Local deposit funder for the bridge testbed.
+ *
+ * The bridge pays a derived address R that arrives with zero SOL, and the deposit takes its
+ * account rent from R (`transact_spl/mod.rs:92` passes `payer_info` into `create_nullifier_pdas`).
+ * But `create_pda_account_safe` (`utils/pda.rs:30-61`) ADOPTS an already-funded, System-owned,
+ * zero-data account and transfers only the shortfall — so the rent can be paid straight to the
+ * three PDAs in an earlier transaction, and R never touches it.
+ *
+ * That split is the whole point. Lamports parked at the nullifier and risk-nonce PDAs are
+ * unrecoverable by ANYONE (no instruction in the program closes them), so flooding this funder
+ * burns Cloak's SOL and earns an attacker nothing. Sending the same total to R instead would put
+ * all of it in an account the requester can sweep in one instruction.
+ *
+ * WHAT SURVIVED THE PORT: the rent constants, the funding-target derivation, and the live rent
+ * read. Everything that SUBMITTED a transaction stayed behind in the prototype — see the note at
+ * the bottom of this file. The production funder is the paymaster, and it runs on a server.
+ */
+
+/** Rent for a 0-byte System account. `utils/pda.rs:99` -> `minimum_balance(0)`. */
+declare const MAINNET_RENT_0 = 890880;
+/** Rent for a 1-byte account. `state/nullifier.rs:18` says `SIZE = 1`. */
+declare const MAINNET_RENT_1 = 897840;
+/**
+ * R must be able to pay its own transaction fee. The SDK hard-codes
+ * setComputeUnitPrice(100_000) over setComputeUnitLimit(1_200_000) with no caller lever
+ * (`sdk/src/flows/transact.ts:2598-2599`), so a deposit that fits costs 5,000 + 120,000.
+ * Funding R with the 20,000 an earlier draft assumed leaves it 105,000 short and every
+ * deposit fails under load.
+ */
+declare const FEE_BUDGET = 130000;
+/**
+ * A SECOND fee, for the cleanup transaction in which R closes its own token account and the
+ * rail-paid 2,039,280 goes back to the user.
+ *
+ * MEASURED 2026-09-05: without it the close is impossible. Solana checks the fee payer's
+ * rent-exemption after deducting the fee and BEFORE executing, so an R funded to exactly the
+ * floor fails with "insufficient funds for rent" — even though the very transaction being
+ * rejected would have credited it 2,039,280. Budgeting only the deposit's fee strands the
+ * largest recoverable line in the whole flow.
+ */
+declare const CLEANUP_FEE_BUDGET = 5000;
+interface DepositRef {
+    programId: PublicKey;
+    mint: PublicKey;
+    /** The two input nullifiers from the proof's public inputs. */
+    nullifiers: [Uint8Array, Uint8Array];
+    /** bind0 from the relay's signed risk quote; the risk-nonce PDA is derived from it. */
+    bind0: Uint8Array;
+    /** R — the derived receiving address that will sign the deposit. */
+    depositor: PublicKey;
+}
+/** Mirrors relay `derive_addresses` (supplemental_alt.rs) and the program's own derivations. */
+declare function deriveFundingTargets(d: DepositRef): {
+    pool: PublicKey;
+    nullifier0: PublicKey;
+    nullifier1: PublicKey;
+    riskNonce: PublicKey;
+    depositorAta: PublicKey;
+};
+interface RentRates {
+    zero: number;
+    one: number;
+}
+/** Read rent live. Never hard-code it: a local validator's rent sysvar is not authoritative. */
+declare function readRent(conn: Connection): Promise<RentRates>;
+interface FundingPlan {
+    transfers: {
+        to: PublicKey;
+        lamports: number;
+        why: string;
+    }[];
+    total: number;
+    alreadyFunded: string[];
+    rent: RentRates;
+    warnings: string[];
+}
+
+declare const ONECLICK_PUBKEY_B58 = "reYaWhvwu8Jzo3WUM3zhn6VrhuMEF4eADL17qtRVifc";
+/**
+ * The exact string this rail signs over, exported so a second implementation can be checked against
+ * it rather than reasoned about.
+ *
+ * A Rust twin of `stable()` has to reproduce JavaScript's key ordering and number formatting byte
+ * for byte, and the two languages do not agree by default: `Object.keys().sort()` orders by UTF-16
+ * code unit while Rust's `sort()` orders by UTF-8 byte. They coincide for ASCII and diverge above
+ * it. This is the same class of bug as `canonicalJson` versus Rust's `keys.sort_unstable()` in the
+ * relay-auth payload, and it fails in the worst direction: a verifier that rejects HONEST quotes
+ * looks like a rail outage, and teaches whoever is on call to ignore it.
+ *
+ * So the cross-language test compares THIS string, not just the boolean verdict. Two verifiers can
+ * agree on a signature by both being wrong in the same place; they cannot agree on the bytes by
+ * accident.
+ */
+declare function canonicalPayloadString(resp: any): string;
+declare function verifyQuoteSignature(resp: any): {
+    valid: boolean;
+    reason?: string;
+};
+
+/**
+ * Deciding whether a bridge deposit can be honoured — BEFORE the user sends anything.
+ *
+ * WHY THIS EXISTS. Shielding on arrival is mandatory, not a choice: a user who bridges and then
+ * sweeps unshielded has manufactured exactly the `receiver -> them` link the whole design removes.
+ * But "mandatory" moves every failure from the user's account to ours. If someone sends 3 USDC and
+ * the paymaster fee leaves less than the program's 1,000,000-base-unit floor, the shield CANNOT
+ * happen — and under a mandatory model that is the product breaking its own promise, with the money
+ * stranded unshielded at an address the user has never heard of.
+ *
+ * So the check belongs at quote time. The rule is the one the rail-signature check already
+ * established: NEVER SHOW AN ADDRESS YOU CANNOT HONOUR. An unviable deposit is refused before the
+ * deposit address is displayed, not diagnosed after the money has landed.
+ *
+ * All figures are worst-case, taken from the rail's guaranteed floor (`minAmountOut`), never its
+ * target. A quote that only works at the target is a quote that fails on a bad day.
+ */
+/** programs/shield-pool/src/constants.rs:126 — enforced at transact_spl/deposit.rs:69. */
+declare const MIN_DEPOSIT_SPL_BASE_UNITS = 1000000n;
+/**
+ * Live mainnet USDC PoolConfig at deploy time: a flat fee plus a proportional part, charged on
+ * WITHDRAWAL. These are the program's DEFAULTS, not a live read — quote.ts has no RPC client, so it
+ * cannot see a PoolConfig an admin has since changed. Treat this pair as a fallback only: it is
+ * shown to a user as what it will cost to get their money out, and if the live config has moved,
+ * this UNDERSTATES that cost. A caller that has already fetched PoolConfig should pass the real
+ * figures through `BridgeQuoteInput.liveWithdrawFixedFee` / `liveWithdrawFeeBps` instead.
+ */
+declare const WITHDRAW_FIXED_FEE = 450000n;
+declare const WITHDRAW_FEE_BPS = 30n;
+/**
+ * Below this, the fixed costs dominate: a deposit works, but most of it goes to fees.
+ *
+ * It is ADVISORY. `viable` is the hard gate; this only warns and asks for a second confirmation,
+ * because it is the user's money and their call.
+ *
+ * WAS 20 USDC, derived from a 1.21 round trip when the paymaster charged $0.458 for something that
+ * cost it $0.104. Fixed pricing took that to $0.150 on 2026-09-07 (docs/17-PAYMASTER-ECONOMICS.md),
+ * the round trip fell to ~0.90, and leaving the constant alone would have warned people off
+ * deposits that had become perfectly reasonable. If the paymaster fee moves again, recompute
+ * FIXED_ROUND_TRIP rather than editing this number.
+ *
+ *   0.903 / a + 0.003 = 0.063  ->  a = 15.05
+ */
+declare const ECONOMIC_MINIMUM: bigint;
+interface BridgeQuoteInput {
+    /** What the user sends on the origin chain, in the destination asset's base units. */
+    sent: bigint;
+    /** The rail's GUARANTEED floor. Assess against this, never `amountOut`. */
+    arrivesMin: bigint;
+    /** The rail's target, for display only. */
+    arrivesTarget: bigint;
+    /** What the paymaster will charge to fund the receiver, buffered, in the same units. */
+    paymasterFee: bigint;
+    /**
+     * Live PoolConfig withdraw-fee figures, when the caller has already fetched them on-chain.
+     * Optional: omitting either falls back to the compile-time WITHDRAW_FIXED_FEE / WITHDRAW_FEE_BPS
+     * constants above, which can be stale. quote.ts never fetches these itself — no RPC call belongs
+     * in a pure quote assessment — so the live figures can only arrive this way.
+     */
+    liveWithdrawFixedFee?: bigint;
+    liveWithdrawFeeBps?: bigint;
+}
+interface BridgeQuoteAssessment extends BridgeQuoteInput {
+    /** What actually lands shielded, worst case. This is the number to show the user. */
+    shieldedMin: bigint;
+    shieldedTarget: bigint;
+    /** False means REFUSE: the shield is impossible, so the deposit must not be offered. */
+    viable: boolean;
+    /** False means warn: it will work, but the fixed costs dominate. */
+    economic: boolean;
+    /** What it would cost to take it out again, so "shielded" is not mistaken for "free to exit". */
+    withdrawFee: bigint;
+    /** Origin-to-recipient loss if they shielded and immediately withdrew, worst case. */
+    roundTripCost: bigint;
+    roundTripFraction: number;
+    /** Human-readable, ordered most important first. Empty when everything is fine. */
+    reasons: string[];
+}
+declare function withdrawFeeFor(amount: bigint): bigint;
+declare function assessBridgeQuote(q: BridgeQuoteInput): BridgeQuoteAssessment;
+/** The quote screen, as the user must see it BEFORE any address is shown. */
+declare function renderAssessment(a: BridgeQuoteAssessment): string;
+
+/**
+ * Deciding whether a failed shield attempt may be retried.
+ *
+ * This is the most dangerous decision in the flow and the least observable, because it only runs
+ * when something has already gone wrong. Getting it wrong in either direction costs money:
+ *
+ *   retry when the deposit actually landed  -> a second proof and a second deposit fee, for a
+ *                                              deposit that already happened
+ *   refuse when it did not land             -> the user is told their funds are unshielded and has
+ *                                              to re-run, which costs a re-run and nothing else
+ *
+ * The asymmetry is the whole design: an unnecessary stop is cheap, a wrongful retry is not. So
+ * anything the evidence cannot explain resolves to "do not retry".
+ *
+ * It lives in the SDK rather than in a CLI script because the shield service will need exactly this
+ * decision, and a second implementation of it would be a second way to lose track of the same money.
+ * It is pure — no chain, no clock — so it can be tested exhaustively, which the CLI version never was.
+ */
+/**
+ * Failures where retrying only burns another proof: the deposit cannot succeed as constructed, so
+ * a second attempt fails identically and costs another fee to find out.
+ */
+declare const TERMINAL_FAILURE: RegExp;
+declare function isTerminalFailure(message: string): boolean;
+type PostFailureVerdict = 
+/** The receiver's tokens are gone: the deposit transaction landed despite the error. */
+"landed"
+/** The balance is untouched: the deposit demonstrably did not consume it. Safe to retry. */
+ | "did-not-land"
+/** The balance moved by an amount nothing here explains, or could not be read at all. */
+ | "unknown";
+/**
+ * What the receiver's token balance says about a deposit attempt that threw.
+ *
+ * The deposit transaction moves the receiver's ENTIRE `attempted` balance atomically with the rest
+ * of its instructions, so the balance is a reliable witness: drained to zero means it landed,
+ * unchanged means it did not. Anything else — a partial move, a fresh delivery mid-flight, an
+ * unreadable account — is not something this can interpret, and guessing is exactly the mistake
+ * this function exists to prevent.
+ *
+ * @param attempted what the receiver held when the attempt started
+ * @param after     what it holds now, or null if the balance could not be read
+ */
+declare function classifyPostFailure(attempted: bigint, after: bigint | null): PostFailureVerdict;
+/** Whether the loop may go again, given what the evidence says. */
+declare function mayRetry(verdict: PostFailureVerdict, message: string): boolean;
+/** Linear backoff. Deliberately not exponential: the failures seen here are relay and blockhash
+ *  timing, which clear in seconds, and a long tail just strands the user watching a terminal. */
+declare function retryDelayMs(attempt: number): number;
+/** Raised in place of the underlying error when the evidence says the deposit landed, or says
+ *  nothing this can interpret. The loop stops on it without claiming the funds are unshielded. */
+declare class DoNotRetry extends Error {
+    constructor(message: string);
+}
+interface RetryHooks {
+    /** Called before each wait, so a CLI can say what it is doing and a service can log it. */
+    onRetry?: (attempt: number, delayMs: number, lastError: string) => void;
+    /** Injectable so tests do not actually wait, and a service can use its own scheduler. */
+    sleep?: (ms: number) => Promise<void>;
+    attempts?: number;
+}
+/**
+ * Run `attempt` until it succeeds or the evidence says stop.
+ *
+ * The loop is separated from what it runs so it can be tested against injected failures. Its
+ * previous form lived inside a CLI script wired to mainnet constants, which meant the only way to
+ * exercise it was to cause a real failure during a real deposit — so it never was exercised, across
+ * two rounds of changes to it.
+ *
+ * `attempt` is expected to throw `DoNotRetry` when it has already checked chain state and found the
+ * deposit landed, or found something it cannot explain. Everything else is judged by
+ * `isTerminalFailure`.
+ */
+declare function withShieldRetries<T>(attempt: (attemptNo: number) => Promise<T>, hooks?: RetryHooks): Promise<T>;
+
 /**
  * Cloak SDK - TypeScript SDK for Private Transactions on Solana
  *
  * @packageDocumentation
  */
 
-declare const VERSION = "0.2.1";
+declare const VERSION = "0.2.3";
 /** True when scanner supports TransactSwap (tag 1). Check this to verify the correct SDK bundle is loaded. */
 declare const SCANNER_SUPPORTS_TRANSACT_SWAP = true;
 
-export { BUILD_ALLOWS_LOCAL_ENDPOINTS, type BuildRecipientDeliveryNotesParams, CHAIN_NOTE_SALT_BITS, CLOAK_PRODUCTION_RELAY_URL, CLOAK_PROGRAM_ID, type ChainNoteTxType, type CircuitVerificationResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, type CommitmentEntry, type CommitmentsResponse, type CompactChainNote, type ComplianceReport, type ComplianceTxType, type ConfirmSettlementParams, DEFAULT_CIRCUITS_URL, DEFAULT_TRANSACTION_CIRCUITS_URL, DELIVERY_MEMO_TAG, DELIVERY_REGISTRY_SEED, type DeliveredNote, type DepositInstructionParams, type DepositNoteSecrets, type DepositOptions, type DepositResult, type DepositStatus, type DiscoverSwapRefundsOptions, type DiscoveredSwapRefund, EXPECTED_CIRCUIT_HASHES, type EncryptedMetadataBundle, type EncryptedNote$1 as EncryptedNote, type ErrorCategory, type ExpandedSpendKey, type ExternalFeePayerAdapter, FIXED_FEE_LAMPORTS, type Groth16Proof, InsecureRandomnessError, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, MERKLE_TREE_HEIGHT, MIN_DEPOSIT_LAMPORTS, type MasterKey, type MatchChangeNoteParams, type MatchDepositNoteParams, type MatchSwapRefundLeafParams, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, MerkleTree, NATIVE_SOL_MINT, type Network, type NoteData, type OnchainMerkleProof, type ParsedDeliveryCarrier, type PendingDeposit, type PendingWithdrawal, RECIPIENT_DELIVERY_CIPHERTEXT_LEN, RECIPIENT_DELIVERY_EPHEMERAL_PK_LEN, RECIPIENT_DELIVERY_NONCE_LEN, RECIPIENT_DELIVERY_NOTE_BYTES, RECIPIENT_DELIVERY_PLAINTEXT_LEN, RECIPIENT_DELIVERY_TAG_LEN, RELAY_ORIGIN_ALLOWLIST, REQUEST_AUTH_MAX_AGE_SECONDS, REQUEST_AUTH_MAX_FUTURE_SKEW_SECONDS, type RecipientDeliveryNote, type RecoveredChangeNote, type RecoveredChangeNoteRecord, type RecoveredDepositNote, type RecoveredDepositNoteRecord, type RecoveredSwapRefund, type RelayAuthPreimage, type RelayAuthSigner, RelayInternalError, RelayService, type RelaySubmissionResult, type RiskQuoteInstructionResponse, RootNotFoundError, SCANNER_SUPPORTS_TRANSACT_SWAP, SIGN_IN_MESSAGE, SanctionsQuoteError, type ScanOptions, type ScanRecipientDeliveryOptions, type ScanResult, type ScanSummary, type ScannedTransaction, type SettlementConnection, type SettlementContext, type SettlementStatus, type SettlementVerdict, SettlementVerificationError, ShieldPoolErrors, type ShieldPoolPDAs, SimpleWallet, type SpendKey, type StorageAdapter, type SubmitTransactToRelayArgs, type SwapOptions, type SwapParams, type SwapRefundAuthorization, type SwapResult, TRANSACTION_CIRCUITS_VERSION, TRANSACT_AUTH_FIELDS, TRANSACT_SWAP_AUTH_FIELDS, type TransactOptions, type TransactParams, type TransactRequestBodyParams, type TransactResult, type TransactionMetadata, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, type Utxo, UtxoAlreadySpentError, type EncryptedNote as UtxoEncryptedNote, type UtxoKeypair, type UtxoSwapParams, type UtxoSwapResult, UtxoWallet, VARIABLE_FEE_DENOMINATOR, VARIABLE_FEE_NUMERATOR, VARIABLE_FEE_RATE, VERSION, type VerifyUtxosResult, type ViewKey, type ViewingKeyPair, type WalletAdapter, type WalletUtxo, type WithdrawOptions, type WithdrawSubmissionResult, assertDirectSubmissionLanded, assertTransactionCircuitIntegrity, bigintToBytes32$1 as bigintToBytes32, bigintToHex, buildMerkleTree, buildMerkleTreeFromChain, buildMerkleTreeFromRelay, buildRecipientDeliveryNotes, buildRelayAuthPreimage, buildTransactRequestBody, bytesToHex, calculateFee, calculateFeeBigint, calculateRelayFee, canRebuildMerkleTreeFromChain, canonicalJson, chainNoteFromBase64, chainNoteToBase64, classifyRelayError, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, computeChainNoteHash, computeExtDataHash, computeMerkleRoot, computeProofForLatestDeposit, computeProofFromChain, computeSignature, computeSwapRefundCommitment, computeCommitment as computeUtxoCommitment, computeNullifier as computeUtxoNullifier, confirmTransactSettlement, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, createRecoverableChangeUtxo, createRecoverableDepositUtxo, createUtxo, createZeroUtxo, decryptCompactChainNote, decryptComplianceMetadataWithMasterKey, decryptTransactionMetadata, deriveChangeNoteBlinding, deriveDepositNoteSecrets, deriveDiversifiedViewingKey, deriveDiversifier, deriveInputNullifierPdas, derivePublicKey, deriveSpendKey, deriveSwapRefundAuthorization, deriveUserCompliancePublicKey, deriveUserComplianceScalar, deriveUtxoKeypairFromSpendKey, deriveViewKey, deriveViewingKeyFromNk, deriveViewingKeyFromSpendKey, deriveViewingKeyFromUtxoPrivateKey, deserializeUtxo, detectNetworkFromRpcUrl, discoverSwapRefunds, downloadNote, encodeDeliveryCarrierMemo, encodeNoteSimple, encodeRecipientDeliveryNote, encryptCompactChainNote, encryptNoteForRecipient, encryptTransactionMetadata, encryptTransactionMetadataBundle, expandSpendKey, explainRelayAuthRejection, exportKeys, exportNote, exportWalletKeys, fetchCommitments, fetchRiskQuoteInstruction, fetchRiskQuoteIx, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatComplianceCsv, formatErrorForLogging, formatSol, fullWithdraw, generateCloakKeys, generateCommitmentAsync, generateMasterSeed, generateNoteFromWallet, generateUtxoKeypair, generateViewingKeyPair, getAddressExplorerUrl, getChainNoteRegistryPDA, getCircuitsPath, getDeliveryRegistryPDA, getDistributableAmount, getExplorerUrl, getNkFromUtxoPrivateKey, getNullifierPDA, getPendingOperationsSummary, getPoolAuthorityConfigPDA, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getSwapStatePDA, getViewKey, hasPendingOperations, hexToBigint$1 as hexToBigint, hexToBytes, importKeys, importWalletKeys, isBrowser, isBrowserLike, isDebugEnabled, isPlausibleSignature, isReactNative, isRootNotFoundError, isSubmissionOutcomeUnknownResponse, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawAmountSufficient, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, loadVerifiedCircuitArtifacts, matchChangeNote, matchDepositNote, matchSwapRefundLeaf, openRecipientDeliveryNote, parseAmount, parseDeliveryCarrierMemo, parseError, parseNote, parseRelayErrorResponse, parseRelayErrorSignature, parseTransactionError, partialWithdraw, poseidonHash, preflightCheck, preflightNullifiers, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToFieldElement, pubkeyToLimbs, randomBytes, randomChangeNoteSalt, randomDepositNoteSalt, randomFieldElement, readMerkleTreeState, recipientDeliveryNoteToBase64, registerViewingKey, removePendingDeposit, removePendingWithdrawal, resolveCircuitsBase, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, scanRecipientDeliveryNotes, scanTransactions, sdkLogger, selectUtxos, sendTransaction, serializeNote, serializeUtxo, setCircuitsPath, setDebugMode, signTransaction, splitTo2Limbs, submitTransactToRelay, sumUtxoAmounts, swapUtxo, swapWithChange, toComplianceReport, transact, transfer, truncate, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, bigintToBytes32 as utxoBigintToBytes32, utxoEquals, hexToBigint as utxoHexToBigint, validateDepositParams, validateNote, validateOutputsSum, validateRoot, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity, verifyUtxos, waitForRoot, withTiming };
+export { BRIDGE_ESCROW_LABEL, BUILD_ALLOWS_LOCAL_ENDPOINTS, type BridgeDeliveryState, type BridgeDeposit, type BridgeDepositState, type BridgeQuoteAssessment, type BridgeQuoteInput, type BridgeRail, type BridgeRailAttestation, type BridgeRailProblem, type BridgeRailQuoteOption, type BridgeRailQuoteRequest, type BridgeRailQuoteResponse, type BridgeRailStatusResult, type BuildRecipientDeliveryNotesParams, CHAIN_NOTE_SALT_BITS, CLEANUP_FEE_BUDGET, CLOAK_PRODUCTION_RELAY_URL, CLOAK_PROGRAM_ID, type ChainNoteTxType, type CircuitVerificationResult, type CleanupResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, type CommitmentEntry, type CommitmentsResponse, type CompactChainNote, type ComplianceReport, type ComplianceTxType, type ConfirmSettlementParams, DEFAULT_CIRCUITS_URL, DEFAULT_TRANSACTION_CIRCUITS_URL, DELIVERY_MEMO_TAG, DELIVERY_REGISTRY_SEED, type DeliveredNote, DepositError, type DepositInstructionParams, type DepositNoteSecrets, type DepositOptions, type DepositOutcome, type DepositRef, type DepositResult, type DepositStatus, type DiscoverOptions, type DiscoverSwapRefundsOptions, type DiscoveredSwapRefund, DoNotRetry, ECONOMIC_MINIMUM, EXPECTED_CIRCUIT_HASHES, type EncryptedMetadataBundle, type EncryptedNote$1 as EncryptedNote, type ErrorCategory, type ExpandedSpendKey, type ExternalFeePayerAdapter, FEE_BUDGET, FIXED_FEE_LAMPORTS, type FundingPlan, type Groth16Proof, InsecureRandomnessError, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, MAINNET_RENT_0, MAINNET_RENT_1, MAX_RECEIVER_INDEX, MERKLE_TREE_HEIGHT, MIN_DEPOSIT_LAMPORTS, MIN_DEPOSIT_SPL_BASE_UNITS, type MasterKey, type MatchChangeNoteParams, type MatchDepositNoteParams, type MatchSwapRefundLeafParams, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, MerkleTree, NATIVE_SOL_MINT, type Network, type NoteData, ONECLICK_PUBKEY_B58, type OnchainMerkleProof, type ParsedDeliveryCarrier, type PaymasterTopUpExpectation, type PaymasterTopUpResult, type PendingDeposit, type PendingWithdrawal, type PostFailureVerdict, RECIPIENT_DELIVERY_CIPHERTEXT_LEN, RECIPIENT_DELIVERY_EPHEMERAL_PK_LEN, RECIPIENT_DELIVERY_NONCE_LEN, RECIPIENT_DELIVERY_NOTE_BYTES, RECIPIENT_DELIVERY_PLAINTEXT_LEN, RECIPIENT_DELIVERY_TAG_LEN, RELAY_ORIGIN_ALLOWLIST, REQUEST_AUTH_MAX_AGE_SECONDS, REQUEST_AUTH_MAX_FUTURE_SKEW_SECONDS, type RecipientDeliveryNote, type RecoveredChangeNote, type RecoveredChangeNoteRecord, type RecoveredDepositNote, type RecoveredDepositNoteRecord, type RecoveredSwapRefund, type RelayAuthPreimage, type RelayAuthSigner, RelayInternalError, RelayService, type RelaySubmissionResult, type RentRates, type RetryHooks, type RiskQuoteInstructionResponse, RootNotFoundError, SCANNER_SUPPORTS_TRANSACT_SWAP, SIGN_IN_MESSAGE, SanctionsQuoteError, type ScanOptions, type ScanRecipientDeliveryOptions, type ScanResult, type ScanSummary, type ScannedTransaction, type SettlementConnection, type SettlementContext, type SettlementStatus, type SettlementVerdict, SettlementVerificationError, ShieldPoolErrors, type ShieldPoolPDAs, SimpleWallet, type SpendKey, type StorageAdapter, type SubmitTransactToRelayArgs, type SwapOptions, type SwapParams, type SwapRefundAuthorization, type SwapResult, TERMINAL_FAILURE, TRANSACTION_CIRCUITS_VERSION, TRANSACT_AUTH_FIELDS, TRANSACT_SWAP_AUTH_FIELDS, type TransactOptions, type TransactParams, type TransactRequestBodyParams, type TransactResult, type TransactionMetadata, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, type Utxo, UtxoAlreadySpentError, type EncryptedNote as UtxoEncryptedNote, type UtxoKeypair, type UtxoSwapParams, type UtxoSwapResult, UtxoWallet, VARIABLE_FEE_DENOMINATOR, VARIABLE_FEE_NUMERATOR, VARIABLE_FEE_RATE, VERSION, type VerifyUtxosResult, type ViewKey, type ViewingKeyPair, WITHDRAW_FEE_BPS, WITHDRAW_FIXED_FEE, type WalletAdapter, type WalletUtxo, type WithdrawOptions, type WithdrawSubmissionResult, assertDirectSubmissionLanded, assertInputMints, assertTransactionCircuitIntegrity, assessBridgeQuote, bigintToBytes32$1 as bigintToBytes32, bigintToHex, buildMerkleTree, buildMerkleTreeFromChain, buildMerkleTreeFromRelay, buildRecipientDeliveryNotes, buildRelayAuthPreimage, buildTransactRequestBody, bytesToHex, calculateFee, calculateFeeBigint, calculateRelayFee, canRebuildMerkleTreeFromChain, canonicalJson, canonicalPayloadString, chainNoteFromBase64, chainNoteToBase64, classifyPostFailure, classifyRelayError, cleanupReceivingAddress, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, cloakBridgeRail, computeChainNoteHash, computeExtDataHash, computeMerkleRoot, computeProofForLatestDeposit, computeProofFromChain, computeSignature, computeSwapRefundCommitment, computeCommitment as computeUtxoCommitment, computeNullifier as computeUtxoNullifier, confirmTransactSettlement, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, createRecoverableChangeUtxo, createRecoverableDepositUtxo, createUtxo, createZeroUtxo, decryptCompactChainNote, decryptComplianceMetadataWithMasterKey, decryptTransactionMetadata, depositFromDerivedKey, deriveBridgeReceiver, deriveChangeNoteBlinding, deriveDepositNoteSecrets, deriveDiversifiedViewingKey, deriveDiversifier, deriveFundingTargets, deriveInputNullifierPdas, derivePublicKey, deriveSpendKey, deriveSwapRefundAuthorization, deriveUserCompliancePublicKey, deriveUserComplianceScalar, deriveUtxoKeypairFromSpendKey, deriveViewKey, deriveViewingKeyFromNk, deriveViewingKeyFromSpendKey, deriveViewingKeyFromUtxoPrivateKey, deserializeUtxo, detectNetworkFromRpcUrl, discoverSwapRefunds, downloadNote, encodeDeliveryCarrierMemo, encodeNoteSimple, encodeRecipientDeliveryNote, encryptCompactChainNote, encryptNoteForRecipient, encryptTransactionMetadata, encryptTransactionMetadataBundle, expandSpendKey, explainRelayAuthRejection, exportKeys, exportNote, exportWalletKeys, fetchCommitments, fetchRiskQuoteInstruction, fetchRiskQuoteIx, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatComplianceCsv, formatErrorForLogging, formatSol, fullWithdraw, fundReceiverViaPaymaster, generateCloakKeys, generateCommitmentAsync, generateMasterSeed, generateNoteFromWallet, generateUtxoKeypair, generateViewingKeyPair, getAddressExplorerUrl, getChainNoteRegistryPDA, getCircuitsPath, getDeliveryRegistryPDA, getDistributableAmount, getExplorerUrl, getNkFromUtxoPrivateKey, getNullifierPDA, getPendingOperationsSummary, getPoolAuthorityConfigPDA, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getSwapStatePDA, getViewKey, hasPendingOperations, hexToBigint$1 as hexToBigint, hexToBytes, importKeys, importWalletKeys, isBrowser, isBrowserLike, isDebugEnabled, isPlausibleSignature, isReactNative, isRootNotFoundError, isSubmissionOutcomeUnknownResponse, isTerminalFailure, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawAmountSufficient, isWithdrawable, keypairToAdapter, listBridgeDeposits, loadPendingDeposits, loadPendingWithdrawals, loadVerifiedCircuitArtifacts, matchChangeNote, matchDepositNote, matchSwapRefundLeaf, mayRetry, openRecipientDeliveryNote, parseAmount, parseDeliveryCarrierMemo, parseError, parseNote, parseRelayErrorResponse, parseRelayErrorSignature, parseTransactionError, partialWithdraw, poseidonHash, preflightCheck, preflightNullifiers, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToFieldElement, pubkeyToLimbs, randomBytes, randomChangeNoteSalt, randomDepositNoteSalt, randomFieldElement, readMerkleTreeState, readRent, recipientDeliveryNoteToBase64, registerViewingKey, removePendingDeposit, removePendingWithdrawal, renderAssessment, resolveCircuitsBase, retryDelayMs, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, scanRecipientDeliveryNotes, scanTransactions, sdkLogger, selectUtxos, sendTransaction, serializeNote, serializeUtxo, setCircuitsPath, setDebugMode, signTransaction, splitTo2Limbs, submitTransactToRelay, sumUtxoAmounts, swapUtxo, swapWithChange, toComplianceReport, transact, transfer, truncate, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, bigintToBytes32 as utxoBigintToBytes32, utxoEquals, hexToBigint as utxoHexToBigint, validateDepositParams, validateNote, validateOutputsSum, validatePaymasterTopUpTransaction, validateRoot, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity, verifyQuoteSignature, verifyUtxos, waitForRoot, withShieldRetries, withTiming, withdrawFeeFor };