HILSA interfaces and integration contracts

HILSA exposes three different kinds of interface: committed-state reads, proof/certificate services, and builders that return instructions for a caller-signed transaction. Choose the surface that matches your job. A proof response is not a transaction, a builder is not submission, and a process-local status view is not a consensus account.

Start with what HILSA enables, read policy, or write settlement for the mechanism. This page owns exact parameters, results, errors and VM encodings. For the ordered diagnostic procedure, use Check HILSA readiness.

Observed deployment: at 2026-09-08 00:19 UTC, the public endpoint served a 51-entry catalog, reported no connected Ethereum head, and returned empty feed-status arrays. hilsa_getAttestation {"quorum":true} returned -32012, stating that protocol-v8 durable roots, proofs, attestations, outbox, mint, unlock, and withdrawal routes were safety-paused. The source contracts below describe this inspected checkout; they are not a claim that those routes are available on that deployment. At 01:44 UTC, a fresh probe of health, version, genesis, catalog, head, feed and quorum attestation returned -32000 with Upstream error (HTTP 521). The availability reference preserves both observations; an older successful discovery response is not a current availability guarantee.

Request conventions

Use JSON-RPC 2.0 over HTTP POST. Most HILSA handlers in this checkout expect an object in params; this differs from many Solana-shaped methods. Exceptions include hilsa_chainInfo, which expects params[0], and instruction builders that explicitly accept an object or a one-element array.

curl -sS --max-time 15 https://rpc.entropytoorder.xyz \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"hilsa_chainHead","params":{"chain":2}}'

At 00:19 UTC on 8 September 2026, this read-only request returned {"connected":false,"head":null}; the 01:44 UTC repeat returned the upstream error described above. Chain 2 is Ethereum in the earlier returned catalog. Discover IDs through hilsa_chainCatalog; do not substitute an EIP-155 chain ID.

Many methods retain eto_cil* aliases, but alias coverage is explicit in the dispatcher. The source CLI's raw rpc and namespace commands require the newer source interface; published CLI 0.3.0 did not expose rpc in the executed check. Direct HTTP is independent of that client limitation. Dispatcher.

Read and discovery methods

Public keys accepted by these balance/builder helpers use hex32 or base58. Prefer decimal strings for input amounts and nonces where accepted, so JavaScript does not round values above 2^53 - 1. Do not assume every old response is precision-safe: account_nonce is emitted as a JSON number in this checkout, while corridorNonce is a string.

Catalog class_ceiling is intended capability. The actual head class comes from the committed chain-state account. Feed quorum status describes artifact assembly, not proof that consensus applied the artifact. Catalog and ID contract, committed head, balance and nonces.

Verify caller-supplied foreign account and storage proofs

hilsa_proveRead is a useful additional capability beyond the in-consensus ReadQuery variants. It verifies a supplied EVM account/storage proof against a head already admitted into committed HILSA state. The RPC handler does not fetch the proof from a foreign endpoint and does not insert a verified value into the VM snapshot.

Its object parameters are:

The proof-system dispatch currently supports:

• Arbitrum, Base, and Optimism: the admitted commitment is treated as the MPT world-state root.
• BNB: the caller supplies a header whose Keccak hash must match the admitted block commitment; the state root is extracted from that header.
• Ethereum: unsupported here because the admitted beacon-block root lacks the implemented SSZ link to execution state.
• Solana, Bitcoin, CometBFT, other cert-native families, and remaining rollup formats: unsupported by this MPT endpoint.

These are code paths, not verified deployed feeds. A valid trie proof authenticates data relative to its root; the active head's artifact, anchor, registry, and verification policy determine why that root is trusted. The proof does not improve an observer-derived root into native consensus verification. Proof-system dispatch.

Success returns verified:true, chain, proof-system tag, root-binding tag, state root, head height/hash, actual verification class, account presence, decimal-string nonce/balance, storage root/code hash, and storage entries with presence and value. Missing trie nodes are errors, not proof of absence. Limits include 512 proof nodes, 64 KiB per node, and 64 storage queries. The handler uses committed chain state and rejects unsupported systems before proof work. RPC verification and result.

hilsa_verifyRead is different. It accepts chain, key, value, stateRoot, proof:[{sib,left}], minClass?, requireFinalized? for HILSA's generic SHA-256 Merkle format. It is not an alternative encoding of an Ethereum MPT proof. Both RPCs default to certificate class and finalized evidence; accepted class strings are reexecuted, consensus-verified-full, consensus-verified-cert, work-verified, consensus-federated, and quorum-observed. The inspected parser rejects unknown strings; callers should supply fields with their documented types. Generic read verification.

Build a transaction without giving the server a key

The durable product builders return:

programId
accounts: [{pubkey, isSigner, isWritable}, ...]
data: 0x-prefixed instruction bytes
requiredSigners: [public key, ...]

The caller creates the outer SVM transaction, assigns its funded fee payer and recent blockhash, includes the returned instruction unchanged, signs with every required signer, submits with sendTransaction, and checks the receipt. A builder response does none of those last steps.

Transfer and burn builders accept account_nonce as an alias for accountNonce; burn also accepts corridor_nonce. Supplying both spellings is an error. A signature is exactly 64 hex-encoded bytes and is verified before the instruction is returned. The owning key must also sign the outer transaction. Builder parsing and results.

The inner authorization preimages are exact byte concatenations:

