GetTransaction

Query Executed Transaction Details

The GetTransaction method retrieves comprehensive information about an executed Sui transaction using its digest. This includes transaction inputs, execution effects, emitted events, object changes, and balance modifications—essential for verifying transaction outcomes and building analytics tools.

Method Signature

Service: sui.rpc.v2beta2.LedgerService Method: GetTransaction Type: Unary RPC

Parameters

Parameter	Type	Required	Description
digest	string	Yes	Transaction digest (64-char base58 string)
read_mask	FieldMask	No	Fields to include in response

Field Mask Options

Path	Description
digest	Transaction identifier
transaction	Transaction data and inputs
effects	Execution effects and state changes
events	Emitted events
object_changes	Object modifications
balance_changes	Balance alterations
timestamp_ms	Execution timestamp

Response Structure

message Transaction {
  string digest = 1;
  TransactionData transaction = 2;
  TransactionEffects effects = 3;
  repeated Event events = 4;
  repeated ObjectChange object_changes = 5;
  repeated BalanceChange balance_changes = 6;
  uint64 timestamp_ms = 7;
}

Code Examples

TypeScript

import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';

const ENDPOINT = 'api-sui-mainnet-full.n.dwellir.com';
const API_TOKEN = 'your_api_token_here';

const packageDefinition = protoLoader.loadSync('./protos/ledger.proto', {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
  includeDirs: ['./protos']
});

const protoDescriptor = grpc.loadPackageDefinition(packageDefinition) as any;
const credentials = grpc.credentials.createSsl();
const client = new protoDescriptor.sui.rpc.v2beta2.LedgerService(ENDPOINT, credentials);

const metadata = new grpc.Metadata();
metadata.add('x-api-key', API_TOKEN);

async function getTransaction(digest: string): Promise<any> {
  return new Promise((resolve, reject) => {
    const request = {
      digest: digest,
      read_mask: {
        paths: ['digest', 'transaction', 'effects', 'events', 'timestamp_ms']
      }
    };

    client.GetTransaction(request, metadata, (error: any, response: any) => {
      if (error) {
        console.error('GetTransaction error:', error.message);
        reject(error);
        return;
      }

      resolve(response);
    });
  });
}

// Usage
const txDigest = 'HUwTkTFSGzKaDXUpLqZigkMb59J3T82zWQKcvQEL9G3X';
const tx = await getTransaction(txDigest);

console.log('Transaction:', tx.digest);
console.log('Status:', tx.effects.status.status);
console.log('Gas Used:', tx.effects.gasUsed);
console.log('Events:', tx.events.length);

Python

import grpc
from google.protobuf import field_mask_pb2
import ledger_service_pb2
import ledger_service_pb2_grpc

ENDPOINT = 'api-sui-mainnet-full.n.dwellir.com'
API_TOKEN = 'your_api_token_here'

def get_transaction(digest: str):
    credentials = grpc.ssl_channel_credentials()
    channel = grpc.secure_channel(ENDPOINT, credentials)
    client = ledger_service_pb2_grpc.LedgerServiceStub(channel)

    request = ledger_service_pb2.GetTransactionRequest(
        digest=digest,
        read_mask=field_mask_pb2.FieldMask(
            paths=['digest', 'transaction', 'effects', 'events']
        )
    )

    metadata = [('x-api-key', API_TOKEN)]
    response = client.GetTransaction(request, metadata=metadata)

    print(f'Transaction: {response.digest}')
    print(f'Status: {response.effects.status.status}')
    print(f'Events: {len(response.events)}')

    channel.close()
    return response

# Usage
tx = get_transaction('HUwTkTFSGzKaDXUpLqZigkMb59J3T82zWQKcvQEL9G3X')

Go

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"sui-grpc-client/config"
	pb "sui-grpc-client/sui/rpc/v2"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/types/known/fieldmaskpb"
)

