CoinUtils - Privacy Pool Coin Utilities
A modular Rust application for managing privacy pool coins, including generation, withdrawal, and association set management.
Features
- Coin Generation: Create new privacy pool coins with cryptographic commitments
- Coin Withdrawal: Generate SNARK inputs for coin withdrawals with merkle proofs
- Association Set Management: Manage association sets for privacy pool operations
- Modular Architecture: Clean separation of concerns with well-defined modules
- Comprehensive Testing: Unit tests and integration tests
- Logging Support: Configurable logging with different levels
Architecture
The application is organized into the following modules:
Core Modules
types/: Data structures for coins, state files, and SNARK inputscrypto/: Cryptographic operations including Poseidon hashing and conversionsmerkle/: Merkle tree operations for withdrawals and association setsio/: File I/O operations and serializationcli/: Command-line interface and argument parsingerror/: Custom error types and error handling
Configuration
config.rs: Application constants and configuration values
Usage
Generate a Coin
stellar-coinutils generate my_pool_scope coin.json
Withdraw a Coin
stellar-coinutils withdraw coin.json state.json association.json withdrawal.json
Update Association Set
stellar-coinutils updateAssociation association.json "1234567890..."
File Formats
Coin File Format
{
"coin": {
"value": "1000000000",
"nullifier": "...",
"secret": "...",
"label": "...",
"commitment": "..."
},
"commitment_hex": "0x..."
}
State File Format
{
"commitments": ["commitment1", "commitment2", ...],
"scope": "pool_scope"
}
Association Set File Format
{
"labels": ["label1", "label2", "label3", "label4"],
"scope": "pool_scope",
"root": "merkle_tree_root"
}
Development
Running Tests
cargo test
Running Integration Tests
cargo test --test integration_tests
Building
cargo build --release
Logging
The application supports configurable logging. Set the RUST_LOG environment variable to control log levels:
RUST_LOG=debug stellar-coinutils generate my_scope coin.json
Available log levels: error, warn, info, debug, trace
Dependencies
- Soroban SDK: Stellar smart contract development
- Poseidon: Cryptographic hash function
- Lean IMT: Incremental Merkle Tree implementation
- Clap: Command-line argument parsing
- Serde: Serialization/deserialization
- ThisError: Error handling
- Log/Env Logger: Logging support
Error Handling
The application uses a custom error type hierarchy with proper error propagation and user-friendly error messages. All operations return Result<T, CoinUtilsError> for consistent error handling.
Testing
The project includes:
- Unit Tests: In each module for testing individual components
- Integration Tests: End-to-end testing of complete workflows
- Test Data: Sample files for testing different scenarios