Clearing Rounds

Netting turns a chain of debts into one transfer

In the crate’s own test vector, A owes B 100 and B owes C 100. Netting keeps each participant’s net position: A pays 100, B nets to zero, and C receives 100, so two gross transfers become one intent.

Nothing cancels bilaterally, because no pair has a reverse flow. The debtor list holds A, the creditor list holds C, and one pass of the match loop emits the intent: A pays C 100. B still receives a signed statement and appears in no intent. The test then re-derives the output and compares, rejects a tampered amount of 101 and refuses to sign it, validates every signed body against its published JSON schema, rejects an added field, fails when one snapshot acknowledgement is dropped, and asserts the output is unchanged when the input order is reversed.

fn acyclic_chain_reduces_to_one_direct_intent() -> TestResult {
    let participant_authority = Keypair::from_seed(&[1; 32]);
    let obligation_authority = Keypair::from_seed(&[2; 32]);
    let obligations = vec![
        reserved_obligation(1, "A", "B", "USD", 100)?,
        reserved_obligation(2, "B", "C", "USD", 100)?,
    ];
    let request = signed_request(
        obligations.clone(),
        &participant_authority,
        &obligation_authority,
    )?;
    let output = compute_netting_round(
        &request,
        &trust(&participant_authority, &obligation_authority),
    )?;

    assert_eq!(output.intents.len(), 1);
    assert_eq!(output.intents[0].debtor_participant_id, "A");
    assert_eq!(output.intents[0].creditor_participant_id, "C");
    assert_eq!(output.intents[0].amount.units, 100);
    verify_netting_round(
        &request,
        &trust(&participant_authority, &obligation_authority),
        &output,
    )?;
    let mut tampered = output.clone();
    tampered.intents[0].amount.units = 101;
    assert!(verify_netting_round(
        &request,
        &trust(&participant_authority, &obligation_authority),
        &tampered,
    )
    .is_err());
    let authority_trust = trust(&participant_authority, &obligation_authority);
    assert!(sign_netting_round(
        &request,
        &tampered,
        &authority_trust,
        &participant_authority,
    )
    .is_err());
    let signed = sign_netting_round(&request, &output, &authority_trust, &participant_authority)?;
    validate_schema(
        "clearing-participant-snapshot.v1.json",
        &request.participant_snapshot,
    )?;
    for acknowledgement in &request.participant_acknowledgements {
        validate_schema(
            "clearing-participant-snapshot-acknowledgement.v1.json",
            acknowledgement,
        )?;
    }
    validate_schema("clearing-input-manifest.v1.json", &request.input_manifest)?;
    validate_schema("clearing-netting-round-core.v1.json", &signed.core)?;
    for statement in &signed.participant_statements {
        validate_schema("clearing-participant-statement.v1.json", statement)?;
    }
    for intent in &signed.intents {
        validate_schema("clearing-settlement-intent.v1.json", intent)?;
    }
    for transformation in &signed.transformations {
        validate_schema("clearing-atom-transformation.v1.json", transformation)?;
    }
    validate_schema("clearing-output-manifest.v1.json", &signed.output_manifest)?;
    assert_eq!(
        verify_signed_netting_round(&request, &authority_trust, &signed)?,
        output
    );
    let mut tampered_signed = signed;
    tampered_signed.intents[0].body.amount.units = 101;
    assert!(verify_signed_netting_round(&request, &authority_trust, &tampered_signed).is_err());
    let mut unknown_field = serde_json::to_value(&tampered_signed.core)?;
    unknown_field["unexpected"] = serde_json::Value::Bool(true);
    assert!(serde_json::from_value::<SignedNettingRoundCoreV1>(unknown_field).is_err());

    let mut missing_acknowledgement = request.clone();
    missing_acknowledgement.participant_acknowledgements.pop();
    assert!(compute_netting_round(&missing_acknowledgement, &authority_trust).is_err());

    let mut shuffled = request;
    shuffled.obligations.reverse();
    let shuffled_output = compute_netting_round(
        &shuffled,
        &trust(&participant_authority, &obligation_authority),
    )?;
    assert_eq!(output, shuffled_output);
    Ok(())
}

A debt enters one round, and only with proof the set is complete

The round’s only input is the canonical ObligationAtomV1: one immutable atom per receipt-backed debt, binding the debtor, the payee-bound original creditor, the amount, and the currency. Exposure-ledger rows and IOU envelopes can describe the same receipt, so the clearinghouse reads atoms alone and counts each debt once.

Each atom arrives as a ClearingObligationInputV1 carrying a source sequence and the atom’s own disposition record, and enters only when that disposition is ClearingReserved { round_id }. An atom that is per_call, assigned, or channelized stays out, so one debt never settles through two paths at once. A repeated obligation_id or atom digest raises duplicate clearing obligation and rejects the whole request.

