diff --git a/content/api-reference/sui-grpc/move-packages.mdx b/content/api-reference/sui-grpc/move-packages.mdx new file mode 100644 index 000000000..7650170b5 --- /dev/null +++ b/content/api-reference/sui-grpc/move-packages.mdx @@ -0,0 +1,132 @@ +--- +title: Move packages +description: Sui gRPC MovePackageService API reference +slug: reference/sui-grpc-move-packages +--- + +The `MovePackageService` provides methods for inspecting Move packages, functions, and data types. + +## GetPackage + +Fetches a Move package by its ID. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `package_id` | string | Yes | The Move package ID | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `package` | Package | The Move package including its modules | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/move_package_service.proto \ + -d '{"package_id": "0x2"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.MovePackageService/GetPackage +``` + +*** + +## GetFunction + +Fetches a Move function definition by package, module, and function name. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `package_id` | string | Yes | The Move package ID | +| `module_name` | string | Yes | The module name | +| `name` | string | Yes | The function name | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `function` | FunctionDescriptor | The function definition including parameters and return types | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/move_package_service.proto \ + -d '{ + "package_id": "0x2", + "module_name": "coin", + "name": "balance" + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.MovePackageService/GetFunction +``` + +*** + +## GetDatatype + +Fetches a Move struct or enum definition by package, module, and name. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `package_id` | string | Yes | The Move package ID | +| `module_name` | string | Yes | The module name | +| `name` | string | Yes | The datatype name | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `datatype` | DatatypeDescriptor | The datatype definition including fields and abilities | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/move_package_service.proto \ + -d '{ + "package_id": "0x2", + "module_name": "coin", + "name": "Coin" + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.MovePackageService/GetDatatype +``` + +*** + +## ListPackageVersions + +Lists all versions of a Move package with pagination. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `package_id` | string | Yes | The Move package ID | +| `page_size` | uint32 | No | Maximum results to return | +| `page_token` | bytes | No | Pagination token from a previous response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `versions` | repeated PackageVersion | List of package versions | +| `next_page_token` | bytes | Token for the next page of results | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/move_package_service.proto \ + -d '{"package_id": "0x2"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.MovePackageService/ListPackageVersions +``` diff --git a/content/api-reference/sui-grpc/name-service.mdx b/content/api-reference/sui-grpc/name-service.mdx new file mode 100644 index 000000000..dd6c55d17 --- /dev/null +++ b/content/api-reference/sui-grpc/name-service.mdx @@ -0,0 +1,61 @@ +--- +title: Name service +description: Sui gRPC NameService API reference +slug: reference/sui-grpc-name-service +--- + +The `NameService` provides methods for resolving SuiNS names to addresses and vice versa. + +## LookupName + +Resolves a SuiNS name to its record, including the associated address. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `name` | string | Yes | The SuiNS name to look up (e.g., `example.sui`) | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `record` | NameRecord | The name record including the resolved address | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/name_service.proto \ + -d '{"name": "example.sui"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.NameService/LookupName +``` + +*** + +## ReverseLookupName + +Resolves an address to its SuiNS name. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `address` | string | Yes | The address to reverse-lookup | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `record` | NameRecord | The name record for the address | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/name_service.proto \ + -d '{"address": "0xYOUR_ADDRESS"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.NameService/ReverseLookupName +``` diff --git a/content/api-reference/sui-grpc/objects-and-ledger.mdx b/content/api-reference/sui-grpc/objects-and-ledger.mdx new file mode 100644 index 000000000..b93e88ae9 --- /dev/null +++ b/content/api-reference/sui-grpc/objects-and-ledger.mdx @@ -0,0 +1,217 @@ +--- +title: Objects and ledger +description: Sui gRPC LedgerService API reference +slug: reference/sui-grpc-objects-and-ledger +--- + +The `LedgerService` provides methods for querying objects, transactions, checkpoints, epochs, and general chain information. + +## GetServiceInfo + +Returns chain metadata including the current checkpoint height and epoch. + +**Request**: No fields required. + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `chain` | string | Network name (e.g., `mainnet`) | +| `chain_id` | string | Chain identifier | +| `checkpoint_height` | uint64 | Current checkpoint height | +| `epoch` | uint64 | Current epoch | +| `lowest_available_checkpoint` | uint64 | Earliest available checkpoint | +| `lowest_available_checkpoint_objects` | uint64 | Earliest checkpoint with object data | +| `server` | string | Server identifier | +| `timestamp` | Timestamp | Server timestamp | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/GetServiceInfo +``` + +*** + +## GetObject + +Fetches a single object by ID, optionally at a specific version. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `object_id` | string | Yes | The object ID | +| `version` | uint64 | No | Specific version to fetch | +| `read_mask` | FieldMask | No | Fields to include in the response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `object` | Object | The requested object | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{"object_id": "0x5"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/GetObject +``` + +*** + +## BatchGetObjects + +Fetches multiple objects in a single request. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `requests` | repeated GetObjectRequest | Yes | Array of object requests | +| `read_mask` | FieldMask | No | Fields to include in each response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `objects` | repeated GetObjectResult | Array of results, each containing an `object` or `error` | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{ + "requests": [ + {"object_id": "0x5"}, + {"object_id": "0x6"} + ] + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/BatchGetObjects +``` + +*** + +## GetTransaction + +Fetches a single executed transaction by its digest. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `digest` | string | Yes | Transaction digest | +| `read_mask` | FieldMask | No | Fields to include in the response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `transaction` | ExecutedTransaction | The executed transaction | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{"digest": "YOUR_TX_DIGEST"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/GetTransaction +``` + +*** + +## BatchGetTransactions + +Fetches multiple transactions by digest in a single request. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `digests` | repeated string | Yes | Array of transaction digests | +| `read_mask` | FieldMask | No | Fields to include in each response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `transactions` | repeated GetTransactionResult | Array of results, each containing a `transaction` or `error` | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{"digests": ["DIGEST_1", "DIGEST_2"]}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/BatchGetTransactions +``` + +*** + +## GetCheckpoint + +Fetches a checkpoint by sequence number or digest. + +**Request** (one of): + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `sequence_number` | uint64 | No | Checkpoint sequence number | +| `digest` | string | No | Checkpoint digest | +| `read_mask` | FieldMask | No | Fields to include in the response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `checkpoint` | Checkpoint | The checkpoint data | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{"sequence_number": 1000000}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/GetCheckpoint +``` + +*** + +## GetEpoch + +Fetches epoch information. Returns the current epoch if no epoch number is specified. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `epoch` | uint64 | No | Epoch number. Defaults to current epoch | +| `read_mask` | FieldMask | No | Fields to include in the response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `epoch` | Epoch | Epoch information | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/GetEpoch +``` diff --git a/content/api-reference/sui-grpc/overview.mdx b/content/api-reference/sui-grpc/overview.mdx new file mode 100644 index 000000000..ade345562 --- /dev/null +++ b/content/api-reference/sui-grpc/overview.mdx @@ -0,0 +1,94 @@ +--- +title: Sui gRPC overview +description: High-performance gRPC API for querying and executing on Sui +slug: reference/sui-grpc-overview +--- + +Sui gRPC is a high-performance API for interacting with the Sui blockchain using Protocol Buffers and gRPC. It provides typed, efficient access to objects, transactions, balances, Move packages, and more. + +## Why Sui gRPC? + +Sui gRPC offers advantages over the JSON-RPC API: + +* **Strongly typed**: Protocol Buffers provide strict typing and schema validation +* **Efficient serialization**: Binary encoding reduces payload size compared to JSON +* **Streaming support**: Subscribe to real-time checkpoint updates with server-streaming RPCs +* **Field masking**: Request only the fields you need with `read_mask` to reduce response size +* **Batch operations**: Fetch multiple objects or transactions in a single request + +## Available services + +### [Objects and ledger](/docs/reference/sui-grpc-objects-and-ledger) + +Query objects, transactions, checkpoints, and epochs through the `LedgerService`. + +| gRPC method | JSON-RPC equivalent | +| --- | --- | +| `GetObject` | `sui_getObject` | +| `BatchGetObjects` | `sui_multiGetObjects` | +| `GetTransaction` | `sui_getTransactionBlock` | +| `BatchGetTransactions` | `sui_multiGetTransactionBlocks` | +| `GetCheckpoint` | `sui_getCheckpoint` | +| `GetEpoch` | No equivalent | +| `GetServiceInfo` | `sui_getChainIdentifier` | + +### [Transactions](/docs/reference/sui-grpc-transactions) + +Execute and simulate transactions through the `TransactionExecutionService`. + +| gRPC method | JSON-RPC equivalent | +| --- | --- | +| `ExecuteTransaction` | `sui_executeTransactionBlock` | +| `SimulateTransaction` | `sui_dryRunTransactionBlock`, `sui_devInspectTransactionBlock` | + +### [State and balances](/docs/reference/sui-grpc-state-and-balances) + +Query coin balances, dynamic fields, and owned objects through the `StateService`. + +| gRPC method | JSON-RPC equivalent | +| --- | --- | +| `GetBalance` | `suix_getBalance` | +| `ListBalances` | `suix_getAllBalances`, `suix_getCoins`, `suix_getAllCoins` | +| `GetCoinInfo` | `suix_getCoinMetadata`, `suix_getTotalSupply` | +| `ListDynamicFields` | `suix_getDynamicFields` | +| `ListOwnedObjects` | `suix_getOwnedObjects` | + +### [Move packages](/docs/reference/sui-grpc-move-packages) + +Inspect Move packages, functions, and data types through the `MovePackageService`. + +| gRPC method | JSON-RPC equivalent | +| --- | --- | +| `GetPackage` | `sui_getNormalizedMoveModulesByPackage` | +| `GetFunction` | `sui_getNormalizedMoveFunction`, `sui_getMoveFunctionArgTypes` | +| `GetDatatype` | `sui_getNormalizedMoveStruct` | +| `ListPackageVersions` | No equivalent | + +### [Name service](/docs/reference/sui-grpc-name-service) + +Resolve SuiNS names through the `NameService`. + +| gRPC method | JSON-RPC equivalent | +| --- | --- | +| `LookupName` | `suix_resolveNameServiceAddress` | +| `ReverseLookupName` | `suix_resolveNameServiceNames` | + +### [Subscriptions](/docs/reference/sui-grpc-subscriptions) + +Stream real-time checkpoint data through the `SubscriptionService`. + +| gRPC method | JSON-RPC equivalent | +| --- | --- | +| `SubscribeCheckpoints` | No equivalent | + +### [Signature verification](/docs/reference/sui-grpc-signature-verification) + +Verify user signatures through the `SignatureVerificationService`. + +| gRPC method | JSON-RPC equivalent | +| --- | --- | +| `VerifySignature` | No equivalent | + +## Getting started + +Check out the [quickstart guide](/docs/reference/sui-grpc-quickstart) to make your first gRPC call. diff --git a/content/api-reference/sui-grpc/quickstart.mdx b/content/api-reference/sui-grpc/quickstart.mdx new file mode 100644 index 000000000..6d57bd95a --- /dev/null +++ b/content/api-reference/sui-grpc/quickstart.mdx @@ -0,0 +1,117 @@ +--- +title: Sui gRPC quickstart +description: Get started with the Sui gRPC API +slug: reference/sui-grpc-quickstart +--- + +import { Steps, Step } from "/snippets/interactive-steps.mdx"; + +This guide walks you through making your first Sui gRPC call. + +## Prerequisites + +* An [Alchemy API key](https://dashboard.alchemy.com/signup) +* A gRPC client library for your language ([grpcurl](https://github.com/fullstorydev/grpcurl) for CLI testing) +* The [Sui gRPC proto definitions](https://github.com/MystenLabs/sui-apis) cloned locally (grpcurl requires the `.proto` files) + +## Endpoints + +| Network | Endpoint | +| --- | --- | +| Mainnet | `sui-mainnet.g.alchemy.com:443` | +| Testnet | `sui-testnet.g.alchemy.com:443` | + +Authentication uses a Bearer token in the request header: + +```bash +-H "Authorization: Bearer " +``` + + + + +Start with a `GetServiceInfo` call to verify your connection and check the current chain state. + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/GetServiceInfo +``` + +Expected response: + +```json +{ + "chain": "mainnet", + "chainId": "35834a8a", + "checkpointHeight": "12345678", + "epoch": "500", + "server": "alchemy" +} +``` + + + + +Query a Sui object by its ID using `GetObject`. Use `read_mask` to request specific fields. + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{ + "object_id": "0x5", + "read_mask": "object_id,version,digest,owner" + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/GetObject +``` + + + + +Fetch a transaction by its digest. + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/ledger_service.proto \ + -d '{ + "digest": "YOUR_TX_DIGEST" + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.LedgerService/GetTransaction +``` + + + + +Query the SUI balance for an address. + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/state_service.proto \ + -d '{ + "owner": "0xYOUR_ADDRESS", + "coin_type": "0x2::sui::SUI" + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.StateService/GetBalance +``` + + + + +## Next steps + +* [Sui gRPC overview](/docs/reference/sui-grpc-overview) for the full list of available services and methods +* [Objects and ledger](/docs/reference/sui-grpc-objects-and-ledger) for detailed `LedgerService` documentation +* [Transactions](/docs/reference/sui-grpc-transactions) for executing and simulating transactions diff --git a/content/api-reference/sui-grpc/signature-verification.mdx b/content/api-reference/sui-grpc/signature-verification.mdx new file mode 100644 index 000000000..4183b2c31 --- /dev/null +++ b/content/api-reference/sui-grpc/signature-verification.mdx @@ -0,0 +1,41 @@ +--- +title: Signature verification +description: Sui gRPC SignatureVerificationService API reference +slug: reference/sui-grpc-signature-verification +--- + +The `SignatureVerificationService` provides methods for verifying user signatures. + +## VerifySignature + +Verifies a user signature against a message and address. Supports standard signatures and ZkLogin signatures (via the `jwks` parameter). + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `address` | string | Yes | The address that signed the message | +| `signature` | UserSignature | Yes | The signature to verify | +| `message` | Bcs | Yes | The BCS-encoded message that was signed | +| `jwks` | repeated ActiveJwk | No | Active JSON Web Keys for ZkLogin signature verification | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `is_valid` | bool | Whether the signature is valid | +| `reason` | string | Reason for failure if the signature is invalid | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/signature_verification_service.proto \ + -d '{ + "address": "0xYOUR_ADDRESS", + "signature": {"bcs": {"value": "BASE64_SIGNATURE"}}, + "message": {"bcs": {"value": "BASE64_MESSAGE"}} + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.SignatureVerificationService/VerifySignature +``` diff --git a/content/api-reference/sui-grpc/state-and-balances.mdx b/content/api-reference/sui-grpc/state-and-balances.mdx new file mode 100644 index 000000000..c8d6dcc11 --- /dev/null +++ b/content/api-reference/sui-grpc/state-and-balances.mdx @@ -0,0 +1,164 @@ +--- +title: State and balances +description: Sui gRPC StateService API reference +slug: reference/sui-grpc-state-and-balances +--- + +The `StateService` provides methods for querying coin balances, dynamic fields, and owned objects. + +## GetBalance + +Gets the balance of a specific coin type for an owner address. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `owner` | string | Yes | Owner address | +| `coin_type` | string | Yes | Coin type (e.g., `0x2::sui::SUI`) | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `balance` | Balance | Balance information including total and coin count | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/state_service.proto \ + -d '{ + "owner": "0xYOUR_ADDRESS", + "coin_type": "0x2::sui::SUI" + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.StateService/GetBalance +``` + +*** + +## ListBalances + +Lists all coin balances for an owner with pagination. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `owner` | string | Yes | Owner address | +| `page_size` | uint32 | No | Maximum results to return | +| `page_token` | bytes | No | Pagination token from a previous response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `balances` | repeated Balance | List of balances by coin type | +| `next_page_token` | bytes | Token for the next page of results | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/state_service.proto \ + -d '{"owner": "0xYOUR_ADDRESS"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.StateService/ListBalances +``` + +*** + +## GetCoinInfo + +Gets metadata and treasury information for a coin type. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `coin_type` | string | Yes | The coin type to query | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `coin_type` | string | The queried coin type | +| `metadata` | CoinMetadata | Coin metadata (name, symbol, decimals, etc.) | +| `regulated_metadata` | RegulatedCoinMetadata | Regulated coin metadata if applicable | +| `treasury` | CoinTreasury | Treasury information | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/state_service.proto \ + -d '{"coin_type": "0x2::sui::SUI"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.StateService/GetCoinInfo +``` + +*** + +## ListDynamicFields + +Lists dynamic fields of an object with pagination. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `parent` | string | Yes | Parent object ID | +| `page_size` | uint32 | No | Maximum results to return | +| `page_token` | bytes | No | Pagination token from a previous response | +| `read_mask` | FieldMask | No | Fields to include in the response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `dynamic_fields` | repeated DynamicField | List of dynamic fields | +| `next_page_token` | bytes | Token for the next page of results | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/state_service.proto \ + -d '{"parent": "0xOBJECT_ID"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.StateService/ListDynamicFields +``` + +*** + +## ListOwnedObjects + +Lists objects owned by an address, optionally filtered by type. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `owner` | string | Yes | Owner address | +| `object_type` | string | No | Filter by object type | +| `page_size` | uint32 | No | Maximum results to return | +| `page_token` | bytes | No | Pagination token from a previous response | +| `read_mask` | FieldMask | No | Fields to include in the response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `objects` | repeated Object | List of owned objects | +| `next_page_token` | bytes | Token for the next page of results | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/state_service.proto \ + -d '{"owner": "0xYOUR_ADDRESS"}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.StateService/ListOwnedObjects +``` diff --git a/content/api-reference/sui-grpc/subscriptions.mdx b/content/api-reference/sui-grpc/subscriptions.mdx new file mode 100644 index 000000000..261d62317 --- /dev/null +++ b/content/api-reference/sui-grpc/subscriptions.mdx @@ -0,0 +1,38 @@ +--- +title: Subscriptions +description: Sui gRPC SubscriptionService API reference +slug: reference/sui-grpc-subscriptions +--- + +The `SubscriptionService` provides server-streaming RPCs for real-time data. + +## SubscribeCheckpoints + +Streams new checkpoints as they are finalized. This is a server-streaming RPC that keeps the connection open and sends checkpoint data in real time. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `read_mask` | FieldMask | No | Fields to include in each checkpoint | + +**Response** (stream): + +| Field | Type | Description | +| --- | --- | --- | +| `checkpoint` | Checkpoint | The checkpoint data | +| `cursor` | uint64 | Cursor position for resuming the stream | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/subscription_service.proto \ + -d '{}' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.SubscriptionService/SubscribeCheckpoints +``` + + + This is a long-lived streaming connection. The server will continue sending checkpoints until the client disconnects. + diff --git a/content/api-reference/sui-grpc/transactions.mdx b/content/api-reference/sui-grpc/transactions.mdx new file mode 100644 index 000000000..b85e7f6fa --- /dev/null +++ b/content/api-reference/sui-grpc/transactions.mdx @@ -0,0 +1,74 @@ +--- +title: Transactions +description: Sui gRPC TransactionExecutionService API reference +slug: reference/sui-grpc-transactions +--- + +The `TransactionExecutionService` provides methods for executing and simulating transactions on Sui. + +## ExecuteTransaction + +Submits a signed transaction for execution on the network. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `transaction` | Transaction | Yes | The transaction to execute | +| `signatures` | repeated UserSignature | Yes | Array of user signatures | +| `read_mask` | FieldMask | No | Fields to include in the response | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `transaction` | ExecutedTransaction | The executed transaction result | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/transaction_execution_service.proto \ + -d '{ + "transaction": {"bcs": {"value": "BASE64_TX_BYTES"}}, + "signatures": [{"bcs": {"value": "BASE64_SIGNATURE"}}] + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.TransactionExecutionService/ExecuteTransaction +``` + +*** + +## SimulateTransaction + +Simulates transaction execution without submitting to the network. Use this to estimate gas costs or preview effects. + +**Request**: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `transaction` | Transaction | Yes | The transaction to simulate | +| `read_mask` | FieldMask | No | Fields to include in the response | +| `checks` | TransactionChecks | No | Enable or disable transaction checks | +| `do_gas_selection` | bool | No | Perform automatic gas coin selection | + +**Response**: + +| Field | Type | Description | +| --- | --- | --- | +| `transaction` | ExecutedTransaction | The simulated transaction result | +| `command_outputs` | repeated CommandResult | Output of each transaction command | +| `suggested_gas_price` | uint64 | Suggested gas price for the transaction | + +```bash cURL +grpcurl \ + -H "Authorization: Bearer " \ + -import-path proto \ + -proto sui/rpc/v2/transaction_execution_service.proto \ + -d '{ + "transaction": {"bcs": {"value": "BASE64_TX_BYTES"}}, + "do_gas_selection": true + }' \ + sui-mainnet.g.alchemy.com:443 \ + sui.rpc.v2.TransactionExecutionService/SimulateTransaction +``` diff --git a/content/docs.yml b/content/docs.yml index 90cc11b49..b6e4ef241 100644 --- a/content/docs.yml +++ b/content/docs.yml @@ -2008,6 +2008,33 @@ navigation: path: api-reference/sui/sui-api-faq.mdx - api: Sui API Endpoints api-name: sui + - section: Sui gRPC + contents: + - section: Getting started + contents: + - page: Overview + path: api-reference/sui-grpc/overview.mdx + - page: Quickstart + path: api-reference/sui-grpc/quickstart.mdx + slug: getting-started + - section: API reference + contents: + - page: Objects and ledger + path: api-reference/sui-grpc/objects-and-ledger.mdx + - page: Transactions + path: api-reference/sui-grpc/transactions.mdx + - page: State and balances + path: api-reference/sui-grpc/state-and-balances.mdx + - page: Move packages + path: api-reference/sui-grpc/move-packages.mdx + - page: Name service + path: api-reference/sui-grpc/name-service.mdx + - page: Subscriptions + path: api-reference/sui-grpc/subscriptions.mdx + - page: Signature verification + path: api-reference/sui-grpc/signature-verification.mdx + slug: api-reference + slug: sui-grpc slug: sui - section: Superseed contents: