feat: implement multi-wallet support, transaction simulation, automatic nonce management, and split ratio preflight fix

[willi-d7]

What this fixes

1. Automatic nonce management (Implement automatic nonce management #1029): Without automated nonce/sequence tracking and validation, transactions generated sequentially or concurrently risk nonce collisions, replay attacks, and out-of-order execution on-chain.
2. Transaction simulation before execution (Add transaction simulation before execution #1028): Transactions previously lacked pre-execution simulation with structured diagnostics, leading to unexpected on-chain transaction reverts, gas waste, and unclear panic messages.
3. Multi-wallet support (Implement multi-wallet support #1027): Wallet extension support was limited and lacked unified connectors for MetaMask, WalletConnect, and Ledger hardware devices, as well as safe fallback handling across providers.
4. Invalid recipient ratio legs pass split preflight validation (Bug: invalid recipient ratio legs pass split preflight validation #1012): validateSplitRatioSum() previously accepted individual out-of-range ratios (such as [-1, 2]) if their arithmetic sum was 1, and allowed NaN or opposite infinities to pass through, allowing splitExecutor() to proceed to capacity operations with corrupt shares.

What changed

• Automatic Nonce Management (src/nonceManager.ts):

  • Implemented NonceManager with per-account state tracking (currentNonce, lastUpdated, inFlightNonces).
  • Added auto-incrementing via acquireNextNonce() / consumeNonce() with peeking (peekNextNonce()) and rollback support (rollbackNonce()).
  • Implemented reset handling with resetNonce() (custom reset values, reason metadata, clearing replay cache) and on-chain sync via syncNonce().
  • Added strict validation before sending (validateBeforeSend(), validate()) detecting replay attack duplicates (DuplicateNonceError), stale nonces (StaleNonceError), nonce gaps (NonceGapError), and invalid values (InvalidNonceError).
  • Added event lifecycle subscriptions (acquired, committed, rolled_back, reset, validation_failed).

• Transaction Simulation (src/transactionSimulator.ts):

  • Implemented TransactionSimulator with structured requests (SimulationRequest) and reports (SimulationReport).
  • Added intelligent error detection classifying simulation failures into AUTH_FAILED, INSUFFICIENT_FUNDS, RESOURCE_EXHAUSTED, SEQUENCE_ERROR, STORAGE_ERROR, DEADLINE_EXPIRED, and CONTRACT_ERROR with actionable remediation suggestions.
  • Added resource consumption tracking (cpuInstructions, memoryBytes, minResourceFee) with automatic warnings when thresholds are exceeded.
  • Implemented multi-format report generation (markdown, text, json) and high-performance TTL caching for repeated simulation requests.

• Multi-Wallet Support (src/multiWallet.ts, src/wallets/adapters/MetaMaskAdapter.ts):

  • Designed unified WalletAdapter interface.
  • Implemented MetaMaskAdapter and MetaMaskConnector supporting window.ethereum, account change events, eth_requestAccounts, personal_sign, and typed errors (MetaMaskNotInstalledError, UserRejectedError, MetaMaskConnectionError).
  • Integrated MetaMask detection into WalletSessionManager.detect().
  • Implemented WalletConnectConnector wrapping WalletConnectAdapter with session management and signing.
  • Implemented LedgerConnector wrapping LedgerAdapter with hardware WebHID checks and pre-signing firmware verification.
  • Implemented MultiWalletManager with safe fallback handling (connectWithFallback()) that attempts providers in order, records detailed WalletAttemptLog diagnostics, and throws WalletFallbackExhaustedError if all fallbacks fail.

• Split Ratio Validation Fix (src/payments/splitExecutor.ts):

  • Updated validateSplitRatioSum() to assert that each leg ratio is finite and in [0, 1] before verifying the total aggregate within SPLIT_RATIO_TOLERANCE.
  • Fails closed with SplitRatioSumError on invalid legs or non-finite sums (NaN, opposite infinities) prior to any subentry capacity checks or network activity.

• Root SDK Exports (src/index.ts):

  • Exported MultiWalletManager, connectors, adapters, and errors for Implement multi-wallet support #1027.
  • Exported TransactionSimulator, simulation structs, and errors for Add transaction simulation before execution #1028.
  • Exported NonceManager, nonce structs, and errors for Implement automatic nonce management #1029.

Testing

All relevant unit tests pass with zero failures:

• test/splitExecutor.invalid-ratios.test.ts (10/10 passed)
• test/nonceManager.test.ts (25/25 passed)
• test/transactionSimulator.test.ts (19/19 passed)
• test/multiWallet.test.ts (18/18 passed)
• test/walletSessionManager.test.ts (26/26 passed)
• test/walletconnect.test.ts (14/14 passed)
• test/ledgerAdapter.test.ts (6/6 passed)
• Default test suite npm test (110/110 passed)

Total: 228 passing tests across all related test suites.

Issues

closes #1029
closes #1028
closes #1027
closes #1012

[drips-wave]

@willi-d7 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits