feat: add browser wallet support

[rplusq]

Summary

• Refactors browser wallet support into a dedicated crate for better modularity
• Implements browser wallet integration (MetaMask, etc.) for Foundry tools
• Addresses issue feat(periphery): support to invoke metamask #6556
• Adds support for transaction sending, contract deployment, and message signing

Motivation

Browser wallets like MetaMask are widely used in the Ethereum ecosystem. This PR adds native support for browser wallets in Foundry, making it more accessible to developers who prefer using their browser wallets for signing transactions.

Solution

This implementation follows the Moccasin pattern with a local HTTP server that bridges between the CLI and browser wallet:

1. HTTP Server Bridge: When --browser flag is used, Foundry starts a local server and opens a browser window
2. Queue-based Communication: Transactions and signing requests are queued and processed asynchronously
3. Web Interface: Clean, minimal interface that handles wallet connections and transaction approvals

What's Implemented

Commands with Full Support

• ✅ cast send --browser - Send transactions via browser wallet
• ✅ forge create --browser - Deploy contracts via browser wallet
• ✅ cast wallet sign --browser - Message signing with both personal_sign and eth_signTypedData_v4

Commands with Limited/No Support

• ❌ cast mktx --browser - Shows clear error (browser wallets can't create offline transactions)
• ❌ forge script --browser - Not implemented (architectural incompatibility explained below)

Architectural Decisions

New Dedicated Crate

Browser wallet functionality has been extracted into a dedicated foundry-browser-wallet crate for:

• Better separation of concerns
• Easier maintenance and testing
• Clear API boundaries

Why forge script is not supported

Forge script's execution model is fundamentally incompatible with browser wallets:

• Forge script uses separate sign/broadcast steps for transaction management
• Browser wallets only support atomic eth_sendTransaction (sign+send together)
• This mismatch makes it impossible to integrate without major architectural changes

Users who need browser wallet deployments should use forge create instead.

Implementation Details

• Uses axum for the HTTP server
• Follows EIP-1193 standard for wallet interaction
• Includes retry logic for wallet detection
• Comprehensive error handling and timeouts
• Full test suite with integration tests

API Documentation

The browser wallet HTTP API and message types are fully documented in crates/browser-wallet/README.md. The API includes:

• HTTP Endpoints: RESTful API for communication between CLI and browser

  • /api/heartbeat - Health check and connection status
  • /api/transaction/pending - Retrieve pending transactions
  • /api/transaction/response - Submit transaction results
  • /api/sign/pending - Retrieve pending signing requests
  • /api/sign/response - Submit signing results
  • /api/network - Get network configuration
  • /api/account - Update wallet connection status

• Message Types: Strongly-typed request/response formats

  • BrowserTransaction - Transaction request wrapper
  • SignRequest - Message signing requests
  • TransactionResponse - Transaction execution results
  • SignResponse - Signing operation results

• Standards Compliance:

  • EIP-1193 for Ethereum Provider JavaScript API
  • EIP-712 for typed data signing
  • JSON-RPC 2.0 for communication protocol

See the full API reference in the browser-wallet README.

Testing

• Run cargo test -p foundry-browser-wallet to run browser wallet tests
• Comprehensive integration test suite covering:
  • Connection management
  • Transaction handling
  • Message signing
  • Security features
  • State persistence
• Manual testing done with MetaMask and Rabby

Breaking Changes

None - this is a new feature that doesn't affect existing functionality.

Closes #6556

Files Changed

Refactoring (Browser Wallet Extraction)

• crates/browser-wallet/ - New dedicated crate for browser wallet functionality
  • Cargo.toml - Crate configuration
  • README.md - API documentation and usage guide
  • src/lib.rs - Public API and message types
  • src/server.rs - HTTP server implementation
  • src/signer.rs - Alloy signer trait implementation
  • src/state.rs - Shared state management
  • src/error.rs - Error types
  • src/assets.rs - Embedded web assets
  • src/assets/web/ - Enhanced web interface (HTML, CSS, JS)
  • src/tests.rs - Unit tests
  • tests/integration/ - Comprehensive integration tests

Updates to Existing Files

• Cargo.lock - Updated dependencies
• Cargo.toml - Added browser-wallet crate to workspace
• crates/cast/src/cmd/send.rs - Updated to use new browser wallet crate
• crates/wallets/Cargo.toml - Removed browser wallet dependencies
• crates/wallets/src/ - Removed browser wallet code (moved to dedicated crate)

Testing Instructions

# Test cast send
cast send 0x... --value 0.1ether --browser

# Test forge create
forge create MyContract --browser

# Test message signing
cast wallet sign "Hello World" --browser

# Run tests
cargo test -p foundry-browser-wallet

Video Demo

cast wallet sign --browser

demo.on.cast.wallet.sign.--browser.mp4

[mattsse]

this looks decent,

not opposed to this but what I'm missing from this is some API specs or references.

[rplusq]

Thanks for the feedback, @mattsse. Applied.