holon-run/sui-jsonrpc-skill

Sui JSON-RPC Skill

Use this skill to run Sui JSON-RPC operations through uxc + JSON-RPC.

Reuse the uxc skill for shared execution and error-handling guidance.

Prerequisites

• uxc is installed and available in PATH.
• Network access to https://fullnode.mainnet.sui.io.
• No API key is required for the public mainnet fullnode in this skill's default flow.

Scope

This skill covers a safe read-first Sui JSON-RPC surface:

• chain identity and latest checkpoint reads
• checkpoint lookup
• object lookup
• reference gas price reads
• latest system state reads
• pubsub subscriptions for events and transaction effects

This skill does not cover:

• unsafe_* transaction-building methods
• sui_executeTransactionBlock
• wallet signing flows
• custom/private Sui RPC providers with different auth or rate limits

Endpoint And Discovery

This skill targets the public Sui fullnode endpoint:

• https://fullnode.mainnet.sui.io

For pubsub, use a Sui provider WebSocket endpoint that you have verified actually accepts JSON-RPC subscriptions. Do not assume the public HTTPS fullnode host automatically supports the same wss:// hostname for pubsub.

uxc JSON-RPC discovery depends on OpenRPC or rpc.discover. Sui exposes a discoverable method surface, so help-first flow works directly against the endpoint.

Authentication

The default public endpoint used by this skill does not require authentication.

If a user later points the same workflow at a private Sui RPC provider, verify its auth model first before reusing this skill unchanged.

Core Workflow

1. Use the fixed link command by default:

   • command -v sui-jsonrpc-cli
   • If missing, create it: uxc link sui-jsonrpc-cli https://fullnode.mainnet.sui.io
   • sui-jsonrpc-cli -h

2. Inspect operation schema first:

   • sui-jsonrpc-cli sui_getLatestCheckpointSequenceNumber -h
   • sui-jsonrpc-cli sui_getCheckpoint -h
   • sui-jsonrpc-cli sui_getObject -h

3. Prefer read/setup validation before any deeper query:

   • sui-jsonrpc-cli sui_getChainIdentifier
   • sui-jsonrpc-cli sui_getLatestCheckpointSequenceNumber
   • sui-jsonrpc-cli suix_getReferenceGasPrice

4. Execute with key/value or positional JSON:

   • key/value: sui-jsonrpc-cli sui_getCheckpoint id=254502592
   • positional JSON: sui-jsonrpc-cli sui_getObject '{"object_id":"0x6"}'

5. Use uxc subscribe start directly for pubsub streams:

   • uxc subscribe start wss://<verified-sui-rpc-host> suix_subscribeEvent '{"params":[{"Package":"0x2"}]}' --sink file:$HOME/.uxc/subscriptions/sui-events.ndjson
   • uxc subscribe start wss://<verified-sui-rpc-host> suix_subscribeTransaction '{"params":[{"FromAddress":"0x..."}]}' --sink file:$HOME/.uxc/subscriptions/sui-transactions.ndjson
   • uxc subscribe status <job_id>
   • uxc subscribe stop <job_id>

Recommended Read Operations

• sui_getChainIdentifier
• sui_getLatestCheckpointSequenceNumber
• sui_getCheckpoint
• sui_getObject
• suix_getReferenceGasPrice
• suix_getLatestSuiSystemState

Recommended Subscription Operations

• suix_subscribeEvent
• suix_subscribeTransaction

Guardrails

• Keep automation on the JSON output envelope; do not use --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• Stay on the public read-only method surface by default.
• Do not call any unsafe_* methods through this skill without explicit follow-up design and review.
• Do not use this skill for write/sign/submit flows; those need separate wallet/auth guidance.
• Use uxc subscribe start for pubsub methods; the fixed sui-jsonrpc-cli link is for normal request/response methods.
• Subscription jobs should always write to a sink file so events can be inspected and replayed safely.
• Before documenting or automating a Sui pubsub host, confirm the specific provider actually exposes JSON-RPC WebSocket subscriptions; public HTTPS endpoints do not guarantee a matching wss:// endpoint.
• Public RPC availability and rate limits can change over time; if discovery or execution starts failing, re-check the endpoint before assuming a uxc bug.
• sui-jsonrpc-cli <operation> ... is equivalent to uxc https://fullnode.mainnet.sui.io <operation> ....

References

• Usage patterns: references/usage-patterns.md
• Sui documentation: https://docs.sui.io/