Struct TransactionBuilder 

pub struct TransactionBuilder { /* private fields */ }

Builder for constructing multi-action transactions.

Created via crate::Near::transaction. Supports chaining multiple actions into a single atomic transaction.

Example

let near = Near::testnet()
    .credentials("ed25519:...", "alice.testnet")?
    .build();

// Single action
near.transaction("bob.testnet")
    .transfer(NearToken::from_near(1))
    .send()
    .await?;

// Multiple actions (atomic)
let key: PublicKey = "ed25519:6E8sCci9badyRkXb3JoRpBj5p8C6Tw41ELDZoiihKEtp".parse()?;
near.transaction("new.alice.testnet")
    .create_account()
    .transfer(NearToken::from_near(5))
    .add_full_access_key(key)
    .send()
    .await?;

Implementations

impl TransactionBuilder

pub fn create_account(self) -> Self

Add a create account action.

Creates a new sub-account. Must be followed by transfer and add_key to properly initialize the account.

pub fn transfer(self, amount: impl IntoNearToken) -> Self

Add a transfer action.

Transfers NEAR tokens to the receiver account.

Example

near.transaction("bob.testnet")
    .transfer(NearToken::from_near(1))
    .send()
    .await?;

Panics

Panics if the amount string cannot be parsed.

pub fn deploy(self, code: impl Into<Vec<u8>>) -> Self

Add a deploy contract action.

Deploys WASM code to the receiver account.

pub fn call(self, method: &str) -> CallBuilder

Add a function call action.

Returns a CallBuilder for configuring the call with args, gas, and deposit.

Example

near.transaction("contract.testnet")
    .call("set_greeting")
        .args(serde_json::json!({ "greeting": "Hello" }))
        .gas(Gas::from_tgas(10))
        .deposit(NearToken::ZERO)
    .call("another_method")
        .args(serde_json::json!({ "value": 42 }))
    .send()
    .await?;

pub fn add_full_access_key(self, public_key: PublicKey) -> Self

Add a full access key to the account.

pub fn add_function_call_key( self, public_key: PublicKey, receiver_id: impl TryIntoAccountId, method_names: Vec<String>, allowance: Option<NearToken>, ) -> Self

Add a function call access key to the account.

Arguments

• public_key - The public key to add
• receiver_id - The contract this key can call
• method_names - Methods this key can call (empty = all methods)
• allowance - Maximum amount this key can spend (None = unlimited)

pub fn delete_key(self, public_key: PublicKey) -> Self

Delete an access key from the account.

pub fn delete_account(self, beneficiary_id: impl TryIntoAccountId) -> Self

Delete the account and transfer remaining balance to beneficiary.

pub fn stake(self, amount: impl IntoNearToken, public_key: PublicKey) -> Self

Add a stake action.

Panics

Panics if the amount string cannot be parsed.

pub fn signed_delegate_action( self, signed_delegate: SignedDelegateAction, ) -> Self

Add a signed delegate action to this transaction (for relayers).

This is used by relayers to wrap a user’s signed delegate action and submit it to the blockchain, paying for the gas on behalf of the user.

Example

// Relayer receives base64 payload from user
let signed_delegate = SignedDelegateAction::from_base64(payload)?;

// Relayer submits it, paying the gas
let result = relayer
    .transaction(signed_delegate.sender_id())
    .signed_delegate_action(signed_delegate)
    .send()
    .await?;

pub async fn delegate( self, options: DelegateOptions, ) -> Result<DelegateResult, Error>

Build and sign a delegate action for meta-transactions (NEP-366).

This allows the user to sign a set of actions off-chain, which can then be submitted by a relayer who pays the gas fees. The user’s signature authorizes the actions, but they don’t need to hold NEAR for gas.

Example

// User builds and signs a delegate action
let result = near
    .transaction("contract.testnet")
    .call("add_message")
        .args(serde_json::json!({ "text": "Hello!" }))
        .gas(Gas::from_tgas(30))
    .delegate(Default::default())
    .await?;

// Send payload to relayer via HTTP
println!("Payload to send: {}", result.payload);

pub fn publish(self, code: impl Into<Vec<u8>>, mode: PublishMode) -> Self

Publish a contract to the global registry.

Global contracts are deployed once and can be referenced by multiple accounts, saving storage costs. Two modes are available via PublishMode:

