@continuumdao/ctm-mpc-defi 0.2.60 → 0.2.61

package/dist/protocols/evm/railgun/index.d.ts

@@ -1,5 +1,5 @@
 import { Address } from 'viem';
-import { TXIDVersion, NetworkName, TransactionGasDetails } from '@railgun-community/shared-models';
+import { TXIDVersion, NetworkName, TransactionGasDetails, RailgunBalancesEvent } from '@railgun-community/shared-models';
 
 /** Aligns with app NonEvmChainType + 'evm'. Extend as mpc-auth adds chains. */
 type ChainCategory = 'evm' | 'solana' | 'near' | 'sui' | 'ton' | 'stellar';
@@ -226,8 +226,8 @@ type AllowanceReader = (args: {
 }) => Promise<bigint>;
 declare function setRailgunPopulateShieldForTests(fn: PopulateShield | null): void;
 declare function setRailgunAllowanceReaderForTests(fn: AllowanceReader | null): void;
-/** Railgun hashes the 65-byte personal_sign. populateShield rejects the raw signature. */
-declare function shieldPrivateKeyFromSignature(signature: string): `0x${string}`;
+/** Railgun hashes the 65-byte personal_sign. The node often returns r||s without the recovery byte. */
+declare function shieldPrivateKeyFromSignature(signature: string, executorAddress?: string): Promise<`0x${string}`>;
 declare function buildEvmMultisignBodyWethUnwrap(args: {
     keyGen: KeyGenSubset;
     executorAddress: Address | string;
@@ -249,8 +249,65 @@ type RailgunPrivateActionArgs = {
     amountWei: string;
     recipientAddress: string;
     memoText?: string;
+    onBroadcasterSearch?: () => void;
+    onBroadcasterNote?: (note: string) => void;
     onProofProgress?: (progress: number) => void;
+    onProofStatusRefresh?: () => void;
+    broadcasterFeesId?: string;
 };
+/** Railgun replaces the note-check text with a short sentence. Keep the required amount and balance when they are still attached. */
+declare function railgunDetailedError(err: unknown): string;
+/** The broadcaster accepted the proof request and asked for a fresh proof-of-innocence status. */
+declare function broadcasterAskedToRefreshProofStatus(err: unknown): boolean;
+declare function broadcasterRefusedForGas(err: unknown): boolean;
+/** A fee message can take about a minute to arrive after the spending-wallet sync. */
+declare const BROADCASTER_PROOF_WAIT_MS: number;
+/** Same margin the Waku client uses before it treats a fee as expired. */
+declare const BROADCASTER_FEE_MIN_REMAINING_MS = 40000;
+declare function broadcasterFeeStillValid(expiration: number, now?: number): boolean;
+type RailgunBroadcasterChoice = {
+    feesId: string;
+    railgunAddress: string;
+    feeWei: string;
+    ratio: string | null;
+    coversGas: boolean;
+    reliability: number;
+    expiration: number;
+    tokenDecimals: number;
+};
+declare function listRailgunBroadcasters(args: {
+    chainId: number;
+    rpcUrl: string;
+    chainDetail: EvmChainDetail;
+    tokenAddress: string;
+    kind: string;
+}): Promise<RailgunBroadcasterChoice[]>;
+declare function quoteRailgunBroadcasterFee(args: {
+    kind: 'transfer' | 'unshield';
+    chainId: number;
+    rpcUrl: string;
+    chainDetail: EvmChainDetail;
+    tokenAddress: string;
+    amountWei: string;
+    recipientAddress: string;
+    memoText?: string;
+    walletId: string;
+    encryptionKey: string;
+}): Promise<{
+    feeWei: string;
+    tokenAddress: string;
+}>;
+/** Broadcaster fee from the live fee rate and chain gas. A view-only wallet cannot run the proof estimate. */
+declare function quoteRailgunBroadcasterFeeRate(args: {
+    kind: 'transfer' | 'unshield';
+    chainId: number;
+    rpcUrl: string;
+    chainDetail: EvmChainDetail;
+    tokenAddress: string;
+}): Promise<{
+    feeWei: string;
+    tokenAddress: string;
+}>;
 declare function railgunPrivateTransfer(args: RailgunPrivateActionArgs): Promise<{
     txHash: string;
 }>;
@@ -258,6 +315,36 @@ declare function railgunUnshield(args: RailgunPrivateActionArgs): Promise<{
     txHash: string;
 }>;
 
+type RailgunFeeKind = 'shield' | 'transfer' | 'unshield';
+type RailgunFeeQuote = {
+    kind: RailgunFeeKind;
+    amountWei: string;
+    protocolFeeBasisPoints: string;
+    protocolFeeWei: string;
+    receivedWei: string;
+    broadcasterFeeWei: string;
+    broadcasterTokenAddress: string;
+    totalDebitWei: string;
+    broadcasterError?: string;
+};
+declare function railgunProtocolFee(amount: bigint, basisPoints: bigint): {
+    fee: bigint;
+    received: bigint;
+};
+declare function clearRailgunFeeCache(): void;
+declare function quoteRailgunFee(args: {
+    kind: RailgunFeeKind;
+    chainId: number;
+    rpcUrl: string;
+    chainDetail?: EvmChainDetail;
+    tokenAddress: string;
+    amountWei: string;
+    recipientAddress?: string;
+    memoText?: string;
+    walletId?: string;
+    encryptionKey?: string;
+}): Promise<RailgunFeeQuote>;
+
 declare function createRailgunBrowserWallet(args: {
     encryptionKey: string;
     mnemonic: string;
@@ -272,25 +359,72 @@ declare function openRailgunViewOnlyWallet(args: {
     encryptionKey: string;
     shareableViewingKey: string;
     chainId: number;
+    keyGenId?: string;
 }): Promise<{
     walletId: string;
     railgunAddress: string;
 }>;
 declare function discardRailgunWallet(walletId: string): Promise<void>;
 declare function railgunAddressIsValid(address: string): Promise<boolean>;
+declare function recordRailgunWalletBalance(event: RailgunBalancesEvent): void;
+declare function railgunWalletBalanceSnapshot(walletId: string, chainId: number): RailgunPrivateBalanceRow[];
+declare function clearRailgunWalletBalances(): void;
 /** History sync emits Complete on the merkletree callback. It does not emit the wallet event awaitWalletScan waits for. */
 declare function utxoScanTerminalStatus(scanStatus: string): 'done' | 'failed' | 'pending';
+/** After the note scan reports 100%, wait this long for the spendable-note check, then save the balances already decrypted. */
+declare const RAILGUN_TXID_WAIT_AFTER_NOTES_MS = 45000;
+/** After the history walk, sync blocks that were mined while it was running. A shield in that gap is otherwise left out. */
+declare const RAILGUN_CATCH_UP_MS = 120000;
+/** The first merkletree walk can take much longer than the catch-up window. Give up only when progress itself stops. */
+declare const RAILGUN_MERKLETREE_STALL_MS: number;
+declare const RAILGUN_SCAN_BEHIND_NOTE = "The shielded balance is saved. The newest blocks did not finish syncing, so a shield that just landed may be missing until the next scan.";
+declare const RAILGUN_SCAN_STOPPED_NOTE = "The note scan stopped before it reached the latest block. The shielded balance is unchanged until a scan finishes.";
+/** A catch-up timer that expires while leaves are still arriving has not finished the tree. */
+declare function merkletreeScanStillRunning(args: {
+    sawProgress: boolean;
+    notesFinished: boolean;
+    terminal: 'done' | 'failed' | 'pending';
+}): boolean;
+declare function railgunScanRecord(merkletree: 'done' | 'failed', balanceCount: number, caughtUp: boolean): {
+    scanStatus: RailgunScanStatus;
+    notes: string;
+};
+declare function balancesToKeepAfterNoteScan(decrypted: RailgunPrivateBalanceRow[], afterRefresh: RailgunPrivateBalanceRow[], previous: RailgunPrivateBalanceRow[]): RailgunPrivateBalanceRow[];
+declare const RAILGUN_SPEND_SCAN_STOPPED = "The spending wallet did not finish scanning private notes.";
+/**
+ * History complete is emitted at 100% after this wallet's notes are decrypted.
+ * The decrypt-complete wallet event is deferred until after that, so 100% is the
+ * signal to build the proof. Give up only when leaves stop arriving before then.
+ */
+declare function spendingScanReadyAfterHistory(progress: number, scanStatus: string): boolean;
+declare function spendingNoteScanGaveUp(args: {
+    walletReady: boolean;
+    sawProgress: boolean;
+    notesFinished: boolean;
+    msSinceProgress: number;
+    msWaitingForDecrypt: number | null;
+}): boolean;
+/** Decrypt this spending wallet's notes before a proof. A view-only scan does not fill this wallet. */
+declare function scanSpendingWalletNotes(args: {
+    chainId: number;
+    rpcUrl: string;
+    walletId: string;
+    onProgress?: (progress: number) => void;
+}): Promise<void>;
 declare function scanRailgunPrivateBalances(args: {
     chainId: number;
     rpcUrl: string;
     walletId: string;
     onProgress?: (progress: number) => void;
+    onBalances?: (balances: RailgunPrivateBalanceRow[]) => void;
 }): Promise<{
     scanStatus: RailgunScanStatus;
     balances: RailgunPrivateBalanceRow[];
+    settled: boolean;
+    notes: string;
 }>;
 
 declare const RAILGUN_PROTOCOL_ID = "railgun";
 declare const railgunProtocolModule: ProtocolModule;
 
-export { RAILGUN_CTM_DISABLED_MESSAGE, RAILGUN_CTM_ENABLED, RAILGUN_POPULAR_ASSET_LIMIT, RAILGUN_PROTOCOL_ID, RAILGUN_WALLET_LOCKED_MESSAGE, type RailgunNetworkRow, type RailgunNetworkSource, type RailgunPrivateActionArgs, type RailgunPrivateBalanceRow, type RailgunPrivateBalanceSnapshot, type RailgunScanStatus, type RailgunShieldArgs, type RailgunWalletSession, type ShieldCommitmentLike, assertRailgunCtmAllowed, buildEvmMultisignBodyRailgunShield, buildEvmMultisignBodyWethUnwrap, clearRailgunNetworkCache, clearRailgunPopularAssetCache, clearRailgunPrivateBalanceSnapshots, commitmentsFromShieldIndex, createRailgunBrowserWallet, discardRailgunWallet, getRailgunWalletSession, loadRailgunNetworks, loadRailgunPopularAssets, loadRailgunSupportedChainIds, openRailgunViewOnlyWallet, publishRailgunPrivateBalanceSnapshot, railgunAddressIsValid, railgunFetchPopularAssets, railgunFetchPrivateBalances, railgunFetchPrivateBalancesSummary, railgunNetworkByChainId, railgunPrivateTransfer, railgunProtocolModule, railgunShareableViewingKey, railgunUnshield, rankPopularShieldTokens, readRailgunPrivateBalanceSnapshot, requireRailgunWalletSession, scanRailgunPrivateBalances, selectRailgunNetworks, setRailgunAllowanceReaderForTests, setRailgunPopulateShieldForTests, setRailgunShieldLogReaderForTests, setRailgunWalletSession, shieldIndexEndpoint, shieldPrivateKeyFromSignature, unlockRailgunBrowserWallet, utxoScanTerminalStatus };
+export { BROADCASTER_FEE_MIN_REMAINING_MS, BROADCASTER_PROOF_WAIT_MS, RAILGUN_CATCH_UP_MS, RAILGUN_CTM_DISABLED_MESSAGE, RAILGUN_CTM_ENABLED, RAILGUN_MERKLETREE_STALL_MS, RAILGUN_POPULAR_ASSET_LIMIT, RAILGUN_PROTOCOL_ID, RAILGUN_SCAN_BEHIND_NOTE, RAILGUN_SCAN_STOPPED_NOTE, RAILGUN_SPEND_SCAN_STOPPED, RAILGUN_TXID_WAIT_AFTER_NOTES_MS, RAILGUN_WALLET_LOCKED_MESSAGE, type RailgunBroadcasterChoice, type RailgunFeeKind, type RailgunFeeQuote, type RailgunNetworkRow, type RailgunNetworkSource, type RailgunPrivateActionArgs, type RailgunPrivateBalanceRow, type RailgunPrivateBalanceSnapshot, type RailgunScanStatus, type RailgunShieldArgs, type RailgunWalletSession, type ShieldCommitmentLike, assertRailgunCtmAllowed, balancesToKeepAfterNoteScan, broadcasterAskedToRefreshProofStatus, broadcasterFeeStillValid, broadcasterRefusedForGas, buildEvmMultisignBodyRailgunShield, buildEvmMultisignBodyWethUnwrap, clearRailgunFeeCache, clearRailgunNetworkCache, clearRailgunPopularAssetCache, clearRailgunPrivateBalanceSnapshots, clearRailgunWalletBalances, commitmentsFromShieldIndex, createRailgunBrowserWallet, discardRailgunWallet, getRailgunWalletSession, listRailgunBroadcasters, loadRailgunNetworks, loadRailgunPopularAssets, loadRailgunSupportedChainIds, merkletreeScanStillRunning, openRailgunViewOnlyWallet, publishRailgunPrivateBalanceSnapshot, quoteRailgunBroadcasterFee, quoteRailgunBroadcasterFeeRate, quoteRailgunFee, railgunAddressIsValid, railgunDetailedError, railgunFetchPopularAssets, railgunFetchPrivateBalances, railgunFetchPrivateBalancesSummary, railgunNetworkByChainId, railgunPrivateTransfer, railgunProtocolFee, railgunProtocolModule, railgunScanRecord, railgunShareableViewingKey, railgunUnshield, railgunWalletBalanceSnapshot, rankPopularShieldTokens, readRailgunPrivateBalanceSnapshot, recordRailgunWalletBalance, requireRailgunWalletSession, scanRailgunPrivateBalances, scanSpendingWalletNotes, selectRailgunNetworks, setRailgunAllowanceReaderForTests, setRailgunPopulateShieldForTests, setRailgunShieldLogReaderForTests, setRailgunWalletSession, shieldIndexEndpoint, shieldPrivateKeyFromSignature, spendingNoteScanGaveUp, spendingScanReadyAfterHistory, unlockRailgunBrowserWallet, utxoScanTerminalStatus };