Struct TransactionBuilder

pub struct TransactionBuilder<'a, P: JsonRpcProvider + 'static> { /* private fields */ }

Implementations

impl<'a, P: JsonRpcProvider + 'static> TransactionBuilder<'a, P>

pub fn signers(&self) -> &Vec<Signer>

pub fn additional_network_fee(&self) -> &u64

pub fn additional_system_fee(&self) -> &u64

pub fn attributes(&self) -> &Vec<TransactionAttribute>

pub fn script(&self) -> &Option<Bytes>

impl<'a, P: JsonRpcProvider + 'static> TransactionBuilder<'a, P>

pub fn set_additional_network_fee(&mut self, val: u64) -> &mut Self

pub fn set_additional_system_fee(&mut self, val: u64) -> &mut Self

pub fn set_script(&mut self, val: Option<Bytes>) -> &mut Self

impl<'a, P: JsonRpcProvider + 'static> TransactionBuilder<'a, P>

pub const BALANCE_OF_FUNCTION: &'static str = "balanceOf"

pub const DUMMY_PUB_KEY: &'static str = "02ec143f00b88524caf36a0121c2de09eef0519ddbe1c710a00f0e2663201ee4c0"

pub fn new() -> Self

Creates a new TransactionBuilder instance with default values.

Returns

A new TransactionBuilder instance with default values.

Examples

use neo3::neo_builder::TransactionBuilder;
use neo3::neo_clients::HttpProvider;

let tx_builder: TransactionBuilder<'_, HttpProvider> = TransactionBuilder::default();

pub fn with_client(client: &'a RpcClient<P>) -> Self

Creates a new TransactionBuilder instance with a client reference.

Arguments

• client - A reference to an RPC client for network operations.

Returns

A new TransactionBuilder instance with the specified client.

Examples

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

let provider = HttpProvider::new("https://testnet1.neo.org:443").unwrap();
let client = RpcClient::new(provider);
let tx_builder = TransactionBuilder::with_client(&client);

pub fn version(&mut self, version: u8) -> &mut Self

Sets the version of the transaction.

Arguments

• version - The transaction version (typically 0 for Neo N3).

Returns

A mutable reference to the TransactionBuilder for method chaining.

Examples

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

let provider = HttpProvider::new("https://testnet1.neo.org:443").unwrap();
let client = RpcClient::new(provider);
let mut tx_builder = TransactionBuilder::with_client(&client);
tx_builder.version(0);

pub fn nonce(&mut self, nonce: u32) -> Result<&mut Self, TransactionError>

Sets the nonce of the transaction.

The nonce is a random number used to prevent transaction duplication.

Arguments

• nonce - A random number to prevent transaction duplication.

Returns

A Result containing a mutable reference to the TransactionBuilder for method chaining, or a TransactionError if the nonce is invalid.

Examples

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

let provider = HttpProvider::new("https://testnet1.neo.org:443").unwrap();
let client = RpcClient::new(provider);
let mut tx_builder = TransactionBuilder::with_client(&client);
tx_builder.nonce(1234567890).unwrap();

pub fn valid_until_block( &mut self, block: u32, ) -> Result<&mut Self, TransactionError>

Sets the block height until which the transaction is valid.

In Neo N3, transactions have a limited validity period defined by block height. This helps prevent transaction replay attacks and cleans up the memory pool.

Arguments

• block - The block height until which the transaction is valid.

Returns

A Result containing a mutable reference to the TransactionBuilder for method chaining, or a TransactionError if the block height is invalid.

Examples

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = HttpProvider::new("https://testnet1.neo.org:443").unwrap();
    let client = RpcClient::new(provider);
     
    let current_height = client.get_block_count().await?;
     
    let mut tx_builder = TransactionBuilder::with_client(&client);
    tx_builder.valid_until_block(current_height + 5760)?; // Valid for ~1 day
     
    Ok(())
}

pub fn first_signer( &mut self, sender: &Account, ) -> Result<&mut Self, TransactionError>

pub fn first_signer_by_hash( &mut self, sender: &H160, ) -> Result<&mut Self, TransactionError>

