Skip to main content

walletkit/
lib.rs

1// `--cfg docsrs` (set by docs.rs) turns on per-item `doc(cfg(...))` feature badges.
2#![cfg_attr(docsrs, feature(doc_cfg))]
3// Doc links must resolve to public items — no dangling or private-item links escape review.
4#![deny(rustdoc::broken_intra_doc_links, rustdoc::private_intra_doc_links)]
5// The no-panic house rule, enforced. Relaxed under `cfg(test)` so unit tests may `unwrap`.
6#![cfg_attr(
7    not(test),
8    deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)
9)]
10// Every public item must carry documentation.
11#![deny(missing_docs)]
12
13//! walletkit — a client-side ergonomic facade over [alloy] for wallet
14//! infrastructure and transaction execution.
15//!
16//! Hexagonal layout: [`core`] holds the domain and the object-safe ports
17//! ([`core::deps`]); [`adapters`] holds the concrete implementations behind those ports.
18//! You wire adapters into the [`Wallet`] facade and drive everything through it.
19//!
20//! Beyond sending and tracking transactions, it exposes read-only surfaces over the same
21//! resilient transport: [`ReadClient`](core::deps::ReadClient) (balances/metadata/allowances,
22//! Multicall3-batched), [`Wallet::dry_run`] → [`TxPreview`](core::wallet::TxPreview) (RPC-only
23//! simulation with decoded revert reasons), and [`EnsResolver`](core::deps::EnsResolver).
24//! Token metadata + prices are an opt-in `pricing` feature.
25//!
26//! [`AccountManager`](adapters::AccountManager) adds HD key management: BIP-39 seed
27//! generation/restore, multi-account BIP-44/Ledger-Live derivation, watch-only account
28//! xpubs, counterfactual [`predict_address`](core::accounts::predict_address), gap-limit
29//! account discovery (one batched round-trip per window), and encrypted keystore export.
30//!
31//! Start with [`Wallet::connect_http`] and `use walletkit::prelude::*;` — the [`prelude`]
32//! brings the facade, the port traits, and the common alloy value/unit types into scope.
33//!
34//! # Quickstart
35//!
36//! ```no_run
37//! use std::sync::Arc;
38//! use walletkit::prelude::*;
39//! use walletkit::adapters::{LocalSigner, SystemClock};
40//! use walletkit::adapters::policy::{DefaultPolicyEngine, TargetAllowlist};
41//!
42//! # async fn quickstart() -> Result<(), walletkit::WalletKitError> {
43//! let to = Address::from([0x22; 20]);
44//! let signer = LocalSigner::from_private_key("0x59c6…").unwrap();
45//! // The recipient is the only allowed target — the guardrail stays explicit.
46//! let policy = DefaultPolicyEngine::new(
47//!     vec![Box::new(TargetAllowlist::new([to]))],
48//!     Arc::new(SystemClock),
49//! );
50//! let wallet = Wallet::connect_http("http://localhost:8545", signer, policy)?;
51//!
52//! let intent = TxIntent::transfer(1, wallet.account(), to, parse_ether("0.01").unwrap());
53//! let handle = wallet.send(&intent).await?;
54//! # Ok(())
55//! # }
56//! ```
57//!
58//! # Feature flags
59//!
60//! | Feature | Default | Enables |
61//! |---|:---:|---|
62//! | `tracing` | ✓ | `tracing` spans/events on key paths (redacted). Off → the shim compiles to no-ops. |
63//! | `redb` | ✓ | The embedded `RedbStateStore` durable backend. |
64//! | `postgres` | | The networked `PostgresStateStore` backend. |
65//! | `pricing` | | The `pricing` seam: token-list metadata + Chainlink prices. |
66//! | `policy-moonpay` | | The MoonPay Open Wallet Standard engine with a sandboxed `wasip1` plugin runner. |
67//!
68//! With `--no-default-features` the crate builds down to the ports plus the
69//! [`InMemoryStateStore`](adapters::InMemoryStateStore) — the minimal dependency surface.
70//!
71//! # Design
72//!
73//! See the [`SPEC.md`](https://github.com/21r21a33333/walletkit/blob/main/SPEC.md) for the
74//! architecture, the phase roadmap, and the cross-cutting invariants (policy→sign binding,
75//! nonce fencing, reorg-aware finality).
76//!
77//! [alloy]: https://github.com/alloy-rs
78
79pub mod adapters;
80pub mod core;
81pub mod error;
82pub mod facade;
83pub mod prelude;
84pub mod types;
85pub mod units;
86
87pub(crate) mod obs;
88
89pub use error::{ErrorKind, WalletKitError};
90pub use facade::{Runner, Wallet, WalletBuilder};
91
92#[cfg(test)]
93pub(crate) mod testutils;