Crate neo3

Expand description

§NeoRust SDK v1.0.1

A production-ready Rust SDK for the Neo N3 blockchain with enterprise-grade features.

§Features

This crate provides several feature flags to customize functionality:

futures: Enables async/futures support for asynchronous blockchain operations. This is recommended for most applications that need to interact with the Neo blockchain without blocking.
ledger: Enables hardware wallet support via Ledger devices. When enabled, you can use Ledger hardware wallets for transaction signing and key management. This feature provides an additional security layer by keeping private keys on dedicated hardware.
aws: ⚠️ DISABLED in v1.0.1 due to security vulnerabilities in rusoto dependencies. Will be re-enabled in a future 1.x release with the modern AWS SDK. For AWS KMS integration, use the legacy v0.3.x line or wait for updated AWS SDK support.
sgx: Enables Intel SGX (Software Guard Extensions) support for running Neo operations in secure enclaves. This feature enables no_std compilation and provides hardware-based security for sensitive operations like key management and transaction signing.
no_std: Enables no_std compilation for embedded systems and SGX environments. This feature removes dependencies on the standard library, allowing the SDK to run in constrained environments with custom allocators.

To enable specific features in your project, modify your Cargo.toml as follows:

[dependencies]
neo3 = { version = "1.0.1", features = ["futures", "ledger"] }

You can disable default features with:

neo3 = { version = "1.0.1", default-features = false, features = ["futures"] }

§Overview

NeoRust is a complete SDK designed to make Neo N3 blockchain development in Rust intuitive, type-safe, and productive. The library provides full support for all Neo N3 features and follows Rust best practices for reliability and performance.

§New in v1.0.x

WebSocket Support: Real-time blockchain events with automatic reconnection
HD Wallets (BIP-39/44): Deterministic wallet generation and derivation
Transaction Simulation: Preview fees, VM state, and state changes before sending
High-Level SDK API: Simplified entrypoint (Neo) for common operations
Enhanced Error Handling: Consistent NeoError with recovery suggestions

§Core Modules

NeoRust is organized into specialized modules, each handling specific aspects of Neo N3:

neo_builder: Transaction construction and script building
neo_clients: Neo node interaction and RPC client implementations
neo_codec: Serialization and deserialization of Neo data structures
neo_config: Configuration for networks and client settings
neo_contract: Smart contract interaction and token standards
neo_crypto: Cryptographic primitives and operations
neo_error: Unified error handling
neo_fs: NeoFS distributed storage system integration
neo_protocol: Core blockchain protocol implementations
neo_types: Core data types and primitives for Neo N3
neo_utils: General utility functions
neo_wallets: Wallet management for Neo N3
neo_x: Neo X EVM compatibility layer

§Quick Start

Import all essential types and traits using the prelude:

use neo3::prelude::*;

§Complete Example

Here’s a comprehensive example showcasing common operations with the NeoRust SDK:

use neo3::neo_protocol::{Account, AccountTrait};
use neo3::neo_clients::{HttpProvider, RpcClient, APITrait};

async fn neo_example() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Neo TestNet
    let provider = HttpProvider::new("https://testnet1.neo.org:443")?;
    let client = RpcClient::new(provider);
     
    // Get basic blockchain information
    let block_height = client.get_block_count().await?;
    println!("Connected to Neo TestNet at height: {}", block_height);
     
    // Create a new wallet account
    let account = Account::create()?;
    println!("New account created:");
    println!("  Address:     {}", account.get_address());
    println!("  Script Hash: {}", account.get_script_hash());
     
    // Get version information
    let version = client.get_version().await?;
    println!("Node version: {}", version.user_agent);
     
    Ok(())
}

§Usage Examples

§Connecting to a Neo N3 node

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Neo N3 MainNet
    let provider = HttpProvider::new("https://mainnet1.neo.org:443")?;
    let client = RpcClient::new(provider);
     
    // Get basic blockchain information
    let block_count = client.get_block_count().await?;
    println!("Current block count: {}", block_count);
     
    let version = client.get_version().await?;
    println!("Node version: {}", version.user_agent);
     
    Ok(())
}

§Creating and sending a transaction