• One currency. A round runs in one currency, three uppercase ASCII letters; a mismatched atom raises clearing input currency does not match the round.
• One signed participant snapshot. chio.clearing.participant-snapshot.v1 maps each identity to one participant id and one settlement destination, and every participant acknowledges it. The round pays only destinations the snapshot names.
• A complete manifest. chio.clearing.input-manifest.v1 carries a closed sequence range, start and end checkpoint digests, and the sorted entries; a bounded report that stopped at its item limit fails as clearing input manifest is incomplete.

The signed round core binds the manifest digest, the input count, and a reservation root, so no atom can join or leave after signing.

Read more in Obligations, which produces the reserved atoms a round reads, and in the snapshot and completeness rules.

Netting is deterministic and conserves every balance

compute_netting_round accepts one algorithm version, the literal balance_match.v1. Inputs sort by source sequence, every per-participant map is a BTreeMap keyed on the participant id, and a reversed input yields byte-identical output. Addition is checked u128, every emitted amount converts back to a u64 at or below 2^53 - 1, and an overflow rejects the round.

1. Verify. The trust configuration, the participant snapshot and its acknowledgements, the input manifest, the reserved disposition on every atom, the exact currency, and the manifest binding.
2. Aggregate. Each atom adds its units to the debtor’s gross debit, the creditor’s gross credit, and a directed (debtor, creditor) total, records its digest against both, and emits one chio.clearing.atom-transformation.v1 naming the raw identity and the resolved participant id on each side.
3. Measure bilateral cancellation. For each unordered pair, the smaller direction is added to both participants’ canceled-debit and canceled-credit totals, self-flow included. The figure is reported; the directed totals stay as recorded.
4. Balance. Each net balance is gross debit minus gross credit, tagged debit, credit, or zero. A zero balance gets a statement and enters neither matching list.
5. Conserve. Summed debit balances equal summed credit balances, or the round stops with clearing arithmetic overflow.
6. Match. Walk the debtor and creditor lists in participant-id order, match the two heads for the smaller remaining amount, and advance whichever side reaches zero. A leftover after the walk is the same error as a conservation failure.
7. Emit. One statement per participant, one settlement intent per match, one transformation per input atom, and one chio.clearing.output-manifest.v1 carrying a root and a count for all three lists.

Each pass of the match loop advances at least one cursor, so a round with d debtors and c creditors emits at most d + c - 1 intents; the crate caps stored progress rows at MAX_CLEARING_INPUTS * 2 - 1. The guarantee is determinism and balance conservation; minimizing rail fees under a fee model is outside it.

A round moves through ten fenced states

Every transition is an authority-authenticated local stage followed by an EconomicStateAnchor compare-and-swap over the round and its obligations. Any pair of state and transition outside the closed match returns illegal clearing lifecycle transition.

Abort is reachable from Reserved, Proposed, and Finalizing, and leaving Finalizing needs the burn checkpoint for its quorum session, so a round never abandons a finalization it might still consume. BeginReconciliation refuses an observed status of unknown, which sends an effect-possible outcome to Incident; that state keeps accepting dispatches and reconciliations and can reach Satisfied. Through all of it the reservations hold.

• An input is missing from a claimed complete set. Refuse the round and rebuild from authenticated reserved inputs, with completeness evidence that covers the intended set.
• A required acceptance is missing. Keep the round unfinalized; obtain a valid acceptance bound to this round and manifest, or take the admitted abort path.
• The finalization response is lost. Read the durable lifecycle head and recover the original operation before proposing another transition; a lost response leaves the round’s state to the recorded head.
• Abort is requested after a possible dispatch. Establish the zero-dispatch proof with verified abort authority, or resolve the execution outcome. A transport error is no proof of zero dispatch.
• An intent’s payment is still pending. Retain the intent and its operation identity and keep reconciling until a verified settlement outcome arrives.

Read more in the abort verifier, which checks the zero-dispatch proof.

A two-of-three quorum seals each round once

Finalization starts only once the trusted clock is at or past the round’s dispute-window end and a ClearingDisputeWindowResolver reports unresolvedDisputeCount of zero over a window that covers the closing time. One acceptance is then required per statement, in participant-id order, under the acknowledgement key the snapshot bound to that participant, so a zero-balance participant signs too.

The seal is a FROST threshold signature: a detached chio.frost.authorization.v1 in the chio.frost.clearing-round-finalize.v1 domain, registered with ladder action class clearing.round_finalize at a two-of-three treaty-scoped quorum. It binds the action digest, the roster digest, the key epoch, the resource version and fence, a scopeId equal to the round’s governance scope, and a resourceId that resolves to the round id. The action preimage binds the finalization body digest, the output manifest digest, the acceptance root, and the round id.

The finalization body carries no FROST field, so the proof binds to a proof-free body digest. The move from Finalizing to Finalized consumes the authorization against a permanent completed slot, so one proof finalizes one round once. Replaying that move needs a FROST artifact trust store; without one it returns clearing authority verification failed and the round stays in Finalizing. The group signature proves threshold authorization by the group without naming the signer subset; the individual acceptances are the attributable evidence of who signed.

Next: close the round against observed payments