@invisi-labs/protocol 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,948 @@
+import * as _invisi_labs_core from '@invisi-labs/core';
+import { Hex, Address, ReceivingKeyLookup, WalletAuthorizationRequest, Wallet, WalletAuthorizationProvider, Note, CreditDeliveryState, AuthorizedStatement } from '@invisi-labs/core';
+import { ContractRunner, Provider } from 'ethers';
+import { Prover, ProverOptions, ProofTarget, CircuitName, ProofStatement, ProvingRequest } from '@invisi-labs/prover';
+import { DeploymentContext, CanonicalBlock, ProtocolDeployment, ProtocolRpcClient } from '@invisi-labs/rpc';
+export { CanonicalBlock, DeploymentContext, Membership, ProtocolDataProvider, ProtocolDataStatus, ProtocolUpdateRange, ProtocolUpdates } from '@invisi-labs/rpc';
+import { F as FundingParams, D as Delivery, I as InputSource, C as CreateCreditParams, a as CancelCreditParams, b as CreditDrawParams, T as TopUpCreditParams, c as TransactRequest, S as ShieldParams, d as ShieldOutput, e as CrossTreeTransactParams } from './types-RN45XzKc.js';
+
+interface RegistryContext {
+    chainId: bigint;
+    registryAddress: Address;
+    /** Optional explicit wall-clock value in seconds. Equality with deadline is valid. */
+    now?: bigint;
+}
+interface RegistryReceivingKeys {
+    viewingPublicKey: Hex;
+    clueKey: Hex;
+}
+interface AddressRegistration {
+    /** Nonzero 20-byte EVM owner address. ABI calls zero-pad it to bytes32. */
+    walletIdentity: Hex;
+    keys: RegistryReceivingKeys;
+    /** The current registry nonce expected for this operation. */
+    nonce: bigint;
+    deadline: bigint;
+}
+interface RegistrationOptions {
+    update?: boolean;
+    /** Check a separately obtained current nonce before authorizing or encoding. */
+    expectedNonce?: bigint;
+}
+interface RegistrationCalldata {
+    to: Address;
+    callData: Hex;
+    value: 0n;
+    publicInputs: readonly [Hex, Hex, Hex];
+}
+/** Private-wallet authorization request; it contains only the public transcript. */
+declare function registrationAuthorizationRequest(context: RegistryContext, registration: AddressRegistration, options?: RegistrationOptions): WalletAuthorizationRequest;
+declare function registrationTypedData(context: RegistryContext, registration: AddressRegistration, options?: RegistrationOptions): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly WalletAuthorization: readonly [{
+            readonly name: "operation";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "statementHash";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "WalletAuthorization";
+    message: {
+        operation: `0x${string}`;
+        statementHash: `0x${string}`;
+    };
+};
+/** Exact wallet_registration public statement: WID, digest high128, digest low128. */
+declare function registrationPublicInputs(context: RegistryContext, registration: AddressRegistration, options?: RegistrationOptions): readonly [Hex, Hex, Hex];
+/** Encode a relayer-ready call after obtaining a proof; does not sign or broadcast. */
+declare function buildRegistrationCalldata(context: RegistryContext, registration: AddressRegistration, proof: Hex, options?: RegistrationOptions): RegistrationCalldata;
+/** Ethers runner used for registry contract reads. */
+type RegistryReadClient = ContractRunner;
+/** One receivingKeysOf query per short address; RPC failures propagate unchanged. */
+declare function createRegistryReceivingKeyLookup(client: RegistryReadClient, registryAddress: Address): ReceivingKeyLookup;
+
+interface TransactionContext extends DeploymentContext {
+    tokenAddress: Address;
+    now?: bigint;
+}
+declare const FIELD_MODULUS = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+declare const ZERO_ADDRESS: "0x0000000000000000000000000000000000000000";
+declare const ZERO_WORD: Hex;
+declare const EMPTY_PERMIT: {
+    readonly deadline: 0n;
+    readonly v: 0;
+    readonly r: `0x${string}`;
+    readonly s: `0x${string}`;
+};
+declare const EMPTY_FUNDING: FundingParams;
+type FundingInput = Partial<Omit<FundingParams, "permit">> & {
+    permit?: FundingParams["permit"];
+};
+declare function uint(v: bigint | number | string, bits: number, name?: string): bigint;
+declare function field(v: bigint | string, name?: string): bigint;
+declare const word: (v: bigint | string) => Hex;
+declare function dense<T>(v: readonly T[], name: string): readonly T[];
+declare function known(v: object, keys: readonly string[], name?: string): void;
+declare function notes(v: readonly Hex[], name: string): `0x${string}`[];
+declare function envelope(v: Hex, length: number, version?: number): Hex;
+declare function normalizeContext(c: TransactionContext): {
+    chainId: bigint;
+    protocolAddress: Hex;
+    tokenAddress: Hex;
+    now?: bigint;
+};
+declare function checkDeadline(c: TransactionContext, value: bigint): bigint;
+declare function normalizeSources(sources: readonly InputSource[], inputCount: number, capacity: number): {
+    treeId: bigint;
+    merkleRoot: `0x${string}`;
+}[];
+declare const pad: (v: readonly bigint[], n: number) => bigint[];
+declare function normalizeDelivery(value: Delivery, options?: {
+    credit?: boolean;
+    empty?: boolean;
+}): Delivery;
+declare const deliveriesHash: (v: readonly Delivery[]) => Hex;
+declare function normalizeFunding(input?: FundingInput): FundingParams;
+declare function validateFundingSubmission(f: FundingParams, caller?: Address, now?: bigint): void;
+declare const getEIP712Domain: (c: TransactionContext) => {
+    name: string;
+    version: string;
+    chainId: bigint;
+    verifyingContract: Hex;
+};
+declare const fundingFields: readonly [{
+    readonly name: "requestHash";
+    readonly type: "bytes32";
+}, {
+    readonly name: "payer";
+    readonly type: "address";
+}, {
+    readonly name: "amount";
+    readonly type: "uint256";
+}, {
+    readonly name: "sigNonce";
+    readonly type: "uint256";
+}, {
+    readonly name: "deadline";
+    readonly type: "uint256";
+}];
+
+interface ProtocolLog {
+    address: Address;
+    data: Hex;
+    topics: readonly Hex[];
+    transactionHash: Hex;
+    logIndex: number;
+}
+interface CanonicalReceipt {
+    block: CanonicalBlock;
+    transactionHash: Hex;
+    logs: readonly ProtocolLog[];
+    status?: "success" | "reverted";
+}
+interface ChainReader {
+    getChainId(): Promise<bigint>;
+    getCode(address: Address): Promise<Hex>;
+    getBlock(number: bigint): Promise<CanonicalBlock>;
+    getLatestBlockNumber(): Promise<bigint>;
+    getFundingNonce(context: DeploymentContext, payer: Address, block: CanonicalBlock): Promise<bigint>;
+    isKnownRoot(context: DeploymentContext, treeId: bigint, root: Hex, block: CanonicalBlock): Promise<boolean>;
+    getTransaction(hash: Hex): Promise<(TransactionCall & {
+        transactionHash: Hex;
+        from: Address;
+        nonce: bigint;
+    }) | null>;
+    getReceipt(hash: Hex): Promise<CanonicalReceipt | null>;
+    isSpent(context: DeploymentContext, nullifiers: readonly Hex[], block: CanonicalBlock): Promise<readonly boolean[]>;
+}
+interface TransactionCall {
+    to: Address;
+    data: Hex;
+    value: bigint;
+}
+/** Optional deployment provenance queries, independent of token policy. */
+interface FactoryReader {
+    getFactoryInstanceAddress(factory: Address, salt: Hex): Promise<Address>;
+    isFactoryInstance(factory: Address, instance: Address): Promise<boolean>;
+    getInstanceFactory(instance: Address): Promise<Address>;
+}
+
+interface RegistryReader extends Pick<ChainReader, "getChainId" | "getCode" | "getBlock" | "getLatestBlockNumber" | "getTransaction" | "getReceipt"> {
+    getRegistryNonce(context: RegistryContext, walletIdentity: Hex, block: CanonicalBlock): Promise<bigint>;
+}
+interface RegistrationPreparation {
+    wallet: Wallet;
+    reader: RegistryReader;
+    authorization?: WalletAuthorizationProvider;
+    prover?: Prover;
+    deadline?: bigint;
+    update?: boolean;
+}
+type RegistrationStatus = "prepared" | "authorized" | "ready" | "submitted" | "confirmed" | "uncertain" | "failed" | "expired" | "reorged";
+declare class RegistrationOperation {
+    #private;
+    readonly status: RegistrationStatus;
+    private constructor();
+    static prepare(registry: AddressRegistry, options: RegistrationPreparation): Promise<RegistrationOperation>;
+    get id(): string;
+    preview(): {
+        update: boolean;
+        walletIdentity: Hex;
+        keys: RegistryReceivingKeys;
+        nonce: bigint;
+        deadline: bigint;
+        id: string;
+        status: RegistrationStatus;
+        chainId: bigint;
+        registryAddress: `0x${string}`;
+    };
+    authorize(options?: {
+        signal?: AbortSignal;
+    }): Promise<RegistrationOperation>;
+    prove(options?: ProverOptions): Promise<RegistrationOperation>;
+    private call;
+    exportTransaction(): Promise<TransactionCall>;
+    /** Associate a signed/broadcast transaction; ethers owns sending and receipt waiting. */
+    trackTransaction(transactionHash: string): RegistrationOperation;
+    reconcile(options?: {
+        transactionHash?: Hex;
+        signal?: AbortSignal;
+    }): Promise<RegistrationOperation>;
+    toJSON(): {
+        id: string;
+        kind: string;
+        status: RegistrationStatus;
+    };
+}
+
+interface AddressRegistryOptions {
+    lookup?: ReceivingKeyLookup;
+    expectedRuntimeCodeHash?: Hex;
+}
+/** Independent registry deployment and nonce domain, selected by the application. */
+declare class AddressRegistry {
+    #private;
+    readonly context: Readonly<RegistryContext>;
+    readonly expectedRuntimeCodeHash: Hex | undefined;
+    constructor(context: RegistryContext, options?: AddressRegistryOptions);
+    validateDeployment(reader: Pick<RegistryReader, "getChainId" | "getCode">): Promise<void>;
+    prepareRegistration(options: RegistrationPreparation): Promise<RegistrationOperation>;
+    resolve(address: string): Promise<string>;
+    authorization(registration: AddressRegistration, options?: RegistrationOptions): _invisi_labs_core.WalletAuthorizationRequest;
+    publicInputs(registration: AddressRegistration, options?: RegistrationOptions): readonly [`0x${string}`, `0x${string}`, `0x${string}`];
+    buildCall(registration: AddressRegistration, proof: `0x${string}`, options?: RegistrationOptions): RegistrationCalldata;
+}
+
+declare const CREATE_CREDIT_FIELDS: readonly ["token", "sources", "nullifiers", "creditCommitment", "changeCommitment", "owner", "expiry", "deadline"];
+/** Public checks cannot establish ownership or conservation: those are enforced by the proof. */
+declare function validateCreateCreditRequest(c: TransactionContext, p: CreateCreditParams, cs: readonly Delivery[], funding?: FundingInput): {
+    sources: {
+        treeId: bigint;
+        merkleRoot: `0x${string}`;
+    }[];
+    nullifiers: `0x${string}`[];
+    actualCount: number;
+    sourceCount: number;
+    creditCommitment: `0x${string}`;
+    changeCommitment: `0x${string}`;
+    owner: `0x${string}`;
+    expiry: bigint;
+    deadline: bigint;
+    deliveries: Delivery[];
+    funding: FundingParams;
+    chainId: bigint;
+    protocolAddress: Hex;
+    tokenAddress: Hex;
+    now?: bigint;
+};
+declare function createCreditBaseInputs(c: TransactionContext, p: CreateCreditParams, cs: readonly Delivery[], f?: FundingInput): `0x${string}`[];
+declare function createCreditPublicInputs(c: TransactionContext, p: CreateCreditParams, deliveries: readonly Delivery[], funding?: FundingInput): `0x${string}`[];
+declare function createCreditRequestHash(p: CreateCreditParams, cs: readonly Delivery[], f?: FundingInput): Hex;
+declare function encodeCreateCreditTypedData(c: TransactionContext, p: CreateCreditParams, deliveries: readonly Delivery[], funding?: FundingInput): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly WalletAuthorization: readonly [{
+            readonly name: "operation";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "statementHash";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "WalletAuthorization";
+    message: {
+        operation: `0x${string}`;
+        statementHash: `0x${string}`;
+    };
+};
+declare function encodeCreateCreditFundingTypedData(c: TransactionContext, p: CreateCreditParams, cs: readonly Delivery[], f: FundingInput): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: Hex;
+    };
+    primaryType: "FundTransact";
+    types: {
+        FundTransact: readonly [{
+            readonly name: "requestHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "payer";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "sigNonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    message: {
+        requestHash: `0x${string}`;
+        payer: `0x${string}`;
+        amount: bigint;
+        sigNonce: bigint;
+        deadline: bigint;
+    };
+};
+interface BuildCreateCreditCalldataParams {
+    context: TransactionContext;
+    proof: Hex;
+    params: CreateCreditParams;
+    deliveries: readonly Delivery[];
+    funding?: FundingInput;
+    caller?: Address;
+}
+declare function buildCreateCreditCalldata(p: BuildCreateCreditCalldataParams): {
+    data: Hex;
+    approveAmount: bigint;
+};
+/** Frame a raw direct proof from the proving backend for the Credit verifier adapter. */
+declare function encodeCreditProof(proof: Hex): Hex;
+
+declare const CREDIT_DRAW_CAPACITIES: readonly [1, 12, 50, 120];
+declare function selectCreditDrawCircuit(count: number): {
+    name: string;
+    maxSize: 1 | 12 | 50 | 120;
+    publicInputCount: number;
+    totalBits: number;
+};
+declare function validateCreditDrawRequest(c: TransactionContext, p: CreditDrawParams, cs: readonly Delivery[]): {
+    sources: {
+        treeId: bigint;
+        merkleRoot: `0x${string}`;
+    }[];
+    nullifiers: `0x${string}`[];
+    remainderCommitments: `0x${string}`[];
+    recoveryAmounts: `0x${string}`[];
+    expiries: bigint[];
+    spender: `0x${string}`;
+    totalAmount: bigint;
+    deadline: bigint;
+    deliveries: Delivery[];
+    profile: {
+        name: string;
+        maxSize: 1 | 12 | 50 | 120;
+        publicInputCount: number;
+        totalBits: number;
+    };
+    chainId: bigint;
+    protocolAddress: Hex;
+    tokenAddress: Hex;
+    now?: bigint;
+};
+declare function creditDrawBaseInputs(c: TransactionContext, p: CreditDrawParams, cs: readonly Delivery[]): `0x${string}`[];
+declare function validateCancelCreditRequest(c: TransactionContext, p: CancelCreditParams): {
+    source: {
+        treeId: bigint;
+        merkleRoot: `0x${string}`;
+    };
+    nullifier: `0x${string}`;
+    owner: `0x${string}`;
+    amount: bigint;
+    deadline: bigint;
+    chainId: bigint;
+    protocolAddress: Hex;
+    tokenAddress: Hex;
+    now?: bigint;
+};
+declare function cancelCreditBaseInputs(c: TransactionContext, p: CancelCreditParams): `0x${string}`[];
+declare function validateTopUpCreditRequest(c: TransactionContext, p: TopUpCreditParams, cs: readonly Delivery[], funding?: FundingInput): {
+    creation: {
+        sources: {
+            treeId: bigint;
+            merkleRoot: `0x${string}`;
+        }[];
+        nullifiers: `0x${string}`[];
+        actualCount: number;
+        sourceCount: number;
+        creditCommitment: `0x${string}`;
+        changeCommitment: `0x${string}`;
+        owner: `0x${string}`;
+        expiry: bigint;
+        deadline: bigint;
+        deliveries: Delivery[];
+        funding: FundingParams;
+        chainId: bigint;
+        protocolAddress: Hex;
+        tokenAddress: Hex;
+        now?: bigint;
+    };
+    creditSource: {
+        treeId: bigint;
+        merkleRoot: `0x${string}`;
+    };
+    creditNullifier: `0x${string}`;
+    previousExpiry: bigint;
+};
+declare function topUpCreditBaseInputs(c: TransactionContext, p: TopUpCreditParams, cs: readonly Delivery[], f?: FundingInput): `0x${string}`[];
+declare function cancelCreditRequestHash(p: CancelCreditParams): Hex;
+declare function topUpCreditRequestHash(p: TopUpCreditParams, cs: readonly Delivery[], f?: FundingInput): Hex;
+declare function encodeCancelCreditTypedData(c: TransactionContext, p: CancelCreditParams): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly WalletAuthorization: readonly [{
+            readonly name: "operation";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "statementHash";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "WalletAuthorization";
+    message: {
+        operation: `0x${string}`;
+        statementHash: `0x${string}`;
+    };
+};
+declare function encodeTopUpCreditTypedData(c: TransactionContext, p: TopUpCreditParams, deliveries: readonly Delivery[], funding?: FundingInput): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly WalletAuthorization: readonly [{
+            readonly name: "operation";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "statementHash";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "WalletAuthorization";
+    message: {
+        operation: `0x${string}`;
+        statementHash: `0x${string}`;
+    };
+};
+declare function encodeCreditDrawTypedData(c: TransactionContext, p: CreditDrawParams, deliveries: readonly Delivery[]): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly WalletAuthorization: readonly [{
+            readonly name: "operation";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "statementHash";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "WalletAuthorization";
+    message: {
+        operation: `0x${string}`;
+        statementHash: `0x${string}`;
+    };
+};
+declare function creditDrawPublicInputs(c: TransactionContext, p: CreditDrawParams, deliveries: readonly Delivery[]): `0x${string}`[];
+declare function cancelCreditPublicInputs(c: TransactionContext, p: CancelCreditParams): `0x${string}`[];
+declare function topUpCreditPublicInputs(c: TransactionContext, p: TopUpCreditParams, deliveries: readonly Delivery[], funding?: FundingInput): `0x${string}`[];
+declare function encodeTopUpCreditFundingTypedData(c: TransactionContext, p: TopUpCreditParams, cs: readonly Delivery[], f: FundingInput): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: Hex;
+    };
+    primaryType: "FundTransact";
+    types: {
+        FundTransact: readonly [{
+            readonly name: "requestHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "payer";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "sigNonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    message: {
+        requestHash: `0x${string}`;
+        payer: `0x${string}`;
+        amount: bigint;
+        sigNonce: bigint;
+        deadline: bigint;
+    };
+};
+interface BuildCreditDrawCalldataParams {
+    context: TransactionContext;
+    proof: Hex;
+    params: CreditDrawParams;
+    deliveries: readonly Delivery[];
+}
+declare function buildCreditDrawCalldata(p: BuildCreditDrawCalldataParams): {
+    data: Hex;
+    nullifiers: readonly `0x${string}`[];
+    totalAmount: bigint;
+};
+interface BuildCancelCreditCalldataParams {
+    context: TransactionContext;
+    proof: Hex;
+    params: CancelCreditParams;
+}
+declare function buildCancelCreditCalldata(p: BuildCancelCreditCalldataParams): {
+    data: Hex;
+};
+interface BuildTopUpCreditCalldataParams {
+    context: TransactionContext;
+    proof: Hex;
+    params: TopUpCreditParams;
+    deliveries: readonly Delivery[];
+    funding?: FundingInput;
+    caller?: Address;
+}
+declare function buildTopUpCreditCalldata(p: BuildTopUpCreditCalldataParams): {
+    data: Hex;
+    approveAmount: bigint;
+};
+
+declare const TRANSACT_CAPACITIES: readonly [14, 56, 112, 168];
+type TransactCapacity = (typeof TRANSACT_CAPACITIES)[number];
+declare function selectTransactCapacity(inputs: number, outputs: number): TransactCapacity;
+type TransactRequestParams = CrossTreeTransactParams;
+declare function normalizeTransactRequest(c: TransactionContext, p: TransactRequestParams, cs: readonly Delivery[], funding?: FundingInput): {
+    capacity: 14 | 56 | 112 | 168;
+    sources: {
+        treeId: bigint;
+        merkleRoot: `0x${string}`;
+    }[];
+    nullifiers: `0x${string}`[];
+    outputCommitments: `0x${string}`[];
+    inputCount: number;
+    outputCount: number;
+    sourceCount: number;
+    inputTreeIds: bigint[];
+    merkleRoots: bigint[];
+    slotValues: bigint[];
+    deliveries: Delivery[];
+    deliveriesHash: `0x${string}`;
+    withdrawalAddress: `0x${string}`;
+    withdrawalAmount: bigint;
+    deadline: bigint;
+    depositAmount: bigint;
+    depositPayer: `0x${string}`;
+    funding: FundingParams;
+    chainId: bigint;
+    protocolAddress: Hex;
+    tokenAddress: Hex;
+    now?: bigint;
+};
+declare function transactPublicInputs(c: TransactionContext, p: TransactRequestParams, cs: readonly Delivery[], f?: FundingInput): `0x${string}`[];
+declare function encodeTransactTypedData(c: TransactionContext, p: TransactRequestParams, deliveries: readonly Delivery[], f?: FundingInput): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly WalletAuthorization: readonly [{
+            readonly name: "operation";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "statementHash";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "WalletAuthorization";
+    message: {
+        operation: `0x${string}`;
+        statementHash: `0x${string}`;
+    };
+};
+declare function transactFundingRequestHash(proof: Hex, p: TransactRequestParams, cs: readonly Delivery[]): `0x${string}`;
+declare function encodeTransactFundingTypedData(c: TransactionContext, proof: Hex, p: TransactRequestParams, cs: readonly Delivery[], funding: FundingInput): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: Hex;
+    };
+    primaryType: "FundTransact";
+    types: {
+        FundTransact: readonly [{
+            readonly name: "requestHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "payer";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "sigNonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    message: {
+        requestHash: `0x${string}`;
+        payer: `0x${string}`;
+        amount: bigint;
+        sigNonce: bigint;
+        deadline: bigint;
+    };
+};
+interface BuildTransactCalldataParams {
+    context: TransactionContext;
+    proof: Hex;
+    params: TransactRequestParams;
+    deliveries: readonly Delivery[];
+    funding?: FundingInput;
+    caller?: Address;
+}
+declare function buildTransactCalldata(p: BuildTransactCalldataParams): {
+    data: `0x${string}`;
+    capacity: 14 | 56 | 112 | 168;
+    approveAmount: bigint;
+};
+interface BuildTransactAggregateCalldataParams {
+    context: DeploymentContext & {
+        now?: bigint;
+    };
+    proof: Hex;
+    requests: readonly TransactRequest[];
+    caller?: Address;
+}
+declare function buildTransactAggregateCalldata(p: BuildTransactAggregateCalldataParams): {
+    data: Hex;
+    capacity: 14;
+};
+interface BuildShieldCalldataParams {
+    context: TransactionContext;
+    params: ShieldParams;
+    outputs: readonly ShieldOutput[];
+    deliveries: readonly Delivery[];
+    funding: FundingInput;
+    caller?: Address;
+}
+declare function validateShieldRequest(p: BuildShieldCalldataParams): Promise<FundingParams>;
+declare function shieldFundingRequestHash(params: ShieldParams, outputs: readonly ShieldOutput[], cs: readonly Delivery[]): Hex;
+declare function encodeShieldFundingTypedData(p: BuildShieldCalldataParams): Promise<{
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: Hex;
+    };
+    primaryType: "FundShield";
+    types: {
+        FundShield: readonly [{
+            readonly name: "requestHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "payer";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "sigNonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    message: {
+        requestHash: `0x${string}`;
+        payer: `0x${string}`;
+        amount: bigint;
+        sigNonce: bigint;
+        deadline: bigint;
+    };
+}>;
+declare function buildShieldCalldata(p: BuildShieldCalldataParams): Promise<{
+    data: Hex;
+    approveAmount: bigint;
+}>;
+/** Full active user-circuit public inputs: business statement followed by EIP-712 digest limbs. */
+declare function transactUserPublicInputs(c: TransactionContext, p: TransactRequestParams, cs: readonly Delivery[], f?: FundingInput): `0x${string}`[];
+type AggregateMemberInput = Pick<TransactRequest, "params" | "deliveries"> & {
+    funding?: FundingInput;
+};
+/** Atomic aggregate funding binds the member statement rather than the aggregate proof bytes. */
+declare function aggregateMemberRequestHash(c: TransactionContext, r: AggregateMemberInput): Hex;
+/** Router adapter business words (56 per member), not the aggregate circuit statement. */
+declare function aggregatePublicInputs(c: TransactionContext, requests: readonly AggregateMemberInput[]): `0x${string}`[];
+declare function encodeAggregateFundingTypedData(c: TransactionContext, r: AggregateMemberInput): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: Hex;
+    };
+    primaryType: "FundTransact";
+    types: {
+        FundTransact: readonly [{
+            readonly name: "requestHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "payer";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "sigNonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    message: {
+        requestHash: `0x${string}`;
+        payer: `0x${string}`;
+        amount: bigint;
+        sigNonce: bigint;
+        deadline: bigint;
+    };
+};
+
+interface TokenProtocolOptions {
+    expectedRuntimeCodeHash?: Hex;
+}
+/** A token-specific operation binding within a multi-token deployment. Pure builders never sign or submit. */
+declare class TokenProtocol {
+    readonly context: Readonly<TransactionContext>;
+    readonly expectedRuntimeCodeHash: Hex | undefined;
+    constructor(context: TransactionContext, options?: TokenProtocolOptions);
+    validateDeployment(reader: Pick<ChainReader, "getChainId" | "getCode">, options?: {
+        requireRuntimeProfile?: boolean;
+    }): Promise<void>;
+    transact(request: Omit<BuildTransactCalldataParams, "context">): {
+        data: `0x${string}`;
+        capacity: 14 | 56 | 112 | 168;
+        approveAmount: bigint;
+        to: `0x${string}`;
+        value: bigint;
+    };
+    aggregate(request: Omit<BuildTransactAggregateCalldataParams, "context">): {
+        data: Hex;
+        capacity: 14;
+        to: `0x${string}`;
+        value: bigint;
+    };
+    shield(request: Omit<BuildShieldCalldataParams, "context">): Promise<{
+        data: Hex;
+        approveAmount: bigint;
+        to: `0x${string}`;
+        value: bigint;
+    }>;
+    createCredit(request: Omit<BuildCreateCreditCalldataParams, "context">): {
+        data: Hex;
+        approveAmount: bigint;
+        to: `0x${string}`;
+        value: bigint;
+    };
+    drawCredit(request: Omit<BuildCreditDrawCalldataParams, "context">): {
+        data: Hex;
+        nullifiers: readonly `0x${string}`[];
+        totalAmount: bigint;
+        to: `0x${string}`;
+        value: bigint;
+    };
+    cancelCredit(request: Omit<BuildCancelCreditCalldataParams, "context">): {
+        data: Hex;
+        to: `0x${string}`;
+        value: bigint;
+    };
+    topUpCredit(request: Omit<BuildTopUpCreditCalldataParams, "context">): {
+        data: Hex;
+        approveAmount: bigint;
+        to: `0x${string}`;
+        value: bigint;
+    };
+}
+
+interface ProtocolOptions {
+    deployment: ProtocolDeployment;
+}
+/** A multi-token deployment. Asset support is always read from the chain. */
+declare class Protocol {
+    readonly deployment: Readonly<ProtocolDeployment>;
+    readonly context: Readonly<DeploymentContext>;
+    constructor(options: ProtocolOptions);
+    /** Load the selected deployment and verify its contract against Chain RPC before returning. */
+    static fromRpc(rpc: Pick<ProtocolRpcClient, "getDeployment">, provider: Provider, options?: {
+        signal?: AbortSignal;
+    }): Promise<Protocol>;
+    validateDeployment(connection: Provider | (Pick<ChainReader, "getChainId" | "getCode"> & {
+        getProtocolVersion?(address: Address): Promise<bigint>;
+    })): Promise<void>;
+    aggregate(request: Omit<BuildTransactAggregateCalldataParams, "context">): {
+        data: Hex;
+        capacity: 14;
+        to: `0x${string}`;
+        value: bigint;
+    };
+    /** Build an operation context for one asset within this same deployment. */
+    forToken(tokenAddress: Address): TokenProtocol;
+}
+
+interface VerifyNoteCommitmentParams {
+    walletIdentity: `0x${string}`;
+    tokenAddress: `0x${string}`;
+    amount: bigint;
+    nonce: `0x${string}`;
+    noteCommitment: `0x${string}`;
+    chainId: bigint;
+}
+declare function verifyNoteCommitment(params: VerifyNoteCommitmentParams): Promise<boolean>;
+interface VerifyCreditCommitmentParams {
+    chainId: bigint;
+    spenderWalletIdentity: `0x${string}`;
+    ownerWalletIdentity: `0x${string}`;
+    spenderPayout: `0x${string}`;
+    ownerPayout: `0x${string}`;
+    tokenAddress: `0x${string}`;
+    amount: bigint;
+    nonce: bigint;
+    expiry: bigint;
+    creditSharedKey: bigint;
+    /** Server-returned value to verify against the locally recomputed commitment. */
+    creditCommitment: `0x${string}`;
+}
+/**
+ * Hashes the received shared key locally, recomputes the Credit leaf and compares it to the
+ * server-returned value. A mismatch means the server folded a wrong nonce
+ * (or other parameter) — the caller MUST abort and not create a Credit.
+ */
+declare function verifyCreditCommitment(params: VerifyCreditCommitmentParams): Promise<boolean>;
+
+interface BuildWithdrawalCalldataParams extends Omit<BuildTransactCalldataParams, "deliveries"> {
+    sourceNotes: readonly Note[];
+}
+/** Prepare a full public withdrawal whose spending authority is already proven in the supplied proof. */
+declare function buildWithdrawalCalldata(p: BuildWithdrawalCalldataParams): Promise<{
+    data: `0x${string}`;
+    capacity: 14 | 56 | 112 | 168;
+    approveAmount: bigint;
+}>;
+
+interface NoteMembership {
+    note: Note;
+    treeId: bigint;
+    leafIndex: number;
+    path: readonly bigint[];
+}
+interface CreditMembership {
+    state: CreditDeliveryState;
+    treeId: bigint;
+    leafIndex: number;
+    path: readonly bigint[];
+}
+interface TransactWitnessParams extends Omit<BuildTransactCalldataParams, "proof" | "context"> {
+    inputs: readonly NoteMembership[];
+    outputs: readonly Note[];
+    authorization?: AuthorizedStatement;
+    target?: ProofTarget;
+}
+interface CreateCreditWitnessParams {
+    params: CreateCreditParams;
+    deliveries: readonly Delivery[];
+    funding?: FundingInput;
+    inputs: readonly NoteMembership[];
+    state: CreditDeliveryState;
+    change?: Note;
+    authorization: AuthorizedStatement;
+}
+interface DrawCreditWitnessParams {
+    params: CreditDrawParams;
+    deliveries: readonly Delivery[];
+    inputs: readonly CreditMembership[];
+    amounts: readonly bigint[];
+    authorization: AuthorizedStatement;
+}
+interface CancelCreditWitnessParams {
+    params: CancelCreditParams;
+    input: CreditMembership;
+    authorization: AuthorizedStatement;
+}
+interface TopUpCreditWitnessParams extends Omit<CreateCreditWitnessParams, "params"> {
+    params: TopUpCreditParams;
+    previous: CreditMembership;
+}
+/** Local typed assembly for authenticated circuit releases; no network or backend selection. */
+declare class WitnessBuilder {
+    #private;
+    constructor(protocol: TokenProtocol);
+    static statement(circuitName: CircuitName, expectedPublicInputs: readonly Hex[], target?: ProofTarget): ProofStatement;
+    private context;
+    private authority;
+    private membership;
+    private noteLeaf;
+    private creditLeaf;
+    private noteInputs;
+    transact(p: TransactWitnessParams): Promise<ProvingRequest>;
+    private creation;
+    createCredit(p: CreateCreditWitnessParams): Promise<ProvingRequest>;
+    cancelCredit(p: CancelCreditWitnessParams): Promise<ProvingRequest>;
+    drawCredit(p: DrawCreditWitnessParams): Promise<ProvingRequest>;
+    topUpCredit(p: TopUpCreditWitnessParams): Promise<ProvingRequest>;
+    static registration(context: RegistryContext, registration: AddressRegistration, authorization: AuthorizedStatement, options?: RegistrationOptions): Promise<ProvingRequest>;
+}
+
+/**
+ * Query the selected factory. The caller still verifies the returned deployment profile.
+ * Calls `factory.getInstanceAddress(salt)` on-chain.
+ */
+declare function resolveInstanceAddress(client: ContractRunner, factoryAddress: `0x${string}`, salt: `0x${string}`): Promise<`0x${string}`>;
+
+export { type AddressRegistration, AddressRegistry, type AddressRegistryOptions, type AggregateMemberInput, type BuildCancelCreditCalldataParams, type BuildCreateCreditCalldataParams, type BuildCreditDrawCalldataParams, type BuildShieldCalldataParams, type BuildTopUpCreditCalldataParams, type BuildTransactAggregateCalldataParams, type BuildTransactCalldataParams, type BuildWithdrawalCalldataParams, CREATE_CREDIT_FIELDS, CREDIT_DRAW_CAPACITIES, type CancelCreditWitnessParams, type CanonicalReceipt, type ChainReader, type CreateCreditWitnessParams, type CreditMembership, type DrawCreditWitnessParams, EMPTY_FUNDING, EMPTY_PERMIT, FIELD_MODULUS, type FactoryReader, type FundingInput, type NoteMembership, Protocol, type ProtocolLog, type ProtocolOptions, type RegistrationCalldata, RegistrationOperation, type RegistrationOptions, type RegistrationPreparation, type RegistrationStatus, type RegistryContext, type RegistryReadClient, type RegistryReader, type RegistryReceivingKeys, TRANSACT_CAPACITIES, TokenProtocol, type TokenProtocolOptions, type TopUpCreditWitnessParams, type TransactCapacity, type TransactRequestParams, type TransactWitnessParams, type TransactionCall, type TransactionContext, type VerifyCreditCommitmentParams, type VerifyNoteCommitmentParams, WitnessBuilder, ZERO_ADDRESS, ZERO_WORD, aggregateMemberRequestHash, aggregatePublicInputs, buildCancelCreditCalldata, buildCreateCreditCalldata, buildCreditDrawCalldata, buildRegistrationCalldata, buildShieldCalldata, buildTopUpCreditCalldata, buildTransactAggregateCalldata, buildTransactCalldata, buildWithdrawalCalldata, cancelCreditBaseInputs, cancelCreditPublicInputs, cancelCreditRequestHash, checkDeadline, createCreditBaseInputs, createCreditPublicInputs, createCreditRequestHash, createRegistryReceivingKeyLookup, creditDrawBaseInputs, creditDrawPublicInputs, deliveriesHash, dense, encodeAggregateFundingTypedData, encodeCancelCreditTypedData, encodeCreateCreditFundingTypedData, encodeCreateCreditTypedData, encodeCreditDrawTypedData, encodeCreditProof, encodeShieldFundingTypedData, encodeTopUpCreditFundingTypedData, encodeTopUpCreditTypedData, encodeTransactFundingTypedData, encodeTransactTypedData, envelope, field, fundingFields, getEIP712Domain, known, normalizeContext, normalizeDelivery, normalizeFunding, normalizeSources, normalizeTransactRequest, notes, pad, registrationAuthorizationRequest, registrationPublicInputs, registrationTypedData, resolveInstanceAddress, selectCreditDrawCircuit, selectTransactCapacity, shieldFundingRequestHash, topUpCreditBaseInputs, topUpCreditPublicInputs, topUpCreditRequestHash, transactFundingRequestHash, transactPublicInputs, transactUserPublicInputs, uint, validateCancelCreditRequest, validateCreateCreditRequest, validateCreditDrawRequest, validateFundingSubmission, validateShieldRequest, validateTopUpCreditRequest, verifyCreditCommitment, verifyNoteCommitment, word };