func main() {
	// Load configuration from .env file
	cfg, err := config.Load()
	if err != nil {
		log.Fatalf("Failed to load config: %v", err)
	}

	// Create TLS credentials
	creds := credentials.NewClientTLSFromCert(nil, "")

	// Connect to Dwellir
	conn, err := grpc.NewClient(
		cfg.Endpoint,
		grpc.WithTransportCredentials(creds),
	)
	if err != nil {
		log.Fatalf("Failed to connect: %v", err)
	}
	defer conn.Close()

	// Create ledger service client
	client := pb.NewLedgerServiceClient(conn)

	// Add authentication
	ctx := metadata.AppendToOutgoingContext(
		context.Background(),
		"x-api-key", cfg.APIKey,
	)

	// Set timeout
	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
	defer cancel()

	// First, get a recent checkpoint to find a transaction
	cpRequest := &pb.GetCheckpointRequest{
		ReadMask: &fieldmaskpb.FieldMask{
			Paths: []string{"contents.transactions"},
		},
	}
	cpResponse, err := client.GetCheckpoint(ctx, cpRequest)
	if err != nil {
		log.Fatalf("Failed to get checkpoint: %v", err)
	}

	checkpoint := cpResponse.GetCheckpoint()
	if checkpoint == nil || checkpoint.GetContents() == nil {
		log.Fatal("No checkpoint data")
	}

	transactions := checkpoint.GetContents().GetTransactions()
	if len(transactions) == 0 {
		log.Fatal("No transactions in checkpoint")
	}

	// Get the first transaction digest
	txDigest := transactions[0].GetTransaction()
	fmt.Printf("Fetching transaction: %s\n\n", txDigest)

	// Create request
	request := &pb.GetTransactionRequest{
		Digest: &txDigest,
		ReadMask: &fieldmaskpb.FieldMask{
			Paths: []string{
				"digest",
				"transaction.sender",
				"effects.status",
				"effects.gas_used",
				"effects.changed_objects",
				"checkpoint",
			},
		},
	}

	// Execute request
	response, err := client.GetTransaction(ctx, request)
	if err != nil {
		log.Fatalf("Failed to get transaction: %v", err)
	}

	tx := response.GetTransaction()
	if tx == nil {
		log.Fatal("No transaction data")
	}

	// Display transaction information
	fmt.Println("Transaction Information:")
	fmt.Println("========================")
	fmt.Printf("Digest: %s\n", tx.GetDigest())
	fmt.Printf("Checkpoint: %d\n", tx.GetCheckpoint())

	if txData := tx.GetTransaction(); txData != nil {
		if sender := txData.GetSender(); sender != "" {
			fmt.Printf("Sender: %s\n", sender)
		}
	}

	// Check effects
	if effects := tx.GetEffects(); effects != nil {
		if status := effects.GetStatus(); status != nil {
			if status.GetSuccess() {
				fmt.Println("Status: SUCCESS")
			} else {
				fmt.Println("Status: FAILURE")
				if errMsg := status.GetError(); errMsg != nil {
					fmt.Printf("Error: %v\n", errMsg)
				}
			}
		}

		if gasUsed := effects.GetGasUsed(); gasUsed != nil {
			fmt.Printf("Computation Cost: %d MIST\n", gasUsed.GetComputationCost())
			fmt.Printf("Storage Cost: %d MIST\n", gasUsed.GetStorageCost())
			fmt.Printf("Storage Rebate: %d MIST\n", gasUsed.GetStorageRebate())
		}

		changedObjects := effects.GetChangedObjects()
		if len(changedObjects) > 0 {
			fmt.Printf("Changed Objects: %d\n", len(changedObjects))
		}
	}
}

Use Cases

Transaction Verification

async function verifyTransactionSuccess(digest: string): Promise<boolean> {
  const tx = await getTransaction(digest);
  return tx.effects?.status?.status === 'success';
}

Gas Cost Analysis

async function analyzeGas(digest: string) {
  const tx = await getTransaction(digest);
  const gas = tx.effects.gasUsed;

  return {
    computation: parseInt(gas.computationCost),
    storage: parseInt(gas.storageCost),
    rebate: parseInt(gas.storageRebate),
    total: parseInt(gas.computationCost) + parseInt(gas.storageCost) - parseInt(gas.storageRebate)
  };
}

Related Methods

• ExecuteTransaction - Submit transactions
• GetCheckpoint - Query checkpoints

---

Need help? Contact support@dwellir.com or check the gRPC overview.