@veil-cash/sdk 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -99,6 +99,7 @@ interface NetworkAddresses {
     usdcPool: `0x${string}`;
     usdcQueue: `0x${string}`;
     usdcToken: `0x${string}`;
+    forwarderFactory: `0x${string}`;
     chainId: number;
     relayUrl: string;
 }
@@ -349,6 +350,124 @@ interface UtxoSelectionResult {
     /** Change amount to return to sender (wei) */
     changeAmount: bigint;
 }
+/**
+ * Supported subaccount assets
+ */
+type SubaccountAsset = 'eth' | 'usdc';
+/**
+ * Deterministically derived subaccount slot metadata
+ */
+interface SubaccountSlot {
+    slot: number;
+    childOwner: `0x${string}`;
+    childDepositKey: string;
+    salt: `0x${string}`;
+    forwarderAddress: `0x${string}`;
+}
+/**
+ * Relay-backed forwarder deploy request
+ */
+interface SubaccountDeployRequest {
+    rootPrivateKey: `0x${string}`;
+    slot: number;
+    relayUrl?: string;
+    rpcUrl?: string;
+}
+/**
+ * Relay-backed forwarder sweep request
+ */
+interface SubaccountSweepRequest {
+    forwarderAddress: `0x${string}`;
+    asset: SubaccountAsset;
+    relayUrl?: string;
+}
+/**
+ * Relay response for subaccount deploy/sweep operations
+ */
+interface SubaccountRelayResult {
+    success: boolean;
+    transactionHash: string;
+    blockNumber: string;
+    gasUsed: string;
+    status: string;
+    network: string;
+}
+/**
+ * Human-readable and wei-denominated balance
+ */
+interface SubaccountAssetBalance {
+    balance: string;
+    balanceWei: string;
+}
+/**
+ * Forwarder wallet balances for both supported assets
+ */
+interface SubaccountBalances {
+    eth: SubaccountAssetBalance;
+    usdc: SubaccountAssetBalance;
+}
+/**
+ * Queue status for a specific asset
+ */
+interface SubaccountQueueStatus {
+    asset: SubaccountAsset;
+    queueBalance: string;
+    queueBalanceWei: string;
+    pendingCount: number;
+    pendingDeposits: PendingDeposit[];
+}
+/**
+ * Combined subaccount status result
+ */
+interface SubaccountStatusResult {
+    slot: SubaccountSlot;
+    deployed: boolean;
+    balances: SubaccountBalances;
+    queues: {
+        eth: SubaccountQueueStatus;
+        usdc: SubaccountQueueStatus;
+    };
+}
+/**
+ * Typed data for forwarder withdraw signing
+ */
+interface SubaccountWithdrawTypedData {
+    domain: {
+        name: 'VeilForwarder';
+        version: string;
+        chainId: number;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        Withdraw: Array<{
+            name: 'token' | 'to' | 'amount' | 'nonce' | 'deadline';
+            type: 'address' | 'uint256';
+        }>;
+    };
+    primaryType: 'Withdraw';
+    message: {
+        token: `0x${string}`;
+        to: `0x${string}`;
+        amount: bigint;
+        nonce: bigint;
+        deadline: bigint;
+    };
+}
+/**
+ * Built recovery transaction and signing metadata
+ */
+interface SubaccountRecoveryResult {
+    transaction: TransactionData;
+    forwarderAddress: `0x${string}`;
+    asset: SubaccountAsset;
+    amount: string;
+    amountWei: string;
+    nonce: string;
+    deadline: string;
+    recipient: `0x${string}`;
+    tokenAddress: `0x${string}`;
+    signature: `0x${string}`;
+}
 
 /**
  * Veil Keypair class
@@ -1015,6 +1134,10 @@ declare function selectCircuit(inputCount: number): string;
  * Contract addresses for Base mainnet
  */
 declare const ADDRESSES: NetworkAddresses;
+/**
+ * Veil forwarder EIP-712 contract version
+ */
+declare const FORWARDER_CONTRACT_VERSION: "1";
 /**
  * Pool configuration (decimals, symbols, etc.)
  */
@@ -1049,6 +1172,11 @@ declare function getPoolAddress(pool: RelayPool): `0x${string}`;
  * @returns Queue contract address
  */
 declare function getQueueAddress(pool: RelayPool): `0x${string}`;
