@chipi-stack/core 0.4.1 → 0.6.0

package/dist/index.d.cts

@@ -0,0 +1,1544 @@
+import { Account, Call, InvokeFunctionResponse, EstimateFeeResponseOverhead, Signer, Signature, ProviderOptions, ProviderInterface, CairoVersion, TypedData, CairoCustomEnum, RpcProvider } from 'starknet';
+import { PaymasterAdapter, X402ClientConfig, PaymentRequirement, PaymentPayload } from '@chipi-stack/types';
+import { ProvingServiceProofProvider } from 'starknet-sdk';
+
+/** Minimal token info needed by Amount. */
+interface TokenInfo {
+    symbol: string;
+    decimals: number;
+    address: string;
+}
+/**
+ * Immutable representation of a token amount.
+ * Stores raw base units (e.g., wei for ETH, micro-units for USDC).
+ * All arithmetic is exact BigInt math — no floating point.
+ */
+declare class Amount {
+    /** Raw value in base units (smallest denomination). */
+    readonly raw: bigint;
+    /** Number of decimal places for this token. */
+    readonly decimals: number;
+    /** Token symbol (e.g., "USDC", "ETH"). */
+    readonly symbol: string;
+    private constructor();
+    private static assertValidDecimals;
+    /**
+     * Parse a human-readable string into an Amount.
+     * @param value - Human-readable value (e.g., "1.5")
+     * @param token - Token info with decimals and symbol
+     * @throws If value is negative, non-numeric, or has too many decimal places
+     */
+    static parse(value: string, token: TokenInfo): Amount;
+    /**
+     * Create an Amount from a raw bigint value (base units).
+     * @param raw - Raw value in base units
+     * @param decimals - Token decimal places
+     * @param symbol - Token symbol (defaults to "")
+     */
+    static fromRaw(raw: bigint, decimals: number, symbol?: string): Amount;
+    /** Add two amounts. Both must have the same decimals. */
+    add(other: Amount): Amount;
+    /**
+     * Subtract an amount.
+     * @throws If result would be negative
+     */
+    subtract(other: Amount): Amount;
+    /**
+     * Multiply by a scalar bigint.
+     * @throws If scalar is negative
+     */
+    multiply(scalar: bigint): Amount;
+    /**
+     * Divide by a scalar bigint. Truncates (no rounding).
+     * @throws If divisor is zero or negative
+     */
+    divide(divisor: bigint): Amount;
+    eq(other: Amount): boolean;
+    gt(other: Amount): boolean;
+    gte(other: Amount): boolean;
+    lt(other: Amount): boolean;
+    lte(other: Amount): boolean;
+    isZero(): boolean;
+    /** Returns the raw bigint value (base units). */
+    toBase(): bigint;
+    /**
+     * Returns human-readable string (e.g., "1.5").
+     * Trailing zeros after decimal are preserved to one place minimum.
+     */
+    toUnit(): string;
+    /**
+     * Returns formatted string with symbol (e.g., "1.5 USDC").
+     * @param compressed - If true, shorten large numbers (e.g., "1.5M USDC")
+     */
+    toFormatted(compressed?: boolean): string;
+    private assertSameDecimals;
+}
+
+/**
+ * Typed ERC20 contract wrapper.
+ * Generates Call objects for approve/transfer and queries for balance/allowance.
+ *
+ * @example
+ * const usdc = new Erc20({ symbol: 'USDC', decimals: 6, address: '0x...' }, account);
+ * const balance = await usdc.balanceOf(myAddress);
+ * console.log(balance.toFormatted()); // "150.5 USDC"
+ */
+declare class Erc20 {
+    private readonly token;
+    private readonly account;
+    constructor(token: TokenInfo, account: Account);
+    /**
+     * Query the balance of an address.
+     * @returns Amount representing the balance
+     */
+    balanceOf(address: string): Promise<Amount>;
+    /**
+     * Query the allowance of owner for spender.
+     * @returns Amount representing the allowance
+     */
+    allowance(owner: string, spender: string): Promise<Amount>;
+    /**
+     * Build an approve Call (does not execute).
+     * @returns Call object for use with TxBuilder or Account.execute()
+     */
+    approveCall(spender: string, amount: Amount): Call;
+    /**
+     * Build a transfer Call (does not execute).
+     * @returns Call object for use with TxBuilder or Account.execute()
+     */
+    transferCall(recipient: string, amount: Amount): Call;
+    private assertCompatibleAmount;
+}
+
+type Network = "mainnet" | "sepolia";
+interface TokenEntry extends TokenInfo {
+    name: string;
+}
+/**
+ * Registry for looking up token metadata by symbol or address.
+ *
+ * @example
+ * const registry = new TokenRegistry('mainnet');
+ * const usdc = registry.bySymbol('USDC');
+ * const amount = Amount.parse('10.0', usdc!);
+ */
+declare class TokenRegistry {
+    private readonly tokens;
+    private readonly bySymbolMap;
+    private readonly byAddressMap;
+    constructor(network: Network);
+    /** Find a token by its symbol (case-insensitive). */
+    bySymbol(symbol: string): TokenEntry | undefined;
+    /** Find a token by its contract address (case-insensitive). */
+    byAddress(address: string): TokenEntry | undefined;
+    /** List all tokens in this registry. */
+    all(): TokenEntry[];
+}
+
+interface TransferTarget {
+    to: string;
+    amount: bigint;
+}
+interface PreflightResult$1 {
+    transaction_trace: unknown;
+    fee_estimation: {
+        overall_fee: bigint;
+    };
+}
+
+/**
+ * Fluent builder for batching Starknet calls.
+ * All calls execute atomically via Account.execute().
+ *
+ * @example
+ * const result = await new TxBuilder(account)
+ *   .approve(tokenAddr, spenderAddr, amount)
+ *   .transfer(tokenAddr, [{ to: recipient, amount: 1000n }])
+ *   .send();
+ */
+interface TxBuilderOptions {
+    /** PaymasterAdapter for gasless transactions via sendSponsored(). */
+    paymaster?: PaymasterAdapter;
+}
+declare class TxBuilder {
+    private readonly account;
+    private readonly paymaster?;
+    private readonly _calls;
+    private sent;
+    constructor(account: Account, opts?: TxBuilderOptions);
+    /** Returns a copy of the current call batch. */
+    calls(): Call[];
+    /**
+     * Add one or more raw calls.
+     * @param call - A single Call or array of Calls
+     */
+    add(call: Call | Call[]): this;
+    /**
+     * Add an ERC20 approve call.
+     * @param token - Token contract address
+     * @param spender - Address to approve
+     * @param amount - Raw amount in base units
+     */
+    approve(token: string, spender: string, amount: bigint): this;
+    /**
+     * Add one or more ERC20 transfer calls.
+     * @param token - Token contract address
+     * @param targets - Array of { to, amount } pairs
+     */
+    transfer(token: string, targets: TransferTarget[]): this;
+    /**
+     * Execute all batched calls atomically.
+     * @throws If no calls have been added
+     * @throws If send() was already called
+     */
+    send(): Promise<InvokeFunctionResponse>;
+    /**
+     * Execute via a paymaster (gasless). Requires a PaymasterAdapter.
+     *
+     * The paymaster handles: prepare typed data -> sign -> submit.
+     * For external wallets (Argent X, Braavos), signing triggers the wallet popup.
+     *
+     * @returns Transaction hash
+     * @throws If no paymaster was configured
+     * @throws If no calls have been added
+     * @throws If sendSponsored() or send() was already called
+     */
+    sendSponsored(): Promise<string>;
+    /**
+     * Estimate fees for the current batch without executing.
+     * @throws If no calls have been added
+     */
+    estimateFee(): Promise<EstimateFeeResponseOverhead>;
+    /**
+     * Simulate the transaction without submitting to the network.
+     * Useful for checking if a transaction would succeed.
+     * @throws If no calls have been added
+     */
+    preflight(): Promise<PreflightResult$1>;
+}
+
+/** Result of a signing operation. */
+interface SignResult {
+    r: string;
+    s: string;
+}
+/**
+ * Unified signer interface.
+ * Implementations wrap different key management strategies
+ * (local key, passkey, external provider).
+ */
+interface SignerAdapter {
+    /** Get the public key associated with this signer. */
+    getPublicKey(): Promise<string>;
+    /** Sign a message hash. */
+    sign(messageHash: string): Promise<SignResult>;
+    /** Get the account address derived from this signer. */
+    getAccountAddress(): Promise<string>;
+}
+
+/**
+ * Signer backed by a local private key.
+ * Equivalent to StarkZap's StarkSigner.
+ *
+ * WARNING: Only for development/testing.
+ * Never hardcode private keys in production.
+ */
+declare class DirectSigner implements SignerAdapter {
+    private readonly privateKey;
+    private readonly publicKey;
+    private readonly accountAddress;
+    constructor(privateKey: string, accountAddress?: string);
+    getPublicKey(): Promise<string>;
+    sign(messageHash: string): Promise<SignResult>;
+    getAccountAddress(): Promise<string>;
+}
+
+/**
+ * Signer that wraps @chipi-stack/passkey functions.
+ * Does NOT modify @chipi-stack/passkey — only wraps it.
+ *
+ * @param authenticateFn - The authenticatePasskey function from @chipi-stack/passkey
+ * @param publicKey - The passkey public key (obtained during registration)
+ */
+declare class PasskeySigner implements SignerAdapter {
+    private readonly authenticateFn;
+    private readonly pubKey;
+    private readonly accountAddress;
+    constructor(opts: {
+        authenticateFn: (challenge: string) => Promise<{
+            r: string;
+            s: string;
+        }>;
+        publicKey: string;
+        accountAddress: string;
+    });
+    getPublicKey(): Promise<string>;
+    sign(messageHash: string): Promise<SignResult>;
+    getAccountAddress(): Promise<string>;
+}
+
+/**
+ * Adapter for external signer providers (Privy, Cartridge, etc.).
+ * Consumers provide the signing function — ExternalSigner just wraps the interface.
+ */
+declare class ExternalSigner implements SignerAdapter {
+    private readonly opts;
+    constructor(opts: {
+        getPublicKey: () => Promise<string>;
+        sign: (messageHash: string) => Promise<SignResult>;
+        getAccountAddress: () => Promise<string>;
+    });
+    getPublicKey(): Promise<string>;
+    sign(messageHash: string): Promise<SignResult>;
+    getAccountAddress(): Promise<string>;
+}
+
+/**
+ * Bridge between SignerAdapter and starknet.js Signer.
+ *
+ * Extends starknet.js `Signer`, overriding `signRaw()` to delegate to
+ * `SignerAdapter.sign()`. All hash computation is handled by starknet.js.
+ *
+ * This allows any SignerAdapter (DirectSigner, PasskeySigner, ExternalSigner)
+ * to be used where starknet.js expects a Signer instance (e.g., Account constructor).
+ */
+declare class StarknetSignerAdapter extends Signer {
+    private readonly adapter;
+    constructor(adapter: SignerAdapter);
+    getPubKey(): Promise<string>;
+    protected signRaw(msgHash: string): Promise<Signature>;
+}
+
+interface CreateAccountOptions {
+    /** Any SignerAdapter implementation (DirectSigner, PasskeySigner, ExternalSigner). */
+    signer: SignerAdapter;
+    /** Starknet provider or provider options. */
+    provider: ProviderOptions | ProviderInterface;
+    /** Override the account address (defaults to signer.getAccountAddress()). */
+    address?: string;
+    /** Cairo version for the account contract. */
+    cairoVersion?: CairoVersion;
+}
+/**
+ * Create a starknet.js Account from any SignerAdapter.
+ *
+ * Bridges the gap between SignerAdapter and starknet.js Account,
+ * so you can use the Account with TxBuilder or any starknet.js API.
+ */
+declare function createAccount(opts: CreateAccountOptions): Promise<Account>;
+
+interface FeeEstimate {
+    overall_fee: bigint;
+    gas_consumed: bigint;
+    gas_price: bigint;
+    data_gas_consumed?: bigint;
+    data_gas_price?: bigint;
+}
+interface PreflightResult {
+    transaction_trace: unknown;
+    fee_estimation: {
+        overall_fee: bigint;
+    };
+}
+
+/**
+ * Estimate invocation fees for a set of calls.
+ * Does NOT execute the transaction.
+ *
+ * @param calls - Array of Starknet calls to estimate
+ * @param account - Starknet Account instance
+ * @throws If calls array is empty
+ */
+declare function estimateFee(calls: Call[], account: Account): Promise<FeeEstimate>;
+/**
+ * Simulate a transaction without submitting it.
+ * Returns trace and fee estimation.
+ *
+ * @param calls - Array of Starknet calls to simulate
+ * @param account - Starknet Account instance
+ * @throws If calls array is empty
+ */
+declare function preflight(calls: Call[], account: Account): Promise<PreflightResult>;
+
+/** SNIP-12 domain for x402 payments */
+declare const X402_DOMAIN: {
+    name: string;
+    version: string;
+    chainId: string;
+};
+/** SNIP-12 typed data structure for x402 payment */
+declare const X402_TYPES: {
+    StarknetDomain: {
+        name: string;
+        type: string;
+    }[];
+    Payment: {
+        name: string;
+        type: string;
+    }[];
+};
+/** Simple convenience params for buildX402TypedData */
+interface BuildX402SimpleParams {
+    /** Sender address */
+    from: string;
+    /** Recipient address */
+    recipient: string;
+    /** Amount in USDC base units (string) */
+    amount: string;
+    /** Nonce for replay protection */
+    nonce: string;
+    /** Seconds until expiry (default: 300) */
+    expiry?: number;
+    /** Asset address (default: USDC mainnet) */
+    asset?: string;
+}
+/** Full message params (original API) */
+interface BuildX402FullMessage {
+    from_address: string;
+    to_address: string;
+    amount: string;
+    asset: string;
+    valid_until: string;
+    nonce: string;
+}
+/**
+ * Build the full SNIP-12 typed data object for an x402 payment.
+ * Centralises the structure so client, facilitator, and React hook stay in sync.
+ *
+ * @example
+ * ```typescript
+ * // Full params (original)
+ * buildX402TypedData({ from_address, to_address, amount, asset, valid_until, nonce })
+ *
+ * // Simple convenience params
+ * buildX402TypedData({ from: sender, recipient, amount, nonce, expiry: 300 })
+ * ```
+ */
+declare function buildX402TypedData(message: BuildX402FullMessage | BuildX402SimpleParams): TypedData;
+/**
+ * Minimal fetch-compatible interfaces.
+ * These mirror the standard Fetch API but allow the client to work
+ * in both browser and Node.js (18+) environments without requiring DOM lib.
+ */
+interface FetchResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * x402 payment client for Starknet.
+ *
+ * Wraps fetch calls with automatic HTTP 402 payment handling.
+ * When a server returns 402 Payment Required, the client:
+ * 1. Parses the payment requirement from the response header
+ * 2. Validates against configured limits (max amount, allowed recipients)
+ * 3. Signs a SNIP-12 typed data payment message
+ * 4. Retries the request with the signed payment in the X-PAYMENT header
+ *
+ * Works with any Starknet Account (DirectSigner, passkey, session key, external wallet).
+ * When used with a session key account, payments are fully automatic (no user interaction).
+ */
+declare class X402Client {
+    private readonly account;
+    private readonly config;
+    private readonly fetchFn;
+    constructor(account: Account, config?: X402ClientConfig);
+    /**
+     * Wrap a fetch call with x402 payment handling.
+     * If the server returns 402, automatically sign payment and retry.
+     */
+    fetch(url: string, init?: Record<string, any>): Promise<FetchResponse>;
+    /**
+     * Parse PAYMENT-REQUIRED header from 402 response.
+     */
+    parsePaymentRequired(response: FetchResponse): PaymentRequirement;
+    /**
+     * Validate payment requirement against client configuration limits.
+     * Throws if the payment would exceed maxPaymentAmount or recipient is not whitelisted.
+     */
+    validateRequirement(requirement: PaymentRequirement): void;
+    /**
+     * Sign a SNIP-12 typed data payment message for the given requirement.
+     * Returns a PaymentPayload ready to be sent as the X-PAYMENT header.
+     */
+    signPayment(requirement: PaymentRequirement): Promise<PaymentPayload>;
+    /**
+     * Retry the original request with the X-PAYMENT header containing the signed payment.
+     */
+    private retryWithPayment;
+}
+
+/**
+ * STRK20 confidential-token (privacy pool) constants and the minimal ABI
+ * fragment needed to (de)serialize pool actions.
+ *
+ * All values verified on Starknet mainnet 2026-06-27 against the official pool.
+ * The pool is StarkWare's permissionless multi-token confidential pool (STRK20,
+ * Starknet v0.14.2). We integrate it directly; we do not deploy our own.
+ */
+/** Official STRK20 privacy pool (Starknet mainnet). */
+declare const POOL_ADDRESS = "0x040337b1af3c663e86e333bab5a4b28da8d4652a15a69beee2b677776ffe812a";
+/** Canonical STRK token — the per-action fee is charged in STRK. */
+declare const STRK_ADDRESS = "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";
+/** Flat fee per private action: 4 STRK (~0.12 USD at 0.03 USD/STRK). */
+declare const FEE_AMOUNT: bigint;
+/**
+ * Settlement window: a generated proof is valid for this many blocks
+ * (~20 min wall-clock at ~2.63s/block). An action must settle inside it.
+ */
+declare const PROOF_VALIDITY_BLOCKS = 450;
+/**
+ * Minimal ABI fragment for the pool. Covers the action flow only:
+ *   compile_actions (local view) -> apply_actions (proven invoke)
+ * plus the read helpers we need. The full pool ABI is large; we keep just
+ * what CallData needs to serialize a ClientAction[] input.
+ */
+declare const POOL_ABI: readonly [{
+    readonly type: "struct";
+    readonly name: "core::integer::u256";
+    readonly members: readonly [{
+        readonly name: "low";
+        readonly type: "core::integer::u128";
+    }, {
+        readonly name: "high";
+        readonly type: "core::integer::u128";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "privacy::actions::DepositInput";
+    readonly members: readonly [{
+        readonly name: "token";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "amount";
+        readonly type: "core::integer::u128";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "privacy::actions::WithdrawInput";
+    readonly members: readonly [{
+        readonly name: "to_addr";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "token";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "amount";
+        readonly type: "core::integer::u128";
+    }, {
+        readonly name: "random";
+        readonly type: "core::felt252";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "privacy::actions::SetViewingKeyInput";
+    readonly members: readonly [{
+        readonly name: "random";
+        readonly type: "core::felt252";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "privacy::actions::OpenChannelInput";
+    readonly members: readonly [{
+        readonly name: "recipient_addr";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "index";
+        readonly type: "core::integer::u32";
+    }, {
+        readonly name: "random";
+        readonly type: "core::felt252";
+    }, {
+        readonly name: "salt";
+        readonly type: "core::felt252";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "privacy::actions::OpenSubchannelInput";
+    readonly members: readonly [{
+        readonly name: "recipient_addr";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "recipient_public_key";
+        readonly type: "core::felt252";
+    }, {
+        readonly name: "channel_key";
+        readonly type: "core::felt252";
+    }, {
+        readonly name: "index";
+        readonly type: "core::integer::u32";
+    }, {
+        readonly name: "token";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "salt";
+        readonly type: "core::felt252";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "privacy::actions::CreateEncNoteInput";
+    readonly members: readonly [{
+        readonly name: "recipient_addr";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "recipient_public_key";
+        readonly type: "core::felt252";
+    }, {
+        readonly name: "token";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "amount";
+        readonly type: "core::integer::u128";
+    }, {
+        readonly name: "index";
+        readonly type: "core::integer::u32";
+    }, {
+        readonly name: "salt";
+        readonly type: "core::integer::u128";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "privacy::actions::CreateOpenNoteInput";
+    readonly members: readonly [{
+        readonly name: "recipient_addr";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "recipient_public_key";
+        readonly type: "core::felt252";
+    }, {
+        readonly name: "token";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "index";
+        readonly type: "core::integer::u32";
+    }, {
+        readonly name: "random";
+        readonly type: "core::felt252";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "privacy::actions::UseNoteInput";
+    readonly members: readonly [{
+        readonly name: "channel_key";
+        readonly type: "core::felt252";
+    }, {
+        readonly name: "token";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "index";
+        readonly type: "core::integer::u32";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "core::array::Span::<core::felt252>";
+    readonly members: readonly [{
+        readonly name: "snapshot";
+        readonly type: "@core::array::Array::<core::felt252>";
+    }];
+}, {
+    readonly type: "struct";
+    readonly name: "privacy::actions::InvokeExternalInput";
+    readonly members: readonly [{
+        readonly name: "contract_address";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "calldata";
+        readonly type: "core::array::Span::<core::felt252>";
+    }];
+}, {
+    readonly type: "enum";
+    readonly name: "privacy::actions::ClientAction";
+    readonly variants: readonly [{
+        readonly name: "SetViewingKey";
+        readonly type: "privacy::actions::SetViewingKeyInput";
+    }, {
+        readonly name: "OpenChannel";
+        readonly type: "privacy::actions::OpenChannelInput";
+    }, {
+        readonly name: "OpenSubchannel";
+        readonly type: "privacy::actions::OpenSubchannelInput";
+    }, {
+        readonly name: "CreateEncNote";
+        readonly type: "privacy::actions::CreateEncNoteInput";
+    }, {
+        readonly name: "CreateOpenNote";
+        readonly type: "privacy::actions::CreateOpenNoteInput";
+    }, {
+        readonly name: "Deposit";
+        readonly type: "privacy::actions::DepositInput";
+    }, {
+        readonly name: "UseNote";
+        readonly type: "privacy::actions::UseNoteInput";
+    }, {
+        readonly name: "Withdraw";
+        readonly type: "privacy::actions::WithdrawInput";
+    }, {
+        readonly name: "InvokeExternal";
+        readonly type: "privacy::actions::InvokeExternalInput";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "compile_actions";
+    readonly state_mutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "user_addr";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }, {
+        readonly name: "user_private_key";
+        readonly type: "core::felt252";
+    }, {
+        readonly name: "client_actions";
+        readonly type: "core::array::Array::<privacy::actions::ClientAction>";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "core::array::Array::<privacy::actions::ServerAction>";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "get_public_key";
+    readonly state_mutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "user_addr";
+        readonly type: "core::starknet::contract_address::ContractAddress";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "core::felt252";
+    }];
+}];
+
+/**
+ * STRK20 privacy types — the shield/unshield action inputs, the opaque
+ * compiled-actions payload, and the prover seam.
+ */
+/** Shield: move a public ERC20 balance into the pool. */
+interface DepositInput {
+    /** ERC20 token address being shielded. */
+    token: string;
+    /** Raw amount in base units. */
+    amount: bigint;
+}
+/** Unshield: spend pool notes back out to a public address. */
+interface WithdrawInput {
+    /** Public recipient address. */
+    toAddr: string;
+    /** ERC20 token address being unshielded. */
+    token: string;
+    /** Raw amount in base units. */
+    amount: bigint;
+    /** Per-action blinding randomness (felt). */
+    random: bigint;
+}
+/**
+ * Output of the local `compile_actions` view: the serialized ServerAction[]
+ * felts, ready to be passed verbatim as `apply_actions` calldata. Kept opaque
+ * on purpose — Cairo serde is symmetric, so the view's return felts are exactly
+ * the array calldata `apply_actions` expects.
+ */
+interface CompiledActions {
+    /** Raw felt serialization of `Array<ServerAction>` (length-prefixed). */
+    serverActions: string[];
+}
+/** An assembled-but-unproven invoke the prover must prove (SNIP-36). */
+interface ProvableInvoke {
+    senderAddress: string;
+    calls: {
+        contractAddress: string;
+        entrypoint: string;
+        calldata: string[];
+    }[];
+    /** Reference block the proof is generated against. */
+    blockNumber?: number;
+}
+/** What a prover returns — attached to the v3 invoke via SNIP-36. */
+interface ProveResult {
+    /** Base64 STARK proof. */
+    proof: string;
+    /** proof_facts felts folded into the SNIP-36 transaction hash. */
+    proofFacts: string[];
+}
+/**
+ * Prover seam. v1 mobile clients use a delegated prover (StarkWare's
+ * `snip-36-prover-backend`); the proof rides the transaction via SNIP-36 and is
+ * never part of the action calldata.
+ */
+interface PrivacyProver {
+    /** Generate a STARK proof for an assembled invoke. */
+    prove(invoke: ProvableInvoke): Promise<ProveResult>;
+    /** Whether this prover is wired and ready (gates the UI submit). */
+    ready(): Promise<boolean>;
+}
+
+/**
+ * Build the `SetViewingKey` ClientAction — the REQUIRED first action for a new
+ * pool user (verified on-chain: without it, Deposit/Withdraw revert
+ * `NO_REPLAY_PROTECTION`). Registers the viewing key (encrypted to the auditor)
+ * and bootstraps the account's replay-protection state.
+ */
+declare function setViewingKeyAction(random: bigint): CairoCustomEnum;
+/**
+ * Build the `Deposit` ClientAction (shield). One variant is active; the rest
+ * are `undefined`, per starknet.js Cairo-enum encoding.
+ */
+declare function depositAction(input: DepositInput): CairoCustomEnum;
+/** Build the `Withdraw` ClientAction (unshield). */
+declare function withdrawAction(input: WithdrawInput): CairoCustomEnum;
+
+/**
+ * Deterministic message signed to derive the STRK20 **pool** key. Distinct from
+ * the account-key derivation so the pool key is a separate keypair, per the
+ * pool's `get_public_key` model. MUST never change (it fixes every pool key).
+ */
+declare const POOL_KEY_DERIVATION_MESSAGE = "CHIPI_STRK20_POOL_KEY_V1";
+/** ASCII bytes of {@link POOL_KEY_DERIVATION_MESSAGE} for signing. */
+declare function getPoolKeyDerivationMessage(): Uint8Array;
+/**
+ * @deprecated OWNER-COUPLED — do not use for new wallets. Deriving the pool key
+ * from an owner signature breaks on guardian recovery (owner keys rotate, the
+ * derived key changes, old notes become unspendable — see SHHH_WALLET_VNEXT_SPEC
+ * §4). Use {@link derivePoolKeypair} with an owner-INDEPENDENT anchor instead.
+ */
+declare function derivePoolKeypairFromSignature(signature: Uint8Array): Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;
+/**
+ * Derive the STRK20 **pool spending keypair** — DECOUPLED from any owner key
+ * (the recovery-stable design, SHHH_WALLET_VNEXT_SPEC §4).
+ *
+ * `anchorSecret` MUST be owner-INDEPENDENT and survive device loss: a passkey
+ * WebAuthn PRF output (synced → survives), a user recovery phrase, or a
+ * guardian-restored secret. NEVER an owner signature (that re-introduces the
+ * coupling). `seedDomainTag` is the per-wallet felt bound on-chain at
+ * `enable_shield` — mixed in so two wallets can never collide by PRF collision.
+ *
+ * pool key = SHA-256(POOL_DOMAIN || seedDomainTag(32B) || anchorSecret) → canonical.
+ * Its public key is the on-chain `privacy_commitment`.
+ *
+ * SECURITY: the private key is the spending key — client-side only, never STORED server-side (note: delegated proving includes the pool key in each proof request — see chipi-proof-provider).
+ */
+declare function derivePoolKeypair(params: {
+    anchorSecret: Uint8Array;
+    seedDomainTag: string | bigint;
+}): Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;
+/**
+ * Derive the **companion account** stark keypair — the standard SNIP-6 account
+ * that acts as the pool's `user_addr` (it has `is_valid_signature`; the SHHH
+ * wallet does not). A SEPARATE draw from the same anchor (defense in depth:
+ * companion-key compromise ≠ note theft, which needs the pool key). Full-range
+ * (a normal account key, not pool-canonical).
+ */
+declare function deriveCompanionKeypair(anchorSecret: Uint8Array): Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;
+/**
+ * Counterfactual address of the companion account — deterministic from its
+ * public key + the standard OZ account class. Self-custodial: derivable on any
+ * device from the anchor; deploy is a no-op if it already exists. Store only the
+ * address (public) in the backend, never the key.
+ */
+declare function deriveCompanionAddress(params: {
+    publicKey: string;
+    classHash: string;
+    salt?: string;
+}): string;
+
+interface CompileActionsParams {
+    /** The user's pool address (separate from the Starknet account address). */
+    userAddress: string;
+    /**
+     * The user's POOL private key (not the account key).
+     *
+     * SECURITY: `compile_actions` is a Cairo view that takes the private key as an
+     * argument, so it MUST run against a local/trusted node only. Never point this
+     * at a public RPC — the key would be sent in the request.
+     */
+    userPrivateKey: string;
+    /** Ordered ClientActions (e.g. a single Deposit, or a Withdraw). */
+    actions: CairoCustomEnum[];
+    /** Pool address override (defaults to the official mainnet pool). */
+    poolAddress?: string;
+}
+/**
+ * Run the pool's `compile_actions` view locally to turn ClientActions into the
+ * serialized ServerAction[] that `apply_actions` consumes.
+ *
+ * @param provider - A LOCAL/trusted provider (the private key is in calldata).
+ */
+declare function compileActions(provider: ProviderInterface, params: CompileActionsParams): Promise<CompiledActions>;
+
+/** Build the `apply_actions(ServerAction[])` Call from compiled actions. */
+declare function applyActionsCall(compiled: CompiledActions, poolAddress?: string): Call;
+interface BuildShieldParams {
+    /** ERC20 token being shielded. */
+    token: string;
+    /** Raw amount in base units (must match the Deposit action). */
+    amount: bigint;
+    /** Output of {@link compileActions} for a single Deposit action. */
+    compiled: CompiledActions;
+    poolAddress?: string;
+}
+/**
+ * Build the shield (deposit) call batch: approve the pool to pull the token,
+ * then apply the compiled Deposit action. The proof is NOT in calldata — it
+ * rides the transaction via SNIP-36 and is attached at submit time.
+ */
+declare function buildShieldCalls(params: BuildShieldParams): Call[];
+interface BuildUnshieldParams {
+    /** Output of {@link compileActions} for a single Withdraw action. */
+    compiled: CompiledActions;
+    poolAddress?: string;
+}
+/**
+ * Build the unshield (withdraw) call batch. The user already owns the notes
+ * being spent, so no approve is needed — just apply the compiled Withdraw.
+ */
+declare function buildUnshieldCalls(params: BuildUnshieldParams): Call[];
+
+/**
+ * Minimal fetch shape so the SDK does not depend on DOM lib types.
+ * Pass `globalThis.fetch` (Node 18+ / browsers) or any compatible impl.
+ */
+type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+interface DelegatedProverOptions {
+    /** Base URL of the SNIP-36 proving backend (self-hosted in prod). */
+    baseUrl: string;
+    /** Path that accepts an invoke and returns { proof, proof_facts }. */
+    provePath?: string;
+    /** Health path used by {@link DelegatedProver.ready}. */
+    healthPath?: string;
+    /** Custom fetch (defaults to globalThis.fetch). */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Delegated prover: sends an assembled invoke to a remote
+ * `snip-36-prover-backend` and returns the STARK proof + proof_facts.
+ *
+ * For mobile, proving is too heavy on-device, so v1 uses this. Test points at
+ * StarkWare/SNF's hosted backend; prod points at our own Railway instance.
+ */
+declare class DelegatedProver implements PrivacyProver {
+    private readonly baseUrl;
+    private readonly provePath;
+    private readonly healthPath;
+    private readonly fetchImpl;
+    constructor(opts: DelegatedProverOptions);
+    prove(invoke: ProvableInvoke): Promise<ProveResult>;
+    ready(): Promise<boolean>;
+}
+/**
+ * Placeholder prover for dev/preview before the real prover is wired. Lets the
+ * full shield/unshield UI render end-to-end with the final submit disabled.
+ */
+declare class StubProver implements PrivacyProver {
+    prove(_invoke: ProvableInvoke): Promise<ProveResult>;
+    ready(): Promise<boolean>;
+}
+
+interface ResourceBound {
+    /** Max units of the resource. */
+    maxAmount: bigint;
+    /** Max price per unit (fri). */
+    maxPricePerUnit: bigint;
+}
+interface ResourceBoundsV3 {
+    l1Gas: ResourceBound;
+    l2Gas: ResourceBound;
+    l1DataGas: ResourceBound;
+}
+interface Snip36InvokeParams {
+    /** Account that signs/pays (user for self-paid, relayer for sponsored). */
+    senderAddress: string;
+    /** The account `__execute__` calldata (felt[]). See {@link encodeExecuteCalldata}. */
+    calldata: string[];
+    /** Chain id felt (e.g. provider.getChainId() → "0x534e5f4d41494e"). */
+    chainId: string;
+    /** Sender nonce. */
+    nonce: bigint;
+    resourceBounds: ResourceBoundsV3;
+    /** Base64 STARK proof from the prover. */
+    proof: string;
+    /** proof_facts felts from the prover (empty → a standard v3 invoke). */
+    proofFacts: string[];
+    /** Defaults: tip 0, empty paymaster/deployment data, L1 DA modes. */
+    tip?: bigint;
+    paymasterData?: string[];
+    accountDeploymentData?: string[];
+    nonceDaMode?: number;
+    feeDaMode?: number;
+}
+/**
+ * Compute the SNIP-36 invoke v3 transaction hash. With `proofFacts` empty this
+ * is exactly the standard Starknet v3 invoke hash; non-empty appends
+ * `poseidon(proof_facts)` as the final element of the hash chain.
+ */
+declare function computeSnip36InvokeHash(params: Snip36InvokeParams): bigint;
+/** Sign a hash with a STARK private key (RFC-6979 deterministic). */
+declare function signHash(privateKey: string, messageHash: bigint): {
+    r: string;
+    s: string;
+};
+/**
+ * Build the RPC `INVOKE_TXN_V3` payload extended with `proof` + `proof_facts`.
+ *
+ * SIGNING (verified on mainnet 2026-06-29): a STANDARD account validates the
+ * STANDARD v3 hash, so by default we sign the hash computed WITHOUT proof_facts
+ * — `proof_facts` rides as a payload field only, and the on-chain tx hash equals
+ * the standard v3 hash. For a SNIP-36-aware account class that folds
+ * `proof_facts` into `__validate__`, pass `{ signWithProofFacts: true }`.
+ *
+ * Returns `txHash` = the signed hash (the on-chain tx hash in the default mode).
+ */
+declare function buildSnip36InvokePayload(params: Snip36InvokeParams, privateKey: string, opts?: {
+    signWithProofFacts?: boolean;
+}): {
+    txHash: bigint;
+    invokeTransaction: Record<string, unknown>;
+};
+/**
+ * Build the SEQUENCER GATEWAY payload for a SNIP-36 invoke (verified on mainnet
+ * 2026-06-29 — the shipped shield/unshield path).
+ *
+ * Why the gateway, not the JSON-RPC: the cartridge JSON-RPC silently DROPS the
+ * `proof_facts` field, so the pool sees `EMPTY_PROOF_FACTS`. The sequencer
+ * gateway is SNIP-36-aware: it keeps `proof_facts` (into tx_info) AND computes
+ * the tx hash WITH the proof_facts hash appended — so we sign the WITH-FACTS
+ * hash here (always), and even a STANDARD account validates it on the gateway.
+ *
+ * Differences from the RPC payload: `type: "INVOKE_FUNCTION"` and UPPERCASE
+ * resource-bound keys (`L1_GAS`/`L2_GAS`/`L1_DATA_GAS`).
+ */
+declare function buildGatewayPayload(params: Snip36InvokeParams, privateKey: string): {
+    txHash: bigint;
+    gatewayPayload: Record<string, unknown>;
+};
+/**
+ * Submit a SNIP-36 gateway payload to `${gatewayUrl}/gateway/add_transaction`.
+ * Returns the transaction hash. Throws if the gateway does not return
+ * `code: "TRANSACTION_RECEIVED"`.
+ */
+declare function submitViaGateway(gatewayUrl: string, gatewayPayload: Record<string, unknown>, fetchImpl?: (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    json(): Promise<unknown>;
+}>): Promise<string>;
+/**
+ * Compile an account `__execute__` calldata from a list of Calls — the
+ * `calldata` field for {@link Snip36InvokeParams}.
+ */
+declare function encodeExecuteCalldata(calls: Call[], cairoVersion?: CairoVersion): string[];
+/**
+ * Submit a SNIP-36 invoke via raw JSON-RPC `starknet_addInvokeTransaction`.
+ * Uses a raw call because the extra proof fields aren't in starknet.js's typed
+ * invoke. Returns the transaction hash from the node.
+ */
+declare function submitSnip36Invoke(rpcUrl: string, invokeTransaction: Record<string, unknown>, fetchImpl?: (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    json(): Promise<unknown>;
+}>): Promise<string>;
+/**
+ * Submit a SNIP-36 invoke with the sequencer GATEWAY as primary and a
+ * SNIP-36-aware RPC as fallback.
+ *
+ * The feeder gateway is StarkWare-deprecated; the RPC path is the durable
+ * successor. The RPC MUST be SNIP-36-aware (keeps `proof_facts` and computes the
+ * with-facts hash — e.g. Alchemy/Dwellir spec v0.8+). Do NOT pass a node that
+ * drops `proof_facts` (e.g. cartridge) — the pool would see `EMPTY_PROOF_FACTS`.
+ * Both transports sign the WITH-FACTS hash.
+ *
+ * @returns the tx hash and which transport carried it.
+ */
+declare function submitSnip36WithFallback(params: Snip36InvokeParams, privateKey: string, opts: {
+    gatewayUrl?: string;
+    rpcUrl?: string;
+    /** FULL submit URL used VERBATIM (no path appended) — for browser callers
+     *  that must POST through a same-origin server proxy: the sequencer
+     *  gateway sends no CORS headers, so a direct browser POST is blocked
+     *  (walletv2 ships an /api/starknet-gateway proxy for exactly this). */
+    submitUrl?: string;
+    fetchImpl?: (url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+    }) => Promise<{
+        json(): Promise<unknown>;
+    }>;
+}): Promise<{
+    transactionHash: string;
+    via: "gateway" | "rpc";
+}>;
+/** Convenience: the apply_actions Call's calldata is the compiled server actions. */
+declare function serverActionsCalldata(compiled: CompiledActions): string[];
+
+/**
+ * Proof provider that routes proving through chipi-back `/privacy/prove` (which
+ * forwards to the private SNIP-36 prover over Railway internal networking).
+ *
+ * Extends the official `ProvingServiceProofProvider` so it inherits the exact
+ * `getDefaultDetails()` the SDK's proof-invocation factory needs (replicating it
+ * drifts — a missing field breaks tx-hash signing). We override ONLY `prove()`
+ * to call chipi-back with auth instead of an open JSON-RPC prover. The prover
+ * itself is never publicly reachable; access is Chipi-gated at the proxy.
+ */
+interface ChipiProofProviderOptions {
+    /** chipi-back base URL, e.g. https://api.chipipay.com */
+    baseUrl: string;
+    /** Chipi API PUBLIC key — sent as `x-api-key` (chipi-back's BearerTokenGuard
+     *  requires it ALONGSIDE the JWT). Also the Authorization fallback when no
+     *  user JWT is supplied (shim / server-side callers). */
+    apiKey: string;
+    /** Static user JWT (Authorization: Bearer). Prefer getBearerToken. */
+    bearerToken?: string;
+    /** Fresh-token source called RIGHT BEFORE each prove request. The companion
+     *  deploy + approvals that precede proving take 30–90s of on-chain waits —
+     *  longer than a typical auth token's lifetime (Clerk ≈60s), so a token
+     *  captured at flow start is often expired by prove time (the live
+     *  first-attempt "prove 401: Invalid JWT", 2026-07-04). */
+    getBearerToken?: () => Promise<string | null | undefined>;
+    /** Chain id felt — needed for the proof-invocation defaults (e.g. SN_MAIN). */
+    chainId: string;
+    /** Prove endpoint path. Default "/privacy/prove". */
+    provePath?: string;
+    /** Reference block. Default "latest" (the prover resolves to head − N). */
+    blockId?: string | number;
+    /** Custom fetch (defaults to globalThis.fetch). */
+    fetchImpl?: FetchLike;
+}
+/** The proof shape the SDK's compiler/execute consumes. */
+interface ProofResult {
+    data: string;
+    output: string[];
+    proofFacts: string[];
+    /** Screening attestation side-channel from a screening-capable prover
+     *  (hosted proving). Pool v2.0 REQUIRES it on deposits; the bundled SDK
+     *  packs it into apply_actions calldata when present. */
+    additionalData?: {
+        signature?: {
+            issued_at: number;
+            sig_r: string;
+            sig_s: string;
+        };
+    };
+}
+interface ProofInvocation {
+    sender_address: string;
+    [k: string]: unknown;
+}
+declare class ChipiProofProvider extends ProvingServiceProofProvider {
+    private readonly chipiBaseUrl;
+    private readonly apiKey;
+    private readonly chipiBearer?;
+    private readonly chipiGetBearer?;
+    private readonly chipiProvePath;
+    private readonly chipiBlockId;
+    private readonly chipiFetch;
+    constructor(opts: ChipiProofProviderOptions);
+    prove(invocation: ProofInvocation, blockIdentifier?: string | number): Promise<ProofResult>;
+}
+
+interface ShieldFee {
+    /** Pool privacy fee in STRK (wei) — `collect_fee` charges this to the caller. */
+    feeStrk: bigint;
+    /** Same fee in USD, given a STRK/USD price. What the user actually sees. */
+    feeUsd: number;
+}
+/**
+ * The STRK20 pool charges a FIXED STRK fee per op (`collect_fee`, 4 STRK). The
+ * consumer UX must NEVER make the user hold STRK (the Ready model): the
+ * paymaster / gas-tank FRONTS the STRK, and we surface the cost in USD. This
+ * converts the on-chain STRK fee to the USD figure for the review screen.
+ */
+declare function getShieldFee(strkUsdPrice: number, feeAmount?: bigint): ShieldFee;
+/**
+ * Review-screen preview (mirrors Ready's `−10 USDC → +9.86 [USDC], 0.14 fee`).
+ *
+ * - `sponsored: true` (recommended for adoption): the gas-tank eats the fee, the
+ *   user receives the FULL amount (`received === amount`).
+ * - otherwise: the USD-equivalent fee is deducted from the shielded amount, so
+ *   `received = amount − feeInToken` (the deducted token reimburses the fronted STRK).
+ *
+ * `amount` and `received` are in token wei (e.g. USDC at 6 decimals).
+ */
+declare function previewShield(params: {
+    amount: bigint;
+    tokenDecimals: number;
+    tokenUsdPrice: number;
+    strkUsdPrice: number;
+    sponsored?: boolean;
+}): {
+    received: bigint;
+    feeInToken: bigint;
+    feeStrk: bigint;
+    feeUsd: number;
+};
+
+/**
+ * High-level shield / unshield over the official (vendored) StarkWare privacy
+ * SDK + our prover proxy + the sequencer gateway. This is the packaged,
+ * verified path (mainnet 2026-06-29: shield 0x31f84064…, unshield 0x78fe9dd5…).
+ *
+ * The note-graph (compile_actions, channel/note crypto, discovery) comes from
+ * the vendored `starknet-sdk`; proving goes through {@link ChipiProofProvider}
+ * (chipi-back → private prover); submit uses {@link submitSnip36WithFallback}
+ * (gateway primary, SNIP-36-aware RPC fallback). Every call WAITS for the
+ * receipt and asserts it settled ({@link assertShieldReceipt}) — no phantom
+ * success on a mere gateway-accept.
+ *
+ * Fee model (the Ready model): the pool charges a fixed STRK fee (`collect_fee`,
+ * 4 STRK) to the caller. The user NEVER holds STRK — the paymaster/gas-tank
+ * FRONTS the STRK into the companion, and the cost is surfaced in USD via
+ * {@link getShieldFee}/{@link previewShield}. `ShieldResult.feeStrk` is the
+ * incurred pool fee.
+ *
+ * Preconditions (the gasless funding step handles both): the companion must hold
+ * the ~4 STRK fee (fronted) and have approved the pool for the deposit amount.
+ */
+
+/** The account/pool context shared by every privacy op (shield, unshield, balance). */
+interface PrivacyContext {
+    provider: RpcProvider;
+    /** The pool `user_addr`: a standard SNIP-6 account (companion or native vNext). */
+    account: Account;
+    /** Pool spending key — DECOUPLED from owner keys, PRF-anchored (see SHHH vNext spec §4). */
+    viewingKey: bigint;
+    provingProvider: ChipiProofProvider;
+    poolAddress?: string;
+}
+interface ShieldParams extends PrivacyContext {
+    /** Private key used to sign the SNIP-36 gateway tx (the account's signer key). */
+    signerKey: string;
+    token: string;
+    amount: bigint;
+    gatewayUrl?: string;
+    /** FULL submit URL used verbatim — browser same-origin proxy for the
+     *  CORS-less sequencer gateway (see submitSnip36WithFallback.submitUrl). */
+    gatewaySubmitUrl?: string;
+    /** SNIP-36-aware RPC fallback (Alchemy/Dwellir v0.8+) if the gateway is down/deprecated. */
+    rpcUrl?: string;
+    chainId: string;
+}
+/** Receipt or the Error waitForTransaction may throw. */
+interface ShieldReceiptLike {
+    execution_status?: string;
+    finality_status?: string;
+    revert_reason?: string;
+    events?: {
+        from_address?: string;
+    }[];
+    message?: string;
+}
+/**
+ * Anti-phantom-success guard. The gateway returning TRANSACTION_RECEIVED only
+ * means accepted — the tx can still REVERT (proof expiry, NEGATIVE_INTERMEDIATE
+ * _BALANCE, etc.). Assert the receipt actually SUCCEEDED *and* the pool emitted
+ * an event (proof verified + state changed), not just that a hash exists.
+ */
+declare function assertShieldReceipt(r: ShieldReceiptLike, poolAddress: string): void;
+interface ShieldResult {
+    transactionHash: string;
+    via: "gateway" | "rpc";
+    receipt: ShieldReceiptLike;
+    /** Pool fee incurred (STRK wei) — fronted by the gas-tank, shown to the user in USD. */
+    feeStrk: bigint;
+}
+/**
+ * Read the user's private (shielded) balance per token by scanning notes with
+ * their viewing key. Discovery only — no proving, no on-chain write, safe to
+ * call for display. Returns per-token totals keyed by lowercase hex address.
+ */
+declare function getPrivateBalance(p: PrivacyContext & {
+    tokens?: string[];
+}): Promise<{
+    byToken: Record<string, bigint>;
+}>;
+/**
+ * Shield SEVERAL tokens in ONE apply_actions — one proof, one pool fee.
+ * Uses the SDK's `with(token, ops)` callback overload (returns `this`),
+ * which exists precisely for batched multi-token builds.
+ */
+declare function shieldMany(p: Omit<ShieldParams, "token" | "amount"> & {
+    deposits: {
+        token: string;
+        amount: bigint;
+    }[];
+}): Promise<ShieldResult>;
+/** Shield `amount` of `token` from the account into a private note. */
+declare function shield(p: ShieldParams): Promise<ShieldResult>;
+/** Unshield `amount` of `token` from private notes back to the account. */
+declare function unshield(p: ShieldParams): Promise<ShieldResult>;
+
+/**
+ * Auto-shield ("Recibir en privado") — automatically shield incoming deposits.
+ *
+ * This layer is PURE POLICY: it decides *whether* and *how much* to shield for a
+ * deposit, then delegates the actual shield to a caller-supplied executor. It is
+ * deliberately account-agnostic so it survives the v8.5 shift unchanged:
+ *   - TODAY (companion): the executor builds ShieldParams with the companion
+ *     account + its derived signer key.
+ *   - v8.5 (native SHHH): the executor builds ShieldParams with the SHHH wallet
+ *     as user_addr + a relayer/OE submit. Same call site; only the executor's
+ *     account wiring changes. NO change to this policy layer.
+ */
+type AutoShieldMode = "off" | "cross-chain" | "all";
+interface PrivacySettings {
+    /** "Recibir en privado" master. */
+    autoShield: AutoShieldMode;
+    /**
+     * Do not auto-shield dust (fee would dominate). In token wei. Deposits below
+     * this are left in the available balance. Default applied by resolveAutoShield.
+     */
+    minAmount?: bigint;
+}
+type DepositSource = "cross-chain" | "onchain" | "internal";
+interface DepositEvent {
+    /** Token contract (felt hex). */
+    token: string;
+    /** Amount that arrived (token wei). */
+    amount: bigint;
+    /** Where it came from — drives the "solo cross-chain" default. */
+    source: DepositSource;
+    /** The arrival tx (for idempotency + notifications). */
+    txHash: string;
+    /** Token decimals, for display. */
+    tokenDecimals?: number;
+}
+type AutoShieldDecision = {
+    shield: true;
+    amount: bigint;
+    reason: "cross-chain" | "all";
+} | {
+    shield: false;
+    reason: "disabled" | "source-excluded" | "below-min";
+};
+/**
+ * Decide whether a deposit should be auto-shielded. Pure — no I/O, fully
+ * testable. `cross-chain` mode shields only bridged/cross-chain inflows (the
+ * killer case: fewer, larger, privacy-worthy); `all` shields every deposit.
+ */
+declare function resolveAutoShield(deposit: DepositEvent, settings: PrivacySettings): AutoShieldDecision;
+interface AutoShieldOutcome {
+    decision: AutoShieldDecision;
+    /** Present only when a shield was executed. */
+    result?: ShieldResult;
+    /** Present when the executor threw (shield failed — deposit stays available). */
+    error?: string;
+}
+/**
+ * Run the auto-shield policy for a deposit and, if it decides to shield, invoke
+ * `executeShield` (which owns the account wiring — companion today, native v8.5
+ * tomorrow). `isAlreadyShielded` provides idempotency: a redelivered deposit
+ * event (webhooks retry) must not double-shield.
+ */
+declare function autoShieldOnDeposit(params: {
+    deposit: DepositEvent;
+    settings: PrivacySettings;
+    executeShield: (token: string, amount: bigint) => Promise<ShieldResult>;
+    isAlreadyShielded?: (txHash: string) => Promise<boolean>;
+}): Promise<AutoShieldOutcome>;
+
+/**
+ * Companion-account orchestration for shield/unshield — the PRODUCTION path
+ * battle-tested in walletv2 (2026-07-04→06 live-money QA) and backported here
+ * so the SDK is the single engine.
+ *
+ * A "companion" is a lightweight standard account, counterfactual until first
+ * use, derived from the user's anchor (see keys.ts). It is the pool
+ * `user_addr` (SNIP-6 `is_valid_signature`) and self-pays gas from STRK the
+ * gas-tank fronts (see gas.ts) — the USER never holds STRK.
+ *
+ * Order of operations (each step idempotent, learned the hard way):
+ *   1. deploy the companion if it isn't on-chain (self-paid, salt = pubkey);
+ *   2. approve the pool for the deposit token (the note-graph SDK proves
+ *      apply_actions in isolation — a missing allowance passes proving under
+ *      SKIP_VALIDATE then reverts on-chain as an opaque "Result::unwrap
+ *      failed");
+ *   3. approve STRK for the pool's collect_fee (same masked-revert trap);
+ *   4. shield()/unshield() — prove + gateway submit + receipt assert.
+ *
+ * Transient RPC errors (the public fee-estimation backend intermittently
+ * refuses connections) retry with backoff; real reverts never do.
+ */
+
+/** Retry clearly-transient network/infra errors only — never a real revert. */
+declare function withTransientRetry<T>(fn: () => Promise<T>, opts?: {
+    tries?: number;
+    delayMs?: number;
+}): Promise<T>;
+interface CompanionCtx {
+    provider: RpcProvider;
+    chainId: string;
+    /** Counterfactual companion address (deriveCompanionAddress). */
+    companionAddress: string;
+    /** Companion signer private key (deriveCompanionKeypair). NEVER a server value. */
+    companionKey: string;
+    /** Companion account class hash (standard SNIP-6 account, e.g. OZ). */
+    classHash: string;
+    /** Pool spending/viewing key (derivePoolKeypair). */
+    poolKey: bigint;
+    provingProvider: ChipiProofProvider;
+    poolAddress?: string;
+    gatewayUrl?: string;
+    /** Browser same-origin proxy for the CORS-less sequencer gateway. */
+    gatewaySubmitUrl?: string;
+    /** SNIP-36-aware RPC fallback. */
+    rpcUrl?: string;
+}
+/**
+ * Deploy the companion if it isn't on-chain yet (counterfactual → live).
+ * Self-pays from the companion's STRK (gas-tank-fronted BEFORE this runs).
+ * Idempotent; salt = pubkey so deployed address == counterfactual address.
+ */
+declare function ensureCompanionDeployed(c: CompanionCtx): Promise<void>;
+/**
+ * Approve `spender-pool` for `amount` of `token` from the companion —
+ * SETTLED ON-CHAIN before proving (see module doc). Idempotent: skips when
+ * the live allowance already covers `amount`.
+ */
+declare function ensureApproval(c: CompanionCtx, token: string, amount: bigint): Promise<void>;
+/** STRK allowance for collect_fee: the fixed fee + 50% buffer. */
+declare const FEE_APPROVE_STRK: bigint;
+/** Full production shield: deploy → approvals → prove/submit/assert. */
+declare function execShield(c: CompanionCtx, token: string, amount: bigint): Promise<ShieldResult>;
+/**
+ * Multi-token production shield: ONE proof, ONE pool fee for N tokens.
+ * Approvals settle per token BEFORE proving (same masked-revert trap as the
+ * single-token path). MAINNET-PROVEN 2026-07-08 (S5 smoke): USDC+STRK in one
+ * apply_actions 0x56f93116…, exactly one 4-STRK fee, per-token unshields OK.
+ * NOTE the prover-view constraint: proving runs against head-12, so notes/
+ * approvals created moments ago are invisible for ~6 min — back-to-back ops
+ * must wait (see scripts/*-token-smoke.mjs waitProverView).
+ */
+declare function execShieldMany(c: CompanionCtx, deposits: {
+    token: string;
+    amount: bigint;
+}[]): Promise<ShieldResult>;
+/**
+ * Full production unshield: deploy → STRK fee re-approve → prove/submit/assert.
+ * (No token approve: funds come FROM the pool.) Withdraws to the COMPANION —
+ * the caller delivers onward (sweepCompanion) so the money lands in the
+ * user's real wallet, not the internal account.
+ */
+declare function execUnshield(c: CompanionCtx, token: string, amount: bigint): Promise<ShieldResult>;
+
+/**
+ * Gas-tank funding + companion hygiene — the "user never holds STRK" half of
+ * the Ready fee model, backported from walletv2's production path.
+ *
+ *   • requestGasFunding — asks chipi-back /privacy/fund-gas to front STRK
+ *     into the companion (deploy gas + the pool's fixed fee). Fetches a FRESH
+ *     auth token per attempt and retries 401 (stale JWT) and 5xx (the
+ *     backend's transient RPC/nonce errors — live 503s killed shields on
+ *     2026-07-05 before retries existed on either side).
+ *   • waitForFunding — fund txs resolve on SUBMIT, not confirmation; poll
+ *     until the companion actually holds the STRK (+ token for a shield) so
+ *     deploy/shield don't fail with "exceed balance (0)".
+ *   • sweepCompanion — after an op, deliver withdrawn tokens to the user's
+ *     wallet and return leftover fronted STRK to the gas tank (the tank
+ *     fronts ~13 STRK but a shield burns ~7.4; without the sweep ~5.6 STRK
+ *     strands per op). Pure call-building is exposed for tests.
+ */
+
+/** STRK fronted per op: pool fee + measured deploy/approve/tx-gas headroom
+ *  (mainnet 0x24dde8c…: ~7.4 STRK burned, gateway validates ~8 STRK of max
+ *  resource bounds — 13 clears validation; the sweep recovers the surplus). */
+declare const GAS_FUND_STRK: bigint;
+/** STRK kept in the companion by the sweep, to pay the sweep tx itself. */
+declare const SWEEP_RESERVE_STRK: bigint;
+interface GasFundingOptions {
+    /** chipi-back base URL, e.g. https://api.chipipay.com/v1 */
+    baseUrl: string;
+    /** Chipi API public key (x-api-key header — required alongside the JWT). */
+    apiKey: string;
+    /** Static JWT fallback. Prefer getBearerToken. */
+    bearerToken?: string;
+    /** Fresh-token source, called before EVERY attempt. */
+    getBearerToken?: () => Promise<string | null | undefined>;
+    /** Fund-gas path. Default "/privacy/fund-gas". */
+    fundGasPath?: string;
+    /** Retry backoff base (ms). Tests inject 0. */
+    retryDelayMs?: number;
+    fetchImpl?: FetchLike;
+}
+/**
+ * Front `amountStrk` (wei; default {@link GAS_FUND_STRK}) from the Chipi
+ * gas-tank into `companion`. Resolves on SUBMIT — pair with waitForFunding.
+ */
+declare function requestGasFunding(companion: string, opts: GasFundingOptions & {
+    amountStrk?: bigint;
+}): Promise<void>;
+/**
+ * Poll until the companion holds ≥ needStrk STRK (and ≥ needToken of `token`
+ * when provided). Throws "funding_timeout" past the deadline.
+ */
+declare function waitForFunding(provider: RpcProvider, companion: string, need: {
+    strk: bigint;
+    token?: {
+        address: string;
+        amount: bigint;
+    };
+}, opts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<void>;
+interface SweepCall {
+    contractAddress: string;
+    entrypoint: "transfer";
+    calldata: [string, string, string];
+}
+/**
+ * PURE: the transfers a sweep should execute given live balances. Exposed for
+ * tests — the on-chain wrapper is {@link sweepCompanion}.
+ */
+declare function buildSweepCalls(p: {
+    tokenBalances: {
+        address: string;
+        amount: bigint;
+        deliverTo?: string;
+    }[];
+    strkBalance: bigint;
+    gasTank: string;
+    reserve?: bigint;
+}): SweepCall[];
+/**
+ * Post-op sweep: deliver `deliverToken` (if any) to the user's wallet and
+ * return leftover STRK (minus the reserve) to the gas tank. One companion tx,
+ * self-paid. BEST-EFFORT by design: a transient failure never blocks the op —
+ * funds stay safe in the companion and the next op/recovery reclaims them.
+ */
+declare function sweepCompanion(p: {
+    provider: RpcProvider;
+    companionAddress: string;
+    companionKey: string;
+    gasTank: string;
+    /** Deliver this token's full companion balance to `to` (unshield delivery). */
+    deliverToken?: {
+        address: string;
+        to: string;
+    };
+    /** Throw instead of swallowing errors — REQUIRED when the sweep IS the
+     *  delivery of the user's money (unshield), review finding M2. Best-effort
+     *  remains the default for the background STRK-return case. */
+    strict?: boolean;
+}): Promise<{
+    transactionHash: string | null;
+}>;
+
+export { Amount, type AutoShieldDecision, type AutoShieldMode, type AutoShieldOutcome, type BuildShieldParams, type BuildUnshieldParams, type BuildX402SimpleParams, ChipiProofProvider, type ChipiProofProviderOptions, type CompanionCtx, type CompileActionsParams, type CompiledActions, type CreateAccountOptions, DelegatedProver, type DelegatedProverOptions, type DepositEvent, type DepositInput, type DepositSource, DirectSigner, Erc20, ExternalSigner, FEE_AMOUNT, FEE_APPROVE_STRK, type FeeEstimate, type FetchLike, GAS_FUND_STRK, type GasFundingOptions, type Network, POOL_ABI, POOL_ADDRESS, POOL_KEY_DERIVATION_MESSAGE, PROOF_VALIDITY_BLOCKS, PasskeySigner, type PreflightResult$1 as PreflightResult, type PrivacyContext, type PrivacyProver, type PrivacySettings, type ProofResult, type ProvableInvoke, type ProveResult, type ResourceBound, type ResourceBoundsV3, STRK_ADDRESS, SWEEP_RESERVE_STRK, type ShieldFee, type ShieldParams, type ShieldReceiptLike, type ShieldResult, type SignResult, type SignerAdapter, type Snip36InvokeParams, StarknetSignerAdapter, StubProver, type SweepCall, type TokenInfo, TokenRegistry, type TransferTarget, TxBuilder, type TxBuilderOptions, type WithdrawInput, X402Client, X402_DOMAIN, X402_TYPES, applyActionsCall, assertShieldReceipt, autoShieldOnDeposit, buildGatewayPayload, buildShieldCalls, buildSnip36InvokePayload, buildSweepCalls, buildUnshieldCalls, buildX402TypedData, compileActions, computeSnip36InvokeHash, createAccount, depositAction, deriveCompanionAddress, deriveCompanionKeypair, derivePoolKeypair, derivePoolKeypairFromSignature, encodeExecuteCalldata, ensureApproval, ensureCompanionDeployed, estimateFee, execShield, execShieldMany, execUnshield, getPoolKeyDerivationMessage, getPrivateBalance, getShieldFee, preflight, previewShield, requestGasFunding, resolveAutoShield, serverActionsCalldata, setViewingKeyAction, shield, shieldMany, signHash, submitSnip36Invoke, submitSnip36WithFallback, submitViaGateway, sweepCompanion, unshield, waitForFunding, withTransientRetry, withdrawAction };