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/