Cross-chain trust model

Design document, published from the repository at docs/networks/CROSS_CHAIN.md.

Principle: a credential verified on one chain is not valid on another by default.

An issuer registers in the QuantLayerCredentialRegistry of one chain, the source, and the status of its credentials lives there. A verifier serving another chain, the target, learns nothing from the source unless it has decided to trust the source for that issuer, and is shown evidence it can authenticate.

The implementation is verifyCrossChainCredential in packages/networks/src/crosschain.ts. It fails closed.

What a verifier must configure

A CrossChainTrustPolicy belongs to exactly one target chain and lists explicit rules:

{
  targetChainId: 4663,                // Robinhood Chain
  rules: [{
    sourceChainId: 42161,             // Arbitrum One
    issuerIds: [0x1234n],             // named issuers only; no wildcards
    evidence: ['source-state-proof', 'issuer-attestation'],
    maxAgeSeconds: 900,
    headerQuorum: 2,                  // independent RPC endpoints for the source chain
  }],
}

A request is denied unless a rule matches its source chain, issuer and evidence kind. The verifier must also have adapters for the source chain.

Evidence kinds, use cases and assurance

EvidenceUse whenHow it is authenticatedAssuranceWhat you trust
target-registrySource = target (same chain)Read the registry at the network's settlement tag (finalized on Arbitrum chains)target-nativeThe chain (and your RPC)
source-state-proofDifferent chains; no issuer involvement needed; status as of a finalized source blockEIP-1186 account and storage proofs of the source registry, verified (Merkle-Patricia, Keccak-256) against a source header that headerQuorum independent endpoints agree on at the settlement tag. The registry's code hash is part of the proven account and must match a known QuantLayerCredentialRegistry build.state-proof:header-quorumThat the quorum endpoints don't collude to forge a header
issuer-attestationDifferent chains; fresher than finality allows, or the issuer must vouch explicitlyAn EIP-712 CredentialStatusAttestation naming the source chain (domain and message), the source registry, the credential, the status and the target chain, with a short validity. The signer must be the issuer authority recorded by the source registry, established by a source state proof.issuer-attestedThe issuer's key and its statement (plus the quorum, for the authority)

Every result names its evidence kind and assurance, lists each check that ran, and records the source block it relied on (observed).

Why a target registry can't vouch for another chain

target-registry is accepted only when source = target. A status in the target's registry says nothing about the source chain.

The tests make this concrete. The same deployer and nonce give the same contract address on two chains, and those two contracts hold different state. Addresses are never identities across chains; the chain id must always be bound.

Checks, in order

  1. Policy. The policy is for this target, has a rule for this source, the issuer is listed, and the evidence kind is accepted. target-registry requires source = target.
  2. Registry. The source registry is recorded in the ContractRegistry (from a real deployment), and its live code is a known QuantLayerCredentialRegistry build.
  3. Header quorum (proof and attestation kinds).
    • headerQuorum distinct endpoints are required; the same endpoint twice doesn't count.
    • Every endpoint must report the same block hash and state root at the settlement-tag height. Any disagreement is a denial.
  4. State proof. The account proof (registry address), plus the storage proofs for the Issuer word (slot keccak(issuerId ‖ 2): authority and active flag) and the status (slot keccak(credentialIdHash ‖ keccak(issuerId ‖ 6))). Absent slots are proven absent.
  5. Issuer. The issuer must be active on the source chain.
  6. Freshness. Source state must be at most maxAgeSeconds old. An attestation must be current, issued at most maxAgeSeconds ago, and valid for no longer than that.
  7. Attestation (attestation kind only).
    • Its source chain, target chain, registry and credential must equal the request's.
    • Its signature must recover, low-S, to the proven issuer authority.
  8. Status. It must equal the required status (default active). A revoked or suspended credential is reported as such.

Any RPC failure is a denial (SOURCE_UNAVAILABLE), never an assumption.

Domain separation

  • Attestations use the domain { name: "QuantLayer Credential Status Attestation", version: "1", chainId: sourceChainId, verifyingContract: sourceRegistry }, and the message repeats sourceChainId and adds targetChainId. A statement for Robinhood Chain can't be replayed to Arbitrum, and a statement about one registry can't be presented as another's.
  • Every other QuantLayer signature (EIP-712 authorization, identity statements, PQC attestations, ZK proof contexts) already binds the chain id and verifying contract (FEAT-08 and FEAT-09). eip712Domain() and domainTag() make this the only way to build a domain in this package.

Verified cross-chain messages

Native Arbitrum messaging is the trust-minimized path between Arbitrum One and Robinhood Chain. It runs L2 → Ethereum through the Outbox, after a 7-day challenge period, then Ethereum → L2 as a retryable ticket, with sender aliasing.

A status delivered that way would land in the target's registry. Once there, it is verified with target-registry evidence on the target chain, as a native fact.

QuantLayer does not ship messenger contracts yet. The registry accepts status updates only from the issuer's authority, so a relay would need the aliased messenger registered as that authority. Until then, the honest options for different chains are state proofs and issuer attestations.

Limits and upgrade path

  • The header quorum is RPC trust, spread across independent providers. It is not light- client verification. The upgrade path is to verify the source header against the parent chain: the Arbitrum rollup's confirmed assertions on Ethereum, checked by an Ethereum light client or a ZK proof of consensus. That would make source-state-proof trustless.
  • Attestations depend on issuer key security. Rotating the issuer authority on the source registry invalidates attestations signed by the old key.
  • Staleness. Settlement-tag reads lag the head by the finality time (roughly 15–20 minutes on Arbitrum chains). Choose maxAgeSeconds with that in mind, and use attestations when fresher status is required.