Add Stark key registration tool for USER_UNREGISTERED withdrawals

[ermyas]

Summary

Users whose Stark key is not the decimal form of their Ethereum address were registered off-chain by Immutable X. The bridge has no ethKey on record for them, so withdraw() reverts with USER_UNREGISTERED even though getWithdrawalBalance shows funds. Registration (registerSender / registerEthAddress, live since StarkExchangeMigrationV2) needs a Stark-curve signature from the Stark private key. Immutable X derived that key from a wallet signature, so users cannot produce it through Etherscan.

This PR adds tools/stark-key-registration, a local web page for Ethereum Mainnet that:

1. asks the wallet to sign the Immutable X key message and re-derives the Stark key in the browser;
2. checks the bridge for pending withdrawals of each token in config/operate/mainnet/imx_tokens.json (getWithdrawalBalance needs an asset ID, so each token is queried);
3. signs the registration payload bound to the connected address and submits registerSender;
4. finalises each pending withdrawal once the key is registered to the connected wallet.

It also updates docs/finalise-pending-withdrawals.md with:

• a getEthKey check step;
• a USER_UNREGISTERED section pointing to the tool;
• the registration gas cost;
• a troubleshooting table.

Key derivation

src/lib/derivation.ts reimplements generateLegacyStarkPrivateKey from @imtbl/core-sdk 3.6.1. For about 1 in 30 wallets the first grinding round is rejected, and the SDK's three grinding variants then disagree. The SDK chose between them by querying the Immutable X API (/v1/users), which now returns 404, so the SDK fails for those users. The tool computes every candidate and uses the one holding funds on the bridge. Every candidate derives from the wallet's own signature, so a derivation error yields a key with no funds, never another user's key.

Safeguards

• Funds go only to the connected wallet. registerSender uses msg.sender as the owner, and the page withdraws only for keys registered to the connected wallet.
• Keys and signatures stay in the tab. The Stark private key exists only inside deriveAccounts. The CSP sets connect-src 'none', and chain access goes through the wallet extension.
• Environment checks. The page refuses to run unless served from 127.0.0.1/localhost. It checks for chain 1 and implementation 0x273b65a7231321D4ee47a4c47408Ef43517455Ec.
• Simulation. Every transaction is simulated with eth_call before it is sent.
• Dependencies. Versions are pinned. npm ci --omit=dev installs vite plus four runtime libraries (ethers, @scure/bip32, @scure/starknet, @noble/hashes), and npm audit is clean for the full tree. @imtbl/core-sdk is not a dependency: its outputs are recorded as test vectors by test/vectors/generate-sdk-vectors.ts, which installs it with npm i --no-save. Socket flagged the SDK's axios@0.26.1 and ws@8.18.0; those alerts are resolved by this change.
• Disclaimers. The page, the tool README and the guide all state that the tool is unaudited and provided as-is, and give anti-phishing guidance.

Registration gas

registerSender uses about 7.9M gas, because StarkCurveECDSA.verify does elliptic-curve arithmetic in Solidity. That is about 0.0006 ETH at 0.07 gwei and 0.04 ETH at 5 gwei. It fits within the 60M block limit and the 16.7M per-transaction cap. With too little balance or gas limit, wallets and simulators report the transaction as likely to fail, and the trace stops at the modexp precompile. The docs describe this.

Testing override

?allow-registration-without-funds offers registration for unregistered keys with no pending withdrawals, so registration can be tested end to end on mainnet with a test wallet. It is not linked from the page, shows a testing-mode banner when set, and is documented in the tool README's Development section.

Test plan

• npm run typecheck
• npm audit: 0 vulnerabilities.
• npm test: 12 unit tests.
  • Derivation equals the outputs of @imtbl/core-sdk 3.6.1 recorded in test/vectors/sdk-3.6.1.json. This covers typical wallets, and the exact candidate set for ambiguous wallets across every API-resolved branch, including a three-candidate wallet. Public keys match the SDK's Stark signer.
  • Registration signatures pass a BigInt port of the contract's StarkCurveECDSA.verify, including its r/s⁻¹ bounds, and fail for another address.
• ETH_RPC_URL=… npm run test:fork: 9 tests against the deployed bridge on an anvil fork.
  • Register and withdraw ETH and USDC.
  • Recover funds held by a non-primary candidate.
  • Signature replay from another wallet is rejected.
  • A key registered elsewhere is refused.
  • No withdrawal before registration.
  • Changed-implementation and non-mainnet detection.
  • The account from the originating support ticket (0.45 ETH, unregistered) reads correctly.
• ETH_RPC_URL=… npm run test:e2e: 7 Playwright tests of the built page on a fork, using a stub wallet that follows MetaMask's event ordering and chain ID validation.
  • Full flow and the no-funds path.
  • Switching from another chain.
  • Wallet events before and after connecting.
  • RPC failure and retry.
  • The testing override.
  • The block on hosted copies.
  • No requests beyond the page's own files, and no CSP violations.
• Mutation checks: altering a grinding variant, the registration prefix, the switch chain ID or the wallet-event handling makes the corresponding suite fail.
• Manual run with MetaMask against a mainnet fork: connect, network switch, sign, derive, balance reads, and the registerSender prompt. The issues found in this run are fixed in 9bfe72a.
• The registerSender calldata MetaMask produced, run with eth_call on real mainnet from the signing address, succeeds. The same calldata from another address reverts INVALID_STARK_SIGNATURE.
• Confirmed registration on mainnet with a funded test wallet.
• Manual run with Rabby.

🤖 Generated with Claude Code

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report