Interchain JSON-RPC reference

Documentation index. Source: public xgr-node jsonrpc/xgr_interchain.go, xgr_interchain_validators.go, xgr_iln_quorum.go, xgr_iln_indexer_status.go.

Parameter conventions

The examples below are request/response shapes, not observations of a live transfer. Replace ROUTE, MESSAGE_ID, SOURCE_BLOCK, SET_ID and PROPOSAL_ID with independently obtained values. Numeric uint64 parameters use JSON numbers, not hex quantity strings. Very large numbers require an exact-integer client; do not round with JavaScript Number.

For route ID 0x followed by 64 lowercase hex digits, the canonical node route name is:

iln_<sourceDomain>_<destinationDomain>_<routeIdWithout0x>

The parser rejects zero domains, zero route ID, extra components, nonhex characters and noncanonical decimal representations. A route name is not just base or arbitrum; those names are used for physical-chain configuration/membership commands.

xgr_requestILNQuorum(route, messageId, sourceBlockNumber)

Parameters, in order: canonical route name (string), nonzero 0x-prefixed 32-byte original message ID (string), nonzero original source RPC block number (uint64). This creates an idempotent discovery/processing hint, not an instruction to sign supplied bytes. The worker must reconstruct and validate actual source evidence.

{"jsonrpc":"2.0","id":1,"method":"xgr_requestILNQuorum","params":["ROUTE","MESSAGE_ID",12345678]}

Successful result shape:

{"route":"ROUTE","messageId":"MESSAGE_ID","sourceBlockNumber":12345678,"status":"PENDING"}

The node requires a fresh worker heartbeat (10-second admission check), local Interchain storage and either a discovered route or parseable deterministic discovery hint. Unknown route hints and per-route message request queues are bounded to 128 entries. A 15-minute request lease permits retry of stale hints; repeating the same identity/source block is idempotent. Reusing a live request with a different source block is rejected. Queue admission never replaces Registry/source validation.

Typical error messages include ILN worker not available, route is not configured or discovered locally, ILN discovery hint queue full, ILN request queue full; retry later, invalid message ID, missing source block and conflicting persisted request identity.

xgr_getILNQuorum(route, messageId)

{"jsonrpc":"2.0","id":2,"method":"xgr_getILNQuorum","params":["ROUTE","MESSAGE_ID"]}

Returns route, messageId, sourceBlockNumber, status and, when recorded, votes, quorumThreshold, failureCategory, updatedUnix.

Status	Meaning and action
NOT_FOUND	No local archived quorum/progress/request; request the original message using its source block
PENDING	An admission hint exists; no conclusion about valid signatures yet
EXPIRED_RETRY	Admission hint exceeded its lease; repeat the same original identity
PARTIAL_QUORUM	Recorded valid progress below threshold; inspect votes/eligible validator availability
RETRYING_VALIDATION	Worker is retrying canonical evidence validation; inspect failure category/source RPC
AVAILABLE_UNVERIFIED	Local quorum data exists; current destination set and execution validity still require verification

Progress records are diagnostics, not authorization. The implementation bounds accepted progress-record size and age, and matches recorded route/message identity. AVAILABLE_UNVERIFIED can refer to a stale set after rotation and is never equivalent to Mailbox.delivered == true.

xgr_getILNQuorumAttestation(route, messageId, setId)

{"jsonrpc":"2.0","id":3,"method":"xgr_getILNQuorumAttestation","params":["ROUTE","MESSAGE_ID",7]}

Returns the complete archived attestation for the explicitly requested nonzero destination set. It does not silently choose another set. The reader enforces Direct-BLS domain, required fields, canonical payload consistency, nonempty bitmap and aggregate lengths. It returns an error if no matching attestation exists, storage is invalid or archived identity/set does not match.