+/**
+ * Get the forwarder factory contract address
+ * @returns Forwarder factory address for Base mainnet
+ */
+declare function getForwarderFactoryAddress(): `0x${string}`;
 /**
  * Get Relay URL
  * @returns Relay URL for Base mainnet
@@ -2142,6 +2270,363 @@ declare const ERC20_ABI: readonly [{
     readonly stateMutability: "view";
     readonly type: "function";
 }];
+/**
+ * Veil Forwarder Factory ABI
+ */
+declare const FORWARDER_FACTORY_ABI: readonly [{
+    readonly inputs: readonly [];
+    readonly name: "CONTRACT_VERSION";
+    readonly outputs: readonly [{
+        readonly internalType: "string";
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "_salt";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "bytes";
+        readonly name: "_childDepositKey";
+        readonly type: "bytes";
+    }, {
+        readonly internalType: "address";
+        readonly name: "_owner";
+        readonly type: "address";
+    }];
+    readonly name: "computeAddress";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "_salt";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "bytes";
+        readonly name: "_childDepositKey";
+        readonly type: "bytes";
+    }, {
+        readonly internalType: "address";
+        readonly name: "_owner";
+        readonly type: "address";
+    }];
+    readonly name: "deploy";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "forwarder";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "relayer";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "veilEntry";
+    readonly outputs: readonly [{
+        readonly internalType: "address payable";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "usdc";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "owner";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];
+/**
+ * Veil Forwarder ABI
+ */
+declare const FORWARDER_ABI: readonly [{
+    readonly inputs: readonly [];
+    readonly name: "CONTRACT_VERSION";
+    readonly outputs: readonly [{
+        readonly internalType: "string";
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "_token";
+        readonly type: "address";
+    }, {
+        readonly internalType: "address";
+        readonly name: "_to";
+        readonly type: "address";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "_amount";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "_nonce";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "_deadline";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "bytes";
+        readonly name: "_signature";
+        readonly type: "bytes";
+    }];
+    readonly name: "withdraw";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly name: "usedNonces";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "owner";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "factory";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "childDepositKey";
+    readonly outputs: readonly [{
+        readonly internalType: "bytes";
+        readonly name: "";
+        readonly type: "bytes";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "entry";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "usdc";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "sweepETH";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "sweepUSDC";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "eip712Domain";
+    readonly outputs: readonly [{
+        readonly internalType: "bytes1";
+        readonly name: "fields";
+        readonly type: "bytes1";
+    }, {
+        readonly internalType: "string";
+        readonly name: "name";
+        readonly type: "string";
+    }, {
+        readonly internalType: "string";
+        readonly name: "version";
+        readonly type: "string";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "address";
+        readonly name: "verifyingContract";
+        readonly type: "address";
+    }, {
+        readonly internalType: "bytes32";
+        readonly name: "salt";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "uint256[]";
+        readonly name: "extensions";
+        readonly type: "uint256[]";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly type: "error";
+    readonly name: "ZeroAddress";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ZeroAmount";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidDepositKey";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "NotRelayer";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "NoETHBalance";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "NoTokenBalance";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "TokenApproveFailed";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ETHTransferFailed";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "NonceUsed";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "Unauthorized";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "DeadlineExpired";
+    readonly inputs: readonly [];
+}];
+
+declare const MAX_SUBACCOUNT_SLOTS = 3;
+declare function deriveSubaccountChildPrivateKey(rootPrivateKey: string, slot: number): `0x${string}`;
+declare function deriveSubaccountSalt(rootPrivateKey: string, slot: number): `0x${string}`;
+declare function deriveSubaccountChildOwner(childPrivateKey: string): `0x${string}`;
+declare function deriveSubaccountChildDepositKey(childPrivateKey: string): string;
+declare function predictSubaccountForwarder(options: {
+    salt: `0x${string}`;
+    childDepositKey: string;
+    childOwner: `0x${string}`;
+    rpcUrl?: string;
+}): Promise<`0x${string}`>;
+declare function deriveSubaccountSlot(options: {
+    rootPrivateKey: `0x${string}`;
+    slot: number;
+    rpcUrl?: string;
+}): Promise<SubaccountSlot>;
+declare function isSubaccountForwarderDeployed(options: {
+    forwarderAddress: `0x${string}`;
+    rpcUrl?: string;
+}): Promise<boolean>;
+declare function deploySubaccountForwarder(options: SubaccountDeployRequest): Promise<SubaccountRelayResult>;
+declare function sweepSubaccountForwarder(options: SubaccountSweepRequest): Promise<SubaccountRelayResult>;
+declare function getSubaccountStatus(options: {
+    rootPrivateKey: `0x${string}`;
+    slot: number;
+    rpcUrl?: string;
+}): Promise<SubaccountStatusResult>;
+declare function buildSubaccountWithdrawTypedData(options: {
+    forwarderAddress: `0x${string}`;
+    token: `0x${string}`;
+    to: `0x${string}`;
+    amount: bigint;
+    nonce: bigint;
+    deadline: bigint;
+}): SubaccountWithdrawTypedData;
+declare function signSubaccountWithdraw(options: {
+    childPrivateKey: `0x${string}`;
+    typedData: SubaccountWithdrawTypedData;
+}): Promise<`0x${string}`>;
+declare function isSubaccountWithdrawNonceUsed(options: {
+    forwarderAddress: `0x${string}`;
+    nonce: bigint | number;
+    rpcUrl?: string;
+}): Promise<boolean>;
+declare function findNextSubaccountWithdrawNonce(options: {
+    forwarderAddress: `0x${string}`;
+    startNonce?: bigint | number;
+    maxScan?: bigint | number;
+    rpcUrl?: string;
+}): Promise<bigint>;
+declare function buildSubaccountRecoveryTx(options: {
+    rootPrivateKey: `0x${string}`;
+    slot: number;
+    asset: SubaccountAsset;
+    to: `0x${string}`;
+    amount: string;
+    nonce?: bigint | number;
+    deadline?: bigint | number;
+    rpcUrl?: string;
+}): Promise<SubaccountRecoveryResult>;
 
 /**
  * Crypto utilities for Veil SDK
@@ -2212,4 +2697,4 @@ declare function getExtDataHash(extData: ExtDataInput): bigint;
  */
 declare function shuffle<T>(array: T[]): T[];
 
-export { ADDRESSES, type BuildTransferProofOptions, type BuildWithdrawProofOptions, CIRCUIT_CONFIG, type DepositTxOptions, ENTRY_ABI, ERC20_ABI, type EncryptedMessage, type ExtData, type ExtDataInput, FIELD_SIZE, Keypair, MERKLE_TREE_HEIGHT, type MessageSigner, type NetworkAddresses, POOL_ABI, POOL_CONFIG, type PendingDeposit, type PoolConfig, type PrepareTransactionParams, type PrivateBalanceResult, type ProgressCallback, type ProofArgs, type ProofBuildResult, type ProofInput, QUEUE_ABI, type QueueBalanceResult, type RegisterTxOptions, RelayError, type RelayErrorResponse, type RelayExtData, type RelayMetadata, type RelayPool, type RelayProofArgs, type RelayRequest, type RelayResponse, type RelayType, type SubmitRelayOptions, type Token, type TransactionData, type TransactionResult, type TransferResult, Utxo, type UtxoInfo, type UtxoParams, type UtxoSelectionResult, VEIL_SIGNED_MESSAGE, type WithdrawResult, buildApproveUSDCTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx, buildDepositUSDCTx, buildMerkleTree, buildRegisterTx, buildTransferProof, buildWithdrawProof, checkRecipientRegistration, checkRelayHealth, getAddresses, getExtDataHash, getMerklePath, getPoolAddress, getPrivateBalance, getQueueAddress, getQueueBalance, getRelayInfo, getRelayUrl, mergeUtxos, packEncryptedMessage, poseidonHash, poseidonHash2, prepareTransaction, prove, randomBN, selectCircuit, selectUtxosForWithdraw, shuffle, submitRelay, toBuffer, toFixedHex, transfer, unpackEncryptedMessage, withdraw };
+export { ADDRESSES, type BuildTransferProofOptions, type BuildWithdrawProofOptions, CIRCUIT_CONFIG, type DepositTxOptions, ENTRY_ABI, ERC20_ABI, type EncryptedMessage, type ExtData, type ExtDataInput, FIELD_SIZE, FORWARDER_ABI, FORWARDER_CONTRACT_VERSION, FORWARDER_FACTORY_ABI, Keypair, MAX_SUBACCOUNT_SLOTS, MERKLE_TREE_HEIGHT, type MessageSigner, type NetworkAddresses, POOL_ABI, POOL_CONFIG, type PendingDeposit, type PoolConfig, type PrepareTransactionParams, type PrivateBalanceResult, type ProgressCallback, type ProofArgs, type ProofBuildResult, type ProofInput, QUEUE_ABI, type QueueBalanceResult, type RegisterTxOptions, RelayError, type RelayErrorResponse, type RelayExtData, type RelayMetadata, type RelayPool, type RelayProofArgs, type RelayRequest, type RelayResponse, type RelayType, type SubaccountAsset, type SubaccountAssetBalance, type SubaccountBalances, type SubaccountDeployRequest, type SubaccountQueueStatus, type SubaccountRecoveryResult, type SubaccountRelayResult, type SubaccountSlot, type SubaccountStatusResult, type SubaccountSweepRequest, type SubaccountWithdrawTypedData, type SubmitRelayOptions, type Token, type TransactionData, type TransactionResult, type TransferResult, Utxo, type UtxoInfo, type UtxoParams, type UtxoSelectionResult, VEIL_SIGNED_MESSAGE, type WithdrawResult, buildApproveUSDCTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx, buildDepositUSDCTx, buildMerkleTree, buildRegisterTx, buildSubaccountRecoveryTx, buildSubaccountWithdrawTypedData, buildTransferProof, buildWithdrawProof, checkRecipientRegistration, checkRelayHealth, deploySubaccountForwarder, deriveSubaccountChildDepositKey, deriveSubaccountChildOwner, deriveSubaccountChildPrivateKey, deriveSubaccountSalt, deriveSubaccountSlot, findNextSubaccountWithdrawNonce, getAddresses, getExtDataHash, getForwarderFactoryAddress, getMerklePath, getPoolAddress, getPrivateBalance, getQueueAddress, getQueueBalance, getRelayInfo, getRelayUrl, getSubaccountStatus, isSubaccountForwarderDeployed, isSubaccountWithdrawNonceUsed, mergeUtxos, packEncryptedMessage, poseidonHash, poseidonHash2, predictSubaccountForwarder, prepareTransaction, prove, randomBN, selectCircuit, selectUtxosForWithdraw, shuffle, signSubaccountWithdraw, submitRelay, sweepSubaccountForwarder, toBuffer, toFixedHex, transfer, unpackEncryptedMessage, withdraw };