GetObject - Retrieve Sui Object Data via gRPC

Retrieve Object Data with High-Performance gRPC

The GetObject method from the Ledger Service provides efficient access to Sui blockchain object data through gRPC. This method returns comprehensive object information including metadata, ownership, type information, and contents, with support for field masking to optimize response payloads.

Overview

Objects are fundamental to Sui's architecture. Every piece of data on Sui exists as an object with a unique identifier, version, ownership model, and type definition. The GetObject gRPC method enables developers to query object state efficiently using binary Protocol Buffer serialization, offering significant performance advantages over JSON-RPC for high-throughput applications.

Key Features

• Field Masking: Request only necessary fields to minimize response size
• Binary Serialization: Protocol Buffers provide compact, efficient data encoding
• Type Safety: Strong typing through proto definitions eliminates runtime errors
• Version Tracking: Access object version history and previous transactions
• Ownership Information: Detailed ownership metadata including transfer capabilities

Method Signature

Service: sui.rpc.v2.LedgerService Method: GetObject Type: Unary RPC (single request, single response)

Use Cases

1. Object Ownership Verification

Verify ownership before performing operations:

async function verifyOwnership(objectId: string, expectedOwner: string): Promise<boolean> {
  const object = await getObject(objectId);

  if (object.owner.kind === 0) {  // ADDRESS_OWNER
    return object.owner.address === expectedOwner;
  }

  return false;
}

2. Object Version Tracking

Monitor object version changes:

async function trackObjectVersions(objectId: string): Promise<void> {
  const object = await getObject(objectId);

  console.log('Current Version:', object.version);
  console.log('Last Modified By:', object.previous_transaction);

  // Store version for comparison
  localStorage.setItem(`${objectId}_version`, object.version);
}

3. NFT Metadata Retrieval

Efficiently query NFT objects:

async function getNFTMetadata(nftObjectId: string) {
  const nft = await client.GetObject({
    object_id: nftObjectId,
    read_mask: {
      paths: [
        'object_id',
        'object_type',
        'owner',
        'contents',
        'has_public_transfer'
      ]
    }
  }, metadata);

  return {
    id: nft.object_id,
    type: nft.object_type,
    owner: nft.owner.address,
    transferrable: nft.has_public_transfer,
    metadata: nft.contents
  };
}

4. Storage Cost Analysis

Analyze storage costs across objects:

async function analyzeStorageCosts(objectIds: string[]): Promise<void> {
  let totalRebate = 0;

  for (const id of objectIds) {
    const obj = await client.GetObject({
      object_id: id,
      read_mask: { paths: ['storage_rebate'] }
    }, metadata);

    totalRebate += parseInt(obj.storage_rebate);
  }

  console.log(`Total Storage Rebate: ${totalRebate / 1_000_000_000} SUI`);
}

Field Masking for Performance

Field masking dramatically reduces response size and improves performance:

Full Response (No Field Mask)

const request = { object_id: '0x5' };
// Response size: ~2.5 KB

Optimized Response (With Field Mask)

const request = {
  object_id: '0x5',
  read_mask: {
    paths: ['object_id', 'version', 'owner']
  }
};
// Response size: ~150 bytes (94% reduction)

Performance Impact

Best Practices

1. Use Field Masking

Always specify only the fields you need:

// ✅ Good: Request only needed fields
const request = {
  object_id: objectId,
  read_mask: { paths: ['owner', 'version'] }
};

// ❌ Bad: Request all fields when you only need a few
const request = { object_id: objectId };

2. Implement Caching

Cache object data to reduce API calls:

const objectCache = new Map();

async function getCachedObject(objectId: string, maxAge: number = 60000) {
  const cached = objectCache.get(objectId);

  if (cached && Date.now() - cached.timestamp < maxAge) {
    return cached.data;
  }

  const object = await getObject(objectId);

  objectCache.set(objectId, {
    data: object,
    timestamp: Date.now()
  });

  return object;
}

3. Handle Version Conflicts

Check version numbers to avoid stale data:

async function updateObjectIfNewer(objectId: string, lastKnownVersion: number) {
  const object = await client.GetObject({
    object_id: objectId,
    read_mask: { paths: ['version', 'digest'] }
  }, metadata);

  if (object.version > lastKnownVersion) {
    console.log('Object updated:', {
      oldVersion: lastKnownVersion,
      newVersion: object.version,
      digest: object.digest
    });
    return object;
  }

  return null;  // No update needed
}

4. Batch Queries

For multiple objects, use BatchGetObjects instead:

// ✅ Efficient: Single batch request
const response = await client.BatchGetObjects({
  requests: objectIds.map(id => ({ object_id: id }))
}, metadata);

// ❌ Inefficient: Multiple individual requests
for (const id of objectIds) {
  await client.GetObject({ object_id: id }, metadata);
}

Related Methods

• BatchGetObjects - Retrieve multiple objects efficiently
• GetTransaction - Query transaction details
• ListOwnedObjects - List objects owned by an address

Performance Considerations

• Field Masking: Reduces response size by up to 94%
• Binary Serialization: 5-10x faster than JSON parsing
• Connection Reuse: Keep gRPC channel open for multiple requests
• Compression: Enable gRPC compression for large payloads
• Caching: Cache immutable objects to avoid repeated queries

Need help with gRPC integration? Contact our support team or check the gRPC overview.