Payment Channels

Transitions and validators

The release a close produces executes and reconciles separately. The host connects admission, durable state transitions, external dispatch, and reconciliation before it carries channel traffic.

Channel records

Every channel body is RFC 8785 canonical JSON with deny_unknown_fields, camelCase keys, and a versioned schema id, signed as a separate wrapper around the body. The files live under spec/schemas/chio-economy/; each registered kind in spec/schemas/registry.json uses the channel_ prefix and is introduced by micro-escrow-channels-v1.

• chio.channel.funding-evidence.v1 One block-pinned read of the escrow: the immutable terms, the deposited, released, and refunded state, the creation event, an identity-registry observation, a token observation, the asset binding, and the finality pin. Every observation repeats the pin’s own block number and block hash.
• chio.channel.open-intent.v1 The proposal both parties sign: identities and keys, refund and beneficiary addresses, currency, the immutable bound, the dispute tier copied from policy, the close-submission cutoff, the escrow reference, and the funding-evidence digest.
• chio.channel.funding-acknowledgement.v1 The funding authority moves the escrow reference from unreserved to opening against the open-intent digest, incrementing the reservation version by exactly one.
• chio.channel.open.v1 Binds the open-intent and acknowledgement digests, carries the derived channel id, and commits the sequence-zero state digest.
• chio.channel.reservation.v1 The payer’s one-shot authorization for the exact next state, carrying the request, the service binding, a maximum charge, an expiry, and the channel-state version and lifecycle fence it expects.
• chio.channel.state.v1 One cumulative state per admitted call: the running total, the appended receipt-id root, and every digest the transition proved.
• chio.channel.terminal-outcome-commitment.v1 The signed outcome of one dispatched reservation: the operation, the reservation and its digest, the receipt and its digest, and the terminal result.
• chio.channel.close.v1 The final allocation: close kind, final state digest and sequence, the expected release and post-release refund in token base units, the dispute deadline, and the versions and fence it was computed against.
• chio.channel.dispute.v1 A contested-close challenge: the close it answers, the competing state and its sequence, the state-chain proof digest, and a reason.
• chio.channel.release-authorization.v1 The publisher’s record of the broadcast: the FROST-bound authority, the publication root, and two distinct mutation bindings for the root publication and the release call.
• chio.channel.transition-replay.v1 A replay descriptor pinning the authorities an offline verifier needs: open trust, funding authority, reservation authority, trusted kernel key, and the anchor.

Three schema constants govern records the registry leaves out, because they describe anchored state or a binding: chio.channel.lifecycle.v1 for the channel head, chio.channel.escrow-reservation.v1 for the escrow head, and chio.channel.asset-binding.v1, the currency-to-token binding every money field round-trips through.

Funding evidence and open

A channel opens on a rail that has already locked the full bound: a fully funded ChioEscrow deposit. A budget reservation alone opens nothing. Before either party signs the open intent, both verify the chio.channel.funding-evidence.v1 from a single block-pinned escrow read. It binds the complete immutable ChannelEscrowTermsV1, the deposited, released, and refunded state, the decoded EscrowCreated event, an identity-registry observation that the named operator is active with that exact key hash, a token observation that the token is allowed, and a trusted ChannelAssetBindingV1 carrying currency, both decimal scales, chain id, token address, token symbol, and the settlement-policy digest.

Every observation repeats the pin’s block number and block hash. The pin reports L1Finalized finality with observed confirmations equal to finalized_head_number - block_number and at least the configured minimum. An inactive operator, a disallowed token, an operator-key-hash mismatch, or a block timestamp later than the observation time rejects the evidence before any signature is checked.

The bound converts through the asset binding’s verify_round_trip, which recomputes token base units from the MonetaryAmount and back, and rejects with InexactAmount unless both directions agree, so terms.maxAmount == deposited == bound_token_base_units. Nothing may already be released or refunded; the escrow beneficiary equals the channel payee and the depositor equals the payer’s refund address; token, currency, both decimal scales, policy digest, chain id, and contract address match the configured funding authority. The dispute tier is selected once from the immutable bound and copied into the intent, and the close-submission cutoff equals the escrow deadline minus the policy’s fixed finality and broadcast margin. Closes and disputes reuse that tier, so a close submitter cannot shorten the dispute window by choosing a smaller amount.

Escrow reservation registry

The funding authority owns one durable escrow-reservation registry that serializes each escrow reference through its off-chain lifecycle. Two enums span it:

• ChannelEscrowReservationStateV1 (unreserved, opening) is the prior and new state inside a signed funding acknowledgement. The body is valid only for the pair unreserved to opening with the version incremented by one, so one deposit funds one channel.
• ChannelEscrowReservationStatusV1 (open, closing, released, refunded, incident) is the escrow head once the channel exists. Its status matches the channel head’s status under a fixed pairing, and both heads carry the same lifecycle fence and pending-close digest.

Channel id and initial state

The open record binds both prior digests and derives a non-cyclic channel id, so an offline verifier proves terms, a unique reservation acknowledgement, the initial state, and final consent in one direction. The derivation hashes a canonical three-tuple under an empty domain prefix, with the domain-separating literal inside the preimage:

pub fn derive_channel_id(
    open_intent_digest: &str,
    funding_acknowledgement_digest: &str,
) -> Result<String, ChannelError> {
    validate_digest("open_intent_digest", open_intent_digest)?;
    validate_digest(
        "funding_acknowledgement_digest",
        funding_acknowledgement_digest,
    )?;
    digest(
        b"",
        &(
            "chio.channel.id.v1",
            open_intent_digest,
            funding_acknowledgement_digest,
        ),
    )
}

The open record commits a sequence-zero state digest with zero cumulative amount and an empty receipt-id root. The consent check rebuilds that initial state from the channel id, currency, and asset-binding digest, and rejects unless the record’s initialStateDigest equals the digest of what it rebuilt.

Reservation wrapper and signatures

SignedChannelReservationV1 carries the reservation body and two ChannelSignatureV1 values, one from the payer and one from the channel authority. The body also binds the channel and open digests, the trusted receipt-authority digest, and the exact maximum in token base units. Every signature in the family has one shape: a signer id, a key epoch, a canonical public key, and a signature over a payload that prefixes the body with the domain chio.channel.signature.v1, the signer id, the epoch, and the key.

State body

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ChannelStateBodyV1 {
    pub schema: String,
    pub channel_id: String,
    pub seq: u64,
    pub prev_state_digest: Option<String>,
    pub cumulative_owed: MonetaryAmount,
    pub receipt_id_root: String,
    pub receipt_count: u64,
    pub receipt_id: Option<String>,
    pub receipt_digest: Option<String>,
    pub receipt_authority_digest: Option<String>,
    pub obligation_atom_digest: Option<String>,
    pub reservation_digest: Option<String>,
    pub actual_charge: Option<MonetaryAmount>,
    pub cumulative_token_base_units: String,
    pub asset_binding_digest: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SignedChannelStateV1 {
    pub body: ChannelStateBodyV1,
    pub payee_signature: ChannelSignatureV1,
}

Each Option field carries skip_serializing_if = "Option::is_none", elided above, so an absent binding is an absent key. The fields separate the two shapes a state takes. At sequence zero every one is absent, the receipt count and cumulative amount are zero, the token total is the string "0", and the receipt-id root equals the empty root. At every later sequence all of them except obligationAtomDigest are present, the receipt count equals the sequence, and the obligation digest is present exactly when the actual charge is non-zero.

Lifecycle head

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ChannelLifecycleStatusV1 {
    Open,
    ClosePending,
    Closing,
    Released,
    Refunded,
    Incident,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ChannelLifecycleViewV1 {
    pub schema: String,
    pub channel_id: String,
    pub status: ChannelLifecycleStatusV1,
    pub latest_state_digest: String,
    pub latest_sequence: u64,
    pub state_version: u64,
    pub lifecycle_fence: u64,
    pub pending_close_body_digest: Option<String>,
    pub admitted_dispute_digest: Option<String>,
    pub live_reservation_id: Option<String>,
    pub operation_id: Option<String>,
}

The four Option fields carry the same elided skip_serializing_if attribute, and the head validates its own combinations. A live reservation id and an operation id are both present or both absent, and present only while the status is open. A pending close digest is required under close_pending and closing and forbidden elsewhere. An admitted dispute digest is allowed only under close_pending. A new reservation requires open with no live reservation, so moving the head to close_pending blocks every later reservation.

Close authorization

The registered ladder action class is channel.close: quorum 2 of 3 in scope treaty, co-sign mode n_of_m, and consistency model quorum-required anchored at frost-quorum. The signing domain is chio.frost.channel-close.v1 and the typed action preimage is chio.frost.action.channel-close.v1. channel_close_frost_action reads every preimage field from a verified effective close, takes only the publisher fence as an argument, and validates the preimage before returning it. Party signatures and independent endorsements cannot substitute for the group authorization.

Building a close requires the head to be open with no live reservation. Verification recomputes the release and refund, rejects a mismatch, and pins the channel-state version, the escrow-reservation version, and the lifecycle fence at exactly one past the values the head carried, so a close computed against a stale head is refused. A contested close’s dispute advance requires the head to carry the dispute digest and to be a validated successor of the head the close was taken against. Verification of a signed release authorization rejects a trusted time at or past the close-submission cutoff, and at or past the escrow deadline, so the runtime never attempts a release after expiry.

Escrow release and refund

Release reuses the escrow runtime. prepare_authorized_channel_merkle_release takes the verified release authorization, rebuilds the preparation facts from it, and refuses with channel release authority mismatch if they disagree. A zero release amount prepares no transaction and returns Ok(None). Otherwise the amount is EscrowExecutionAmount::Full when it equals the dispatch settlement amount and EscrowExecutionAmount::Partial below it, and prepare_merkle_release prepares partialReleaseWithProofDetailed for the escrow beneficiary. A prepared release whose scaled minor units differ from the authorization’s expectedReleaseTokenBaseUnits is refused.

The close body’s finalCumulativeOwed and expectedRefundAfterReleaseTokenBaseUnits are the intended split. ChioEscrow.refund can be called by anyone once block.timestamp passes the deadline, reverts with EscrowNotExpired before it and EscrowAlreadyRefunded after a first refund, and transfers deposited - released to the depositor before emitting EscrowRefunded. The observable events are EscrowReleased, EscrowPartialRelease, and EscrowRefunded.

The release and the post-deadline refund are two separate contract calls. Inside the release authorization, the two mutations it owns, the root publication and the release broadcast, must differ in operation id, effect slot id, idempotency key, and call digest, and both must name the FROST scope the authority binds. ChioEscrow understands deposits, releases, proofs, and the refund; the reservation-aware gate that guards release is the channel runtime’s off-chain control. A beneficiary, the named operator, or a settlement-key holder can move value through the signature and admin paths, so the pause, allowlist, and transferable-admin model is an explicit trust assumption.

Source

A channel is a bilateral overlay on one ChioEscrow deposit and adds no contract code. The records, validators, and close protocol are code in chio-settle under crates/economy/chio-settle/src/channel/, and release reuses the escrow runtime chio-settle owns. The close preconditions and allocation checks are in close.rs.