NeoRust

A comprehensive, production-ready Rust SDK for the Neo N3 blockchain platform. NeoRust provides an enterprise-grade toolkit with simplified APIs, real-time features, and professional developer tools for building blockchain applications.

📊 Project Status

• Version: 0.5.0 (Production Ready - Enterprise Features)
• Rust Version: 1.70.0+
• Platform Support: Windows, macOS, Linux
• Security: All dependencies audited, 0 known vulnerabilities
• Coverage: Comprehensive testing with property-based tests
• Production Readiness: Enterprise-grade with WebSocket support, HD wallets, and transaction simulation
• Performance: <100ms WebSocket latency, <10ms HD derivation, 50-70% code reduction

Features

Core Features

• 🔐 Cryptography - Complete cryptographic functions including key generation, signing, and verification
• 💼 Wallet Management - Create, import, and manage Neo wallets with hardware wallet support
• 🔗 RPC Client - Full-featured RPC client for Neo N3 node interaction
• 📦 Smart Contracts - Deploy, invoke, and interact with Neo N3 smart contracts
• 🪙 Token Support - Native NEP-17 token operations and custom token support
• 🌐 Network Support - Mainnet, Testnet, and custom network configurations

New in v0.5.0 🚀

• 🌐 WebSocket Support - Real-time blockchain events with auto-reconnection
• 🔑 HD Wallet (BIP-39/44) - Hierarchical deterministic wallets with mnemonic phrases
• 🔮 Transaction Simulation - Preview effects and estimate gas before submission
• 🎯 High-Level SDK API - Simplified interface reducing code by 50-70%
• 🧙 Interactive CLI Wizard - Guided blockchain operations with visual feedback
• 📦 Project Templates - Quick-start templates for dApps, tokens, and smart contracts
• 🔧 Unified Error Handling - Consistent errors with recovery suggestions
• ⚡ Performance Optimized - <100ms event processing, efficient caching

Applications

• 🖥️ CLI Tools - Command-line interface for common blockchain operations
• 🖼️ GUI Application - Desktop GUI application built with Tauri and React

Quick Start

Add NeoRust to your Cargo.toml:

[dependencies]
neo3 = "0.5.0"

Basic Usage

New Simplified API (v0.5.0+)

use neo3::sdk::Neo;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Quick connection to TestNet
    let neo = Neo::testnet().await?;
    
    // Get balance with automatic error handling
    let balance = neo.get_balance("NbTiM6h8r99kpRtb428XcsUk1TzKed2gTc").await?;
    println!("Balance: {} NEO, {} GAS", balance.neo, balance.gas);
    
    // Custom configuration with all features
    let neo = Neo::builder()
        .network(Network::MainNet)
        .timeout(Duration::from_secs(30))
        .websocket_url("wss://mainnet.neo.org/ws")
        .enable_transaction_simulation()
        .build()
        .await?;
    
    Ok(())
}

WebSocket Real-time Events

use neo3::sdk::websocket::{WebSocketClient, SubscriptionType};

// Connect to WebSocket
let mut ws = WebSocketClient::new("ws://localhost:10332/ws").await?;
ws.connect().await?;

// Subscribe to new blocks
let handle = ws.subscribe(SubscriptionType::NewBlocks).await?;

// Process events
if let Some(mut rx) = ws.take_event_receiver() {
    while let Some((sub_type, event)) = rx.recv().await {
        println!("New event: {:?}", event);
    }
}

HD Wallet with BIP-39

use neo3::sdk::hd_wallet::HDWallet;

// Generate new HD wallet with 24-word mnemonic
let wallet = HDWallet::generate(24, None)?;
println!("Mnemonic: {}", wallet.mnemonic_phrase());

// Derive multiple accounts
let mut wallet = wallet;
let account1 = wallet.derive_account("m/44'/888'/0'/0/0")?;
let account2 = wallet.derive_account("m/44'/888'/0'/0/1")?;

// Import from existing mnemonic
let wallet = HDWallet::from_phrase(
    "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
    None,
    Language::English
)?;

Transaction Simulation

use neo3::sdk::transaction_simulator::TransactionSimulator;

// Create simulator
let mut simulator = TransactionSimulator::new(client);

// Simulate before sending
let result = simulator.simulate_script(&script, signers).await?;

if result.success {
    println!("Estimated gas: {} GAS", result.gas_consumed as f64 / 100_000_000.0);
    println!("State changes: {:?}", result.state_changes);
    
    // Check for warnings
    for warning in result.warnings {
        println!("⚠️ {}", warning.message);
    }
    
    // Get optimization suggestions
    for suggestion in result.suggestions {
        println!("💡 {}", suggestion.description);
    }
} else {
    println!("Transaction would fail: {:?}", result.vm_state);
}

Traditional API (still supported)

use neo3::prelude::*;

// Create a new wallet
let wallet = Wallet::new().unwrap();

// Connect to Neo testnet
let client = RpcClient::new("https://testnet1.neo.coz.io:443").unwrap();

