executeTransactionBlock | Sui API Docs

Submit and execute signed transactions on Sui blockchain. Send coins, call smart contracts, and manage objects with Dwellir's reliable Sui RPC infrastructure.

Executes a signed transaction block on the Sui network, enabling coin transfers, smart contract interactions, and object manipulations.

Overview

The sui_executeTransactionBlock method is the primary way to submit transactions to the Sui blockchain. It processes pre-signed transaction blocks that can contain multiple commands, such as transferring objects, calling Move functions, splitting coins, and more. The method supports various response options to retrieve transaction effects, events, and object changes.

const tx = new TransactionBlock();

// Transfer SUI to recipient
const [coin] = tx.splitCoins(tx.gas, [tx.pure(1000000000)]); // 1 SUI
tx.transferObjects([coin], tx.pure(recipientAddress));

const result = await client.signAndExecuteTransactionBlock({
  signer: keypair,
  transactionBlock: tx,
});

Call Move Function

JavaScript

const tx = new TransactionBlock();

// Call a Move function
tx.moveCall({
  target: '0xpackage::module::function',
  arguments: [
    tx.pure('string_argument'),
    tx.pure(123, 'u64'),
    tx.object('0xobject_id')
  ],
  typeArguments: ['0x2::sui::SUI']
});

const result = await client.signAndExecuteTransactionBlock({
  signer: keypair,
  transactionBlock: tx,
});

Complex Transaction with Multiple Commands

JavaScript

const tx = new TransactionBlock();

// Split coins
const [coin1, coin2] = tx.splitCoins(tx.gas, [
  tx.pure(1000000000),
  tx.pure(2000000000)
]);

// Transfer first coin
tx.transferObjects([coin1], tx.pure(recipient1));

// Use second coin in Move call
tx.moveCall({
  target: '0xpackage::defi::deposit',
  arguments: [coin2]
});

// Merge remaining coins
tx.mergeCoins(tx.gas, [/* other coins */]);

const result = await client.signAndExecuteTransactionBlock({
  signer: keypair,
  transactionBlock: tx,
  options: {
    showEffects: true,
    showEvents: true,
    showObjectChanges: true
  }
});

Transaction Effects Status

Understanding transaction status from effects:

Success Status

JavaScript

if (result.effects.status.status === 'success') {
  console.log('Transaction successful');
  // Process created/modified objects
  result.effects.created?.forEach(obj => {
    console.log('Created object:', obj.reference.objectId);
  });
}

Failure Handling

JavaScript

if (result.effects.status.status === 'failure') {
  console.error('Transaction failed:', result.effects.status.error);
  // Common errors:
  // - InsufficientGas: Increase gas budget
  // - ObjectNotFound: Object doesn't exist
  // - InvalidInput: Check function arguments
}

Gas Management

Setting Gas Budget

JavaScript

const tx = new TransactionBlock();
tx.setGasBudget(10000000); // 0.01 SUI

Estimating Gas Costs

JavaScript

// Use dryRunTransactionBlock first to estimate
const dryRun = await client.dryRunTransactionBlock({
  transactionBlock: await tx.build({ client })
});

const estimatedGas = 
  Number(dryRun.effects.gasUsed.computationCost) +
  Number(dryRun.effects.gasUsed.storageCost) -
  Number(dryRun.effects.gasUsed.storageRebate);

console.log('Estimated gas:', estimatedGas);

Best Practices

1. Always Handle Transaction Status

JavaScript

const executeTransaction = async (tx) => {
  try {
    const result = await client.signAndExecuteTransactionBlock({
      signer: keypair,
      transactionBlock: tx,
      options: { showEffects: true }
    });
    
    if (result.effects?.status?.status !== 'success') {
      throw new Error(`Transaction failed: ${result.effects.status.error}`);
    }
    
    return result;
  } catch (error) {
    console.error('Execution error:', error);
    throw error;
  }
};

2. Use Appropriate Request Type

Use WaitForEffectsCert for critical transactions requiring confirmation
Use WaitForLocalExecution for faster response when immediate confirmation isn't critical

3. Monitor Gas Usage

JavaScript

const gasUsed = result.effects.gasUsed;
console.log(`
  Computation: ${gasUsed.computationCost}
  Storage: ${gasUsed.storageCost}
  Rebate: ${gasUsed.storageRebate}
  Total: ${
    Number(gasUsed.computationCost) + 
    Number(gasUsed.storageCost) - 
    Number(gasUsed.storageRebate)
  }
`);

sui_getObject - Retrieve object information
suix_getBalance - Query coin balances

Common Errors

Error	Description	Solution
`InsufficientGas`	Gas budget too low	Increase gas budget
`ObjectNotFound`	Referenced object doesn't exist	Verify object IDs
`InvalidInput`	Incorrect function arguments	Check argument types and values
`ObjectVersionMismatch`	Object was modified	Refresh object version
`InvalidSignature`	Signature verification failed	Ensure correct keypair

Need help? Contact our support team or check the Sui documentation.

sui_executeTransactionBlock - Execute Su...

Overview

Code Examples

Transaction Building Examples

Transfer SUI Coins

Call Move Function

Complex Transaction with Multiple Commands

Transaction Effects Status

Success Status

Failure Handling

Gas Management

Setting Gas Budget

Estimating Gas Costs

Best Practices

1. Always Handle Transaction Status

2. Use Appropriate Request Type

3. Monitor Gas Usage

Common Errors

On this page