txgate_core/lib.rs
1//! # txgate-core
2//!
3//! Core types, traits, and error definitions for the `TxGate` signing service.
4//!
5//! ## Internal Crate Warning
6//!
7//! **This crate is an internal implementation detail of [`txgate`](https://crates.io/crates/txgate).**
8//!
9//! It is published to crates.io only because Cargo requires all dependencies to be
10//! published. The API is **unstable** and may change without notice between any versions,
11//! including patch releases.
12//!
13//! **Do not depend on this crate directly.** Instead:
14//! - For the signing server binary: `cargo install txgate`
15//! - For programmatic access: Open an issue at <https://github.com/luisjpf/txgate>
16//! to discuss a stable public API.
17//!
18//! This crate provides the foundational types shared across all `TxGate` crates:
19//!
20//! ## Modules
21//!
22//! - [`error`] - Error types and result aliases
23//! - [`types`] - Core data types ([`ParsedTx`], [`TxType`], [`PolicyResult`])
24//! - `traits` - Core trait definitions (planned)
25//! - `chain` - Chain identifier types (planned)
26//!
27//! ## Error Handling
28//!
29//! The crate provides comprehensive error types for all failure modes:
30//!
31//! ```rust
32//! use txgate_core::error::{TxGateError, ParseError, RpcErrorCode};
33//!
34//! fn example() -> Result<(), TxGateError> {
35//! // Parse errors automatically convert to TxGateError
36//! let err = ParseError::unsupported_chain("cosmos");
37//!
38//! // Get the RPC error code for JSON-RPC responses
39//! let txgate_err: TxGateError = err.into();
40//! let code = RpcErrorCode::from(&txgate_err);
41//! assert_eq!(code, RpcErrorCode::ChainNotSupported);
42//!
43//! Ok(())
44//! }
45//! ```
46//!
47//! ## Core Types
48//!
49//! The types module provides the foundational data structures:
50//!
51//! ```rust
52//! use txgate_core::{ParsedTx, TxType, PolicyResult, U256};
53//! use std::collections::HashMap;
54//!
55//! // Create a parsed transaction
56//! let tx = ParsedTx {
57//! hash: [0u8; 32],
58//! recipient: Some("0x742d35Cc...".to_string()),
59//! amount: Some(U256::from(1_500_000_000_000_000_000u64)),
60//! token: Some("ETH".to_string()),
61//! token_address: None,
62//! tx_type: TxType::Transfer,
63//! chain: "ethereum".to_string(),
64//! nonce: Some(42),
65//! chain_id: Some(1),
66//! metadata: HashMap::new(),
67//! };
68//!
69//! // Check transaction type
70//! assert!(tx.is_native_transfer());
71//!
72//! // Evaluate policy result
73//! let result = PolicyResult::Allowed;
74//! assert!(result.is_allowed());
75//! ```
76//!
77//! ## Features
78//!
79//! - `serde` - Enable serde serialization/deserialization
80//! - `std` - Enable standard library features (enabled by default)
81//!
82//! [`ParsedTx`]: types::ParsedTx
83//! [`TxType`]: types::TxType
84//! [`PolicyResult`]: types::PolicyResult
85
86#![forbid(unsafe_code)]
87#![warn(missing_docs)]
88#![warn(clippy::all)]
89#![warn(clippy::pedantic)]
90
91pub mod config;
92pub mod config_loader;
93pub mod error;
94pub mod signing;
95pub mod types;
96
97// Re-export commonly used error types at crate root for convenience
98pub use error::{
99 ConfigError, ParseError, PolicyError, Result, RpcErrorCode, SignError, StoreError, TxGateError,
100};
101
102// Re-export config types at crate root for convenience
103pub use config::{Config, ConfigBuilder, KeysConfig, PolicyConfig, ServerConfig};
104
105// Re-export config loader types at crate root for convenience
106pub use config_loader::{expand_path, load_config, ConfigLoader};
107
108// Re-export core types at crate root for convenience
109pub use types::{ParsedTx, PolicyResult, TxType};
110
111// Re-export signing types at crate root for convenience
112pub use signing::{
113 ChainParser, PolicyCheckResult, PolicyEngineExt, SignatureBytes, SignerExt, SigningError,
114 SigningResult, SigningService,
115};
116
117// Re-export U256 from alloy_primitives for working with amounts
118pub use alloy_primitives::U256;
119
120// Placeholder for future modules
121// pub mod traits;
122// pub mod chain;