Expand description
walletkit — a client-side ergonomic facade over alloy for wallet infrastructure and transaction execution.
Hexagonal layout: core holds the domain and the object-safe ports
(core::deps); adapters holds the concrete implementations behind those ports.
You wire adapters into the Wallet facade and drive everything through it.
Beyond sending and tracking transactions, it exposes read-only surfaces over the same
resilient transport: ReadClient (balances/metadata/allowances,
Multicall3-batched), Wallet::dry_run → TxPreview (RPC-only
simulation with decoded revert reasons), and EnsResolver.
Token metadata + prices are an opt-in pricing feature.
AccountManager adds HD key management: BIP-39 seed
generation/restore, multi-account BIP-44/Ledger-Live derivation, watch-only account
xpubs, counterfactual predict_address, gap-limit
account discovery (one batched round-trip per window), and encrypted keystore export.
Start with Wallet::connect_http and use walletkit::prelude::*; — the prelude
brings the facade, the port traits, and the common alloy value/unit types into scope.
§Quickstart
use std::sync::Arc;
use walletkit::prelude::*;
use walletkit::adapters::{LocalSigner, SystemClock};
use walletkit::adapters::policy::{DefaultPolicyEngine, TargetAllowlist};
let to = Address::from([0x22; 20]);
let signer = LocalSigner::from_private_key("0x59c6…").unwrap();
// The recipient is the only allowed target — the guardrail stays explicit.
let policy = DefaultPolicyEngine::new(
vec![Box::new(TargetAllowlist::new([to]))],
Arc::new(SystemClock),
);
let wallet = Wallet::connect_http("http://localhost:8545", signer, policy)?;
let intent = TxIntent::transfer(1, wallet.account(), to, parse_ether("0.01").unwrap());
let handle = wallet.send(&intent).await?;§Feature flags
| Feature | Default | Enables |
|---|---|---|
tracing | ✓ | tracing spans/events on key paths (redacted). Off → the shim compiles to no-ops. |
redb | ✓ | The embedded RedbStateStore durable backend. |
postgres | The networked PostgresStateStore backend. | |
pricing | The pricing seam: token-list metadata + Chainlink prices. | |
policy-moonpay | The MoonPay Open Wallet Standard engine with a sandboxed wasip1 plugin runner. |
With --no-default-features the crate builds down to the ports plus the
InMemoryStateStore — the minimal dependency surface.
§Design
See the SPEC.md for the
architecture, the phase roadmap, and the cross-cutting invariants (policy→sign binding,
nonce fencing, reorg-aware finality).
Re-exports§
pub use error::ErrorKind;pub use error::WalletKitError;pub use facade::Runner;pub use facade::Wallet;pub use facade::WalletBuilder;
Modules§
- adapters
- Concrete implementations of the
core::depsports. One module per adapter; multi-file adapters (policy,store,transport) get a subdirectory. - core
- Domain core: wallet primitives (
wallet), account-management types (accounts), and the object-safe ports (deps) adapters implement. - error
- The public error taxonomy (SPEC §5.5). Per-port
{Trait}Errors remain the internal contracts;WalletKitErroris the one umbrella everyWalletoperation returns, classified for retry with a machine-readableErrorKind. - facade
Wallet— the composition root: wires the eight adapters into one account’s runtime (the send pipeline + the tracking executor) behind a small public API. OneWalletis one account (the signer defines it), so single-executor-per-account is structural. Host-driven:tickruns one recover→confirm→escalate pass; a background runner is opt-in sugar.- prelude
- A curated glob-import for the common path:
use walletkit::prelude::*;. - types
- Common alloy value types, re-exported so callers can name them without adding
alloyas a direct dependency — which would risk a version skew against walletkit’s pinned alloy. - units
- Ether/unit conversion helpers, re-exported from alloy rather than reinvented.