Skip to main content

Crate walletkit

Crate walletkit 

Source
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

FeatureDefaultEnables
tracing✓tracing spans/events on key paths (redacted). Off → the shim compiles to no-ops.
redb✓The embedded RedbStateStore durable backend.
postgresThe networked PostgresStateStore backend.
pricingThe pricing seam: token-list metadata + Chainlink prices.
policy-moonpayThe 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::deps ports. 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; WalletKitError is the one umbrella every Wallet operation returns, classified for retry with a machine-readable ErrorKind.
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. One Wallet is one account (the signer defines it), so single-executor-per-account is structural. Host-driven: tick runs 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 alloy as 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.