@kohaku-eth/tornado-cash 0.0.2-alpha.15 → 0.0.2-alpha.16

package/dist/index.d.ts

@@ -33,6 +33,15 @@ type DeriveDepositSecretParams = BaseDeriveSecretParams & {
 interface ISecretManager {
     getDepositSecrets: (params: DeriveDepositSecretParams) => Promise<Secret>;
     deriveEphemeralSigner: (params: DeriveDepositSecretParams) => Promise<`0x${string}`>;
+    /**
+     * Derives a delegator key from a classical wallet BIP-32 `path`, WITHOUT the
+     * `coalesceSecret` privacy transform, so it resolves to a recoverable,
+     * classical Ethereum address. Used for the tail-call batch delegator when the
+     * integrator supplies a wallet path (see `paymasterWithdrawThunk`).
+     */
+    deriveDelegatorSigner: (params: {
+        path: string;
+    }) => Promise<`0x${string}`>;
 }
 interface SecretManagerParams {
     host: Pick<Host, 'keystore'>;
@@ -352,6 +361,24 @@ declare enum DepositStrategy {
     MinFee = 1
 }
 
+/**
+ * How the batch delegator for a tail-call paymaster withdrawal is produced.
+ * Only honored when `tailCalls` are present (see `paymasterWithdrawThunk`).
+ *
+ * - `deterministic` (default): recoverable. With `path`, the delegator is a
+ *   classical wallet-path address; without `path`, an ephemeral address keyed by
+ *   the batch's first deposit.
+ * - `random`: a throwaway, unrecoverable EOA — an explicit opt-out of
+ *   recoverability. Never the default, because in the tail-call path the
+ *   delegator holds the withdrawn funds.
+ */
+type DelegationConfig = {
+    mode: 'deterministic';
+    path?: string;
+} | {
+    mode: 'random';
+};
+
 interface SerializedAuth {
     address: Address$1;
     chainId: Hex;
@@ -410,12 +437,6 @@ interface IPaymasterBroadcasterClient {
     broadcast(withdrawals: IPaymasterWithdrawalPayload[]): Promise<PaymasterBroadcastResult[]>;
 }
 
-type DelegationConfig = {
-    mode: 'deterministic';
-    path?: string;
-} | {
-    mode: 'random';
-};
 type StringAddress = `0x${string}`;
 interface IPaymasterConfig {
     paymasterAddress: StringAddress;

package/dist/index.js

@@ -764,9 +764,13 @@ async function SecretManager({
     const coalesced = coalesceSecret({ secret: raw, chainId, poolAddress });
     return `0x${coalesced.toString(16).padStart(64, "0")}`;
   };
+  const deriveDelegatorSigner = async ({ path }) => {
+    return Promise.resolve(keystore.deriveAt(path));
+  };
   return {
     getDepositSecrets: (params) => deriveSecrets(params),
-    deriveEphemeralSigner
+    deriveEphemeralSigner,
+    deriveDelegatorSigner
   };
 }
 function tcPath({ accountIndex, secretType, depositIndex }) {

package/dist/state-manager.worker.js

@@ -17281,9 +17281,13 @@ async function SecretManager({
     const coalesced = coalesceSecret({ secret: raw, chainId, poolAddress });
     return `0x${coalesced.toString(16).padStart(64, "0")}`;
   };
+  const deriveDelegatorSigner = async ({ path }) => {
+    return Promise.resolve(keystore.deriveAt(path));
+  };
   return {
     getDepositSecrets: (params) => deriveSecrets(params),
-    deriveEphemeralSigner
+    deriveEphemeralSigner,
+    deriveDelegatorSigner
   };
 }
 function tcPath({ accountIndex, secretType, depositIndex }) {
@@ -24087,11 +24091,8 @@ async function getUserOperationGasPrice(client) {
     fast: parse(result.fast)
   };
 }
-function ephemeralSenderAddress(privateKey) {
-  return privateKeyToAccount(privateKey).address;
-}
 async function buildSignedTornadoUserOp({
-  privateKey,
+  signer,
   chainId,
   paymasterAddress,
   paymasterData,
@@ -24101,7 +24102,7 @@ async function buildSignedTornadoUserOp({
   tailCalls = async () => [],
   nonce = 0n
 }) {
-  const owner = privateKeyToAccount(privateKey);
+  const owner = signer;
   const calls = await tailCalls(owner.address);
   let callData = "0x";
   if (calls.length === 1) {
@@ -24174,6 +24175,12 @@ function serializeAuth(auth) {
 }
 
 // src/state/thunks/paymasterWithdrawThunk.ts
+var BIP32_PATH = /^m(\/\d+'?)+$/;
+function assertValidDelegatorPath(path) {
+  if (!BIP32_PATH.test(path)) {
+    throw new Error(`Invalid delegation path "${path}": expected a BIP-32 path like m/44'/60'/0'/0/0`);
+  }
+}
 var paymasterWithdrawThunk = createAsyncThunk("withdraw/executePaymasterWithdrawals", async ({
   dataService,
   assetAddress,
@@ -24220,18 +24227,28 @@ var paymasterWithdrawThunk = createAsyncThunk("withdraw/executePaymasterWithdraw
   const relayerAddress = BigInt(paymasterAddress);
   const bigintChainId = await dataService.getChainId();
   const { recipient: originalRecipient, ...restWithoutRecipient } = rest;
-  const sharedPrivateKey = tailCalls ? generatePrivateKey() : null;
+  const ephemeralSigner = async (deposit) => privateKeyToAccount(await secretManager.deriveEphemeralSigner({
+    depositIndex: deposit.index,
+    chainId: bigintChainId,
+    poolAddress: deposit.pool
+  }));
+  const resolveBatchDelegator = async () => {
+    if (delegation?.mode === "random") return privateKeyToAccount(generatePrivateKey());
+    if (delegation?.mode === "deterministic" && delegation.path) {
+      assertValidDelegatorPath(delegation.path);
+      return privateKeyToAccount(await secretManager.deriveDelegatorSigner({ path: delegation.path }));
+    }
+    return ephemeralSigner(deposits[0]);
+  };
+  const resolveIndependentSigner = (deposit) => delegation?.mode === "deterministic" ? ephemeralSigner(deposit) : Promise.resolve(privateKeyToAccount(generatePrivateKey()));
+  const sharedDelegator = tailCalls ? await resolveBatchDelegator() : null;
   const proofOutputs = [];
   const userOperations = [];
   for (let i = 0; i < deposits.length; i++) {
     const deposit = deposits[i];
     const isLast = i === deposits.length - 1;
-    const privateKey = sharedPrivateKey ?? (delegation?.mode === "deterministic" ? await secretManager.deriveEphemeralSigner({
-      depositIndex: deposit.index,
-      chainId: bigintChainId,
-      poolAddress: deposit.pool
-    }) : generatePrivateKey());
-    const recipient = sharedPrivateKey ? BigInt(ephemeralSenderAddress(privateKey)) : originalRecipient;
+    const signer = sharedDelegator ?? await resolveIndependentSigner(deposit);
+    const recipient = sharedDelegator ? BigInt(signer.address) : originalRecipient;
     const effectiveTailCalls = isLast ? tailCalls : void 0;
     const gas = { ...gasUnits, callGasLimit: effectiveTailCalls ? gasUnits.callGasLimit : 0n };
     const withdrawResultAction = await dispatch(
@@ -24261,7 +24278,7 @@ var paymasterWithdrawThunk = createAsyncThunk("withdraw/executePaymasterWithdraw
     );
     userOperations.push(
       await buildSignedTornadoUserOp({
-        privateKey,
+        signer,
         chainId,
         paymasterAddress,
         paymasterData,
@@ -24269,9 +24286,9 @@ var paymasterWithdrawThunk = createAsyncThunk("withdraw/executePaymasterWithdraw
         maxFeePerGas,
         maxPriorityFeePerGas,
         tailCalls: effectiveTailCalls,
-        // When sharing one ephemeral key across multiple deposits each userOp
-        // needs a distinct nonce (0, 1, 2 …) on the shared sender.
-        nonce: sharedPrivateKey ? BigInt(i) : 0n
+        // When sharing one delegator across multiple deposits each userOp needs
+        // a distinct nonce (0, 1, 2 …) on the shared sender.
+        nonce: sharedDelegator ? BigInt(i) : 0n
       })
     );
   }

package/dist/state-manager.worker.node.js

@@ -16853,9 +16853,13 @@ async function SecretManager({
     const coalesced = coalesceSecret({ secret: raw, chainId, poolAddress });
     return `0x${coalesced.toString(16).padStart(64, "0")}`;
   };
+  const deriveDelegatorSigner = async ({ path }) => {
+    return Promise.resolve(keystore.deriveAt(path));
+  };
   return {
     getDepositSecrets: (params) => deriveSecrets(params),
-    deriveEphemeralSigner
+    deriveEphemeralSigner,
+    deriveDelegatorSigner
   };
 }
 function tcPath({ accountIndex, secretType, depositIndex }) {
@@ -23313,11 +23317,8 @@ async function getUserOperationGasPrice(client) {
     fast: parse(result.fast)
   };
 }
-function ephemeralSenderAddress(privateKey) {
-  return privateKeyToAccount(privateKey).address;
-}
 async function buildSignedTornadoUserOp({
-  privateKey,
+  signer,
   chainId,
   paymasterAddress,
   paymasterData,
@@ -23327,7 +23328,7 @@ async function buildSignedTornadoUserOp({
   tailCalls = async () => [],
   nonce = 0n
 }) {
-  const owner = privateKeyToAccount(privateKey);
+  const owner = signer;
   const calls = await tailCalls(owner.address);
   let callData = "0x";
   if (calls.length === 1) {
@@ -23400,6 +23401,12 @@ function serializeAuth(auth) {
 }
 
 // src/state/thunks/paymasterWithdrawThunk.ts
+var BIP32_PATH = /^m(\/\d+'?)+$/;
+function assertValidDelegatorPath(path) {
+  if (!BIP32_PATH.test(path)) {
+    throw new Error(`Invalid delegation path "${path}": expected a BIP-32 path like m/44'/60'/0'/0/0`);
+  }
+}
 var paymasterWithdrawThunk = createAsyncThunk("withdraw/executePaymasterWithdrawals", async ({
   dataService,
   assetAddress,
@@ -23446,18 +23453,28 @@ var paymasterWithdrawThunk = createAsyncThunk("withdraw/executePaymasterWithdraw
   const relayerAddress = BigInt(paymasterAddress);
   const bigintChainId = await dataService.getChainId();
   const { recipient: originalRecipient, ...restWithoutRecipient } = rest;
-  const sharedPrivateKey = tailCalls ? generatePrivateKey() : null;
+  const ephemeralSigner = async (deposit) => privateKeyToAccount(await secretManager.deriveEphemeralSigner({
+    depositIndex: deposit.index,
+    chainId: bigintChainId,
+    poolAddress: deposit.pool
+  }));
+  const resolveBatchDelegator = async () => {
+    if (delegation?.mode === "random") return privateKeyToAccount(generatePrivateKey());
+    if (delegation?.mode === "deterministic" && delegation.path) {
+      assertValidDelegatorPath(delegation.path);
+      return privateKeyToAccount(await secretManager.deriveDelegatorSigner({ path: delegation.path }));
+    }
+    return ephemeralSigner(deposits[0]);
+  };
+  const resolveIndependentSigner = (deposit) => delegation?.mode === "deterministic" ? ephemeralSigner(deposit) : Promise.resolve(privateKeyToAccount(generatePrivateKey()));
+  const sharedDelegator = tailCalls ? await resolveBatchDelegator() : null;
   const proofOutputs = [];
   const userOperations = [];
   for (let i = 0; i < deposits.length; i++) {
     const deposit = deposits[i];
     const isLast = i === deposits.length - 1;
-    const privateKey = sharedPrivateKey ?? (delegation?.mode === "deterministic" ? await secretManager.deriveEphemeralSigner({
-      depositIndex: deposit.index,
-      chainId: bigintChainId,
-      poolAddress: deposit.pool
-    }) : generatePrivateKey());
-    const recipient = sharedPrivateKey ? BigInt(ephemeralSenderAddress(privateKey)) : originalRecipient;
+    const signer = sharedDelegator ?? await resolveIndependentSigner(deposit);
+    const recipient = sharedDelegator ? BigInt(signer.address) : originalRecipient;
     const effectiveTailCalls = isLast ? tailCalls : void 0;
     const gas = { ...gasUnits, callGasLimit: effectiveTailCalls ? gasUnits.callGasLimit : 0n };
     const withdrawResultAction = await dispatch(
@@ -23487,7 +23504,7 @@ var paymasterWithdrawThunk = createAsyncThunk("withdraw/executePaymasterWithdraw
     );
     userOperations.push(
       await buildSignedTornadoUserOp({
-        privateKey,
+        signer,
         chainId,
         paymasterAddress,
         paymasterData,
@@ -23495,9 +23512,9 @@ var paymasterWithdrawThunk = createAsyncThunk("withdraw/executePaymasterWithdraw
         maxFeePerGas,
         maxPriorityFeePerGas,
         tailCalls: effectiveTailCalls,
-        // When sharing one ephemeral key across multiple deposits each userOp
-        // needs a distinct nonce (0, 1, 2 …) on the shared sender.
-        nonce: sharedPrivateKey ? BigInt(i) : 0n
+        // When sharing one delegator across multiple deposits each userOp needs
+        // a distinct nonce (0, 1, 2 …) on the shared sender.
+        nonce: sharedDelegator ? BigInt(i) : 0n
       })
     );
   }

package/dist/worker-loader.browser.d.ts

@@ -113,6 +113,24 @@ declare enum DepositStrategy {
     MinFee = 1
 }
 
+/**
+ * How the batch delegator for a tail-call paymaster withdrawal is produced.
+ * Only honored when `tailCalls` are present (see `paymasterWithdrawThunk`).
+ *
+ * - `deterministic` (default): recoverable. With `path`, the delegator is a
+ *   classical wallet-path address; without `path`, an ephemeral address keyed by
+ *   the batch's first deposit.
+ * - `random`: a throwaway, unrecoverable EOA — an explicit opt-out of
+ *   recoverability. Never the default, because in the tail-call path the
+ *   delegator holds the withdrawn funds.
+ */
+type DelegationConfig = {
+    mode: 'deterministic';
+    path?: string;
+} | {
+    mode: 'random';
+};
+
 interface SerializedAuth {
     address: Address$1;
     chainId: Hex;
@@ -154,12 +172,6 @@ interface IGenericPaymasterWithdrawalPayload {
     userOperation: SerializedUserOperation;
 }
 
-type DelegationConfig = {
-    mode: 'deterministic';
-    path?: string;
-} | {
-    mode: 'random';
-};
 type StringAddress = `0x${string}`;
 interface IPaymasterConfig {
     paymasterAddress: StringAddress;

package/dist/worker-loader.node.d.ts

@@ -114,6 +114,24 @@ declare enum DepositStrategy {
     MinFee = 1
 }
 
+/**
+ * How the batch delegator for a tail-call paymaster withdrawal is produced.
+ * Only honored when `tailCalls` are present (see `paymasterWithdrawThunk`).
+ *
+ * - `deterministic` (default): recoverable. With `path`, the delegator is a
+ *   classical wallet-path address; without `path`, an ephemeral address keyed by
+ *   the batch's first deposit.
+ * - `random`: a throwaway, unrecoverable EOA — an explicit opt-out of
+ *   recoverability. Never the default, because in the tail-call path the
+ *   delegator holds the withdrawn funds.
+ */
+type DelegationConfig = {
+    mode: 'deterministic';
+    path?: string;
+} | {
+    mode: 'random';
+};
+
 interface SerializedAuth {
     address: Address$1;
     chainId: Hex;
@@ -155,12 +173,6 @@ interface IGenericPaymasterWithdrawalPayload {
     userOperation: SerializedUserOperation;
 }
 
-type DelegationConfig = {
-    mode: 'deterministic';
-    path?: string;
-} | {
-    mode: 'random';
-};
 type StringAddress = `0x${string}`;
 interface IPaymasterConfig {
     paymasterAddress: StringAddress;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kohaku-eth/tornado-cash",
-  "version": "0.0.2-alpha.15",
+  "version": "0.0.2-alpha.16",
   "description": "Tornado Cash Shielded Pool Kohaku Plugin",
   "type": "module",
   "private": false,
@@ -74,9 +74,9 @@
     "micro-zk-proofs": "0.3.1",
     "ox": "^0.12.0",
     "viem": "^2.51.3",
+    "@kohaku-eth/plugins": "0.0.1-alpha.11",
     "@kohaku-eth/mimc-tree": "0.0.3",
-    "@kohaku-eth/provider": "0.1.0-alpha.8",
-    "@kohaku-eth/plugins": "0.0.1-alpha.11"
+    "@kohaku-eth/provider": "0.1.0-alpha.8"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",