pub fn extend_script(&mut self, script: Vec<u8>) -> &mut Self

pub async fn call_invoke_script( &self, ) -> Result<InvocationResult, TransactionError>

pub async fn build(&mut self) -> Result<Transaction<'_, P>, TransactionError>

Builds a transaction from the current builder configuration

Returns

A Result containing the built transaction or a TransactionError

Examples

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = HttpProvider::new("https://testnet1.neo.org:443").unwrap();
    let client = RpcClient::new(provider);
     
    let mut tx_builder = TransactionBuilder::with_client(&client);
    tx_builder.version(0)
              .nonce(1234567890)?
              .valid_until_block(100)?;
     
    let tx = tx_builder.build().await?;
     
    Ok(())
}

pub async fn get_unsigned_tx( &mut self, ) -> Result<Transaction<'_, P>, TransactionError>

pub async fn sign(&mut self) -> Result<Transaction<'_, P>, BuilderError>

Signs the transaction with the provided signers.

This method creates an unsigned transaction, signs it with the appropriate signers, and returns the signed transaction. For account signers, it uses the account’s private key to create a signature. For contract signers, it creates a contract witness.

Returns

A Result containing the signed Transaction if successful, or a BuilderError if an error occurs during signing.

Errors

Returns an error if:

• The transaction cannot be built (see get_unsigned_tx)
• A multi-signature account is used (these require manual signing)
• An account does not have a private key
• Witness creation fails

Examples

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = HttpProvider::new("https://testnet1.neo.org:443").unwrap();
    let client = RpcClient::new(provider);
     
    // Create an account for signing
    let account = Account::from_wif("YOUR_WIF_HERE")?;
     
    // Create a proper contract invocation script
    let contract_hash = neo3::neo_types::ScriptHash::from_str("0xd2a4cff31913016155e38e474a2c06d08be276cf")?; // GAS
    let from_address = account.get_script_hash();
    let to_address = neo3::neo_types::ScriptHash::from_str("0x0000000000000000000000000000000000000000")?;
    let amount = 1_000_000i64;
    let mut script_builder = ScriptBuilder::new();
    script_builder.contract_call(
        &contract_hash,
        "transfer",
        &[
            ContractParameter::from(from_address),
            ContractParameter::from(to_address),
            ContractParameter::integer(amount),
            ContractParameter::any()
        ],
        None
    )?;
    let script = script_builder.to_bytes();
     
    // Create and configure the transaction
    let mut tx_builder = TransactionBuilder::with_client(&client);
    tx_builder.extend_script(script);
    let account_signer = AccountSigner::called_by_entry(&account)?;
    tx_builder.set_signers(vec![account_signer.into()])?;
    tx_builder.valid_until_block(client.get_block_count().await? + 5760)?; // Valid for ~1 day

    // Sign the transaction
    let signed_tx = tx_builder.sign().await?;
     
    // Send the transaction to the network
    let tx_response = signed_tx.send_tx().await?;
    println!("Transaction sent: {:?}", tx_response);
     
    Ok(())
}

pub fn set_signers( &mut self, signers: Vec<Signer>, ) -> Result<&mut Self, TransactionError>

Sets the signers for the transaction.

Signers are entities that authorize the transaction. They can be accounts, contracts, or other entities that can provide a signature or verification method.

Arguments

• signers - A vector of Signer objects representing the transaction signers.

Returns

A Result containing a mutable reference to the TransactionBuilder for method chaining, or a TransactionError if there are duplicate signers or if adding the signers would exceed the maximum allowed number of attributes.

Examples

use neo3::neo_builder::{TransactionBuilder, Signer, AccountSigner};
use neo3::neo_protocol::{Account, AccountTrait};

let account = Account::create().unwrap();
let account_signer = AccountSigner::called_by_entry(&account).unwrap();
let signer: Signer = account_signer.into();

let mut tx_builder: TransactionBuilder<'_, HttpProvider> = TransactionBuilder::default();
tx_builder.set_signers(vec![signer]).unwrap();