use neo3::neo_clients::{HttpProvider, RpcClient, APITrait};
use neo3::neo_protocol::{Account, AccountTrait};
use neo3::neo_types::{ScriptHash, ContractParameter, ScriptHashExtension};
use neo3::neo_builder::{ScriptBuilder, TransactionBuilder, AccountSigner};
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the JSON-RPC provider
    let provider = HttpProvider::new("https://testnet1.neo.org:443")?;
    let client = RpcClient::new(provider);

    // Create accounts for the sender and recipient
    // Load sender key from an environment variable to avoid hardcoding secrets.
    let sender_wif = std::env::var("NEO_WIF")?;
    let sender = Account::from_wif(&sender_wif)?;
    let recipient = ScriptHash::from_address("NbTiM6h8r99kpRtb428XcsUk1TzKed2gTc")?;

    // Get the GAS token contract
    let gas_token_hash = ScriptHash::from_str("d2a4cff31913016155e38e474a2c06d08be276cf")?;
     
    // Build the transaction using the ScriptBuilder
    let script = ScriptBuilder::new()
        .contract_call(
            &gas_token_hash,
            "transfer",
            &[
                ContractParameter::h160(&sender.get_script_hash()),
                ContractParameter::h160(&recipient),
                ContractParameter::integer(1_0000_0000), // 1 GAS (8 decimals)
                ContractParameter::any(),
            ],
            None,
        )?
        .to_bytes();
     
    // Create and configure the transaction
    let mut tx_builder = TransactionBuilder::with_client(&client);
    tx_builder
        .set_script(Some(script))
        .set_signers(vec![AccountSigner::called_by_entry(&sender)?.into()])?
        .valid_until_block(client.get_block_count().await? + 5760)?; // Valid for ~1 day

    // Sign the transaction
    let mut tx = tx_builder.sign().await?;

    // Send the transaction
    let result = tx.send_tx().await?;
    println!("Transaction sent: {}", result.hash);

    // Wait for the transaction to be confirmed
    println!("Waiting for confirmation...");
    tx.track_tx(10).await?;
    println!("Transaction confirmed!");

    // Get the application log
    let app_log = tx.get_application_log(&client).await?;
    println!("Application log: {:?}", app_log);

    Ok(())
}

§Interacting with a smart contract

use neo3::neo_clients::{HttpProvider, RpcClient, APITrait};
use neo3::neo_types::ScriptHash;
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Neo N3 TestNet
    let provider = HttpProvider::new("https://testnet1.neo.org:443")?;
    let client = RpcClient::new(provider);
     
    // Get the NEO token contract
    let neo_token = ScriptHash::from_str("ef4073a0f2b305a38ec4050e4d3d28bc40ea63f5")?;
     
    // Call a read-only method (doesn't require signing)
    let result = client
        .invoke_function(&neo_token, "symbol".to_string(), vec![], None)
        .await?;
     
    // Parse the result
    if let Some(item) = result.stack.first() {
        println!("NEO Token Symbol: {:?}", item);
    }
     
    // Get the total supply
    let supply_result = client
        .invoke_function(&neo_token, "totalSupply".to_string(), vec![], None)
        .await?;
     
    println!("Total Supply Result: {:?}", supply_result);
     
    Ok(())
}

§Working with NEP-17 tokens

use neo3::neo_clients::{HttpProvider, RpcClient, APITrait};
use neo3::neo_protocol::{Account, AccountTrait};
use neo3::neo_types::{ScriptHash, ContractParameter};
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Neo N3 TestNet
    let provider = HttpProvider::new("https://testnet1.neo.org:443")?;
    let client = RpcClient::new(provider);
     
    // Create an account from WIF (Wallet Import Format)
    let wif = std::env::var("NEO_WIF")?;
    let account = Account::from_wif(&wif)?;
     
    // Get account information
    println!("Account address: {}", account.get_address());
    println!("Account script hash: {}", account.get_script_hash());
     
    // Get GAS token balance for the account
    let gas_token = ScriptHash::from_str("d2a4cff31913016155e38e474a2c06d08be276cf")?;
     
    let balance_result = client
        .invoke_function(
            &gas_token,
            "balanceOf".to_string(),
            vec![ContractParameter::h160(&account.get_script_hash())],
            None,
        )
        .await?;
     
    // Parse the balance result
    if let Some(item) = balance_result.stack.first() {
        println!("GAS Balance: {:?}", item);
    }
     
    Ok(())
}

§Using the Neo Name Service (NNS)

use neo3::neo_clients::{HttpProvider, RpcClient, APITrait};
use neo3::neo_types::{ContractParameter, ScriptHash};
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Neo N3 TestNet
    let provider = HttpProvider::new("https://testnet1.neo.org:443")?;
    let client = RpcClient::new(provider);
     
    // NNS contract on TestNet (use MainNet hash for production)
    let nns_contract = ScriptHash::from_str("50ac1c37690cc2cfc594472833cf57505d5f46de")?;
     
    // Check if a name is available
    let available_result = client
        .invoke_function(
            &nns_contract,
            "isAvailable".to_string(),
            vec![ContractParameter::string("myname.neo".to_string())],
            None,
        )
        .await?;
     
    if let Some(item) = available_result.stack.first() {
        println!("Is 'myname.neo' available: {:?}", item);
    }
     
    Ok(())
}

