walletkit
A Rust wallet-infrastructure library: one ergonomic facade over alloy for sending EVM transactions safely — keys that never leave a swappable backend, un-bypassable policy guardrails, and a transaction lifecycle that survives stuck txs and reorgs.
It is a client-side facade, not a custody service: it integrates MPC/TEE signers, relayers, bundlers, and paymasters as pluggable backends behind narrow traits rather than operating any of them.
See SPEC.md for the full design specification: architecture, the 7-phase roadmap, locked decisions, and cross-cutting invariants.
Install
The crates.io package is walletkit-rs; the library imports as walletkit:
use *;
Quickstart
use walletkit::prelude::*; brings the facade, the port traits, and the common alloy
value/unit types into scope. Wallet::connect_http wires the transport, signer, and policy
in one call — the policy stays explicit (the guardrail is never defaulted away):
use Arc;
use *;
use ;
use ;
let to = from;
let signer = from_private_key?;
// The recipient is the only allowed target.
let policy = new;
let wallet = connect_http?;
let intent = transfer;
let handle = wallet.send.await?;
Runnable end-to-end examples live in examples/: cargo run --example send_eth,
read_balance, resolve_ens, hd_accounts, preview_and_validate. For dev/tests,
Wallet::connect_http_dev(url, signer) skips the policy with a loud, allow-all default.
Preview before sending: wallet.dry_run(&intent) (what happens on-chain) and
wallet.validate(&intent) (would the policy allow it).
RPC layer — eRPC recommended
walletkit's Transport reuses alloy's transport layers (retry/backoff + multi-endpoint
failover) and adds no bespoke resilience. For production, we recommend running
eRPC as your RPC layer and pointing walletkit at it
with Transport::url(erpc_url). eRPC owns the RPC-management catalog — failover,
hedging, reorg-aware caching, request dedup, cross-upstream quorum, rate-limits, and
per-method overrides — so walletkit stays thin and you configure RPC policy in one place.
Without eRPC, Transport::builder(primary).fallbacks(rest).build() (or
Transport::from_config) gives in-process failover across multiple endpoints.
Reading, previewing & names
Beyond sending, walletkit exposes read-only surfaces over the same resilient Transport,
so reads inherit its failover/retry:
ReadClient—chain_id/code/is_contract, native balance, ERC-20 (balance/allowance/metadata), and ERC-721/1155 reads for known contracts.balances(account, &[tokens])folds the native balance and each token'sbalanceOfinto one Multicall3 round-trip, with a per-tokenResultso one non-conforming token can't fail the scan. Metadata toleratesbytes32name/symbol (MKR/DAI).Wallet::dry_run(&intent)→TxPreview— an RPC-only pre-sign simulation: gas (advisory), success or a decoded revert reason, EIP-2930 access list, and return data. A would-revert tx is a successful preview with aRevertoutcome, not an error.EnsResolver—resolve_name/reverse_lookup(forward-verified) /text_record/avatar. Offchain (CCIP-Read) names surface as a typed error rather than being followed.pricingfeature (opt-in) —TokenMetadataSource(Uniswap token-list) andPriceSource(Chainlink, per-feed staleness); core stays vendor-free. Enable withfeatures = ["pricing"].
use ;
use ReadClient;
let transport = url?;
let read = new;
// One Multicall3 round-trip: native + each token, failure-isolated per token.
let overview = read.balances.await?;
println!;
Reads and ENS are standalone (built from a Transport, targeting any address);
Wallet::dry_run is the one wallet-bound convenience.
Accounts (HD keys, discovery, prediction)
AccountManager is the seed-owning HD factory. It generates or restores a BIP-39 mnemonic
(fail-closed OS CSPRNG, zeroized in memory, redacted from logs) and derives accounts under
it. Derived signers plug straight into Wallet::builder — no facade change.
- Derivation —
account(index)/account_at_path(path)andsigner(index)under a selectablePathScheme(Bip44Standardm/44'/60'/0'/0/{i}vs Ledger Livem/44'/60'/{i}'/0/0), with an optional BIP-39 passphrase. - Watch-only —
account_xpub(account)hands out an account-level xpub;derive_addressderives receive addresses from it without the seed. predict_address— counterfactual CREATE2 smart-account address + ERC-4337/6492 deploy data (predict_address_checkedalso reports whether it's deployed);safe_salthelper.- Discovery —
discover(&[rpc], opts)scans the seed with a BIP-44 gap limit, probing each window in one JSON-RPC batch per chain (Rpc::account_activity) and unioning "used" across chains; results flagpartial/hit_max_index. - Backup —
LocalSigner::export_keystorewrites an encrypted EIP-2335 / Web3 Secret Storage keystore (load it back withfrom_keystore). No raw-mnemonic export.
use AccountManager;
use WordCount;
let manager = generate?; // fresh seed, retained for backup
let signer = manager.signer?; // m/44'/60'/0'/0/0
let wallet = builder.build;
Status
Pre-1.0 and evolving (minor releases may break, per the changelog). The Phase-1 EVM execution core is complete: transaction execution with policy-gated signing, durable state and crash recovery, a resilient RPC transport, reads/preview/ENS/pricing, and HD account management. See SPEC.md for the full roadmap.