@kohaku-eth/tornado-cash 0.0.1 → 0.0.2-alpha.10

package/README.md

@@ -0,0 +1,12 @@
+# @kohaku-eth/tornado-cash
+
+> [!IMPORTANT]
+> THIS PACKAGE IS NOT READY FOR PRODUCTION USE AND CONTAINS UNAUDITED CODE. USE WITH CAUTION AND ENTIRELY AT YOUR OWN RISK. POSSIBILITY OF BREAKING CHANGES IN SUBSEQUENT VERSIONS.
+
+Cross-platform Tornado Cash Typescript SDK with support for kohaku's standard interfaces.
+
+## Installation
+
+```sh
+pnpm add @kohaku-eth/tornado-cash
+```

package/dist/index.d.ts

@@ -0,0 +1,528 @@
+import { Broadcaster } from '@kohaku-eth/plugins/broadcaster';
+import { Host, ChainId, Storage, PrivateOperation, PublicOperation, AssetAmount, ERC20AssetId, PluginInstance, AccountId } from '@kohaku-eth/plugins';
+import { combineReducers } from '@reduxjs/toolkit';
+import { ParseAbiItem, SignedAuthorization, Hash, Address as Address$2 } from 'viem';
+import { TxData } from '@kohaku-eth/provider';
+import { Address as Address$1 } from 'ox/Address';
+
+type Nullifier$1 = bigint & {};
+type NullifierHash = bigint & {};
+type Address = bigint & {};
+type Commitment$1 = bigint & {};
+interface IContract {
+    address: Address;
+}
+interface IScrapeableContract extends IContract {
+    deploymentBlock: bigint;
+}
+
+interface Secret {
+    nullifier: Nullifier$1;
+    salt: bigint;
+    commitment: Commitment$1;
+    nullifierHash: NullifierHash;
+}
+type BaseDeriveSecretParams = {
+    poolAddress: bigint;
+    chainId: bigint;
+};
+type DeriveDepositSecretParams = BaseDeriveSecretParams & {
+    depositIndex: number;
+};
+interface ISecretManager {
+    getDepositSecrets: (params: DeriveDepositSecretParams) => Promise<Secret>;
+    deriveEphemeralSigner: (params: DeriveDepositSecretParams) => Promise<`0x${string}`>;
+}
+interface SecretManagerParams {
+    host: Pick<Host, 'keystore'>;
+    accountIndex?: number;
+}
+declare function SecretManager({ host: { keystore }, accountIndex }: SecretManagerParams): Promise<ISecretManager>;
+
+interface IRelayerStatusResponse {
+    currentQueue: number;
+    netId: number;
+    rewardAccount: string;
+    version: string;
+    tornadoServiceFee: number;
+    ethPrices: Record<string, string>;
+}
+interface ITornadoWithdrawRequest {
+    proof: `0x${string}`;
+    args: [`0x${string}`, `0x${string}`, `0x${string}`, `0x${string}`, `0x${string}`, `0x${string}`];
+    contract: `0x${string}`;
+}
+interface ITornadoWithdrawResponse {
+    id: string;
+}
+interface IRelayerClient {
+    getStatus(hostname: string): Promise<IRelayerStatusResponse>;
+    withdraw(relayerUrl: string, body: ITornadoWithdrawRequest): Promise<ITornadoWithdrawResponse>;
+}
+
+interface InstanceRegistryConfig extends IScrapeableContract {
+    lastDeployedOnBlock?: bigint;
+}
+interface ProtocolConfigState {
+    chainId: bigint;
+    ensSubdomainKey: string;
+    instanceRegistry: InstanceRegistryConfig;
+    relayerRegistry: IScrapeableContract;
+    aggregator: IContract;
+}
+
+type RootState = ReturnType<ReturnType<typeof combineReducers<typeof reducers>>>;
+type PublicRootState = Omit<RootState, 'userSecrets'>;
+
+interface IBaseEvent {
+    blockNumber: bigint;
+    transactionHash: bigint;
+}
+interface IPoolEvent extends IBaseEvent {
+    pool: Address;
+}
+interface IDepositEvent extends IPoolEvent {
+    commitment: Commitment$1;
+    leafIndex: number;
+    timestamp: bigint;
+}
+interface IWithdrawalEvent extends IPoolEvent {
+    to: Address;
+    nullifierHash: NullifierHash;
+    relayer: Address;
+    fee: bigint;
+}
+type IRawDepositEvent = Omit<IDepositEvent, 'pool'>;
+type IRawWithdrawalEvent = Omit<IWithdrawalEvent, 'pool'>;
+interface IRelayerRegisteredEvent extends IBaseEvent {
+    relayer: bigint;
+    ensName: string;
+    relayerAddress: Address;
+    stakedAmount: bigint;
+}
+interface IInstanceStateUpdated extends IBaseEvent {
+    address: Address;
+    state: 0 | 1;
+}
+interface IAsset {
+    name: string;
+    decimals: number;
+    address: Address;
+    symbol: string;
+}
+
+declare const POOL_EVENTS_SIGNATURES: {
+    readonly Deposited: {
+        readonly name: "Deposit";
+        readonly type: "event";
+        readonly inputs: readonly [{
+            readonly type: "bytes32";
+            readonly name: "commitment";
+            readonly indexed: true;
+        }, {
+            readonly type: "uint32";
+            readonly name: "leafIndex";
+        }, {
+            readonly type: "uint256";
+            readonly name: "timestamp";
+        }];
+    };
+    readonly Withdrawn: {
+        readonly name: "Withdrawal";
+        readonly type: "event";
+        readonly inputs: readonly [{
+            readonly type: "address";
+            readonly name: "to";
+        }, {
+            readonly type: "bytes32";
+            readonly name: "nullifierHash";
+        }, {
+            readonly type: "address";
+            readonly name: "relayer";
+            readonly indexed: true;
+        }, {
+            readonly type: "uint256";
+            readonly name: "fee";
+        }];
+    };
+};
+declare const RELAYER_REGISTRY_EVENTS_SIGNATURES: {
+    readonly RelayerRegistered: {
+        readonly name: "RelayerRegistered";
+        readonly type: "event";
+        readonly inputs: readonly [{
+            readonly type: "bytes32";
+            readonly name: "relayer";
+        }, {
+            readonly type: "string";
+            readonly name: "ensName";
+        }, {
+            readonly type: "address";
+            readonly name: "relayerAddress";
+        }, {
+            readonly type: "uint256";
+            readonly name: "stakedAmount";
+        }];
+    };
+};
+declare const INSTANCE_REGISTRY_EVENT_SIGNATURES: {
+    InstanceStateUpdated: {
+        readonly name: "InstanceStateUpdated";
+        readonly type: "event";
+        readonly inputs: readonly [{
+            readonly type: "address";
+            readonly name: "instance";
+            readonly indexed: true;
+        }, {
+            readonly type: "uint8";
+            readonly name: "state";
+        }];
+    };
+};
+
+type IEventsMap = Record<string, ParseAbiItem<string>>;
+interface IGetEventsParams<T> {
+    events: T | T[];
+    fromBlock: bigint;
+    toBlock?: bigint;
+    address: bigint;
+}
+interface IRelayerRegistryEvents {
+    RelayerRegistered: IRelayerRegisteredEvent;
+}
+interface IPoolEvents {
+    Deposited: IRawDepositEvent;
+    Withdrawn: IRawWithdrawalEvent;
+}
+interface IInstanceRegistryEvents {
+    InstanceStateUpdated: IInstanceStateUpdated;
+}
+type IGroupedEvents<NamesTable extends Record<string, unknown>> = {
+    [key in keyof NamesTable]: NamesTable[key][];
+};
+type GetEventsFn<EventsMap extends IEventsMap, ParsedEvents extends {
+    [key in keyof EventsMap]: unknown;
+}> = <const T extends keyof ParsedEvents = never>(params: IGetEventsParams<T>) => Promise<Pick<IGroupedEvents<ParsedEvents>, T> & {
+    fromBlock: bigint;
+    toBlock: bigint;
+}>;
+interface IPoolConfig {
+    poolAddress: Address;
+    isERC20: boolean;
+    token: Address;
+    state: 0 | 1;
+    uniswapPoolSwappingFee: number;
+    protocolFeePercentage: number;
+    denomination: bigint;
+    rootHistorySize: number;
+}
+interface IRelayerAggregatorData {
+    owner: Address;
+    balance: bigint;
+    isRegistered: boolean;
+    records: string[];
+}
+interface IDataService {
+    getPoolEvents: GetEventsFn<typeof POOL_EVENTS_SIGNATURES, IPoolEvents>;
+    getRelayerRegistryEvents: GetEventsFn<typeof RELAYER_REGISTRY_EVENTS_SIGNATURES, IRelayerRegistryEvents>;
+    getInstanceRegistryEvents: GetEventsFn<typeof INSTANCE_REGISTRY_EVENT_SIGNATURES, IInstanceRegistryEvents>;
+    getAsset(assetAddress: Address): Promise<IAsset>;
+    getAllPoolsAddresses(registryAddress: Address): Promise<Address[]>;
+    getPoolAsset(poolAddress: Address): Promise<Address>;
+    getPoolConfig(registryAddress: Address, poolAddress: Address): Promise<IPoolConfig>;
+    getChainId(): Promise<ChainId>;
+    getGasPrice(): Promise<bigint>;
+    getContractDeploymentBlock(address: Address, fromBlock?: bigint): Promise<bigint>;
+    getPoolStateRoot(poolAddress: Address): Promise<bigint>;
+    getPoolCurrentRootIndex(poolAddress: Address): Promise<number>;
+    isPoolRootValid(poolAddress: Address, root: bigint): Promise<boolean>;
+    getPoolHistoricalRoot(poolAddress: Address, index: number): Promise<bigint>;
+    getLatestBlockTimestamp(): Promise<bigint>;
+    getRelayerData(aggregatorAddress: Address, relayerNameHashes: bigint[], subdomains: string[]): Promise<IRelayerAggregatorData[]>;
+    getAccountNonce(accountAddress: Address): Promise<number>;
+    quoteEthToToken(amountInWei: bigint, tokenAddress: Address, poolFee: number): Promise<bigint>;
+}
+
+type SpecificAssetBalanceFn<isAsync extends boolean = false> = <const Adresses extends Address | Address[] = Address[], ReturnType = Adresses extends unknown[] ? Map<Address, bigint> : bigint>(assetAddress?: Adresses) => isAsync extends true ? Promise<ReturnType> : ReturnType;
+
+interface TornadoWithdrawInputs {
+    nullifier: bigint;
+    secret: bigint;
+    pathElements: bigint[];
+    pathIndices: number[];
+    root: bigint;
+    nullifierHash: bigint;
+    recipient: bigint;
+    relayer: bigint;
+    fee: bigint;
+    refund: bigint;
+}
+interface TornadoProveOutput {
+    proof: `0x${string}`;
+    args: [
+        `0x${string}`,
+        `0x${string}`,
+        `0x${string}`,
+        `0x${string}`,
+        `0x${string}`,
+        `0x${string}`
+    ];
+}
+interface ITornadoProver {
+    prove(inputs: TornadoWithdrawInputs): Promise<TornadoProveOutput>;
+}
+
+interface IRelayerFeeConfig {
+    minFee: number;
+    maxFee: number;
+}
+
+interface StoreFactoryParams {
+    secretManagerFactory: () => Promise<ISecretManager>;
+    dataService: IDataService;
+    relayerClient: IRelayerClient;
+    paymasterConfig: IChainsPaymastersConfig;
+    storageToSyncTo?: Storage;
+    protocolConfig: TCProtocolConfig;
+    relayerConfig?: IRelayerFeeConfig;
+    proverFactory: () => Promise<ITornadoProver>;
+    initialState?: () => Promise<Record<string, PublicRootState>>;
+}
+
+declare enum DepositStrategy {
+    MaxAnonimitySet = 0,
+    MinFee = 1
+}
+
+interface SignedDelegation {
+    senderAddress: `0x${string}`;
+    authorization: SignedAuthorization;
+}
+interface IPaymasterWithdrawalPayload {
+    mode: 'paymaster';
+    proof: TornadoProveOutput;
+    poolAddress: Address;
+    isERC20: boolean;
+    delegation?: SignedDelegation;
+}
+interface PaymasterBroadcastResult {
+    userOpHash: Hash;
+}
+interface IPaymasterBroadcasterClient {
+    broadcast(withdrawals: IPaymasterWithdrawalPayload[]): Promise<PaymasterBroadcastResult[]>;
+}
+
+type DelegationConfig = {
+    mode: 'deterministic';
+    path?: string;
+} | {
+    mode: 'random';
+};
+type StringAddress = `0x${string}`;
+interface IPaymasterConfig {
+    paymasterAddress: StringAddress;
+    entryPointAddress: StringAddress;
+    poolsAccountsMap: Record<StringAddress, StringAddress>;
+    bundlerUrl: string;
+}
+type IChainsPaymastersConfig = Record<number, IPaymasterConfig>;
+interface IRelayerWithdrawalPayload {
+    mode: 'relayer';
+    proof: TornadoProveOutput;
+    poolAddress: Address;
+    relayerUrl: string;
+}
+type IWithdrawalPayload = IRelayerWithdrawalPayload | IPaymasterWithdrawalPayload;
+interface TCPrivateOperation<Mode extends IWithdrawalPayload['mode'] = 'relayer' | 'paymaster'> extends PrivateOperation {
+    withdrawals: (IWithdrawalPayload & {
+        mode: Mode;
+    })[];
+}
+interface TCPublicOperation extends PublicOperation {
+    txns: TxData[];
+}
+interface ITornadoArtifacts {
+    circuitText: string;
+    provingKey: ArrayBuffer;
+}
+type TCProtocolConfig = Omit<ProtocolConfigState, 'chainId'>;
+interface PrivacyPoolsV1ProtocolParams {
+    accountIndex?: number;
+    paymasterConfig: IChainsPaymastersConfig;
+    secretManagerFactory: (params: SecretManagerParams) => Promise<ISecretManager>;
+    stateManager: (params: StoreFactoryParams) => Promise<IStateManager>;
+    relayerClientFactory: () => IRelayerClient;
+    protocolConfig: TCProtocolConfig;
+    relayerConfig?: IRelayerFeeConfig;
+    artifactsLoader?: () => Promise<ITornadoArtifacts>;
+    proverFactory?: () => Promise<ITornadoProver>;
+    initialState?: () => Promise<Record<string, PublicRootState>>;
+    stateManagerWorkerUrl?: string;
+}
+interface IBaseOperationParams {
+}
+interface IDepositOperationParams extends IBaseOperationParams {
+    asset: Address;
+    amount: bigint;
+    strategy: DepositStrategy;
+}
+interface IWithdrawBaseParams extends Omit<IDepositOperationParams, 'amount' | 'strategy'> {
+    amount?: bigint;
+    recipient: Address;
+}
+interface IRelayerWithdrawParams extends IWithdrawBaseParams {
+    mode: 'relayer';
+    preferredRelayersEns?: string[];
+}
+interface IPaymasterWithdrawParams extends IWithdrawBaseParams {
+    mode: 'paymaster';
+    delegation?: DelegationConfig;
+}
+type IWithdrawapOperationParams = IRelayerWithdrawParams | IPaymasterWithdrawParams;
+type StoreKey = `${string}-${string}`;
+type StoreStorageKey = `tornado-cash-state-${StoreKey}`;
+interface IStateManager {
+    /**
+     * Queries the chain and updates its state
+     */
+    sync: () => Promise<void>;
+    /**
+     * Generates a deposit payload for the signer
+     */
+    getDepositPayload: (params: IDepositOperationParams) => Promise<TxData[]>;
+    /**
+     * Calls the relayer to submit withdrawals and returns job IDs
+     */
+    getWithdrawalPayloads: (params: IWithdrawapOperationParams) => Promise<IWithdrawalPayload[]>;
+    /**
+     * Gets the balance of the specified assets.
+     * All assets if not specified.
+     */
+    getBalances: SpecificAssetBalanceFn<true>;
+    dumpState: () => Record<StoreStorageKey, PublicRootState>;
+}
+
+type TCBroadcasterParameters = {
+    relayerClientFactory?: () => IRelayerClient;
+    paymasterConfig?: IChainsPaymastersConfig;
+    paymasterClientFactory?: () => IPaymasterBroadcasterClient;
+};
+type TCBroadcaster = Broadcaster<TCPrivateOperation, ITornadoWithdrawResponse[]>;
+interface TCBaseCredential {
+    accountIndex: number;
+}
+interface TCPluginParameters extends TCBroadcasterParameters, TCBaseCredential {
+    protocolConfig: TCProtocolConfig;
+    relayerConfig?: IRelayerFeeConfig;
+    initialState?: PrivacyPoolsV1ProtocolParams['initialState'];
+    artifacts: ITornadoArtifacts;
+    stateManagerWorkerUrl?: string;
+}
+type TCAddress = Address$1;
+type TCAssetAmount<Tag extends string | undefined = undefined> = AssetAmount<ERC20AssetId, bigint, Tag>;
+type TCAssetBalance = TCAssetAmount;
+interface TCRelayerUnshieldOptions {
+    mode: 'relayer';
+    preferredRelayersEns?: string[];
+}
+interface TCPaymasterUnshieldOptions {
+    mode: 'paymaster';
+    delegation?: DelegationConfig;
+}
+type TCPrepareUnshieldOptions = TCRelayerUnshieldOptions | TCPaymasterUnshieldOptions;
+interface TCPrepareShieldOptions {
+    strategy: DepositStrategy;
+}
+type TCInstance = PluginInstance<TCAddress, {
+    features: {
+        prepareShield: true;
+        prepareUnshield: true;
+    };
+    assetAmounts: {
+        input: TCAssetAmount;
+        internal: TCAssetAmount;
+        output: TCAssetAmount;
+        read: TCAssetBalance;
+    };
+    extras: {
+        sync(): Promise<void>;
+        prepareShield(asset: TCAssetAmount, options: TCPrepareShieldOptions): Promise<TCPublicOperation>;
+        prepareUnshield(asset: TCAssetAmount, to: Address$1, options: TCRelayerUnshieldOptions): Promise<TCPrivateOperation<'relayer'>>;
+        prepareUnshield(asset: TCAssetAmount, to: Address$1, options: TCPaymasterUnshieldOptions): Promise<TCPrivateOperation<'paymaster'>>;
+    };
+    publicOp: TCPublicOperation;
+    privateOp: TCPrivateOperation;
+}>;
+
+declare const createTCBroadcaster: (host: Host, params?: TCBroadcasterParameters) => TCBroadcaster;
+declare const createTCPlugin: (host: Host, params: TCPluginParameters) => TCInstance;
+
+type RequireOnly<T, Keys extends keyof T> = Partial<T> & Pick<T, Keys>;
+declare class TornadoCashProtocol implements TCInstance {
+    readonly host: Host;
+    private stateManager;
+    constructor(host: Host, { accountIndex, initialState, protocolConfig, artifactsLoader, stateManagerWorkerUrl, relayerConfig, paymasterConfig, relayerClientFactory }: RequireOnly<PrivacyPoolsV1ProtocolParams, 'protocolConfig'>);
+    instanceId: () => Promise<"0x1">;
+    /**
+     * Only process supported assets or error out?
+     * Returns the balances of the requested assets.
+     * The assets retain the provided order. If an asset is not supported its balance will be 0
+     */
+    balance(assets?: ERC20AssetId[]): Promise<TCAssetBalance[]>;
+    prepareShield(assets: TCAssetAmount, options?: TCPrepareShieldOptions | `0x${string}`): Promise<TCPublicOperation>;
+    prepareUnshield(assets: AssetAmount, to: AccountId, options?: TCRelayerUnshieldOptions): Promise<TCPrivateOperation<'relayer'>>;
+    prepareUnshield(assets: AssetAmount, to: AccountId, options?: TCPaymasterUnshieldOptions): Promise<TCPrivateOperation<'paymaster'>>;
+    sync(): Promise<void>;
+    dumpState(): Promise<Record<`tornado-cash-state-${string}-${string}`, PublicRootState>>;
+}
+
+interface Commitment {
+    hash: string;
+    token: Address$2;
+    value: bigint;
+    randomness: Uint8Array;
+    spent: boolean;
+    index?: number;
+}
+interface Nullifier {
+    hash: string;
+    commitment: Commitment;
+}
+
+declare const E_ADDRESS = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
+declare const TornadoCashConfigs: {
+    readonly 1: {
+        readonly ensSubdomainKey: "mainnet-tornado";
+        readonly instanceRegistry: {
+            readonly address: 1016476918593216659678085511611900461079531923729n;
+            readonly deploymentBlock: 14173395n;
+        };
+        readonly relayerRegistry: {
+            readonly address: 507584191175595477754377491521282335005092363762n;
+            readonly deploymentBlock: 14173129n;
+        };
+        readonly aggregator: {
+            readonly address: 1329937909414098670091808248270266272594403334985n;
+        };
+        readonly weth: 1097077688018008265106216665536940668749033598146n;
+        readonly uniswapQuoterV2: 559478315000592720989748010348495519536007655966n;
+    };
+    readonly 11155111: {
+        readonly ensSubdomainKey: "sepolia-tornado";
+        readonly instanceRegistry: {
+            readonly address: 447664927873626138772898946646079239273904189887n;
+            readonly deploymentBlock: 5594611n;
+        };
+        readonly relayerRegistry: {
+            readonly address: 1224003368246423020781607736948693909640296222714n;
+            readonly deploymentBlock: 5594660n;
+        };
+        readonly aggregator: {
+            readonly address: 368418168928372787409224158240737522620871644738n;
+        };
+        readonly weth: 1461358721292675304620367034492138750323989506836n;
+        readonly uniswapQuoterV2: 1353730886217084326490181093487957540173111046067n;
+    };
+};
+
+export { type Commitment, DepositStrategy, E_ADDRESS, type ISecretManager, type Nullifier, SecretManager, type SecretManagerParams, type TCAddress, type TCAssetAmount, type TCAssetBalance, type TCBroadcaster, type TCBroadcasterParameters, type TCInstance, type TCPaymasterUnshieldOptions, type TCPluginParameters, type TCPrepareShieldOptions, type TCPrepareUnshieldOptions, type TCRelayerUnshieldOptions, TornadoCashConfigs, TornadoCashProtocol, createTCBroadcaster, createTCPlugin };