Ethereum Protocol
The Ethereum protocol exposes an EIP-1193 provider over a WalletPair encrypted channel. Frames use
the canonical eip155:<decimal chain ID> suffix; the EIP-155 value in that suffix
selects the request chain context and is authenticated by AEAD.
Envelope shapes
The encrypted plaintext is a JSON value encoded with the MessagePack profile. It is not a JSON-RPC
2.0 response object and has no jsonrpc field.
// Request (dApp → Wallet)
{ "id": "req-1", "method": "eth_getBalance", "params": ["0x…", "latest"] }
// Response (Wallet → dApp)
{ "id": "req-1", "result": "0x0" }
// Event (Wallet → dApp)
{ "event": "chainChanged", "data": "0x1" }An ID is a unique printable ASCII string of 1–128 bytes among outstanding requests. A response
reuses the exact ID and has exactly one of result or error. The receiver
rejects values that match more than one envelope shape.
Required methods
| Area | Methods |
|---|---|
| Accounts and chain | eth_requestAccounts, eth_accounts, eth_chainId, net_version |
| Permissions and network | wallet_switchEthereumChain, wallet_addEthereumChain, wallet_getPermissions, wallet_requestPermissions |
| Signing and sending | eth_sendTransaction, personal_sign, eth_signTypedData and v1/v3/v4, wallet_sendCalls, wallet_getCallsStatus |
EIP-5792 support also requires wallet_getCapabilities. Wallets may serve the listed
read-only RPC methods locally or through a trusted endpoint, but must never blindly forward
unknown methods or infer safety from an eth_ prefix.
Events
| Event | Data |
|---|---|
connect | { chainId: "0x1" } |
disconnect | An EIP-1193 ProviderRpcError |
chainChanged | New canonical hexadecimal chain ID |
accountsChanged | The complete eth_accounts array |
message | { type: string, data: unknown } |
Errors
| Code | Meaning |
|---|---|
4001 | User rejected the request. |
4100 | Method or account is not authorized. |
4200 | Method is not supported. |
4900 / 4901 | Provider or requested chain is disconnected. |
-32600 / -32602 / -32603 | Malformed request, invalid parameters, or internal failure. |
Wallet security requirements
- Authorize accounts per paired dApp origin; do not expose accounts before approval.
- Validate actual decoded account, chain, value, target, calldata, and typed-data domain before signing.
- Reject a signing address that is not currently authorized and warn on EIP-712 domain-chain conflicts.
- Validate chain metadata and RPC URLs independently; they are untrusted dApp input.
- Return a
-32005limit error when a valid response exceeds the 64 KiB plaintext bound.