// Get account balance
let balance = client.get_balance(&wallet.address()).await?;
println!("Balance: {} NEO", balance.neo);

Components

Core SDK (neo3)

The main Rust SDK providing all blockchain functionality.

CLI Tool (neo-cli)

Interactive command-line interface with wizard mode:

# Launch interactive wizard
neo-cli wizard

# Generate a new project from template
neo-cli generate --template nep17-token my-token

# Traditional commands
neo-cli wallet create
neo-cli wallet balance <address>
neo-cli transaction send --to <address> --amount 10 --token NEO

GUI Application (neo-gui)

Desktop application with modern React UI. Note: Requires GTK libraries on Linux.

Building

Core SDK and CLI

cargo build --workspace --exclude neo-gui

GUI Application (requires additional dependencies)

Linux (Ubuntu/Debian):

sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libayatana-appindicator3-dev librsvg2-dev
cd neo-gui && npm install && cargo build

macOS and Windows:

cd neo-gui && npm install && cargo build

Documentation

• Getting Started Guide
• API Documentation
• WebSocket Guide
• HD Wallet Guide
• Transaction Simulation Guide
• Examples
• CLI Documentation
• GUI Documentation
• Migration Guide v0.4 → v0.5

Examples

Explore our comprehensive examples:

• Basic Operations: Wallet creation, token transfers, balance queries
• Smart Contracts: Deploy and interact with Neo N3 contracts
• WebSocket Events: Real-time blockchain monitoring and event handling
• HD Wallets: BIP-39/44 mnemonic wallets with account derivation
• Transaction Simulation: Gas estimation and state change preview
• Advanced Features: Multi-sig wallets, hardware wallet integration
• DeFi Integration: Interact with popular Neo DeFi protocols
• Neo X: Cross-chain bridge operations

See the examples directory for full code samples.

License

Licensed under MIT license (LICENSE or http://opensource.org/licenses/MIT)

Testing

# Run all tests
cargo test --workspace

# Run specific component tests
cargo test -p neo3
cargo test -p neo-cli

# Run integration tests
cargo test --test integration_tests

CI/CD

The project uses streamlined GitHub Actions workflows:

GitHub Workflows

• build-test.yml - Unified build, test, and quality checks

  • Multi-platform testing (Linux, Windows, macOS)
  • Rust formatting and clippy checks
  • Security audit on every PR
  • Code coverage reporting
  • Optional Neo GUI builds

• release.yml - Automated release process

  • Triggered by version tags (v*..)
  • Cross-platform binary builds
  • Automatic crates.io publishing
  • GitHub release creation with artifacts
  • Release notes extraction from CHANGELOG

Running Tests Locally

# Format check
cargo fmt --all -- --check

# Clippy lints
cargo clippy --all-targets --all-features -- -D warnings

# Run all tests
cargo test --all-features

# Security audit
cargo audit

# Build documentation
cargo doc --no-deps --all-features

Feature Comparison

Feature	v0.4.x	v0.5.0	Improvement
Connection Setup	5-10 lines	1 line	90% reduction
Balance Check	Manual RPC + parsing	Single method	70% reduction
Error Handling	Basic errors	Recovery suggestions	Enhanced UX
Real-time Events	Not supported	WebSocket with auto-reconnect	New feature
HD Wallets	Not supported	BIP-39/44 compliant	New feature
Gas Estimation	Manual calculation	Automatic simulation	95% accuracy
Transaction Preview	Not available	Full state change preview	New feature
Project Setup	Manual	Template generation	80% faster
CLI Experience	Commands only	Interactive wizard	Enhanced UX

Migration from v0.4 to v0.5

Quick Migration

// Old (v0.4)
let provider = HttpProvider::new("https://testnet1.neo.org:443")?;
let client = RpcClient::new(provider);
let result = client.invoke_function(&contract, "balanceOf", vec![address], None).await?;
let balance = parse_balance(result)?; // Manual parsing

// New (v0.5)
let neo = Neo::testnet().await?;
let balance = neo.get_balance(address).await?; // Automatic parsing

Breaking Changes

1. Error Types: All errors now use NeoError with recovery suggestions
2. Module Structure: Some modules reorganized for better discoverability
3. Async Patterns: Standardized async/await usage across all APIs

See the full migration guide for detailed instructions.

Performance Metrics

Operation	v0.4.x	v0.5.0	Improvement
WebSocket Events	N/A	<100ms	New
HD Account Derivation	N/A	<10ms	New
Transaction Simulation	N/A	<200ms	New
Balance Query	300-500ms	200-300ms	40% faster
Token Transfer	15-20 lines	5-7 lines	65% less code
Error Recovery	Manual	Automatic suggestions	Enhanced

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• All tests pass (cargo test --workspace)
• Code is formatted (cargo fmt)
• No clippy warnings (cargo clippy -- -D warnings)
• Documentation is updated
• CI checks pass locally before pushing

Security

For security issues, please email security@r3e.network instead of using the issue tracker.

Acknowledgments

• Neo Foundation for the Neo N3 blockchain
• Rust community for excellent tooling
• All contributors who have helped shape this project