transfer:
"HILSA_TRANSFER_V1" | local_domain:u32-LE | from[32] | to[32] |
mint[32] | amount:u64-LE | account_nonce:u64-LE

burn:
"HILSA_BURN_V1" | local_domain:u32-LE | owner[32] | mint[32] |
amount:u64-LE | destination:u32-LE | account_nonce:u64-LE

The local HILSA domain is currently zero. The inner burn signature does not include corridorNonce; the outer signed transaction commits to the complete instruction, and execution checks the supplied corridor nonce. Obtain the current owner/corridor nonces before building. A competing transaction can make the plan stale; rebuild deliberately rather than assuming a cached plan reserves a nonce. Authorization bytes.

hilsa_buildGenesisAnchor, hilsa_buildMintConfig, and hilsa_buildMintRoute return account/configuration material for authorized provisioning. Building bytes does not grant installation authority. Artifact builders similarly do not validate a live route merely by serializing an artifact. Anchor builder, artifact output.

Legacy hilsa_sendMessage, hilsa_transfer, hilsa_burn, hilsa_mint, hilsa_mintIntent, hilsa_anchorChain, and hilsa_submitArtifact intentionally return migration errors, generally -32010. They previously bypassed consensus or used volatile state. There is no active general-message RPC builder equivalent to the disabled sendMessage method in this checkout. Disabled mutations, anchor/artifact migration.

Pair proofs with the correct certificate

hilsa_proveMessage {"dst":ID,"nonce":N} returns the message, branch, outbox root, local block, root opening fields, and root hash. Obtain an attestation for that same root and block. Recompute the message leaf from its fields; do not trust the server's supplied leaf without checking it.

hilsa_getAttestation accepts {"block":N} or positional [N]; absent block selects the latest retained certificate. {"quorum":true} selects the newest retained BLS quorum certificate and defaults its scheme to BLS. An explicitly incompatible scheme with quorum selection is rejected.

Schemes differ materially:

The response includes root, block, epoch, bitmap, decimal-string stake totals, and meets_two_thirds. Check the exact signature scheme and destination verifier. HilsaGateway expects sorted recovered secp signer addresses; do not assume index-sorted RPC concatenation already has that ordering.

hilsa_getValidatorSet serves the current set, even when an epoch field was requested in this checkout. Compare the returned epoch with the certificate. It exposes indices, keys, stake, set commitment, and BLS proof-of-possession information. A fetched set still needs a trusted anchor or authenticated transition. Certificate selection and schemes, validator set.

hilsa_rootAt {"block":N} and hilsa_roots {"from":N,"limit":K} serve the retained root window; listing defaults to 20 and is bounded to 1,000. hilsa_proveRootInclusion is disabled pending a consensus-persistent historical accumulator. A missing old proof is not evidence that its message never existed. hilsa_messageStatus and hilsa_outbox are ingress views, not a substitute for durable message-account inspection. Root history boundary.

Call the committed read API from a VM

All projections use the class strengths and finality ranks described in verified reads, but their ABI differs.

EVM: address 0x0000000000000000000000000000000000000106 exposes chainHead(uint32,uint8,uint8), interopSnapshot(uint8,uint8), and depositProcessed(uint64,uint32,uint64,uint8,uint8). They cost 2,000, 6,000, and 3,000 gas respectively in the host precompile. Head output is eight ABI words; the current snapshot output is eight words including appended outbox root/count, despite the older six-field selector comment. Failure uses HilsaReadError(uint32), selector 0x81a5ddfb; code zero denotes malformed calls. This host path must be distinguished from arbitrary nested calls inside GPU EVM execution. Selectors, implementation.

WASM: imports under env are hilsa_chain_head(chain,minV,minF,outPtr), hilsa_interop_snapshot(minV,minF,outPtr), and hilsa_deposit_processed(bridgeChain,attributedChain,nonce,minV,minF,outPtr). Successful record lengths are 142, 114, and 3 bytes. Scalars are little-endian except the 32-byte weight, which is big-endian; read failures return the negated shared error code. The host also checks memory bounds and fuel. Record encoding, import binding.

Move: the native table uses address 0x0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d, module read, functions chain_head, interop_snapshot, and deposit_processed. Numeric inputs use u64 with range checks. Read failures abort at 0x20 + code; invalid class is 0x2f. The table must actually be installed in the selected Move execution path. Move ABI.

SVM: a CILV read-guard instruction under the CIL artifact program carries magic, version 1, query kind, minimum verification, minimum finality, and little-endian query payload. It declares the exact read-only accounts and fails the transaction when policy is not met. A following instruction can then consume the guarded data. A raw account decoder alone does not enforce that policy. Read-guard wire contract.

No Bombil-specific HILSA host ABI is established by these interfaces. See Bombil for the VM's current name and dispatch gates.

Integration failure handling

Keep transport errors, -32602 malformed parameters, -32603 invalid internal state, -32001 unavailable head/certificate, -32010 disabled capability, and deployment-specific -32012 pause distinct. Source proof rejection commonly uses -32000; BLS unavailability uses -32011. Preserve the message and method as well as the number because error meanings are contextual.

A complete acceptance test should include a valid proof, a missing proof node, a wrong root, a weaker-than-required head, a stale nonce, and a mismatched certificate/set epoch. Source tests cover these kinds of boundaries through fixtures; this documentation run executed discovery/status requests only, without submitting HILSA transactions or asserting a live proof route.