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 onlyPOST /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) servesPOST /joinandPOST /statuswhen 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/joinandPOST /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
purposeisrpc,joinorstatus. 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.
| Method | Parameters | Purpose |
|---|---|---|
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 calls | Several 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 slots | Full finalized blocks for the given slots. |
getWalletRetainedHistory, …V2, …V3 | A cursor, a target slot and a checkpoint or token | Pages 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
getGenesisHashis 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:
getBlockwithencoding: 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
| Limit | Value in the code |
|---|---|
| Request body | 1 to 32,768 bytes, Content-Type: application/json |
| Response | At most 16 MiB |
| Requests per member | A configured rate per minute, between 1 and 10,000 |
| Requests, all members | 6,000 per minute |
| Requests per network address | 3,000 per minute for RPC, 240 for admission |
| Wallets admitted per day | A configured number |
| Cost of a request | One unit for an ordinary call; one per inner call of a read batch; one per 16 history slots |
| Response | Meaning |
|---|---|
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.scope | Relay capacity reached for this member or for the network. |
JSON-RPC -32062 | A 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”.