Skip to main content

sui_devInspectTransactionBlock

Executes a transaction in dev-inspect mode for debugging, providing detailed execution information without state changes.

Overview​

The sui_devInspectTransactionBlock method runs transactions in a special debugging mode that provides comprehensive execution details including return values from Move functions, detailed gas profiling, and execution traces. This is invaluable for smart contract development and debugging complex transactions.

Parameters​

ParameterTypeRequiredDescription
senderstringYesAddress of the transaction sender
transactionBlockBytesstringYesBCS serialized transaction data as base64 string
gasPricestringNoGas price for simulation (defaults to reference gas price)
epochstringNoEpoch to simulate in (defaults to current)

Returns​

Returns detailed execution results and debugging information.

FieldTypeDescription
effectsobjectTransaction effects including status and changes
eventsarrayEvents emitted during execution
resultsarrayReturn values from Move function calls
errorstringError message if execution failed
gasUsedobjectDetailed gas consumption breakdown

Results Array​

Each element represents a Move call result:

FieldTypeDescription
mutableReferenceOutputsarrayMutable references returned
returnValuesarrayFunction return values (BCS encoded)

Code Examples​

curl -X POST https://sui-mainnet.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sui_devInspectTransactionBlock",
    "params": [
      "0xsender_address",
      "AAACAAgAypo7AAAAAAAg7Vgw...transaction_bytes_base64...",
      null,
      null
    ],
    "id": 1
  }'

Response Example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "effects": {
      "messageVersion": "v1",
      "status": {
        "status": "success"
      },
      "executedEpoch": "251",
      "gasUsed": {
        "computationCost": "1500000",
        "storageCost": "2588000",
        "storageRebate": "978120",
        "nonRefundableStorageFee": "9880"
      },
      "modifiedAtVersions": [],
      "transactionDigest": "DevInspectTransaction",
      "created": [],
      "mutated": [],
      "deleted": [],
      "dependencies": []
    },
    "events": [
      {
        "id": {
          "txDigest": "DevInspectTransaction",
          "eventSeq": "0"
        },
        "packageId": "0xpackage",
        "transactionModule": "module",
        "sender": "0xsender",
        "type": "0xpackage::module::EventType",
        "parsedJson": {
          "field1": "value1",
          "field2": 123
        }
      }
    ],
    "results": [
      {
        "mutableReferenceOutputs": [],
        "returnValues": [
          ["gAAAAAAAAA==", "u64"],
          ["AQAAAAAAAADoBwAAAAAAAOgHAAAAAAAA", "vector<u64>"]
        ]
      }
    ]
  }
}

Debugging Use Cases​

Testing Move Functions​

async function testMoveFunction(packageId, module, func, args) {
  const tx = new TransactionBlock();
  
  const result = tx.moveCall({
    target: `${packageId}::${module}::${func}`,
    arguments: args
  });
  
  const inspection = await client.devInspectTransactionBlock({
    sender: '0x0', // Can use any address for inspection
    transactionBlock: tx
  });
  
  if (inspection.effects.status.status !== 'success') {
    console.error('Function failed:', inspection.error);
    return null;
  }
  
  // Extract and decode return values
  const returns = inspection.results?.[0]?.returnValues || [];
  return returns.map(([data, type]) => {
    // Decode based on type
    return bcs.de(type, data);
  });
}

Gas Profiling​

async function profileGasUsage(tx, sender) {
  const result = await client.devInspectTransactionBlock({
    sender,
    transactionBlock: tx
  });
  
  const gas = result.effects.gasUsed;
  
  console.log('Gas Profile:');
  console.log('├─ Computation:', gas.computationCost);
  console.log('├─ Storage:', gas.storageCost);
  console.log('├─ Rebate:', gas.storageRebate);
  console.log('└─ Total:', 
    Number(gas.computationCost) + 
    Number(gas.storageCost) - 
    Number(gas.storageRebate)
  );
  
  return gas;
}

Event Analysis​

async function analyzeEvents(tx, sender) {
  const result = await client.devInspectTransactionBlock({
    sender,
    transactionBlock: tx
  });
  
  const eventsByType = {};
  
  result.events.forEach(event => {
    const type = event.type.split('::').pop();
    if (!eventsByType[type]) {
      eventsByType[type] = [];
    }
    eventsByType[type].push(event.parsedJson);
  });
  
  console.log('Events emitted:', Object.keys(eventsByType));
  return eventsByType;
}

Complex Transaction Debugging​

async function debugComplexTransaction() {
  const tx = new TransactionBlock();
  
  // Multiple operations
  const [coin1, coin2] = tx.splitCoins(tx.gas, [
    tx.pure(1000000),
    tx.pure(2000000)
  ]);
  
  // First Move call
  const result1 = tx.moveCall({
    target: '0xdefi::swap::swap',
    arguments: [coin1, tx.pure('0x2::sui::SUI')]
  });
  
  // Second Move call using first result
  const result2 = tx.moveCall({
    target: '0xdefi::pool::add_liquidity',
    arguments: [result1, coin2]
  });
  
  // Inspect execution
  const inspection = await client.devInspectTransactionBlock({
    sender: '0xsender',
    transactionBlock: tx
  });
  
  // Analyze each call's results
  inspection.results?.forEach((result, idx) => {
    console.log(`Call ${idx} results:`, result.returnValues);
  });
  
  return inspection;
}

Best Practices​

  1. Use for development only - Not for production validation
  2. Test with realistic sender - Some functions check sender permissions
  3. Decode return values properly - Use correct BCS types
  4. Check gas estimates - More accurate than dry run for complex transactions
  5. Analyze event emissions - Verify correct events are emitted

Differences from Other Methods​

MethodPurposeReturnsState Change
devInspectTransactionBlockDebuggingReturn values, detailed tracesNo
dryRunTransactionBlockGas estimationEffects previewNo
executeTransactionBlockExecutionTransaction receiptYes

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