Overview
Consensus Verifiability
The primary purpose of cryptographic consensus protocols is to enable people to interact with strangers all over the world where a person's locally controlled software can provide safe, timely guarantees that some globally available state was updated through an interaction.
To do this, a person's software needs to be able to verify that a particular interaction resulted in a change to some globally available state and the resuling state is valid according to a set of pre-defined rules.
Unfortunately, "global state" is a useful fiction:
Objectivity and Subjectivity in Consensus
Objective Verifiability
Verifying nodes run software which verifies whether a particular ledge history is valid according to consensus rules, which all nodes must agree on to arrive at the same view of the network's ledger. In order to ensure any two nodes would arrive at the same decision as to whether a given history is valid or not, their decision must be objectively verifiable. Precisely:
An objectively verifiable property of a ledger history can be computed using only that ledger history as input.
Objectively verifiable properties include all of the ledger state that users care about: balances, when transfers occurred, what authorization criteria were fulfilled to enable a transfer, the current total supply, the supply totals for different shielded pools, how changes to balances and ownership were bundled into (objectively verifiable) transactions, and so forth.
By relying only on the ledger history, and not any other auxillary, node-specific information, a node ensures that a property it verifies is the same value any other node would verify from that same history. If nodes relied on non-objective input to their verification process, they would lose the guarantee that other nodes would arrive at the same conclusion for a given history.
The top-line objectively verifiable property of a ledger history is a boolean value: consensus-valid. By accurately excluding any ledger history which is not objectively verifiable as consensus-valid, nodes protect their users from large categories of malice and accident with respect to the ledger state.
Intersubjectivity
Nodes, like people, are immersed in subjectivity. Local data and code can compute values locally, which nodes can then rely on innately through the magic of computation, but there's no a priori guarantee any other entity has access to the the same input or calculated data. Furthermore, if presented with arbitrary data along with a claim that it is a conclusion or result of some kind of verification, a node can only rely on this claim by either performing their own verification locally, or relying on the third party as an authority (or anyone who can foil authentication attempts of that authority).
When performing local verification, a wonderful advancement Zcash in particular has leveraged are proofs-of-integrity which allow verifying a claim objectively without needing to reproduce all of the original input data and direct calculation steps.
However, none of this can
Finality & Incentives
The incentivization design of Crosslink follows this general principle:
Anything involving Proof-of-Stake, such as calculating amount of rewards, changing the roster used in BFT, or withdrawing funds requires a finality update to take effect.
PoS Action Validity Restricitons
The Bond Actions and States chapter includes transaction validity restrictions aimed at supporting this general principle.
Future Work
We need a way to compare trade-offs around incentive design, because it seems like there are always many possible hard-to-predict scenarios and impacts.
Address this concern:
-
if rewards are only based on finalized roster state, then finalizers who can halt finality can use that to prevent others' pending deposits from taking effect which would dillute the rewards of those halting finalizers.
-
if deposits can occur at any time regardless of finality, but withdrawals require finality updates, what concerns or drawbacks should we analyze about this?
Rewards Distribution
Here we give an overview of how the Zcash protocol with Crosslink enabled distributes protocol rewards.
XXX: TODO: get more precise about how finality interacts with rewards, specifically if rewards are proportional to "latest final state" or "most recent PoW state".
The ZEC Supply Policy
We conceptualize all abstract rules about the ZEC asset's ownership and accounting as the ZEC Supply Policy. This policy is not an emergent property of (any version of) the Zcash consensus protocol, and is instead an explicit part of the conceptual design which protocol implementations and changes are evaluated against.
We propose the following hold for existing Zcash mainnet (NU 6.3) as well as in this Crosslink design:
-
ZECmust be scarce, with every unit accounted for by the consensus protocol, all adding up to the Max Supply Cap of 21,000,000. -
The consensus protocol constrains
ZECtransfers, either between users, or between the protocol and users. All such transfers maintain Supply Integrity by ensuring the same number of units transferred away from a set of sources are distributed to a set of recipients. -
ZECis divided between Unissued Supply versus Active Supply, with the total of these two categories being the Max Supply Cap. -
The Active Supply is all
ZECthat is under a user's discretionary control, given any protocol constraints on those funds. For example, much of the active supply isZECwhich cannot be transferred without possession of a spending authority, but another example relevant to Crosslink is that staking bonds have restrictions on transfers, yet end users still have discretion within those constraints, and so both examples are considered part of the Active Supply. -
The consensus protocol may issue or unissue
ZECby accounting for those units being removed from the Unissues Supply in a transfer to the Active Supply (or vice versa for unissuance), with the following further constraints on issuance:The consensus protocol regularly issues
ZECas part of the network operation in order to incentivize successful operation of the network and establish a valuable network effect ofZECscarcity among users.This new
ZECis issued by the protocol at a predictable constrained rate, the Issuance Schedule, which asymptotically approaches 0 over time with an approximate 4 year half-life.Issuance Rate Detail
- Details:
- The rate is time-approximate by relying on per-block accounting on the assumption that the block production rate is approximately constant.
- The rate currently follows the Bitcoin-like "four year halving" schedule, although it may be adjusted by the Network Sustainability Mechanism or other changes which alter this "fine-grained" detail of the issuance rate.
- Details:
Consensus Rewards Distribution
Given the concept of the ZEC Supply Policy, we can envision any version of a given consensus protocol as a component which can take newly issued ZEC and distribute it such that all of the consensus guarantees hold, including all of the ZEC Supply Policy.
In other words, one way to conceptualize the consensus protocol designers job is in terms of an operational budget:
Given that the ZEC Supply Policy provides you with new
ZECto distribute in each time period to protocol participants, design and deploy a self-funding protocol that supports all of the ZEC Supply Policy goals.
FIXME: What about transaction fees?
FIXME: What about "dev fund" / "human-governed funding" that is not direct "consensus operation funding"?
Crosslink Rewards Distribution Rules
With that framework in mind, here are the concrete rewards distribution rules Crosslink follows:
-
The consensus protocol distributes block rewards (= new issuance + transaction fees) in each block. Crosslink does not alter the distribution of transaction fees in any way, and their distribution is orthogonal to Crosslink.
-
A chunk may come out for dev fund or other discretionary governed funding (FIXME: this is part of the policy that's out-of-scope for the consensus protocol; move this section).
-
The remainder is called the Operational Consensus Rewards (aka OCR).
-
50% (rounding up) of the OCR is distributed as Mining Rewards to the current block miner in the same manner/mechanism as in Zcash NU 6.3. (Note: transaction fees are not altered by Crosslink, and thus accrue to the miner and/or NSM or any other current txn fee design when Crosslink activates.)
-
50% (rounding down) of the OCR is distributed as PoS Rewards as follows:
a. 90% (rounding down) of PoS Rewards are distributed as Staking Returns. Staking returns are divided proportionally among all Bonds present in a block. b. 10% (rounding up) are distributed as Finalizer Comission Fees which are divided propotionally to the total stake weight of each active finalizer.
FIXME: Should it be $F^{active}_i / \Sum F^{active}$ or $F^{active}_i / \Sum F^{total}$ ?
Staking Mechanics
The rewards distribution rules above depend on these staking mechanics:
-
Users can modify their bonds with Crosslink-specific transaction fields. All interactions with bonds require that there are no txn inputs or outputs aside from: the bond actions, latest/greatest shielded pool actions, and transaction fee payments.
-
Txns with bond actions may only be included in blocks at Staking Day height ranges (FIXME: define these heights).
-
Bonds have a stateful lifecycle:
-
From any Shielded Pool
ZEC:createaction -
From
activestate:redelegateorwithdrawactions -
From
withdrawing w/ sufficient delay state:transferaction- FIXME: define "Sufficient delay", but it should be relatively simple and based on the height of the withdraw action (or maaaaybe an associated staking day on/off height?)
Actions:
- The
createandwithdrawactions may only occur during Staking Day heights. - The
redelegateandtransferactions are not constrained by Staking Day height ranges. - The
transferaction is akin to any other transfer transaction with the additional restriction that ther are no inputs/outputs/actions except for the transfer and the latest/greatest shielded pool actions, plus a transaction fee.
-
FIXME: consistent rigorous rounding for every apportioning of ZEC of entire accounting design.
Bond Actions and States
FIXMEs:
- Does finality need to appear on this state diagram?
- xxx
graph TD Liquid_ZEC -->|"Create Bond"| Staked_Bond Staked_Bond -->|"Unstake Bond"| Unstaked_Bond Staked_Bond -->|"Redelegate Bond"| Staked_Bond Unstaked_Bond -->|"Withdraw Bond"| Liquid_ZEC Finalizer_Commissions_Bucket -->|"Convert Rewards"| Staked_Bond %% Define PoW block style with dark blue border and oval shape classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000 %% Define alternative PoW block style with orange fill for caution classDef powAlt fill:#ffcc80,stroke:#01579b,stroke-width:3px,color:#000
Consensus Rule Restrictions
Here we list consensus rule restrictions for transactions containing the following actions in addition to rules which apply to all transactions.
Here we assume a set of "cryptography widget guarantees" are already verified and don't specify them. (XXX: Specify these somewhere!)
Assumption: "contextual" txn verification has access to a subset of "most recently finalized state" (at least it's PoW height), as well as a subset of "most recent unfinalized state".
Create Bond action
- No txn inputs can be present except those from a "set of acceptable shielded pools" (XXX: Define "acceptable shielded pools" as a protocol constant)
- The block height must be a
staking dayblock height - The bond amount must be a power of 10 of ZATOSHI
Redelegate Bond action
- Must refer to an existing
Staked_Bond
Nuance / Subtle: This does not have a staking day blockheight restriction.
Unstake Bond action
- Must refer to an existing
Staked_Bondwhich is at least one staking cycle old - The block height must be a
staking dayblock height
Withdraw Bond action
- Must refer to an existing
Unstaked_Bondwhich is at least one staking cycle old - The block height must be a
staking dayblock height - (provisional C) The "most recent finalized PoW Height" is > N staking cycles from the height of the
Unstake Bondaction.
Alternatives Considered to Provisional C:
- (provisional A) There are no restrictions based on finality.
- (provisional B) The "most recent finalized PoW Height" is > the height of the
Unstake Bondaction.
Convert Rewards action
- Must refer to an existing
finalizer commissions bucketwhich is at least one staking cycle old
Nuance / Subtle: This does not have a staking day blockheight restriction.
Zcash Crosslink Design Overview
Project: Crosslink (Zcash)
Status: Living document — draft 10. Draft 7 plus material folded in from four working notes: slashing_constraints, network_design, bootstrap_and_stake_rewards, storing_crosslink_in_pow. Items marked [TBC] are unsettled or were cut off in dictation.
Related: Nikete's Mechanism Design Audit of Crosslink Zebra (recommended reading for Part IV).
How to read this document: The main body text is specification. Supporting material is folded into collapsible sections tagged by category: Rationale (what motivates a design choice), Implementation detail (details of the current or possible implementations), and Other details.
Terminology used in the working notes and adopted here
TFC— the BFT certificate ("trailing finality certificate").lockbox— the finalizer bank account of section 14.NSM— Zcash's network sustainability mechanism (burn/reissue).Tenderlink— the BFT (Tendermint-derived) node component and its networking;PoWLink— the PoW block side-channel.
CONTENTS
- Part I — What Crosslink is and why
- Part II — The two chains
- Part III — What finality means here
- Part IV — Stake
- Part V — Punishment
- Part VI — Open questions
PART I — WHAT CROSSLINK IS AND WHY
1. PURPOSE
Crosslink adds a proof-of-stake BFT (Byzantine fault tolerant) layer whose only job is to finalize the proof-of-work chain. It does not replace proof of work and it does not carry the ledger. It periodically reaches agreement that a specific PoW block is final.
Rationale: the problem, and the five goals the design serves
Zcash is a proof-of-work chain, and proof of work gives only probabilistic finality: reversing a block grows ever more expensive, but there is never a moment at which it is definitively settled. In practice the tip of the chain can thrash — small reorganisations near the head as competing blocks race.
The rest of the design is arranged so that:
- this agreement has teeth (nodes will not reorg past it),
- proof of work remains the primary system, so that if the BFT layer fails the network decays gracefully back to plain PoW,
- stake is genuinely at risk, so finalizers can be held to account,
- all of this is done privately, in keeping with Zcash, and
- the whole thing is robust to malicious peers.
Most specific choices below are downstream of one of those five goals.
2. THE ONE-PARAGRAPH VERSION
There are two chains. The PoW chain gets a new field, the "fat pointer", that names a BFT certificate by hash and carries signatures attesting to it. The BFT chain is a sequence of certificates, each of which finalizes one PoW block and carries a few PoW headers above it as evidence of work. Each chain therefore points at the other. Nodes follow the "sticky choice" rule: most-work still picks the best chain, but once a finalized block is on your best chain you never reorg past it, so finality is a ratchet rather than an override. BFT participants are "finalizers"; anyone can delegate stake to them by creating anonymous, fixed-denomination bonds from shielded funds. Rewards are paid uniformly and only while the system is working; there is no in-protocol slashing. Instead, slashing is a user-coordinated hard fork that burns all stake delegated to a named finalizer and jails it. All ledger state lives on the PoW chain, and every economic effect is computed from what the PoW chain can see through the fat pointer.
Rationale: why there is no in-protocol slashing
There is no in-protocol slashing because the protocol cannot agree on who voted for what.
PART II — THE TWO CHAINS
3. THE PROOF-OF-WORK SIDE: THE FAT POINTER AND WHERE IT LIVES
What the fat pointer is
The PoW chain carries, per block, a "fat pointer" to the BFT chain:
- a hash identifying a BFT certificate, and
- a set of Ed25519 signatures attesting to that certificate.
The certificate is referenced by hash rather than embedded by value.
All ledger state — balances, bonds, rosters — lives on the PoW chain. The BFT chain finalizes and holds no state of its own. Every payout, burn or slash is computed from what the PoW chain can observe about the BFT chain, and the fat pointer is the only window.
Rationale: why a hash, and why the signatures sit beside it
A certificate contains PoW headers, so embedding it in a PoW block would be recursive. Referring by hash breaks the recursion at the cost of the "not yet known" state discussed in section 5.
The fat pointer exists because a certificate cannot carry its own signatures: the signatures are over the certificate, so they cannot be inside it. Several places for the signatures were considered; alongside the hash on the PoW side is the one settled on.
Other details: fixed-size signature set
Whether the signature set could be made fixed-size with a different scheme is an open question (Part VI).
Where in the PoW block it lives
Which storage option to adopt is not yet settled (Part VI).
Implementation detail: the current approach
The current implementation modifies the block header directly and bumps the header version. (The version number is [TBC]; "version 5" was dictated but may be a confusion with transaction v5.)
Other details: consultation with ZIP editors
A ZIP call on 2025-08-05 with Jack "str4d" Grigg and Daira-Emma established that this is possible but "fractally difficult", and that the options below should be weighed first. Jack has offered to review early designs.
Rationale: why changing the header is hard
- ASIC miners may have hardcoded header interpretation. Breaking most miners would structurally reduce PoW security.
- The version field has been used inconsistently in the wild (e.g. big-endian 4 and other small numbers). If mining follows the Stratum protocol of ZIP 301, a strict version == 4 is already required and a plain bump would work; if not, the little-endian signed value must still be positive, so the top bit is available as a flag (the approach ZIP 202 uses for "overwintered"). [TODO: survey actual version-field use on chain.]
- Exchanges and others may have custom parsers. SPV and lightwallet protocols are little used, and the mining-pool population is small enough to talk to individually, which may make this tractable.
Implementation detail: storage options, in increasing order of change required
- a. Commit only. Do not store Crosslink data; add it to the tree behind the existing 32-byte commitment field whose meaning is versioned. Probably insufficient, since some data must actually be stored.
- b. Coinbase sigscript. ~100 bytes, and the cap is far easier to raise than the header. Fits a 32-byte hash of the certificate but not signatures. Compatible with designs that ignore signatures on the PoW side, at the cost that a new PoW block's link cannot be verified as carrying the required votes without consulting an up-to-date PoS service.
- c. Typed memo bundle on the coinbase transaction (all-zero key), committed to. Up to 16 KB — ample for the current signature format, perhaps not for anything post-quantum.
- d. Modify the header directly (current approach). Daira-Emma's caution: unless notarization proofs are short and constant length they do not belong in the header, and putting them in the coinbase merges the indirection with one that is needed anyway to validate the block. A variable-length vector of 32-byte fields, length fixed by semantic version, is one shape.
- e. Two-level header: a small fixed-size header committing to a variable-length non-transaction "sidecar" section that holds the Crosslink data and other things. Jack and Daira-Emma were both in favour if the pain of a breaking header change is being paid anyway; there is a backlog of things they would like to fix at the same time (promoting data currently back-doored through the commitment tree, etc.). Top-level headers should fit in a network MTU; if PoW is not in the fixed part, P2P may need care.
A caveat for any option that keeps the data outside the header: PoS blocks cannot then use the PoW headers they carry to directly reach back-references to earlier PoS blocks.
Other details: further reading
ZIP 200 (network upgrade mechanism); zcash issues #172, #5755, #1040.
4. THE BFT SIDE: TFCs AND σ
The unit of the BFT chain is a TFC. Each non-genesis TFC carries headers_bc: exactly σ PoW headers, deepest first. The block it finalizes (its "snapshot") is not among them. It is the parent of the first header, named by that header's parent hash. So the σ headers are the confirmations above the snapshot, and the snapshot is σ-confirmed by construction.
σ is a protocol parameter.
Implementation detail: the prototype's value of σ
The prototype sets σ = 4. This value has not been checked for security or performance.
Two TFC validity rules concern headers_bc:
- Tail Confirmation: the headers are the
σ-block tail of a bc-valid chain. - Linearity: each snapshot is equal to or descends from the parent TFC's snapshot. Final snapshots only move forward along one PoW chain.
A validator must download and validate the PoW blocks under those headers, not just check the headers' work. Tail Confirmation requires a bc-valid chain, and a proposal whose snapshot the node cannot resolve cannot be validated yet.
Rationale: why validators fetch the blocks, not just the headers
Headers alone do not establish validity. The trade-off is accepted: finalization waits on the validators receiving those blocks. Tail Confirmation is objective all the same: σ consecutive headers ending at a bc-valid block form that block's tail, whatever the validator's own best chain is.
Inclusion Depth
A PoW block at height P may cite (via context_bft) a TFC whose snapshot is at height F only if P >= F + σ + 1: the σ carried headers F+1 ..= F+σ, then the carrier. This is a bc-block validity rule, beside Valid Context, Extension and Last Final Snapshot. Checking it takes a PoW -> PoS -> PoW lookup: resolve the pointer to its TFC, take the TFC's snapshot, look up its height. A block whose snapshot is not yet known is deferred, not rejected.
Implementation detail: block templates
Block templates apply the same test, so a miner is never handed a TFC it could not include.
Rolling, not batch
An honest proposer carries the σ-block tail of its own best chain. If that tail would break Linearity (e.g. after a PoW reorg below the last final snapshot), it repeats its parent's headers instead. A decision at PoW tip T therefore finalizes T - σ. Each decision advances the snapshot by however many PoW blocks arrived since the last decision. It repeats the snapshot when no block arrived and jumps several blocks when decisions are slow.
Other details: the rolling window is inherent
This rolling window is how the construction already works; it does not depend on incentives.
Implementation detail: deviations from the TFL Book's honest proposer
- Our proposer clamps the snapshot to at most 40 blocks above the previous final snapshot. When the clamp binds, the proposal is a window ending below the tip. That still satisfies Tail Confirmation. The clamp is a heuristic, not part of Crosslink 2.
- Where the honest proposer would repeat its parent's headers, ours makes no proposal. It declines when the tail would break Linearity, when the candidate would not improve on the last final snapshot, and when a PoW reorg lands between reading the tip and reading the tail. How often a proposer should repeat instead is not yet decided. Both are proposer behavior, not validity rules: a validator cannot tell whether the headers were the proposer's best-chain tail.
Finality lag
By the Inclusion Depth rule, the first PoW block that can cite a decision at tip T (snapshot T - σ) is T + 1, and only if its template was built after the decision arrived. So local finality trails the best tip by at least σ + 1 blocks in steady state. Stale templates and slow decisions add more.
5. MUTUAL REFERENCE AND ITS CONSEQUENCES
Because each chain references the other, there is a serial dependency in both directions:
PoW depends on BFT
A PoW block pointing at a certificate the node has not seen cannot be validated until the certificate arrives.
BFT depends on PoW
A finalizer cannot vote on a proposal whose candidate it has not fully validated, which requires the candidate and its ancestry.
The third validity state
Conventionally a proposal or block is valid or invalid. Crosslink adds "not yet determinable" on both sides: the node is waiting for data before it can take a position. That data may never arrive — a malicious peer can reference a hash for which nothing exists — so "pending" must be a state that can expire or be abandoned, never one the node blocks on indefinitely. [TBC: the exact rule.]
Rationale: threat model
Robustness to malicious peers — dangling references, withheld data, attempts to wedge validation — is a standing constraint. Hash-only pointers, the third state, and tolerance for data that never arrives all follow from it.
6. THE BFT IMPLEMENTATION
The BFT layer is Tendermint-derived, with the ternary validity state (section 5) encoded in the protocol itself.
Implementation detail: Tenderlink
The BFT layer (Tenderlink) is a reimplementation of Tendermint. Reuse was not possible because the ternary validity state must be encoded in the protocol itself.
One property shapes the whole economic design: peers reach consensus on the decision for a certificate (was it approved by two thirds of stake-weighted power?), but different peers may hold different subsets of the votes that made up that two thirds. The outcome is agreed; the exact signature set is not. The protocol therefore cannot use "who voted for what" as evidence for anything — not slashing, not per-vote payouts. See sections 11 and 16.
A second assumption of Tendermint matters for slashing: every finalizer must have an identical understanding of who is in the roster. Section 16 spells out what that forbids.
7. NETWORKING AND SYNC
Rationale: what went wrong with the existing stack
Zcash's sync layer assumes one logical chain in which every block has one parent, so a suffix connecting to a known ancestor is enough to validate everything in it. It bulk-syncs infrequently, and any validation failure triggers a long timeout. Crosslink has two logical chains, each needing knowledge of the other to progress, which produces round-trips like:
receive a decided BFT block → query for its PoW blocks → header missing → PoWLink downloads the chain backwards by hash until Zebra recognises a block → submit PoW blocks in order, but they contain certificate changes that query PoS state → only now can the BFT block be processed.
In workshops at an increased block rate, sync was too slow: people diverged by over a hundred blocks and could not recover without a reset, and a side channel had to be added. Mempool sync also appeared not to happen when the sender is a miner placing the transaction directly in a block.
σ-based security depends on sufficiently fast sync, so this is a security requirement, not just a usability one.
Implementation detail: interim solution — Tenderlink networking and PoWLink
Tenderlink networking is a custom, encrypted-from-the-ground-up (NOISE/Snow) datagram protocol. Keys rather than certificates provide identity and addressing. Packets are MTU-sized with application-level fragmentation and application-controlled (naive) resend and specific-peer targeting; there is no congestion control. Proposals span many packets, votes pack many into one, status messages are one-to-one.
PoWLink is a reliable-stream side channel that downloads PoW blocks and submits them to PoW state. It exploits finality directly to linearise and find the required chain — in effect "more frequent checkpoints" — and is "always up" rather than periodic. Its gain is discovery speed more than raw download speed.
The new networking stack
Requirements: "little and often" and "high-bandwidth serial beaming"; reliable and unreliable transport; large datagrams; multiple streams per connection; forward and backward secrecy; connection migration and rekeying; upgradeable-but-not-downgradable crypto; high bandwidth, high ping and high jitter; identical API over Nym mixnet and direct connections; and the recognition that networking is CPU work, not just I/O waiting. It is not expected to be compatible with Bitcoin-style sync.
Other details: coordination
Requirements are being coordinated with Nym, ZF and Tachyon.
Three layers:
- 1. Transport — use-case agnostic: congestion control (ECN, loss, bytes in flight), MTU discovery and BDP, bulk transfer with acking, minimally blocking. Data packets are all the same size for indistinguishability.
- 2. P2P — probably application-transparent: gossip, UDP hole punching via a third party. Hard-NAT clients (phone wallets) are expected to use a client-server model, which the protocol is designed to support well.
- 3. Application — sensitive-metadata announcements over Nym (tx announcements; optionally BFT messages and newly mined blocks), BFT and PoW block sync, BFT votes, lightwalletd traffic, bootstrap (DNS?).
Non-goals for now: multiple NICs, one logical client in multiple physical locations, rapid reopen of identical connections, symmetric-NAT traversal, local-endpoint discovery, packet relay.
Other details: possible later transport features
Possible later: opt-in RaptorQ-style loss recovery, compression, "packlet" framing for small items.
Rationale: why not QUIC or libp2p
Why not QUIC: no Nym path; TLS is redundant with NOISE and brings certificate authorities and downgrade concerns; complexity and audit surface.
Why not libp2p: misaligned goals (NAT-poor, relay-heavy, broadcast only), too modular to use effectively, large code volume, pub-sub is the wrong model since every message is globally relevant and should always be gossiped, DHT is unneeded, and it would be a heavy non-Zcash supply-chain dependency for a key component.
Interleaving
Implementation detail: interleaving the two sync streams
The two streams are currently handled separately. Interleaving them in a serializable order is planned but not done.
8. BOOTSTRAP AND ACTIVATION
The BFT chain has no external genesis. It is started deterministically by every node from PoW state alone; nothing about genesis is received from the network or agreed by a separate process.
Other details: why this section exists
This section records how, since the safety argument otherwise lives only in code.
Heights
h1 (BOOTSTRAP_ROSTER_HEIGHT): The PoW block whose staking state supplies the roster that votes on BFT height 0.
h2 (BOOTSTRAP_ACTIVATION_HEIGHT): The PoW height at which a node walks back, finalizes h1, and starts BFT. Every PoW block at or below h2 must carry a nil fat pointer; the first non-nil pointer can appear only above h2.
h2 - h1 > MAX_BLOCK_REORG_HEIGHT.
At activation every block in [0, h1] becomes de facto finalized.
Implementation detail: heights as implemented
BOOTSTRAP_ROSTER_HEIGHT = STAKING_PERIOD / 2 (call it h1)
BOOTSTRAP_ACTIVATION_HEIGHT = h1 + 200 (call it h2)
There is a compile-time assertion that h2 - h1 > MAX_BLOCK_REORG_HEIGHT.
Rationale: safety argument
By the time any node reaches h2, block h1 is below the reorg limit and therefore identical on every chain a node could be following. So every node computes the same roster from h1, constructs the same BFT genesis, and the Tendermint requirement that all finalizers share one view of the roster (section 6) holds from the first round without any coordination.
This is the bootstrap instance of the general rule in section 16: the roster is a pure function of finalized PoW state, and the finality in question here is reorg-depth finality rather than BFT finality.
Other details: relation to the three-height plan in the notes, and BFT genesis
The rewards notes describe three heights: H1 (staking transactions activate), H2 (roster is determined), H3 (first block that may point at a certificate), with H2 and H3 fixed in one governance decision and H2 perhaps H3 minus 100,000. The code's h1 corresponds to the notes' H2 and the code's h2 to the notes' H3; the notes' H1 (activation of staking actions) is not a separate constant in the code as described. [TBC: reconcile naming, and confirm whether the 200-block gap is a development value versus the ~100,000 suggested for mainnet.]
Whether BFT genesis should point at the PoW genesis or at h1 remains open.
PART III — WHAT FINALITY MEANS HERE
9. STICKY FORK CHOICE
Every node, and in particular every miner, must choose a best chain given information from both chains.
Rationale: alternatives on the spectrum
Raw work (Crosslink 2's unmodified fork choice)
Most work wins. A node can follow a heavier chain that excludes its own finalized block. The finalized point is then left on an abandoned branch.
Follow the latest BFT snapshot (the TFL Book's "Questions" rule)
The best chain must extend the snapshot of the newest final TFC in view. That point need not be on any chain the node has selected, nor σ-confirmed in one. The Book's author concludes "Probably not".
Sticky fork choice — our rule
The floor is the node's own fin (local_finalized_tip), not the BFT snapshot. A node switches from its current chain to a new one iff fin is on the new chain and the new chain has more work (ties broken by tip hash). Equivalently: best = heaviest chain that contains fin.
How fin moves
fin is never set from a BFT decision directly. On every change of best chain, the node computes
candidate(best) = lca(snapshot(LF(best)), prune_σ(best))
where LF(best) is the TFC the tip's context_bft points at, and prune_σ(C) is C with its last σ blocks removed. If fin is an ancestor of or equal to the candidate, fin := candidate. Otherwise fin stays put. So fin only advances along the node's own best chain, only to blocks the node has itself buried σ deep, and never backwards.
The walk that computes the candidate, with σ = 4 and best tip P10. Newer blocks are at the top, and each arrow points from a block to something it names:
graph TD
subgraph bftChain ["BFT chain"]
T6("TFC 6 · LF(P10)<br/>headers_bc =<br/>[P6, P7, P8, P9]"):::lf
T5("TFC 5"):::bft
T4("TFC 4"):::bft
T3("TFC 3"):::bft
T2("TFC 2"):::bft
T1("TFC 1"):::bft
end
subgraph powChain ["PoW best chain"]
P10(["P10 · best tip"]):::pow
P9([P9]):::pow
P8([P8]):::pow
P7([P7]):::pow
P6(["P6 · prune_σ(best)"]):::pow
P5(["P5 · candidate(best) · fin"]):::candidate
P4(["P4 · fin before this update"]):::pow
P3([P3]):::pow
end
%% Parent links
P10 --> P9 --> P8 --> P7 --> P6 --> P5 --> P4 --> P3
T6 --> T5 --> T4 --> T3 --> T2 --> T1
%% Crosslinks
P10 -- context_bft --> T6
T6 -.-> P9
T6 -.-> P8
T6 -.-> P7
T6 -.-> P6
T6 == snapshot ==> P5
%% Styles defined in mermaid-common-styles.js and mermaid-styles.md
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
classDef bft fill:#fff,stroke:#b71c1c,stroke-width:3px,color:#000
classDef lf fill:#ffcdd2,stroke:#b71c1c,stroke-width:3px,color:#000
classDef candidate fill:#ffeb3b,stroke:#01579b,stroke-width:3px,color:#000
%% Define fin last, so that its border wins over the block style.
classDef fin stroke:#8e24aa,stroke-width:7px
class P5 fin
P10 cites TFC 6. Its dotted arrows are the σ headers it carries, and its snapshot is the parent of the deepest one: P5. prune_σ(best) is P6. So candidate(best) = lca(P5, P6) = P5. fin was P4, an ancestor of P5, so fin := P5.
The update rule:
graph TD
decision(["A BFT decision arrives"]):::input --> snap["bft_final_snapshot advances.<br/>fin does not move."]:::storage
change(["The best chain changes"]):::input --> compute["candidate(best) =<br/>lca(snapshot(LF(best)), prune_σ(best))"]:::compute
compute --> test{"Is fin the candidate<br/>or an ancestor of it?"}:::compute
test -- yes --> advance["fin := candidate"]:::output
test -- no --> hold["fin stays put"]:::storage
%% Styles defined in mermaid-common-styles.js and mermaid-styles.md
classDef input fill:#e1f5ff,stroke:#01579b,stroke-width:3px,color:#000
classDef compute fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
classDef output fill:#e8f5e9,stroke:#1b5e20,stroke-width:3px,color:#000
classDef storage fill:#fce4ec,stroke:#880e4f,stroke-width:2px,color:#000
A Visual Guide to Finality and Fork Choice draws the reorg cases.
The ratchet, step by step
- A decision arrives. It advances
bft_final_snapshot(the snapshot of the newest decided TFC), which may be on a side chain. Myfindoes not move yet. - A PoW block on my best chain cites that decision in its
context_bft. Once that block is my best tip,finratchets up to its candidate. I will never again switch to a chain lacking it. - A side chain carries newer decisions. I sync it anyway, store its blocks and decisions outside the finalized state, and track bonds along it (I need that for the roster, section 11). Under Linearity it contains my
fin, so it stays eligible. - If it ever has more work than my chain, I switch, on work alone.
finthen ratchets to that chain's candidate. - A heavier chain that forks below my
fin: I refuse it, whatever its work. This refused switch is the only observable sign of a finality conflict.
Implementation detail: logging finality conflicts, and Zebra's reorg-depth commit
A refused switch is logged; a persisted hazard record is still TODO.
Caveat: Zebra also commits blocks at reorg depth (MAX_BLOCK_REORG_HEIGHT). If my best chain runs that far past the fork to bft_final_snapshot, the depth commit conflicts with it and I can never switch back. Under Linearity my branch then never finalizes again until I resync.
Rationale: why this rule
BFT does not choose the chain. It only ratchets a floor under the work rule, and only to points my own work-selected chain already has σ deep. An advance of fin never causes a switch. The rule departs from raw work only when a heavier chain excludes fin. By construction that would displace a prefix σ-confirmed on my own earlier best chain. While BFT is stalled or withholding, fin is frozen and selection above it is plain most-work, so PoW stays the Schelling point.
Other details: what this rule does not buy
- No Stalled Mode, so the gap between
finand the tip is unbounded during a stall, and ordinary spends keep landing abovefin. - A miner who dominates the best chain can withhold finality progress by never updating
context_bft; that costs nothing in validity. - A partition in which only one side can finalize past the fork leaves that side permanently unwilling to switch to the other.
- The TFL Book has no safety or liveness proof for this rule. Its liveness argument relies on unmodified fork choice.
10. KINDS OF FINALITY AND WHICH LEDGER STATE IS CURRENT
BFT finality (bft_final_snapshot)
The snapshot of the newest decided TFC. It is objective, and possibly on a chain the node does not consider best, for any length of time.
Other details: usage in conversation
"Crosslink finalized" in conversation usually means this.
Local finality (fin / local_finalized_tip)
The node will not reorg past this block. It is node-local and monotone, advanced only from candidate(best) as in section 9. It always lies on the best chain and is at or below bft_final_snapshot (under Linearity).
Implementation detail: persistence of fin, and the database finalized tip
fin is persisted in the finalized database as its own hash.
Database finalized tip. Not finality. It is the higher of fin and Zebra's reorg-depth commit, so it can be above fin. It is a physical commit boundary, not a cache of fin. Never report it as Crosslink finality. Finality readers take fin.
No protocol quantity lies between the best tip and fin. A "confirmed" display is plain PoW confirmation depth, never final.
Consensus must never read fin. Anything every node must compute identically comes from objective chain data:
Rationale: why consensus must not read fin
Honest nodes reach the same chain through different histories, so their fin values are only prefix-compatible, not equal.
Roster for BFT height H
the bonds at snapshot(B_{H-1}), the snapshot of the decided TFC at H - 1. BFT agreement fixes that TFC, so every validator derives the same set. It is generally above fin and may be off the best chain, so it is read from the synced chain leading to bft_final_snapshot (section 11).
Staking rewards
an objective per-block trigger, not fin (section 14).
PoW-tip state
ordinary ledger state at the best tip. Staking transactions in a block are validated against their own chain.
PART IV — STAKE
11. FINALIZERS AND ROSTERS
Participants in the BFT layer are finalizers. A finalizer's voting power is the stake delegated to it (section 12). Every "percentage of finalizers" here is stake-weighted, never a headcount.
Active and inactive rosters
Finalizers are split into an active roster and an inactive roster. The roster for a given certificate must be a pure function of finalized PoW state plus the slashing config (section 16). The active roster is selected as the top N finalizers when sorted by voting power, where N is the active roster length (a fixed constant).
Rationale: why two rosters
The split exists for performance and technical reasons — it bounds the number of parties per BFT round — and is not a reward or penalty mechanism.
Finalizers opt in
A finalizer publishes an address that acts as a capability carrying its own signature consenting to act as a finalizer. Delegation requires this consent.
Who is behind a finalizer
Crosslink has no internal web of trust.
Other details: off-protocol attestation, and a possible signed-message channel
The expectation is that Zcash organisations will attest outside the protocol that a finalizer is run by a particular provider or company, and that users can combine several attestations into a reasonable judgement.
A possible built-in feature: since finalizers already have keys, they could sign short, namespaced messages that nodes gossip at a rate limit of about one per active finalizer — "down for maintenance Tuesday; planned, not malice." Today such notices go out on forums or social media, unlinked to the on-chain identity. The most important use would be during a slash fork, where finalizers need to signal which side they will be on. [Idea only.]
Uniformity, and no automatic slashing
There is no automatic slashing, and all active finalizers are paid uniformly at the same time. Punishment is a social process (section 16).
Rationale: why uniform, and why no automatic slashing
Because peers do not agree on exact vote sets (section 6), the protocol cannot reward or punish individual votes.
12. DELEGATION BONDS
Delegation of stake from anyone (including finalizers themselves) to a finalizer is a primitive construct, and the way essentially all stake is assigned.
Creating a bond
A user spends shielded funds in a transaction carrying a staking action. "Create delegation bond" specifies:
- an amount, which must be a power of ten ZEC;
- a target finalizer, via its consent capability.
The result is a bond: a free-floating note controlled by an Ed25519 key. Holding the key is holding the bond. The key is derived from the create action plus a salt.
The total staked to each finalizer is public.
Rationale: privacy properties of bonds
The power-of-ten amount is privacy quantization, so bonds cannot be fingerprinted by size.
Because holding the key is holding the bond, it can be operated anonymously, decoupled from the funds that created it. Deriving the key with a salt means repeated identical delegations yield distinct, untangled bonds.
The privacy trade-off: bonds are anonymous, but the total staked to each finalizer is public. That total is what voting weight is computed from, so it has to be.
Bonds are atomic
Bonds cannot be split; retarget, unbond and withdraw act on the whole bond.
Retargeting
A bond can be retargeted at any time. The transaction records both old and new target, so from the bond state at time t the retargets can be played backwards to recover the mapping at any earlier time.
Rationale: why retargets record the old target
Slashing depends on this.
Withdrawing: unbond, then withdraw
Two actions on two different staking days (section 13), so minimum exit is two weeks.
- Unbond. Value depends on which block it lands in; once landed, the bond has a fixed numeric value.
- Withdraw. The transaction must state that value explicitly and match the chain exactly, or it is invalid.
Rationale: why two steps
Two reasons. Accounting clarity: before funds re-enter ordinary Zcash transaction land their amount must be an explicit number, not implicit ledger state. Security: the enforced delay is what puts stake genuinely at risk — if an attack is discovered there is time to slash before the funds escape into the shielded pool.
13. STAKING DAYS
One day per week is a staking day. Bond creation, unbond and withdraw are quantized to staking days.
The slash window (section 16) is also measured in staking days.
Rationale: why staking days
- Privacy: batching activity into one day per week removes timing information that could link actions to users.
- Security: unbond and withdraw on successive staking days gives the two-week minimum exit.
14. REWARDS
Rationale: design stance — smooth enforcement
The economic design leans on withheld income rather than destroyed funds. Uniform, conditional payouts make staking feel like mining: put money in, earn while the system works, and if the system is attacked or stalls you lose income, not principal. Missed income is a far smoother enforcement mechanism than burning, and it means stakers are rewarded or not for the mechanism as a whole working — never for particular finalizer or miner behaviour. Destruction of funds is reserved for the case where users identify a staker as having aided or been totally negligent in an attack, via a slash fork (Part V).
Proposed issuance split
Of post-dev-fund issuance (ignoring the initial 20% deduction):
- 48% — miner subsidy
- 48% — staking rewards (finalizers and stakers)
- 4% — miner bounty for including a new finality
Within the 48% staking share, the split is 90/10:
- 90% — to bonds, pro rata by size against total stake
- 10% — to active finalizers, uniformly
The 90% includes finalizers staking to themselves. Rewards come from a fixed pool; there is no guaranteed percentage yield.
Proposed issuance rule
IF a PoW block points at a new certificate, AND that certificate finalizes a PoW block close to the tip, THEN stakers and finalizers receive the 48% staking reward and the miner receives the 4% bounty; OTHERWISE the 52% is NSM-burned.
"Close to the tip" is measured entirely on the PoW chain: this block points to a certificate, which points to a PoW block; the delta between those two PoW heights is the distance.
Rationale: the purposes this one rule serves
- First-inclusion miner bounty: miners are paid to advance finality monotonically rather than reuse a stale pointer (audit item R2).
- Anti-jackpot: rewards cannot accumulate while finality is stalled (R4). Because the reward is single-shot per block, nothing is ever accrued or recalculated; accumulated values need not be stored anywhere. Bounty sniping is not an issue in steady state and at most a flaky-finalizer concern.
- Certificate aging by another route: instead of expiring old certificates, catch-up is incentivized by withholding rewards from finalizations far behind the tip (R6). During catch-up the current heuristic is roughly 40 blocks per certificate; finalizers are incentivized to coordinate quickly on a known shared prefix rather than skip ahead to unshared tips, because otherwise they earn nothing. This is an incentive, not a consensus constraint.
- Slash forks suspend payouts for their duration, since the pointer stops advancing. This does not disincentivize spring-cleaning forks: their BFT activation is
u32::MAX, so they are a single point of cremation rather than a stall.
Other details: FlyClient aside
FlyClient-style proofs might help finalizers establish a shared prefix fast.
Bonds always earn
A bond accrues reward whether or not its finalizer is on the active roster.
Rationale: anti-centralization
Backing an up-and-coming finalizer costs nothing — deliberate anti-centralization.
Other details: open question on the 10% denominator
Open: is delegating to a non-active finalizer a "vote of no confidence" in the active roster, such that finalizer commission should shrink — i.e. should the 10% denominator be active-roster stake or total stake? ("Vote of no confidence" versus "pay for infrastructure".)
Finalizer lockboxes (bank accounts)
The 10% goes into a per-finalizer lockbox balance on the ledger. A staking action turns lockbox balance into a bond. The lockbox itself also behaves as a virtual bond delegated to its finalizer, so it accrues from both sources: from the 90% like any bond (per total), and from the 10% (per total, or per active-roster member on each new block — open). Ordinary bonds accrue only from the 90%.
Implementation detail: burns and acceleration for lockboxes
Burns are an extra complication: normal burns come from transactions, whereas these would be implicit or a new data member, and different burn designs have different complexity costs.
Because the active roster is bounded, lockboxes should not need the acceleration structure of section 15, though computing "active" as well as "total" stake is a small addition that is needed for Tenderlink anyway.
15. ACCOUNTING AND THE ACCELERATION STRUCTURE
Every party, at every query resolution, must agree exactly on the value produced for each recipient.
Rationale: why an acceleration structure, and why determinism over precision
Very many unmergeable bonds; finalizers, miners and wallets need fast answers (finalizer weight, what is final, what my bonds are worth). An acceleration structure over bonds is required, and it depends on payout details, so it follows them.
Integer zatoshis divided by an arbitrary total stake guarantee some rounding error. It is minor and should be apportioned sensibly, but the requirement above stands. Determinism beats precision.
Implementation detail: defer everything
Bond creation is cheap; ongoing work is per-finalizer and global; an individual bond's value is computed only on query or at unbond. Single-shot rewards (section 14) help here: nothing accumulates.
PART V — PUNISHMENT
16. SOCIAL SLASHING
There is no automatic slashing (sections 6, 11). Punishment of stake behind misbehaving finalizers is a user-coordinated hard fork.
Rationale: why social
The protocol cannot agree on vote sets, and "well behaved" is fuzzy: a stall can never be proven permanent. The judgement is left to users, aided by visualization tools that inform but cannot decide.
Hard constraints on how a slash may work
- The updated roster must be a pure function of finalized PoW state plus the slashing config. It may not depend on any PoW data not already implied by shared certificates. Tendermint assumes every finalizer has an identical view of the roster, and side chains may validly disagree about recent PoW, so:
- the new roster cannot be derived from staking actions up to the activation tip, and
- it cannot use "the highest certificate the PoW chain points at", since chains may disagree on what that is.
-
Staking actions that have landed in the PoW chain must be respected.
-
PoS stores no ledger information of its own.
-
Application must be robust to users, miners and finalizers adopting the config at different times; no accidental hard forks from unspecified race conditions.
Rationale: why landed staking actions must be respected; design virtues
Justice: most are unrelated to any slashed finalizer. Practicality: reclaiming them would need extra machinery. PR: in a long stall, ignoring them would look like a huge reorg.
Design virtues (soft constraints). Users should preference-cascade to the same input values, so fewer degrees of freedom is better. Users should be able to decide at a suitable resolution. Negligent stakers should be slashed and non-negligent ones not. Miners and finalizers should not be over-weighted in the decision. Roster computation should be cheap in memory and CPU. Forks should be deferred where possible.
Triggering a slash
Node operators modify their config to list the finalizer(s) to slash and a PoW activation height. Every slash event is a hard fork; there is no default switch.
Implementation detail: nudging nodes onto a fork
Currently nothing nudges a node onto a fork (a warning system may be added).
Rationale: why a config, not something else
Two goals pulled in different directions: users should have a large amount of control, so the decision is not centralised; but it should also be easy for everyone to agree on the same thing and decide the same way, because divergent decisions mean multiple hard forks.
The alternative considered was having users edit the code directly. It was rejected because:
- the space of possible edits is too large to reach a Schelling point on;
- working through it exposed, as expected, many edge cases where it would be easy to produce a corrupt state, or one where an action on the PoW side rendered the PoS decisions meaningless — a tested implementation with a small set of inputs is far safer than something implemented and decided under time pressure;
- a config lets non-programmers have meaningful input.
A config with few degrees of freedom satisfies both goals: users decide, but there are few enough choices that they converge.
Two components
The Incinerator (PoW chain)
Burns every bond delegated to the named finalizer(s) within a window reaching back two staking days from activation. Retarget history makes that set reconstructible. No partial slashing, no tunable amount.
The Sergeant-at-Arms (BFT chain)
Jails the named finalizer(s) from voting in current and subsequent rounds; their weight leaves the pool so the rest can reach two thirds.
Bridging the fork: the "do not include by" height
Each certificate carries a "do not include by" PoW height, monotonically non-decreasing, which may only increase in the first certificate of a forked chain — the one embedding the slash config. The forked set resumes immediately on the BFT side while PoW transitions at one agreed height.
Rationale: why the "do not include by" height
PoW must not be disrupted while nodes switch. BFT has stalled; old PoW blocks keep pointing at the last old certificate; once enough finalizers adopt the fork, the reduced set produces new certificates, which must not leak into PoW before activation.
How nodes on different configs see each other
Votes are cryptographically namespaced by config, so nodes on different configs diverge immediately.
Implementation detail: how the other side currently appears
Currently the other side looks like malicious nonsense. This should be improved so a node can recognise "well behaved, different worldview". [TBC.]
Rationale: a big stick
A slash fork needs buy-in from essentially every node. Obvious cases behave like a network upgrade; splinter groups would leave no apparent canonical chain. The intended dynamic is that misbehaviour is obvious early and honest stakers retarget away in time — the threat moves stake, the burn is the fallback.
Scenarios
Other details: outright stall, flaky stall, spring cleaning, other malicious behaviour
Outright stall
BFT stops with identifiable offline participants. Available information stays consistent; probably the easy case — though one may actually be in the flaky case without knowing it.
Flaky stall
BFT stalls, resumes, stalls again; a gradient, not a category. Open: what happens if new certificates are produced between the creation of a slash config and its application?
Spring cleaning
No stall, but the stake-weighted share actually voting drifts down toward two thirds because some finalizers are permanently gone. From this perspective it may be fine for the fork to be merely a deadline by which stakers must have moved, rather than an actual punishment — i.e. analysis and application on a single block.
Other malicious behaviour
[TBC: not yet elaborated.]
PART VI — OPEN QUESTIONS
Other details: open questions
Header and encoding
- Which storage option from section 3 to adopt; survey actual version-field use on chain; talk to miners, pools and exchanges.
- Fixed-size fat pointer via a zero-knowledge proof over the signatures: feasibility and proving cost.
- Exact encoding of the fat pointer and certificate, including the "do not include by" field.
Protocol details
- Timeout/abandonment rule for "not yet determinable" (section 5).
- Whether BFT genesis points at PoW genesis or
h1(section 8). - Reconcile the notes'
H1/H2/H3with the code'sh1/h2, and the 200-block gap versus ~100,000 (section 8). - How the active roster is selected (section 11).
- Other anti-tail-thrashing mechanisms (section 1).
- Precise definition of "close to the tip" (section 14).
- 10% denominator: active-roster stake or total (section 14).
- Lockbox accrual from the 10%: per total or per active (section 14).
- Burn representation for withheld rewards (section 14).
- Acceleration structure design once payouts are fixed (section 15).
- Non-liveness misbehaviour slashing should cover (section 16).
- Certificates produced between slash-config creation and application (section 16).
- Why the parameters are what they are:
σ= 3, 48/48/4, 90/10, weekly cadence, two-staking-day window, power-of-ten sizes.
Networking
- Interleaving the two sync streams in serializable order.
- Bootstrap/peer discovery (DNS?).
Slash forks
- Recognising peers on another fork as well-behaved (section 16).
- Signed finalizer messaging channel (section 11).
Signature cryptography
- Aggregate signatures (BLS or similar) to make the signature set fixed-size. Most such schemes assume equal-weight signers; weight by repeated voting scales badly. Weight-aware schemes may exist or be emerging. Parliament-style quantization is an alternative with its own centralization risk.
- Post-quantum story for the fat pointer, bond keys and finalizer keys — not yet considered. Possible collaboration with the post-quantum cryptography team.
Wallet UX dependent on cryptography
- Automating the withdraw step without a live wallet.
- Scheduling a staking action from a non-staking day without relying on OS wake-up.
Loose ends
- Andrew had one further point at the end of session 5 that slipped his mind.
- Off-topic musing from the rewards notes: pay miners by block fullness rather than tx fees?
Crosslink finality semantics and Zebra policy boundaries
This document separates the three Crosslink 2 protocol quantities that Zebra's design retains from Zebra's irreversible state-commit boundary, legacy reorg-depth fallback, and consumer-specific meanings of "final".
It keeps three layers apart:
- Book: Crosslink 2 as the pinned TFL Book specifies it (§1).
- Zebra Crosslink: the behavior this tree implements. It is the Book's construction without
Stalled Mode, with sticky fork choice, persisted
fin, and every remaining CL2 validity rule. Statements in this layer are requirements, including where the code does not meet them yet. - Current tree: the code at this revision of the repository. Statements in this layer describe code that the implementation changes, and are not requirements.
| section | layer |
|---|---|
| §1 Scope | Book, with Zebra Crosslink's parameter and Stalled Mode choices |
| §2 Terminology | Zebra Crosslink; the Zebra-specific quantities note their current-tree form |
| §3 Crosslink 2 model | Book, with the consequences for Zebra Crosslink |
| §4.1 Raw fork choice | Book |
| §4.2 Finalized-prefix policy | a general policy, and its current-tree form |
| §4.3 Sticky fork choice | Zebra Crosslink, ending with the current tree |
| §5 Implementation inventory | current tree |
| §6 Divergences | current tree, measured against Zebra Crosslink |
| §7 Names and consumer contracts | Zebra Crosslink |
| §8 Implementation status and pitfalls | current-tree facts that constrain the implementation |
| §9 Open decisions | outside this document's implementation work |
Where a section mixes layers, a paragraph opens with its layer in bold. The ordered
implementation work, and the questions that still need a design pass, are in
IMPLEMENTATION.md.
A companion visual explanation is in
FINALITY_DIAGRAM.html.
1. Scope and source maturity
Crosslink 2 is parameterized by a best-chain protocol Π_bc and a BFT protocol Π_bft; it is
not intrinsically a PoW/PoS protocol. This tree's Zebra prototype instantiates the best-chain
side with PoW and the BFT side with a stake-based protocol. The generic model below therefore
uses bc and bft; implementation observations use PoW and PoS/BFT.
The primary design source is the original TFL Book at pinned revision
daira/tfl-book@fe6e1d6.
The adaptation in ShieldedLabs/zebra-crosslink is useful implementation context, but
describes itself as an almost-direct paste that may be incomplete, confusing, or
inconsistent
and records Zebra-specific omissions such as Stalled Mode.
The pinned construction currently defines
candidate(H) as written below.
Its rationale nevertheless ends with a TODO to choose between that clamp and a stronger Last
Final Snapshot rule based on proof and latency results
(lines 510–517).
This document treats the formula as the current construction, not as a settled protocol
decision beyond that source revision.
Zebra Crosslink omits Stalled Mode. The Book builds bounded availability from three parts: the
finalization gap bound L, the Finality Depth rule with its stalled-block exception, and the
bounded-available client view ba_μ with its confirmation depth μ. This design has none of
them; §3.3 derives why omitting Stalled Mode removes the other two, and what the remaining
definitions guarantee.
Current tree. The prototype sets σ = 4 in librustzcash/zcash_primitives/src/bft.rs
(PROTOTYPE_PARAMETERS). The source code explicitly warns that this value has not been
verified as secure or performant. The Book's L is not a parameter of this design: it is absent
from ZcashCrosslinkParameters, from the node configuration, and from the test format, whose
parameter instruction writes a zero in its place.
Notation
prune_k(C) means C with its last k blocks removed, with genesis as the floor. It is the
plain-text spelling of the Book's C ⌈bc^k. A ⪯ B means that A is an ancestor of or equal
to B; A and B conflict when neither is an ancestor of the other.
The two chains have their own parent links. They also contain two cross-chain references:
- each bc-block
HhasH.context_bft, which commits to a bft-block; and - each non-genesis bft-block has
headers_bc, exactlyσbc-headers in deepest-first order; the block it finalizes is the parent of the first, named by that header's parent hash (§6.1).
2. Terminology and layers
The construction as adopted has one fork-choice input, one objective intermediate quantity, and one client view:
| quantity | definition | kind |
|---|---|---|
bc_best / χ | highest-score bc-valid chain in the node's view | raw fork-choice view |
candidate(H) | lca(snapshot(LF(H)), prune_σ(H)) | objective function of a block and its ancestry |
fin | monotone local state updated from candidate(bc_best) | locally finalized client view |
The Book's fourth quantity, the bounded-available chain ba_μ, is not part of this design
(§3.3). No CL2 quantity lies between bc_best and fin.
Those three quantities do not exhaust the meanings carried by "final" in this tree. Zebra also has:
- a canonical-finalized policy point,
canonical_finalized_tip, that makes only chains containing that point eligible for local activation; - a physical database-commit boundary, the finalized database's tip, which advances only after the finalized-state write has succeeded; and
- a legacy reorg-depth marker, roughly
tip − MAX_BLOCK_REORG_HEIGHT. It has no consumer in the current tree, whose finality RPCs no longer substitute it when no Crosslink marker exists. It is listed here so that it is not reintroduced under a Crosslink name.
Protocol fin and these Zebra quantities must not share an undocumented storage slot. In raw
CL2, fin can remain fixed on a branch that raw bc_best no longer contains. A
finalized-prefix policy instead enforces canonical_finalized_tip ⪯ canonical_tip locally,
which is an additional chain-activation and state policy (§4.2).
Current tree. The floor is fin, advanced where the best chain changes and committed as it
advances, so the two quantities coincide (§5.2).
Zebra Crosslink. Under sticky fork choice (§4.3) the policy floor is fin itself, so
canonical_finalized_tip and fin are one quantity. Two stored values remain: fin, persisted in the finalized database
as its own block hash, and the database's finalized tip, which is the higher of fin and the
block Zebra commits at reorg depth. The finalized tip equals fin while finality lags the
best tip by less than about MAX_BLOCK_REORG_HEIGHT blocks. Past that lag the depth commit
runs ahead of fin, and if it comes to lie on a branch that excludes bft_final_snapshot, the
node opens a second chain state of the same shape for the BFT branch (§4.3, §7.1). fin is one
quantity across both: every branch the node records contains it.
A fourth quantity is objective rather than node-local:
| quantity | definition | kind |
|---|---|---|
bft_final_snapshot | snapshot(B) for the newest decided bft-block B in the node's view | the bc-block Π_bft has most recently finalized |
A BFT decision finalizes bft_final_snapshot in the sense of Π_bft, and "Crosslink finalized"
in conversation usually means this point. A node's fin reaches it only through the node's own
best chain, by the update rule of §3.2. Under sticky fork choice, and after each update:
candidate(bc_best) ⪯ fin ⪯ bc_best
fin ⪯ bft_final_snapshot (under Linearity and Π_bft Final Agreement)
fin equals candidate(bc_best) except after a reorganization that moved the candidate back.
bft_final_snapshot need not be on bc_best, and can stay off it for any length of time: it is
on a chain the node switches to only when that chain has more work (§4.3). The first line holds
exactly under fork-choice rules that keep fin ⪯ bc_best; under raw work-based fork choice both
of its relations can fail.
3. Crosslink 2 model
3.1 snapshot, LF, and candidate
snapshot(B) := O_bc if B.headers_bc = ∅
:= parent(B.headers_bc[0]) otherwise
LF(H) := bft-last-final(H.context_bft)
candidate(H) := lca(snapshot(LF(H)), prune_σ(H))
The walk is bc → bft → bft → bc, followed by the last-common-ancestor clamp.
bft-last-final(B) is the last final ancestor of B, B included. In Zebra, in the current
tree and in Zebra Crosslink alike, Π_bft decides
each bft-block individually, and a decided block is final. A bc-block's context_bft is a fat
pointer, and a node resolves it only against the node's own store of decided bft-blocks; a
pointer that does not resolve defers the bc-block (§6.2, Extension). Every context a node accepts
is therefore final, and bft-last-final is the identity on them, so LF(H) is the bft-block
that H.context_bft points at. Zebra Crosslink keeps that store in zebra-state beside the
chain it is resolved against (§7.1); in the current tree it is
BftChain::blocks (§5.5).
The clamp puts candidate(H) on H's own chain and no later than prune_σ(H). The Book says,
“This ensures that the candidate is at least σ‑confirmed”
(lines 510–517).
The source immediately identifies a possible alternative rule, so this rationale is evidence
for the current formula rather than evidence that the design choice is final.
3.2 fin: node-local monotone memory
When a node's bc-best-chain view changes, it runs the locally-finalized-chain update:
N := candidate(bc_best)
if fin ⪯ N:
fin := N
else:
keep fin
if N conflicts with fin:
record a finalization safety hazard
A candidate that moves behind fin during a reorg leaves fin unchanged and is not itself a
hazard; the Book gives that
reorg case as the reason fin needs local state.
A candidate on a conflicting fork also leaves fin unchanged and must produce the specified
hazard record, which carries bc_best and the fin history back to the last update that was
an ancestor of N. fin is therefore a node-local time series, not a pure function of the
current tip.
The Book's Local fin-depth lemma bounds where that series can be:
for node i honest at time t, there is a time r ≤ t with fin_i^t ⪯ prune_σ(bc_best_i^r)
Take r as the last time fin changed, or genesis if it never has. At r > 0, fin was set
to candidate(bc_best^r), and candidate(H) ⪯ prune_σ(H) because an lca is an ancestor of
both of its arguments. At genesis both sides are O_bc, since pruning O_bc yields O_bc. The
Book combines the lemma with Π_bc Prefix Agreement at depth σ to argue Assured Finality; that
use is why candidate clamps to prune_σ(H) rather than using snapshot(LF(H)) alone
(line 513).
When the prune_σ clamp binds. When the σ headers of LF(H) are all ancestors of H,
the last of them is at or below parent(H), so snapshot(LF(H)) is at least σ + 1 blocks
below H and the clamp does not bind. It binds when the headers lie on another chain that extends past H's own chain: for
example a short side chain whose blocks sit just above snapshot(B) and cite a bft-block B
whose σ headers continue on a different, longer chain. Last Final Snapshot admits such a block,
since snapshot(B) is its ancestor. Without the clamp, a node whose best chain is that side
chain would finalize snapshot(B) while its own chain buried that block only one or two deep.
That matters only when Π_bft is subverted. A subverted Π_bft can decide a bft-block whose
headers come from any chain with valid PoW, including one the adversary mined privately, and so
can name as its snapshot a block that an honest node has seen only shallowly on a branch about to
be abandoned. With the clamp, a node finalizes a block only once its own best chain has buried it
σ deep, so under Π_bc Prefix Consistency every honest best chain keeps that block and honest
fin values stay compatible without any assumption about Π_bft. Without it, a subverted
Π_bft alone could give honest nodes conflicting fin values.
Assured Finality requires honest nodes' fin values at arbitrary times to be
prefix-compatible. It does not require those values to be equal at the same wall-clock time.
3.3 No bounded availability
The Book's bounded availability is one mechanism in three parts:
- the Finality Depth rule
admits a bc-block
Hwithheight(H) − height(snapshot(LF(H))) > Lonly ifHis a stalled block; - Stalled Mode
defines stalled blocks (proposed for Zcash as coinbase-only), so that
Π_bckeeps producing blocks while no user transaction lands more thanLblocks past the snapshot; and - the bounded-available chain
ba_μ := prune_μ(bc_best) if fin ⪯ prune_μ(bc_best), else finis the client view whose distance ahead offinthat bound limits.
Without Stalled Mode, the other two parts have no role:
- Finality Depth. With no stalled blocks the rule would reduce to
height(H) − height(snapshot(LF(H))) ≤ L. During a BFT stall no context can lower that depth, soΠ_bcwould haltLblocks past the snapshot. That is still bounded availability, in its strictest form. The Book also rejects it as a design: it calls stopping the chain a naive approach with serious security problems under PoW, and its liveness analysis says any loss ofΠ_bcliveness would be a bug because it allows tail-thrashing attacks.Landis_stalled_blockhave no other use. ba_μandμ.ba_μdiffers from a plain confirmation depth only in its fallback tofin, and that fallback exists to keepfin ⪯ ba_μ. Without a bound there is nothing for that view to bound.
The same liveness analysis states that the Finality Depth rule is technically independent of the rest of Crosslink 2: without it, the protocol keeps its advantages over Snap-and-Chat, but the incentive to pull the finalization point forward is weaker. The concrete consequences for the remaining definitions are:
candidate(bc_best)can lag without any validity cost. The Extension rule permitsLF(H) = LF(parent(H)), and the Valid Context and Last Final Snapshot rules are always satisfiable by reusing the parent'scontext_bft. With no depth bound, a chain that never updates its context stays valid at any height. Progress offinwhileΠ_bftis live therefore depends on bc-block producers following the honest context-selection procedure (§3.4), which is not a validity rule. A producer with enough hash rate to dominatebc_bestcan withhold finality progress; under bounded availability it would have been confined to stalled blocks afterL.- The finality gap is unbounded. During a finalization stall,
bc_bestkeeps accepting ordinary spending transactions at any distance pastfin. The rollback exposure of those transactions grows with the gap. This is the outcome the Book's bounded-availability argument was written to avoid; omitting Stalled Mode accepts it. - No client view is both available and guaranteed to extend
fin. An application that does not want to stop with finality readsbc_bestor a confirmation prefixprune_k(bc_best). Those areΠ_bcviews, not CL2 quantities, and their security isΠ_bc's own Prefix Consistency. The Book's "Prefix Consistency ofba" theorem has no subject. A prefixprune_k(bc_best)can be an ancestor offineven when every assumption holds; the Book gives difficulty adjustment after a reorg as the reason, which is whyba_μhad its fallback. It can conflict withfinonly if Prefix Consistency atσhas failed:fin ⪯ prune_σ(χ^r)for some earlierr, so Prefix Consistency atσgivesfin ⪯ bc_best, and every prefix ofbc_bestis then comparable withfin. - The application choice changes. The Book framed it as
fin(stop immediately) versusba_μ(continue for at mostLblocks). Here it isfinversus abc_bestview that never stops and has no bound on how much can be rolled back tofin.
In the current tree, the collapse onto each decided block (§4.2) locally forces
canonical_finalized_tip ⪯ canonical_tip; in Zebra Crosslink, sticky fork choice (§4.3) keeps
fin ⪯ bc_best. Either restores, as a chain-selection policy, a prefix relation that ba_μ provided by
definition. Neither limits the finality gap, and both cost local liveness whenever the dominant
chain excludes the floor (§4.3).
3.4 Validity rules and honest production
In addition to inherited rules, the bc-block validity rules are:
- Valid context:
H.context_bftis bft-block-valid. - Extension:
LF(parent(H)) ⪯bft LF(H). - Last Final Snapshot:
snapshot(LF(H)) ⪯bc H.
The Book's fourth rule, Finality Depth, is omitted with Stalled Mode (§3.3).
The separately stated bft-proposal and bft-block validity rules add:
- Linearity:
snapshot(parent(B)) ⪯bc snapshot(B). - Tail Confirmation:
B.headers_bcform theσ-block tail of a bc-valid chain.
Zebra Crosslink enforces all five rules above, and so does the current tree (§6.2).
Tail Confirmation is objective: σ consecutive headers ending at a bc-valid block are the tail
of the chain that ends at that block, whatever the validator's own best chain. The Book
separately defines what an honest proposer puts in that field.
Honest proposal. An
honest proposer
of a bft-proposal P:
- sets
P.headers_bcto theσ-block tail of its ownbc_best, if that satisfies Linearity againstP's parent; - otherwise sets
P.headers_bcto its parent'sheaders_bc, repeating the parent's snapshot; and - makes no proposals until its
bc_bestis at leastσ + 1blocks long.
A proposal is therefore always possible once the chain is long enough. The Linearity rationale
depends on that:
liveness of the underlying BFT protocol can require honest proposers to propose at a minimum
rate. Honest proposal is a behavior, not a validity rule: a validator cannot tell whether the
carried tail was the proposer's best chain. An
honest validator
first downloads the bc-blocks for P.headers_bc and checks their bc-block validity.
Zebra Crosslink. A proposer clamps its candidate height to at most 40 blocks above the
previous final snapshot. When the clamp binds, P.headers_bc is a window of bc_best ending
below its tip rather than its tail, which breaks honest proposal. The clamp is a design
heuristic, not part of the Crosslink 2 specification. The window still satisfies Tail
Confirmation.
Linearity and bc reorganizations. Let B be the newest final bft-block. Linearity requires
every later final snapshot to extend snapshot(B). When a node's bc_best reorganizes onto a
branch that forks below snapshot(B), the tail of that branch fails Linearity, so honest
proposers repeat B.headers_bc. Last Final Snapshot admits a block H on that branch only if
snapshot(LF(H)) lies on the branch, so H cannot cite B or any later final bft-block, and
candidate(H) stays at or below the fork point. Finality for nodes on that branch resumes when
a chain containing snapshot(B) becomes their best chain again. Under honest proposal at every
bc-block, snapshot(B) sits about σ blocks below the proposer's tip, so a reorganization
slightly deeper than σ reaches this case.
Finality lag under honest production. This follows from the Book's honest proposal and
applies to Zebra Crosslink. A proposer at tip T carries headers T − σ + 1
through T, so the decided block's snapshot is T − σ. The first bc-block that can cite that
decision is T + 1, and only if its template was built after the decision arrived; then
candidate(T + 1) = T − σ. In steady state fin therefore trails the best tip by at least
σ + 1 blocks. Every bc-block built from a template that predates the latest decision cites an
older bft-block and adds one more block of lag, and a decision that takes longer than a bc-block
interval adds more.
The Book's informal safety argument uses Linearity and Last Final Snapshot as follows:
- Linearity with
Π_bftFinal Agreement makes the snapshots of final bft-blocks bc-linear, which the Book says implies Assured Finality without anyΠ_bcsafety assumption (lines 587–594). - Last Final Snapshot with the
σcarried headers is the basis of the other half of that sketch: each candidate final snapshot is aσ-confirmed prefix of the observer's best chain, soΠ_bcPrefix Agreement gives safety without anyΠ_bftassumption (same lines). - The two together remove the sanitization of ledgers that Snap-and-Chat and Crosslink 1
needed (potential changes, lines 320–371). That
section's security analysis starts from the observation that neither rule affects the
evolution of
Π_bcunless its Prefix Consistency or Prefix Agreement would be violated, and breaks off mid-sentence.
The Book's safety section is marked as not updated for Crosslink 2, and a later edit says Linearity so far contributes to security only heuristically. These arguments are sketches, not proofs.
Two facts used in §4.3 follow from the definitions:
candidate(H) ⪯ snapshot(LF(H))andcandidate(H) ⪯ prune_σ(H)hold for everyH, because an lca is an ancestor of both of its arguments.- With Last Final Snapshot,
snapshot(LF(H))andprune_σ(H)both lie onH, socandidate(H)is the lower of the two. Without it,snapshot(LF(H))can lie on another branch, andcandidate(H)is then the lower ofprune_σ(H)and the point where that branch leavesH.
Beyond satisfying validity rules, the explicit BFT-context selection procedure chooses
H.context_bft: among eligible bft-valid tips it chooses a longest chain, then breaks ties by
final-snapshot score and hash
(lines 705–716).
BFT-derived data therefore affects block validity as well as this selection procedure. With no
Finality Depth rule, the procedure is the only thing that makes a producer advance its
context (§3.3).
3.5 Prefix Consistency and client exposure
Prefix Consistency at depth σ is a property assumed of qualifying executions of the
best-chain protocol:
prune_σ(χ_i^t) ⪯ χ_j^u for honest observations at t ≤ u
It is not a Crosslink checkpoint rule and is not enforced by fin. If a later best chain
displaces an earlier σ-confirmed prefix, an argument that assumes Prefix Consistency no
longer applies to that execution.
The Book recommends baking in a BFT checkpoint and withholding fin from
clients
until the checkpoint precedes LF(bc_best), its snapshot precedes fin, and fin is recent.
This is a sync-safety recommendation, not a block-validity or consensus rule. The Book applies
it to fin and ba_μ; here it covers fin only, and says nothing about exposing bc_best.
Zebra Crosslink marks with an @Todo where the condition applies and does not implement it;
the current tree has neither.
4. Raw fork choice and finalized-prefix policy
4.1 What raw CL2 selects
Raw CL2 leaves the underlying rule in place: choose a highest-score bc-valid chain. In the
Zebra instantiation, score is accumulated PoW. Crosslink constrains individual blocks through
the validity rules carried by their own BFT context; it does not require raw bc_best to
contain the observer's current fin.
The evidence chain is:
- The generic best-chain model chooses a highest-score bc-valid chain (construction lines 245–260).
- The CL2 validity rules constrain a block relative to the BFT context that block carries (lines 686–693). A chain can retain an older, still-valid BFT context.
- Honest bc-block production says producers “must not use information from the BFT protocol” beyond the specified consensus rules when selecting a bc-valid chain (lines 705–716).
- The Questions chapter analyzes the stronger rule requiring
bc_bestto extend the latest final BFT snapshot in the node's view and says it breaks the current safety and liveness arguments (lines 11–26).
Its exact conclusion is:
“Probably not. I don’t know how to repair the safety and liveness arguments.”
The Questions page is partly historical. It
analyzes the Last Final Snapshot rule on its own and defers the
combination with Linearity to the potential-changes section, which says the Questions argument
against that rule
was made for a protocol without Linearity. The fork-choice
change and its "Probably not" belong to the same pre-Linearity discussion, and part of that
discussion
relies on the Finality Depth rule and Stalled Mode, which this
design omits. The Book does not revisit the fork-choice change with Linearity in place. The
reason it gives for its conclusion is that an analysis that treats Π_bft as possibly
subverted
can say nothing useful about snapshot(B).
The per-block rule and the fork-choice constraint remain distinct. A block can satisfy
snapshot(LF(H)) ⪯ H using stale BFT context; the fork-choice constraint would constrain the
selected best chain by the newest final BFT snapshot in the observer's view. §4.3 compares that
constraint with sticky fork choice.
4.2 The additional Zebra policy
A finalized-prefix eligibility rule would be:
eligible_i(C, t) := bc_valid(C) and local_finalized_tip_i^t ⪯ C
bc_best_i^t := highest_score({ C | eligible_i(C, t) })
This rule preserves the finalized prefix for each node that enforces it. It does not by itself prove global agreement, network progress, or Prefix Consistency for unfinalized blocks. If an enforcing node has no eligible progressing chain, local liveness must yield.
Current tree. The floor is fin, and the rule is sticky fork choice (§4.3): committing
fin discards the non-finalized branches that do not hold it, which makes the policy physical.
The CL2 construction does not mandate that.
Omitting Stalled Mode changes what the policy constrains. The Book pairs raw fork choice with
Stalled Mode, which confines a dominant unfinalizable branch to stalled blocks after L. Without
it, raw fork choice lets that branch carry ordinary spends without limit, all of them past fin
and unfinalizable under Linearity. A finalized-prefix policy keeps an enforcing node off such a
branch, at the cost of that node's liveness whenever the dominant chain excludes its finalized
point.
4.3 Sticky fork choice
Sticky fork choice is the fork-choice rule Zebra Crosslink implements. It selects bc_best so
that a node's best chain never excludes its own fin. It is temporal: the result depends on the node's current best chain and its
current fin, which is node-local memory (§3.2), not only on the set of chains in view.
A node holds current, its best chain, and fin. When a bc-valid chain new is in view, the
node switches from current to new iff:
fin ⪯ new
and ( work(new) > work(current)
or ( work(new) = work(current) and tip_hash(new) > tip_hash(current) ) )
After every change of best chain, fin is updated from candidate(bc_best) by the rule in
§3.2. Equal-work chains are ordered by tip hash, which is Zebra's existing tiebreak: Chain::cmp in
zebra-state/src/service/non_finalized_state/chain.rs orders equal-work chains by tip hash
bytes, and NonFinalizedState::best_chain takes the greatest. That doc comment records that the
Zcash protocol specification instead prefers the block received first.
Relation to §4.2. fin only ever advances to candidate(bc_best), and
candidate(bc_best) ⪯ bc_best, so the current chain always contains fin. A chain that contains
fin now also contained every earlier fin, so it was eligible when it appeared and would have
been switched to then if it were greater. The pairwise switch condition therefore selects the
greatest chain, by work and then tip hash, among the chains that contain fin. That is the
eligibility rule of §4.2 with local_finalized_tip := fin. The temporal behavior comes
entirely from fin: the eligible set shrinks each time fin advances.
Relation to the Book's fork-choice discussion
The nearest relative of sticky fork choice in the Book is the fork-choice change on the
Questions page (§4.1): bc_best must extend snapshot(B) for the newest final bft-block B
in the node's view. The two rules differ in their floor:
- The Questions rule uses
snapshot(B). That point need not lie on any chain the node has selected, nor beσ-confirmed in one. - Sticky fork choice uses
fin. It advances only tocandidate(bc_best), a point on the node's own best chain at or belowprune_σ(bc_best).
Under Π_bft Final Agreement and Linearity, fin ⪯ snapshot(B): fin is at or below the
snapshot of some final bft-block (§3.4), and the snapshots of final bft-blocks are bc-linear.
Every chain containing snapshot(B) then contains fin, so sticky fork choice refuses a subset
of the chains the Questions rule refuses. Without Linearity the two floors can conflict, and
neither set of refused chains contains the other.
If the Last Final Snapshot rule holds as well, every chain that sticky fork choice refuses ends
in a block whose last final bft-block is strictly older than the one from which fin was last
advanced. Suppose fin was advanced from a chain with last final bft-block F, so
fin ⪯ snapshot(F). A chain new with F ⪯bft LF(new) has snapshot(F) ⪯ snapshot(LF(new))
by Linearity, and snapshot(LF(new)) ⪯ new by Last Final Snapshot, so new contains fin. The
refused chains are therefore stale-context chains, as in the adversary strategy the Questions
page describes.
The Book makes three statements that bear on a change of this kind:
- The honest-production instruction excludes using
Π_bftinformation beyond the consensus rules to choose among bc-valid chains (§4.1, item 3). Sticky fork choice usesfin. - The liveness analysis
attributes its tractability to leaving
Π_bcfork choice unmodified, in contrast with Casper FFG, whose fork choice follows the justified checkpoint. Under sticky fork choice a node never switches to a chain with less work, and an advance offinnever causes a switch, becausefinadvances only along the current chain. A node can instead refuse a switch. The Book has no liveness argument for that. - The reason given for "Probably not" is that nothing useful can be said about
snapshot(B)onceΠ_bftmay be subverted. Under sticky fork choice a subvertedΠ_bftstill cannot placefinoff the node's best chain or aboveprune_σ(bc_best). It can choose when to finalize: aσ-confirmed prefix finalized before a Prefix Consistency failure would displace it is the branch the node keeps. The Book has no safety argument for that either.
Properties
These follow from the definitions of candidate and fin (§3.1, §3.2) and the switch
condition, and hold in Zebra Crosslink. The current tree does not compute fin (§6.1).
fin ⪯ bc_bestholds on the node at all times. The raw-CL2 state in whichfinstays fixed on a branch thatbc_bestno longer contains (§4.1) does not arise.- The conflicting-candidate case of the §3.2 update cannot occur:
candidate(bc_best)andfinboth lie onbc_best, so they are comparable. The §3.2 hazard record is therefore never written. Its observable counterpart is a refused switch, meaning a chain in view with more work thancurrentthat excludesfin. - The rule selects a different chain from raw work-based fork choice only when a chain with
more work than
currentexcludesfin. By the Local fin-depth lemma (§3.2),finwas part ofprune_σof this node's best chain at some earlier time. The raw choice in that situation would displace a prefix that wasσ-confirmed in the node's own earlier best chain. Where no such chain is in view, the two rules select the same chain. candidate(H) ⪯ prune_σ(H)for everyH, because an lca is an ancestor of both of its arguments.Π_bftcan therefore movefinonly to blocks the node had already selected by work andσ-confirmed; it cannot move the node onto a chain it did not select. WhileΠ_bftis stalled or withholding,finis frozen and selection above it is the raw work rule.- The node never switches to a chain with less work than
current.
Behavior by situation
Each case compares sticky fork choice with raw work-based fork choice. Statements under
With Linearity assume Π_bft Final Agreement and enforcement of the Linearity rule, as the
abstract outcome in FINALITY_DIAGRAM §4 does; Zebra Crosslink enforces Linearity, so they
describe it. Statements under Without Linearity show what the rule prevents.
- Candidate regression with
finstill on the heavier chain (FINALITY_DIAGRAM §3). Both rules switch to the heavier chain. - Heavier chain forked below
fin(FINALITY_DIAGRAM §4). Under raw fork choice the node follows the heavier chain andfinstays behind on the other branch. Under sticky fork choice the node stays on the branch containingfin, and its tip advances only as fast as hash rate on that branch extends it. No amount of work on the other branch changes this; only a change tofinfrom outside the protocol would.- With Linearity: no final snapshot can move onto the heavier branch past the branch point.
Under raw fork choice the node's
finstays frozen while that branch is its best chain. Under sticky fork choicefincan keep advancing ifΠ_bftfinalizes the branch the node holds. - Without Linearity:
Π_bftcan finalize snapshots on the heavier branch. Under raw fork choicecandidate(bc_best)then conflicts withfin, the node records the §3.2 hazard, andfinstays frozen. Under sticky fork choicecandidate(bc_best)is at or below the branch point, sofinfreezes without a hazard record; the event is visible only as the refused switch.
- With Linearity: no final snapshot can move onto the heavier branch past the branch point.
Under raw fork choice the node's
- Partition while
finis frozen on every node. Every chain extending the commonfinis eligible, so selection is by work on both sides. After the partition heals, nodes converge on the heavier chain under either rule, provided no node'sfinmoved past the fork point. - Partition in which one side advances
fin. Side A holds enough stake forΠ_bftto decide and advancesfinpast the fork point; side B does not. After the partition heals, A-side nodes never switch to B's chain, whatever its work. B-side nodes switch to A's chain once it has more work than theirs, since it contains theirfin. While B's branch has more work, the nodes stay split along the partition. B's blocks cannot advance B-sidefinpast the fork point using A's decisions: with Last Final Snapshot they cannot carry that context, and without it their candidate is clamped to the fork point. How often this arises, and how many nodes land on each side, depends on how stake and hash rate are distributed across the partition. Under raw fork choice all nodes follow the heavier branch.- With Linearity: later final snapshots stay on A's branch, so B-side
finnever passes the fork point and B-side nodes can always still switch to A. Under raw fork choice, if B is heavier, finality stays stalled until B's branch is abandoned. A partition lasting more thanMAX_BLOCK_REORG_HEIGHTblocks puts the fork point below the B-side depth commit, which is the case the second finalized state of the implementation below exists to serve: the B-side node records both branches and switches without an operator. - Without Linearity: if
Π_bftlater finalizes a snapshot on B's branch, B-side nodes advancefinpast the fork point on B. From then on neither side switches, whatever the work, and neither records a hazard, because each side's candidate from the other branch is clamped below its ownfin. Under raw fork choice every node follows the heavier branch, and nodes whosefinlies on the other branch record the hazard once the candidate passes the branch point.
- With Linearity: later final snapshots stay on A's branch, so B-side
- Order of observation. Suppose a lighter branch carries final snapshots past the fork point
and a heavier branch does not. A node that processes the lighter branch first, for example
during sync, advances
fininto it and then refuses the heavier branch. A node that processes the heavier branch first keepsfinat or below the fork and does not switch to the lighter branch until it has more work. Under raw fork choice both nodes end on the heavier branch.- With Linearity: the premise persists: no later final snapshot can move onto the heavier branch past the fork point.
- Without Linearity: the heavier branch can later gain final snapshots past the fork point
as well. A node that processed it first then advances
fininto it, and the two nodes stay on different branches whatever the work.
- Conflicting finality. Each
finlies onprune_σof its own node's earlier best chain, so two conflictingfinvalues require those best chains to have diverged at depthσ, a Prefix Consistency failure. Under raw fork choice both nodes follow the heavier chain, and the node whosefinit excludes records the §3.2 hazard once the candidate passes the branch point. Under sticky fork choice each node keeps the branch containing its ownfin, whatever the work on the other, and neither records a hazard.- With Linearity: conflicting
finvalues also require a Final Agreement failure, because everyfinis at or below the snapshot of a final bft-block (§3.4) and those snapshots are bc-linear. - Without Linearity: conflicting
finvalues need no Final Agreement failure; the partition case above is an example.
- With Linearity: conflicting
Implementation in Zebra Crosslink
These are requirements; §5 describes the current tree. The rule is implemented through the finalized database rather than as a separate chain filter:
-
On every change of
bc_best, the node computesN := candidate(bc_best). Iffin ⪯ NandN ≠ fin, it finalizes up toNand storesNasfin. A candidate at or belowfinchanges nothing. The candidate computation and both writes belong to the code that changed the best chain, so they are one synchronous sequence rather than a request that can fail partway (§7.1). -
The commit discards every non-finalized chain that does not contain
N, and Zebra rejects blocks that fork below its finalized tip. Chains that excludefintherefore never enter the node's view, which is the switch condition above. That rejection is the refused switch; the node reports it on stdout, and a persisted hazard record is an@Todo. -
finis stored in the finalized database as its own block hash, so the floor survives a restart. The database's finalized tip is the higher offinand the reorg-depth commit (next bullet), so finality readers takefin, never the finalized tip. -
A BFT decision does not change the finalized state. It advances
bft_final_snapshot(§2), which can lie on a chain that is notbc_best. Only a laterbc_bestchange movesfin, and only by the rule above. -
The node syncs the chain leading to
bft_final_snapshotwhether or not it isbc_best, and it never needs a resync to do so. While that chain forks above the depth-committed block it is a chain of the non-finalized state, exempt from the pruning that drops the lowest-work chains pastMAX_NON_FINALIZED_CHAIN_FORKS, and it survives a restart through the non-finalized backup. Every chain carries its aggregated stakes per block, beside the per-blockbond_rewardsandfinalizer_commissionsit already unwinds, so the validator set at any held block is a lookup, on either side of a finalized tip (§7.3). Under Linearity that chain containsfin, so it remains eligible, and the node switches to it once it has more work. Bc-block validity, bft-block validity and roster computation are therefore one synchronous domain inzebra-state(§7.1). -
Zebra also commits the root of the best chain to the finalized database once the chain is longer than
MAX_BLOCK_REORG_HEIGHT(fromzcash_protocol::consensus, applied inzebra-state/src/service/write.rs). The value in the current tree is 99. Upstream Zebra raised it to 999, and that change was lost when this tree was rebased onto new Zebra, so 999 is the intended value; the depths of 99 written elsewhere in this document follow the tree. Chains forking below that point are no longer in view of that database. On a Zebra node the effective floor is the higher offinand that depth-committed block.The depth commit is never held back indefinitely. A node whose BFT has stalled, for any length of time or forever, keeps committing its PoW best chain and remains a working PoW node with a frozen
fin. Ifbc_bestthen runs more than that depth past the point where the chain tobft_final_snapshotforks from it, the depth commit writes a block that conflicts withbft_final_snapshot, and one finalized database cannot be rewound to take the other branch. The node must nevertheless keep syncing and recording both branches for as long as both grow, validating bft-blocks and computing rosters along the BFT branch, and switch its served best chain to that branch when the rule above says to. That is a second finalized state:- The PoW state P is today's Zebra: raw work fork choice and the depth commit. Its
finalized state keeps, at a height at or below
fin, a snapshot of itself from which an independent, writable copy can be opened while P keeps writing. The snapshot is retaken asfinadvances, and during a stall it stays valid, only staler. Every chain containingfinforks at or above it. - When a bc-block arrives that forks below P's finalized tip but above
fin, the node opens the Crosslink state C from that snapshot, replays P's own stored blocks from the snapshot height to the fork point into it, and from there feeds C the conflicting chain from peers. C's fork-choice floor isbft_final_snapshotand C never depth-commits. Both states keep syncing and committing; the served best chain is chosen across both by the switch rule above. C is dropped oncefinpasses the fork, and P's branch is recorded for as long as blocks arrive on it. - How the snapshot is taken belongs to the storage engine, and it sets the cost of a conflict
rather than whether the node survives one: a hard-linked checkpoint or a filesystem reflink
clone is milliseconds, a persistent savepoint plus a file clone needs P's writer paused for
the copy, and a logical copy into a fresh database costs a full database of time and disk.
The last is the portable floor and is acceptable, because what it pays for is a network
partition deeper than
MAX_BLOCK_REORG_HEIGHT.
Until the second state exists, the node holds P's depth commit at the fork point while a conflict is live, up to
CONFLICT_HOLD_DEPTHblocks past the fork, then commits and reports on stdout that it can no longer followbft_final_snapshot; that path carries an@Todonaming the second state. The hold is an interim and never the design, because under a permanent conflict it is the same wallCONFLICT_HOLD_DEPTHblocks later. A node never requires a resync to resume bft-block validation. - The PoW state P is today's Zebra: raw work fork choice and the depth commit. Its
finalized state keeps, at a height at or below
Sticky fork choice and Linearity constrain different points. Sticky fork choice keeps fin on
bc_best; Linearity keeps each final snapshot on or after the previous one. fin lies at or
below the newest final snapshot, so a reorganization that forks between the two is admitted by
sticky fork choice and then leaves finality on the new branch waiting (§3.4, Linearity and bc
reorganizations).
Current tree
- The rule needs protocol
fin, which the current tree does not compute (§6.1). Its collapse onto a BFT-decided branch (§4.2, §6.3) is a related rule with a different floor: the stored marker, taken directly from a decided BFT block when it is decided rather than fromcandidate(bc_best). With that floor, the invariant above does not follow: the marker need not lie on the node's best chain when it advances, and a known side-chain hash becomes canonical (§5.2). - It enforces Linearity and Last Final Snapshot (§6.2).
5. Current tree: implementation inventory
Everything in this section describes the current tree, not requirements. It refers to symbols in the tree this document ships with; symbol names are preferred over brittle working tree line numbers.
5.1 The two finality markers and their write paths
zebra-crosslink/zebra-state/src/new_network/fin.rs holds fin, the block this node has
finalized. It is a cache of the single row of the crosslink_fin column family, loaded by
fin::load at startup and advanced only by fin::advance, which runs on the sync thread that
owns the block writer, so the marker has exactly one writer. fin::candidate computes
candidate(bc_best), and WriteBlockWorkerTask::crosslink_update_fin applies the §3.2 rule
where a commit changes the best chain.
zebra-crosslink/zebra-state/src/new_network/bft.rs holds the other marker,
BftChain::bft_final_snapshot: the snapshot of the last decided bft-block, which is what
Π_bft has finalized rather than what this node has (§3.2). BftRunner::decide assigns it, and
BftRunner::restore replays it from the stored chain. Its readers are the BFT proposal path,
the +40 clamp, the reorg-depth conflict hold, and the non-finalized pruning exemption — all
inside zebra-state, because a block it names is not final for this node until fin reaches
it (§2).
Both markers take snapshot(new_block) = parent(new_block.headers[0]) from
BftBlock::snapshot_block_hash, the one accessor through which every reader derives the
finalized block (§8.1).
When fin is absent, the finality RPCs return None. They previously substituted a Zebra
reorg-depth location derived from the state block locator, so that the API changed semantics
depending on whether Crosslink had produced a value; that substitution and its helper have been
removed. Removing it was safe because the substitution reached only the RPC-facing readers of
the marker: the finalized-tip, block-status and transaction-status answers. Every consensus-,
state-, and GUI-side reader takes fin directly and never saw the substituted value.
The Crosslink service no longer carries a second copy of the marker: current_bc_final, which
was written during startup restore and read nowhere, has been deleted.
5.2 Irreversible commitment and ordering
BftRunner::decide assigns bft_final_snapshot and stores the decision. It commits nothing:
the finalized state follows fin, which WriteBlockWorkerTask::handle_commit advances where
the best chain changes. Tenderlink therefore no longer waits on a finalized-state write to
start the next round, and no reader can observe a fin whose block is not committed, because
fin::advance runs after handle_crosslink_finalize returns and writes the row before it
publishes.
The state behavior depends on whether the hash is known:
new_networkaccepts a hash found in any non-finalized chain or in the finalized database.NonFinalizedState::crosslink_finalizeretains the chain containing a known side-chain hash, butcrosslink_update_finpasses it only a hash already on the best chain, so finalizing no longer makes a branch canonical.- a hash the state does not know never reaches the finalize call:
candidateanswersNonewhile the snapshot is a block this node does not hold, and the bft-block naming it is refused byvalidatefor the same reason. - the restore path makes a
KnownBlocklookup for the last decided BFT block. The decided chain and the blocks it finalizes are rows of one database, written together, so a database that cannot resolve that block is damaged rather than merely behind: restore says so and ends the process instead of panicking. The replay-watermark loop just above it tolerates the case.
The stored fin row is therefore both a fin implementation and a lower bound on the finalized
database's tip: it is written only after the commit it names has succeeded, so a crash leaves it
at or below that tip and never naming a block the database lacks.
5.3 Consumers
fin reaches:
- the
get_tfl_final_block_*, block-finality and transaction-finality RPC methods, through theCrosslinkFinalizedTip,CrosslinkBlockFinalityandCrosslinkTxFinalityread requests; - the GUI's finalized row and its visualization paging lower bound; and
- the notification subscribers of
fin::fin_change_rx, reached throughCrosslinkFinalizedTipChange.
bft_final_snapshot reaches irreversible state commitment only indirectly, through the conflict
hold that delays it (§4.3). Its other readers are the BFT proposal path's +40 clamp, the
pruning exemption, and the GUI's terminated-finalizer display, which passes it to
terminated_finalizers_at as the finalized bc-height so that the display and the consensus
roster share one derivation.
BftChain::roster is a write target, populated from the aggregated stakes at the decided
snapshot: the chain holding that block answers if it is still non-finalized, and the finalized
database answers otherwise (§8.1). That read is the node's own and is separate from any commit.
fin::fin_change_rx is a tokio::sync::watch, published beside the chain-tip channels and
handed out by the CrosslinkFinalizedTipChange read request; the RPC notification methods in
zebra-crosslink/zebra-rpc/src/methods.rs wait on it. Every fin::advance publishes on that
channel after the database row is written, so a notification names a block this node has already
committed. A watch rather than a broadcast: fin is monotone, so a subscriber that fell behind
wants the latest value and nothing else.
5.4 Current staking rewards
At the end of Chain::push in
zebra-crosslink/zebra-state/src/service/non_finalized_state/chain.rs:
- a block that does not pay (see the payout rule below) pushes empty
bond_rewardsandfinalizer_commissionsentries and mints nothing; the empty entries keep positional reorg reversal aligned; - if no bond is active, the same empty entries are pushed and no staking reward is minted; and
- otherwise it distributes the fixed
POS_BLOCK_REWARD_ZATSfor that PoW block, increasesstaking_bonded_amountby the same total, and records the per-bond rewards for exact reorg reversal.
update_bonds_with_pos_issuance in zebra-crosslink/zebra-state/src/service.rs allocates the
total pro rata with integer division, gives the remainder to the largest active bond (then
smallest key on a tie), and adds rewards to bond principal. Rewards therefore compound.
The variable payout rule
Issuance is not paid per PoW block. A block P pays exactly when it advances finality and
does so promptly:
payout(P) iff cert(P) != cert(parent(P)) and height(P) - F <= σ + FINALITY_LIVENESS_ALLOWANCE
where cert(P) is the BFT block named by P.context_bft (compared by BFT block hash, not by
the whole fat pointer: two honest nodes can carry different signature sets for the same
decision) and F is the height of the PoW block that certificate finalizes — its snapshot.
FINALITY_LIVENESS_ALLOWANCE = 3, in librustzcash/zcash_primitives/src/bft.rs.
Both inputs are objective functions of committed chain data, so every node computes the same
answer for the same block, as §9.1 requires. The fat-pointer check (§6.2) already refuses any
P below F + σ + 1, so height(P) − F is at least σ + 1: with σ = 4 the paying gaps are 5,
6 and 7, i.e. 4, 5 or 6 blocks strictly between F and P, and a seventh earns nothing.
The decision is made in new_network::bft::admit_fat_pointer
(zebra-crosslink/zebra-state/src/new_network/bft.rs), which is the one place that can resolve both
facts, and travels with the block as SemanticallyVerifiedBlock::pos_payout →
ContextuallyVerifiedBlock::pos_payout → Chain::push. Paths that never run that check
(checkpoint sync, tests, blocks rebuilt from raw bytes) carry pos_payout: false and mint
nothing.
Because the verdict cannot be recovered from the block bytes, it is persisted in the
non-finalized state backup alongside the deferred pool change
(zebra-state/src/service/non_finalized_state/backup.rs), and restored with the block. Without
that, a node that restarts re-enters its non-finalized blocks through
SemanticallyVerifiedBlock::from(Arc<Block>), which defaults to pos_payout: false: the
restarted node mints nothing for blocks every other node has already paid. That is not a local
accounting slip. It changes the bonded stake, the bonded stake is the voting power, and the
roster derived from it then differs between nodes — which in a two-node roster is enough to
make both nodes believe they are the proposer, prevote different values forever and stall
finality permanently. This was observed on a dilated two-node testnet: node two restarted,
restored 4 backed-up blocks, and came back exactly 4 × POS_BLOCK_REWARD_ZATS short, after
which BFT never decided another block.
The same per-block calculation is replayed by the wallet projection path in
zebra-crosslink/zebra-crosslink/src/lib.rs, which recomputes the rule from committed data in
block_pays_pos_issuance, and by fixup_aggregated_stakes in
zebra-crosslink/zebra-state/src/service/stake_fixup.rs (reached through the --fixup-db-stake
entry point). Any future consensus change must keep all three paths identical.
The repair tool is the one path that cannot evaluate the rule in full: it has the PoW database
and nothing else, and F lives inside the BFT block. It applies the half it can see — a block
that does not advance the certificate pays nothing — and assumes an advancing block was
prompt. That is correct whenever BFT kept up. When it did not, the replay disagrees with the
rows already stored and its existing cross-check refuses to write anything, so the failure mode
is a repair that declines, never a repair that corrupts.
5.5 The Crosslink service crate
The decided bft-chain, the tenderlink engine and every reader of them live in zebra-state,
in zebra-crosslink/zebra-state/src/new_network/bft.rs. What is left of
zebra-crosslink/zebra-crosslink is about 1,000 lines in four files: lib.rs, holding the
service and the wallet, faucet and staking arms; service.rs, which constructs it; viz2.rs,
the GUI feed; and test_format.rs, the .zeccltf test driver. It exposes a tower Service
over TFLServiceRequest whose handlers take a tokio Mutex on TFLServiceInternal, which now
holds only the BFT message and error counters and the two BFT connection strings.
tfl_service_main_loop starts the visualizer and the test driver and then sleeps, because
zebrad treats the service task's exit as a node shutdown.
Nothing on a consensus path calls that service, and nothing calls into it from zebra-state.
Its callers outside the crate are zebra-crosslink/zebra-rpc/src/methods.rs — the staking,
wallet and faucet commands — and one site in zebra-crosslink/zebrad/src/lightwalletd.rs, which
asks for Faucet. No finality answer reaches it. The roster, the block template's fat pointer,
the recency status, activation, and every finality answer are ReadStateService requests
(CrosslinkRoster, CrosslinkFatPointerToBftChainTip, CrosslinkRecencyStatus,
CrosslinkIsActivated, CrosslinkFinalizedTip, CrosslinkFinalizedTipChange,
CrosslinkBlockFinality, CrosslinkTxFinality).
BftChain in new_network::bft is the decided bft-chain: blocks and hash_to_height,
fat_pointer_to_tip, roster — the validator set read at the snapshot of the previous decided
bft-block — bft_final_snapshot, the marker of §5.1, and is_activated. It
sits behind one RwLock; the new_network::sync thread is its only writer, and every reader
outside that thread takes the read lock without an asynchronous call. Recency status is a
tokio::sync::watch the bft_access closure publishes.
BftRunner, owned by the sync loop, holds the tenderlink side. The five closures of
tenderlink::entry_point each send one BftRequest and await one reply; the loop drains that
channel where it used to sleep, so propose, validate and decide run on the thread that
holds the best chain, the non-finalized state, the finalized database and the commit path. A
decision commits nothing, so nothing on that path can reject one or hold up the round (§5.2).
admit_fat_pointer answers the Extension, Last Final Snapshot and σ-confirmation verdicts and
the pos_payout flag (§5.4, §6.2) as a pure function of the BftChain and a ReadStateService,
called under the read lock from the retain loop that filters blocks about to be committed.
The decided bft-chain is persisted in the finalized database, in three column families keyed by
BFT height: bft_block_by_height, bft_fat_pointer_by_height and bft_proposal_sigs_by_height.
BftRunner::finish_decision writes all three in one batch once the decision's snapshot has
committed, so a crash in between leaves the chain one height short and that height is decided
again on the next run. BftRunner::restore reads them back at startup to rebuild the chain and
tenderlink's ingest_startup_data, recomputing each height's roster from the bonds at its
snapshot and the watermark prev_finalized_bc_height from the same lookup. A database past the
activation height holding no decided chain, or a decided chain whose snapshot the database does
not hold, ends the process with a message rather than being migrated or re-bootstrapped (§5.2).
force_feed_bft_block injects a decided bft-block without Π_bft, as a message to the sync
thread. Its only caller is test_format.rs, through TFLServiceCalls::force_feed_pos.
fin::block_finality answers block status inside one read request, against fin and the best
chain taken from the same state snapshot, so the answer cannot straddle a reorganization. A
block the node does not hold is not in its best chain, which is the answer it gives for one.
6. Current tree: divergences from Zebra Crosslink
Each item states a current-tree fact and, where it is not evident, the Zebra Crosslink behavior it departs from.
6.1 Derivation and update trigger
- Header order is enforced by validation, not by the type. Honest proposal construction issues
FindBlockHeaderswith the snapshot block as the sole known hash. That request returns the headers following the intersection, ascending, so the proposal carries theσblocks above the snapshot, deepest-first, andparent(headers[0])is the snapshot.σheaders suffice, becauseheaders[0]carries the snapshot's hash in its parent field, and a validator must hold the snapshot block to validate the certificate anyway.BftRunner::validateenforces that order as part of Tail Confirmation, rejecting a block whose headers do not each name the one below as parent (§6.2). The type does not:BftBlock::try_fromchecks only the header count and logs that its documented validations are unimplemented, and the deserialization path used for network and stored blocks does not calltry_fromat all. The snapshot is named by hash only; a consumer that needs its height asks the chain, and the fat-pointer check is handed a height lookup for that purpose (§6.2). - The candidate height is clamped, and the clamp is not
prune_σ. The proposal path computestip − σand then takesmin(tip − σ, bft_final_snapshot + 40). Only when that clamp does not bind is the stored markerprune_σ(tip), i.e.σconfirmations. Whenevertip − σ > marker + 40, which is the normal regime during catch-up after a restart or a BFT stall, the candidate ismarker + 40and the block is finalized far deeper thanσ. Any statement of the form "the proposal path finalizes attip − σ" is true only in the unclamped regime. - The improvement test runs before the clamp.
is_improved_finalcompares the proposal's snapshot height,tip − σ, against the stored marker, so every new PoW block is proposable at once. The clamp can only lower the snapshot tomarker + 40, so it never turns an admitted proposal into a non-improving one. - Missing hazard record.
crosslink_update_finholdsfinwhere the candidate regresses, and refuses to move it onto a chain that does not hold it, but a refused switch is only reported on stdout: the safety incident of §3.2 is not distinguished from the benign regression in anything that survives a restart.
6.2 Validity rules
- The Last Final Snapshot rule is enforced on bc-block admission, beside the Extension rule in
new_network::bft::admit_fat_pointer, with the same defer/reject split: a snapshot the state cannot yet place on a branch defers, and one it places off the block's own ancestry is rejected permanently. Ancestry is read withReadStateService::is_ancestor_of, across every chain the state holds rather than the best chain alone. - The Finality Depth rule and Stalled Mode are omitted by design (§3.3). The 512-block log threshold is diagnostic, not consensus.
- BFT validation enforces Linearity and Tail Confirmation in
BftRunner::validate. Tail Confirmation is checked as the three things it is: exactlyσheaders, each naming the one below it, and the block at the topmost header known to this state — which, given the linkage, carries the bc-validity of the whole tail, since a block the state holds has been validated along with its ancestry. Linearity compares the parent bft-block's snapshot against this block's through the same ancestry read. A block either check cannot resolve yet returnsIndeterminatewith the hash it needs, as a missing snapshot already did. - The confirmation depth is enforced on inclusion. A PoW block at height
Pmay carry a fat pointer to a BFT block whose snapshot is at heightFonly whenP ≥ F + σ + 1: theσcarried headersF+1 ..= F+σ, then the carrier. Admitting a PoW block therefore requires a PoW → PoS → PoW lookup: resolve the pointer to its BFT block, take that block's snapshot hash, and ask the state for its height.new_network::bft::admit_fat_pointerresolves the pointer in the decided chain it holds and asks theReadStateServicebeside it for the height, searching every chain the state holds, and defers rather than rejects while the snapshot is unknown here. The block-template path applies the same test, so a miner is never handed a certificate that could not be committed. The inequality bounds depth only; whetherFis an ancestor ofPis the Last Final Snapshot rule, which the same read answers. - The proposal path departs from honest proposal (§3.4) in two ways. When the
+40candidate clamp in §6.1 binds,headers_bcis a window ending atmarker + 40 + σ, not the tail of the proposer'sbc_best; the window still satisfies Tail Confirmation. The clamp is a Zebra Crosslink design heuristic (§3.4). Where honest proposal repeats the parent'sheaders_bc, the path makes no proposal instead: whenis_improved_finalfails, when the candidate's snapshot would fail Linearity against the parent bft-block's, and when the tail the chain returns is short or does not link to the candidate. The two reads behind the tail run on the writer thread, so no commit falls between them. How often a node should repeat its parent's headers is an open implementation question, so declining is what it does until that is settled. - Bc-block production follows the honest context-selection procedure (§3.4) as far as validity
requires: the block template's
FatPointerToBFTChainTiprequest cites the newest decided bft-block whosedo_not_include_until_bc_heightadmits the proposed height, whose snapshot is deep enough for the σ-confirmation rule, and whose snapshot lies on the chain the template extends. It does not implement the Book's longest-chain-then-score-then-hash tie-break, which is a selection among bft-valid tips this tree does not hold: the decided chain is linear here. When no decided block qualifies, the template repeats the parent block's owncontext_bft, which always does; reverting to the null pointer would break the Extension rule. - Block templates lag BFT decisions. Time-accelerated and realtime tests show miners producing
two consecutive bc-blocks with the same fat pointer, each of which adds a block of finality
lag (§3.4). Any rule keyed to finalization at exactly
σ + 1below the tip misses those blocks. - The Extension rule is implemented by
new_network::bft::admit_fat_pointer, including its defer/reject distinction.
6.3 State-finalization and fork-choice policy
Committing up to fin leaves the non-finalized state holding only chains that contain it, so a
higher-score conflicting chain cannot become canonical. This locally enforces a finalized-prefix
activation policy; raw CL2 does not impose that rule. The test
crosslink_pow_follows_the_heaviest_chain_until_fin_moves_to_the_decided_branch documents the
behavior: a decision alone moves nothing, and the floor appears only once fin does.
Zebra Crosslink names separately:
- protocol
local_finalized_tip(fin), which under sticky fork choice is also the Zebra policy floorcanonical_finalized_tip(§2, §4.3); and - the finalized tip of the PoW state's database, the higher of
finand the reorg-depth commit; a second state opened for a conflicting BFT branch (§4.3) has its own.
6.4 Unbounded finality gap
Nothing in consensus bounds the finality gap or restricts which transactions a block far past the snapshot may carry. This follows from omitting Stalled Mode (§3.3). It has two practical consequences:
- The diagnostic warning at a hardcoded gap is the only signal of a long finalization stall. Any response to one, such as alerts, wallet warnings, or operator action, is outside consensus.
- A best chain that has forked below
fin(§3.5) can carry ordinary spending transactions for as long as it dominates. Under raw CL2 fork choice nothing limits that activity. Sticky fork choice keeps a node off such a branch (§4.3).
6.5 Client exposure and API semantics
There is no checkpoint/recency sync condition on client exposure. Before the Crosslink marker
exists, finality RPCs now report no value rather than silently exposing the legacy reorg-depth
fallback; get_tfl_final_block_hash and get_tfl_final_block_height_and_hash return null,
and the block- and transaction-finality methods collapse their error to null as well.
Existing GUI and RPC surfaces still conflate raw tip, confirmation, and finalization instead of
defining each endpoint's contract. What these methods return once the marker does exist is fin
itself.
6.6 Ordering and notification
- The visible marker advances, and the
finwatch channel's subscribers are notified, only after the commit it names has succeeded (§5.2). bft_final_snapshotadvances without any commit, and nothing outsidezebra-statereads it, so a decision is not visible as finality untilfinreaches it (§5.1).
6.7 Placement
Zebra Crosslink keeps finality state in zebra-state (§7.1). The decided bft-chain, the
tenderlink engine, the admission check, fin and the persisted chain are all there now
(§5.5); what remains of the placement divergence is smaller:
- The decided bft-chain is held in memory as well as in the database, and every reader takes the in-memory copy; the database is read only at startup (§5.5).
- The GUI reaches
finand the bft-chain as a crate-level import rather than through the state service, which is the move of §7.2.
7. Names and consumer contracts
This section is Zebra Crosslink. The protocol names encode their definitions:
| protocol quantity | value identifier | optional newtype |
|---|---|---|
bc_best | bc_best_tip | BcBestTip |
candidate(H) | finalization_candidate | FinalizationCandidate |
fin | local_finalized_tip | LocalFinalizedTip |
bft_final_snapshot | bft_final_snapshot | BftFinalSnapshot |
The database's finalized tip has a name distinct from fin (§6.3). The legacy reorg-depth
value keeps a name that says it is a reorg-depth marker, not Crosslink finality.
7.1 Where finality state lives
Finality state is chain state. The quantities of §2 are computed from blocks the node holds —
fin from its own history of them (§3.2) — and every consumer of one needs the bc-chain as it
stood at the same instant. Zebra Crosslink keeps all of it in zebra-state, beside the finalized
database and the non-finalized state, reachable without an asynchronous call:
finis a column of the finalized database, written in or after the batch that commits the block it names (§8.1).- The decided bft-chain — its blocks, their fat pointers, and the proposal signatures that accompany them — is stored the way bc-blocks are stored, in the same database.
LF(H),snapshot(LF(H)),candidate(H),bft_final_snapshotand the σ-confirmation test are computed from those two by the code that also holds the chains they are compared against.- The validator set is derived from bonds on the chain the decided bft-block names, by the same function that computes the finalized aggregate (§7.3).
Π_bft is not chain state. The tenderlink crate owns the vote rounds, the message transport,
and the rule that a height decides before the next one starts; none of that is a function of the
chain, and it stays where it is. It reaches its host through the arguments of
tenderlink::entry_point, which are the whole interface:
| argument | what the host answers with |
|---|---|
propose_closure | a bft-proposal built from the host's bc_best, or nothing (§3.4) |
validate_closure | a verdict on a proposed bft-block, or Indeterminate with the block it still needs |
push_block_closure | acceptance of a decision, answered with the roster and vote namespace for the next height |
peer_cmd_closure | the peer addresses of the current roster |
bft_access_closure | a copy of round state for display; it decides nothing |
Three of the five need the bc-chain: a proposal is the σ-block tail of bc_best, validation is
Tail Confirmation and Linearity against the chains the node holds, and the roster is the bonds
at a bc-block. The host side therefore belongs in zebra-state, which already depends on
tenderlink and already runs its transport (tenderlink::stp, tenderlink::native_sockets)
for bc-block propagation. Nothing sits between the two: a crate that relays between tenderlink
and zebra-state can only reintroduce the boundary that makes these quantities race.
The closures stay asynchronous, because tenderlink awaits them. What moves is the side of the
boundary the reads happen on: a closure sends one message to the block writer and awaits one
reply, and every chain read behind that reply is local and synchronous. There is no path back
out, so there is no lock ordering to respect (§6.7). Current tree: this is how the five
closures are built, in BftRunner.
Finality state is chain state, and there can be two chain states at once. When the depth commit
and bft_final_snapshot come to lie on different branches, the BFT branch is a second finalized
database plus non-finalized state of the same shape as the first, opened from a snapshot of the
first at or below fin (§4.3). zebra-state routes blocks and reads between the two and chooses
the served best chain across both. How that snapshot is taken belongs to the storage engine, not
to the protocol.
By fate. What the Crosslink service crate held is four kinds of thing, and only the first is irreducible. The moves marked "moved" are done (§5.5); the rest are ahead:
| current tree | fate |
|---|---|
tenderlink and its entry_point interface | unchanged; zebra-state constructs the five closures |
bft_blocks, bft_block_hash_to_height, fat_pointer_to_tip, finalizers_at_current_height | moved: BftChain in new_network::bft, still in memory rather than in the database |
latest_final_block | gone: split into BftChain::bft_final_snapshot and fin in new_network::fin, the latter with one writer, the §3.2 update rule and a database row (§5.1) |
propose_new_bft_block, BftRunner::validate, handle_new_decided_bft_block, call_from_state_to_crosslink_to_ask_about_fat_pointers | moved: BftRunner::{propose, validate, decide} and admit_fat_pointer, each reading one consistent view on the writer thread |
| the PoS store file | gone; its records are database rows keyed by BFT height, and the roster is recomputed from bonds rather than stored |
TFLServiceInternal, tfl_service_main_loop, TFLServiceHandle, the tower service over TFLServiceRequest, and the reentrancy constraint it imposes | the reentrancy constraint is gone; the rest die; every finality arm is answered by the state service or by a channel it publishes |
| the wallet, faucet and staking arms | survive as calls rather than as a service: they relay to the wallet crate and read no finality quantity |
viz2.rs | survives as a view over the state service and a published diagnostic snapshot, holding no state of its own; where it lives is a packaging question |
test_format.rs and force_feed_pos | survive as test support beside the tests they drive; injection is a message to the block writer |
Once the moves above are done, what remains holds no finality state and sits on no consensus path, so where it lives is a packaging question and not a finality one. The GUI feed is the largest such piece, and it is a view in the sense of the §7.2 table: it reads the state service and the published round-state snapshot, answers the renderer's requests from them, and is free to lag or to be absent without any consequence for consensus.
7.2 Consumer contracts
No protocol view lies between the best tip and the finalized tip, so no CL2 quantity is a default for "confirmed" presentation. Each consumer needs a contract:
| consumer or endpoint | value | contract or unresolved work |
|---|---|---|
| raw best-tip display | bc_best_tip | current fork-choice result |
| confirmed display | bc_best_tip at a stated confirmation depth | Π_bc confirmation only; can be an ancestor of local_finalized_tip, or conflict with it after a Prefix Consistency failure (§3.3); never present it as final |
| final display | local_finalized_tip | node-local monotone CL2 view |
get_tfl_final_block_hash and get_tfl_final_block_height_and_hash | local_finalized_tip | no value before the first fin; the exposure condition of §3.5 is an @Todo |
| block status | local_finalized_tip and bc_best_tip | Finalized if the block is an ancestor of or equal to local_finalized_tip; InBestChain { confirmations } if it is on bc_best above that; NotInBestChain otherwise, including unknown blocks |
| transaction status | status of the block containing it | the block status of its mined block under the same three states; a mempool transaction has no block status |
| finality-change notifications | local_finalized_tip transitions | sent after fin is persisted; the exposure condition of §3.5 is an @Todo |
| visualization paging | operational paging cursor | do not overload a finality value merely to bound a window |
| canonical state activation | fin | sticky fork choice floor (§4.3) |
| physical database status | database finalized tip | higher of fin and the reorg-depth commit, in the PoW state; a second state for a conflicting BFT branch has its own; never reported as Crosslink finality |
| staking rewards | objective per-block source | never use node-local fin; see §9.1 |
| validator roster and hardfork membership | bonds at snapshot(B_{H−1}) | objective; see below |
| block-template BFT context | newest qualifying decided bft-block | the σ-confirmation and Last Final Snapshot tests are the ones bc-block admission runs, so a template never carries a certificate its own chain would refuse (§6.2) |
| BFT round diagnostics | tenderlink round state | display only; a published snapshot, never an input to consensus |
| visualization feed | bc_best_tip, local_finalized_tip, the decided bft-chain, round diagnostics | a view: it holds no state and decides nothing |
| wallet, faucet and staking commands | none of the above | not finality; they relay to the wallet crate |
Every row is served by zebra-state: a read request against the finalized database and the
non-finalized state, or a watch channel published beside the existing chain-tip channels. No row
is served by a component that keeps its own copy of the value (§7.1). Block and transaction
status read fin and the best chain together, so they cannot report two different moments.
Current tree. Every row keyed on local_finalized_tip is served by a ReadStateService
request, except the GUI's, which still reaches fin as a crate-level import (§6.7). The
finality RPCs return no value while fin is unset. TFLBlockFinality carries no confirmation
count with its middle state, because the count would change the test format.
7.3 Consensus-sensitive roster and hardfork inputs
The validator roster, voting power, and hardfork-driven membership changes are
consensus-sensitive. They must not read node-local fin unless there is a proof that every
validator derives the same value at the same BFT height. Prefix compatibility between honest
fin values is insufficient.
The two quantities are separate:
- Canonical ledger state is selected by sticky fork choice with floor
fin(§4.3). - The validator set for BFT height
H(roster, voting power, and hardfork-driven membership) is read from the bonds atsnapshot(B_{H−1}), whereB_{H−1}is the decided bft-block at heightH − 1.Π_bftagreement fixesB_{H−1}, its snapshot is a function of itsheaders_bc, and the bonds at a bc-block are a function of that block's ancestry, so every validator that has those blocks derives the same set.terminated_finalizers_attakes the height of the same block.
snapshot(B_{H−1}) generally lies above fin, because candidate(H) ⪯ snapshot(LF(H)) and
fin advances only once a bc-block citing the bft-block is best. It need not lie on bc_best
at all, and can stay off it for any length of time (§2, §4.3). Its bonds are therefore read from
the chain leading to bft_final_snapshot, which the node syncs and stores independently of its
best chain: as a non-finalized chain carrying its aggregated stakes per block, or, once it forks
below the depth commit, as the second state of §4.3. The aggregate at a block is the same function
whichever side of a finalized tip the block is on, so a block committed later yields the
identical row. An honest validator has downloaded that chain while validating B_{H−1} (§3.4).
Validation on that chain is interdependent but well-founded. Validating bft-block B_H needs
the validator set from the bonds at snapshot(B_{H−1}) and the bc-blocks under B_H.headers_bc;
validating those bc-blocks needs the bft-blocks their fat pointers cite, all of which were
decided before them. Processing decisions in BFT height order, each after the bc-blocks up to its
headers, satisfies every dependency.
8. Implementation status and pitfalls
The ordered implementation work is in IMPLEMENTATION.md. This section
records the current-tree facts that work starts from.
Current tree. The final-block accessor returns only the stored Crosslink value and never
substitutes the legacy reorg-depth marker; tfl_reorg_final_block_height_hash and
tfl_final_block_height_hash_pre_locked no longer exist. Before Crosslink produces a value,
finality queries return None. There is no test harness for these RPC methods, so the absent
and present cases are covered at the ReadStateService request level, by
crosslink_finality_reads_before_and_after_the_first_decision; a JSON-RPC harness remains
separate work. fin::advance publishes every marker write on the fin watch channel, after
state commitment.
Current tree. fin is computed by candidate(bc_best), moved only where the best chain
changes, held where the candidate regresses, and persisted, so it is the CL2 quantity and
local_finalized_tip is an accurate name for it. Its readers reach it through the state service
(§7.2), except the GUI's (§6.7). What is left is the hazard record a refused switch should leave
(§6.1).
8.1 Implementation pitfalls
These are current-tree facts, and they hold for any change to how the marker is derived, stored, or consumed.
- The derivation has one accessor.
BftBlock::snapshot_block_hashis the only placeparent(headers[0])is computed.BftRunner::decide, the BFT validation path, the restore path and its replay watermarkprev_finalized_bc_height,test_format.rs, andviz2.rs(both the live viz response andVizScene) read it, and the finality-diagram tests inzebrad/tests/crosslink.rsandviz2::scene_testsassert marker positions derived from it. A second derivation makes the node, the GUI, and the tests disagree about which block is final. - The roster is a function of a block, not of committing it.
BftChain::rosteris filled fromFinalizedState::db::aggregated_stakesatsnapshot(B_{H−1}), on the decide path and on the restore path alike, andterminated_finalizers_attakes that same block's height. Nothing reads stakes from the reply tohandle_crosslink_finalize, which returns the hash alone, so the roster does not depend on a decision and a commit being one event. The read answers on either side of the finalized tip:Chaincarries the aggregate per block, appended byChain::pushbesidebond_rewardsandfinalizer_commissionsand popped with them, from the same functionprepare_aggregated_stakes_batchuses, so a block held only in the non-finalized state yields the row the database will hold once it commits. A block on no chain the node holds is the case the second state of §4.3 removes. - The BFT genesis snapshot is below the bootstrap roster height. Bootstrap genesis
carries headers starting at
BOOTSTRAP_ROSTER_HEIGHT, so its snapshot, and the roster for BFT height 1, is the block below that height. - A derivation change is a network-wide consensus change. Nodes running two derivations
disagree on the finalized block and on the roster. Databases written under the old derivation
are deleted, not migrated. A stored decision holds the
BftBlock, the fat pointer and the proposal signatures; restore recomputes both the roster and the replay watermarkprev_finalized_bc_heightfrom each stored block's snapshot, so an old database loaded by new code yields rosters that disagree with the stored votes, which travel by roster index. finmoves only forward.candidate(bc_best)falls belowfinafter a benign reorg (§3.2), andWriteBlockWorkerTask::handle_crosslink_finalizereturns success for a hash the database already holds, so a caller that stored whatever it committed would movefinbackwards. Thefin ⪯ Ncheck is at the caller, incrosslink_update_fin;fin::advanceaborts on a regression rather than recording one.finis written no earlier than its commit. A persistedfinabove the finalized tip can name a block that was only in non-finalized state, which does not survive a restart. Writingfinin the commit's batch, or after it, keepsfinat or below the finalized tip.- The database finalized tip is not
fin. PastMAX_BLOCK_REORG_HEIGHTof lag it is the reorg-depth commit. RPC, GUI, and notification readers take the persistedfin. - Last Final Snapshot constrains block templates. A template must cite a bft-block whose snapshot lies on the template's parent chain, or the mined block is invalid (§6.2).
- Tail Confirmation needs the whole tail. Validation checks all
σcarried headers and the bc-validity of their blocks, which a validator may first have to download (§3.4). - A
σwindow is a chain, and its top must be present. Enforcing Tail Confirmation invalidated two fixtures incrosslink_test_basic_finalitythat predate it: a window taken as a slice of a block list that holds a fork carried two siblings rather than a chain, and the last window's topmost header named a block the test never loaded, which now defers withNeedsBlockinstead of validating. Any test that builds a certificate from a slice has to take its blocks from one branch and load the block at the top of the window. - Reward logic has three copies.
Chain::pushwithupdate_bonds_with_pos_issuance,fixup_aggregated_stakesinstake_fixup.rs, and the wallet projection inlib.rsmust change together (§5.4). - Header order is a property of the honest producer.
BftBlock::try_fromchecks only the header count, and the network and stored-block deserialization path does not call it. Code that readsheaders[0]as the deepest header relies on the producer, not on validation. NonFinalizedStateholds less than the finalized chain needs. It lives in memory, it drops the lowest-work chain pastMAX_NON_FINALIZED_CHAIN_FORKS(10), and it drops chains that do not contain the finalized tip, including those forking below a reorg-depth commit. The chain tobft_final_snapshotmust survive all three. Its BFT decisions are database rows beside the bc-chain (§7.1); the chain holdingbft_final_snapshotis exempt from the lowest-work pruning and is restored by the non-finalized backup; and a fork below the depth commit is the second state of §4.3, never a reason to stop following the chain.- A conflict below the depth commit is a second database, not a resync. The Wall of Death
(
410d99ed) was this failure with no conflict in it: a decision's snapshot lay on the committed chain, deep, and the roster could not be read there, so a node that had mined past it could never resume BFT. Storing aggregated stakes per committed block fixed that, and the resyncs it had forced on feature-testnet operators are what the fix existed to end. The conflict case is the same failure one branch over, and the same answer applies: the node recovers from what it already holds, without an operator. - Switching to the BFT branch can be a reorganization deeper than
MAX_BLOCK_REORG_HEIGHT. The wallet'sREWIND_DISTANCEandCHECKPOINTS_Nderive from that constant, so a client of a node that can switch to a second state needs checkpoints back tofin. - A switch onto the finalized chain replaces bond state. Bonds tracked along that chain while
it was a side chain must agree with what the chain produces once it becomes
bc_best; one implementation of the bond update serves both (§5.4). - The decided bft-chain is stored in the finalized database, without its roster. The rows carry the block, the fat pointer and the proposal signatures; restore recomputes each height's roster from the bonds at that height's snapshot. Storing the roster instead would be the second derivation the first bullet of this list warns against: a roster that disagreed with the stored votes would re-index every one of them through seats that never voted (§5.5).
MAX_BLOCK_REORG_HEIGHTis asserted against the bootstrap gap.ZcashCrosslinkParameters::bootstrap_is_validrequiresactivation_height − roster_height > MAX_BLOCK_REORG_HEIGHT, and aconst _: () = assert!onPROTOTYPE_PARAMETERSchecks it while compiling. The prototype gap is 200 blocks, so raising the constant past that stops the workspace building until the bootstrap heights move with it.- Aborts kill the node. The build uses
panic=abort. The decide path unwrapsblock_height_from_hashon the decided header, so a decided block whose header is unknown to state terminates the process, as does everyassert!on that path. finis a time series, not a function of the tip (§3.2). Recomputing it fromcandidate(bc_best)after a restart reproduces only the current candidate, which is whyfinis persisted.- Zebra's depth commit is a second floor, per state. Blocks deeper than
MAX_BLOCK_REORG_HEIGHTon the best chain are written to the PoW state's finalized database regardless offin(§4.3, Implementation in Zebra), and a fork-choice rule abovefinoperates only within that window in one database. A second state is what lets the rule reach past it; holding the commit back is not, because the hold has to end. - The
+40candidate clamp breaks honest proposal (§6.2). It stays, as a design heuristic outside the specification (§3.4). With it, one bft-block's snapshot advances by at most 40 bc-blocks; the commit, the roster lookup, andterminated_finalizers_athandle steps of any size regardless. - Block status never reports
bft_final_snapshotas finalized. A block at or belowbft_final_snapshotbut abovelocal_finalized_tipisInBestChainorNotInBestChain, becausefinis the view Assured Finality covers (§2). σcomes fromZcashCrosslinkParameters. The GUI'sapply_viz_ophardcodes it asTMP_SIGMA, which matches only whilePROTOTYPE_PARAMETERSis unchanged.- Last Final Snapshot is testable only because deciding no longer commits. A violation needs
a block whose ancestry omits the snapshot of the bft-block it cites, which needs that snapshot
to survive on a branch the block is not on. While the decide path committed every snapshot as
it was decided, the state collapsed onto that branch and refused forks below it, so such a
block was refused for the wrong reason before it could be offered. The test is
crosslink_reject_pow_block_citing_a_snapshot_off_its_own_chain. The rule is what makes the σ carried headers confirmations of the admitting chain. Linearity and Tail Confirmation are tested, incrosslink_reject_pos_block_that_regresses_the_snapshot,crosslink_reject_pos_block_with_lt_sigma_headersandcrosslink_reject_pos_block_with_unlinked_headers. - Crosslink node tests and
viz_gui. Tests run throughphest.bat zebra-crosslink, andphargo.batenablesviz_guifor that project, which puts winit on the main thread. The node tests inzebrad/tests/crosslink.rsrun headless, so they run withPH_NO_VIZ_GUIset, which leaves the feature out of an otherwise identical build.
9. Open decisions
Payout design belongs to separate work, recorded here for context. Implementation questions
that need a design pass are in IMPLEMENTATION.md.
9.1 Objective reward trigger and reward economics
Consensus issuance cannot depend on node-local fin. Honest nodes can reach the same chain
through different best-chain and reorg histories, so they need not observe the same sequence
of fin transitions. They must nevertheless compute identical value pools for the same
chain.
An objective per-block event can instead be derived from block data, for example:
payout boundary at H iff candidate(H) != candidate(parent(H))
Implemented. The prototype now takes this trigger, with a liveness bound added to it:
a block pays iff its certificate differs from its parent's and the certificate is at most
σ + FINALITY_LIVENESS_ALLOWANCE blocks behind it. §5.4 states the rule and where each path
evaluates it. The consequences listed below under "payout amount" are the ones this choice
accepts: a flat reward per advance, so a BFT stall lowers issuance for as long as it lasts and
never pays the missed blocks back.
This is not literally the event "local fin advanced." It is a block-local event that would
permit fin to advance if H were observed as best and its candidate were ahead of that
node's current fin. snapshot(LF(H)) is another objective candidate source. The selected
function must be monotone along a chain under the enforced validity rules. Extension makes
LF(H) monotone along a chain; Linearity then makes snapshot(LF(H)) monotone, and
candidate(H) follows because prune_σ(H) is monotone and an lca of two monotone arguments is
monotone. The current tree enforces both Extension and Linearity (§6.2). Without a Finality
Depth rule, a bc-block producer can also keep a stale context_bft at no validity cost (§3.3), so an
objective advance trigger lets whoever dominates bc_best delay payouts while Π_bft is live.
Payout amount is a separate decision:
- A flat
POS_BLOCK_REWARD_ZATSper objective advance lowers issuance during a BFT stall and can leave it permanently lower if advances never resume. - A deferred amount based on elapsed PoW height can catch up only when a later payout occurs and only under an explicit accrual rule. Issuance is still lower at intermediate heights, remains lower after a permanent stall, and intervals with no active bonds need a rule: drop, burn, or carry their nominal reward.
- Current rewards increase bond principal every rewarded block. A lump delays that compounding and allocates the whole amount among bonds active at payout time. Individual allocations therefore change, even if aggregate eventual base issuance is preserved under stated assumptions.
- Non-payout blocks must still append empty
bond_rewardsentries so positional reorg reversal remains aligned.
The choice of objective trigger does not depend on resolving the amount formula. Conversely, the amount decision must not obscure the already-settled requirement that a consensus trigger be replayable from the chain alone. Detailed reward economics should live in a separate decision document once a concrete policy is proposed.
10. Source appendix
- Original TFL Book:
candidate,fin, and syncing; the same range defines the omittedba_μ - Original TFL Book: parameters
σ,L,μ, and Stalled Mode, of which onlyσis used here - Original TFL Book: liveness argument, including the note that the Finality Depth rule can be omitted
- Original TFL Book: the arguments for bounded availability, the case for the design this tree does not adopt
- Original TFL Book: BFT validity rules
- Original TFL Book: bc validity and honest production
- Original TFL Book: fork-choice question
- Original TFL Book: Linearity and Last Final Snapshot rules combined, including the note that the Questions argument predates Linearity
- Original TFL Book: what the Linearity rule does, the informal safety sketch for both rules
- Original TFL Book: liveness contrast with Casper FFG and the status of the safety argument
- Shielded Labs warning about the adapted construction. Protocol definitions above are cited separately from the original pinned source.
Every current-tree statement describes the monolith tree this document ships with. Code can move without this file being updated, so re-check the cited symbols before using this document to plan changes.
A Visual Tour of Zcash Crosslink
Zcash PoW
-Currently the Zcash Mainnet uses consensus rules defined by Network Upgrade 6.1. This relies on a Bitcoin-like PoW consensus mechanism, which enables partition-tolerant high availability at the cost of forks / rollbacks. Here's a conceptual diagram of PoW blocks pointing to their parents (via prevhash header fields) which shows two objectively-verifiable histories leading back from PoW blocks B₃ and B₂', with B₃ being the longer:
+Currently the Zcash Mainnet uses consensus rules defined by Network Upgrade 6.3. This relies on a Bitcoin-like PoW consensus mechanism, which enables partition-tolerant high availability at the cost of forks / rollbacks. Here's a conceptual diagram of PoW blocks pointing to their parents (via prevhash header fields) which shows two objectively-verifiable histories leading back from PoW blocks B₃ and B₂', with B₃ being the longer:
graph TD
B3([B₃]):::pow --> B2([B₂]):::pow
B2 --> B1([B₁]):::pow
B1 --> B0([B₀]):::pow
%% A split history:
B2b([B₂']):::powAlt --> B1b([B₁']):::powAlt
B1b --> B0
%% Styles defined in mermaid-common-styles.js and mermaid-styles.md
%% Define PoW block style with dark blue border and oval shape
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
%% Define alternative PoW block style with orange fill for caution
classDef powAlt fill:#ffcc80,stroke:#01579b,stroke-width:3px,color:#000
A Visual Lexicon for TFL Book
The Last Final Snapshot Rule
Last Final Snapshot rule: .
For a bft‑block or bft‑proposal , define
Note that the type of in the quoted definition is a BFT Finality Certificate.
graph TD
%% Node Categories
classDef protocol stroke-width:1px
class powProto,bftProto protocol;
classDef pow stroke-width:1px
classDef powAlt stroke:grey,stroke-width:1px,stroke-dasharray:2,2
classDef bft stroke-width:2px
classDef elidedNode stroke-width:0px,fill:none
%% Nodes
subgraph powProto [Proof of Work blocks]
B0(["`$$B_0$$`"]):::pow
B1(["`$$B_1$$`"]):::pow
B2(["`$$B_2$$`"]):::pow
B3(["`$$B_3$$`"]):::pow
B2alt(["`$$B_2'$$`"]):::powAlt
B1alt(["`$$B_1'$$`"]):::powAlt
end
subgraph bftProto [BFT Finality Certificates]
FIN_0("`$$FIN_0$$`"):::bft
FIN_1("`$$FIN_1$$`"):::bft
FIN_2("`$$FIN_2$$`"):::bft
end
%% "Out of view" node indicators:
powDots(["…"]):::elidedNode
bftDots(["…"]):::elidedNode
%% PoW Edges
B3 --> B2
B2 --> B1
B1 --> B0
B0 --> powDots
B2alt --> B1alt
B1alt --> B0
%% Finality certificate sequence
FIN_2 --> FIN_1
FIN_1 --> FIN_0
FIN_0 --> bftDots
%% Finality snapshots
FIN_2 == snapshot ==> B2
FIN_1 == snapshot ==> B0
FIN_0 == snapshot ==> powDots
For a bc‑block , define
A Visual Guide to Finality and Fork Choice
A Zebra Crosslink node tracks three points on the PoW chain. This guide shows how each one is found, and what happens to them when the PoW chain reorganizes.
bc_bestis the PoW chain that the node's fork choice selects, andbc_best_tipis its newest block. It is available but not final.candidate(H)is the finalization point that a PoW blockHand its linked ancestry imply. It is objective: every correct replay of the sameHgets the same answer.finis the furthest compatiblecandidate(bc_best_tip)that this node has accepted across best-chain updates. It is node-local memory and never moves backward.
A candidate can move backward without the best chain crossing fin; that is the benign case. A best chain that actually forks below fin is a different, exceptional case.
Reading the diagrams
Newer blocks are at the top. Arrows are committed references, not message flow: each one points from a block to something that block names.
| Drawn as | Meaning |
|---|---|
| Rounded block, blue border, white fill | PoW block on the node's best chain |
| Rounded block, orange fill | PoW block off the node's best chain |
| Box, red border | PoS / BFT block |
| Box, pink fill | LF(H): the last final BFT block in the context of H |
| Box, dashed red border | BFT proposal that the validity rules reject |
| Yellow fill | candidate(H) for the best tip H |
| Thick purple border | fin |
| Plain arrow | Parent link |
Arrow labelled context_bft | The BFT block that a PoW block cites |
| Dotted arrow | A PoW header carried in a BFT block's headers_bc |
Thick arrow labelled snapshot | snapshot(B): the parent of the deepest header in B.headers_bc |
a ⪯ b means that a is b or an ancestor of b. Two blocks conflict when neither is an ancestor of the other.
The styles are listed in Mermaid Common Styles.
How candidate(H) crosses both chains
graph TD
subgraph bftChain ["PoS / BFT chain"]
S6("S6 · LF(P10)<br/>headers_bc = [P6, P7, P8]"):::lf
S5(S5):::bft
S4(S4):::bft
S3(S3):::bft
S2(S2):::bft
S1(S1):::bft
end
subgraph powChain ["PoW / bc chain"]
P10([P10]):::pow
P9([P9]):::pow
P8([P8]):::pow
P7(["P7 · prune_sigma(P10)"]):::pow
P6(["P6 · headers_bc[0]"]):::pow
P5(["P5 · candidate(P10)"]):::candidate
P4([P4]):::pow
P3([P3]):::pow
P2([P2]):::pow
end
%% Parent links
P10 --> P9 --> P8 --> P7 --> P6 --> P5 --> P4 --> P3 --> P2
S6 --> S5 --> S4 --> S3 --> S2 --> S1
%% Crosslinks
P10 -- context_bft --> S6
S6 -.-> P8
S6 -.-> P7
S6 -.-> P6
S6 == snapshot ==> P5
%% Styles defined in mermaid-common-styles.js and mermaid-styles.md
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
classDef bft fill:#fff,stroke:#b71c1c,stroke-width:3px,color:#000
classDef lf fill:#ffcdd2,stroke:#b71c1c,stroke-width:3px,color:#000
classDef candidate fill:#ffeb3b,stroke:#01579b,stroke-width:3px,color:#000
Starting from H = P10:
P10.context_bftcitesS6. Tenderlink decides each BFT block on its own, and the fat pointer incontext_bftcarries the signatures of that decision, so the cited block is final andLF(P10) = S6. The Book's generic BFT protocol can instead finalize an ancestor of the cited block.S6.headers_bc = [P6, P7, P8], deepest first. Its snapshot is the parent ofheaders_bc[0]:snapshot(S6) = parent(P6) = P5.prune_sigma(P10)drops the newestsigmablocks:P7whensigma = 3.- The candidate is the last common ancestor of those two blocks:
candidate(P10) = lca(snapshot(LF(P10)), prune_sigma(P10)) = lca(P5, P7) = P5
The lexicon quotes the Book's definitions of snapshot, LF and candidate.
All three values name PoW-chain points
The PoS chain helps compute the candidate, but bc_best_tip, candidate and fin are all tips of PoW-chain prefixes.
graph TD
subgraph bftChain ["PoS"]
S6("S6<br/>headers_bc = [P6, P7, P8]"):::bft
S5(S5):::bft
S4(S4):::bft
S3(S3):::bft
S2(S2):::bft
end
subgraph powChain ["PoW"]
P10(["P10 · bc_best_tip"]):::pow
P9([P9]):::pow
P8([P8]):::pow
P7([P7]):::pow
P6([P6]):::pow
P5(["P5 · candidate(P10) · fin"]):::candidate
P4([P4]):::pow
P3([P3]):::pow
P2([P2]):::pow
end
%% Parent links
P10 --> P9 --> P8 --> P7 --> P6 --> P5 --> P4 --> P3 --> P2
S6 --> S5 --> S4 --> S3 --> S2
%% Crosslinks
P10 -- context_bft --> S6
S6 -.-> P8
S6 -.-> P7
S6 -.-> P6
S6 == snapshot ==> P5
%% Styles defined in mermaid-common-styles.js and mermaid-styles.md
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
classDef bft fill:#fff,stroke:#b71c1c,stroke-width:3px,color:#000
classDef candidate fill:#ffeb3b,stroke:#01579b,stroke-width:3px,color:#000
%% Define fin last, so that its border wins over the block style.
classDef fin stroke:#8e24aa,stroke-width:7px
class P5 fin
bc_best_tip = P10is the fork-choice result, not finality.P6–P10are unfinalized, and no protocol rule bounds this gap: Zebra Crosslink omits Stalled Mode, so nothing limits how far the best chain runs ahead offin.candidate(P10) = P5is the objective result of the two-chain walk. It is pure, and it can move backward while the best chain still containsfin.finadvances fromP4toP5, because on thisbc_bestupdate the candidate is ahead of it. It is stateful and never rolls back locally.
Benign case: the candidate moves backward
A shallow PoW reorg can expose an older BFT context. Its derived candidate can therefore be an ancestor of fin. That is not a rollback through finality: the complete new best chain still descends from fin.
Before: fin advances
bc_best_tip = P10 cites S6, whose snapshot P5 is the candidate, so fin advances to P5.
graph TD
subgraph bftChain ["PoS"]
S6("S6<br/>headers_bc = [P6, P7, P8]"):::bft
S5(S5):::bft
S4(S4):::bft
S3(S3):::bft
S2(S2):::bft
end
subgraph powChain ["PoW"]
P10(["P10 · bc_best_tip"]):::pow
P9([P9]):::pow
P8([P8]):::pow
P7([P7]):::pow
P6([P6]):::pow
P5(["P5 · candidate · fin"]):::candidate
P4([P4]):::pow
P3([P3]):::pow
P2([P2]):::pow
P1([P1]):::pow
end
%% Parent links
P10 --> P9 --> P8 --> P7 --> P6 --> P5 --> P4 --> P3 --> P2 --> P1
S6 --> S5 --> S4 --> S3 --> S2
%% Crosslinks
P10 -- context_bft --> S6
S6 -.-> P8
S6 -.-> P7
S6 -.-> P6
S6 == snapshot ==> P5
%% Styles defined in mermaid-common-styles.js and mermaid-styles.md
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
classDef bft fill:#fff,stroke:#b71c1c,stroke-width:3px,color:#000
classDef candidate fill:#ffeb3b,stroke:#01579b,stroke-width:3px,color:#000
%% Define fin last, so that its border wins over the block style.
classDef fin stroke:#8e24aa,stroke-width:7px
class P5 fin
bc_best = P10 · candidate = P5 · fin = P5
After: the candidate is older, not conflicting
The higher-work Q branch replaces only P8–P10, so bc_best_tip = Q10 still contains fin = P5. Its older BFT context yields candidate P4. Hold fin at P5.
graph TD
subgraph powChain ["PoW"]
Q10(["Q10 · bc_best_tip"]):::pow
Q9([Q9]):::pow
Q8([Q8]):::pow
P10([P10]):::powAlt
P9([P9]):::powAlt
P8([P8]):::powAlt
P7([P7]):::pow
P6([P6]):::pow
P5(["P5 · fin"]):::pow
P4(["P4 · candidate"]):::candidate
P3([P3]):::pow
P2([P2]):::pow
P1([P1]):::pow
end
subgraph bftChain ["PoS"]
S6(S6):::bft
S5("S5<br/>headers_bc = [P5, P6, P7]"):::bft
S4(S4):::bft
S3(S3):::bft
S2(S2):::bft
end
%% Parent links
Q10 --> Q9 --> Q8 --> P7 --> P6 --> P5 --> P4 --> P3 --> P2 --> P1
P10 --> P9 --> P8 --> P7
S6 --> S5 --> S4 --> S3 --> S2
%% Crosslinks
Q10 -- context_bft --> S5
S5 -.-> P7
S5 -.-> P6
S5 -.-> P5
S5 == snapshot ==> P4
%% Styles defined in mermaid-common-styles.js and mermaid-styles.md
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
classDef powAlt fill:#ffcc80,stroke:#01579b,stroke-width:3px,color:#000
classDef bft fill:#fff,stroke:#b71c1c,stroke-width:3px,color:#000
classDef candidate fill:#ffeb3b,stroke:#01579b,stroke-width:3px,color:#000
%% Define fin last, so that its border wins over the block style.
classDef fin stroke:#8e24aa,stroke-width:7px
class P5 fin
bc_best = Q10 · candidate = P4 · fin = P5 · fin ⪯ Q10
Why this is benign: S5 carries [P5, P6, P7], so snapshot(S5) = P4. Its child S6 carries [P6, P7, P8], so snapshot(S6) = P5. The snapshots are linear, and both the old P chain and the new Q chain contain fin = P5. Only the derived candidate moved backward.
What the node does on each best-chain update
| Situation | Action |
|---|---|
candidate(bc_best_tip) descends from fin | Advance fin to the candidate. |
The candidate is an ancestor of fin | Hold fin. This can be benign, when the complete bc_best still contains fin. |
The candidate conflicts with fin | Hold fin and record a finalization safety hazard. |
bc_best_tip itself conflicts with fin | Hold fin. The candidate test may only report "ancestor", so detect this separately. |
Do not conflate two tests. fin ⪯ candidate(bc_best_tip) can fail merely because the candidate lands behind fin; that does not mean the best chain has rolled back a finalized block. A full-best-chain conflict means that fin and bc_best_tip are on different forks. The candidate test alone does not detect it: the candidate of a conflicting tip can still be an ancestor of fin, as the next section shows.
Exceptional case: the best chain forks below fin
This is not the benign case above. Because fin came from a previously sigma-confirmed prefix, a later bc_best that conflicts with it means that this execution does not satisfy PoW Prefix Consistency at that confirmation depth.
Prefix Consistency failure at sigma: fin = P5 conflicts with raw bc_best = C8.
graph TD
subgraph bftChain ["PoS / BFT"]
S6("S6 proposal"):::rejected
S5(S5):::bft
S4("S4<br/>headers_bc = [P6, P7, P8]"):::bft
S3(S3):::bft
S2(S2):::bft
end
subgraph powChain ["PoW / raw bc_best"]
C8(["C8 · raw bc_best_tip"]):::pow
C7([C7]):::pow
C6([C6]):::pow
C5([C5]):::pow
C4([C4]):::pow
P8([P8]):::powAlt
P7([P7]):::powAlt
P6([P6]):::powAlt
P5(["P5 · fin"]):::powAlt
P4([P4]):::powAlt
P3(["P3 · candidate(C8)"]):::candidate
P2([P2]):::pow
P1([P1]):::pow
end
%% Parent links
C8 --> C7 --> C6 --> C5 --> C4 --> P3 --> P2 --> P1
P8 --> P7 --> P6 --> P5 --> P4 --> P3
S6 --> S5 --> S4 --> S3 --> S2
%% Crosslinks
C8 -- context_bft --> S3
S4 == snapshot ==> P5
S6 == "rejected snapshot" ==x C6
%% Styles defined in mermaid-common-styles.js and mermaid-styles.md
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
classDef powAlt fill:#ffcc80,stroke:#01579b,stroke-width:3px,color:#000
classDef bft fill:#fff,stroke:#b71c1c,stroke-width:3px,color:#000
classDef rejected fill:#fff,stroke:#b71c1c,stroke-width:2px,stroke-dasharray:5 4,color:#000
classDef candidate fill:#ffeb3b,stroke:#01579b,stroke-width:3px,color:#000
%% Define fin last, so that its border wins over the block style.
classDef fin stroke:#8e24aa,stroke-width:7px
class P5 fin
The higher-work C chain forks from P3, below finalized P5. C8 cites the older BFT block S3, and that context gives candidate(C8) = P3. The arrows for S4's three headers are left out to keep the picture readable; they would point at P6, P7 and P8.
- Prefix Consistency at
sigmafailed. A previouslysigma-confirmed prefix was displaced. - CL2 keeps
C8asbc_best. The highest-score valid chain wins. No CL2 rule requires rawbc_bestto containfin. - Abstract CL2 rejects the crossing. Linearity keeps valid snapshots on the P branch, so a proposal
S6whose snapshot is on the C fork is rejected. candidate(C8) = P3;finstaysP5. No C block can advance this finalization point. With no Stalled Mode, C blocks still carry ordinary spends.
Result: miners extend an unfinalizable best chain with ordinary spends, and the finality gap grows without bound. Raw fork choice may return to P; intervention is needed only if C stays dominant and finality must resume elsewhere.
The diagram shows the abstract CL2 path, not current Zebra. It assumes BFT Final Agreement and objective enforcement of the Linearity and Tail Confirmation validity rules. With those, the BFT snapshot history cannot cross to C, so fin remains P5 while C is dominant. Zebra enforces both rules in BFT validation, so there this outcome rests on BFT Final Agreement alone. But Zebra does not follow raw bc_best onto C in the first place:
- Abstract CL2 response. Keep raw
bc_best = C8, keepfin = P5, and prevent valid BFT snapshots from crossing forks. With Stalled Mode omitted, nothing restricts later C blocks: spends accumulate pastfinfor as long as C dominates, and would be rolled back if the best chain returns to P. - Zebra Crosslink response. Sticky fork choice, described next. The node commits up to
fin, which discards every chain that does not contain it, and rejects blocks that fork below its finalized tip.C8never becomes its best chain, whatever C's work; the node stays on P and keepsfin = P5. This enforcesfin ⪯ bc_best, not the stronger property that an unfinalizedsigma-deep prefix can never be displaced. Raw CL2 does not impose this rule; it is a Zebra Crosslink decision.
Sticky fork choice
Sticky fork choice selects bc_best so that the node's own fin stays on its best chain. It is temporal: the result depends on the chain the node is already on and on its current fin, not only on the chains in view.
graph TD
Q9(["Q9 · switch"]):::pow
Q8([Q8]):::pow
Q7([Q7]):::pow
P8(["P8 · bc_best_tip"]):::pow
P7([P7]):::pow
P6([P6]):::pow
P5(["P5 · fin"]):::pow
P4([P4]):::pow
P3([P3]):::pow
P2([P2]):::pow
P1([P1]):::pow
C9(["C9 · no switch"]):::powAlt
C8([C8]):::powAlt
C7([C7]):::powAlt
C6([C6]):::powAlt
C5([C5]):::powAlt
C4([C4]):::powAlt
%% Parent links
Q9 --> Q8 --> Q7 -- "forks above fin" --> P6
P8 --> P7 --> P6 --> P5 --> P4 --> P3 --> P2 --> P1
C9 --> C8 --> C7 --> C6 --> C5 --> C4 -- "forks below fin" --> P3
%% Styles defined in mermaid-common-styles.js and mermaid-styles.md
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
classDef powAlt fill:#ffcc80,stroke:#01579b,stroke-width:3px,color:#000
%% Define fin last, so that its border wins over the block style.
classDef fin stroke:#8e24aa,stroke-width:7px
class P5 fin
The node's current chain ends at P8, and fin = P5. It switches from its current chain to a new one if and only if:
fin ⪯ new and (work(new) > work(current) or equal work and greater tip hash)
Q9: more work, containsfin = P5. Switch. Raw work-based fork choice does the same.C9: more work, forks atP3, belowfin. No switch, whatever C's work. Raw fork choice switches and leavesfinoffbc_best.finadvances only tocandidate(bc_best).candidate(bc_best) ⪯ bc_best, so the node's best chain always contains itsfin.
Summary
bc_best is raw fork choice, candidate(H) is objective evidence, and fin is node-local monotone memory. An application either stops with fin during a finalization stall, or follows bc_best with no bound on how far it runs past fin. Sticky fork choice, the rule Zebra Crosslink implements, selects bc_best only among chains containing fin, ordered by work and then tip hash.
Crosslink Architecture Decision Records
We use an approach of documenting many design decisions during the implementation of zebra-crosslink via Architecture Decision Records, inspired by their use in upstream zebra. These are especially important for our Prototype-then-Productionize approach, since they record key decisions we should review for production readiness.
Currently ADRs are very rough and tracked on this zebra-crosslink ADR Google Sheet.
Moving forward we will begin to incorporate them into this codebase.
The Crosslink 2 Construction
This section is an almost direct paste from a section found in `https://github.com/Electric-Coin-Company/tfl-book` for the purposes of precisely committing to a (potentially incomplete, confusing, or inconsistent) precise set of book contents for a security design review.
We believe this respects the license of the other repository. However, the other authors of the TFL-Book, Daira-Emma Hopwood and Jack Grigg have not reviewed and do not necessarily endorse its content or design changes relative to Crosslink 2. Also note that any corrections made to the TFL-Book will not necessarily be reflected here.
The `zebra-crosslink` design in this book diverges from this text by _not_ including "Stalled Mode" rules. This simplification to the protocol rules follows the rationale that we are already relying heavily on the stakers to guard safe operation of the protocol by redelegating appropriately to prevent hazards like BFT stalls.
The `zebra-crosslink` design does not use the "outer signature" referred to in this chapter, because this replaces a subtle security hazard which many participants could leverage maliciously to one where only the current proposer could leverage it maliciously, and we believe this trade-off is not worth it. This means a direct hash or copy of the most recent BFT finality certificate is insufficient evidence to ensure that specific bitwise copy is canonical or will become canonical in the chain.
We are now ready to give a description of a protocol that takes into account the issues described in Notes on Snap‑and‑Chat, and that implements bounded availability. We call this the “Crosslink” construction; more precisely the version described here is “Crosslink 2”.
This description will attempt to be self-contained, but [NTT2020] (arXiv version) is useful background on the general model of Ebb-and-Flow protocols.
Conventions
“” is a metavariable for the name of a protocol. We also use it as a wildcard in protocol names of a particular type, for example “bc” for the name of some best‑chain protocol.
Protocols are referred to as for a name “”. Where it is useful to avoid ambiguity, when referring to a concept defined by we prefix it with “‑”.
We do not take synchrony or partial synchrony as an implicit assumption of the communication model; that is, unless otherwise specified, messages between protocol participants can be arbitrarily delayed or dropped. A given message is received at most once, and messages are nonmalleably authenticated as originating from a given sender whenever needed by the applicable protocol. Particular subprotocols may require a stronger model.
For an overview of communication models used to analyze distributed protocols, see [this blog post by Ittai Abraham](https://decentralizedthoughts.github.io/2019-06-01-2019-5-31-models/).
The original context for the definition of the partially synchronous model in [[DLS1988]](https://groups.csail.mit.edu/tds/papers/Lynch/jacm88.pdf) was for “one‑shot” Byzantine Agreement — called “the consensus problem” in that paper. The following argument is used to justify assuming that all messages from the Global Stabilization Time onward are delivered within the <span style="white-space: nowrap">upper time bound $\Delta$:</span>
> Therefore, we impose an additional constraint: For each execution there is a global stabilization time (GST), unknown to the processors, such that the message system respects the upper bound $\Delta$ from time GST onward.
>
> This constraint might at first seem too strong: In realistic situations, the upper bound cannot reasonably be expected to hold forever after GST, but perhaps only for a limited time. However, any good solution to the consensus problem in this model would have an <span style="white-space: nowrap">upper bound $L$</span> on the amount of time after GST required for consensus to be reached; in this case it is not really necessary that the bound $\Delta$ hold forever after time GST, but only up to <span style="white-space: nowrap">time GST $+\; L$.</span> We find it technically convenient to avoid explicit mention of the interval length $L$ in the model, but will instead present the appropriate upper bounds on time for each of our algorithms.
Several subsequent authors applying the partially synchronous model to block chains appear to have forgotten or neglected this context. In particular, the argument depends on the protocol completing soon after GST. Obviously a block‑chain protocol does not satisfy this assumption; it is not a “one‑shot” consensus problem.
This assumption could be removed, but some authors of papers about block‑chain protocols have taken it to be an essential aspect of modelling partial synchrony. I believe this is contrary to the intent of [[DLS1988]](https://groups.csail.mit.edu/tds/papers/Lynch/jacm88.pdf):
> Instead of requiring that the consensus problem be solvable in the GST model, we might think of separating the correctness conditions into safety and termination properties. The safety conditions are that no two correct processors should ever reach disagreement, and that no correct processor should ever make a decision that is contrary to the specified validity conditions. The termination property is just that each correct processor should eventually make a decision. Then we might require an algorithm to satisfy the safety conditions no matter how asynchronously the message system behaves, that is, even if $\Delta$ does not hold eventually. On the other hand, we might only require termination in case $\Delta$ holds eventually. It is easy to see that these safety and termination conditions are [for the consensus problem] equivalent to our GST condition: If an algorithm solves the consensus problem when $\Delta$ holds from time GST onward, then that algorithm cannot possibly violate a safety property even if the message system is completely asynchronous. This is because safety violations must occur at some finite point in time, and there would be some continuation of the violating execution in which $\Delta$ eventually holds.
This argument is correct as stated, i.e. for the one‑shot consensus problem. Subtly, essentially the same argument can be adapted to protocols with *safety* properties that need to be satisfied continuously. However, it cannot correctly be applied to *liveness* properties of non‑terminating protocols. The authors (Cynthia Dwork, Nancy Lynch, and Larry Stockmeyer) would certainly have known this: notice how they carefully distinguish “the GST model” from “partial synchrony”. They cannot plausibly have intended this GST formalization to be applied unmodified to analyze liveness in such protocols, which seems to be common in the block‑chain literature, including in the Ebb-and-Flow paper [[NTT2020]](https://eprint.iacr.org/2020/1091.pdf) and the Streamlet paper [[CS2020]](https://eprint.iacr.org/2020/088.pdf).
The Ebb-and-Flow paper acknowledges the issue by saying “Although in reality, multiple such periods of (a‑)synchrony could alternate, we follow the long‑standing practice in the BFT literature and study only a single such transition.” This is not adequate: “long‑standing practice” notwithstanding, it is not valid in general to infer that properties holding for the first transition to synchrony also apply to subsequent transitions (where the protocol can be in states that would not occur initially), and it is plausible that this inference could fail for real protocols. The Streamlet paper also refers to “periods of synchrony” which indicates awareness of the issue, but then it uses the unmodified GST model in the proofs.
Informally, to solve this issue it is necessary to also prove that existing progress is maintained during periods of asynchrony, and that during such periods the protocol remains in states where it will be able to take advantage of a future period of synchrony to make further progress.
This provides further motivation to avoid taking the GST formalization of partial synchrony as a basic assumption.
Note that the recent result [[CGSW2024]](https://arxiv.org/pdf/2405.10249) does not contradict anything we say here. Although the GST and Unknown Latency models are “equally demanding” in the sense of existence of protocols that satisfy a given goal, this result does not show that the models are equivalent for any specific protocol. In particular the requirements of the “clock‑slowing” technique fail in practice for any protocol involving Proof‑of‑Work.
A ‑execution is the complete set of events (message sends/receives and decisions by protocol participants) that occur in a particular run of from its initiation up to a given time. A prefix of a ‑execution is also a ‑execution. Since executions always start from protocol initiation, a strict suffix of a ‑execution is not a ‑execution.
Times are modelled as values of a totally ordered type with minimum value . For convenience, we consider all protocol executions to start at time .
Although protocols may be nondeterministic, an execution fixes the events that occur and times at which they occur, for the purpose of modeling.
For simplicity, we assume that all events occur at global times in a total ordering. This assumption is not realistic in an asynchronous communication model, but it is not essential to the design or analysis and could be removed: we could use a partial happens-before ordering on events in place of a total ordering on times.
A “‑node” is a participant in (the protocol may be implicit). A ‑node is “honest at time ” in a given execution iff it has followed the protocol up to and including time in that execution.
A time series on type is a function assigning a value of to each time in an execution. By convention, we will write the time as a superscript: .
A ‑chain is a nonempty sequence of ‑blocks, starting at the “genesis block” , in which each subsequent block refers to its preceding or “parent block” by a collision‑resistant hash. The “tip” of a ‑chain is its last element.
For convenience, we conflate ‑blocks with ‑chains; that is, we identify a chain with the block at its tip. This is justified because, assuming that the hash function used for parent links is collision‑resistant, there is exactly one ‑chain corresponding to a ‑block; and conversely there is exactly one ‑block at the tip of a ‑chain.
If is a ‑chain, means with the last blocks pruned, except that if , the result is the genesis ‑chain consisting only of .
The block at depth in a ‑chain is defined to be the tip of . Thus the block at depth in a chain is the last one that cannot be affected by a rollback of length (this also applies when because the genesis ‑chain cannot roll back).
Our usage of “depth” is different from [[NTT2020]](https://eprint.iacr.org/2020/1091.pdf), which uses “depth” to refer to what Bitcoin and Zcash call “height”. It also differs by $1$ from the convention for confirmation depths in `zcashd`, where the tip is considered to be at <span style="white-space: nowrap">depth $1$,</span> rather <span style="white-space: nowrap">than $0$.</span>
For ‑blocks and :
- The notation means that the ‑chain with tip is a prefix of the one with tip . This includes the case .
- The notation means that either or . That is, “one of and is a prefix of the other”. This also includes the case .
- The notation means that both and . That is, “neither of and is a prefix of the other”.
A function is ‑linear iff for every where we have . (This definition can be applied to time series where , or to sequences of ‑blocks where values of are indices.)
If $A \preceq_{\star} C$ and $B \preceq_{\star} C$ then $A \agrees_{\star} B$.
Proof: The chain of ancestors of $C$ is $\star$-linear, and $A$, $B$ are both on that chain.
The notation means the sequence of for each ‑block in chain order from genesis up to and including . ( is a bound variable within this construct.)
remove this if not used:
We use (without a subscript on ) to mean that the transaction ledger is a prefix of . Similarly to above, means that either or ; that is, “one of and is a prefix of the other”.
Views
In the simplest case, a block‑chain protocol provides a single “view” that, for a given ‑execution, provides each ‑node with a time series on ‑chains. More generally a protocol may define several “views” that provide each ‑node with time series on potentially different chain types.
We model a ‑view as a function . By convention, we will write the node index as a subscript and the time as a superscript: .
An execution of $\Pi$ has **Agreement** on the view $V \typecolon \Node \times \Time \rightarrow \starchain$ iff <span style="white-space: nowrap">for all times $t$, $u$</span> and <span style="white-space: nowrap">all $\Pi$ nodes $i$, $j$</span> (potentially the same) such that <span style="white-space: nowrap">$i$ is honest</span> at <span style="white-space: nowrap">time $t$</span> and <span style="white-space: nowrap">$j$ is honest</span> at <span style="white-space: nowrap">time $u$,</span> we have <span style="white-space: nowrap">$V_i^t\, \agrees_{\star} V_j^u$.</span>
Subprotocols
As in Snap‑and‑Chat, we depend on a BFT protocol , and a best‑chain protocol .
See [this terminology note](./the-arguments-for-bounded-availability-and-finality-overrides.md#terminology-note) for why we do not call $\Pi_{\origbc}$ a “longest‑chain” protocol.
We modify (resp. ) to give (resp. ) by adding structural elements, changing validity rules, and changing the specified behaviour of honest nodes.
A Crosslink 2 node must participate in both and ; that is, it must maintain a view of the state of each protocol. Acting in more specific roles such as bft‑proposer, bft‑validator, or bc‑block‑producer is optional, but we assume that all such actors are Crosslink 2 nodes.
Model for BFT protocols (Π{origbft,bft})
A bft‑node’s view includes a set of bft‑block chains each rooted at a fixed genesis bft‑block . There is a bft‑block‑validity rule (specified below), which depends only on the content of the block and its ancestors. A non‑genesis block can only be bft‑block‑valid if its parent is bft‑block‑valid. A bft‑valid‑chain is a chain of bft‑block‑valid blocks.
Execution proceeds in a sequence of epochs. In each epoch, an honest proposer for that epoch may make a bft‑proposal.
A bft‑proposal refers to a parent bft‑block, and specifies the proposal’s epoch. The content of a proposal is signed by the proposer using a strongly unforgeable signature scheme. We consider the proposal to include this signature. There is a bft‑proposal‑validity rule, depending only on the content of the proposal and its parent block, and the validity of the proposer’s signature.
We extend the notation to bft‑proposals in the obvious way: if , is a bft‑proposal and its parent bft‑block, then .
We will shorten <span style="white-space: nowrap">“$\star$bft‑block‑valid $\star$bft‑block”</span> to <span style="white-space: nowrap">“$\star$bft‑valid‑block”,</span> and <span style="white-space: nowrap">“$\star$bft‑proposal‑valid $\star$bft‑proposal”</span> to <span style="white-space: nowrap">“$\star$bft‑valid‑proposal”.</span>
For each epoch, there is a fixed number of voting units distributed between the bft‑nodes, which they use to vote for a bft‑proposal. We say that a voting unit has been cast for a bft‑proposal at a given time in a bft‑execution, if and only if is bft‑proposal‑valid and a ballot for authenticated by the holder of the voting unit exists at that time.
Using knowledge of ballots cast for a bft‑proposal that collectively satisfy a notarization rule at a given time in a bft‑execution, and only with such knowledge, it is possible to obtain a valid bft‑notarization‑proof . The notarization rule must require at least a two‑thirds absolute supermajority of voting units in ’s epoch to have been cast for . It may also require other conditions.
A voting unit is cast non‑honestly for an epoch’s proposal iff:
- it is cast other than by the holder of the unit (due to key compromise or any flaw in the voting protocol, for example); or
- it is double‑cast (i.e. there are at least two ballots casting it for distinct proposals); or
- the holder of the unit following the conditions for honest voting in , according to its view, should not have cast that vote.
Note that a unit should be considered to be cast non-honestly in the case of key compromise, because it is then effectively under the control of an adversary. The key compromise may or may not be attributable to another flaw in the protocol, but such a flaw would not be a break of the consensus mechanism per se.
An execution of $\Pi_{\bft}$ has the **one‑third bound on non‑honest voting** property iff for every epoch, *strictly* fewer than one third of the total voting units for that epoch are ever cast non‑honestly.
It may be the case that a ballot cast for $P$ is not [in honest view](#in-honest-view) when it is used to create a notarization proof for $P$. Since we are not assuming synchrony, it may also be the case that such a ballot is in honest view but that any given node has not received it (and perhaps will never receive it).
There may be multiple distinct ballots or distinct ballot messages attempting to cast a given voting unit for the same proposal; this is undesirable for bandwidth usage, but it is not necessary to consider it to be non‑honest behaviour for the purpose of security analysis, as long as such ballots are not double‑counted toward the two‑thirds threshold.
The **one‑third bound on non‑honest voting** property considers all ballots cast in the entire execution. In particular, it is possible that a validator’s key is compromised and then used to cast its voting units for a proposal of an epoch long finished. If the number of voting units cast non-honestly for any epoch *ever* reaches one third of the total voting units for that epoch during an execution, then the **one‑third bound on non‑honest voting** property is violated for that execution.
Therefore, validator keys of honest nodes must remain secret indefinitely. Whenever a key is rotated, the old key must be securely deleted. For further discussion and potential improvements, see [tfl-book issue #140](https://github.com/Electric-Coin-Company/tfl-book/issues/140).
A bft‑block consists of re‑signed by the same proposer using a strongly unforgeable signature scheme. It is bft‑block‑valid iff:
- is bft‑proposal‑valid; and
- is a valid proof that some subset of ballots cast for are sufficient to satisfy the notarization rule; and
- the proposer’s outer signature on is valid.
A bft‑proposal’s parent reference hashes the entire parent bft‑block, i.e. proposal, proof, and outer signature.
Neither $\proof_P$ nor the proposer’s outer signature is unique for a <span style="white-space: nowrap">given $P$.</span> The proposer’s outer signature is however third‑party nonmalleable, by definition of a strongly unforgeable signature scheme. An <span style="white-space: nowrap">“honest $\star$bft‑proposal”</span> is a <span style="white-space: nowrap">$\star$bft‑proposal</span> made for a given epoch by a proposer who is honest in that epoch. Such a proposer will only create one proposal and only sign at most once for each epoch, and so there will be at most one <span style="white-space: nowrap">“honestly submitted”</span> <span style="white-space: nowrap">$\star$bft‑block</span> for each epoch.
It is possible for there to be multiple <span style="white-space: nowrap">$\star$bft‑valid‑blocks</span> for the same proposal, with different notarization proofs and/or outer signatures, if the proposer is not honest. However, the property that there will be at most one <span style="white-space: nowrap">“honestly submitted”</span> <span style="white-space: nowrap">$\star$bft‑block</span> for each epoch is important for liveness, even though we cannot guarantee that any particular proposer for an epoch is honest.
$\TODO$ check that we are correctly using this in the liveness analysis.
There is an efficiently computable function . For a bft‑block‑valid input block , this function outputs the last ancestor of that is final in the context of .
The chain of ancestors is unambiguously determined because a <span style="white-space: nowrap">$\star$bft‑proposal’s</span> parent reference hashes the entire parent <span style="white-space: nowrap">$\star$bft‑block;</span> each <span style="white-space: nowrap">$\star$bft‑block</span> commits to a proposal; and the parent hashes are collision‑resistant. This holds despite the caveat mentioned above that there may be multiple <span style="white-space: nowrap">$\star$bft‑valid‑blocks</span> for the same proposal.
must satisfy all of the following:
- is not bft‑block‑valid.
- If is bft‑block‑valid, then:
- (and therefore it must also be bft‑block‑valid);
- for all bft‑valid‑blocks such that , .
- .
It is correct to talk about the “last final block” of a given chain (that is, each <span style="white-space: nowrap">$\star$bft‑valid-block $C$</span> unambiguously determines a <span style="white-space: nowrap">$\star$bft‑valid-block</span> <span style="white-space: nowrap">$\star\bftlastfinal(C)$)</span>, but it is not correct to refer to a given <span style="white-space: nowrap">$\star$bft‑block</span> as objectively <span style="white-space: nowrap">“$\star$bft‑final”.</span>
A particular BFT protocol might need adaptations to fit it into this model for , before we apply the Crosslink 2 modifications to obtain . Any such adaptions are necessarily protocol-specific. In particular:
- origbft‑proposal‑validity should correspond to the strongest property of an origbft‑proposal that is objectively and feasibly verifiable from the content of the proposal and its parent origbft‑block at the time the proposal is made. It must include verification of the proposer’s signature.
- origbft‑block‑validity should correspond to the strongest property of an origbft‑block that is objectively and feasibly verifiable from the content of the block and its ancestors at the time the block is added to an origbft‑chain. It should typically include all of the relevant checks from origbft‑proposal‑validity that apply to the created block (or equivalent checks). It must also include verification of the notarization proof and the proposer’s outer signature.
- If a node observes an origbft‑valid block , then it should be infeasible for an adversary to cause a rollback in that node’s view past , and the view of the chain up to should agree with that of all other honest nodes. This is formalized in the next section.
Safety of
The intuition behind the following safety property is that:
- For to be safe, it should never be the case that two honest nodes observe (at any time) bft‑blocks and respectively that they each consider final in some context, but does not hold.
- By definition, an honest node observes a bft‑block to be final in the context of another bft‑block , iff .
We say that a bft‑block is “in honest view” if a party observes it at some time at which that party is honest.
An execution of $\Pi_{\starbft}$ has **Final Agreement** iff for all <span style="white-space: nowrap">$\star$bft‑valid blocks $C$</span> in honest view at <span style="white-space: nowrap">time $t$</span> and <span style="white-space: nowrap">$C'$ in honest view</span> at <span style="white-space: nowrap">time $t'$,</span> we have <span style="white-space: nowrap">$\star\bftlastfinal(C) \agrees_{\starbft} \star\bftlastfinal(C')$.</span>
Note that it is possible for this property to hold for an execution of a BFT protocol in an asynchronous communication model. As previously mentioned, if the one‑third bound on non‑honest voting property is ever broken at any time in an execution, then it may not be possible to maintain Final Agreement from that point on.
Streamlet as described in [[CS2020]](https://eprint.iacr.org/2020/088.pdf) has three possible states of a block in a player’s view:
* “valid” (but not notarized or final);
* “notarized” (but not final);
* “final”.
By “valid” the Streamlet paper means just that it satisfies the structural property of being part of a block chain with parent hashes. The role of <span style="white-space: nowrap">$\star$bft‑block‑validity</span> in our model corresponds roughly to Streamlet’s “notarized”. It turns out that with some straightforward changes relative to Streamlet, we can identify “origbft‑block‑valid” with “notarized” and consider an origbft‑valid‑chain to only consist of notarized blocks. This is not obvious, but is a useful simplification.
Here is how the paper defines “notarized”:
> When a block gains votes from at least $2n/3$ distinct players, it becomes notarized. A chain is notarized if its constituent blocks are all notarized.
This implies that blocks can be added to chains independently of notarization. However, the paper also says that an honest leader always proposes a block extending from a notarized chain. Therefore, only *notarized* chains really matter in the protocol.
In unmodified Streamlet, the order in which a player sees signatures might cause it to view blocks as notarized out of order. Streamlet’s security analysis is in a synchronous model, and assumes for liveness that any vote will have been received by all players (Streamlet nodes) within two epochs.
In Crosslink 2, however, we need origbft‑block‑validity to be an objectively and feasibly verifiable property. We also would prefer reliable message delivery within bounded time not to be a basic assumption of our communication model. (This does not dictate what assumptions about message delivery are made for particular security analyses.) If we did not make a modification to the protocol to take this into account, then some Crosslink 2 nodes might receive a two‑thirds absolute supermajority of voting messages and consider a BFT block to be notarized, while others might never receive enough of those messages.
Obviously a *proposal* cannot include signatures on itself — but the block formed from it can include proofs about the proposal and signatures. We can therefore say that when a proposal gains a two‑thirds absolute supermajority of signatures, a block is created from it that contains a proof (such as an aggregate signature) that it had such a supermajority. For example, we can have the proposer itself make this proof once it has enough votes, sign the <span style="white-space: nowrap">resulting $(P, \proof_P)$</span> to create a block, then *submit* that block in a separate message. (The proposer has most incentive to do this in order to gain whatever reward attaches to a successful proposal; it can outsource the proving task if needed.) Then the origbft‑block‑validity rule can require a valid supermajority proof, which is objectively and feasibly verifiable. Players that see an origbft‑valid‑block can immediately consider it notarized.
Note that for the liveness analysis to be unaffected, we need to assume that the combined latency of messages, of collecting and aggregating signatures, and of block submission is such that all adapted‑Streamlet nodes will receive a notarized block corresponding to a given proposal (rather than just all of the votes for the proposal) within two epochs. Alternatively we could re‑do the timing analysis.
With this change, “origbft‑block‑valid” and “notarized” do not need to be distinguished.
Streamlet’s finality rule is:
> If in any notarized chain, there are three adjacent blocks with consecutive epoch numbers, the prefix of the chain up to the second of the three blocks is considered final. When a block becomes final, all of its prefix must be final too.
We can straightforwardly express this as an $\origbftlastfinal$ function of a context block $C$, as required by the model:
For an origbft‑valid‑block $C$, $\origbftlastfinal(C)$ is the last origbft‑valid‑block $B \preceq_{\origbft} C$ such that either $B = \Origin_{\origbft}$ or $B$ is the second block of a group of three adjacent blocks with consecutive epoch numbers.
Note that “When a block becomes final, all of its prefix must be final too.” is implicit in the model.
Model for best-chain protocols (Π{origbc,bc})
A node’s view in includes a set of bc‑block chains each rooted at a fixed genesis bc‑block . There is a bc‑block‑validity rule (often described as a collection of “consensus rules”), depending only on the content of the block and its ancestors. A non‑genesis block can only be bc‑block‑valid if its parent is bc‑block‑valid. By “bc‑valid‑chain” we mean a chain of bc‑block‑valid blocks.
The terminology commonly used in the block‑chain community does not distinguish between rules that are part of the consensus protocol proper, and rules required for validity of the economic computation supported by the block chain. Where it is necessary to distinguish, the former can be called “L0” consensus rules, and the latter “L1” consensus rules.
The definition of bc‑block‑validity is such that it is hard for a block producer to extend a bc‑valid‑chain unless they are selected by a random process that chooses a block producer in proportion to their resources with an approximately known and consistent time distribution, subject to some assumption about the total proportion of resources held by honest nodes.
There is a function , with a strict total ordering on . An honest node will choose one of the bc‑valid‑chains with highest score as the bc‑best‑chain in its view. Any rule can be specified for breaking ties.
The function is required to satisfy for any non‑genesis bc‑valid‑chain .
For a Proof‑of‑Work protocol, the score of a <span style="white-space: nowrap">$\star$bc‑chain</span> should be its accumulated work.
Unless an adversary is able to censor knowledge of other chains from a node’s view, it should be difficult to cause the node to switch to a chain with a last common ancestor more than blocks back from the tip of its previous bc‑best‑chain.
Let be a view such that is node ’s bc‑best‑chain at time . (This matches the notation used in [NTT2020].) We define to be .
A bc‑valid‑block is assumed to commit to a collection (usually, a sequence) of bc‑transactions. Unlike in Crosslink 1 or Snap-and-Chat, we do not need to explicitly model bc‑transaction validity or impose any additional constraints on it. The consensus rules applying to bc‑transactions are entirely unchanged, including any rules that depend on bc‑block height or previous bc‑blocks. This is because Crosslink 2 never reorders or selectively “sanitizes” transactions as Snap-and-Chat does. If a bc‑block is included in a Crosslink 2 block chain then its entire parent bc‑block chain is included just as it would have been in (only modified by the structural additions described later), so block heights are also preserved.
A “coinbase transaction” is a bc‑transaction that only distributes newly issued funds and has no inputs.
Define so that iff has exactly one transaction that is a coinbase transaction.
Each bc‑block is summarized by a bc‑header that commits to the block. There is a notion of bc‑header‑validity that is necessary, but not sufficient, for validity of the block. We will only make the distinction between bc‑headers and bc‑blocks when it is necessary to avoid ambiguity.
In a Proof‑of‑Work protocol, it is normally possible to check the Proof‑of‑Work of a block using only the header. There is a difficulty adjustment function that determines the target difficulty for a block based on its parent chain. So, checking that the correct difficulty target has been used relies on knowing that the header’s parent chain is valid.
Checking header validity before expending further resources on a purported block can be relevant to mitigating denial‑of‑service attacks that attempt to inflate validation cost.
Typically, Bitcoin‑derived best chain protocols do not need much adaptation to fit into this model. The model still omits some details that would be important to implementing Crosslink 2, but distracting for this level of abstraction.
Safety of
We make an assumption on executions of that we will call Prefix Consistency (introduced in [PSS2016, section 3.3] as just “consistency”):
An execution of $\Pi_{\starbc}$ has **Prefix Consistency** at confirmation depth $\sigma$, iff <span style="white-space: nowrap">for all times $t \leq u$</span> and <span style="white-space: nowrap">all nodes $i$, $j$</span> (potentially the same) such that <span style="white-space: nowrap">$i$ is honest</span> at <span style="white-space: nowrap">time $t$</span> and <span style="white-space: nowrap">$j$ is honest</span> at <span style="white-space: nowrap">time $u$,</span> we have that <span style="white-space: nowrap">$\ch_i^t \trunc_{\!\starbc}^\sigma\, \preceq_{\starbc} \ch_j^u$.</span>
The literature uses the same name, <span style="white-space: nowrap">“common‑prefix property”,</span> for two different properties of very different strength.
[[PSS2016](https://eprint.iacr.org/2016/454.pdf), section 3.3] introduced the stronger variant. That paper first describes the weaker variant, calling it the “common‑prefix property by Garay et al [[GKL2015]](https://link.springer.com/chapter/10.1007/978-3-662-46803-6_10).” Then it explains what is essentially a bug in that variant, and describes the stronger variant which it just calls “consistency”:
> The common‑prefix property by Garay et al [[GKL2015]](https://link.springer.com/chapter/10.1007/978-3-662-46803-6_10), which was already considered and studied by Nakamoto [[Nakamoto2008]](https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.221.9986), requires that in any round $r$, the record chains of any two honest players $i$, $j$ agree on all, but potentially the last $T$, records. We note that this property (even in combination with the other two desiderata [of Chain Growth and Chain Quality]) provides quite weak guarantees: even if any two honest parties perfectly agree on the chains, the chain could be completely different on, say, even rounds and odd rounds. We here consider a stronger notion of consistency which additionally stipulates players should be consistent with their “future selves”.
>
> Let $\consistent^T(\view) = 1$ iff for <span style="white-space: nowrap">all rounds $r \leq r'$,</span> and <span style="white-space: nowrap">all players $i$, $j$</span> (potentially the same) such that <span style="white-space: nowrap">$i$ is honest at $\view^r$</span> and <span style="white-space: nowrap">$j$ is honest at $\view^{r'}$,</span> we have that the prefixes of $\mathcal{C}_i^r(\view)$ and $\mathcal{C}_j^{r'}(\view)$ consisting of the first $\ell = |\mathcal{C}_i^r(\view)| - T$ records are identical.
Unfortunately, [[GKL2020]](https://eprint.iacr.org/2014/765.pdf), which is a revised version of [[GKL2015]](https://link.springer.com/chapter/10.1007/978-3-662-46803-6_10), switches to the stronger variant *without changing the name*.
(The [eprint version history](https://eprint.iacr.org/archive/versions/2014/765) may be useful; the change was made in [version 20181013:200033](https://eprint.iacr.org/archive/2014/765/20181013:200033), page 17.)
Note that [GKL2020] uses an adaptive‑corruption model, “meaning that the adversary is allowed to take control of parties on the fly”, and so their wording in Definition 3:
> ... for any pair of <span style="white-space: nowrap">honest players $P_1$, $P_2$</span> adopting the <span style="white-space: nowrap">chains $\mathcal{C}_1$, $\mathcal{C}_2$</span> at rounds $r_1 \leq r_2$ in <span style="white-space: nowrap"><font style="font-variant: small-caps;">view</font>$^{t,n}_{\Pi,\mathcal{A},\mathcal{Z}}$</span> respectively, it holds that <span style="white-space: nowrap">$\mathcal{C}_1^{\trunc k} \preceq \mathcal{C}_2$.</span>
is intended to mean the same as our
> ... <span style="white-space: nowrap">for all times $t \leq u$</span> and <span style="white-space: nowrap">all nodes $i$, $j$</span> (potentially the same) such that <span style="white-space: nowrap">$i$ is honest</span> at <span style="white-space: nowrap">time $t$</span> and <span style="white-space: nowrap">$j$ is honest</span> at <span style="white-space: nowrap">time $u$,</span> we have that <span style="white-space: nowrap">$\ch_i^t \trunc_{\!\starbc}^\sigma\, \preceq_{\starbc} \ch_j^u$.</span>
The latter is closer to [[PSS2016]](https://eprint.iacr.org/2016/454.pdf).
Incidentally, this property does *not* seem to be mentioned in [[Nakamoto2008]](https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.221.9986), contrary to the [PSS2016] authors’ assertion. Maybe implicitly, but it’s a stretch.
When **Prefix Consistency** is taken to hold of typical PoW-based block‑chain protocols like Bitcoin (as it often is), this implies that, in the relevant executions, the network of honest nodes is never <span style="white-space: nowrap">partitioned —</span> unless any partition lasts only for a short length of time relative to $\sigma$ block times. <span style="white-space: nowrap">If node $i$</span> is on one side of a full partition and <span style="white-space: nowrap">node $j$</span> on the other, then after <span style="white-space: nowrap">node $i$’s</span> best chain has been extended by more than <span style="white-space: nowrap">$\sigma$ blocks,</span> $\ch_i^t \trunc_{\!\starbc}^\sigma$ will contain information that has no way to get to <span style="white-space: nowrap">node $j$.</span> And even if the partition is incomplete, we cannot guarantee that the Prefix Consistency property will hold for any given pair of nodes.
It might be possible to maintain Prefix Consistency if the honest nodes on one side of the partition knew that they should not continue building on their chain until the partition has healed, but it is unclear how that would be done in general without resorting to a BFT protocol (as opposed to in specific cases like a single node being unable to connect to the rest of the network). Certainly there is no mechanism to explicitly detect and respond to partitions in protocols derived from Bitcoin.
And yet, [[GKL2020]](https://eprint.iacr.org/2014/765.pdf) claims to *prove* Prefix Consistency from other assumptions. So we know that those assumptions must also rule out a long partition between honest nodes. In fact the required assumption is *implicit* in the communication model:
* A synchronous network cannot be partitioned.
* A partially synchronous network <span style="white-space: nowrap">—that is,</span> providing reliable delivery with bounded but <span style="white-space: nowrap">unknown delay—</span> cannot be partitioned for longer than the delay.
We might be concerned that these implicit assumptions are stronger than we would like. In practice, the peer‑to‑peer network protocol of Bitcoin and Zcash attempts to flood blocks to all nodes. This protocol might have weaknesses, but it is not intended to (and plausibly does not) depend on all messages being received. (Incidentally, Streamlet also implicitly floods messages to all nodes.)
Also, Streamlet and many other BFT protocols do *not* assume *for safety* that the network is not partitioned. That is, BFT protocols can be safe in a fully asynchronous communication model with unreliable messaging. That is why we avoid taking synchrony or partial synchrony as an implicit assumption of the communication model, or else we could end up with a protocol with weaker safety properties than $\Pi_{\origbft}$ alone.
This leaves the question of whether the **Prefix Consistency** property is still too strong, even if we do not rely on it for the analysis of safety when $\Pi_{\bft}$ has not been subverted. In particular, if a particular <span style="white-space: nowrap">node $h$</span> is not well-connected to the rest of the network, then that will inevitably affect <span style="white-space: nowrap">node $h$’s</span> security, but should not affect other honest nodes’ security.
Fortunately, it is not the case that disconnecting a single <span style="white-space: nowrap">node $h$</span> from the network causes the security assumption to be voided. The solution is to view $h$ as not honest in that case (even though it would follow the protocol if it could). This achieves the desired effect within the model, because other nodes can no longer rely on <span style="white-space: nowrap">$h$’s honest input.</span> Although viewing $h$ as potentially adversarial might seem conservative from the point of view of other nodes, bear in mind that an adversary could censor an arbitrary subset of incoming and outgoing messages from the node, and this may be best modelled by considering it to be effectively controlled by the adversary.
Prefix Consistency compares the -truncated chain of some node with the untruncated chain of node . For our analysis of safety of the derived ledgers, we will also need to make an assumption on executions of that at any given time , any two honest nodes and agree on their confirmed prefixes — with only the caveat that one may have observed more of the chain than the other. That is:
An execution of $\Pi_{\starbc}$ has **Prefix Agreement** at confirmation <span style="white-space: nowrap">depth $\sigma$</span> iff it has [**Agreement**](#agreement-on-a-view) on the <span style="white-space: nowrap">view $(i, t) \mapsto \ch_i^t \trunc_{\!\starbc}^\sigma$.</span>
Our security arguments that depend on these properties will all be of the form “in an execution where ⟨safety properties⟩ are not violated, ⟨undesirable thing⟩ cannot happen”.
It is not necessary to involve probability in arguments of this form. Any probabilistic reasoning can be done separately.
In particular, if a statement of this form holds, and ⟨safety properties⟩ are violated with probability <span style="white-space: nowrap">at most $p$</span> under certain conditions, then it immediately follows that under those conditions ⟨undesirable thing⟩ happens with probability <span style="white-space: nowrap">at most $p$.</span> Furthermore, ⟨undesirable thing⟩ can only happen *after* ⟨safety properties⟩ have been violated, because the execution up to that point has been an execution in which ⟨safety properties⟩ are *not* violated.
With few exceptions, involving probability in a security argument is best done only to account for nondeterministic choices in the protocol itself. This is opinionated advice, but a lot of security proofs would likely be simpler if inherently probabilistic arguments were more distinctly separated from unconditional ones.
In the case of the Prefix Agreement property, an alternative approach would be to prove that Prefix Agreement holds with some probability given Prefix Consistency and some other chain properties. This is what [[NTT2020]](https://eprint.iacr.org/2020/1091.pdf) does in its <span style="white-space: nowrap">Theorem 2,</span> which essentially says that under certain conditions Prefix Agreement holds except with <span style="white-space: nowrap">probability $e^{-\Omega(\sqrt{\sigma})}$.</span>
The conclusions that can be obtained from this approach are necessarily probabilistic, and depending on the techniques used, the proof may not be tight; that is, the proof may obtain a bound on the probability of failure that is (either asymptotically or concretely) higher than needed. This is the case for <span>[[NTT2020](https://eprint.iacr.org/2020/1091.pdf), Theorem 2];</span> <span style="white-space: nowrap">footnote 10</span> in that paper points out that the expression for the probability can be asymptotically improved:
> Using the recursive bootstrapping argument developed in <span>[[DKT+2020](https://eprint.iacr.org/2020/601.pdf), Section 4.2],</span> it is possible to bring the error <span style="white-space: nowrap">probability $e^{-\Omega(\sqrt{\sigma})}$</span> as close to an exponential decay as possible. In this context, <span style="white-space: nowrap">for any $\epsilon > 0$,</span> it is possible to find <span style="white-space: nowrap">constants $A_\epsilon$, $a_\epsilon$</span> such that $\Pi_{\lc}(p)$ is secure after <span style="white-space: nowrap">*C*$(\max(\GST, \GAT))$</span> with confirmation time $T_{\confirm} = \sigma$ except with <span style="white-space: nowrap">probability $A_\epsilon\, e^{-a_\epsilon\, \sigma^{1 - \epsilon}}$.</span>
(Here $p$ is the probability that any given node gets to produce a block in any given time slot.)
In fact none of the proofs of security properties for Snap‑and‑Chat depend on the particular expression <span style="white-space: nowrap">$e^{-\Omega(\sqrt{\sigma})}$;</span> for example in the proofs of <span style="white-space: nowrap">Lemma 5</span> and <span style="white-space: nowrap">Theorem 1,</span> this probability just “passes through” the proof from the premisses to the conclusion, because the argument is not probabilistic. The same will be true of our safety arguments.
Talking about what is possible in particular executions has further advantages:
* It sidesteps the issue of how to interpret results in the GST model of partial synchrony, when we do not know what <span style="white-space: nowrap">*C*$(\max(\GST, \GAT))$ is.</span> See also the critique of applying the GST model to block‑chain protocols under [“Discussion of [GKL2020]’s communication model and network partition”](#admonition-discussion-of-gkl2020s-communication-model-and-network-partition) above. (This is not an inherent problem with analyzing the protocol in the partially synchronous setting, but only with inappropriate use of the GST model of that setting.)
* We do not require $\Pi_{\bc}$ to be a Nakamoto‑style Proof‑of‑Work block chain protocol. Some other kind of protocol could potentially satisfy Prefix Consistency and Prefix Agreement.
* It is not clear whether a $e^{-\Omega(\sqrt{\sigma})}$ probability of failure would be concretely adequate. That would depend on the value of $\sigma$ and the constant hidden by the $\Omega$ notation. The asymptotic property using $\Omega$ tells us whether a sufficiently large $\sigma$ *could* be chosen, but we are more interested in what needs to be assumed for a given concrete choice of $\sigma$.
* If a violation of a required safety property occurs *in a given execution*, then the safety argument for Crosslink that depended on the property fails for that execution, regardless of what the probability of that occurrence was. This approach therefore more precisely models the consequences of such violations.
Roughly speaking, the intuition behind both properties is as follows:
Honest nodes are collectively able to find blocks faster than an adversary, and communication between honest nodes is sufficiently reliable that they act as a combined network racing against that adversary. Then by the argument in [[Nakamoto2008]](https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.221.9986), modified by [[GP2020]](https://arxiv.org/pdf/1702.02867.pdf) to correct an error in the concrete analysis, a private mining attack that attempts to cause a <span style="white-space: nowrap">$\sigma$‑block</span> rollback will, with high probability, fail for <span style="white-space: nowrap">large enough $\sigma$.</span> A private mining attack is optimal by the argument in [[DKT+2020]](https://arxiv.org/pdf/2005.10484.pdf).
Any further analysis of the conditions under which these properties hold should be done in the context of a <span style="white-space: nowrap">particular $\Pi_{\starbc}$.</span>
This strengthens the security property, relative to quantifying over a single time. The question can then be split into several parts:
1. _**What does the strengthened property mean, intuitively?**_
Consider the full tree of <span style="white-space: nowrap">$\star$bc‑valid-blocks</span> that honest nodes have considered to be part of their <span style="white-space: nowrap">$\star$bc‑best-chain</span> at any times during the execution. This property holds iff, when we strip off all branches of length up to and including <span style="white-space: nowrap">$\sigma$ blocks,</span> the resulting tree <span style="white-space: nowrap">is $\star$bc‑linear.</span>
2. _**Why is the strengthening needed?**_
Suppose that time were split into periods such that honest nodes agreed on one chain in odd periods, and a completely different chain in even periods. This would obviously not satisfy the intent, but it would satisfy a version of the property that did not quantify over different <span style="white-space: nowrap">times $t$ and $u$.</span>
3. _**Why should we expect the strengthened property to hold?**_
If <span style="white-space: nowrap">node $j$</span> were far ahead, <span style="white-space: nowrap">i.e. $u \gg t$,</span> then it is obvious that $\ch_i^t \trunc_{\!\starbc}^\sigma\, \preceq_{\starbc} \ch_j^u \trunc_{\!\starbc}^\sigma$ should hold. Conversely, if node $i$ were far ahead then it is obvious that $\ch_j^u \trunc_{\!\starbc}^\sigma\, \preceq_{\starbc} \ch_i^t \trunc_{\!\starbc}^\sigma$ should hold. The case where $t = u$ is the same as quantifying over a single time. By considering intermediate cases where <span style="white-space: nowrap">$t$ and $u$</span> converge from the extremes or where they diverge from being equal, you should be able to convince yourself that the property holds for any relative values of <span style="white-space: nowrap">$t$ and $u$,</span> in executions of a reasonable best‑chain protocol.
Definition of Crosslink 2
Parameters
Crosslink 2 is parameterized by a bc‑confirmation‑depth (as in Snap‑and‑Chat), and also a finalization gap bound with significantly greater than .
Each node always uses the fixed confirmation depth to obtain its view of the finalized chain . Unlike in Snap‑and‑Chat or Crosslink 1, this is just a block chain; because we do not need sanitization, there is no need to express it as a log of transactions rather than blocks.
Each node chooses a potentially different bc‑confirmation‑depth where to obtain its view of the bounded‑available ledger at time , . (We make the restriction because there is no reason to choose a larger .)
Choosing $\mu \lt \sigma$</span> is at the node’s own risk and may increase the risk of rollback attacks against $(\localba_\mu)_i^t$ (it does not <span style="white-space: nowrap">affect $\localfin_i^t$).</span> Using small values of $\mu$ is not recommended. The default should <span style="white-space: nowrap">be $\mu = \sigma$.</span>
Stalled Mode
Consider, roughly speaking, the number of bc‑blocks that are not yet finalized at time (a more precise definition will be given in the section on changes from ). We call this the “finality gap” at time . Under an assumption about the distribution of bc‑block intervals, if this gap stays roughly constant then it corresponds to the approximate time that transactions take to be finalized after being included in a bc‑block (if they are finalized at all) just prior to time .
As explained in detail by The Arguments for Bounded Availability and Finality Overrides, if this bound exceeds a threshold , then it likely signals an exceptional or emergency condition, in which it is undesirable to keep accepting user transactions that spend funds into new bc‑blocks. In practice, should be at least .
The condition that the network enters in such cases will be called “Stalled Mode”. For a given higher‑level transaction protocol, we can define a policy for which bc‑blocks will be accepted in Stalled Mode. This will be modelled by a predicate . A bc‑block for which returns is called a “stalled block”.
A bc‑block producer is only constrained to produce stalled blocks while, roughly speaking, its view of the finalization point is not advancing. In particular an adversary that has subverted the BFT protocol in a way that does *not* keep the finalization point from advancing, can always avoid being constrained by Stalled Mode.
The desired properties of stalled blocks and a possible Stalled Mode policy for Zcash are discussed in the How to block hazards section of The Arguments for Bounded Availability and Finality Overrides.
In practice a node's view of the finalized chain, , is likely to lag only a few blocks behind (depending on the latency overhead imposed by ), unless the chain has entered Stalled Mode. So when , the main factor influencing the choice of a given application to use or is not the average latency, but rather the desired behaviour in the case of a finalization stall: i.e. stall immediately, or keep processing user transactions until blocks have passed.
Structural additions
- Each bc‑header has, in addition to origbc‑header fields, a field that commits to a bft‑block.
- Each bft‑proposal has, in addition to origbft‑proposal fields, a field containing a sequence of exactly bc‑headers (zero‑indexed, deepest first).
- Each non‑genesis bft‑block has, in addition to origbft‑block fields, a field containing a sequence of exactly bc‑headers (zero-indexed, deepest first). The genesis bft‑block has .
For a bft‑block or bft‑proposal , define For a bc‑block , define
When is the tip of a node’s bc‑best‑chain, will give the candidate finalization point, subject to a condition described below that prevents local rollbacks.
For a bft‑proposal or <span style="white-space: nowrap">bft‑block $B$,</span> the role of the bc‑chain snapshot referenced by $B\dot\headersbc[0] \trunc_{\bc}^1$ is comparable to the <span style="white-space: nowrap">$\Pi_{\lc}$ snapshot</span> referenced by $B\dot\ch$ in the Snap‑and‑Chat construction from [[NTT2020]](https://eprint.iacr.org/2020/1091.pdf). The motivation for the additional headers is to demonstrate, to any party that sees a bft‑proposal (resp. bft‑block), that the snapshot had been confirmed when the proposal (resp. the block’s proposal) was made.
Typically, a node that is validating an honest bft‑proposal or bft‑block will have seen at least the snapshotted bc‑block (and possibly some of the subsequent bc‑blocks in the $\headersbc$ chain) before. For this not to be the case, the validator’s bc‑best‑chain would have to be more than <span style="white-space: nowrap">$\sigma$ bc‑blocks</span> behind the honest proposer’s bc‑best‑chain at a given time, which would violate the **Prefix Consistency** property <span style="white-space: nowrap">of $\Pi_{\bc}$.</span>
If the headers do not connect to any bc‑valid‑chain known to the validator, then the validator should be suspicious that the proposer might not be honest. It can assign a lower priority to validating the proposal in this case, or simply drop it. The latter option could drop a valid proposal, but this does not in practice cause a problem as long as a sufficient number of validators are properly synced (so that **Prefix Consistency** holds for them).
If the headers *do* connect to a known bc‑valid‑chain, it could still be the case that the whole header chain up to and including $B\dot\headersbc[\sigma-1]$ is not a bc‑valid‑chain. Therefore, to limit denial‑of‑service attacks the validator should first check the Proofs‑of‑Work and difficulty adjustment <span style="white-space: nowrap">—which it can do locally using only the headers—</span> before attempting to download and validate any bc‑blocks that it has not already seen. This is why we include the full headers rather than just the block hashes. Nodes may “trim” (i.e. not explicitly store) headers in a bft‑block that overlap with those referred to by its <span style="white-space: nowrap">ancestor bft‑block(s).</span>
It would be conceptually nice for $\Origin_{\bft}\dot\mathsf{headers}[0] \trunc_{\bc}^1$ to refer to $\Origin_{\bc}$, as well as $\Origin_{\bc}\dot\contextbft$ being $\Origin_{\bft}$ so that <span style="white-space: nowrap">$\bftlastfinal(\Origin_{\bc}\dot\contextbft) = \Origin_{\bft}$.</span> That reflects the fact that we know <span style="white-space: nowrap">“from the start”</span> that neither genesis block can be rolled back.
This is not literally implementable using block hashes because it would involve a hash cycle, but we achieve the same effect by defining a $\snapshot$ function that allows us to “patch” $\snapshot(\Origin_{\bft})$ <span style="white-space: nowrap">to be $\Origin_{\bc}$.</span> We do it this way around rather than “patching” the link from a bc‑block to a bft‑block, because the genesis bft‑block already needs a special case since there are not <span style="white-space: nowrap">$\sigma$ bc‑headers</span> available.
The finality of some bft‑block is only defined in the context of another bft‑block. One possible design would be for a bc‑block to have both $\mathsf{final\_bft}$ and $\contextbft$ fields, so that the finality of $\mathsf{final\_bft}$ could be checked objectively in the context <span style="white-space: nowrap">of $\contextbft$.</span>
However, specifying just the context block is sufficient information to determine its last final ancestor. There would never be any need to give a context block and a final ancestor that is not the last one. The $\bftlastfinal$ function can be computed efficiently for typical BFT protocols. Therefore, having just the $\contextbft$ field is sufficient.
Locally finalized chain
Each node keeps track of a “locally finalized” bc‑chain at time . Each node’s locally finalized bc‑chain starts at . However, this chain state should not be exposed to clients of the node until it has synced.
Node $i$ has **Local finalization linearity** up to time $t$ iff the time series of <span style="white-space: nowrap">bc‑blocks $\localfin_i^{r \,\leq\, t}$</span> is <span style="white-space: nowrap">[bc‑linear](#notation).</span>
When node ’s bc‑best‑chain view is updated from to , the node’s will become if and only if this is a descendant of . Otherwise will stay at . This guarantees Local finalization linearity by construction.
If when making this update, (i.e. and are on different forks), then the node should record a finalization safety hazard. This can only happen if global safety assumptions are violated. Note that Local finalization linearity on each node is not sufficient for Assured Finality, but it is necessary.
This can be expressed by the following state update algorithm, where is the time of the last update and is the time of the current update:
A safety hazard record should include and the history of updates including and since the last one that was an ancestor of .
In any execution of Crosslink 2, for any <span style="white-space: nowrap">node $i$</span> that is honest at <span style="white-space: nowrap">time $t$,</span> there exists a <span style="white-space: nowrap">time $r \leq t$</span> <span style="white-space: nowrap">such that $\localfin_i^t \preceq \ch_i^r \trunc_{\bc}^\sigma$.</span>
Proof: By the definition of $\candidate$ we have $\candidate(\ch_i^u) \preceq \ch_i^u \trunc_{\bc}^\sigma$ for all <span style="white-space: nowrap">times $u$.</span> <span style="white-space: nowrap">Let $r \leq t$</span> be the last time at which <span style="white-space: nowrap">$\localfin_i^t$ changed,</span> or the <span style="white-space: nowrap">genesis time $0$</span> if it has never changed. <span style="white-space: nowrap">Then for $r > 0$</span> we have <span style="white-space: nowrap">$\localfin_i^t = \localfin_i^r = \candidate(\ch_i^r) \preceq \ch_i^r \trunc_{\bc}^\sigma$,</span> and <span style="white-space: nowrap">for $r = 0$</span> we have <span style="white-space: nowrap">$\localfin_i^t = \localfin_i^r = \Origin_{\bc} \preceq \ch_i^r \trunc_{\bc}^\sigma$</span> <span style="white-space: nowrap">(because $\ch_i^0 = \Origin_{\bc}$,</span> and <span style="white-space: nowrap">truncating $\Origin_{\bc}$</span> always <span style="white-space: nowrap">yields $\Origin_{\bc}$).</span>
When a node’s view of the bc‑best‑chain reorgs to a different fork (even if the reorg is shorter than $\sigma$ blocks), it may be the case that $\candidate(\ch_i^t)$ rolls back. If [**Final Agreement**](#final-agreement) of $\Pi_{\bft}$ holds up to time $t$, the new snapshot should in that case be an ancestor of the old one. If all is well then this snapshot will subsequently roll forward along the same path. However, we do not want applications using the node to see the temporary rollback.
Assured Finality is our main safety goal for Crosslink 2. It is essentially the same goal as Final Agreement but applied to nodes’ locally finalized bc‑chains; intuitively it means that honest nodes never see conflicting locally finalized chains. We intend to prove that this goal holds under reasonable assumptions about either or .
An execution of Crosslink 2 has **Assured Finality** iff <span style="white-space: nowrap">for all times $t$, $u$</span> and <span style="white-space: nowrap">all nodes $i$, $j$</span> (potentially the same) such that <span style="white-space: nowrap">$i$ is honest</span> at <span style="white-space: nowrap">time $t$</span> and <span style="white-space: nowrap">$j$ is honest</span> at <span style="white-space: nowrap">time $u$,</span> we have <span style="white-space: nowrap">$\localfin_i^t \agrees_{\bc} \localfin_j^u$.</span>
Note that if an execution of Crosslink 2 has Assured Finality, then all nodes that are honest for that execution have Local finalization linearity. That is because the restriction of Assured Finality to the case is equivalent to Local finalization linearity for node up to any time at which node is honest.
This ensures that the candidate is at least <span style="white-space: nowrap">$\sigma$‑confirmed.</span>
In practice $\candidate(H)$ will rarely differ from $\snapshotlf{H}$, but using the former patches over a potential gap in the safety proof. The [**Last Final Snapshot rule**](#last-final-snapshot-rule) specified later will guarantee that <span style="white-space: nowrap">$\snapshotlf{H} \preceq_{\bc} H$,</span> and this ensures that <span style="white-space: nowrap">$\snapshotlf{H} \agrees_{\bc} H \trunc_{\bc}^\sigma$.</span> However, the depth of $\snapshotlf{H}$ relative to $H$ is not guaranteed to be $\geq \sigma$. For the proof we will need <span style="white-space: nowrap">$\candidate(H) \preceq_{\bc} H \trunc_{\bc}^\sigma$,</span> so that we can use the [**Local fin‑depth lemma**](#local-fin-depth) together with [**Prefix Agreement**](#prefix-agreement) of $\Pi_{\bc}$ at confirmation depth $\sigma$ to prove [**Assured Finality**](#assured-finality).
An alternative would be to change the [**Last Final Snapshot rule**](#last-final-snapshot-rule) to directly require <span style="white-space: nowrap">$\snapshotlf{H} \preceq_{\bc} H \trunc_{\bc}^\sigma$.</span>
$\TODO$ Choose between these options based on what works well for the security proofs and finalization latency.
Locally bounded‑available chain
Define the locally bounded‑available chain on node for bc‑confirmation‑depth , as
Like the locally finalized bc‑chain, this chain state should not be exposed to clients of the node until it has synced.
For any node $i$ that is honest at <span style="white-space: nowrap">time $t$,</span> and any confirmation <span style="white-space: nowrap">depth $\mu$,</span> <span style="white-space: nowrap">$\localfin_i^t \preceq (\localba_\mu)_i^t$.</span>
Proof: By construction of $(\localba_\mu)_i^t$.</span>
In any execution of Crosslink 2, for any <span style="white-space: nowrap">confirmation depth $\mu \leq \sigma$</span> and any <span style="white-space: nowrap">node $i$</span> that is honest at <span style="white-space: nowrap">time $t$,</span> there exists a <span style="white-space: nowrap">time $r \leq t$</span> <span style="white-space: nowrap">such that $(\localba_\mu)_i^t \preceq_{\bc} \ch_i^r \trunc_{\bc}^\mu$.</span>
Proof: Either $(\localba_\mu)_i^t = \localfin_i^t$, in which case the result follows by the [**Local fin‑depth lemma**](#local-fin-depth) since $\mu \leq \sigma$, or $(\localba_\mu)_i^t = \ch_i^t \trunc_{\bc}^\mu$ in which case it follows trivially with $r = t$.
Our security goal for will be Agreement on as already defined.
Assume for this discussion that $\Pi_{\bc}$ uses PoW.
Depending on the value of $\sigma$, the timestamps of bc‑blocks, and the difficulty adjustment rule, it can be the case that if $\localfin_i$ switches to a different fork, the difficulty on that fork is greater than on the chain of the previous snapshot. Then, the new bc‑chain could reach a higher score than the previous chain in fewer than <span style="white-space: nowrap">$\sigma$ blocks</span> from the fork point, and so $\ch_i^t \trunc_{\bc}^\mu$ might not be a descendant of $\localfin_i^t$ (which is more likely <span style="white-space: nowrap">if $\mu = \sigma$).</span> This can occur even when all safety assumptions are satisfied.
For [Zcash’s difficulty adjustment algorithm](https://zips.z.cash/protocol/protocol.pdf#diffadjustment), the difficulty of each block is adjusted based on the median timestamps and difficulty target thresholds over a range of <span style="white-space: nowrap">$\mathsf{PoWAveragingWindow} = 17$ blocks,</span> where each median is taken over <span style="white-space: nowrap">$\mathsf{PoWMedianBlockSpan} = 11$ blocks.</span> Other damping factors and clamps are applied in order to prevent instability and to reduce the influence that adversarially chosen timestamps can have on difficulty adjustment. This makes it unlikely that an adversary could gain a significant advantage by manipulating the difficulty adjustment. So it is safe to use $\localfin_i^t$ in this case: even though it does not have <span style="white-space: nowrap">$\mu$ confirmations</span> relative to <span style="white-space: nowrap">$\ch_i^t$,</span> it does have at least the required amount of work “on top” of it.
Defining $(\localba_\mu)_i^t$ this way also has the advantage of making the proof of the **Ledger prefix property** trivial.
Syncing and checkpoints
It is recommended that node implementations “bake in” a checkpointed bft‑block to each released version, and that node should only expose and to its clients once it is “synced”, that is:
- ; and
- ; and
- the timestamp of is within some threshold of the current time.
Πbft changes from Πorigbft
Πbft proposal and block validity
Genesis bft‑block rule: is bft‑block‑valid.
A bft‑proposal (resp. non‑genesis bft‑block) is bft‑proposal‑valid (resp. bft‑block‑valid) iff all of the following hold:
- Inherited origbft rules: The corresponding origbft‑proposal‑validity (resp. origbft‑block‑validity) rules hold for .
- Linearity rule: .
- Tail Confirmation rule: form the ‑block tail of a bc‑valid‑chain.
The “corresponding validity rules” are assumed to include the Parent rule that ’s parent is bft‑valid.
Note: origbft‑block‑validity rules may be different to origbft‑proposal‑validity rules. For example, in adapted Streamlet, a origbft‑block needs evidence that it was voted for by a supermajority, and an origbft‑proposal doesn’t. Such differences also apply to bft‑block‑validity vs bft‑proposal‑validity.
The reason to separate the validity rules from the honest voting condition, is that the validity rules are objective: they don’t depend on an observer’s view of the bc‑best‑chain. Therefore, they can be checked independently of validator signatures. Even a proposal voted for by 100% of validators will not be considered bft‑proposal‑valid by other nodes unless it satisfies the above rules. If more than two thirds of voting units are cast for an **invalid** proposal, something is seriously *and visibly* wrong; in any case, the block will not be accepted as a bft‑valid‑block. Importantly, a purportedly valid bft‑block will not be recognized as such by *any* honest Crosslink 2 node even if it includes a valid notarization proof, if it does not meet other bft‑block‑validity rules.
This is essential to making the finalized chain safe against a flaw in $\Pi_{\bft}$ or its security assumptions (even, say, a complete break of the validator signature algorithm), as long as $\Pi_{\bc}$ remains safe.
This rule is key to combining simplicity with strong security properties in Crosslink 2. It essentially says that, in a given bft‑valid‑chain, the snapshots pointed to by blocks in that chain cannot roll back.
This allows the informal safety argument for Crosslink 2 to be rather intuitive.
Informally, if $\Pi_{\bft}$ has [**Final Agreement**](#final-agreement), then all nodes see only one consistent [bft‑linear](#notation) chain (restricting to bft‑blocks that are final in the context of some bft‑block [in honest view](#in-honest-view)). Within such a bft‑chain, the [**Linearity rule**](#linearity-rule) ensures *by construction* that the sequence of referenced bc‑chain snapshots is [bc‑linear](#notation). This implies [**Assured Finality**](#assured-finality), without needing to assume any safety property of $\Pi_{\bc}$.
We will *also* be able to prove safety of the finalized snapshots based only on safety of $\Pi_{\bc}$ (for a confirmation depth of $\sigma$), without needing to assume any safety property of $\Pi_{\bft}$. Informally, that is because each node sees each candidate final snapshot at a given time as a $\sigma$-confirmed prefix of its bc‑best‑chain at that time (this can be proven based on the [**Last Final Snapshot rule**](#Πbc-changes-from-Πorigbc) and the fact that a snapshot includes $\sigma$ subsequent headers), and [**Prefix Agreement**](#prefix-agreement) implies that honest nodes agree on this prefix. We will leave a more detailed argument until after we have presented the <span style="white-space: nowrap">[$\Pi_{\bc}$ changes from $\Pi_{\origbc}$](#Πbc-changes-from-Πorigbc).</span>
The [**Linearity rule**](#linearity-rule) replaces the “Increasing Score rule” used in Crosslink 1. The Increasing Score rule required that each snapshot in a bft‑valid‑chain either be the same snapshot, or a higher-scoring snapshot to that of its parent block. Since scores strictly increase within a bc‑valid‑chain, the [**Linearity rule**](#linearity-rule) *implies* the Increasing Score rule. It retains the same or stronger positive effects:
* It prevents potential attacks that rely on proposing a bc‑valid‑chain that forks from a much earlier block. This is necessary because the difficulty (or stake threshold) at that point could have been much lower.
* It limits the extent of disruption an adversary can feasibly cause to the bounded‑available <span style="white-space: nowrap">chain $\ch_i$,</span> *even if* it has <span style="white-space: nowrap">subverted $\Pi_{\bft}$.</span> Informally, because the finalized chain *is* a $\Pi_{\bc}$ chain, its safety is no worse than $\Pi_{\bc}$ alone for a rollback of *any* depth.
* It ensures that either progress is made (the snapshot advances relative to that of the parent bft‑block), *or* there is no further validation that needs to be done for the snapshot because it was already validated.
Note that the adversary could take advantage of an “accidental” fork and start its attack from the base of that fork, so that not all of this work is done by it alone. This is also possible in the case of a standard “private mining” attack, and is not so much of a problem in practice because accidental forks are expected to be short. In any case, <span style="white-space: nowrap">$\sigma$ should</span> be chosen to take it into account.
The [**Linearity rule**](#linearity-rule) is also critical to removing the need for one of the most complex elements of Snap‑and‑Chat and Crosslink 1, “sanitization”. In those protocols, because bc‑chain snapshots could be unrelated to each other, it was necessary to sanitize the chain formed from these snapshots to remove transactions that were contextually invalid (e.g. because they double‑spend). The negative consequences of this are described in [Notes on Snap‑and‑Chat](./notes-on-snap-and-chat.md); avoiding it is much simpler.
The linearity property is intentionally always relative to the snapshot of the parent bft‑block, even if it is not final in the context of the current bft‑block. This is because the rule needs to hold if and when it becomes final in the context of some descendant bft‑block.
$\TODO$ PoS Desideratum: we want leader selection with good security / performance properties that will be relevant to this rule. (Suggested: [PoSAT](https://arxiv.org/pdf/2010.08154.pdf).)
This is necessary in order to preserve liveness of $\Pi_{\bft}$ relative <span style="white-space: nowrap">to $\Pi_{\origbft}$.</span> Liveness of $\Pi_{\origbft}$ might require honest proposers to make proposals at a minimum rate. That requirement could be consistently violated if it were not always possible to make a valid proposal. But given that it is allowed to repeat the same snapshot as in the parent bft‑block, neither the [**Linearity rule**](#linearity-rule) nor the [**Tail Confirmation rule**](#tail-confirmation-rule) can prevent making a valid proposal — and all other rules of $\Pi_{\bft}$ affecting the ability to make valid proposals are the same as <span style="white-space: nowrap">in $\Pi_{\origbft}$.</span> <span style="white-space: nowrap">(In principle,</span> changes to voting in $\Pi_{\bft}$ could also affect its liveness; we’ll discuss that in the liveness proof later.)
For example, Streamlet requires three notarized blocks *in consecutive epochs* in order to finalize <span style="white-space: nowrap">a block [[CS2020](https://eprint.iacr.org/2020/088.pdf), section 1.1].</span> Its proof of liveness depends on the assumption that in each epoch for which the leader is honest, that leader will make a proposal, and that during a “period of synchrony” this proposal will be received by <span style="white-space: nowrap">every node [[CS2020](https://eprint.iacr.org/2020/088.pdf), section 3.6].</span> This argument can also be extended to adapted‑Streamlet.
We could alternatively have allowed to always make a “null” proposal, rather than to always make a proposal with the same snapshot as the parent. We prefer the latter because the former would require specifying the rules for null proposals <span style="white-space: nowrap">in $\Pi_{\origbft}$.</span>
As a clarification, no BFT protocol that uses leader election can *require* a proposal in each epoch, because the leader might be dishonest. The above issue concerns liveness of the protocol when assumptions about the attacker’s share of bft‑validators or stake are met, so that it can be assumed that sufficiently long periods with enough honest leaders to make progress <span style="white-space: nowrap">(5 consecutive</span> epochs in the case of Streamlet), will occur with significant probability.
Πbft block finality in context
The finality rule for bft‑blocks in a given context is unchanged from origbft‑finality. That is, is defined in the same way as (modulo referring to bft‑block‑validity and ).
Πbft honest proposal
An honest proposer of a bft‑proposal chooses as the ‑block tail of its bc‑best‑chain, provided that it is consistent with the Linearity rule. If it would not be consistent with that rule, it sets to the same field as ’s parent bft‑block. It does not make proposals until its bc‑best‑chain is at least blocks long.
If the length were less than $\sigma + 1$ blocks, it would be impossible to construct the $\headersbc$ field of the proposal.
Note that when the length of the proposer’s bc‑best‑chain is exactly $\sigma + 1$ blocks, the snapshot must be of $\Origin_{\bc}.$ But this does not violate the [**Linearity rule**](#linearity-rule), because $\Origin_{\bc}$ matches the previous snapshot by $\Origin_{\bft}$.
As in the answer to [Why is the ‘otherwise’ case in the definition of $(\localba_\mu)_i^t$ necessary?](#admonition-why-is-the-otherwise-case-in-the-definition-of-bai%CE%BCt-necessary) above, after a reorg on the bc‑chain, the $\sigma$-confirmed block on the new chain might not be a descendant of the $\sigma$-confirmed block on the old chain, which could break the [**Linearity rule**](#linearity-rule).
Πbft honest voting
An honest validator considering a proposal , first updates its view of both subprotocols with the bc‑headers given in , downloading bc‑blocks for these headers and checking their bc‑block‑validity.
For each downloaded bc‑block, the bft‑chain referenced by its field might need to be validated if it has not been seen before.
In general the entire referenced bft‑chain needs to be validated, not just the referenced block — and for each bft‑block, the bc‑chain in $\headersbc$ needs to be validated, and so on recursively. If this sounds overwhelming, note that:
* We should check the requirement that a bft‑valid‑block must have been voted for by a two‑thirds absolute supermajority of validators, and any other *non‑recursive* bft‑validity rules, *first*.
* Before validating a bc‑chain referenced by a $\headersbc$ field, we check that it connects to an already-validated bc‑chain and that the Proofs‑of‑Work are valid. This implies that the amount of bc‑block validation is constrained by how fast the network can find valid Proofs‑of‑Work.
* The [**Linearity rule**](#linearity-rule) reduces the worst‑case validation effort, by ensuring that only one bc‑chain needs to be validated for any bft‑chain. Assuming safety of $\Pi_{\bft}$ and that the adversary does not have an overwhelming advantage in computing the Proof‑of‑Work, this is effectively only one bc‑chain overall with, at most, short side branches.
In summary, the order of validation is important to avoid denial‑of‑service — but it already is in Bitcoin and Zcash.
After updating its view, the validator will vote for a proposal only if:
- Valid proposal criterion: it is bft‑proposal‑valid, and
- Confirmed best‑chain criterion: is part of the validator’s bc‑best‑chain at a bc‑confirmation‑depth of at least .
The **Confirmed best‑chain criterion** is quite subtle. It ensures that $\snapshot(P) = P\dot\headersbc[0] \trunc_{\bc}^1$ is bc‑block‑valid and has $\sigma$ bc‑block‑valid blocks after it in the validator’s bc‑best‑chain. However, it need not be the case that $P\dot\headersbc[\sigma-1]$ is part of the validator’s bc‑best‑chain after it updates its view. That is, the chain could fork after $\snapshot(P)$.
The bft‑proposal‑validity rule must be objective; it can’t depend on what the validator’s bc‑best‑chain is. The validator’s bc‑best‑chain *may* have been updated to $P\dot\headersbc[\sigma-1]$ (if it has the highest score), but it also may not.
However, if the validator’s bc‑best‑chain *was* updated, that makes it more likely that it will be able to vote for the proposal.
In any case, if the validator does not check that all of the blocks referenced by the headers are bc‑block‑valid, then its vote may be invalid.
Snap‑and‑Chat already had the voting condition:
> An honest node only votes for a proposed BFT block $B$ if it views $B\dot\ch$ as confirmed.
but it did *not* give the headers potentially needed to update the validator’s view, and it did not require a proposal to be for an *objectively confirmed* snapshot as a matter of validity.
If a Crosslink‑like protocol were to require an objectively confirmed snapshot but without including the bc‑headers in the proposal, then validators would not immediately know which bc‑blocks to download to check its validity. This would increase latency, and would be likely to lead proposers to be more conservative and only propose blocks that they think will *already* be in at least a two‑thirds absolute supermajority of validators’ best chains.
That is, showing $P\dot\headersbc$ to all of the validators is advantageous to the proposer, because the proposer does not have to guess what blocks the validators might have already seen. It is also advantageous for the protocol goals in general, because it improves the trade‑off between finalization latency and security.
Πbc changes from Πorigbc
Πbc block validity
Genesis bc‑block rule: For the genesis bc‑block we must have , and therefore .
A bc‑block is bc‑block‑valid iff all of the following hold:
- Inherited origbc rules: satisfies the corresponding origbc‑block‑validity rules.
- Valid context rule: is bft‑block‑valid.
- Extension rule: .
- Last Final Snapshot rule: .
- Finality depth rule: Define: Then either or .
The finality depth must be objectively defined, since it is used in a consensus rule. Therefore it should measure the height of $H$ relative to $\snapshotlf{H}$, which is an objectively defined function of $H$, rather than relative to $\localfin_i^t$. (These will only differ for $H = \ch_i^t$ when node $i$ has just reorged, and only then in corner cases.)
Note that the [**Last Final Snapshot rule**](#last-final-snapshot-rule) ensures that it is meaningful to simply use the difference in heights, since $\snapshotlf{H} \preceq_{\bc} H$.
Πbc contextual validity
The consensus rule changes above are all non-contextual. Modulo these changes, contextual validity in is the same as in .
Πbc honest block production
An honest producer of a bc‑block must follow the consensus rules under block validity above. In particular, it must produce a stalled block if required to do so by the Finality depth rule.
To choose , the producer considers a subset of the tips of bft‑valid‑chains in its view: It chooses one of the longest of these chains, , breaking ties by maximizing , and if there is still a tie then by taking with the smallest hash.
The honest block producer then sets to .
An honest bc‑block‑producer must not use information from the BFT protocol, other than the specified consensus rules, to decide which bc‑valid‑chain to follow. The specified consensus rules that depend on $\Pi_{\bft}$ have been carefully constructed to preserve safety of $\Pi_{\bc}$ relative <span style="white-space: nowrap">to $\Pi_{\origbc}$.</span> Imposing any additional constraints could potentially allow an adversary that is able to <span style="white-space: nowrap">subvert $\Pi_{\bft}$,</span> to influence the evolution of the bc‑best‑chain in ways that are not considered in the safety argument.
The effect of this would be to tend to more often follow the last bft‑block seen by the producer of the parent bc‑block, if there is a choice. It is not always possible to do so, though: the resulting set of candidates <span style="white-space: nowrap">for $C$</span> might be empty.
Also, it is not clear that giving the parent bc‑block‑producer the chance to “guide” what bft‑block should be chosen next is beneficial, since that producer might be adversarial and the resulting incentives are difficult to reason about.
We could have instead chosen $C$ to maximize the length <span style="white-space: nowrap">of $\bftlastfinal(C)$.</span> The rule we chose follows Streamlet, which builds on the longest notarized chain, not the longest finalized chain. This may call for more analysis specific to the chosen BFT protocol.
Choosing the bft‑chain that has the last final snapshot with the highest score, tends to inhibit an adversary’s ability to finalize its own chain if it has a lesser score. (If it has a greater score, then it has already won a hash race and we cannot stop the adversary chain from being finalized.)
For discussion of potentially unifying the roles of bc‑block producer and bft‑proposer, see What about making the bc‑block‑producer the bft‑proposer? in Potential changes to Crosslink.
At this point we have completed the definition of Crosslink 2. In Security Analysis of Crosslink 2, we will prove it secure.
Engineering Deliverables for Shielded Lab's Crosslink Deployment
This is a draft list of SL's engineering deliverables as part of our Crosslink Deployment project. This list may be refined as the project develops, both to provide greater precision or clarity around deliverables, or to add or potentially remove deliverables (ideally only in early phases of the project lifecycle).
Code Products
The active list of Code Deliverables is evolving on GitHub, and includes these major components:
- a full node implementation of the Crosslink protocol - intended for use by all full node users
- GH #154 a basic working commandline finalizer (probably as a configured mode of the full node) - potentially used by production finalizers
- GH #106 a basic, minimal stake delegation tool - this will not be an easily usable or recommended product for end users
- GH #112 all necessary Continuous Integration / Continuous Deployment source code is an explicit code deliverable
All code products will be open source and suitable for merging or bundling with zebra source and binary distributions.
All code products will be first developed and released as testnet prototypes which are then matured into production-ready status as the target activation date approaches.
Technical Documentation
The active list of Documentation Deliverables is evolving on GitHub, and includes these important components:
- User facing documentation about Crosslink finality and safety considerations, including links to assessments, analyses, and audits by other parties.
- User facing documentation for users of all code deliverables.
- Design notes on prototype design trade-offs, delegation secure UX considerations, and a "Staking in Zcash" primer for PoS protocol-expert audiences.
- A Productionization Plan describing the process to develop the prototype into a safe mainnet production deployment and activation process.
- Process documentation for code releases, testnet deployments, and documentation releases intended for current and future maintainers, and developers.
External Validation Partnerships
While not deliverables per se, a key strategy we'll use for gauging our success is to establish working relationships with partner teams which are representative stakeholders for these categories:
- Wallet developers
- Finalizers
- Exchanges
- Bridges, DEXes, or other protocol-integration product teams
Our success criteria require user-facing in-production products in these categories (with the first three prioritized). In order to meet these criteria, we need to engage with high quality partners to serve as representative stakeholders relatively early in the process, as the prototype approaches a usable state. We track ongoing Partner Validation goals on GitHub.
The Five Component Model
There are five components of the system. Each component is responsible for preventing certain attacks, or for holding other components accountable.
Wallets
The job of the wallet is to protect a user’s funds and to enable sending or receiving funds safely.
When receiving funds, the wallet verifies that the incoming funds total to a specific amount, safe against rollbacks, and available to be respent in the future. Additionally, wallets that prioritize user privacy often ensure all incoming funds become shielded to protect the user against unintentional on-chain privacy leaks.
When sending funds, the wallet minimizes all information leakage except those details a user explicitly requests to disclose to certain parties, or those details which must be disclosed. Zcash relies on strong encryption for all information where possible given a transaction type. Privacy is also a protection against censorship, since a censor must either identify specific transactions to censor, or perform blanket or probabilistic censorship in a less effective manner. However, some information disclosures or leakages are inevitable:
- Some information disclosures are always necessary for certain transactions:
- The amount, timing, and memo always needs to be disclosed to the recipient.
- The recipient’s receiving address is always known to a sender.
- Some other kinds of transactions require that some of the information is disclosed to specific parties or to the public in order to achieve certain kinds of desirable transparency. Examples include coin-voting, bridges/DEXes/L2’s, CEXes, turnstile migrations, t-addresses for backward compatibility, staking, unstaking, and redelegating.
- Some information “leakage” occurs even when not theoretically necessary for a given kind of transaction, especially by correlation with off-chain activity, such as:
- The recipient will often know something about the sender’s relationship with them, may be able to learn the sender’s IP address, etc. Therefore if the recipient colludes with the attacker, encryption cannot entirely protect against censorship by itself.
- It is also the responsibility of the wallet to protect the user against censorship attacks that leverage network-level information leakage. Wallets can and should use network-level protections against information leakage such as Tor or Nym.
Miners
The job of the miners is to include transactions and advance the blockchain, which provides an additional kind of censorship-resistance, in addition to the kind of censorship-resistance provided by wallets encrypting the transaction contents when possible. This function of miners also provides liveness. However the miners cannot unilaterally violate finality, even if an attacker controls >½ of the hashpower, because the finalizers ensure finality regardless of the behavior of the miners. A majority of the miners (>½ of the hashpower) can violate censorship-resistance (except when it can be provided by the wallet with encryption).
Finalizers
The job of the finalisers is to ensure finality (i.e. to prevent rollback attacks) but finalisers cannot unilaterally compromise liveness or censorship-resistance (even if an attacker controls >⅔ of the stake-weighted votes) because miners ensure those properties. Also the finalisers cannot unilaterally execute rollback attacks even though they can prevent rollback attacks. A plurality of the finalisers (controlling >⅓ of the stake-weighted votes) could execute stall attacks (i.e. violate liveness).
Stakers
It is the job of the stakers to hold the finalisers accountable by detecting and punishing misbehavior on the part of the finalizers by redelegating stake away from ill-behaved finalizers to well-behaved finalizers.
Users
It is the duty of the users, collectively, to hold the stakers accountable for doing their job. If the stakers fail in their duty to hold the finalizers accountable, they can be disempowered and punished for this failure by the users with an emergency user-led hard fork (which is what happened in the STEEM/HIVE hard fork). We clarify how we envision this could work with more safety and preparedeness by the Zcash community in the User-Led Emergency Hardforks.
Attacker Resource Scenarios
When considering these components, it is useful to consider scenarios where an attacker has compromised some portion of each kind of component, as a coarse means of assessing the robustness of Crosslink in maintaining the security properties.
- A collusion that controlled both >½ of the hashpower and >⅔ of the stake.
- ...could violate finality.
- A collusion that included both a majority of the miners (controlling >½ of the hashpower) and a supermajority of the finalizers (controlling >⅔ of the stake-weighted votes)
- ...could execute rollback and unavailability attacks.
Censorship-resistance is necessary for stakers to stake, unstake, and redelegate, which means censorship-resistance is necessary for stakers to be able to perform their duty of holding the finalizers accountable. Therefore, if an attacker controls >½ of the hashpower (and is thereby able to censor), then the attacker can prevent the stakers from holding the finalizers accountable.
An important and under-investigated consideration is what security properties hold when an attacker controls a minority of the hashpower. In a pure-PoW system, an attacker that controls some hashpower but ≤½ of it can not completely censor transactions, but can force them to be delayed.
- A collusion that controls >⅔ of the stake and <½ of the hashpower.
Crosslink Design in a Nutshell
This chapter covers the major components of the design. This presents the design positively, without rationales, trade-offs, safety anlyses, or other supporting information. This will eventually be entirely redundant with, or simply link to, a canonical Zcash Improvement Proposal submission. Treat this chapter as a provisional sketch.
It assumes and leverages familiarity with Zcash PoW and only describes new differences from today's mainnet.
CAVEATS: A lot of the terminology and descriptions will be adjusted as we go to follow conventions and specifications in the Zcash Protocol Specification and the Zcash Improvement Proposals.
Roles and Capabilities
We rely on several roles described in the Five Component Model in this nutshell section along with their intended capabilities. The absence of an explicit capability description for a role implies that role should not be able to perform that capability
Changes to Transactions
Changes to the Coinbase Transaction
The coinbase transaction is an exceptional transaction Zcash inherited from Bitcoin which follows exceptional rules, including the distribution of newly issued tokens. This transaction is created by a block's miner.
The consensus rules are updated to require this transaction to make transfers of a portion of newly issued ZEC dedicated to Crosslink rewards only when this block updates finality to a greater height, and then as the sum of all pending finalization rewards since the previous finalization.
For each block produced which does not update finality, the per-block Crosslink rewards are collected into a running total, and a block which updates finality must then distributed this entire pending amount to the stakers and finalizers determined from the active set used to produce the finality update.
The pending finalizaiton rewards, , in a block which updates finality must be distributed by the coinbase transaction to finalizers and stakers proportionally to their reward slice, , where the active set (defined below) refers to the state as of the most recent final block, prior to this update.
This is calculated as follows where we let be the total stake weight for that participant:
-
For finalizers in the active set:
The constant is a fixed protocol parameter called the commission fee rate.
-
For all stakers:
The constant is called the staker reward rate.
Note that is the total weight of all staking positions of the given staker regardless of whether or not it is assigned to an finalizer in the active set.
Another nuance: the sum of all commission fees and staker rewards adds up to or less, with the difference coming from stake assigned to finalizers outside the active set.
New Transaction Format & Staking Actions
A new transaction format is introduced which contains a new optional field for staking actions, which enable operations such as staking ZEC to a finalizer, beginning or completing an unstaking action, or redelegating an existing staking position to a different delegator.
The ZEC flowing into staking actions, or flowing out of completing unstaking transactions must balance as part of the transactions chain value pool balancing. See The Zcash Protocol §4.17 Chain Value Pool Balances.
Additionally, we introduce a new restricting consensus rule on context-free transaction validity1:
A context-free transaction validity check may be performed on the bytes of the transaction itself without the need to access any chain state or index.
Crosslink Staking Orchard Restriction:
A transaction which contains any staking actions must not contain any other fields contributing to or withdrawing from the Chain Value Pool Balances except Orchard actions, explicit transaction fees, and/or explicit ZEC burning fields.
Abstractly, the staking actions include:
- _stake - This creates a new staking position assigning a transparent ZEC amount, which must be a power of 10, to a finalizer and including a cryptographic signature verification key intended for only the signing-key holder of the position to redelegate or unstake.
- redelegate - This identifies a specific staking position, a new finalizer to reassign to, and a signature valid with the position's published verification key to authorize the transition.
- unbond - This initiates an "unbonding process" which puts the staking position into an unbonding state and includes the ZEC amount, the current block height, and the signature verification key to authorize a later claim. Once in this state, redelegations are not valid and the ZEC amount does not contribute to staking weight for finalizers or the staker.
- claim - This action removes a position in the unbonding state and contributes the bonded ZEC into the transaction's Chain Value Pool Balance, where because of the "Crosslink Staking Orchard Restriction, it may only be distributed into an Orchard destination and/or transaction fees.
Further Restrictions on Staking Actions
We furthermore introduce the following consensus rule restrictions on transactions involving staking actions which rely on a staking epoch design:
Staking Epoch Definition:
Once Crosslink activates at block height , staking epochs begin, which are continguous spans of block heights with two phases: staking day and the locked phase. The number of blocks for staking day is a protocol parameter constant roughly equivalent to 24 hours given assumptions about the Difficulty Adjustment Algorithm. The number of blocks for the locked phase is also a constant roughly equivalent to 6*24 hour periods, so that staking day is approximately one day per week.
Given the staking epoch definition, we introduce the following restrictions in the consensus rules:
Locked Staking Actions Restriction:
If a transaction includes any staking actions except for redelegate, and that transaction is in a block height in a locked phase of the staking epoch, then that block is invalid.
Also:
Unbonding Delay:
If a transaction is block height includes any claim staking actions which refer to unbonding state positions which have not existed in the unbonding state for at least one full staking epoch, that block is invalid.
Note: An implication of the Unbonding Delay is that the same staking day cannot include both an unbond and claim for the same position.
A final restriction (already mentioned above in introducing the staking action is:
Stake Action Amount Quantization:
If a transaction includes any staking actions with an amount which is not a power of 10 ZEC (or ZAT), that transaction is invalid.
Changes to Ledger State
The Ledger State is a conceptual and practical data structure which can be computed by fully verifying nodes solely from the sequence of blocks starting from the genesis block.2 To this Ledger State, Crosslink introduces the roster which is a table containing all of the information about all ZEC staked to finalizers.
Theoretically all of the Ledger State could be purely computed on demand from prior blocks, so literal Ledger State representations in memory can be thought of as chain indices or optimizing caches for verifying consensus rules. In some cases components of the Ledger State must be committed to within the blockchain state itself (for example, commitment anchors) which constrains how lazy a theoretical implementation can be. Real implementations trade off caching vs lazy-computation in a fine-grained way to achieve practical goals.
The Roster
Crosslink's addition to Ledger State is embodied in the PoS roster, aka the roster for short. Which tracks staking positions created by Stakers, and attached to specific Finalizers. A Finalizer has a "voting weight" equal to the sum of all staking positions attached to it (see below in FIXME).
Each staking position is composed of at least a single specific target finalizer verification key, a staked ZEC amount, and a unstaking/redelegation verification key. The finalizer verification key designates a cryptographic signature verification key which serves as the sole on-chain reference to a specific finalizer3. People may mean a specific person, organization, entity, computer server, etc... when they say "finalizer", but for the rest of this document we will use the term finalizer as a shorthand for "whichever entity controls the verification key for a given finalizer verification key.
Any particular entity may produce any number of finalizer verifying keys of course, although for economic or social reasons, we expect many finalizers to be motivated to hang their reputation on 1 or just a few well-known finalizer verifying keys.
The unstaking/redelegation verifying key enables unstaking or redelegating that position from the participant that created that position (or more precisely anyone who controls the associated verifying key, which should be managed by a good wallet on behalf of users without their need to directly know or care about these keys for safe operation). These are unique to the position itself (and not linked on-chain to a user's other potential staking positions or other activity).
The sum of outstanding staking positions designating a specific finalizer verification key at a given block height is called the stake weight of that finalizer. At a given block height the top K (currently 100) finalizers by stake weight are called the active set of finalizers.
Ledger State Invariants
We adopt a design invariant around the Ledger State changes Crosslink makes against mainnet Zcash:
General Ledger State Design Invariant:
All changes to Ledger State can be computed entirely from (PoW) blocks, transactions, and data transitively referred to by such. This includes all existing Ledger State in mainnet Zcash today, the PoS and BFT roster state (see below), and the finality status of blocks and transactions.
All current mainnet Zcash Ledger State and almost all Crosslink Ledger State is height-immediate Ledger State: the value for height can be computed from height itself (and implicitly all prior heights and contents). Some examples of height-immediate values are the total ZEC issued, the UTXOs spendable by the same P2PKH t-addr, the block's zero-knowledge commitment anchor values, and so on. In Crosslink examples include all of the roster state (e.g. the active set, finalizer verification keys, staking positions, ...).
Height-Eventual Ledger State
Crosslink introduces a novel category of Ledger State not present in Zcash mainnet, which is height-eventual Ledger State. This is a property or value about height which is only computable at a later larger height (of which the implicit block at must be an ancestor). The sole example of this is finality status.
The finality status of a block at height (and by extension any transactions it contains and all previous block contents) is a property which guarantees[^guarantees] to the verifying node that this block (and all txns and previous content) is final and cannot be reverted or rolled back. Furthermore, the presence of this property also provides a guarantee that a majority of finalizers already agree on the finality status of this block and also that all verifying nodes which see a sufficient number of subsequent blocks will also agree on the finality status.
[^guarantees] In this book, whenever we say a protocol "guarantees" some condition, we mean that so long as the security assumptions truly hold verifying nodes can and should safely rely on that condition.
The finality status of a block at height (which we'll call a finality-candidate block here for precision) is computable from a block at a later height (which we'll call the attesting block). All verifying nodes who have observed the that attesting block will agree on the finality of the candidate block even though they may observe the attesting block rollback. In the event of such a rollback, the protocol guarantees that an alternative block will eventually attest to the finality status of the same candidate block.
Finality, Transaction Semantics, Ledger State, and the Roster
It bears pointing out a nuance: the Ledger State, including the Roster and the Active Set are all determined by valid transactions within PoW blocks. Every PoW block height thus has a specific unambiguous Ledger State. This comes into play later when we consider finality which is a property of a given block height which is only verifiable at a later block height.
The BFT Sub-Protocol
TODO: Flesh out this section
TODOS from deep dive:
- rewards distribution to stakers and finalizers requires changes to the Coinbase transaction.
- how finality status is calculated
- how BFT operates, votes, network, etc...
- active set selection
- quantization of amounts / time
- the power of 10 restriction on amount is only applied to "stake" (create position)
- how do staking actions pay fees?
Scope for Crosslink
What are our goals for the first deployment of Crosslink?
Rationale
Why add a Proof-of-Stake finality gadget?
- The Proof-of-Stake finality gadget adds crosslink finality, which protects users from being robbed, improves the safety and efficiency of bridges, and enables centralized exchanges, decentralized exchanges, and other services to reduce and unify deposit times.
- Proof-of-Stake provides a different and complementary kind of security that pure Proof-of-Work doesn't, by allowing the value at stake (which inventivizes defenders to protect users) to be cumulative instead of transient. This makes Zcash more secure—it provides better security for the same security budget. It also makes Zcash more sustainable—it provides long-term security even as the rate of issuance shrinks, which strengthens assurance that the 21M supply cap will be maintained.
- Proof-of-Stake replaces some of the sell pressure from miners with buy pressure from finalizers. This is good because the price of ZEC is the fuel for the mission and attracts users.
- Proof-of-Stake allows a larger number of users to participate actively in the network than mining does, and to become direct recipients of ZEC issued by the blockchain. This increases the size and diversity of the set of users and stakeholders 1.
In Proof-of-Work, smaller miners have a substantial economic disadvantage compared to larger mining operations, resulting in almost all hashpower being controlled by a few large miners. This economic disadvantage is reduced in Proof-of-Stake finalization—smaller finalizers have less of an economic disadvantage compared to larger finalizers. The economic disadvantage is almost eliminated in Proof-of-Stake delegation—smaller delegators compete on a level playing field with larger delegators, earning roughly the same reward with roughly the same risk.
Why Keep the Proof-of-Work blockchain?
- Proof-of-Work provides a different and complementary kind of security that pure Proof-of-Stake doesn’t, by requiring a recurring, non-reusable, and non-recoverable expenditure (by defenders and potential attackers). This prevents attackers from re-using resources in attacks (whether simultaneous or successive attacks). Crosslink security is therefore more robust and self-healing against large-scale attacks than pure Proof-of-Stake security.
- Proof-of-Work provides excellent liveness, availability, and censorship-resistance (which complements the censorship-resistance provided by using end-to-end-encryption whenever possible).
- Proof-of-Work allows people to earn ZEC by mining, even if they don’t already own any ZEC and they can’t acquire ZEC any other way.
- Keeping Proof-of-Work in addition to adding Proof-of-Stake means that in addition to adding the stakers, we also keep miners as active participants in the network and recipients of ZEC, increasing the size and diversity of the Zcash network and the ZEC economy.
UX goals
This list of UX Goals is tracked on GitHub.
- CEXes (GH #131) and decentralized services like DEXes/bridges (GH #128) are willing to rely on Zcash transaction finality. E.g. Coinbase reduces its required confirmations to no longer than Crosslink finality. All or most services rely on the same canonical (protocol-provided) finality instead of enforcing their own additional delays or conditions, so users get predictable transaction finality across services.
- GH #127: Casual users (who understand little about crypto and do not use specialized tools such as a Linux user interface) delegate ZEC and get rewards from their mobile wallet. GH #124 They have to learn a minimal set of new concepts in order to do this.
- GH #158: Users can get compounding returns by leaving their stake plus their rewards staked, without them or their wallet having to take action.
- GH #126: Skilled users (who understand more and can use specialized tools) run finalizers and get rewards.
- GH #214: Skilled users can easily collect records of finalizer behavior and performaance.
Shielded Labs’s First Deployment of Crosslink is not done until substantial numbers of real users are actually gaining the above benefits.
Deployment Goals
This list of Deployment Goals is tracked on GitHub.
- GH #125: Zcash transactions come with a kind of finality which protects the users as much as possible against all possible attacks, and is sufficient for services such as cross-chain bridges and centralized exchanges.
- GH #124: Users can delegate their ZEC and earn rewards, safely and while needing to learn only the minimal number of new concepts.
- Delegating to a finalizer does not enable the finalizer to steal your funds.
- Delegating to a finalizer does not leak information that links the user's action to other information about them, such as their IP address, their other ZEC holdings that they are choosing not to stake, or their previous or future transactions.
- GH #123: The time-to-market and the risk of Shielded Labs's First Deployment of Crosslink is minimized: the benefits listed above start accruing to users as soon as safely possible.
- GH #122: Activating Crosslink on Zcash mainnet retains as much as possible of Zcash users' safety, security, privacy, and availability guarantees.
Trade-offs
Goals which we currently believe are not safely achievable in this first deployment without losing some of the above goals:
- Improving Zcash's bandwidth (number of transactions per time) or latency (time for a transaction).
- Deploying cross-chain interoperation such as the Inter-Blockchain Communication protocol (IBC) or Cross-Chain Interoperability Protocol (CCIP).
- Supporting a large number of finalizers so that any user who wants to run their own finalizer can do so.
- Supporting casual users, with little computer expertise, running finalizers.
Non-Goals
- The consensus mechanism is needed primarily to prevent double-spending/multi-spending/rollback attacks. It is not the primary provider of censorship-resistance, since that is provided primarily by end-to-end encryption, and it is not the primary provider of counterfeiting-resistance, since that is provided by proofs and turnstiles. So censorship-resistance and counterfeiting-resistance are not primary goals for (at least) the first deployment of Crosslink.
- This is neutral with regard to Zcash governance —-- it doesn't change anything about Zcash governance.
Crosslink Security Properties
Crosslink is designed and can be analyzed with respect to the following security properties:
Irreversible Finality
Transactions enter a finalized state, and finalized transactions cannot be rolled back. Failure of this security property is called “rollback attack”.
Importantly, all participants who are sufficiently in sync with the consensus agree on finality status, or if there is a failure by the protocol to provide finality, all of those participants agree that this failure occurred. This contrasts with PoW which provides “probabilistic finality” and subtly this means every participant must select their own rollback threshold at which point they consider a protocol failure event to have occurred (including potential malicious “rollback attacks”). Because these thresholds vary over users, rollbacks naturally fragment users into groups with competing interests in the event of protocol failures.
Liveness/Availability
It is possible for any user to get at least some of their transactions paying sufficiently high fees to be included in one of the next few blocks. Failure of this security property is called a “denial-of-service for blockspace attack” (aka “blockspace DoS”). Two example attacks illustrate different attack approaches: in one case, an attacker has enough mining capacity to exclude all transactions (except perhaps their own); in another approach an attacker pays fees higher than any legitimate user for so many transactions that any other user cannot effectively get any of their transactions included.
Finality Progress
Blocks become final or they are removed from the chain within a finite amount of time. A failure of “finality progress” is called a “finality stall attack”. This is subtly distinct from a general liveness failure: a finality stall may occur even while new blocks containing transactions are continually produced. The longer that finality stalls while new blocks arrive with new transactions, the more likely it is that those users who require finality and those users who do not rely on finality will diverge in their expectations and behavior, which is a growing economic and governance risk, so finality stalls may be especially pernicious.
Censorship-resistance
It is possible to get new transactions processed even in the presence of an adversary who tries to prevent those specific transactions. Failure of this security property is called “censorship attack”. This kind of attack is distinct from blockspace DoS attacks because of the narrower targeting policy. In practice more general DoS attacks use different techniques than more targeted censorship.
Broadly speaking, an adversary may have a “censorship policy” based on a variety of criteria including both on-chain behavior and correlated metadata from many different domains.
Because censorship (and other privacy attacks) often rely on a wide array of data sources, practical protection also relies on a wide array of techniques and technologies out of scope for Crosslink’s design. One key area where we assume supporting defensive technologies (such as mixnets) is around network privacy for wallets (especially) and potentially other Crosslink infrastructure.
Supply-integrity
The total supply of ZEC is correct and any user can verify that it is correct. Failure of this security property is called “counterfeiting attack”.
TODO: Where does the following live?
What is the difference between liveness and censorship-resistance? The difference is whether specific transactions are targeted (a censorship attack) or (a stall attack). An important fact is that a stall attack would be immediately noticed and a wide set of users would be able to agree that the stall attack is happening. In contrast, a censorship attack would tend to go unnoticed except by the victims, and it might be difficult to achieve widespread recognition that it had happened. For this reason, part of the design of Crosslink is intended to “convert censorship attacks into stall attacks” – make it impossible for an attacker to censor targeted transactions without causing the entire service to stall.
Terminology
Here we introduce terminology specific to this design, especially when it may deviate from other consensus systems or common terminology used in the consensus protocol field.
Crosslink Finality
Crosslink provides a kind of finality which we call crosslink finality. Crosslink finality has these properties:
- It is accountable because the chain contains explicit voting records which indicate each participating finalizer's on-chain behavior.
- It is irreversible within the protocol scope. The only way to "undo" a final block is to modify the software to do so, which requires intervention by the user. Note that because a finality safety violation is always theoretically possible, this implies the only recovery from such a violation is out-of-band to the protocol and requires human intervention.
- It is objectively verifiable because it is possible to determine finality from a local block history without any out-of-band information.
- It is globally consistent meaning that all nodes which have received a sufficient number of valid blocks agree on the finality status, and also can rely on all other nodes in this set arriving at the same conclusion.
- It provides asymmetric cost-of-attack defense (TODO: Describe this better.)
User-Led Emergency Hardforks
In The Five Component Model we describe a key role of users is their governance capability to initiate a user-led hardfork in the event of an emergency.
In the context of Crosslink, we believe it's beneficial to gain community agreement on a norm for when such emergency hardforks are called for. Having an up-front agreement can help reduce confusion, debate, or contention during specific kinds of emergencies.
A Proposed Governance ZIP for the Use of an Emergency User-Led Hard Fork to Correct Layer-1 Security Failures
An emergency user-led hard fork is an extraordinary intervention that reflects a core value of cryptocurrencies: the ability of users to assert sovereignty over the protocol in response to a failure of its most fundamental security guarantees. This form of intervention is distinct from ordinary network upgrades, which change consensus rules prospectively and only with broad user acceptance. Because an emergency user-led hard fork carries significant social, economic, and political consequences, the Zcash community should establish a clear and limited social consensus in advance about when it is legitimate.
This Governance ZIP establishes that a user-led hard fork should be considered only to rectify and hold consensus operators accountable for failures of the layer-1 consensus system itself, specifically failures to prevent rollback or double-spend attacks, failures to ensure network liveness or availability, and failures to ensure censorship resistance or freedom of participation, including situations in which would-be miners, finalizers, or stakers are being systematically censored or prevented from participating in block production, finalization, or staking. These grounds are intended to capture violations of finality, liveness, and censorship resistance at the base layer and define the exclusive scope of legitimate emergency intervention under this framework.
This Governance ZIP explicitly rejects the use of an emergency user-led hard fork to mitigate harm arising from application-layer failures or to alter outcomes that, while undesirable, do not constitute violations of layer-1 security properties. It does not apply to wallet bugs, smart contract failures, bridge exploits, custodial failures, key management errors, user mistakes, or other application-level attacks or economic losses. A user-led hard fork must not be used to reverse or “make whole” thefts or hacks, to rewrite application-layer outcomes, or for purposes analogous to Ethereum’s DAO hard fork, the SUI blockchain hard fork, or similar interventions motivated by dissatisfaction with economic outcomes rather than base-layer security failure. Control over a large share of hashpower, finalization power, or stake does not itself constitute a violation, and a user-led hard fork must not be used to disadvantage miners, finalizers, or stakers solely for being large, nor to resolve governance disputes or enforce social policy outcomes.
This Governance ZIP also does not apply to ordinary prospective rule changes adopted through standard upgrade processes, including the introduction of new transaction types, new features, or protocol cleanups. It does not apply to monetary policy, economic parameters, or protocol design choices such as shielded pool deprecations, fee changes, new fee mechanisms, staking or unbonding parameters, or funding mechanisms. All such matters fall within the domain of future community governance and must be decided through ordinary governance and network upgrade processes, not through an emergency user-led hard fork justified under this security framework.
Even when one of the legitimate layer-1 security grounds is clearly met, any emergency user-led hard fork should be narrowly scoped to address only the specific security failure, avoid unnecessary collateral changes, minimize downstream disruption, and preserve continuity of honest user state where technically feasible. Possible interventions may include correcting a critical consensus bug, changing a security-critical consensus mechanism that failed to prevent the violation, or, where directly relevant, neutralizing counterfeit or illegitimate base-layer state created by the failure. The objective of such intervention is the restoration of neutral protocol function, not broad protocol re-engineering under crisis conditions.
This Governance ZIP is a proposed expression of social consensus. Its force derives solely from the degree to which the Zcash community chooses to adopt and uphold it. Whether any particular emergency intervention is ultimately acceptable will depend not only on technical criteria, but also on whether it aligns with the community’s explicit or assumed social values. By committing to these constraints in advance, the community strengthens credible neutrality, reduces moral hazard, and increases confidence that the protocol will not be arbitrarily rewritten.
Mermaid Common Styles
This file contains reusable Mermaid style definitions for diagrams throughout the book.
How to Use
Copy the relevant style definitions from this page into your Mermaid diagrams. While the styles are also defined in mermaid-common-styles.js for potential programmatic use, Mermaid requires classDef statements to be included within each diagram block.
PoW Block Styles
For Proof-of-Work blockchain diagrams:
%% Define PoW block style with dark blue border and oval shape
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
%% Define alternative PoW block style with orange fill for caution
classDef powAlt fill:#ffcc80,stroke:#01579b,stroke-width:3px,color:#000
Usage Example
graph TD
Block_0([B₀]):::pow
Block_1([B₁]):::pow
Block_1_alt([B₁']):::powAlt
Block_1 --> Block_0
Block_1_alt --> Block_0
%% Define PoW block style with dark blue border and oval shape
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
%% Define alternative PoW block style with orange fill for caution
classDef powAlt fill:#ffcc80,stroke:#01579b,stroke-width:3px,color:#000
Crosslink Finality Styles
For diagrams that show both chains and the finality markers, as in A Visual Guide to Finality and Fork Choice. Use pow for PoW blocks on the node's best chain and powAlt for PoW blocks off it.
%% Define PoS / BFT block style with dark red border
classDef bft fill:#fff,stroke:#b71c1c,stroke-width:3px,color:#000
%% Define style for the BFT block that a PoW block's context_bft makes final, LF(H)
classDef lf fill:#ffcdd2,stroke:#b71c1c,stroke-width:3px,color:#000
%% Define style for a BFT proposal that the validity rules reject
classDef rejected fill:#fff,stroke:#b71c1c,stroke-width:2px,stroke-dasharray:5 4,color:#000
%% Define style for the PoW block that is candidate(H), with yellow fill
classDef candidate fill:#ffeb3b,stroke:#01579b,stroke-width:3px,color:#000
%% Define fin last, so that its border wins over the block style.
classDef fin stroke:#8e24aa,stroke-width:7px
fin only sets a border, so add it on top of a block's own style with a class statement, such as class P5 fin. Both styles then set a border, and Mermaid lets the one defined later win, so classDef fin must come after the others.
Usage Example
graph TD
A([pow]):::pow --> B([candidate]):::candidate
B --> C(["candidate + fin"]):::candidate
C --> D(["pow + fin"]):::pow
E(["powAlt + fin"]):::powAlt --> D
X(rejected):::rejected --> Y(lf):::lf
Y --> Z(bft):::bft
class C,D,E fin
classDef pow fill:#fff,stroke:#01579b,stroke-width:3px,color:#000
classDef powAlt fill:#ffcc80,stroke:#01579b,stroke-width:3px,color:#000
classDef bft fill:#fff,stroke:#b71c1c,stroke-width:3px,color:#000
classDef lf fill:#ffcdd2,stroke:#b71c1c,stroke-width:3px,color:#000
classDef rejected fill:#fff,stroke:#b71c1c,stroke-width:2px,stroke-dasharray:5 4,color:#000
classDef candidate fill:#ffeb3b,stroke:#01579b,stroke-width:3px,color:#000
%% Define fin last, so that its border wins over the block style.
classDef fin stroke:#8e24aa,stroke-width:7px
Node Type Styles
Standard node types used across diagrams:
classDef input fill:#e1f5ff,stroke:#01579b,stroke-width:3px,color:#000
classDef compute fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
classDef aggregate fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000
classDef output fill:#e8f5e9,stroke:#1b5e20,stroke-width:3px,color:#000
classDef storage fill:#fce4ec,stroke:#880e4f,stroke-width:2px,color:#000