Reading foreign evidence with HILSA

Use HILSA reads when a local decision depends on a supported foreign fact and the strength of its evidence. A read returns the value, its verification class, and its finality class together. The shared implementation rejects a fact that falls below either requested minimum.

For a deposit-backed strategy, the first question is not simply “did a service return true?” It is “which source chain and deposit does this record describe, under which verifier and anchor, and is that evidence sufficient for the action?” HILSA provides common state and policy primitives for answering that question. The application still supplies the business binding and freshness policy.

Use this explanation to design a read policy. The readiness task checks endpoint evidence; the interface reference owns exact RPC requests and VM encodings.

A concrete policy outcome

The source unit tests seed a committed Ethereum head with QuorumObserved/Finalized, then request Reexecuted/Finalized. The result is TrustDowngrade, numeric code 2. Finality alone cannot satisfy a stronger verification demand. Another test holds verification constant and rejects insufficient finality. These are deterministic fixture checks, not observations of live Ethereum verification. They were inspected, not executed during this documentation run. Policy tests.

What can be read

The current ReadQuery variants have deliberately different meanings:

HILSA chain IDs are unsigned 32-bit catalog keys. The bridge plane uses its own unsigned 64-bit chain numbering. In a deposit query, the caller supplies both the bridge ID and the HILSA attribution. The resolver does not derive that mapping or prove the historical deposit again. Bind both IDs and the nonce to the intended source in your application; do not let an untrusted caller choose an unrelated stronger head to label a tracker result. A missing tracker gives false once the attributed head exists. Query schema and resolver, deposit attribution.

A chain commitment is also not automatically an account-state root of the same kind on every chain. It may represent a world-state root, bank hash, or other chain-specific commitment. The verifier and proof format determine what can be opened beneath it. Chain commitment fields.

One local snapshot, explicit age

The block prologue prepares the HILSA snapshot from the end of the preceding block. In block H, execution reads the H - 1 committed view. This makes the read independent of network timing, the feeder daemon, and the RPC server's latest process-local status.

This is useful when an application combines evidence from several chains: its local decision has a common snapshot boundary. It is not a global simultaneity guarantee. A stopped feed can leave an old foreign head inside a newer local snapshot. A finalized fact can also be too old for a price-sensitive decision.

Check foreign height or other available age evidence according to your application policy, and compare it with a trusted progression signal. The minimum finality gate does not check freshness. For map-backed VM readers, declare the required accounts: an undeclared account is not available simply because it exists elsewhere in the node's state. Snapshot and account-reader contract.

The committed snapshot omits the current eto_state root to avoid a circular commitment. It is not interchangeable with the separately constructed, attested InteropRoot.

Supplied proofs answer a different read question

The separate hilsa_proveRead RPC accepts caller-supplied EVM account/storage MPT proofs and checks them against the chain's admitted head. Arbitrum, Base and Optimism use direct MPT roots; BNB requires a supplied block header whose hash matches the admitted commitment before its state root can be used. The caller obtains the proof, and its validity inherits the admitted root's anchor, registry and achieved verification class. The helper does not fetch arbitrary foreign data or implement Ethereum beacon-to-execution linkage. Root profiles, RPC handler.

This is distinct from the unsupported in-consensus Subtree variant above. Use HILSA interfaces for exact proof inputs, bounds and errors, and availability for the observed deployed proof/settlement gate.

Select verification and finality independently

The VM-facing numeric verification strengths are exact wire values:

Finality ranks are 40 for Finalized, 30 for Justified, 20 for Optimistic, and 10 for Work. The common gate compares verification strength and finality rank independently. An unknown numeric class is rejected rather than clamped to the weakest value. Work rank 10 does not require a particular cumulative chainwork amount; inspect the returned work value and apply your own threshold. Class definitions, numeric decoding and gate.

For an aggregate snapshot, the read reports the weakest verification and finality categories among contributing heads. An empty snapshot falls back to local execution classes because no foreign head contributed. Do not interpret that fallback as evidence that a requested foreign chain exists.

A withdrawal record receives local Reexecuted/Finalized labels. Those labels describe Singularity's own recorded action; they do not establish that another chain released assets. Aggregate and local labels.

Trace the authority behind the class

An application should assess four linked objects: the source artifact, the verifier that accepts it, the current registry, and the initial or replacement anchor.

The observer feed builders produce HILSA-specific signed observations. In the generic cert-native module, the signature preimage includes a HILSA domain, chain, epoch, height, and block hash. Receiving ConsensusVerifiedCert from that path does not mean it parsed a native Sui, Aptos, or other chain's certificate. The class describes the module's category; provenance requires inspecting the actual accepted bytes. Observer builders, generic certificate implementation.

Registry continuity also needs module-specific review. For example, the generic certificate's canonical signature preimage does not include next_epoch_registry, although apply copies that field when the epoch advances. This implementation does not establish a universal cryptographically bound native validator-set handoff. Avoid turning the registry module's architectural comments into a blanket guarantee.

A separate Ethereum native-attestation path derives the attesting committee and checks BLS over the SSZ signing root. It refuses a missing anchored fork context. Its existence is not evidence that the configured observer daemon provisions every native registry, RANDAO input, and artifact needed for that path. Native attestation entry.

Initial chain-state accounts are provisioned as anchors. Later reanchors require the persisted authority as an outer transaction signer, the expected sequence, and the next receipt account. They may replace the same chain's same-family slot and head. This authority is an explicit trust boundary. The feed helper describes holding it in a daemon as a testnet arrangement; production governance is an integration responsibility, not a property conferred by a class label. Reanchor validation, feeder authority posture.

Re-execution has a defined profile

The consensus CILX path currently registers only EvmTransferVm. It requires a full-state witness, verifies its root against the committed parent, replays the supported payload, and compares the resulting world-state root. A touched-account subset cannot establish the complete root. Beacon-block-root and derived-output-root bindings are unsupported by this path.

The transfer profile is not arbitrary contract execution. Unsupported extensions or operations do not earn a stronger class. A supported replay that disagrees with the admitted commitment is a halt condition, not a reason to silently retain a convenient stronger label. Other VM replay helpers and a CuEVM implementation do not make those engines members of the consensus registry. Registry, root and witness checks.

Read failures carry different meanings

Handle the stable read errors distinctly:

Use HILSA interfaces for VM and RPC encodings. Use writes and settlement when a successful read must lead to an external action, and the alternatives guide when arbitrary foreign calls or a different trust architecture are the primary requirement.