pub fn add_attributes( &mut self, attributes: Vec<TransactionAttribute>, ) -> Result<&mut Self, TransactionError>

Adds transaction attributes to the transaction.

Transaction attributes provide additional metadata or functionality to the transaction. This method checks for duplicate attribute types and ensures the total number of attributes does not exceed the maximum allowed.

Arguments

• attributes - A vector of TransactionAttribute objects to add to the transaction.

Returns

A Result containing a mutable reference to the TransactionBuilder for method chaining, or a TransactionError if adding the attributes would exceed the maximum allowed number of attributes or if an attribute of the same type already exists.

Examples

use neo3::neo_builder::{TransactionBuilder, TransactionAttribute};
use neo3::neo_clients::{HttpProvider, RpcClient};

let provider = HttpProvider::new("https://testnet1.neo.org:443").unwrap();
let client = RpcClient::new(provider);
let mut tx_builder = TransactionBuilder::with_client(&client);

// Add a high-priority attribute
let high_priority_attr = TransactionAttribute::HighPriority;

// Add a not-valid-before attribute
let not_valid_before_attr = TransactionAttribute::NotValidBefore { height: 1000 };

tx_builder.add_attributes(vec![high_priority_attr, not_valid_before_attr]).unwrap();

pub fn do_if_sender_cannot_cover_fees<F>( &mut self, consumer: F, ) -> Result<&mut Self, TransactionError>

where F: FnMut(i64, i64) + Send + Sync + 'static,

Checks if the sender account of this transaction can cover the network and system fees. If not, executes the given consumer supplying it with the required fee and the sender’s GAS balance.

The check and potential execution of the consumer is only performed when the transaction is built, i.e., when calling TransactionBuilder::sign or TransactionBuilder::get_unsigned_transaction.

• Parameter consumer: The consumer
• Returns: This transaction builder (self) Checks if the sender account can cover the transaction fees and executes a callback if not.

This method allows you to provide a callback function that will be executed if the sender account does not have enough GAS to cover the network and system fees. The callback receives the required fee amount and the sender’s current balance.

Arguments

• consumer - A callback function that takes two i64 parameters: the required fee and the sender’s current balance.

Returns

A Result containing a mutable reference to the TransactionBuilder for method chaining, or a TransactionError if a fee error handler is already set.

Examples

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = HttpProvider::new("https://testnet1.neo.org:443").unwrap();
    let client = RpcClient::new(provider);
     
    let mut tx_builder = TransactionBuilder::with_client(&client);
     
    // Add a callback for insufficient funds
    tx_builder.do_if_sender_cannot_cover_fees(|required_fee, balance| {
        println!("Insufficient funds: Required {} GAS, but only have {} GAS",
            required_fee as f64 / 100_000_000.0,
            balance as f64 / 100_000_000.0);
    })?;
     
    Ok(())
}

pub fn throw_if_sender_cannot_cover_fees( &mut self, error: TransactionError, ) -> Result<&mut Self, TransactionError>

Checks if the sender account of this transaction can cover the network and system fees. If not, otherwise throw an error created by the provided supplier.

The check and potential throwing of the exception is only performed when the transaction is built, i.e., when calling TransactionBuilder::sign or TransactionBuilder::get_unsigned_transaction.

• Parameter error: The error to throw
• Returns: This transaction builder (self)

Trait Implementations

impl<'a, P: JsonRpcProvider + 'static> Clone for TransactionBuilder<'a, P>

fn clone(&self) -> Self

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, P: JsonRpcProvider + 'static> Debug for TransactionBuilder<'a, P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, P: Default + JsonRpcProvider + 'static> Default for TransactionBuilder<'a, P>

fn default() -> TransactionBuilder<'a, P>

Returns the “default value” for a type.

impl<'a, P: JsonRpcProvider + 'static> Hash for TransactionBuilder<'a, P>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, P: JsonRpcProvider + 'static> PartialEq for TransactionBuilder<'a, P>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, P: JsonRpcProvider + 'static> Eq for TransactionBuilder<'a, P>