@cloak.dev/sdk 0.2.2 → 0.2.3-staging.005e3de

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PublicKey, Transaction, AddressLookupTableAccount, Connection, TransactionInstruction, Keypair, SendOptions, VersionedTransaction } from '@solana/web3.js';
+import { PublicKey, Transaction, Keypair, AddressLookupTableAccount, Connection, TransactionInstruction, SendOptions, VersionedTransaction } from '@solana/web3.js';
 
 /**
  * The deployed Cloak program.
@@ -781,6 +781,199 @@ declare class LocalStorageAdapter implements StorageAdapter {
     deleteKeys(): void;
 }
 
+/**
+ * How long the relay accepts a signed request after its `auth_issued_at`
+ * (`REQUEST_AUTH_MAX_AGE_SECONDS`, `api/request_auth.rs`).
+ *
+ * A FIRST-USE request past this window is rejected outright. The expiry exception the relay grants
+ * applies only to an exact replay of a request whose durable row already exists, which by
+ * definition never happens for a request that has not been accepted once.
+ */
+declare const REQUEST_AUTH_MAX_AGE_SECONDS = 300;
+/**
+ * How far ahead of the relay's clock a request may be stamped
+ * (`REQUEST_AUTH_MAX_FUTURE_SKEW_SECONDS`, `api/request_auth.rs`).
+ *
+ * `auth_issued_at` comes from `Date.now()`. On a server that is NTP-disciplined; in a browser it
+ * is the user's own machine clock, and a laptop more than 30 seconds fast cannot authenticate at
+ * all until its clock is corrected.
+ */
+declare const REQUEST_AUTH_MAX_FUTURE_SKEW_SECONDS = 30;
+/**
+ * The exact fields each endpoint signs. Both lists mirror the relay's `*_auth_request` builders and
+ * must stay in lockstep with them: adding a field on one side alone silently invalidates every
+ * signature, and the failure surfaces as a bare 401 with nothing pointing here.
+ */
+declare const TRANSACT_AUTH_FIELDS: readonly ["encrypted_notes", "max_fee", "mint", "proof_bytes", "public_inputs", "recipient", "recipient_delivery_notes", "risk_quote", "sender"];
+declare const TRANSACT_SWAP_AUTH_FIELDS: readonly ["close_timed_out", "dexes", "encrypted_notes", "exclude_dexes", "max_fee", "min_output_amount", "output_mint", "proof_bytes", "public_inputs", "recipient", "recipient_ata", "refund_blinding", "refund_pubkey", "retry_request_id", "risk_quote", "route_retry_attempts", "sender", "slippage_bps", "swap_max_retries"];
+/**
+ * Serialize exactly like the relay's `canonical_json`: keys sorted bytewise, no whitespace.
+ *
+ * SCOPE. This is the SDK's half of a byte-for-byte agreement with one specific Rust function over
+ * one specific schema: the values reachable through {@link TRANSACT_AUTH_FIELDS} and
+ * {@link TRANSACT_SWAP_AUTH_FIELDS}, which are ASCII keys over strings, small unsigned integers,
+ * booleans, nulls, arrays and plain objects. Inside that schema the two implementations agree.
+ *
+ * Outside it they need not, so anything that could serialize differently on the two sides is
+ * REFUSED here rather than signed into a digest that silently fails to match:
+ *
+ *  - Non-integer, non-finite and beyond-safe-integer numbers. `serde_json` renders an f64 as Rust
+ *    does (`1e21`) where JavaScript renders `1e+21`, and `0.1 + 0.2` has no single spelling. Every
+ *    number in both field lists is a small unsigned integer (`slippage_bps`, `route_retry_attempts`,
+ *    `swap_max_retries`); u64 amounts already travel as decimal STRINGS for exactly this reason.
+ *  - Functions and symbols as object VALUES. `JSON.stringify` drops such a key from the wire body
+ *    while it stays in the signed view, so the two digests can never agree.
+ *
+ * `undefined` is NOT refused: it serializes as `null` here, `JSON.stringify` omits the key on the
+ * wire, and every optional field on the relay side is `Option<T>` with `#[serde(default)]`, so the
+ * relay sees `null` too. That is the same agreement {@link buildAuthRequest} relies on. The one
+ * field where it does not hold is `slippage_bps`, which is why that field is checked by name.
+ *
+ * `bigint` is accepted and rendered as a bare decimal integer, matching serde's u64/i64 output.
+ * Note that such a value cannot also go on the wire: `JSON.stringify` throws on a bigint. Use a
+ * decimal string in the body, as every SDK-built body does.
+ */
+declare function canonicalJson(value: unknown): string;
+interface RelayAuthFields {
+    sender: string;
+    auth_issued_at: string;
+    auth_nonce: string;
+    auth_signature: string;
+    /**
+     * How `auth_signature` was produced. Absent means an off-chain message, today's wire. Set to
+     * `"transaction"` when the wallet signed the no-op transaction envelope instead
+     * (`signRelayAuthPayload`). Not part of the signed view, so it never enters the digest.
+     */
+    auth_mode?: RelayAuthMode;
+}
+/**
+ * Everything an authenticated request needs EXCEPT the signature: the three fields that go on the
+ * wire alongside it, plus the exact bytes to sign.
+ *
+ * This exists because the holder of the pen is not always a `Keypair`. A browser wallet adapter
+ * exposes `signMessage(bytes): Promise<Uint8Array>` and no secret key at all, so the scheme has to
+ * be reachable in two halves: build the preimage here, sign it wherever the key actually lives,
+ * then put `sender` / `auth_issued_at` / `auth_nonce` and the base64 signature on the body.
+ *
+ * `message` is a plain ed25519 detached-signature preimage — nothing about the scheme changes
+ * between a local keypair and a wallet, only who signs it.
+ */
+interface RelayAuthPreimage {
+    sender: string;
+    auth_issued_at: string;
+    auth_nonce: string;
+    message: Uint8Array;
+}
+/**
+ * Build the signed view and its preimage for one request, WITHOUT signing.
+ *
+ * `sender` is bound into the signed view and returned for the body — the relay rejects a request
+ * whose authenticated sender is not also present inside the signed payload. It must be the end
+ * user's own wallet: `sender` is the key screened for sanctions on a shield-to-shield send, so
+ * substituting an ephemeral or service key here moves the screening off the actual user.
+ *
+ * `nonce` and `issued_at` are generated here, once per call. Callers that re-POST a request must
+ * reuse the same preimage rather than rebuilding it, or the relay sees a brand-new request.
+ */
+declare function buildRelayAuthPreimage(endpoint: string, programId: PublicKey, body: Record<string, unknown>, sender: PublicKey, nowSeconds?: number, fields?: readonly string[]): RelayAuthPreimage;
+/**
+ * An async message signer standing in for a `Keypair`.
+ *
+ * A browser wallet adapter has no secret key to hand over — it exposes `signMessage`, and what
+ * this scheme needs signed is a plain ed25519 detached signature, which is exactly what that
+ * produces. Only the holder of the pen changes.
+ *
+ * COMPLIANCE — `walletPublicKey` becomes the request's authenticated `sender`, and `sender` is the
+ * key screened for sanctions on a shield-to-shield send. It MUST be the end user's own wallet.
+ * Putting an ephemeral, service-held or otherwise substituted key here moves the screening onto a
+ * key that is not the user: a compliance regression, not a shortcut.
+ */
+interface RelayMessageSigner {
+    /** The end user's real wallet. Becomes the authenticated `sender`. Never an ephemeral key. */
+    walletPublicKey: PublicKey;
+    /** Wallet-adapter `signMessage`; must return the 64-byte ed25519 detached signature. */
+    signMessage: (message: Uint8Array) => Promise<Uint8Array>;
+    signAuthTransaction?: undefined;
+}
+/**
+ * A wallet that cannot sign messages at all (Ledger, Trezor) but can sign a transaction. It signs
+ * the deterministic no-op transaction from `buildAuthTransactionMessage` instead; the relay rebuilds
+ * the same bytes and verifies against them. See `signRelayAuthPayload`.
+ */
+interface RelayTransactionSigner {
+    walletPublicKey: PublicKey;
+    /** Wallet-adapter `signTransaction`. Receives a legacy `Transaction` and returns it signed. */
+    signAuthTransaction: <T extends Transaction>(transaction: T) => Promise<T>;
+    signMessage?: undefined;
+}
+type RelayAuthSigner = RelayMessageSigner | RelayTransactionSigner;
+/** How a relay-auth payload was signed. Mirrors `RelayAuthMode` in the relay's `auth_envelope.rs`. */
+type RelayAuthMode = "message" | "transaction";
+/**
+ * The transaction a message-less wallet signs to authenticate a relay payload.
+ *
+ * Legacy message, one instruction: `sender -> sender`, 0 lamports, System program. The 32-byte
+ * `recent_blockhash` slot carries `sha256(payload)`, so the signature binds the payload exactly as
+ * a message signature would, through a shape every hardware wallet can sign. It cannot land on
+ * chain: the network does not know that "blockhash". It names no Cloak program, endpoint or domain,
+ * so it leaks nothing if published. Byte-identical to the relay's `build_auth_transaction_message`;
+ * the vector is pinned on both sides.
+ */
+declare function buildAuthTransactionMessage(sender: PublicKey, digest: Uint8Array): Transaction;
+/** The exact bytes the wallet signs for `buildAuthTransactionMessage(sender, digest)`. */
+declare function serializeAuthTransactionMessage(sender: PublicKey, digest: Uint8Array): Uint8Array;
+/**
+ * Sign a relay-auth payload with whatever the caller holds: a local `Keypair` or a message signer
+ * signs the payload bytes; a transaction-only signer signs the no-op transaction carrying the
+ * payload's digest. Returns the 64-byte detached signature and the mode the relay must be told.
+ */
+declare function signRelayAuthPayload(signer: RelayAuthSigner | Keypair, payload: Uint8Array): Promise<{
+    signature: Uint8Array;
+    mode: RelayAuthMode;
+}>;
+/**
+ * Turn a relay rejection into something the person in front of the screen can act on.
+ *
+ * Every string matched here is an `Error::Unauthorized` from `api/request_auth.rs`, and all of them
+ * arrive as the same bare 401. Two of them are not the caller's mistake at all: an approval that
+ * sat too long, and a machine clock that is simply wrong. Returns `null` for anything that is not
+ * an authentication rejection, so callers can append it only when there is something to add.
+ */
+declare function explainRelayAuthRejection(responseText: string): string | null;
+declare const REQUEST_AUTH_BATCH_DOMAIN = "CLOAK_RELAY_BATCH_AUTH_V1";
+/**
+ * How long the relay accepts an item that arrives under a batch signature
+ * (`REQUEST_AUTH_BATCH_MAX_AGE_SECONDS`, `api/request_auth.rs`).
+ *
+ * Longer than the single-request window because one approval now stands in front of N
+ * submissions, each confirmed on chain in turn. Every digest is a specific proof over specific
+ * nullifiers and every item still burns its own nonce, so the extra time widens nothing except how
+ * long the SAME already-approved requests stay submittable.
+ */
+declare const REQUEST_AUTH_BATCH_MAX_AGE_SECONDS = 600;
+/**
+ * Most items one batch signature may cover (`REQUEST_AUTH_BATCH_MAX_ITEMS`, `api/request_auth.rs`).
+ *
+ * The practical bound is lower and comes from the chain, not the relay: every spend appends two
+ * roots to the on-chain ring of 100, so N items proved against one root push that root out of the
+ * ring by themselves before N reaches 50, and sooner with other traffic. Size a batch as
+ * `(100 - expected foreign inserts while it submits) / 2`, and chunk above that.
+ */
+declare const RELAY_BATCH_AUTH_MAX_ITEMS = 64;
+/** The batch envelope an item carries next to its per-request auth fields. Not part of the digest. */
+interface RelayBatchAuthEnvelope {
+    /** Lowercase hex sha256 of every item's request-auth message, in the order the wallet signed. */
+    digests: string[];
+}
+/** Per-item wire fields under a batch signature: the single-request fields plus the envelope. */
+interface RelayBatchAuthFields extends RelayAuthFields {
+    auth_batch: RelayBatchAuthEnvelope;
+}
+/** The digest an item contributes to a batch: sha256 of its request-auth message bytes, hex. */
+declare function relayRequestDigestHex(preimage: RelayAuthPreimage): string;
+/** Build the batch message the wallet signs. Byte-identical to `build_batch_auth_message`. */
+declare function buildRelayBatchAuthMessage(programId: PublicKey, issuedAt: string, digests: readonly string[]): Uint8Array;
+
 interface ViewingKeyPair {
     privateKey: Uint8Array;
     publicKey: Uint8Array;
@@ -858,7 +1051,7 @@ declare const SIGN_IN_MESSAGE = "Cloak: Sign in\n\nSign this message to securely
  * Relay stores nk and derives sk_d per note when exporting.
  * Registration is authenticated via one-time nonce challenge.
  */
-declare function registerViewingKey(relayUrl: string, userPubkey: PublicKey, nk: Uint8Array, signMessage: (message: Uint8Array) => Promise<Uint8Array>): Promise<void>;
+declare function registerViewingKey(relayUrl: string, userPubkey: PublicKey, nk: Uint8Array, signMessage: ((message: Uint8Array) => Promise<Uint8Array>) | RelayAuthSigner): Promise<void>;
 
 interface EncryptMetadataContext {
     userPubkey?: PublicKey | string;
@@ -2081,7 +2274,7 @@ declare class RelayService {
      * );
      * ```
      */
-    registerViewingKey(userPubkey: string, viewingKey: string, signMessage: (message: Uint8Array) => Promise<Uint8Array>): Promise<boolean>;
+    registerViewingKey(userPubkey: string, viewingKey: string, signMessage: ((message: Uint8Array) => Promise<Uint8Array>) | RelayAuthSigner): Promise<boolean>;
     /**
      * Fetch relay compliance master public key.
      * DEPRECATED: This endpoint is no longer used
@@ -2634,115 +2827,119 @@ declare function isBrowser(): boolean;
 declare function isBrowserLike(): boolean;
 
 /**
- * How long the relay accepts a signed request after its `auth_issued_at`
- * (`REQUEST_AUTH_MAX_AGE_SECONDS`, `api/request_auth.rs`).
- *
- * A FIRST-USE request past this window is rejected outright. The expiry exception the relay grants
- * applies only to an exact replay of a request whose durable row already exists, which by
- * definition never happens for a request that has not been accepted once.
- */
-declare const REQUEST_AUTH_MAX_AGE_SECONDS = 300;
-/**
- * How far ahead of the relay's clock a request may be stamped
- * (`REQUEST_AUTH_MAX_FUTURE_SKEW_SECONDS`, `api/request_auth.rs`).
- *
- * `auth_issued_at` comes from `Date.now()`. On a server that is NTP-disciplined; in a browser it
- * is the user's own machine clock, and a laptop more than 30 seconds fast cannot authenticate at
- * all until its clock is corrected.
- */
-declare const REQUEST_AUTH_MAX_FUTURE_SKEW_SECONDS = 30;
-/**
- * The exact fields each endpoint signs. Both lists mirror the relay's `*_auth_request` builders and
- * must stay in lockstep with them: adding a field on one side alone silently invalidates every
- * signature, and the failure surfaces as a bare 401 with nothing pointing here.
+ * One wallet approval for a batch of relay requests (CLOAK_RELAY_BATCH_AUTH_V1).
+ *
+ * ── The problem ───────────────────────────────────────────────────────────────────────────────
+ * A payout to N recipients is N private spends, because the recipient is bound into each proof
+ * through `ext_data_hash`. Every spend is its own `/transact` request, and the relay authenticates
+ * every request with a wallet signature over that request's digest (`payload.ts`). So a payout of
+ * forty asked the wallet forty times. The transactions are not the problem: the relay builds and
+ * submits those and the user never signs them. The forty prompts were forty request signatures.
+ *
+ * ── The mechanism ─────────────────────────────────────────────────────────────────────────────
+ * Every item runs the ordinary `transact` flow unchanged, up to the moment it would sign its
+ * request. There it hands its finished body to the coordinator below and waits. When every item of
+ * the batch is either waiting here or already finished, the coordinator stamps one `issued_at`,
+ * builds each item's per-request preimage exactly as the single path would, takes the sha256 of
+ * each preimage, and asks the wallet ONCE to sign the list of those digests. Each item then gets
+ * back its own nonce and that one signature, plus the digest list the relay needs to verify it, and
+ * proceeds to POST as before. The relay checks that the item's digest is in the signed list and that
+ * the signature covers the list (`request_auth.rs`).
+ *
+ * ── What it deliberately keeps ────────────────────────────────────────────────────────────────
+ * - Every item still has its own one-time nonce, so an item cannot be submitted twice.
+ * - The user still signs every request they submit, as a list; nothing here can add a request the
+ *   wallet did not see without breaking the signature.
+ * - A stale-root retry re-proves, which changes the item's digest. That item comes back here and
+ *   is signed in a NEW wave with whichever other items also had to re-prove: one more approval for
+ *   the retries, never one per row. `approvals` counts the waves so a caller can show that.
+ * - Submissions after the signature are released `submitConcurrency` at a time, not all at once,
+ *   so the relay is not hit with N proofs in the same second while the signed window runs.
+ *
+ * Wave readiness is exact, not a timer: the coordinator knows how many items were registered and
+ * what each one is doing, so it signs the moment nothing in the batch is still building a proof.
+ *
+ * Every row must therefore be IN FLIGHT at once: a row that has not started counts as building, and
+ * the wave waits for it. Register every item (`item()`) BEFORE any row can fail, and always call
+ * `finish()`: a declared item that never registers, or never finishes, holds the wave forever, and
+ * `snapshot()` is how a caller sees that (`registered < expected`, or a row stuck in `building`). Do not run rows through a worker pool smaller than the batch (the pooled
+ * rows park at the signature, the pool never frees, and nothing ever signs). Bound the expensive
+ * part instead: `proofSlot()` limits how many rows prove at the same time.
  */
-declare const TRANSACT_AUTH_FIELDS: readonly ["encrypted_notes", "max_fee", "mint", "proof_bytes", "public_inputs", "recipient", "recipient_delivery_notes", "risk_quote", "sender"];
-declare const TRANSACT_SWAP_AUTH_FIELDS: readonly ["close_timed_out", "dexes", "encrypted_notes", "exclude_dexes", "max_fee", "min_output_amount", "output_mint", "proof_bytes", "public_inputs", "recipient", "recipient_ata", "refund_blinding", "refund_pubkey", "retry_request_id", "risk_quote", "route_retry_attempts", "sender", "slippage_bps", "swap_max_retries"];
-/**
- * Serialize exactly like the relay's `canonical_json`: keys sorted bytewise, no whitespace.
- *
- * SCOPE. This is the SDK's half of a byte-for-byte agreement with one specific Rust function over
- * one specific schema: the values reachable through {@link TRANSACT_AUTH_FIELDS} and
- * {@link TRANSACT_SWAP_AUTH_FIELDS}, which are ASCII keys over strings, small unsigned integers,
- * booleans, nulls, arrays and plain objects. Inside that schema the two implementations agree.
- *
- * Outside it they need not, so anything that could serialize differently on the two sides is
- * REFUSED here rather than signed into a digest that silently fails to match:
- *
- *  - Non-integer, non-finite and beyond-safe-integer numbers. `serde_json` renders an f64 as Rust
- *    does (`1e21`) where JavaScript renders `1e+21`, and `0.1 + 0.2` has no single spelling. Every
- *    number in both field lists is a small unsigned integer (`slippage_bps`, `route_retry_attempts`,
- *    `swap_max_retries`); u64 amounts already travel as decimal STRINGS for exactly this reason.
- *  - Functions and symbols as object VALUES. `JSON.stringify` drops such a key from the wire body
- *    while it stays in the signed view, so the two digests can never agree.
- *
- * `undefined` is NOT refused: it serializes as `null` here, `JSON.stringify` omits the key on the
- * wire, and every optional field on the relay side is `Option<T>` with `#[serde(default)]`, so the
- * relay sees `null` too. That is the same agreement {@link buildAuthRequest} relies on. The one
- * field where it does not hold is `slippage_bps`, which is why that field is checked by name.
- *
- * `bigint` is accepted and rendered as a bare decimal integer, matching serde's u64/i64 output.
- * Note that such a value cannot also go on the wire: `JSON.stringify` throws on a bigint. Use a
- * decimal string in the body, as every SDK-built body does.
- */
-declare function canonicalJson(value: unknown): string;
+
 /**
- * Everything an authenticated request needs EXCEPT the signature: the three fields that go on the
- * wire alongside it, plus the exact bytes to sign.
- *
- * This exists because the holder of the pen is not always a `Keypair`. A browser wallet adapter
- * exposes `signMessage(bytes): Promise<Uint8Array>` and no secret key at all, so the scheme has to
- * be reachable in two halves: build the preimage here, sign it wherever the key actually lives,
- * then put `sender` / `auth_issued_at` / `auth_nonce` and the base64 signature on the body.
- *
- * `message` is a plain ed25519 detached-signature preimage — nothing about the scheme changes
- * between a local keypair and a wallet, only who signs it.
+ * What one item of the batch holds. `submitTransactToRelay` calls `authorize` where it would
+ * otherwise sign; the caller that ran the item calls `finish` when the item's flow has settled,
+ * successfully or not, so the coordinator never waits on an item that is not coming.
  */
-interface RelayAuthPreimage {
-    sender: string;
-    auth_issued_at: string;
-    auth_nonce: string;
-    message: Uint8Array;
+interface RelayBatchAuthItemHandle {
+    /**
+     * Wait for a proof slot. Every row of a batch is in flight at once, because all proofs must exist
+     * before the one signature; this is where CPU and memory are bounded instead. Returns the release.
+     */
+    proofSlot(): Promise<() => void>;
+    authorize(endpoint: string, programId: PublicKey, body: Record<string, unknown>, fields: readonly string[]): Promise<RelayBatchAuthFields>;
+    finish(): void;
 }
-/**
- * Build the signed view and its preimage for one request, WITHOUT signing.
- *
- * `sender` is bound into the signed view and returned for the body — the relay rejects a request
- * whose authenticated sender is not also present inside the signed payload. It must be the end
- * user's own wallet: `sender` is the key screened for sanctions on a shield-to-shield send, so
- * substituting an ephemeral or service key here moves the screening off the actual user.
- *
- * `nonce` and `issued_at` are generated here, once per call. Callers that re-POST a request must
- * reuse the same preimage rather than rebuilding it, or the relay sees a brand-new request.
- */
-declare function buildRelayAuthPreimage(endpoint: string, programId: PublicKey, body: Record<string, unknown>, sender: PublicKey, nowSeconds?: number, fields?: readonly string[]): RelayAuthPreimage;
-/**
- * An async message signer standing in for a `Keypair`.
- *
- * A browser wallet adapter has no secret key to hand over — it exposes `signMessage`, and what
- * this scheme needs signed is a plain ed25519 detached signature, which is exactly what that
- * produces. Only the holder of the pen changes.
- *
- * COMPLIANCE — `walletPublicKey` becomes the request's authenticated `sender`, and `sender` is the
- * key screened for sanctions on a shield-to-shield send. It MUST be the end user's own wallet.
- * Putting an ephemeral, service-held or otherwise substituted key here moves the screening onto a
- * key that is not the user: a compliance regression, not a shortcut.
- */
-interface RelayAuthSigner {
-    /** The end user's real wallet. Becomes the authenticated `sender`. Never an ephemeral key. */
-    walletPublicKey: PublicKey;
-    /** Wallet-adapter `signMessage`; must return the 64-byte ed25519 detached signature. */
-    signMessage: (message: Uint8Array) => Promise<Uint8Array>;
+interface RelayBatchAuthCoordinatorOptions {
+    /**
+     * Who signs. A `Keypair` signs locally (tests, scripts, server-side callers); a wallet adapter
+     * signs through `signMessage` and its `walletPublicKey` becomes every item's authenticated
+     * `sender`. COMPLIANCE: that key is the one screened for sanctions on a shield-to-shield send,
+     * so it must be the end user's own wallet, never a service or ephemeral key.
+     */
+    signer: RelayAuthSigner | Keypair;
+    /** How many items will call `item()`. The wave signs only when all of them are accounted for. */
+    items: number;
+    /** Rows proving at the same time. Proofs are CPU-bound; default 2. */
+    proofConcurrency?: number;
+    /** Items released to submit at once after a signature. Default 3. */
+    submitConcurrency?: number;
+    onProgress?: (status: string) => void;
 }
-/**
- * Turn a relay rejection into something the person in front of the screen can act on.
- *
- * Every string matched here is an `Error::Unauthorized` from `api/request_auth.rs`, and all of them
- * arrive as the same bare 401. Two of them are not the caller's mistake at all: an approval that
- * sat too long, and a machine clock that is simply wrong. Returns `null` for anything that is not
- * an authentication rejection, so callers can append it only when there is something to add.
- */
-declare function explainRelayAuthRejection(responseText: string): string | null;
+declare class RelayBatchAuthCoordinator {
+    private readonly signer;
+    private readonly sender;
+    private readonly expectedItems;
+    private readonly submitConcurrency;
+    private readonly proofConcurrency;
+    private proofSlotsInUse;
+    private readonly proofQueue;
+    private readonly onProgress?;
+    private readonly items;
+    private signing;
+    private slotsInUse;
+    private readonly ready;
+    private waves;
+    constructor(options: RelayBatchAuthCoordinatorOptions);
+    /** The wallet that signs and is every item's authenticated `sender`. */
+    get walletPublicKey(): PublicKey;
+    /** How many times the signer has been asked so far: one per wave. */
+    get approvals(): number;
+    /** Where every item is right now. For progress UIs and for diagnosing a batch that never signs. */
+    snapshot(): {
+        building: number;
+        waiting: number;
+        submitting: number;
+        done: number;
+        proving: number;
+        proofQueue: number;
+        registered: number;
+        expected: number;
+    };
+    /** Register one item. Throws past `items`: the wave condition would never be reachable. */
+    item(): RelayBatchAuthItemHandle;
+    private acquireProofSlot;
+    private authorize;
+    private finish;
+    private releaseSlot;
+    /** Sign when every registered item is either waiting here or finished, and nothing is building. */
+    private maybeSign;
+    private signWave;
+    /** Release signed items to submit, `submitConcurrency` at a time, in signing order. */
+    private pump;
+}
+declare function createRelayBatchAuthCoordinator(options: RelayBatchAuthCoordinatorOptions): RelayBatchAuthCoordinator;
 
 /**
  * The circuit artifacts this SDK build proves against.
@@ -2931,6 +3128,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
  */
@@ -2973,6 +3191,14 @@ interface TransactOptions {
     signTransaction?: <T extends Transaction | VersionedTransaction>(transaction: T) => Promise<T>;
     /** Wallet adapter signMessage for viewing-key registration auth. */
     signMessage?: (message: Uint8Array) => Promise<Uint8Array>;
+    /**
+     * Relay authentication for a wallet that cannot sign messages at all (Ledger, Trezor): the
+     * wallet-adapter `signTransaction`, used to sign a deterministic no-op transaction that carries
+     * the request digest in its blockhash slot instead of signing the text (`relay/payload.ts`,
+     * `buildAuthTransactionMessage`). Also used for viewing-key registration. Requires
+     * `walletPublicKey` (or `depositorPublicKey`). `signMessage` wins when both are present.
+     */
+    signAuthTransaction?: <T extends Transaction>(transaction: T) => Promise<T>;
     /** Public key of the depositor when using signTransaction */
     depositorPublicKey?: PublicKey;
     /** Wallet public key for relay submissions when depositor keypair isn't used. */
@@ -3184,6 +3410,38 @@ 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;
+    /**
+     * One item of a batch approval, from `createRelayBatchAuthCoordinator().item()`. When present the
+     * relay request is authenticated with the batch's single wallet signature instead of a prompt of
+     * its own; `transactBatch` sets it for every item it runs. Ignored on the deposit path, which the
+     * relay does not authenticate this way.
+     */
+    relayAuthBatch?: RelayBatchAuthItemHandle;
 }
 /**
  * Switchboard-style response: a pre-built instruction.
@@ -3288,6 +3546,13 @@ interface SubmitTransactToRelayArgs {
      * or server-side key here is a compliance regression, not a shortcut.
      */
     relayAuthSigner?: RelayAuthSigner;
+    /**
+     * Batch alternative to both signers above: the request is authenticated by the batch's one
+     * wallet signature (CLOAK_RELAY_BATCH_AUTH_V1) instead of signing here. Takes precedence over
+     * `depositorKeypair` and `relayAuthSigner` when present, because the coordinator already holds
+     * whichever of those the batch was created with.
+     */
+    relayAuthBatch?: RelayBatchAuthItemHandle;
     settlement: SettlementContext;
     /** True while the caller still has a re-prove budget for a stale root. */
     canRetryStaleRoot: boolean;
@@ -3738,6 +4003,32 @@ declare function cleanupStalePendingOperations(maxAgeMs?: number): {
     removedWithdrawals: number;
 };
 
+interface TransactBatchItem {
+    params: TransactParams;
+    /** Per-item overrides (recipient viewing key, chain-note salt, expected mint, ...). */
+    options?: Partial<TransactOptions>;
+}
+interface TransactBatchOptions extends Omit<TransactOptions, "relayAuthBatch"> {
+    /** Items proved at the same time. Proofs are CPU-bound; default 2. */
+    proofConcurrency?: number;
+    /** Items released to the relay at the same time after the signature. Default 3. */
+    submitConcurrency?: number;
+}
+type TransactBatchItemOutcome = {
+    status: "fulfilled";
+    value: TransactResult;
+} | {
+    status: "rejected";
+    reason: unknown;
+};
+interface TransactBatchResult {
+    /** One entry per item, in input order. A rejected item did not settle; the others are unaffected. */
+    results: TransactBatchItemOutcome[];
+    /** Wallet approvals raised: 1 for the batch, plus 1 per wave of stale-root re-proves. */
+    approvals: number;
+}
+declare function transactBatch(items: readonly TransactBatchItem[], options: TransactBatchOptions): Promise<TransactBatchResult>;
+
 /**
  * Recipient-addressed delivery envelope (CLKD1).
  *
@@ -4668,14 +4959,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_BATCH_AUTH_MAX_ITEMS, RELAY_ORIGIN_ALLOWLIST, REQUEST_AUTH_BATCH_DOMAIN, REQUEST_AUTH_BATCH_MAX_AGE_SECONDS, REQUEST_AUTH_MAX_AGE_SECONDS, REQUEST_AUTH_MAX_FUTURE_SKEW_SECONDS, type RecipientDeliveryNote, type RecoveredChangeNote, type RecoveredChangeNoteRecord, type RecoveredDepositNote, type RecoveredDepositNoteRecord, type RecoveredSwapRefund, type RelayAuthMode, type RelayAuthPreimage, type RelayAuthSigner, RelayBatchAuthCoordinator, type RelayBatchAuthCoordinatorOptions, type RelayBatchAuthEnvelope, type RelayBatchAuthFields, type RelayBatchAuthItemHandle, RelayInternalError, type RelayMessageSigner, RelayService, type RelaySubmissionResult, type RelayTransactionSigner, 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 TransactBatchItem, type TransactBatchItemOutcome, type TransactBatchOptions, type TransactBatchResult, 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, buildAuthTransactionMessage, buildMerkleTree, buildMerkleTreeFromChain, buildMerkleTreeFromRelay, buildRecipientDeliveryNotes, buildRelayAuthPreimage, buildRelayBatchAuthMessage, 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, createRelayBatchAuthCoordinator, 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, relayRequestDigestHex, removePendingDeposit, removePendingWithdrawal, renderAssessment, resolveCircuitsBase, retryDelayMs, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, scanRecipientDeliveryNotes, scanTransactions, sdkLogger, selectUtxos, sendTransaction, serializeAuthTransactionMessage, serializeNote, serializeUtxo, setCircuitsPath, setDebugMode, signRelayAuthPayload, signTransaction, splitTo2Limbs, submitTransactToRelay, sumUtxoAmounts, swapUtxo, swapWithChange, toComplianceReport, transact, transactBatch, 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 };