Setting up your RPC

The SDK does not talk to the blockchain directly. It asks an RPC endpoint — a server that keeps a copy of the chain and answers questions about it. You supply that endpoint; the SDK never picks one for you.

import { createSolanaRpc } from '@solana/kit';

const rpc = createSolanaRpc('https://testnet-rpc.z.ink');

The public endpoint

https://testnet-rpc.z.ink is the public endpoint for the z.ink test realm. It is what the examples use, and it is enough to get started.

It is shared infrastructure. Expect rate limiting under load, and do not build anything you care about on top of it.

When to bring your own

Move to your own endpoint when you are polling on a schedule, serving other people, or seeing rate-limit errors. A provider with z.ink support, or your own node, both work — the SDK only needs something that speaks the Solana JSON-RPC protocol for this network.

Mainnet endpoints will not work

SAGE C4 runs on z.ink, not Solana mainnet. Pointing the SDK at a mainnet RPC gets you a working connection to the wrong chain: the Game account simply is not there, and reads fail in confusing ways rather than saying “wrong network”.

If reads fail immediately and consistently, check the endpoint first.

Using it from a browser

Reads work directly from browser code — https://testnet-rpc.z.ink sends permissive CORS headers, so no proxy is needed.

This is worth knowing because it shapes what you can build. A dashboard that reads fleet state needs no backend at all: the browser talks to the RPC, and the SDK decodes the response. Since the SDK is read-only, there is nothing to secure and no key to protect.

If you use a different provider, check its CORS policy before assuming the same.

Freshness

Every read accepts a maximum age. The SDK caches decoded accounts, and a read inside that window is served from cache rather than the network.

const sage = createSageClient({
  cluster: 'zink-ptr',
  rpc,
  defaultMaxAgeMs: 10_000,
});

That default applies to every read unless a specific call overrides it. Raising it cuts RPC traffic; lowering it costs requests. How the SDK thinks covers the caching model properly.

Why staleness is usually fine

Most SAGE state changes on the scale of minutes or hours, not milliseconds. A mining operation runs for a while; a fleet in transit arrives at a known time; a starbase upgrade takes real time to complete.

Reading fleet state that is ten seconds old is almost always correct. The exceptions are the ones you would expect — anything racing another player, like a market order.