Result field	Type and meaning
version	XITA_DIRECT_MESSAGE_V1
chain, optional destination	Node route label and destination diagnostic label
originChainId, originDomain, destinationDomain	Signed source/destination identities
routeId, setId, sourceBlockNumber	Signed directed route, destination epoch and original source block
registry, gateway, sourceRouter, mailbox	Signed source contract bindings
destinationRouter, destinationIsm, destinationRegistry	Signed recipient/authentication contract bindings
validatorFeeWei	Exact unsigned fee as a decimal string
authorizedMessageId	Original dispatched message hash
payload	Canonical fixed-width signing bytes, hex
signerBitmap	Bitmap in canonical destination Registry order, hex
aggregateSignatureCompressed	96-byte compressed aggregate, hex
aggregateSignature	256-byte EIP-2537 aggregate, hex

Do not sort validators before interpreting the bitmap. Compare setId with the live destination registry and verify the quorum/ISM on that destination. The archival read does not prove that the set is current, that the recipient can execute or that the message has not already been delivered.

xgr_getInterchainAttestation(route) and xgr_getILNInterchainAttestation(route,messageId)

These compatibility methods read the route's latest archive or its message archive respectively. They return the same validated Direct-BLS result structure. Old implementation comments or method labels containing “checkpoint” do not turn the current result into a Merkle proof. For delivery prefer the explicit-set method above, because an arbitrary latest entry need not be the desired message/current set. xgr_getInterchainAttestationByCheckpoint is not documented as a supported current method.

xgr_getInterchainValidators(destinationName)

{"jsonrpc":"2.0","id":4,"method":"xgr_getInterchainValidators","params":["base"]}

Result fields: destination, chainId, domain, configured registry, setId, count, quorumThreshold and ordered validators entries with address and 48-byte compressed blsPublicKey. This reads the configured destination's membership set; callers cannot supply their own RPC/Registry. It rejects unknown destinations and invalid, empty, duplicate or malformed set entries.

Quorum threshold is ceil(2*n/3) = (2*n+2)/3 with integer division. This is not XGRChain stake-weighted voting. A one-member set is representable; the API does not prove sufficient operational decentralization or current node uptime.

xgr_getILNGovernanceQuorum(proposalId)

{"jsonrpc":"2.0","id":5,"method":"xgr_getILNGovernanceQuorum","params":["PROPOSAL_ID"]}

Read-only retrieval of a completed source fee quorum. Result fields: version, proposalId, sourceChainId, sourceDomain, registry, decimal-string validatorFeeWei, setId, nonce, Unix validUntil, canonical hex payload, signerBitmap, both aggregate signature encodings. Reading does not create, approve or execute a proposal. Validate source bindings, current set, expiry and next on-chain nonce before execution; the method does not expose a route-admission governance mechanism.

xgr_getILNIndexerStatus()

{"jsonrpc":"2.0","id":6,"method":"xgr_getILNIndexerStatus","params":[]}

Top-level fields: version (schema 2), updatedUnix, workerAlive, state, routes. Each route includes route, source, destination, state, sourceHead, scanCursor, blockLag, sourceHeadKnown, scanCursorKnown, optional lastSuccessfulScanUnix, updatedUnix, optional error.

The implementation marks a heartbeat snapshot older than two minutes, or more than 30 seconds in the future, as stalled. It derives aggregate state from worker and per-route states; therefore inspect per-route errors and timestamps rather than treating a single summary string as a cryptographic health certificate. Unknown head/cursor fields are not evidence of zero lag. This monitor is independent of the XITA transfer indexer's database.

HTTP transport and error handling

curl -fsS http://127.0.0.1:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"xgr_getILNIndexerStatus","params":[]}'

Check JSON-RPC error, not only HTTP status or curl exit code. Application errors use the node dispatcher's JSON-RPC envelope with a message; this reference does not assign invented stable error codes to implementation errors. Missing files, malformed storage, worker unavailability and destination RPC failures must remain visible and must not be transformed into successful proof readiness. Deploy authenticated/rate-limited RPC infrastructure according to operator policy; public quorum hints never provide arbitrary signing authority.

Local storage diagnostics

Disk usage is exposed by the local xgrchain ibft interchain storage-status --json command, not by an Interchain JSON-RPC method. See the CLI result schema. The eight methods above expose message, membership, fee-quorum and worker state; they do not expose filesystem counters.