NeoRust

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

📊 Project Status

• Version: 1.4.0
• Rust Version: 1.83.0+
• Neo Version: Neo N3 compatible
• Platform Support: Linux verified locally; Windows and macOS are intended targets and should be validated in your CI before release
• Security: Dependency auditing via cargo deny; wallet exports use authenticated encryption
• Coverage: Comprehensive testing with property-based tests
• Production Readiness: Core wallet, cryptography, RPC, WebSocket, and simulation paths are tested; hardware devices, SGX/no_std, and live broadcasts require environment-specific validation
• 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

Highlights

• 🌉 Neo X EVM Integration - Full ethers-rs compatibility with unified cross-chain EcosystemClient
• 🛡️ Anti-MEV Support - Built-in secure mempool routing for Neo X to prevent front-running
• 🌐 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
• 🆕 Neo v3.9.1 Compatible - Full support for latest Neo N3 protocols including Hardfork Echidna, Faun, and Gorgon

Applications

• 🖥️ CLI Tools - Command-line interface for common blockchain operations

Quick Start

Add NeoRust to your Cargo.toml:

[dependencies]
neo3 = "1.4.0"

Basic Usage

Simplified API

use neo3::sdk::{Neo, Network};
use std::time::Duration;

#[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))
        .retries(3)
        .cache(true)
        .build()
        .await?;
    
    Ok(())
}

Choose Your Transport (HTTP / WS / IPC / Mock)

use neo3::neo_clients::{HttpProvider, RpcClient};

// 1) HTTP (default, no extra feature flags)
let http = HttpProvider::new("https://testnet1.neo.org:443")?;
let client = RpcClient::new(http);

// 2) Modern WebSocket client (enable the `ws` feature)
#[cfg(feature = "ws")]
{
    use neo3::neo_clients::rpc::transports::Ws;
    let ws = Ws::connect("wss://testnet1.neo.org:443/ws").await?;
    let client = RpcClient::new(ws);
}

// 3) IPC (enable the `ipc` feature)
#[cfg(feature = "ipc")]
	{
	    use neo3::neo_clients::rpc::transports::Ipc;
	    let ipc = Ipc::connect("/tmp/neo.ipc").await?;
	    let client = RpcClient::new(ipc);
	}

// 4) Offline-friendly mock (enable the `mock` feature; great for tests/CI)
#[cfg(feature = "mock")]
{
    use neo3::neo_clients::MockClient;
    let mut mock = MockClient::new().await;
    mock.mock_get_block_count(1_000).await;
    mock.mount_mocks().await;
    let client = mock.into_client();
}

Feature Flags

• ws: enable the modern WebSocket transport
• ipc: enable IPC (Unix domain sockets / Windows named pipes)
• legacy-ws: legacy WebSocket compatibility layer (fallback)
• mock: enable MockClient and in-memory mocking helpers
• ledger, yubi: opt into hardware wallet support; feature gates compile, but real devices must be tested before production use
• mock-hsm: enables the YubiHSM mock backend for tests
• no_std, sgx: experimental compile-gated specialized environments; not certified as general no_std target support

WebSocket Real-time Events

Requires the ws feature:

neo3 = { version = "1.4.0", features = ["ws"] }

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);
}

Neo X & EVM Integration

NeoRust natively supports Neo X (the EVM-compatible sidechain) and bridges the gap between NeoVM and EVM environments via ethers-rs.

use neo3::sdk::unified::EcosystemClient;
use neo3::neo_x::NeoXWallet;

// Create a randomized secure EVM wallet
let wallet = NeoXWallet::create_random();

// Initialize an Anti-MEV protected EcosystemClient for Neo X
let client = EcosystemClient::new_neox_anti_mev(wallet);

// Query balance using standard ethers-rs providers underneath
let balance = client.get_balance().await?;
println!("EVM Balance: {} Wei", balance);

// Easily bridge funds back to an N3 address
let tx_hash = client.bridge_to_other_chain("NXX...YourN3Address", "1000000000").await?;
println!("Bridge Tx: {}", tx_hash);

Traditional API (still supported)

use neo3::neo_clients::{APITrait, HttpProvider, RpcClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Neo TestNet
    let provider = HttpProvider::new("https://testnet1.neo.coz.io:443")?;
    let client = RpcClient::new(provider);

    // Query basic chain state (works without a wallet)
    let block_count = client.get_block_count().await?;
    println!("Block height: {}", block_count.saturating_sub(1));

    Ok(())
}

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

# Common commands
neo-cli wallet create --path my-wallet.json
neo-cli network connect --network testnet
neo-cli network status
neo-cli de-fi token NEO

Building

Core SDK and CLI

cargo build --workspace

Documentation

• Installation Guide
• API Documentation
• WebSocket Guide
• HD Wallet Guide
• Transaction Simulation Guide
• Examples
• CLI Documentation
• Migration Guide to v1.0

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
• Live RPC (optional): Set NEO_RPC_URL to point examples at your preferred node; otherwise they run offline-friendly paths.

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

• 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

Migration to v1.0

Quick Migration

// Pre-1.0
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

// v1.0
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

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