Skip to main content

sui_executeTransactionBlock

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.

Parameters​

ParameterTypeRequiredDescription
transactionBlockBytesstringYesBCS serialized transaction data as base64 string
signaturearrayYesArray of signatures (base64) from transaction signers
optionsobjectNoOptions controlling response content
requestTypestringNoExecution type: "WaitForEffectsCert" (default) or "WaitForLocalExecution"

Options Object​

FieldTypeDefaultDescription
showInputbooleanfalseInclude transaction input in response
showRawInputbooleanfalseInclude raw transaction input
showEffectsbooleanfalseInclude transaction effects
showEventsbooleanfalseInclude emitted events
showObjectChangesbooleanfalseInclude object modifications
showBalanceChangesbooleanfalseInclude balance changes
showRawEffectsbooleanfalseInclude raw effects data

Request Types​

  • WaitForEffectsCert: Waits for transaction to be checkpointed (recommended)
  • WaitForLocalExecution: Returns after local execution (faster but less reliable)

Returns​

Returns transaction execution results based on requested options.

FieldTypeDescription
digeststringTransaction digest (unique identifier)
transactionobjectTransaction input (if requested)
rawTransactionstringRaw transaction bytes (if requested)
effectsobjectTransaction effects including status and changes
eventsarrayEvents emitted during execution
objectChangesarrayObjects created, modified, or deleted
balanceChangesarrayCoin balance modifications
timestampMsstringExecution timestamp in milliseconds
checkpointstringCheckpoint sequence number

Code Examples​

curl -X POST https://sui-mainnet.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sui_executeTransactionBlock",
    "params": [
      "AAACAAgAypo7AAAAAAAg7Vgw...transaction_bytes_base64...",
      [
        "AGnKiH1Z0bj...signature_base64..."
      ],
      {
        "showEffects": true,
        "showEvents": true,
        "showObjectChanges": true,
        "showBalanceChanges": true
      },
      "WaitForEffectsCert"
    ],
    "id": 1
  }'

Response Example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "digest": "HkCBSKmKKPqPR5hiKnp7j2JYN6HDkEZSjGpLvNapKwhF",
    "effects": {
      "messageVersion": "v1",
      "status": {
        "status": "success"
      },
      "executedEpoch": "251",
      "gasUsed": {
        "computationCost": "1000000",
        "storageCost": "2588000",
        "storageRebate": "978120",
        "nonRefundableStorageFee": "9880"
      },
      "modifiedAtVersions": [
        {
          "objectId": "0x5d3c87e88bc566e3f10c66e0275a366001ffa8b86142adc78c744de6afffeb34",
          "sequenceNumber": "31823925"
        }
      ],
      "transactionDigest": "HkCBSKmKKPqPR5hiKnp7j2JYN6HDkEZSjGpLvNapKwhF",
      "created": [],
      "mutated": [
        {
          "owner": {
            "AddressOwner": "0xd77955e670601c2c2e6e8637e383695c166aac0a86b741c266bdfb23c2e3369f"
          },
          "reference": {
            "objectId": "0x5d3c87e88bc566e3f10c66e0275a366001ffa8b86142adc78c744de6afffeb34",
            "version": 31823925,
            "digest": "2VivvnKSj89drLLNdkKhDxPFXTzPFkVH4V4DpCwN6pJk"
          }
        }
      ],
      "deleted": [],
      "dependencies": [
        "5yxPx9j5yQVhR3NmM9vHkvPq98zng3kFgPvL5pb6MfmT"
      ]
    },
    "events": [
      {
        "id": {
          "txDigest": "HkCBSKmKKPqPR5hiKnp7j2JYN6HDkEZSjGpLvNapKwhF",
          "eventSeq": "0"
        },
        "packageId": "0x3",
        "transactionModule": "sui_system",
        "sender": "0xd77955e670601c2c2e6e8637e383695c166aac0a86b741c266bdfb23c2e3369f",
        "type": "0x3::validator::StakingRequestEvent",
        "parsedJson": {
          "amount": "100000000000",
          "epoch": "251",
          "staker_address": "0xd77955e670601c2c2e6e8637e383695c166aac0a86b741c266bdfb23c2e3369f",
          "validator_address": "0x..."
        }
      }
    ],
    "objectChanges": [
      {
        "type": "mutated",
        "sender": "0xd77955e670601c2c2e6e8637e383695c166aac0a86b741c266bdfb23c2e3369f",
        "owner": {
          "AddressOwner": "0xd77955e670601c2c2e6e8637e383695c166aac0a86b741c266bdfb23c2e3369f"
        },
        "objectType": "0x2::coin::Coin<0x2::sui::SUI>",
        "objectId": "0x5d3c87e88bc566e3f10c66e0275a366001ffa8b86142adc78c744de6afffeb34",
        "version": "31823925",
        "previousVersion": "31823924",
        "digest": "2VivvnKSj89drLLNdkKhDxPFXTzPFkVH4V4DpCwN6pJk"
      }
    ],
    "balanceChanges": [
      {
        "owner": {
          "AddressOwner": "0xd77955e670601c2c2e6e8637e383695c166aac0a86b741c266bdfb23c2e3369f"
        },
        "coinType": "0x2::sui::SUI",
        "amount": "-2609880"
      }
    ],
    "timestampMs": "1703012345678",
    "checkpoint": "19823924"
  }
}

Transaction Building Examples​

Transfer SUI Coins​

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​

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​

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​

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​

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​

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

Estimating Gas Costs​

// 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​

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​

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)
  }
`);

Common Errors​

ErrorDescriptionSolution
InsufficientGasGas budget too lowIncrease gas budget
ObjectNotFoundReferenced object doesn't existVerify object IDs
InvalidInputIncorrect function argumentsCheck argument types and values
ObjectVersionMismatchObject was modifiedRefresh object version
InvalidSignatureSignature verification failedEnsure correct keypair

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