Overview

Shielded Labs' Crosslink is an in-development complete protocol design covering consensus, networking, usability, and security considerations intended for the Zcash network. In addition Shielded Labs is developing software for a prototypical fully verifying node and also finalizer and wallet support.

This book is focused on the design itself, rather than software implementations.

There are multiple opportunities to get involved: design contributions, joining our live Feature Net, and more. See The Shielded Labs' Crosslink Site to get involved!

Status

The Shielded Labs' Crosslink project is in a "productionization" phase, during which we are refining and analyzing the design and software to make it "production ready" as a stand-alone Zcash consensus feature.

This phase and it's conclusion of "production readiness" does not imply this protocol change will be accepted or deployed in Zcash!

For this design book, this includes making the specification more precise, documenting design choice rationales, alternatives considered, and analysis results.

For further information, see the current Shielded Labs' Crosslink Roadmap.

Scope and Goals

This chapter describes Shielded Labs' goals for the first deployment of Crosslink, the rationale behind the overall hybrid PoW/PoS approach, and the trade-offs and non-goals we've chosen for that first deployment.

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 incentivizes 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 (see The ZEC Supply Policy).
  • 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.
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 performance.

Shielded Labs' 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' 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 Design

The zebra-crosslink design fleshes out and adapts the abstract Crosslink 2 into a working implementation. (See The Crosslink 2 Construction in the TFL Book for the abstract construction's precise definition.) This includes extending and adapting that construction to include a fully functional BFT protocol, and including staking mechanics, accounting, and associated security reasoning and arguments. Additionally, we explicitly alter some trade-offs, or terminology compared to the abstract construction.

This Design chapter focuses specifically on differences from pure PoW Zcash (using zebra as a reference implementation) and the Crosslink 2 construction. We assume basic familiarity with both. Also, please see our Terminology for terms specific to this project.

WARNINGS

  • These extensions and changes from the Crosslink 2 construction may violate some of the assumptions in the security proofs. This still needs to be reviewed after this design is more complete.
  • We are using a custom-fit in-house BFT protocol for prototyping. It's own security properties need to be more thoroughly verified.
  • All trade-off decisions need to be thoroughly vetted for market fit, while ensuring we maintain a minimum high bar for safety befitting Zcash's pedigree. Part of our implementation approach is to do rapid prototyping to explore the market fit more directly while modifying trade-offs in the design.

It is especially important that we identify deviations from Zcash PoW consensus, the Crosslink 2 construction, and the upstream zebra implementation. In particular, it is important for us to clarify our rationale for deviation, which may fit one of these general categories:

  • We intentionally prefer a different trade-off to the original design; in which case we should have very explicit rationale documentation about the difference (in an ADR). One example (TODO: we may not use ADR format specifically, but the spirit of this needs to be fulfilled) is our ADR-0001 selects a different approach to on-chain signatures than (TODO: link to TFL section).
  • Something about the more abstract design makes assumptions we cannot uphold in practice with all of the other implementation constraints. In this case, we need to determine if the upstream design needs to be improved, or we need to alter our implementation constraints.
  • As an expedient, we found it quicker and easier to do something different to get the prototype working, even though we believe the upstream makes better trade-offs. These are prime candidates for improvement during productionization to match the design, or else require persuasive rationale that a "short cut" is worth the trade-offs and risks.

Design Decision Records

During prototyping of zebra-crosslink we documented many design decisions as Architecture Decision Records (ADRs), 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.

Those early records are very rough and tracked on this zebra-crosslink ADR Google Sheet. During productionization we are incorporating their substance, including rationales and alternatives considered, into this book, whether or not we keep the ADR format itself.

Engineering Deliverables for Shielded Labs' Crosslink Deployment

This is a list of Shielded Labs' 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). See the Shielded Labs' Crosslink Roadmap for current status.

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 #105 augmentation of existing RPC APIs for blocks and transactions to include finality status
    • GH #104 new RPC APIs related to Proof-of-Stake: finalizer identities, staking weights, delegation info
    • GH #172 new RPC APIs related to Crosslink: contingency mode, finality traversal
  • 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 are first developed and released as testnet prototypes (such as our Feature Nets) which are then matured into production-ready status during the current productionization phase (see Status).

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, and staking actions such as creating, retargeting, unbonding, and withdrawing delegation bonds.
  • 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 finalizers is to ensure finality (i.e. to prevent rollback attacks) but finalizers cannot unilaterally compromise liveness or censorship-resistance (even if an attacker controls >⅔ of the stake-weighted votes) because miners ensure those properties. Also the finalizers cannot unilaterally execute rollback attacks even though they can prevent rollback attacks. A plurality of the finalizers (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 finalizers accountable by detecting and punishing misbehavior on the part of the finalizers by retargeting their delegation bonds 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). The current design specifies one such mechanism, a user-coordinated social slashing hard fork, and we describe a proposed community norm for when emergency hard forks are legitimate in 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 create, retarget, unbond, and withdraw bonds, 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...
    • TODO: Analyze this scenario.

User-Led Emergency Hardforks

In The Five Component Model we describe that 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.

The current Crosslink design relies on this capability directly: there is no in-protocol slashing, and instead punishment of stake behind misbehaving finalizers is a user-coordinated hard fork driven by a node configuration. See Social Slashing in the Design Overview for its mechanics. The proposed norm below is intended to bound when such a fork, or any other emergency user-led hard fork, is legitimate.

TODO: Reconcile this norm with the slash fork scenarios in the Design Overview. In particular, a "spring cleaning" slash fork (removing permanently absent finalizers when there is no stall) may not clearly fall within the layer-1 security failure grounds below.

A Proposed Norm for the Use of an Emergency User-Led Hard Fork to Correct Layer-1 Security Failures

The following text is drafted in the style of a potential Governance ZIP.

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.

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

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.1 To this Ledger State, Crosslink introduces the roster, which contains all of the information about all ZEC staked to finalizers.

1

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 delegation bonds created by stakers and targeting specific finalizers. A finalizer's voting power is the sum of all bonds targeting it, and the top N finalizers by voting power form the active roster (see Finalizers and Rosters).

A finalizer is identified on-chain solely by its key and its published consent capability2. People may mean a specific person, organization, entity, computer server, etc... when they say "finalizer", but in this book we use the term finalizer as a shorthand for "whichever entity controls the keys for a given on-chain finalizer identity".

2

Any particular entity may produce any number of finalizer identities of course, although for economic or social reasons, we expect many finalizers to be motivated to hang their reputation on one or just a few well-known identities.

Each bond is controlled by its own key, which enables retargeting, unbonding, and withdrawing that bond (a good wallet should manage these keys on behalf of users without their need to directly know or care about them for safe operation). These keys are unique to the bond itself and are not linked on-chain to a user's other bonds or other activity.

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 roster state, and the BFT finality status of blocks and transactions.

This matches the Design Overview's principle that 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. Two nuances apply:

  • A node's local finality (fin) is deliberately not Ledger State. It is node-local, monotone memory which depends on the history of that node's views, so consensus rules must never read it. See Kinds of Finality.
  • A social slashing configuration alters how the roster is computed. Every slash event is a hard fork, so this does not violate the invariant: within any given set of consensus rules, the roster remains a pure function of finalized PoW state.

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 the bonds and their targets, and finalizer voting power.

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 BFT finality status.

The BFT finality status of a block at height (and by extension any transactions it contains and all previous block contents) is a property which guarantees3 to the verifying node that this block (and all txns and previous content) is final. Furthermore, the presence of this property also provides a guarantee that a supermajority of finalizers already agreed 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.

3

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 BFT 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), whose fat pointer refers to a BFT certificate finalizing the candidate. All verifying nodes who have observed that attesting block will agree on the finality of the candidate block even though they may observe the attesting block roll back. 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 roster, are all determined by valid transactions within PoW blocks. Every PoW block height thus has a specific unambiguous Ledger State. This comes into play when we consider finality, which is a property of a given block height which is only verifiable at a later block height, and when determining which Ledger State a given consumer should use. For example, the roster for a given BFT height is taken from the snapshot of the previously decided certificate rather than the PoW tip. See Which Ledger State is Current.

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?

Crosslink Security Properties

Crosslink is designed and can be analyzed with respect to the following security properties. See Design Analysis for frameworks and results analyzing them.

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.

See Crosslink Finality for the specific kind of finality Crosslink provides, and the Design Overview §9 Sticky Fork Choice for how nodes enforce it.

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.

Converting Censorship Attacks into Stall Attacks

What is the difference between liveness and censorship-resistance? The difference is whether specific transactions are targeted (a censorship attack) or not (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.

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”. See The ZEC Supply Policy for the broader set of ZEC supply characteristics Crosslink must preserve.

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 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.)

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:

  1. ZEC must be scarce, with every unit accounted for by the consensus protocol, all adding up to the Max Supply Cap of 21,000,000.

  2. The consensus protocol constrains ZEC transfers, 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.

  3. ZEC is divided between Unissued Supply versus Active Supply, with the total of these two categories being the Max Supply Cap.

  4. The Active Supply is all ZEC that is under a user's discretionary control, given any protocol constraints on those funds. For example, much of the active supply is ZEC which 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.

  5. The consensus protocol may issue or unissue ZEC by 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 ZEC as part of the network operation in order to incentivize successful operation of the network and establish a valuable network effect of ZEC scarcity among users.

    This new ZEC is 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.

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 ZEC to 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"?