• PublishMode::Updatable: the contract is identified by the publisher’s account and can be updated by publishing new code from the same account.
• PublishMode::Immutable: the contract is identified by its code hash and cannot be updated once published.

Example

let wasm_code = std::fs::read("contract.wasm")?;

// Publish updatable contract (identified by your account)
near.transaction("alice.testnet")
    .publish(wasm_code.clone(), PublishMode::Updatable)
    .send()
    .await?;

// Publish immutable contract (identified by its hash)
near.transaction("alice.testnet")
    .publish(wasm_code, PublishMode::Immutable)
    .send()
    .await?;

pub fn deploy_from(self, contract_ref: impl GlobalContractRef) -> Self

Deploy a contract from the global registry.

Accepts any GlobalContractRef (such as a CryptoHash or an account ID string/AccountId) to reference a previously published contract.

Example

near.transaction("alice.testnet")
    .deploy_from(code_hash)
    .send()
    .await?;

pub fn state_init( self, state_init: DeterministicAccountStateInit, deposit: impl IntoNearToken, ) -> Self

Create a NEP-616 deterministic state init action.

The receiver_id is automatically set to the deterministically derived account ID: "0s" + hex(keccak256(borsh(state_init))[12..32])

Example

let si = DeterministicAccountStateInit::by_hash(code_hash, Default::default());
let outcome = near.transaction("alice.testnet")
    .state_init(si, NearToken::from_near(1))
    .send()
    .await?;

Panics

Panics if the deposit amount string cannot be parsed.

pub fn add_action(self, action: impl Into<Action>) -> Self

Add a pre-built action to the transaction.

This is the most flexible way to add actions, since it accepts any Action variant directly. It’s especially useful when you want to build function call actions independently and attach them later, or when working with action types that don’t have dedicated builder methods.

Example

let action = Action::function_call(
    "transfer",
    serde_json::to_vec(&serde_json::json!({ "receiver": "bob.testnet" }))?,
    Gas::from_tgas(30),
    NearToken::ZERO,
);

near.transaction("contract.testnet")
    .add_action(action)
    .send()
    .await?;

pub fn sign_with(self, signer: impl Signer + 'static) -> Self

Override the signer for this transaction.

pub fn wait_until(self, status: TxExecutionStatus) -> Self

Set the execution wait level.

pub fn max_nonce_retries(self, retries: u32) -> Self

Override the number of nonce retries for this transaction on InvalidNonce errors. 0 means no retries (send once), 1 means one retry, etc.

pub async fn sign(self) -> Result<SignedTransaction, Error>

Sign the transaction without sending it.

Returns a SignedTransaction that can be inspected or sent later.

Example

let signed = near.transaction("bob.testnet")
    .transfer(NearToken::from_near(1))
    .sign()
    .await?;

// Inspect the transaction
println!("Hash: {}", signed.transaction.get_hash());
println!("Actions: {:?}", signed.transaction.actions);

// Send it later
let outcome = near.send(&signed).await?;

pub async fn sign_offline( self, block_hash: CryptoHash, nonce: u64, ) -> Result<SignedTransaction, Error>

Sign the transaction offline without network access.

This is useful for air-gapped signing workflows where you need to provide the block hash and nonce manually (obtained from a separate online machine).

Arguments

• block_hash - A recent block hash (transaction expires ~24h after this block)
• nonce - The next nonce for the signing key (current nonce + 1)

Example

// On online machine: get block hash and nonce
// let block = near.rpc().block(BlockReference::latest()).await?;
// let access_key = near.rpc().view_access_key(...).await?;

// On offline machine: sign with pre-fetched values
let block_hash: CryptoHash = "11111111111111111111111111111111".parse().unwrap();
let nonce = 12345u64;

let signed = near.transaction("bob.testnet")
    .transfer(NearToken::from_near(1))
    .sign_offline(block_hash, nonce)
    .await?;

// Transport signed_tx.to_base64() back to online machine

pub fn send(self) -> TransactionSend

Send the transaction.

This is equivalent to awaiting the builder directly.

Trait Implementations

impl Debug for TransactionBuilder

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

Formats the value using the given formatter.

impl IntoFuture for TransactionBuilder

type Output = Result<FinalExecutionOutcome, Error>

The output that the future will produce on completion.

type IntoFuture = Pin<Box<dyn Future<Output = <TransactionBuilder as IntoFuture>::Output> + Send>>

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.