feat: deployer-from-mnemonic utility modes (--print-key, EVM⇄Substrate twin) + fix wrong documented prod twin

[hanwencheng]

What

Extends scripts/heima-deployer-from-mnemonic.sh with three standalone utility modes and fixes a wrong address in the docs.

New script modes

• --print-key — derive the private key from a mnemonic and print it to stdout only: nothing written to disk, no key-file comparison. Address/path/twin go to stderr so stdout stays pipeable. Safe for scanning --index N candidates when a derived address doesn't match the existing key file.
• --evm-to-substrate <0xADDR> — print the Heima Substrate twin of an EVM address (Frontier HashedAddressMapping<BlakeTwo256>: account32 = blake2_256("evm:" ‖ eth_bytes)) as JSON: raw 32-byte hex + SS58 prefix 31 (mainnet) / 131 (Paseo) / 42 (generic). The twin is the account you send HEI to when funding an EVM address. python3 stdlib only — no @polkadot deps, no foundry needed.
• --substrate-to-evm <SS58|0xHEX32> [--verify-evm 0xADDR] — checksum-verified SS58 decode + re-encodings. The EVM preimage cannot be computed back (one-way hash), so the honest reverse is verification: --verify-evm exits 0 iff the Substrate account IS that EVM address's twin.
• The normal mnemonic flow now also prints the derived address's Substrate twin (twin: line) — funding info at hand immediately.
• --help now prints the whole header via awk (no more stale hand-maintained sed line range).

Removed

• scripts/evm-to-substrate-address.mjs — superseded. It imported @polkadot/keyring/@polkadot/util-crypto which were never recorded in any package.json and never installed, so it could not run as shipped. The python replacement is output-identical: verified by installing the @polkadot deps in a sandbox and diffing — both produce 47hNCTi9… / 0x392331f7… for the prod deployer.

Doc fix (found during verification)

docs/spec/deployed-contracts.md listed the prod deployer's Substrate twin as 47NGSq6JE5ZSnymGNa4nFVjWbsuhTfoSKN2jtpk28mUyC1M3 — that is not the twin of 0xdE6449…63Bc. Two independent implementations (the @polkadot libs and the new python) agree the real twin is 47hNCTi9Jrs86atvDj9AhY67X2vQEDzzHAvzapKvUpxXz6EX. The old value is likely the mnemonic's sr25519 address — exactly the mix-up the old .mjs header warned about. HEI sent to it would not credit the deployer's EVM balance. Corrected with an explicit correction note.

docs/ci-setup.md §2 documents all the new modes with copy-paste examples.

Verification

• --evm-to-substrate 0xdE6449…63Bc output is byte-identical to the original @polkadot-based .mjs (run in a sandbox with deps installed)
• SS58 round-trip: decode(47hNCTi9…) → re-encode reproduces input exactly, checksum verified, prefix 31 parsed
• --verify-evm MATCH → exit 0, NO-MATCH → exit 1
• --print-key with the Anvil test mnemonic prints the canonical index-0 key; ls -la ~/.agentkeys snapshot before/after proves zero disk writes
• [ -n … ] && echo set-e footgun avoided (twin lines use if-form, so a python3-less box still prints the key)
• bash -n clean; no dangling references to the deleted .mjs

What landed

• scripts/heima-deployer-from-mnemonic.sh — all modes above
• scripts/evm-to-substrate-address.mjs — deleted (superseded)
• docs/spec/deployed-contracts.md — twin corrected + new command pointer
• docs/ci-setup.md — utility-modes section

What did NOT land

Nothing — all intended changes shipped.

🤖 Generated with Claude Code