For more usage examples, refer to the examples directory in the repository.

§Project Structure

NeoRust
├── examples
│   ├── neo_nodes          - Examples for connecting to Neo nodes
│   ├── neo_transactions   - Examples for creating and sending transactions
│   ├── neo_smart_contracts - Examples for interacting with smart contracts
│   ├── neo_wallets        - Examples for wallet management
│   ├── neo_nep17_tokens   - Examples for working with NEP-17 tokens
│   └── neo_nns            - Examples for using the Neo Name Service
└── src
    ├── neo_builder        - Transaction and script building utilities
    ├── neo_clients        - Neo node interaction clients (RPC and WebSocket)
    ├── neo_codec          - Encoding and decoding for Neo-specific data structures
    ├── neo_config         - Network and client configuration management
    ├── neo_contract       - Smart contract interaction abstractions
    ├── neo_crypto         - Neo-specific cryptographic operations
    ├── neo_protocol       - Neo network protocol implementation
    ├── neo_sgx            - SGX support for secure enclave execution
    ├── neo_types          - Core Neo ecosystem data types
    └── neo_wallets        - Neo asset and account management

§Module Overview

neo_builder: Transaction and script building utilities.
- Transaction construction and signing
- Script building for contract calls
- Network fee calculation
neo_clients: Neo node interaction clients.
- HTTP, WebSocket, and IPC providers
- JSON-RPC client implementation
- Event subscription and notification handling
neo_codec: Encoding and decoding for Neo-specific data structures.
- Binary serialization and deserialization
- Neo VM script encoding
neo_config: Network and client configuration management.
- Network magic numbers
- Client settings
neo_contract: Smart contract interaction abstractions.
- Contract invocation and deployment
- NEP-17 token standard implementation
- Native contracts (GAS, NEO, etc.)
- Neo Name Service (NNS) support
neo_crypto: Neo-specific cryptographic operations.
- Key generation and management
- Signing and verification
- Hashing functions
neo_protocol: Neo network protocol implementation.
- Account management
- Address formats and conversions
neo_types: Core Neo ecosystem data types.
- Script hashes
- Contract parameters
- Block and transaction types
- NNS name types
neo_wallets: Neo asset and account management.
- Wallet creation and management
- NEP-6 wallet standard support
- Account import/export
- Wallet backup and recovery

For detailed information, consult the documentation of each module.

Re-exports§