With that framework in mind, here are the concrete rewards distribution rules Crosslink follows:

  1. 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.

  2. 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).

  3. The remainder is called the Operational Consensus Rewards (aka OCR).

  4. 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.)

  5. 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:

  1. 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.

  2. Txns with bond actions may only be included in blocks at Staking Day height ranges (FIXME: define these heights).

  3. Bonds have a stateful lifecycle:

    • From any Shielded Pool ZEC: create action

    • From active state: redelegate or withdraw actions

    • From withdrawing w/ sufficient delay state: transfer action

      • 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 create and withdraw actions may only occur during Staking Day heights.
    • The redelegate and transfer actions are not constrained by Staking Day height ranges.
    • The transfer action 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 day block 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_Bond which is at least one staking cycle old
  • The block height must be a staking day block height

Withdraw Bond action

  • Must refer to an existing Unstaked_Bond which is at least one staking cycle old
  • The block height must be a staking day block height
  • (provisional C) The "most recent finalized PoW Height" is > N staking cycles from the height of the Unstake Bond action.

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 Bond action.

Convert Rewards action

  • Must refer to an existing finalizer commissions bucket which 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

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

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. My fin does not move yet.
  • A PoW block on my best chain cites that decision in its context_bft. Once that block is my best tip, fin ratchets 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. fin then 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 fin and the tip is unbounded during a stall, and ordinary spends keep landing above fin.
  • 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.

  1. Unbond. Value depends on which block it lands in; once landed, the bond has a fixed numeric value.
  2. 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

  1. 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.
  1. Staking actions that have landed in the PoW chain must be respected.

  2. PoS stores no ledger information of its own.

  3. 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/H3 with the code's h1/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?

Design Analysis

This chapter collects frameworks and results for analyzing the safety and security of the Crosslink design.

  • Penalty for Failure to Defend introduces our primary framework for quantitative comparison of Crosslink's security properties against other consensus protocols.
  • Design Analysis History documents third-party reviews of the design, their scopes, and their results.

The abstract Crosslink 2 construction which this design adapts (defined in The Crosslink 2 Construction) has its own liveness and safety analysis in the TFL Book: Security Analysis of Crosslink 2.

That analysis applies to the abstract construction, and the extensions and changes described in our Design Overview may violate some of its assumptions. Identifying where our design diverges from those assumptions is ongoing work.

Penalty for Failure to Defend

Our primary conceptual framework for quantitative comparison between Crosslink security properties versus pure PoW or Tendermint-like BFT protocols is called "penalty for failure to defend" (aka ).

TODO: This chapter is a rough sketch originally drafted in zebra-crosslink #264 and needs to be fleshed out.

