tenzro_wallet/
lib.rs

1//! MPC Wallet System for Tenzro Network
2//!
3//! This crate provides auto-provisioned threshold wallets for Tenzro Network,
4//! an AI-Native, Agentic, Tokenized Settlement Layer blockchain.
5//!
6//! # Key Features
7//!
8//! - **Seamless Onboarding**: Auto-provisioned MPC wallets - no seed phrases to manage
9//! - **Threshold Signatures**: 2-of-3 (configurable) multi-party signing
10//! - **Multi-Asset Support**: TNZO (native settlement), plus USDC, USDT, and major tokens
11//! - **Encrypted Storage**: Password-protected keystore for key shares (Argon2id)
12//! - **Transaction Validation**: Chain ID, nonce, gas, address, and data size checks
13//! - **Signature Verification**: Automatic post-signing cryptographic verification
14//! - **Nonce Management**: Per-address sequential nonces with replay protection
15//! - **Transaction History**: Full lifecycle tracking with filtering and pagination
16//! - **Address Book**: Contact management with name resolution and tag filtering
17//! - **State Sync**: On-chain balance/nonce synchronization via ChainStateProvider
18//! - **Transaction Builder**: Type-safe builder pattern with auto gas estimation
19//! - **Key Zeroization**: Sensitive key material zeroized on drop
20//!
21//! # Architecture
22//!
23//! The wallet system uses Multi-Party Computation (MPC) to distribute key shares
24//! across multiple parties. A threshold number of shares (e.g., 2 out of 3) are
25//! required to generate signatures, providing security without single points of failure.
26//!
27//! # Examples
28//!
29//! ## Provisioning a new wallet
30//!
31//! ```no_run
32//! use tenzro_wallet::service::TenzroWalletService;
33//! use tenzro_wallet::traits::WalletService;
34//!
35//! # async fn example() -> tenzro_wallet::error::Result<()> {
36//! let service = TenzroWalletService::new()?;
37//!
38//! // Auto-provision a new MPC wallet
39//! let wallet = service.provision_wallet().await?;
40//!
41//! println!("Wallet created: {}", wallet.wallet_id);
42//! println!("Address: {}", wallet.address);
43//! println!("Threshold: {}-of-{}", wallet.threshold, wallet.total_shares);
44//! # Ok(())
45//! # }
46//! ```
47//!
48//! ## Building and signing a transaction
49//!
50//! ```no_run
51//! use tenzro_wallet::service::TenzroWalletService;
52//! use tenzro_wallet::traits::WalletService;
53//! use tenzro_wallet::builder::TransactionBuilder;
54//! use tenzro_types::primitives::{Address, Nonce};
55//!
56//! # async fn example() -> tenzro_wallet::error::Result<()> {
57//! let service = TenzroWalletService::new()?;
58//! let wallet = service.provision_wallet().await?;
59//!
60//! // Build a validated transfer transaction. `from_wallet_pq` binds the
61//! // wallet's classical address AND its ML-DSA-65 verifying key into the
62//! // transaction so the hybrid signature stays self-consistent.
63//! let tx = TransactionBuilder::default_chain()
64//!     .from_wallet_pq(&wallet)
65//!     .to(Address::new([2u8; 32]))
66//!     .nonce(service.next_nonce(&wallet.address))
67//!     .transfer(1000)
68//!     .build_validated()?;
69//!
70//! // Sign (validates, signs with MPC threshold + ML-DSA-65, verifies both legs)
71//! let signature = service.sign_transaction(&wallet.wallet_id, &tx).await?;
72//! println!(
73//!     "Signature: classical={} bytes, pq={} bytes",
74//!     signature.classical.len(),
75//!     signature.pq.len(),
76//! );
77//! # Ok(())
78//! # }
79//! ```
80
81pub mod asset_manager;
82pub mod balance;
83pub mod builder;
84pub mod contacts;
85pub mod error;
86pub mod history;
87pub mod keystore;
88pub mod mpc_signing;
89pub mod nonce;
90pub mod pluggable_signer;
91pub mod provisioning;
92pub mod rpc_provider;
93pub mod service;
94pub mod signing;
95pub mod state_sync;
96pub mod traits;
97pub mod userop;
98pub mod validation;
99pub mod wallet;
100
101// Re-export commonly used types
102pub use asset_manager::{AssetManager, DefaultAssetConfig, SharedAssetManager};
103pub use balance::{Balance, BalanceProvider, BalanceTracker};
104pub use builder::TransactionBuilder;
105pub use contacts::{AddressBook, Contact};
106pub use error::{Result, WalletError};
107pub use history::{HistoryFilter, TransactionHistory, TxDirection, TxRecord, TxStatus};
108pub use keystore::Keystore;
109pub use mpc_signing::{MpcSigner, TransactionSigner};
110pub use nonce::NonceManager;
111pub use provisioning::{ProvisioningConfig, WalletProvisioner};
112pub use service::{TenzroWalletService, WalletServiceConfig};
113pub use signing::HybridSignatureBytes;
114pub use state_sync::{ChainStateProvider, LocalStateProvider, WalletStateSync};
115pub use traits::WalletService;
116pub use userop::{
117    encode_user_op_json, pack_validator_signature, user_op_hash, UserOp, UserOpBuilder,
118};
119pub use validation::{TransactionValidator, ValidationConfig};
120pub use wallet::{KeyShare, MpcWallet, WalletId};
121
122#[cfg(test)]
123mod tests {
124    use super::*;
125
126    #[test]
127    fn test_crate_exports() {
128        // Ensure main types are accessible
129        let _ = ProvisioningConfig::default();
130        let _ = WalletServiceConfig::default();
131        let _ = WalletId::new();
132        let _ = ValidationConfig::default();
133        let _ = NonceManager::new();
134        let _ = TransactionHistory::new();
135        let _ = AddressBook::new();
136    }
137}
tenzro_wallet/lib.rs

tenzro_wallet/
lib.rs
