Zolana
ExplorerDocsGitHubOpen wallet

Docs · Build on Zolana

RPC and gateway

The JSON-RPC methods the wallets call, the custom methods the gateway adds, and what a gateway lets through.

This page lists what the code in the repository calls and allows. It does not assume that a method exists because another chain has it. Which gateway and which settings the hosted devnet runs is not part of the repository.

The layers

  • Validator RPC is operator-only. In the design records, raw RPC sits behind an operator capability on a loopback address, and raw WebSockets are disabled in that mode. Wallets on a hosted network do not reach it.
  • The invited RPC gateway (tools/testnet_gateway.py) stands in front of the validator. It accepts only POST / with a JSON body, checks an access proof, charges a quota and either forwards an allowed method or answers a custom one itself.
  • The admission service (tools/test_faucet.py) serves POST /join and POST /status when invitations are required.
  • The browser gateway (tools/browser_gateway.py) gives the browser wallet a same-origin front: GET /wallet-config.json, GET /transport.json, POST /rpc, POST /admission/join and POST /admission/status, with a narrower method list.
  • The shielded relay (tools/shielded_relay.py) is attached to the gateway and submits shielded-fee payments.

On a local network there is no gateway: the command-line wallet talks to a validator on loopback HTTP using standard methods.

Access proofs

Every gateway method except getGenesisHash requires the header X-Testnet-Access. Its value is a base64url-encoded JSON proof signed by the wallet’s seed-derived fee key, with these fields:

purpose  network  audience  fee_address  issued_at  expires_at  nonce  body_digest  signature
  • purpose is rpc, join or status. The audience is the RPC URL or the admission URL.
  • A proof expires 600 seconds after it is issued. RPC proofs are reusable session credentials for that time, “not per-request anti-replay signatures”.
  • The wallet must be an admitted, unrevoked, unexpired member. Otherwise the answer is HTTP 403.

Joining needs an operator-issued invitation code (invite1_ followed by 43 base64url characters). The code admits one fee key; in the repository’s admission code the membership lasts seven days.

Methods the gateway accepts

The invited RPC gateway’s allow-list, exactly as in the source:

METHODS = {
    "getShieldedFeeQuote", "submitShieldedPayment", "getShieldedPaymentStatus",
    "getWalletReadBatch",
    "getWalletSyncSnapshot",
    "getWalletHistoryBlocks", "getWalletRetainedHistory", "getWalletRetainedHistoryV2", "getWalletRetainedHistoryV3", "getWalletCanonicalHistory",
    "getGenesisHash", "getHealth", "getVersion", "getAccountInfo", "getMultipleAccounts",
    "getBlocks", "getBlock", "getBlockHeight", "getSlot", "getEpochInfo", "getBalance",
    "getSignaturesForAddress", "getSignatureStatuses", "getTransaction", "getLatestBlockhash",
    "getMinimumBalanceForRentExemption", "getFeeForMessage", "sendTransaction", "getProgramAccounts",
}

Any other method is refused with “RPC method or envelope denied” (HTTP 403). JSON-RPC batch arrays are refused too; a request must be a single object with only the keys jsonrpc, id, method and params.

The browser gateway allows fewer methods. It has no sendTransaction, no getProgramAccounts, no getBalance and no getLatestBlockhash; its only write is submitShieldedPayment, and a test asserts that sendTransaction is refused. The browser wallet uses this path.

Custom methods

These are not standard validator methods. The gateway answers them.

Custom gateway methods
MethodParametersPurpose
getShieldedFeeQuote[]The relay’s current fee and account.
submitShieldedPayment[{network, payload}]Hand one shielded-fee payment to the relay. Returns {id}.
getShieldedPaymentStatus[id] (64 hex characters)A hint about a submitted job: unknown, pending, accepted or aborted.
getWalletReadBatch[[{method, params}, …]], 1 to 16 callsSeveral bounded reads in one request. Inner methods: getAccountInfo, getBalance, getLatestBlockhash, getSlot, getMinimumBalanceForRentExemption, getFeeForMessage.
getWalletSyncSnapshot[saved_slot]One consistent view for a browser sync: pool account, headers and a short canonical tail.
getWalletHistoryBlocks[slots], 1 to 256 strictly increasing slotsFull finalized blocks for the given slots.
getWalletRetainedHistory, …V2, …V3A cursor, a target slot and a checkpoint or tokenPages of retained payment history for rebuilding a balance. V3 is the compact form the browser wallet uses.
getWalletCanonicalHistory[before, target, anchor]Pages from a canonical archive, used to recover an old pending payment. Returns null when no archive is configured.

