gRPC

Galene serves the modern Sui gRPC interface (sui.rpc.v2) over the same fork state as JSON-RPC. So a gRPC client points at the local fork and reads forked on-chain state, submits transactions, and streams the fork as it changes.

It runs alongside JSON-RPC. By default on 127.0.0.1:9000.


# served with the fork
galene start                       # gRPC on 127.0.0.1:9000
 
galene start --grpc-addr 0.0.0.0:9000   # bind elsewhere (also GALENE_GRPC_ADDR)
galene start --no-grpc                  # JSON-RPC only

The gRPC and JSON-RPC servers share one fork state. A cheatcode over JSON-RPC is visible to a gRPC client immediately, and the other way around.

Services

Served from the official Sui SDK protos.

LedgerService

RPCsui.rpc.v2.LedgerService

Method	What it does
`GetServiceInfo`	Chain id, epoch, checkpoint height, and server info.
`GetObject`	Read one object from the fork (copy-on-read on a miss). Serves Move packages too.
`BatchGetObjects`	Read many objects in one call.
`GetTransaction`	Fetch a transaction and its effects.
`GetEpoch`	The current epoch.
`GetCheckpoint`	A checkpoint by sequence number or digest. See checkpoints on a fork.

StateService

RPCsui.rpc.v2.StateService

Method	What it does
`ListOwnedObjects`	An owner’s objects, with type filtering and paging.
`ListDynamicFields`	A parent’s dynamic fields. An empty local result is filled from upstream (copy-on-read), so forked tables and bags list their real children.
`GetBalance` / `ListBalances`	Coin balances for an owner.
`GetCoinInfo`	Coin metadata, from the built-in registry first, upstream otherwise.

TransactionExecutionService

RPCsui.rpc.v2.TransactionExecutionService

Method	What it does
`ExecuteTransaction`	Submit a transaction. Galene forks every object it needs, then runs it.
`SimulateTransaction`	Dry-run a transaction and roll it back. The fork is untouched.

SubscriptionService

RPCsui.rpc.v2.SubscriptionService

Method	What it does
`SubscribeCheckpoints`	A live stream of the fork’s transactions as they land, each with its digest, status, and balance changes. The cursor is the fork’s checkpoint height.

CheatcodeService

Every cheatcode is reachable over gRPC, so a gRPC-only client never needs a second JSON-RPC client. The common ones have typed RPCs on galene.v1.CheatcodeService: Faucet, MintCoin, SetGas, WarpEpoch, SetClock, Impersonate, ForkObject, Snapshot, Revert, and Reset. The rest go through the generic Call, which takes any method name from the cheatcode reference with JSON params.


# mint USDC over gRPC
grpcurl -plaintext -d '{"coin_symbol":"USDC","amount":1000000,"recipient":"0x..."}' \
  127.0.0.1:9000 galene.v1.CheatcodeService/Faucet
 
# anything without a typed RPC goes through Call
grpcurl -plaintext -d '{"method":"galene_dumpState","params_json":"{}"}' \
  127.0.0.1:9000 galene.v1.CheatcodeService/Call

Health

Standard grpc.health.v1.Health, per service rather than a rubber stamp. When the upstream node is unreachable, the read services report NOT_SERVING while execution and cheatcodes stay SERVING, because those run entirely on local state.


grpcurl -plaintext -d '{}' 127.0.0.1:9000 grpc.health.v1.Health/Check
# {"status": "SERVING"}

Checkpoints on a fork

A fork has no real checkpoint production, so Galene synthesizes one checkpoint per committed transaction. The height is 1-based and shared across the whole surface: GetServiceInfo reports it, GetCheckpoint looks it up, SubscribeCheckpoints uses it as the cursor, and the JSON-RPC Checkpoint transaction filter matches on it.

GetCheckpoint carries full transaction detail for the newest 50 heights, and digest, status, and balance changes out to 1,000. Older or unknown heights return an empty placeholder instead of an error, so clients that poll for a head never fail. Numbering restarts at 1 on galene_reset and galene_loadState.

Server reflection

The server registers reflection (both v1 and v1alpha), so clients discover the schema without local .proto files. grpcurl and Postman work out of the box.


# list services
grpcurl -plaintext 127.0.0.1:9000 list
 
# describe a method
grpcurl -plaintext 127.0.0.1:9000 describe sui.rpc.v2.LedgerService.GetObject
 
# read an object
grpcurl -plaintext -d '{"object_id":"0x6"}' \
  127.0.0.1:9000 sui.rpc.v2.LedgerService/GetObject