feat: add support for overriding ethereum session key

DenzelPenzel · DenzelPenzel · commit 93a48a9bee67 · 2025-11-06T21:39:11.000Z
diff --git a/docs/src/network-definition-spec.md b/docs/src/network-definition-spec.md
@@ -112,6 +112,7 @@ The network config can be provided both in `json` or `toml` format and each sect
       - name: (String) name of the `env` var.
       - value: (String| number) Value of the env var.
     - `keystore_key_types`: Defines which keystore keys should be created, for more details checkout details below.
+    - `override_eth_key`: (String) Overrides the auto-generated ethereum session key for EVM-based paras. When set, the provided key is used and Zombienet omits the random seed from the resulting `zombie.json`.
 
   - `collator_groups`:
 
@@ -126,6 +127,7 @@ The network config can be provided both in `json` or `toml` format and each sect
       - name: (String) name of the `env` var.
       - value: (String| number) Value of the env var.
       - `substrate_cli_args_version`: (0|1|2) By default zombienet will evaluate your binary and set the correct version, but that produces a small overhead that could be skipped if you set directly with this key.
+    - `override_eth_key`: (String) Same as above, lets you provide the ethereum session key.
 
   - `onboard_as_parachain`: (Boolean, default true) flag to specify whether the para should be onboarded as a parachain or stay a parathread
   - `register_para`: (Boolean, default true) flag to specify whether the para should be registered. The `add_to_genesis` flag **must** be set to false for this flag to have any effect.
diff --git a/examples/0010-generic-evm-override-eth-key.toml b/examples/0010-generic-evm-override-eth-key.toml
@@ -0,0 +1,26 @@
+[settings]
+timeout = 1000
+
+[relaychain]
+default_image = "docker.io/paritypr/polkadot-debug:master"
+default_command = "polkadot"
+default_args = ["-lparachain=debug"]
+
+chain = "rococo-local"
+
+  [[relaychain.nodes]]
+  name = "alice"
+
+  [[relaychain.nodes]]
+  name = "bob"
+
+[[parachains]]
+id = 2000
+chain = "generic-evm"
+
+  [parachains.collator]
+  name = "evm-collator"
+  image = "docker.io/parity/polkadot-parachain:latest"
+  command = "polkadot-parachain"
+  args = ["-lparachain=debug"]
+  override_eth_key = "calm dirt remove satisfy web real danger swap ship enroll youth prize"
diff --git a/javascript/packages/orchestrator/src/chain-decorators/generic-evm.ts b/javascript/packages/orchestrator/src/chain-decorators/generic-evm.ts
@@ -1,4 +1,5 @@
 import { Keyring } from "@polkadot/api";
+import type { KeyringPair } from "@polkadot/keyring/types";
 import { u8aToHex } from "@polkadot/util";
 import { cryptoWaitReady } from "@polkadot/util-crypto";
 import { CreateLogTable, decorators } from "@zombienet/utils";
@@ -8,24 +9,46 @@ import {
   readAndParseChainSpec,
   writeChainSpec,
 } from "../chainSpec";
-import { generateKeyForNode as _generateKeyForNode } from "../keys";
+import {
+  type NodeAccounts,
+  generateKeyForNode as _generateKeyForNode,
+  resolveEthereumDerivationUri,
+} from "../keys";
 import { Node } from "../sharedTypes";
 