pub use crate::neo_types::deserialize_address_or_script_hash;
pub use crate::neo_types::deserialize_h256;
pub use crate::neo_types::deserialize_h256_option;
pub use crate::neo_types::deserialize_hash_map_h160_account;
pub use crate::neo_types::deserialize_script_hash;
pub use crate::neo_types::deserialize_script_hash_option;
pub use crate::neo_types::deserialize_url_option;
pub use crate::neo_types::serialize_address_or_script_hash;
pub use crate::neo_types::serialize_h256;
pub use crate::neo_types::serialize_h256_option;
pub use crate::neo_types::serialize_hash_map_h160_account;
pub use crate::neo_types::serialize_script_hash;
pub use crate::neo_types::serialize_script_hash_option;
pub use crate::neo_types::serialize_url_option;
pub use crate::neo_types::var_size;
pub use crate::neo_types::vec_to_array32;
pub use crate::neo_types::Address;
pub use crate::neo_types::AddressOrScriptHash;
pub use crate::neo_types::Base64Encode;
pub use crate::neo_types::Bytes;
pub use crate::neo_types::ContractIdentifiers;
pub use crate::neo_types::ContractManifest;
pub use crate::neo_types::ContractParameter;
pub use crate::neo_types::ContractParameterType;
pub use crate::neo_types::ContractState;
pub use crate::neo_types::InvocationResult;
pub use crate::neo_types::NNSName;
pub use crate::neo_types::NefFile;
pub use crate::neo_types::OpCode;
pub use crate::neo_types::OperandSize;
pub use crate::neo_types::ParameterValue;
pub use crate::neo_types::ScriptHash;
pub use crate::neo_types::ScriptHashExtension;
pub use crate::neo_types::ScryptParamsDef;
pub use crate::neo_types::StackItem;
pub use crate::neo_types::StringExt;
pub use crate::neo_types::TypeError;
pub use crate::neo_types::VMState;
pub use crate::neo_types::serde_with_utils::deserialize_boolean_expression;
pub use crate::neo_types::serde_with_utils::deserialize_bytes;
pub use crate::neo_types::serde_with_utils::deserialize_h160;
pub use crate::neo_types::serde_with_utils::deserialize_hardforks;
pub use crate::neo_types::serde_with_utils::deserialize_hashmap_address_u256;
pub use crate::neo_types::serde_with_utils::deserialize_hashmap_u256_hashset_h256;
pub use crate::neo_types::serde_with_utils::deserialize_hashmap_u256_hashset_u256;
pub use crate::neo_types::serde_with_utils::deserialize_hashmap_u256_vec_u256;
pub use crate::neo_types::serde_with_utils::deserialize_hashset_u256;
pub use crate::neo_types::serde_with_utils::deserialize_map;
pub use crate::neo_types::serde_with_utils::deserialize_private_key;
pub use crate::neo_types::serde_with_utils::deserialize_public_key;
pub use crate::neo_types::serde_with_utils::deserialize_public_key_option;
pub use crate::neo_types::serde_with_utils::deserialize_scopes;
pub use crate::neo_types::serde_with_utils::deserialize_vec_script_hash;
pub use crate::neo_types::serde_with_utils::deserialize_vec_script_hash_option;
pub use crate::neo_types::serde_with_utils::deserialize_wildcard;
pub use crate::neo_types::serde_with_utils::serialize_boolean_expression;
pub use crate::neo_types::serde_with_utils::serialize_bytes;
pub use crate::neo_types::serde_with_utils::serialize_h160;
pub use crate::neo_types::serde_with_utils::serialize_hashmap_address_u256;
pub use crate::neo_types::serde_with_utils::serialize_hashmap_u256_hashset_h256;
pub use crate::neo_types::serde_with_utils::serialize_hashmap_u256_hashset_u256;
pub use crate::neo_types::serde_with_utils::serialize_hashmap_u256_vec_u256;
pub use crate::neo_types::serde_with_utils::serialize_hashset_u256;
pub use crate::neo_types::serde_with_utils::serialize_map;
pub use crate::neo_types::serde_with_utils::serialize_private_key;
pub use crate::neo_types::serde_with_utils::serialize_public_key;
pub use crate::neo_types::serde_with_utils::serialize_public_key_option;
pub use crate::neo_types::serde_with_utils::serialize_scopes;
pub use crate::neo_types::serde_with_utils::serialize_vec_script_hash;
pub use crate::neo_types::serde_with_utils::serialize_vec_script_hash_option;
pub use crate::neo_types::serde_with_utils::serialize_wildcard;
pub use crate::neo_types::contract::ContractMethodToken;
pub use crate::neo_types::contract::ContractNef;
pub use crate::neo_types::contract::NativeContractState;
pub use crate::neo_types::contract::NeoVMStateType;
pub use crate::neo_types::serde_value::ValueExtension;
pub use futures;
pub use coins_ledger;

Modules§

builder: Neo Builder Module
codec
config
constants: Constants used throughout the Neo N3 SDK.
crypto: Neo Crypto
extensions
neo_builder: Neo Builder Module
neo_clients: Neo Clients
neo_codec
neo_config
neo_contract: Neo Contract Module
neo_crypto: Neo Crypto
neo_error
neo_fs: Neo File Storage (NeoFS)
neo_protocol: Neo Protocol
neo_types: Neo Types (v1.0.1)
neo_utils: Neo Utilities
neo_wallets: Neo Wallets
neo_x: Neo X
prelude: Convenient imports for commonly used types and traits.
protocol: Neo Protocol
providers: Neo Clients
sdk: High-level SDK API for simplified Neo blockchain interaction
wallets: Neo Wallets
x: Neo X

Macros§

ensure: Macro for early return with context
neo3_error: Macro for creating context-aware errors

Constants§

VERSION: Current version of the neo3 crate.

Crate neo3

Crate neo3 Copy item path

§NeoRust SDK v1.0.1

§Features

§Overview

§New in v1.0.x

§Core Modules

§Quick Start

§Complete Example

§Usage Examples

§Connecting to a Neo N3 node

§Creating and sending a transaction

§Interacting with a smart contract

§Working with NEP-17 tokens

§Using the Neo Name Service (NNS)

§Project Structure

§Module Overview

Re-exports§

Modules§

Macros§

Constants§

Crate neo3