Quorum & Anti-Eclipse

The validator checks the report, and the receiver checks what the report claims

Three checks run inside validate_federation_quorum_report. Two more, the policy floor and listing agreement, belong to the operator that receives the report.

The validator establishes that a report is consistent under the policy it declares. The receiver establishes that the policy is strict enough and that the publishers saw the same listing. A report that passes both establishes who has seen the listing.

The anti-eclipse policy requires an origin, an indexer, and two distinct operators

The default FederationAntiEclipsePolicy needs at least two distinct operator ids, an observation from the named origin, an indexer observation, and no observation more than one upstream hop away. A hop-count violation rejects the whole report.

The origin test has two halves: the observation's role is origin, and its operator id equals the report's originOperatorId. The indexer test checks the role alone. Distinct ids are distinct strings, so independent ownership is a judgment the receiver makes about the operators it sees.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FederationAntiEclipsePolicy {
    pub minimum_distinct_operators: u32,
    pub require_origin_publisher: bool,
    pub require_indexer_observation: bool,
    pub max_upstream_hops: u32,
}

impl Default for FederationAntiEclipsePolicy {
    fn default() -> Self {
        Self {
            minimum_distinct_operators: 2,
            require_origin_publisher: true,
            require_indexer_observation: true,
            max_upstream_hops: 1,
        }
    }
}

Read more in the policy fields.

Only fresh observations count, and the declared state must agree with the count

An observation is stale when its ageSecs exceeds the report's maxReplicaAgeSecs, or when its state is stale. Every other observation adds one to the fresh count.

if publisher.freshness.age_secs > report.max_replica_age_secs
    || publisher.freshness.state == GenericListingFreshnessState::Stale
{
    stale_count += 1;
} else {
    fresh_count += 1;
}

The producer declares finalState, and after the coverage checks pass the validator tests that label against the counts and the supplied conflicts:

1. converged. No conflicts, and the fresh count meets quorumThreshold.
2. conflicting. At least one conflict entry.
3. insufficient_quorum. The fresh count is below the threshold once every preceding gate has passed.
4. stale. Every observation is stale.

With a 300-second ceiling and threshold 2, three observations at age 400 leave a fresh count of 0, so a converged declaration is refused. A divergent observation inside the ceiling counts as fresh here; the trust-activation evaluator refuses divergent listings separately.

Read more in the final-state rules.

The receiver checks what the validator reads as supplied

The receiving operator runs four checks of its own around the validator:

1. Signature. SignedFederationQuorumReport wraps the body in a SignedExportEnvelope. The receiver verifies the envelope and its trusted signer, then validates the body.
2. Age. The receiver derives each observation's age from its own trusted clock before building the input.
3. Agreement. The receiver compares observedListingSha256 across publishers. See listing agreement.
4. Floor. The policy travels inside the report, so the receiver compares antiEclipsePolicy, the threshold, and the ceiling with its own requirements.

The quorum program applies the floor and agreement checks to the reference report and three altered copies.

Validate a report under the receiver’s policy

Load the complete report, validate its declared state, then apply a local policy floor and listing-agreement check.

Complete the project setup, then run the program from federation-guide/. The download includes every constructor and input.

cargo run --locked --bin quorum

reference report: accepted under receiver policy
weaker declared policy: refused
different listing digest: refused
stale observations with converged declaration: refused

The supplied report is a reference artifact with declared ages. Authenticate observations and derive their age from a trusted receiver clock before constructing this input. Different operator IDs do not prove independent ownership.

use chio_federation::quorum::{validate_federation_quorum_report, FederationQuorumReport};
use serde_json::Value;

// These checks belong to the receiving application. They supplement the report
// validator; they cannot authenticate publishers or prove independent ownership.
fn receive(value: Value) -> Result<(), String> {
    let report: FederationQuorumReport =
        serde_json::from_value(value).map_err(|e| e.to_string())?;
    validate_federation_quorum_report(&report).map_err(|e| e.to_string())?;
    let policy = &report.anti_eclipse_policy;
    if policy.minimum_distinct_operators < 2
        || !policy.require_origin_publisher
        || !policy.require_indexer_observation
        || policy.max_upstream_hops > 1
    {
        return Err("report weakens receiver policy".into());
    }
    if report.quorum_threshold < 2 || report.max_replica_age_secs > 300 {
        return Err("report weakens receiver freshness or threshold".into());
    }
    if report
        .publishers
        .iter()
        .any(|p| format!("{:?}", p.freshness.state) != "Fresh")
    {
        return Err("receiver requires fresh agreeing observations".into());
    }
    let first = &report.publishers[0].observed_listing_sha256;
    if report
        .publishers
        .iter()
        .any(|p| &p.observed_listing_sha256 != first)
    {
        return Err("publisher listing digests disagree".into());
    }
    if report.final_state != chio_federation::quorum::FederationQuorumState::Converged {
        return Err("receiver requires a converged report".into());
    }
    Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "quorum-report.json".into());
    let report: Value = serde_json::from_slice(&std::fs::read(path)?)?;
    receive(report.clone())?;
    println!("reference report: accepted under receiver policy");
    let mut weak = report.clone();
    weak["antiEclipsePolicy"]["minimumDistinctOperators"] = 1.into();
    assert!(receive(weak).unwrap_err().contains("weakens"));
    println!("weaker declared policy: refused");
    let mut divergent = report.clone();
    divergent["publishers"][1]["observedListingSha256"] = "f".repeat(64).into();
    assert!(receive(divergent).unwrap_err().contains("disagree"));
    println!("different listing digest: refused");
    let mut stale = report;
    for p in stale["publishers"].as_array_mut().unwrap() {
        p["freshness"]["ageSecs"] = 400.into();
    }
    assert!(receive(stale).is_err());
    println!("stale observations with converged declaration: refused");
    Ok(())
}

Open the source file. Each program asserts its expected refusals; keys, timestamps, and digests change between runs.

You should see the reference report accepted, then a copy declaring minimumDistinctOperators 1, a copy whose mirror reports a different listing digest, and a copy with every observation at age 400, each refused. The complete reference report is the input. To write your own, collect the observations first and record conflicts from a comparison of their digests.

chio federation quorum verify runs the signature check, the validator, and the floor and agreement checks on a received report, against a floor file you keep. The report that declares one distinct operator is refused at your floor:

chio federation quorum verify fqr-1.json fqr-1-one-operator.json \
  --trusted-signer ./quorum-signer.pub --floor ./quorum-floor.json

ACCEPTED  fqr-1  converged, 3 of 3 fresh, 3 distinct operators, listing digests agree
REFUSED   fqr-1-one-operator  minimumDistinctOperators 1 is below your floor of 2

A valid report organizes evidence and authorizes nothing

Quorum reports answer who has seen a listing. Bilateral Co-Sign and FROST Quorum authorize actions, and accepting a report invokes neither. The federation import contract requires explicit local activation, and a qualification matrix that names a quorum report holds the reference as a string.

Read more in the federation admission path.

Next: agree on the actions a listing can lead to