-async function generateKeyForNode(nodeName?: string): Promise<any> {
-  const keys = await _generateKeyForNode(nodeName);
+async function generateKeyForNode(
+  nodeName?: string,
+  overrideEthKey?: string,
+): Promise<NodeAccounts> {
+  const keys = await _generateKeyForNode(nodeName, overrideEthKey);
 
   await cryptoWaitReady();
 
   const eth_keyring = new Keyring({ type: "ethereum" });
-  const eth_account = eth_keyring.createFromUri(
-    `${keys.mnemonic}/m/44'/60'/0'/0/0`,
+  const uri = resolveEthereumDerivationUri(
+    keys.mnemonic ?? "",
+    overrideEthKey,
   );
 
+  let eth_account: KeyringPair;
+  try {
+    eth_account = eth_keyring.createFromUri(uri);
+  } catch (error) {
+    throw new Error(
+      `Failed to create ethereum session key for ${nodeName}: ${error}`,
+    );
+  }
+
   keys.eth_account = {
     address: eth_account.address,
     publicKey: u8aToHex(eth_account.publicKey),
   };
 
+  if (overrideEthKey) {
+    keys.ethKeyOverrideUsed = true;
+    delete keys.mnemonic;
+  }
+
   return keys;
 }
 
diff --git a/javascript/packages/orchestrator/src/chain-decorators/local-v.ts b/javascript/packages/orchestrator/src/chain-decorators/local-v.ts
@@ -1,4 +1,5 @@
 import { Keyring } from "@polkadot/api";
+import type { KeyringPair } from "@polkadot/keyring/types";
 import { u8aToHex } from "@polkadot/util";
 import { cryptoWaitReady } from "@polkadot/util-crypto";
 import { CreateLogTable, decorators } from "@zombienet/utils";
@@ -8,24 +9,46 @@ import {
   readAndParseChainSpec,
   writeChainSpec,
 } from "../chainSpec";
-import { generateKeyForNode as _generateKeyForNode } from "../keys";
+import {
+  type NodeAccounts,
+  generateKeyForNode as _generateKeyForNode,
+  resolveEthereumDerivationUri,
+} from "../keys";
 import { Node } from "../sharedTypes";
 
-async function generateKeyForNode(nodeName?: string): Promise<any> {
-  const keys = await _generateKeyForNode(nodeName);
+async function generateKeyForNode(
+  nodeName?: string,
+  overrideEthKey?: string,
+): Promise<NodeAccounts> {
+  const keys = await _generateKeyForNode(nodeName, overrideEthKey);
 
   await cryptoWaitReady();
 
   const eth_keyring = new Keyring({ type: "ethereum" });
-  const eth_account = eth_keyring.createFromUri(
-    `${keys.mnemonic}/m/44'/60'/0'/0/0`,
+  const uri = resolveEthereumDerivationUri(
+    keys.mnemonic ?? "",
+    overrideEthKey,
   );
 
+  let eth_account: KeyringPair;
+  try {
+    eth_account = eth_keyring.createFromUri(uri);
+  } catch (error) {
+    throw new Error(
+      `Failed to create ethereum session key for ${nodeName ?? "collator"}: ${error}`,
+    );
+  }
+
   keys.eth_account = {
     address: eth_account.address,
     publicKey: u8aToHex(eth_account.publicKey),
   };
 
+  if (overrideEthKey) {
+    keys.ethKeyOverrideUsed = true;
+    delete keys.mnemonic;
+  }
+
   return keys;
 }
 
diff --git a/javascript/packages/orchestrator/src/chain-decorators/mainnet-local-v.ts b/javascript/packages/orchestrator/src/chain-decorators/mainnet-local-v.ts
@@ -1,4 +1,5 @@
 import { Keyring } from "@polkadot/api";
+import type { KeyringPair } from "@polkadot/keyring/types";
 import { u8aToHex } from "@polkadot/util";
 import { cryptoWaitReady } from "@polkadot/util-crypto";
 import { CreateLogTable, decorators } from "@zombienet/utils";
@@ -8,24 +9,46 @@ import {
   readAndParseChainSpec,
   writeChainSpec,
 } from "../chainSpec";
-import { generateKeyForNode as _generateKeyForNode } from "../keys";
+import {
+  type NodeAccounts,
+  generateKeyForNode as _generateKeyForNode,
+  resolveEthereumDerivationUri,
+} from "../keys";
 import { Node } from "../sharedTypes";
 
-async function generateKeyForNode(nodeName?: string): Promise<any> {
-  const keys = await _generateKeyForNode(nodeName);
+async function generateKeyForNode(
+  nodeName?: string,
+  overrideEthKey?: string,
+): Promise<NodeAccounts> {
+  const keys = await _generateKeyForNode(nodeName, overrideEthKey);
 
   await cryptoWaitReady();
 
   const eth_keyring = new Keyring({ type: "ethereum" });
-  const eth_account = eth_keyring.createFromUri(
-    `${keys.mnemonic}/m/44'/60'/0'/0/0`,
+  const uri = resolveEthereumDerivationUri(
+    keys.mnemonic ?? "",
+    overrideEthKey,
   );
 
+  let eth_account: KeyringPair;
+  try {
+    eth_account = eth_keyring.createFromUri(uri);
+  } catch (error) {
+    throw new Error(
+      `Failed to create ethereum session key for ${nodeName ?? "collator"}: ${error}`,
+    );
+  }
+
   keys.eth_account = {
     address: eth_account.address,
     publicKey: u8aToHex(eth_account.publicKey),
   };
 
+  if (overrideEthKey) {
+    keys.ethKeyOverrideUsed = true;
+    delete keys.mnemonic;
+  }
+
   return keys;
 }
 
diff --git a/javascript/packages/orchestrator/src/chain-decorators/moonbeam.ts b/javascript/packages/orchestrator/src/chain-decorators/moonbeam.ts
@@ -1,4 +1,5 @@
 import { Keyring } from "@polkadot/api";
+import type { KeyringPair } from "@polkadot/keyring/types";
 import { u8aToHex } from "@polkadot/util";
 import { cryptoWaitReady } from "@polkadot/util-crypto";
 import { CreateLogTable, decorators } from "@zombienet/utils";
@@ -9,7 +10,11 @@ import {
   readAndParseChainSpec,
   writeChainSpec,
 } from "../chainSpec";
-import { generateKeyForNode as _generateKeyForNode } from "../keys";
+import {
+  type NodeAccounts,
+  generateKeyForNode as _generateKeyForNode,
+  resolveEthereumDerivationUri,
+} from "../keys";
 import { ChainSpec } from "../types";
 import { Node } from "../sharedTypes";
 
@@ -96,23 +101,40 @@ async function clearAuthorities(specPath: string) {
   writeChainSpec(specPath, chainSpec);
 }
 
-async function generateKeyForNode(nodeName?: string): Promise<any> {
-  const keys = await _generateKeyForNode(nodeName);
+async function generateKeyForNode(
+  nodeName?: string,
+  overrideEthKey?: string,
+): Promise<NodeAccounts> {
+  const keys = await _generateKeyForNode(nodeName, overrideEthKey);
 
   await cryptoWaitReady();
 
   const eth_keyring = new Keyring({ type: "ethereum" });
-  const eth_account = eth_keyring.createFromUri(
-    nodeName && nodeName.toLocaleLowerCase() in KNOWN_MOONBEAM_KEYS
-      ? KNOWN_MOONBEAM_KEYS[nodeName.toLocaleLowerCase()]
-      : `${keys.mnemonic}/m/44'/60'/0'/0/0`,
-  );
+  const lowerName = nodeName?.toLocaleLowerCase();
+  const knownKey = lowerName ? KNOWN_MOONBEAM_KEYS[lowerName] : undefined;
+  const uri = knownKey
+    ? knownKey
+    : resolveEthereumDerivationUri(keys.mnemonic ?? "", overrideEthKey);
+
+  let eth_account: KeyringPair;
+  try {
+    eth_account = eth_keyring.createFromUri(uri);
+  } catch (error) {
+    throw new Error(
+      `Failed to create ethereum session key for ${nodeName ?? "collator"}: ${error}`,
+    );
+  }
 
   keys.eth_account = {
     address: eth_account.address,
     publicKey: u8aToHex(eth_account.publicKey),
   };
 
+  if (overrideEthKey) {
+    keys.ethKeyOverrideUsed = true;
+    delete keys.mnemonic;
+  }
+
   return keys;
 }
 
diff --git a/javascript/packages/orchestrator/src/configGenerator.ts b/javascript/packages/orchestrator/src/configGenerator.ts
@@ -616,7 +616,10 @@ async function getCollatorNodeFromConfig(
 
   const collatorName = getUniqueName(collatorConfig.name || "collator");
   const [decoratedKeysGenerator] = decorate(para, [generateKeyForNode]);
-  const accountsForNode = await decoratedKeysGenerator(collatorName);
+  const accountsForNode = await decoratedKeysGenerator(
+    collatorName,
+    collatorConfig.override_eth_key,
+  );
 
   const provider = networkSpec.settings.provider;
   const ports = await getPorts(provider, collatorConfig);
diff --git a/javascript/packages/orchestrator/src/keys.ts b/javascript/packages/orchestrator/src/keys.ts
@@ -1,4 +1,5 @@
 import { Keyring } from "@polkadot/api";
+import type { KeyringPair } from "@polkadot/keyring/types";
 import { u8aToHex } from "@polkadot/util";
 import {
   cryptoWaitReady,
@@ -13,14 +14,64 @@ function nameCase(string: string) {
   return string.charAt(0).toUpperCase() + string.slice(1);
 }
 
-export async function generateKeyFromSeed(seed: string): Promise<any> {
+export interface SigningAccount {
+  address: string;
+  publicKey: string;
+}
+
+export interface NodeAccounts {
+  seed?: string;
+  mnemonic?: string;
+  sr_account: SigningAccount;
+  sr_stash: SigningAccount;
+  ed_account: SigningAccount;
+  ec_account: {
+    publicKey: string;
+  };
+  eth_account?: SigningAccount;
+  ethKeyOverrideUsed?: boolean;
+}
+
+const BIP39_WORD_LENGTHS = new Set([12, 15, 18, 21, 24]);
+
+export function resolveEthereumDerivationUri(
+  fallbackMnemonic: string,
+  override?: string,
+): string {
+  if (!override || override.trim().length === 0) {
+    return `${fallbackMnemonic}/m/44'/60'/0'/0/0`;
+  }
+
+  const trimmed = override.trim();
+
+  if (trimmed.startsWith("//")) {
+    throw new Error(
+      "override_eth_key for ethereum nodes must be a mnemonic, a mnemonic with an explicit /m/ path, or a 0x-prefixed private key.",
+    );
+  }
+
+  if (trimmed.startsWith("0x")) return trimmed;
+  if (trimmed.includes("/m/")) return trimmed;
+
+  const wordCount = trimmed.split(/\s+/).filter(Boolean).length;
+  if (BIP39_WORD_LENGTHS.has(wordCount)) {
+    return `${trimmed}/m/44'/60'/0'/0/0`;
+  }
+
+  return trimmed;
+}
+
+export async function generateKeyFromSeed(seed: string): Promise<KeyringPair> {
   await cryptoWaitReady();
 
   const sr_keyring = new Keyring({ type: "sr25519" });
   return sr_keyring.createFromUri(`//${seed}`);
 }
 
-export async function generateKeyForNode(nodeName?: string): Promise<any> {
+export async function generateKeyForNode(
+  nodeName?: string,
+  _overrideEthKey?: string,
+): Promise<NodeAccounts> {
   await cryptoWaitReady();
 
   const mnemonic = mnemonicGenerate();
@@ -38,7 +89,6 @@ export async function generateKeyForNode(nodeName?: string): Promise<any> {
   const ec_keyring = new Keyring({ type: "ecdsa" });
   const ec_account = ec_keyring.createFromUri(`${seed}`);
 
-  // return the needed info
   return {
     seed,
     mnemonic,
diff --git a/javascript/packages/orchestrator/src/sharedTypes.ts b/javascript/packages/orchestrator/src/sharedTypes.ts
@@ -115,6 +115,7 @@ export interface NodeConfig extends NodeCommonTypes {
   prometheus_port?: number;
   p2p_cert_hash?: string; // libp2p certhash to use with webrtc transport.
   delay_network_settings?: DelayNetworkSettings;
+  override_eth_key?: string;
 }
 
 export interface NodeCommonTypes {
diff --git a/javascript/packages/orchestrator/src/spawner.ts b/javascript/packages/orchestrator/src/spawner.ts
@@ -96,6 +96,14 @@ export const spawnNode = async (
       isAssetHubPolkadot,
     );
     keystoreLocalDir = path.dirname(keystoreFiles[0]);
+
+    // When we have `override_eth_key` option
+    // seeds/mnemonics that should not leak into `zombie.json`;
+    if (node.accounts.ethKeyOverrideUsed) {
+      delete node.accounts.seed;
+      delete node.accounts.mnemonic;
+      delete node.accounts.ethKeyOverrideUsed;
+    }
   }
 
   // replace all network references in command

Original file line number	Diff line number	Diff line change
`@@ -115,6 +115,7 @@ export interface NodeConfig extends NodeCommonTypes {`
`115`	`115`	`prometheus_port?: number;`
`116`	`116`	`p2p_cert_hash?: string; // libp2p certhash to use with webrtc transport.`
`117`	`117`	`delay_network_settings?: DelayNetworkSettings;`
	`118`	`+ override_eth_key?: string;`
`118`	`119`	`}`
`119`	`120`
`120`	`121`	`export interface NodeCommonTypes {`