neo3 1.0.1

# NeoRust

<p align="center">
  <img src="./assets/neo-rust-sdk-logo.svg" alt="NeoRust SDK logo" width="520">
</p>

[![Build & Test](https://github.com/r3e-network/NeoRust/actions/workflows/build-test.yml/badge.svg)](https://github.com/r3e-network/NeoRust/actions/workflows/build-test.yml)
[![Release](https://github.com/r3e-network/NeoRust/actions/workflows/release.yml/badge.svg)](https://github.com/r3e-network/NeoRust/actions/workflows/release.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Crates.io](https://img.shields.io/crates/v/neo3.svg)](https://crates.io/crates/neo3)
[![Documentation](https://docs.rs/neo3/badge.svg)](https://docs.rs/neo3)
[![MSRV](https://img.shields.io/badge/MSRV-1.70.0-blue)](https://blog.rust-lang.org/2023/06/01/Rust-1.70.0.html)

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**: 1.0.1 (Production Ready - Security Hardened)
- **Rust Version**: 1.70.0+
- **Platform Support**: Windows, macOS, Linux
- **Security**: Dependencies audited; no known CVEs, with tracked unmaintained transitive crates only
- **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 v1.0.x 🚀
- 🌐 **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 3.9 Ready** - Full support for Hardfork Echidna, Faun, and upcoming Gorgon

### Applications
- 🖥️ **CLI Tools** - Command-line interface for common blockchain operations

## Quick Start

Add NeoRust to your `Cargo.toml`:

```toml
[dependencies]
neo3 = "1.0.1"
```

## Basic Usage

### New Simplified API (v1.0.x+)

```rust
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)

```rust
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
- `no_std`, `sgx`: specialized environments

### WebSocket Real-time Events

Requires the `ws` feature:

```toml
neo3 = { version = "1.0.1", features = ["ws"] }
```

```rust
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

```rust
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

```rust
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)

```rust
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:

```bash
# 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
```bash
cargo build --workspace
```

## Documentation

- [Installation Guide](docs/guides/installation.md)
- [API Documentation](https://docs.rs/neo3)
- [WebSocket Guide](docs/guides/websocket.md)
- [HD Wallet Guide](docs/guides/hd-wallet.md)
- [Transaction Simulation Guide](docs/guides/transaction-simulation.md)
- [Examples](examples/)
- [CLI Documentation](neo-cli/README.md)
- [Migration Guide to v1.0](docs/guides/migration-v1.0.md)

## 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](examples/) for full code samples.

## License

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

## Testing

```bash
# 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

```bash
# 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 | Pre-1.0 | v1.0.x | 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 to v1.0

### Quick Migration

```rust
// 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](docs/guides/migration-v1.0.md) for detailed instructions.

## Performance Metrics

| Operation | Pre-1.0 | v1.0.x | 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