Key Top-Level Details

  • PFDs can be specific to compromising specific properties; example: and are different (so there's no simple top-line number for a given protocol).
  • is distinct from the confusing misnomer of "cost-to-attack" (because the penalty may accrue to non-attackers, and the nature of successful attacks is that they cost less than designers or security analysts anticipate).
  • Neither nor the ill-conceived "cost-to-attack" metrics are conclusive about financial feasibility, since they don't capture attacker revenue/profit.
  • Some may be a "financial value gauge" such as in Tendermint protocols where a could slash a large bond at stake. Meanwhile others may be a "rate" such as in PoW where the penalty to miners is loss of a future revenue rate over time.
  • The two different types of (gauge vs rate) cannot be directly compared for two reasons:
    • The obvious reason that rates and gauges are different unit types.
    • The less obvious reason that the trade-offs in compromise, response, and recovery dynamics are qualitatively incommensurate. (TODO: flesh out the nuance here.)

Design Analysis History

Throughout the prototypical and production-oriented development of Crosslink, we engage third-party experts to analyze on the safety and security of the design.

This section documents those reviews, their scopes, and the report results.

Mechanism Design Audit of Crosslink Zebra

2025-12-11

This design review audit was initiated as the Shielded Labs team approached the final stretch of their prototyping phase (see the Roadmap for the current status). This was useful timing between prototyping enough to have confidence the design is feasible for production versus too late in the process when the design is already "baked" to get a mechanism-design focused review of the consensus safety.

This audit focused on the core safety and reliability of Crosslink as a consensus foundation, and not on other crucial concerns like privacy, usability, the code implementation, and so on.

Pre-Registration Process

Shielded Labs undertook a "pre-registration" process for this design audit by publicly committing to the scope and deliverables prior to engaging in the audit so that the public can verify we did not "shift the goal posts" after learning details from the auditor in order to influence the perception of the findings.

See the precommitted Proposal for this audit.

Results

The audit report is referenced by the Crosslink Design Overview as Nikete's Mechanism Design Audit of Crosslink Zebra, and several design choices there cite its recommendations (for example, items R2, R4, and R6 in §14 Rewards).

TODO: Link the published report, executive summary, and outreach materials.

Proposal: Mechanism Design Audit of Crosslink Zebra

Note: This proposal is preserved verbatim as pre-registered (minus budget details), so the scope cannot drift after the fact. The only changes are to links: references to "this book" now point to the archived revision of the book as it existed when the proposal was committed, since the book has since been reorganized.

Prepared for: Shielded Labs Duration: 1 week core analysis + light follow‑up outreach

Objective

Shielded Labs is designing and stewarding Crosslink v2 (Crosslink 2 consensus plus updated staking economics). This proposal covers a mechanism design–focused audit that:

  • Evaluates the incentive structure faced by miners, finalizers, stakers, and the wider community.
  • Assesses the Penalty for Failure to Defend (PFD) for key properties (safety, liveness, censorship resistance).
  • Identifies likely equilibria and failure modes under realistic behavior.
  • Produces clear recommendations to harden Crosslink v2 before or shortly after deployment.
  • The work will be completed over one week, followed by targeted outreach so results can inform the broader Zcash ecosystem.

Scope

In scope: Crosslink Zebra as defined by Shielded Labs, specifically defined in this book in the Design chapter.

Questions to answer:

  • What behaviors are rational for miners, finalizers, and stakers?
  • What are the “good” and “bad” equilibria?
  • How large is the effective PFD for safety, liveness, and censorship resistance?
  • Where does the design rely on social courage instead of hard incentives?
  • In general, what conditions are necessary to violate the security properties listed Security Properties

Out of scope

  • Cryptographic soundness of Zcash primitives.
  • Implementation bugs in node software.
  • Detailed macro‑economic modeling of ZEC price or off‑chain markets.
  • Privacy impacts on stakers or finalizers. Privacy protection is a top priority for Zcash generally, and a priority for Crosslink analyses in the future. However, for this initial audit we first want to focus on the general safety and reliability of the base consensus mechanism. Note that there are a set of constraints on the mechanism design which are present in order to provide privacy, and these must be satisfied for any alternatives or recommendations. These are described in our blog post Crosslink: Updated Staking Design.

Deliverables

By the end of the one‑week analysis:

  1. Mechanism Design Audit Report (10–15 pages)
  • Role‑by‑role incentive analysis (miners, finalizers, stakers, community).
  • PFD analysis for core properties under representative attack scenarios.
  • Identified “bad equilibria” (e.g., PoS cartelization).
  • Prioritized recommendations with concrete levers (e.g., minimal penalties, tweaks to incentives to bolster against bad outcomes, delegation tweaks, governance formalization).
  1. Executive Summary (2–3 pages)
  • Non‑technical overview of risks, trade‑offs, and recommended changes, suitable for Shielded Labs leadership and partner orgs (ECC, ZF).
  1. Slide Deck (15–20 slides)
  • Visual summary of findings for internal review and community calls.
  1. Outreach Draft
  • Draft blog / forum post summarizing the results for the public Zcash community.
  • Suggested agenda + talking points for a community call presenting the audit.

Work Plan & Timeline

Day 1 – Kickoff & Alignment

  • 60–90 minute kickoff with Shielded Labs.
  • Confirm canonical specs and design assumptions.
  • Clarify constraints (e.g., “no protocol‑level slashing in V1”) and any specific questions.
  • Finalize success criteria and deliverable format.

Days 2–4 – Mechanism Design Analysis

  • Map incentives for each role (miners, finalizers, stakers, community), given:
    • 40/40 issuance split;
    • 5‑day epochs, 5–10 day unbonding;
    • Emergency patch + hard‑fork constitution.
  • Identify likely equilibria and failure modes (cartels, PoS capture, unbounded divergence between PoW progress and a stalled BFT subprotocol, etc.).
  • Qualitative PFD modeling for safety, liveness, and censorship resistance; comparison to Zcash PoW‑only at the same issuance rate.

Day 5 – Recommendations & Drafts

  • Translate analysis into concrete, ranked recommendations (high / medium / low impact & complexity).
  • Produce draft audit report and executive summary.

Day 6 – Review & Finalization

  • Share drafts with a small Shielded Labs review group.
  • Incorporate feedback and finalize:
    • Audit report
    • Executive summary
    • Slide deck

Day 7 – Outreach Prep

  • Draft blog / forum post and call agenda.
  • Finalize outreach materials in collaboration with Shielded Labs communications.

Outreach & Follow‑up

Within the same budget:

  • One live presentation of findings (e.g., Zcash community call or internal Shielded Labs session).
  • Asynchronous Q&A on the report (e.g., GitHub, forum thread) for 1–2 weeks after publication.
  • Minor updates to slides and outreach text in response to initial feedback (no new analysis).

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_best is the PoW chain that the node's fork choice selects, and bc_best_tip is its newest block. It is available but not final.
  • candidate(H) is the finalization point that a PoW block H and its linked ancestry imply. It is objective: every correct replay of the same H gets the same answer.
  • fin is the furthest compatible candidate(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 asMeaning
Rounded block, blue border, white fillPoW block on the node's best chain
Rounded block, orange fillPoW block off the node's best chain
Box, red borderPoS / BFT block
Box, pink fillLF(H): the last final BFT block in the context of H
Box, dashed red borderBFT proposal that the validity rules reject
Yellow fillcandidate(H) for the best tip H
Thick purple borderfin
Plain arrowParent link
Arrow labelled context_bftThe BFT block that a PoW block cites
Dotted arrowA PoW header carried in a BFT block's headers_bc
Thick arrow labelled snapshotsnapshot(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:

  1. P10.context_bft cites S6. Tenderlink decides each BFT block on its own, and the fat pointer in context_bft carries the signatures of that decision, so the cited block is final and LF(P10) = S6. The Book's generic BFT protocol can instead finalize an ancestor of the cited block.
  2. S6.headers_bc = [P6, P7, P8], deepest first. Its snapshot is the parent of headers_bc[0]: snapshot(S6) = parent(P6) = P5.
  3. prune_sigma(P10) drops the newest sigma blocks: P7 when sigma = 3.
  4. 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 = P10 is the fork-choice result, not finality. P6–P10 are unfinalized, and no protocol rule bounds this gap: Zebra Crosslink omits Stalled Mode, so nothing limits how far the best chain runs ahead of fin.
  • candidate(P10) = P5 is the objective result of the two-chain walk. It is pure, and it can move backward while the best chain still contains fin.
  • fin advances from P4 to P5, because on this bc_best update 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

SituationAction
candidate(bc_best_tip) descends from finAdvance fin to the candidate.
The candidate is an ancestor of finHold fin. This can be benign, when the complete bc_best still contains fin.
The candidate conflicts with finHold fin and record a finalization safety hazard.
bc_best_tip itself conflicts with finHold 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.

  1. Prefix Consistency at sigma failed. A previously sigma-confirmed prefix was displaced.
  2. CL2 keeps C8 as bc_best. The highest-score valid chain wins. No CL2 rule requires raw bc_best to contain fin.
  3. Abstract CL2 rejects the crossing. Linearity keeps valid snapshots on the P branch, so a proposal S6 whose snapshot is on the C fork is rejected.
  4. candidate(C8) = P3; fin stays P5. 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, keep fin = P5, and prevent valid BFT snapshots from crossing forks. With Stalled Mode omitted, nothing restricts later C blocks: spends accumulate past fin for 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. C8 never becomes its best chain, whatever C's work; the node stays on P and keeps fin = P5. This enforces fin ⪯ bc_best, not the stronger property that an unfinalized sigma-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, contains fin = P5. Switch. Raw work-based fork choice does the same.
  • C9: more work, forks at P3, below fin. No switch, whatever C's work. Raw fork choice switches and leaves fin off bc_best.
  • fin advances only to candidate(bc_best). candidate(bc_best) ⪯ bc_best, so the node's best chain always contains its fin.

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.

Writing Style

This is not comprehensive, just tips we want to remember / be consistent on:

Shielded Labs

  • Refer to the team as "Shielded Labs".
  • Use Shielded Labs' Thing for possessive.

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

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