The relay methods in detail

A quote, as built by the relay:

{
  "format": "native-shielded-fee-quote-v1",
  "network": { ... },
  "payer": "<base58 relay account>",
  "fee": 3000000,
  "transport": "native-inline-v1",
  "pool_format": "NPOOL004"
}

The last two fields are present when the relay is configured for inline payments; the browser wallet requires them. The fee is whatever the relay’s configuration says; 3,000,000 is the value the cohort tooling pins.

submitShieldedPayment takes exactly {network, payload}. The payload is the base64 of a 9,230-byte payment that starts with NPAY0003 and names this network, this relay’s account and this relay’s fee; anything else is refused with “relay fee, payee or native encoding mismatch”. The job id is a digest of the packet, so submitting the same packet again returns the same id. A different member submitting it gets “relay ownership mismatch”.

The relay has finite lifetime capacity. When it is used up the answer is JSON-RPC error -32040, “Testnet private payment capacity reached”, with data.scope set to member or network. Completed jobs keep their slots.

Methods the command-line wallet calls

Through the Solana RPC client library the native wallet uses these standard methods:

getGenesisHash  getAccountInfo  getMultipleAccounts  getBlock  getBlocks  getSlot
getBlockHeight  getEpochInfo  getLatestBlockhash  getBalance
getMinimumBalanceForRentExemption  getFeeForMessage  getSignatureStatuses  sendTransaction
  • getGenesisHash is the handshake. If the answer differs from the configured network the wallet stops with “RPC genesis does not match the wallet network”.
  • History is read as full finalized blocks: getBlock with encoding: base64, transactionDetails: full, commitment: finalized.
  • Staged upload transactions are sent with preflight skipped; the finalizing transaction is sent with preflight on.

Against an invited gateway it uses the custom methods above in place of raw history and batched reads. One further custom method, getNativePrivateTransactionFee, exists on the candidate validator for the relay operator; invited gateways do not expose it.

Methods the browser wallet calls

getGenesisHash  getAccountInfo  getBlock  getBlocks  getSlot
getWalletSyncSnapshot  getWalletRetainedHistoryV3  getWalletHistoryBlocks  getWalletCanonicalHistory
getShieldedFeeQuote  submitShieldedPayment  getShieldedPaymentStatus

All of them are POST /rpc on the wallet’s own origin, without cookies, with caching disabled and redirects treated as errors. Each request times out after 25 seconds. Only the retained-history read is ever retried automatically, once.

Limits and errors

Gateway limits
LimitValue in the code
Request body1 to 32,768 bytes, Content-Type: application/json
ResponseAt most 16 MiB
Requests per memberA configured rate per minute, between 1 and 10,000
Requests, all members6,000 per minute
Requests per network address3,000 per minute for RPC, 240 for admission
Wallets admitted per dayA configured number
Cost of a requestOne unit for an ordinary call; one per inner call of a read batch; one per 16 history slots
Gateway errors
ResponseMeaning
HTTP 403 {"error":"access_denied"}No valid proof, not a member, method not allowed, or a malformed request.
HTTP 429 {"error":"request_limit"}A quota was reached.
HTTP 409 from the join path (capacity_exhausted)The faucet’s lifetime capacity is used up: the cohort is full.
JSON-RPC -32040 with data.scopeRelay capacity reached for this member or for the network.
JSON-RPC -32062A history response would exceed the byte limit.

What the gateway does not check

For the relay methods the gateway and relay check the exact shape of the payment. For the ordinary forwarded methods, including sendTransaction on the invited RPC gateway, the code checks membership, quota, envelope and size and then forwards the request body unchanged. A test asserts that the forwarded bytes are identical. The gateway is an access and rate control, not a transaction filter.

It is also not a consensus rule. The design record says invited RPC access “is not a consensus permission rule; public peer/TPU exposure would require its own deployment policy”.

Your privacy
has a boundary.

Zolana is an independent blockchain for native shielded deposits, private transfers and withdrawals. The browser wallet creates proofs and decrypts its own notes locally.

Shielded details

Payment amounts and receiving addresses are protected by proofs. Your spending and viewing keys stay on your device.

Public evidence

Blocks, timing, fees, nullifiers and public deposit or withdrawal accounts and amounts remain visible.

The invited gateway knows your membership and receiving address. It sees your IP address and request timing and can link your submissions. This is not a claim of complete anonymity.

Valueless test coins. No Solana bridge, SOL/USDC deposits, post-quantum protection or audited-security claim.