PR #1216proposed changes to·draft-shieldedlabs-crosslink-construction·draft-shieldedlabs-crosslink-ledger-state·draft-shieldedlabs-crosslink-overview

Crosslink ZIPs

status → Draftby shielded-nate · updated 2026-06-03zips/draft-shieldedlabs-crosslink-construction.rst @ d9ac34322c · upstream 4699a8d518view on GitHub ↗

Unofficial preview — the proposed text below is rendered from the pull request head and is not part of the canonical ZIP set.

Terminology

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in BCP 14 [1] when, and only when, they appear in all capitals.

The terms "Mainnet" and "Testnet" in this document are to be interpreted as defined in the Zcash protocol specification [3].

The terms below are to be interpreted as follows:

CCC-SL (Crosslink Consensus Construction from Shielded Labs)

The hybrid consensus construction specified by this ZIP, integrating the Zcash PoW best-chain protocol with CFP-SL to produce a protocol with both availability and Crosslink Finality. CCC-SL is the core of Shielded Labs Crosslink v1 and is closely based on CCC-TFLv2 from the TFL book [6].

CCC-TFLv2 (Crosslink Consensus Construction from the TFL Book, version 2)

The abstract hybrid consensus construction documented in the Zcash TFL book [6]. CCC-SL is the Shielded Labs adaptation and extension of this construction for the Zcash PoW+TFL deployment.

CFP-SL (Crosslink Finalization Protocol from Shielded Labs)

The BFT Proof-of-Stake finalization protocol used as the BFT subprotocol within CCC-SL. CFP-SL satisfies the interface requirements (Final Agreement and related properties) defined in this ZIP.

Best-chain subprotocol (Πbc)

The Zcash Proof-of-Work best-chain protocol, modified by CCC-SL to participate in the hybrid construction. Blocks in this protocol are called "bc-blocks" and chains are "bc-chains".

Original best-chain subprotocol (Πorigbc)

The "off-the-shelf" PoW best-chain protocol before CCC-SL modifications. For the Zcash deployment, this corresponds to the Zcash NU5/NU6 consensus protocol.

BFT subprotocol (Πbft)

The BFT protocol (instantiated by CFP-SL) modified to participate in CCC-SL. Blocks in this protocol are called "bft-blocks" and finality is called "bft-finality".

Original BFT subprotocol (Πorigbft)

The "off-the-shelf" BFT protocol before CCC-SL adaptation modifications. CFP-SL is a specific instance of this with Zcash-specific adaptations.

bc-confirmation-depth (σ)

A protocol parameter specifying the number of bc-block confirmations required before a bc-block may be included in the snapshot referenced by a bft-block. This is also the default depth used by nodes when computing the locally finalized chain.

Finalization gap bound (L)

A protocol parameter specifying the maximum number of unfinalized bc-blocks permitted before CCC-SL enforces Stalled Mode. MUST satisfy L ≥ 2σ.

Bounded-availability depth (μ)

A per-node choice of confirmation depth for the locally bounded-available chain, where 0 < μ ≤ σ.

Locally finalized chain (localfin)

Each node's monotonically advancing view of the bc-chain that has been finalized by CFP-SL. Once a bc-block is in a node's locally finalized chain, it will never be removed from it.

Locally bounded-available chain (localba)

Each node's view of the confirmed (but not necessarily finalized) bc-chain, computed using confirmation depth μ.

Finality gap

At a given time, the number of bc-blocks in the bc-best-chain that have not yet been finalized by CFP-SL.

Stalled Mode

A mode enforced by CCC-SL when the finality gap exceeds L, during which bc-block producers are constrained to produce only stalled blocks.

Stalled block

A bc-block produced during Stalled Mode, constrained by the isStalledBlock predicate (e.g., not including new user transactions that spend into the unfinalized zone).

Final Agreement

The property of the BFT subprotocol (CFP-SL) that all bft-valid blocks in honest view are consistent: for any two such blocks, one must be an ancestor of the other.

Prefix Consistency

The property of the best-chain subprotocol (Zcash PoW) that any two honest nodes' confirmed best-chains are consistent up to their confirmed depths.

Crosslink Finality

The finality property provided by CCC-SL, as defined in the zebra-crosslink design documentation [10]. Formally: for any two honest nodes i and j at any times t and u, if both localfin_i(t) and localfin_j(u) are non-genesis then one is a prefix of the other (localfin_i(t) ≼_bc localfin_j(u) or localfin_j(u) ≼_bc localfin_i(t)). See the Security Analysis section.

≼_bc (bc-prefix relation)

A ≼_bc B holds iff the bc-chain with tip A is a prefix of the bc-chain with tip B; equivalently, A is an ancestor of B or A = B. The notation ≼ (without subscript) is used as a shorthand for ≼_bc when the context is unambiguous.

C.truncate_bc(k)

For a bc-chain C and natural number k: the bc-chain obtained by removing the last k blocks from C. The tip of C.truncate_bc(k) is the block at depth k in C. If len(C) ≤ k, the result is the genesis block Origin_bc. When applied to a block H (shorthand for the chain ending at H), H.truncate_bc(k) denotes the block at depth k from H.

lastCommonAncestor(A, B)

For two bc-blocks A and B: the most recent (deepest) bc-block that is an ancestor of both A and B. Equivalently, the tip of the longest common prefix of the bc-chains ending at A and B. If one block is an ancestor of the other, lastCommonAncestor(A, B) = min(A, B) by depth.

bftLastFinal(B)

For a bft-block B, the function returning the last bft-block that is considered final in the context of B (including B itself, if applicable). This function is defined by CFP-SL.

snapshot(B)

For a bft-block or bft-proposal B, the bc-block at the base of the bc-chain snapshot committed to by B. Formally: if B.headers_bc is null (genesis), snapshot(B) = Origin_bc; otherwise snapshot(B) = B.headers_bc[0].truncate_bc(1).

LF(H)

For a bc-block H, the last final bft-block in the context of H: LF(H) = bftLastFinal(H.context_bft).

candidate(H)

For a bc-block H, the candidate finalization point: candidate(H) = lastCommonAncestor(snapshot(LF(H)), H.truncate_bc(σ)).

Abstract

This ZIP specifies CCC-SL (the Crosslink Consensus Construction from Shielded Labs), the hybrid consensus protocol at the core of Shielded Labs Crosslink v1 [5]. CCC-SL integrates the Zcash Proof-of-Work best-chain protocol with the CFP-SL BFT finalization protocol to provide both the availability properties of the PoW chain and the Crosslink Finality of a BFT protocol.

CCC-SL is closely based on the CCC-TFLv2 construction from the Zcash TFL book [6]. The key features of CCC-SL are:

  1. Cross-referencing fields in both bc-blocks and bft-blocks/proposals that allow each chain to objectively verify properties of the other.

  2. A locally finalized chain (localfin) maintained by each node that advances monotonically and never rolls back.

  3. A locally bounded-available chain (localba) providing a confirmed-but-not-necessarily-finalized view of the PoW chain.

  4. A Stalled Mode mechanism implementing bounded availability when the finality gap exceeds the threshold L.

This ZIP is accompanied by ZIP [5], which provides the design motivation and architecture overview for the full Shielded Labs Crosslink v1 protocol suite.

Motivation

See ZIP [5] for the full motivation. In brief:

  • Zcash's current PoW-only consensus provides only probabilistic finality, creating friction for exchanges, bridges, and other services.

  • Integrating CFP-SL as a finality layer via CCC-SL preserves PoW availability and security while adding Crosslink Finality.

  • CCC-SL (following CCC-TFLv2) improves on the Snap-and-Chat construction [7] by eliminating the need for transaction-log sanitization and by implementing bounded availability.

  • The cross-referencing design of CCC-SL enables each chain to provide objective validity checks on the other, strengthening the security of the hybrid construction.

Requirements

CCC-SL MUST satisfy:

  • Crosslink Finality: If both subprotocols satisfy their safety assumptions, the locally finalized chain of any two honest nodes must be consistent — neither node's locally finalized chain can conflict with the other's.

  • Local Finalization Linearity: For each honest node, the locally finalized chain is monotonically non-decreasing: it only ever advances forward, never rolls back.

  • Prefix Consistency (inherited from Πbc): Two honest nodes' confirmed best-chains must be consistent.

  • Bounded Availability: The finality depth of any non-stalled bc-block MUST NOT exceed L while honest bc-block producers follow the protocol. (Stalled blocks may exist at finality depth greater than L; the bound applies to transaction-carrying blocks only.) When the finality depth at the chain tip exceeds L, bc-block producers MUST enter Stalled Mode.

  • Objective Validity: The validity of any bc-block MUST be determinable from the block itself and its ancestors in both chains, with no external context beyond the two chains.

  • Minimal Subprotocol Modification: The modifications to the PoW and CFP-SL subprotocols SHOULD be as minimal as possible while satisfying the above requirements.

Non-requirements

The following are out of scope for this ZIP:

  • The specific BFT algorithm used internally by CFP-SL. This ZIP specifies only the interface requirements (Final Agreement, etc.) that Πorigbft must satisfy. The CFP-SL specification is a separate ZIP.

  • The staking mechanics, Finalizer registration, delegation, and slashing rules (specified in the RSM-SL-v1 ZIP).

  • Reward distribution between PoW miners and Finalizers (a separate funding ZIP).

  • The specific activation height(s) for the network upgrade.

Specification

Parameters

CCC-SL is parameterized by:

  • bc-confirmation-depth σ ∈ ℕ⁺: the number of bc-block headers included in each bft-block's headers_bc field, representing the depth at which a bc-block is considered confirmed for snapshotting purposes. This is also the default confirmation depth for the locally finalized chain.

  • Finalization gap bound L ∈ ℕ⁺, where L is significantly greater than σ (the minimum is L ≥ 2σ): the maximum finality gap before Stalled Mode is enforced.

The precise values of σ and L for Mainnet and Testnet deployment are to be determined through a network upgrade process ZIP, taking into account measured CFP-SL latency and desired time-to-finality targets.

Subprotocol Interface Requirements

CCC-SL places the following requirements on Πorigbft (which is instantiated as CFP-SL in Shielded Labs Crosslink v1):

  • Πorigbft MUST be a protocol with an identified set of blocks forming a DAG with a defined genesis block Origin_bft.

  • Πorigbft MUST define a function bftValid(B) → Boolean determining whether a bft-block B is valid in the context of the bft-chain.

  • Πorigbft MUST define a function bftLastFinal(B) → BftBlock returning the last bft-block that is "final" in the context of bft-block B, where bftLastFinal(Origin_bft) = Origin_bft.

  • Πorigbft MUST satisfy Final Agreement: in any execution where safety assumptions hold, for all bft-valid blocks C in honest view and all times t, bftLastFinal(C) must be an ancestor of every other bft-valid block that honest nodes have finalized.

CCC-SL places the following requirements on Πorigbc (the Zcash PoW protocol):

  • Πorigbc MUST be a best-chain protocol with bc-blocks forming a tree rooted at Origin_bc.

  • Πorigbc MUST define a fork-choice function selecting the "best chain" among all bc-valid chains known to a node.

  • Πorigbc MUST satisfy Prefix Consistency (Common Prefix): in any execution where assumptions hold, for any two honest nodes' confirmed chains C1 and C2, one is a prefix of the other.

Structural Additions

CCC-SL extends the block formats of both subprotocols with cross-referencing fields:

bc-block structural additions

Each bc-block header MUST include, in addition to all Πorigbc-block fields:

  • context_bft: a hash identifying a bft-block. This commits the bc-block producer to their view of the CFP-SL chain at the time the block was produced. The referenced bft-block MUST be a bft-valid block in the bc-block producer's view at the time of production.

bft-proposal structural additions

Each non-genesis bft-proposal MUST include, in addition to all Πorigbft-proposal fields:

  • headers_bc: a sequence of exactly σ bc-block headers (zero-indexed, deepest first, i.e., headers_bc[0] is deepest and headers_bc[σ-1] is the most recent). These headers MUST form a valid chain in Πbc (each header's parent hash must match the previous header's hash). The genesis bft-block has headers_bc = null.

bft-block structural additions

Each non-genesis bft-block MUST include, in addition to all Πorigbft-block fields:

  • headers_bc: the same sequence of σ bc-block headers as in the corresponding bft-proposal. The genesis bft-block has headers_bc = null.

Derived Functions

Based on the structural additions above, define:

snapshot(B)

For a bft-block or bft-proposal B:

snapshot(B) :=
  if B.headers_bc == null:
    Origin_bc
  else:
    B.headers_bc[0].truncate_bc(1)

That is, the bc-block one step before the deepest header in the snapshot, i.e., the bc-block at depth σ+1 relative to the tip of the snapshot chain. [11]

LF(H)

For a bc-block H:

LF(H) := bftLastFinal(H.context_bft)
candidate(H)

For a bc-block H:

candidate(H) := lastCommonAncestor(snapshot(LF(H)), H.truncate_bc(σ))

When H is the tip of a node's bc-best-chain, candidate(H) gives the candidate finalization point (subject to the local finalization update rule below). It represents the deepest bc-block that both (a) has been snapshotted by the last final bft-block in context, and (b) is at least σ deep in the bc-best-chain.

Locally Finalized Chain

Each node i maintains a locally finalized bc-chain localfin_i, initialized at Origin_bc. The chain state MUST NOT be exposed to external clients of the node until the node has synced (see Syncing and Checkpoints).

When node i's bc-best-chain view is updated from ch_i(s) to ch_i(t):

UpdateLocalFin(localfin_i, ch_i(t), s):
  let N = candidate(ch_i(t))
  if N is a descendant of localfin_i(s) (i.e., localfin_i(s) ≼ N):
    localfin_i(t) ← N
  else:
    localfin_i(t) ← localfin_i(s)
    if N conflicts with localfin_i(s) (i.e., neither is a prefix of the other):
      record a finalization safety hazard

A finalization safety hazard record SHOULD include ch_i(t) and the history of localfin_i updates including and since the last update that was an ancestor of N.

Lemma (Local Finalization Linearity): The time series of bc-blocks localfin_i(t) for any honest node i is bc-linear: for all times s ≤ t, localfin_i(s) ≼_bc localfin_i(t).

Proof: By the update rule, localfin_i(t) is either localfin_i(s) or a descendant of it, never a conflicting chain or an ancestor.

Lemma (Local Fin-Depth): For any honest node i at time t, there exists a time r ≤ t such that localfin_i(t) ≼_bc ch_i(r).truncate_bc(σ).

Proof: By definition of candidate, candidate(H) ≼ H.truncate_bc(σ) for all bc-blocks H. Let r ≤ t be the last time localfin_i(t) changed, or genesis time 0 if it has never changed.

Locally Bounded-Available Chain

Each node i chooses a bounded-availability depth μ where 0 < μ ≤ σ. The locally bounded-available chain is:

localba(μ)_i(t) := ch_i(t).truncate_bc(μ)

Syncing and Checkpoints

When a node first syncs or re-syncs, the locally finalized chain state MUST NOT be exposed to external clients until the node has processed the full bc-chain and bft-chain up to a recent point. The node MAY use checkpoints embedded in the software (committing to a known bc-block and bft-block at a given height) to accelerate syncing.

Checkpoints MUST be chosen conservatively to avoid committing to blocks that could be reorganized or that have not been finalized by CFP-SL. A checkpoint at bc-height h SHOULD only be used if CFP-SL has finalized bc-blocks up to height h - σ or deeper.

Πbft (CFP-SL) Changes from Πorigbft

BFT block and proposal validity

In addition to Πorigbft validity rules, a bft-proposal P is bft-valid only if:

  1. P.headers_bc is a sequence of exactly σ bc-block headers forming a valid bc-chain (headers are correctly linked by parent hashes and each satisfies the bc-block header validity rules, including proof-of-work and difficulty adjustment).

  2. For each header h in P.headers_bc, the proof-of-work MUST be valid (checking this requires only the headers, enabling DoS mitigation).

  3. P.headers_bc[σ-1] (the most recent header) MUST be at block height at least as great as the snapshot committed to in the bft-parent of P, to prevent proposers from referencing stale bc-chain snapshots.

  4. The bc-chain committed to by P.headers_bc MUST be consistent with (i.e., a descendant of) the snapshot committed to in the bft-parent of P.

BFT honest proposal rule (CFP-SL)

An honest CFP-SL Finalizer proposing a bft-block at time t MUST set headers_bc to the sequence of the most recent σ bc-block headers in the node's bc-best-chain at time t. The Finalizer MUST only propose if they have a bc-best-chain that is at least σ blocks deep.

BFT honest voting rule (CFP-SL)

An honest CFP-SL Finalizer voting on a bft-proposal P MUST verify that P.headers_bc satisfies the proposal validity rules above. In particular, it MUST verify proof-of-work for all headers in P.headers_bc before accepting the proposal.

If P.headers_bc connects to the Finalizer's known bc-chain, the Finalizer SHOULD download and fully validate any bc-blocks it has not yet seen before voting. If the headers do not connect to any known bc-chain, the Finalizer SHOULD assign lower priority to validating the proposal (to limit DoS exposure) and MAY drop it.

Πbc (Zcash PoW) Changes from Πorigbc

BC block validity (structural)

In addition to Πorigbc validity rules, a bc-block H is bc-valid only if:

  1. H.context_bft is a hash identifying a bft-valid block in Πbft.

  2. H.context_bft refers to a bft-block that is an ancestor of, or equal to, the bft-block referred to by H's bc-parent's context_bft field. (Context can only move forward in the bft-chain.)

BC contextual validity (finality gap)

A bc-block H is contextually valid only if the finality gap constraint is satisfied. Let fin_height(H) be the bc-height of candidate(H) and tip_height(H) be the bc-height of H. The finality gap is tip_height(H) - fin_height(H).

If the finality gap at H exceeds L, then H MUST be a stalled block (i.e., isStalledBlock(H) MUST return true).

BC honest block production

An honest bc-block producer creating bc-block H at time t MUST:

  1. Set H.context_bft to the hash of the most recent bft-valid block in the producer's CFP-SL node view at time t.

  2. Check the finality gap: if the finality gap would exceed L for the new block, the producer MUST apply the stalled-block policy.

  3. Not include H.context_bft referencing a bft-block whose headers_bc[σ-1] refers to a bc-block that is not a prefix of H's bc-ancestor chain (consistency check).

Stalled Mode Policy

The stalled-block predicate isStalledBlock(H) → Boolean determines whether a bc-block is a stalled block. The specific definition of isStalledBlock for the Zcash deployment is deferred to a subsequent consensus ZIP, but MUST satisfy:

  1. A stalled block MUST NOT include transactions that spend outputs created in bc-blocks that are not in the locally finalized chain (i.e., unfinalized outputs). This prevents users from having their funds locked in a deep unfinalized zone.

  2. A stalled block MAY include coinbase transactions for miner rewards.

  3. The validity of isStalledBlock(H) MUST be objectively determinable from H and its bc-ancestors (it requires no external state beyond the chain).

  4. Nodes MUST enforce the stalled block policy: a non-stalled block with a finality gap exceeding L MUST be rejected as bc-invalid.

Open questions

  • Should stalled blocks be permitted to include transactions spending finalized outputs only, or should they be entirely empty of user transactions? The tradeoff is between some throughput during a stall versus specification simplicity.

  • What is the correct definition of "unfinalized outputs" in the context of Zcash shielded transactions, where output ownership is not publicly visible?

TODO: Define the specific encoding of context_bft in Zcash block headers, including the exact byte representation of the bft-block hash reference.

TODO: Define the specific encoding of headers_bc in bft-proposals and bft-blocks, including the exact byte layout.

TODO: Specify the precise values of σ and L for Mainnet and Testnet.

Security Analysis

The following properties are claimed for CCC-SL under the stated assumptions.

Property: If CFP-SL satisfies Final Agreement and the Zcash PoW protocol satisfies Prefix Consistency, then for any two honest nodes i and j at any times t and u, their locally finalized chains are consistent: either localfin_i(t) ≼_bc localfin_j(u) or localfin_j(u) ≼_bc localfin_i(t).

Proof sketch: By the UpdateLocalFin rule, localfin_i(t) is always equal to candidate(ch_i(r)) for some time r ≤ t. By the definition of candidate, this is the last common ancestor of snapshot(LF(ch_i(r))) and ch_i(r).truncate_bc(σ).

By Final Agreement of CFP-SL, LF(ch_i(r)) and LF(ch_j(s)) (for any two honest nodes and times) must be consistent: one is an ancestor of the other in the bft-chain. By the monotonic inclusion of snapshots in bft-ancestor chains and Prefix Consistency of the PoW protocol, candidate(ch_i(r)) and candidate(ch_j(s)) are consistent bc-blocks. Since both localfin_i(t) and localfin_j(u) are derived from candidate values of consistent finalization points and consistent bc-chains, they must be consistent.

Bounded Availability

Property: If all honest bc-block producers follow the stalled-block policy, then every non-stalled bc-block accepted by honest full nodes has finality depth at most L. (Stalled blocks may have finality depth greater than L; the bound applies only to transaction-carrying, non-stalled blocks.)

Proof sketch: By the BC contextual validity rule, a bc-block whose finality gap exceeds L that is not a stalled block is rejected as bc-invalid. Since honest bc-block producers only produce stalled blocks when the gap would exceed L, and honest full nodes reject non-stalled blocks with tip_height(H) - fin_height(H) > L, all non-stalled blocks in any honest full node's view of the bc-chain satisfy tip_height(H) - fin_height(H) ≤ L. Stalled blocks may accumulate arbitrarily, but they do not carry new unfinalized-output-spending transactions, so the set of pending unfinalized user transactions is bounded.

Resilience of Finality to PoW Reorgs

Property: A rollback of the bc-best-chain shorter than σ blocks does not cause the locally finalized chain to roll back.

Proof sketch: The candidate finalization point candidate(H) for a chain tip H is at depth σ or deeper in the bc-chain (by the Local Fin-Depth lemma). A reorg of fewer than σ blocks cannot affect the bc-block at depth σ. Furthermore, the UpdateLocalFin rule only advances the locally finalized chain, never rolling it back.

Reference Implementation

A prototype implementation of CCC-SL is being developed in the zebra-crosslink component of [8] and integrated in the crosslink_monolith repository [9]. These implementations are experimental and should not be used in production.

Reference documentation for CCC-SL's theoretical foundations is available in the Zcash TFL design book [6], specifically the "Crosslink 2 Construction" chapter (which corresponds to CCC-TFLv2, the basis for CCC-SL).

References

Changes

README.rst +7 −2
@@ -208,10 +208,11 @@ written. <tr> <td>400</td> <td class="left"><a href="zips/zip-0400.rst">Wallet.dat format</a></td> <td>Draft</td> <td class="left"></td> <tr> <td><span class="reserved">402</span></td> <td class="left"><a class="reserved" href="zips/zip-0402.rst">New Wallet Database Format</a></td> <td>Reserved</td> <td class="left"><a href="https://github.com/zcash/zips/issues/365">zips#365</a></td> <tr> <td><span class="reserved">403</span></td> <td class="left"><a class="reserved" href="zips/zip-0403.rst">Verification Behaviour of zcashd</a></td> <td>Reserved</td> <td class="left"><a href="https://github.com/zcash/zips/issues/404">zips#404</a></td> - <tr> <td><span class="reserved">416</span></td> <td class="left"><a class="reserved" href="zips/zip-0416.rst">Support for Unified Addresses in zcashd</a></td> <td>Reserved</td> <td class="left"><a href="https://github.com/zcash/zips/issues/503">zips#503</a></td> + <tr> <td><span class="reserved">416</span></td> <td class="left"><a class="reserved" href="zips/zip-0416.rst">Spending Key Derivation in the `zcashd` wallet</a></td> <td>Reserved</td> <td class="left"><a href="https://github.com/zcash/zips/issues/1175">zips#1175</a></td> <tr> <td>2002</td> <td class="left"><a href="zips/zip-2002.rst">Explicit Fees</a></td> <td>Draft</td> <td class="left"><a href="https://github.com/zcash/zips/issues/803">zips#803</a></td> <tr> <td>2003</td> <td class="left"><a href="zips/zip-2003.rst">Disallow version 4 transactions</a></td> <td>Draft</td> <td class="left"><a href="https://github.com/zcash/zips/issues/825">zips#825</a></td> <tr> <td>2004</td> <td class="left"><a href="zips/zip-2004.rst">Remove the dependency of consensus on note encryption</a></td> <td>Draft</td> <td class="left"><a href="https://github.com/zcash/zips/issues/917">zips#917</a></td> + <tr> <td>CROSSLINK</td> <td class="left"><a href="zips/zip-CROSSLINK.md">The Crosslink Consensus Protocol</a></td> <td>Draft</td> <td class="left"></td> <tr> <td>guide-markdown</td> <td class="left"><a href="zips/zip-guide-markdown.md">{Something Short and To the Point}</a></td> <td>Draft</td> <td class="left"></td> <tr> <td>guide</td> <td class="left"><a href="zips/zip-guide.rst">{Something Short and To the Point}</a></td> <td>Draft</td> <td class="left"></td> <tr> <td>template</td> <td class="left"><a href="zips/zip-template.md">{Template for new ZIPs}</a></td> <td>Draft</td> <td class="left"></td> @@ -233,6 +234,9 @@ be deleted. <tr> <td class="left">draft-arya-deploy-nu7</td> <td class="left"><a href="zips/draft-arya-deploy-nu7.md">Deployment of the NU7 Network Upgrade</a></td> <td class="left"><a href="https://github.com/zcash/zips/issues/839">zips#839</a></td> <tr> <td class="left">draft-ecc-authenticated-reply-addrs</td> <td class="left"><a href="zips/draft-ecc-authenticated-reply-addrs.md">Authenticated Reply Addresses</a></td> <td class="left"><a href="https://github.com/zcash/zips/issues/1230">zips#1230</a></td> <tr> <td class="left">draft-ecc-onchain-accountable-voting</td> <td class="left"><a href="zips/draft-ecc-onchain-accountable-voting.md">On-chain Accountable Voting</a></td> <td class="left"></td> + <tr> <td class="left">draft-shieldedlabs-crosslink-construction</td> <td class="left"><a href="zips/draft-shieldedlabs-crosslink-construction.rst">CCC-SL: Crosslink Consensus Construction from Shielded Labs</a></td> <td class="left"></td> + <tr> <td class="left">draft-shieldedlabs-crosslink-ledger-state</td> <td class="left"><a href="zips/draft-shieldedlabs-crosslink-ledger-state.rst">RSM-SL-v1: Crosslink Ledger State and Ledger Mutations</a></td> <td class="left"></td> + <tr> <td class="left">draft-shieldedlabs-crosslink-overview</td> <td class="left"><a href="zips/draft-shieldedlabs-crosslink-overview.rst">Shielded Labs Crosslink v1: Protocol Overview and Architecture</a></td> <td class="left"></td> <tr> <td class="left">draft-str4d-orchard-balance-proof</td> <td class="left"><a href="zips/draft-str4d-orchard-balance-proof.md">Air drops, Proof-of-Balance, and Stake-weighted Polling</a></td> <td class="left"><a href="https://github.com/zcash/zips/issues/1229">zips#1229</a></td> </table></embed> @@ -368,7 +372,7 @@ Index of ZIPs <tr> <td>401</td> <td class="left"><a href="zips/zip-0401.rst">Addressing Mempool Denial-of-Service</a></td> <td>Active</td> <tr> <td><span class="reserved">402</span></td> <td class="left"><a class="reserved" href="zips/zip-0402.rst">New Wallet Database Format</a></td> <td>Reserved</td> <tr> <td><span class="reserved">403</span></td> <td class="left"><a class="reserved" href="zips/zip-0403.rst">Verification Behaviour of zcashd</a></td> <td>Reserved</td> - <tr> <td><span class="reserved">416</span></td> <td class="left"><a class="reserved" href="zips/zip-0416.rst">Support for Unified Addresses in zcashd</a></td> <td>Reserved</td> + <tr> <td><span class="reserved">416</span></td> <td class="left"><a class="reserved" href="zips/zip-0416.rst">Spending Key Derivation in the `zcashd` wallet</a></td> <td>Reserved</td> <tr> <td><strike>1001</strike></td> <td class="left"><strike><a href="zips/zip-1001.rst">Keep the Block Distribution as Initially Defined — 90% to Miners</a></strike></td> <td>Obsolete</td> <tr> <td><strike>1002</strike></td> <td class="left"><strike><a href="zips/zip-1002.rst">Opt-in Donation Feature</a></strike></td> <td>Obsolete</td> <tr> <td><strike>1003</strike></td> <td class="left"><strike><a href="zips/zip-1003.rst">20% Split Evenly Between the ECC and the Zcash Foundation, and a Voting System Mandate</a></strike></td> <td>Obsolete</td> @@ -390,6 +394,7 @@ Index of ZIPs <tr> <td>2003</td> <td class="left"><a href="zips/zip-2003.rst">Disallow version 4 transactions</a></td> <td>Draft</td> <tr> <td>2004</td> <td class="left"><a href="zips/zip-2004.rst">Remove the dependency of consensus on note encryption</a></td> <td>Draft</td> <tr> <td>2005</td> <td class="left"><a href="zips/zip-2005.md">Orchard Quantum Recoverability</a></td> <td>Proposed</td> + <tr> <td>CROSSLINK</td> <td class="left"><a href="zips/zip-CROSSLINK.md">The Crosslink Consensus Protocol</a></td> <td>Draft</td> <tr> <td>guide-markdown</td> <td class="left"><a href="zips/zip-guide-markdown.md">{Something Short and To the Point}</a></td> <td>Draft</td> <tr> <td>guide</td> <td class="left"><a href="zips/zip-guide.rst">{Something Short and To the Point}</a></td> <td>Draft</td> <tr> <td>template</td> <td class="left"><a href="zips/zip-template.md">{Template for new ZIPs}</a></td> <td>Draft</td>
zips/draft-shieldedlabs-crosslink-construction.rst +646 −0
@@ -0,0 +1,646 @@ +:: + + ZIP: Unassigned {numbers are assigned by ZIP editors} + Title: CCC-SL: Crosslink Consensus Construction from Shielded Labs + Owners: Nate Wilcox <nate@shieldedlabs.com> + Credits: Daira-Emma Hopwood + Jack Grigg + Kris Nuttycombe + Status: Draft + Category: Consensus + Created: 2026-04-08 + License: MIT + Discussions-To: TBD (no specific discussion thread yet) + + +Terminology +=========== + +The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this +document are to be interpreted as described in BCP 14 [#BCP14]_ when, and only +when, they appear in all capitals. + +The terms "Mainnet" and "Testnet" in this document are to be interpreted as +defined in the Zcash protocol specification [#protocol-networks]_. + +The terms below are to be interpreted as follows: + +CCC-SL (Crosslink Consensus Construction from Shielded Labs) + The hybrid consensus construction specified by this ZIP, integrating the + Zcash PoW best-chain protocol with ``CFP-SL`` to produce a protocol with + both availability and Crosslink Finality. CCC-SL is the core of Shielded + Labs Crosslink v1 and is closely based on CCC-TFLv2 from the TFL book + [#tfl-book]_. + +CCC-TFLv2 (Crosslink Consensus Construction from the TFL Book, version 2) + The abstract hybrid consensus construction documented in the Zcash TFL book + [#tfl-book]_. CCC-SL is the Shielded Labs adaptation and extension of this + construction for the Zcash PoW+TFL deployment. + +CFP-SL (Crosslink Finalization Protocol from Shielded Labs) + The BFT Proof-of-Stake finalization protocol used as the BFT subprotocol + within CCC-SL. CFP-SL satisfies the interface requirements (``Final + Agreement`` and related properties) defined in this ZIP. + +Best-chain subprotocol (Π\ :sub:`bc`) + The Zcash Proof-of-Work best-chain protocol, modified by CCC-SL to + participate in the hybrid construction. Blocks in this protocol are called + "bc-blocks" and chains are "bc-chains". + +Original best-chain subprotocol (Π\ :sub:`origbc`) + The "off-the-shelf" PoW best-chain protocol before CCC-SL modifications. + For the Zcash deployment, this corresponds to the Zcash NU5/NU6 consensus + protocol. + +BFT subprotocol (Π\ :sub:`bft`) + The BFT protocol (instantiated by ``CFP-SL``) modified to participate in + CCC-SL. Blocks in this protocol are called "bft-blocks" and finality is + called "bft-finality". + +Original BFT subprotocol (Π\ :sub:`origbft`) + The "off-the-shelf" BFT protocol before CCC-SL adaptation modifications. + CFP-SL is a specific instance of this with Zcash-specific adaptations. + +bc-confirmation-depth (σ) + A protocol parameter specifying the number of bc-block confirmations required + before a bc-block may be included in the snapshot referenced by a bft-block. + This is also the default depth used by nodes when computing the locally + finalized chain. + +Finalization gap bound (L) + A protocol parameter specifying the maximum number of unfinalized bc-blocks + permitted before CCC-SL enforces Stalled Mode. MUST satisfy ``L ≥ 2σ``. + +Bounded-availability depth (μ) + A per-node choice of confirmation depth for the locally bounded-available + chain, where ``0 < μ ≤ σ``. + +Locally finalized chain (``localfin``) + Each node's monotonically advancing view of the bc-chain that has been + finalized by ``CFP-SL``. Once a bc-block is in a node's locally finalized + chain, it will never be removed from it. + +Locally bounded-available chain (``localba``) + Each node's view of the confirmed (but not necessarily finalized) bc-chain, + computed using confirmation depth μ. + +Finality gap + At a given time, the number of bc-blocks in the bc-best-chain that have not + yet been finalized by ``CFP-SL``. + +Stalled Mode + A mode enforced by CCC-SL when the finality gap exceeds ``L``, during which + bc-block producers are constrained to produce only stalled blocks. + +Stalled block + A bc-block produced during Stalled Mode, constrained by the ``isStalledBlock`` + predicate (e.g., not including new user transactions that spend into the + unfinalized zone). + +Final Agreement + The property of the BFT subprotocol (``CFP-SL``) that all bft-valid blocks + in honest view are consistent: for any two such blocks, one must be an + ancestor of the other. + +Prefix Consistency + The property of the best-chain subprotocol (Zcash PoW) that any two honest + nodes' confirmed best-chains are consistent up to their confirmed depths. + +Crosslink Finality + The finality property provided by CCC-SL, as defined in the zebra-crosslink + design documentation [#zebra-crosslink-terminology]_. Formally: for any two + honest nodes ``i`` and ``j`` at any times ``t`` and ``u``, if both + ``localfin_i(t)`` and ``localfin_j(u)`` are non-genesis then one is a + prefix of the other (``localfin_i(t) ≼_bc localfin_j(u)`` or + ``localfin_j(u) ≼_bc localfin_i(t)``). See the Security Analysis section. + +``≼_bc`` (bc-prefix relation) + ``A ≼_bc B`` holds iff the bc-chain with tip ``A`` is a prefix of the + bc-chain with tip ``B``; equivalently, ``A`` is an ancestor of ``B`` or + ``A = B``. The notation ``≼`` (without subscript) is used as a shorthand + for ``≼_bc`` when the context is unambiguous. + +``C.truncate_bc(k)`` + For a bc-chain ``C`` and natural number ``k``: the bc-chain obtained by + removing the last ``k`` blocks from ``C``. The tip of ``C.truncate_bc(k)`` + is the block at depth ``k`` in ``C``. If ``len(C) ≤ k``, the result is the + genesis block ``Origin_bc``. When applied to a block ``H`` (shorthand for + the chain ending at ``H``), ``H.truncate_bc(k)`` denotes the block at + depth ``k`` from ``H``. + +``lastCommonAncestor(A, B)`` + For two bc-blocks ``A`` and ``B``: the most recent (deepest) bc-block that + is an ancestor of both ``A`` and ``B``. Equivalently, the tip of the longest + common prefix of the bc-chains ending at ``A`` and ``B``. If one block is an + ancestor of the other, ``lastCommonAncestor(A, B) = min(A, B)`` by depth. + +``bftLastFinal(B)`` + For a bft-block ``B``, the function returning the last bft-block that is + considered final in the context of ``B`` (including ``B`` itself, if + applicable). This function is defined by ``CFP-SL``. + +``snapshot(B)`` + For a bft-block or bft-proposal ``B``, the bc-block at the base of the + bc-chain snapshot committed to by ``B``. Formally: if ``B.headers_bc`` is + null (genesis), ``snapshot(B) = Origin_bc``; otherwise + ``snapshot(B) = B.headers_bc[0].truncate_bc(1)``. + +``LF(H)`` + For a bc-block ``H``, the last final bft-block in the context of ``H``: + ``LF(H) = bftLastFinal(H.context_bft)``. + +``candidate(H)`` + For a bc-block ``H``, the candidate finalization point: + ``candidate(H) = lastCommonAncestor(snapshot(LF(H)), H.truncate_bc(σ))``. + + +Abstract +======== + +This ZIP specifies **CCC-SL** (the Crosslink Consensus Construction from +Shielded Labs), the hybrid consensus protocol at the core of Shielded Labs +Crosslink v1 [#zip-crosslink-overview]_. CCC-SL integrates the Zcash +Proof-of-Work best-chain protocol with the ``CFP-SL`` BFT finalization +protocol to provide both the availability properties of the PoW chain and the +Crosslink Finality of a BFT protocol. + +CCC-SL is closely based on the ``CCC-TFLv2`` construction from the Zcash TFL +book [#tfl-book]_. The key features of CCC-SL are: + +1. Cross-referencing fields in both bc-blocks and bft-blocks/proposals that + allow each chain to objectively verify properties of the other. + +2. A locally finalized chain (``localfin``) maintained by each node that + advances monotonically and never rolls back. + +3. A locally bounded-available chain (``localba``) providing a + confirmed-but-not-necessarily-finalized view of the PoW chain. + +4. A Stalled Mode mechanism implementing bounded availability when the + finality gap exceeds the threshold ``L``. + +This ZIP is accompanied by ZIP [#zip-crosslink-overview]_, which provides the +design motivation and architecture overview for the full Shielded Labs +Crosslink v1 protocol suite. + + +Motivation +========== + +See ZIP [#zip-crosslink-overview]_ for the full motivation. In brief: + +* Zcash's current PoW-only consensus provides only probabilistic finality, + creating friction for exchanges, bridges, and other services. + +* Integrating ``CFP-SL`` as a finality layer via CCC-SL preserves PoW + availability and security while adding Crosslink Finality. + +* CCC-SL (following CCC-TFLv2) improves on the Snap-and-Chat construction + [#ebb-and-flow]_ by eliminating the need for transaction-log sanitization + and by implementing bounded availability. + +* The cross-referencing design of CCC-SL enables each chain to provide + objective validity checks on the other, strengthening the security of the + hybrid construction. + + +Requirements +============ + +CCC-SL MUST satisfy: + +* **Crosslink Finality**: If both subprotocols satisfy their safety assumptions, + the locally finalized chain of any two honest nodes must be consistent — + neither node's locally finalized chain can conflict with the other's. + +* **Local Finalization Linearity**: For each honest node, the locally finalized + chain is monotonically non-decreasing: it only ever advances forward, never + rolls back. + +* **Prefix Consistency** (inherited from Π\ :sub:`bc`): Two honest nodes' + confirmed best-chains must be consistent. + +* **Bounded Availability**: The finality depth of any non-stalled bc-block + MUST NOT exceed ``L`` while honest bc-block producers follow the protocol. + (Stalled blocks may exist at finality depth greater than ``L``; the bound + applies to transaction-carrying blocks only.) When the finality depth at the + chain tip exceeds ``L``, bc-block producers MUST enter Stalled Mode. + +* **Objective Validity**: The validity of any bc-block MUST be determinable + from the block itself and its ancestors in both chains, with no external + context beyond the two chains. + +* **Minimal Subprotocol Modification**: The modifications to the PoW and + ``CFP-SL`` subprotocols SHOULD be as minimal as possible while satisfying + the above requirements. + + +Non-requirements +================ + +The following are out of scope for this ZIP: + +* The specific BFT algorithm used internally by ``CFP-SL``. This ZIP specifies + only the interface requirements (Final Agreement, etc.) that + Π\ :sub:`origbft` must satisfy. The CFP-SL specification is a separate ZIP. + +* The staking mechanics, Finalizer registration, delegation, and slashing + rules (specified in the RSM-SL-v1 ZIP). + +* Reward distribution between PoW miners and Finalizers (a separate funding + ZIP). + +* The specific activation height(s) for the network upgrade. + + +Specification +============= + +Parameters +---------- + +CCC-SL is parameterized by: + +* **bc-confirmation-depth** ``σ ∈ ℕ⁺``: the number of bc-block headers + included in each bft-block's ``headers_bc`` field, representing the depth + at which a bc-block is considered confirmed for snapshotting purposes. This + is also the default confirmation depth for the locally finalized chain. + +* **Finalization gap bound** ``L ∈ ℕ⁺``, where ``L`` is significantly greater + than ``σ`` (the minimum is ``L ≥ 2σ``): the maximum finality gap before + Stalled Mode is enforced. + +The precise values of ``σ`` and ``L`` for Mainnet and Testnet deployment are +to be determined through a network upgrade process ZIP, taking into account +measured CFP-SL latency and desired time-to-finality targets. + +Subprotocol Interface Requirements +------------------------------------ + +CCC-SL places the following requirements on Π\ :sub:`origbft` (which is +instantiated as ``CFP-SL`` in Shielded Labs Crosslink v1): + +* Π\ :sub:`origbft` MUST be a protocol with an identified set of blocks + forming a DAG with a defined genesis block ``Origin_bft``. + +* Π\ :sub:`origbft` MUST define a function + ``bftValid(B) → Boolean`` determining whether a bft-block ``B`` is valid + in the context of the bft-chain. + +* Π\ :sub:`origbft` MUST define a function + ``bftLastFinal(B) → BftBlock`` returning the last bft-block that is + "final" in the context of bft-block ``B``, where ``bftLastFinal(Origin_bft) + = Origin_bft``. + +* Π\ :sub:`origbft` MUST satisfy **Final Agreement**: in any execution where + safety assumptions hold, for all bft-valid blocks ``C`` in honest view and + all times ``t``, ``bftLastFinal(C)`` must be an ancestor of every other + bft-valid block that honest nodes have finalized. + +CCC-SL places the following requirements on Π\ :sub:`origbc` (the Zcash PoW +protocol): + +* Π\ :sub:`origbc` MUST be a best-chain protocol with bc-blocks forming a tree + rooted at ``Origin_bc``. + +* Π\ :sub:`origbc` MUST define a fork-choice function selecting the "best + chain" among all bc-valid chains known to a node. + +* Π\ :sub:`origbc` MUST satisfy **Prefix Consistency** (Common Prefix): in any + execution where assumptions hold, for any two honest nodes' confirmed chains + ``C1`` and ``C2``, one is a prefix of the other. + +Structural Additions +-------------------- + +CCC-SL extends the block formats of both subprotocols with cross-referencing +fields: + +bc-block structural additions + Each bc-block header MUST include, in addition to all + Π\ :sub:`origbc`-block fields: + + * ``context_bft``: a hash identifying a bft-block. This commits the + bc-block producer to their view of the ``CFP-SL`` chain at the time the + block was produced. The referenced bft-block MUST be a bft-valid block in + the bc-block producer's view at the time of production. + +bft-proposal structural additions + Each non-genesis bft-proposal MUST include, in addition to all + Π\ :sub:`origbft`-proposal fields: + + * ``headers_bc``: a sequence of exactly ``σ`` bc-block headers (zero-indexed, + deepest first, i.e., ``headers_bc[0]`` is deepest and + ``headers_bc[σ-1]`` is the most recent). These headers MUST form a valid + chain in Π\ :sub:`bc` (each header's parent hash must match the previous + header's hash). The genesis bft-block has ``headers_bc = null``. + +bft-block structural additions + Each non-genesis bft-block MUST include, in addition to all + Π\ :sub:`origbft`-block fields: + + * ``headers_bc``: the same sequence of ``σ`` bc-block headers as in the + corresponding bft-proposal. The genesis bft-block has ``headers_bc = null``. + +Derived Functions +----------------- + +Based on the structural additions above, define: + +``snapshot(B)`` + For a bft-block or bft-proposal ``B``:: + + snapshot(B) := + if B.headers_bc == null: + Origin_bc + else: + B.headers_bc[0].truncate_bc(1) + + That is, the bc-block one step before the deepest header in the snapshot, + i.e., the bc-block at depth ``σ+1`` relative to the tip of the snapshot + chain. [#note-snapshot]_ + +``LF(H)`` + For a bc-block ``H``:: + + LF(H) := bftLastFinal(H.context_bft) + +``candidate(H)`` + For a bc-block ``H``:: + + candidate(H) := lastCommonAncestor(snapshot(LF(H)), H.truncate_bc(σ)) + + When ``H`` is the tip of a node's bc-best-chain, ``candidate(H)`` gives the + candidate finalization point (subject to the local finalization update rule + below). It represents the deepest bc-block that both (a) has been snapshotted + by the last final bft-block in context, and (b) is at least ``σ`` deep in + the bc-best-chain. + +Locally Finalized Chain +----------------------- + +Each node ``i`` maintains a locally finalized bc-chain ``localfin_i``, +initialized at ``Origin_bc``. The chain state MUST NOT be exposed to external +clients of the node until the node has synced (see `Syncing and Checkpoints`_). + +When node ``i``'s bc-best-chain view is updated from ``ch_i(s)`` to +``ch_i(t)``:: + + UpdateLocalFin(localfin_i, ch_i(t), s): + let N = candidate(ch_i(t)) + if N is a descendant of localfin_i(s) (i.e., localfin_i(s) ≼ N): + localfin_i(t) ← N + else: + localfin_i(t) ← localfin_i(s) + if N conflicts with localfin_i(s) (i.e., neither is a prefix of the other): + record a finalization safety hazard + +A finalization safety hazard record SHOULD include ``ch_i(t)`` and the history +of ``localfin_i`` updates including and since the last update that was an +ancestor of ``N``. + +**Lemma (Local Finalization Linearity)**: The time series of bc-blocks +``localfin_i(t)`` for any honest node ``i`` is bc-linear: for all times +``s ≤ t``, ``localfin_i(s) ≼_bc localfin_i(t)``. + +*Proof*: By the update rule, ``localfin_i(t)`` is either ``localfin_i(s)`` or +a descendant of it, never a conflicting chain or an ancestor. + +**Lemma (Local Fin-Depth)**: For any honest node ``i`` at time ``t``, there +exists a time ``r ≤ t`` such that +``localfin_i(t) ≼_bc ch_i(r).truncate_bc(σ)``. + +*Proof*: By definition of ``candidate``, ``candidate(H) ≼ H.truncate_bc(σ)`` +for all bc-blocks ``H``. Let ``r ≤ t`` be the last time ``localfin_i(t)`` +changed, or genesis time ``0`` if it has never changed. + +Locally Bounded-Available Chain +--------------------------------- + +Each node ``i`` chooses a bounded-availability depth ``μ`` where +``0 < μ ≤ σ``. The locally bounded-available chain is:: + + localba(μ)_i(t) := ch_i(t).truncate_bc(μ) + +.. warning:: + Choosing ``μ < σ`` is at the node's own risk and may increase susceptibility + to rollback attacks. The default SHOULD be ``μ = σ``. + +Syncing and Checkpoints +------------------------ + +When a node first syncs or re-syncs, the locally finalized chain state MUST +NOT be exposed to external clients until the node has processed the full bc-chain +and bft-chain up to a recent point. The node MAY use checkpoints embedded in +the software (committing to a known bc-block and bft-block at a given height) +to accelerate syncing. + +Checkpoints MUST be chosen conservatively to avoid committing to blocks that +could be reorganized or that have not been finalized by ``CFP-SL``. A +checkpoint at bc-height ``h`` SHOULD only be used if ``CFP-SL`` has finalized +bc-blocks up to height ``h - σ`` or deeper. + +Π\ :sub:`bft` (CFP-SL) Changes from Π\ :sub:`origbft` +-------------------------------------------------------- + +BFT block and proposal validity + In addition to Π\ :sub:`origbft` validity rules, a bft-proposal ``P`` is + bft-valid only if: + + 1. ``P.headers_bc`` is a sequence of exactly ``σ`` bc-block headers forming + a valid bc-chain (headers are correctly linked by parent hashes and each + satisfies the bc-block header validity rules, including proof-of-work and + difficulty adjustment). + + 2. For each header ``h`` in ``P.headers_bc``, the proof-of-work MUST be + valid (checking this requires only the headers, enabling DoS mitigation). + + 3. ``P.headers_bc[σ-1]`` (the most recent header) MUST be at block height + at least as great as the snapshot committed to in the bft-parent of + ``P``, to prevent proposers from referencing stale bc-chain snapshots. + + 4. The bc-chain committed to by ``P.headers_bc`` MUST be consistent with + (i.e., a descendant of) the snapshot committed to in the bft-parent of + ``P``. + +BFT honest proposal rule (CFP-SL) + An honest CFP-SL Finalizer proposing a bft-block at time ``t`` MUST set + ``headers_bc`` to the sequence of the most recent ``σ`` bc-block headers + in the node's bc-best-chain at time ``t``. The Finalizer MUST only propose + if they have a bc-best-chain that is at least ``σ`` blocks deep. + +BFT honest voting rule (CFP-SL) + An honest CFP-SL Finalizer voting on a bft-proposal ``P`` MUST verify that + ``P.headers_bc`` satisfies the proposal validity rules above. In particular, + it MUST verify proof-of-work for all headers in ``P.headers_bc`` before + accepting the proposal. + + If ``P.headers_bc`` connects to the Finalizer's known bc-chain, the + Finalizer SHOULD download and fully validate any bc-blocks it has not yet + seen before voting. If the headers do not connect to any known bc-chain, the + Finalizer SHOULD assign lower priority to validating the proposal (to limit + DoS exposure) and MAY drop it. + +Π\ :sub:`bc` (Zcash PoW) Changes from Π\ :sub:`origbc` +--------------------------------------------------------- + +BC block validity (structural) + In addition to Π\ :sub:`origbc` validity rules, a bc-block ``H`` is + bc-valid only if: + + 1. ``H.context_bft`` is a hash identifying a bft-valid block in + Π\ :sub:`bft`. + + 2. ``H.context_bft`` refers to a bft-block that is an ancestor of, or + equal to, the bft-block referred to by ``H``'s bc-parent's + ``context_bft`` field. (Context can only move forward in the bft-chain.) + +BC contextual validity (finality gap) + A bc-block ``H`` is contextually valid only if the finality gap constraint + is satisfied. Let ``fin_height(H)`` be the bc-height of ``candidate(H)`` + and ``tip_height(H)`` be the bc-height of ``H``. The finality gap is + ``tip_height(H) - fin_height(H)``. + + If the finality gap at ``H`` exceeds ``L``, then ``H`` MUST be a stalled + block (i.e., ``isStalledBlock(H)`` MUST return ``true``). + +BC honest block production + An honest bc-block producer creating bc-block ``H`` at time ``t`` MUST: + + 1. Set ``H.context_bft`` to the hash of the most recent bft-valid block + in the producer's CFP-SL node view at time ``t``. + + 2. Check the finality gap: if the finality gap would exceed ``L`` for the + new block, the producer MUST apply the stalled-block policy. + + 3. Not include ``H.context_bft`` referencing a bft-block whose + ``headers_bc[σ-1]`` refers to a bc-block that is not a prefix of + ``H``'s bc-ancestor chain (consistency check). + +Stalled Mode Policy +-------------------- + +The stalled-block predicate ``isStalledBlock(H) → Boolean`` determines whether +a bc-block is a stalled block. The specific definition of ``isStalledBlock`` +for the Zcash deployment is deferred to a subsequent consensus ZIP, but MUST +satisfy: + +1. A stalled block MUST NOT include transactions that spend outputs created in + bc-blocks that are not in the locally finalized chain (i.e., unfinalized + outputs). This prevents users from having their funds locked in a deep + unfinalized zone. + +2. A stalled block MAY include coinbase transactions for miner rewards. + +3. The validity of ``isStalledBlock(H)`` MUST be objectively determinable from + ``H`` and its bc-ancestors (it requires no external state beyond the chain). + +4. Nodes MUST enforce the stalled block policy: a non-stalled block with a + finality gap exceeding ``L`` MUST be rejected as bc-invalid. + +Open questions +'''''''''''''' + +* Should stalled blocks be permitted to include transactions spending finalized + outputs only, or should they be entirely empty of user transactions? The + tradeoff is between some throughput during a stall versus specification + simplicity. + +* What is the correct definition of "unfinalized outputs" in the context of + Zcash shielded transactions, where output ownership is not publicly visible? + +TODO: Define the specific encoding of ``context_bft`` in Zcash block headers, +including the exact byte representation of the bft-block hash reference. + +TODO: Define the specific encoding of ``headers_bc`` in bft-proposals and +bft-blocks, including the exact byte layout. + +TODO: Specify the precise values of ``σ`` and ``L`` for Mainnet and Testnet. + +Security Analysis +----------------- + +The following properties are claimed for CCC-SL under the stated assumptions. + +Crosslink Finality +'''''''''''''''''' + +**Property**: If ``CFP-SL`` satisfies Final Agreement and the Zcash PoW +protocol satisfies Prefix Consistency, then for any two honest nodes ``i`` and +``j`` at any times ``t`` and ``u``, their locally finalized chains are +consistent: either ``localfin_i(t) ≼_bc localfin_j(u)`` or +``localfin_j(u) ≼_bc localfin_i(t)``. + +*Proof sketch*: By the ``UpdateLocalFin`` rule, ``localfin_i(t)`` is always +equal to ``candidate(ch_i(r))`` for some time ``r ≤ t``. By the definition of +``candidate``, this is the last common ancestor of ``snapshot(LF(ch_i(r)))`` +and ``ch_i(r).truncate_bc(σ)``. + +By Final Agreement of ``CFP-SL``, ``LF(ch_i(r))`` and ``LF(ch_j(s))`` (for +any two honest nodes and times) must be consistent: one is an ancestor of the +other in the bft-chain. By the monotonic inclusion of snapshots in bft-ancestor +chains and Prefix Consistency of the PoW protocol, ``candidate(ch_i(r))`` and +``candidate(ch_j(s))`` are consistent bc-blocks. Since both +``localfin_i(t)`` and ``localfin_j(u)`` are derived from ``candidate`` values +of consistent finalization points and consistent bc-chains, they must be +consistent. + +Bounded Availability +'''''''''''''''''''' + +**Property**: If all honest bc-block producers follow the stalled-block policy, +then every non-stalled bc-block accepted by honest full nodes has finality depth +at most ``L``. (Stalled blocks may have finality depth greater than ``L``; the +bound applies only to transaction-carrying, non-stalled blocks.) + +*Proof sketch*: By the BC contextual validity rule, a bc-block whose finality +gap exceeds ``L`` that is not a stalled block is rejected as bc-invalid. Since +honest bc-block producers only produce stalled blocks when the gap would exceed +``L``, and honest full nodes reject non-stalled blocks with +``tip_height(H) - fin_height(H) > L``, all non-stalled blocks in any honest +full node's view of the bc-chain satisfy ``tip_height(H) - fin_height(H) ≤ L``. +Stalled blocks may accumulate arbitrarily, but they do not carry new +unfinalized-output-spending transactions, so the set of pending unfinalized +user transactions is bounded. + +Resilience of Finality to PoW Reorgs +'''''''''''''''''''''''''''''''''''''' + +**Property**: A rollback of the bc-best-chain shorter than ``σ`` blocks does +not cause the locally finalized chain to roll back. + +*Proof sketch*: The candidate finalization point ``candidate(H)`` for a chain +tip ``H`` is at depth ``σ`` or deeper in the bc-chain (by the Local Fin-Depth +lemma). A reorg of fewer than ``σ`` blocks cannot affect the bc-block at depth +``σ``. Furthermore, the ``UpdateLocalFin`` rule only advances the locally +finalized chain, never rolling it back. + + +Reference Implementation +======================== + +A prototype implementation of CCC-SL is being developed in the +``zebra-crosslink`` component of [#zebra-crosslink]_ and integrated in the +``crosslink_monolith`` repository [#crosslink-monolith]_. These implementations +are experimental and should not be used in production. + +Reference documentation for CCC-SL's theoretical foundations is available in +the Zcash TFL design book [#tfl-book]_, specifically the "Crosslink 2 +Construction" chapter (which corresponds to CCC-TFLv2, the basis for CCC-SL). + + +References +========== + +.. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" <https://www.rfc-editor.org/info/bcp14>`_ +.. [#protocol] `Zcash Protocol Specification, Version 2022.3.8 or later <protocol/protocol.pdf>`_ +.. [#protocol-networks] `Zcash Protocol Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet <protocol/protocol.pdf#networks>`_ +.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism <zip-0200.rst>`_ +.. [#zip-crosslink-overview] `ZIP [Unassigned]: Shielded Labs Crosslink v1: Protocol Overview and Architecture <draft-shieldedlabs-crosslink-overview.rst>`_ +.. [#tfl-book] `Zcash Trailing Finality Layer Design Book — The Crosslink 2 Construction <https://electric-coin-company.github.io/tfl-book/design/crosslink/construction.html>`_ +.. [#ebb-and-flow] `Ebb-and-Flow Protocols: A Resolution of the Availability-Finality Dilemma. David Neu, Joachim Neu, Ertem Nusret Tas, David Tse. <https://eprint.iacr.org/2020/1091.pdf>`_ +.. [#zebra-crosslink] `ShieldedLabs zebra-crosslink repository <https://github.com/ShieldedLabs/zebra-crosslink>`_ +.. [#crosslink-monolith] `ShieldedLabs crosslink_monolith repository <https://github.com/ShieldedLabs/crosslink_monolith>`_ +.. [#zebra-crosslink-terminology] `Shielded Labs zebra-crosslink design book: Terminology <https://github.com/ShieldedLabs/zebra-crosslink/blob/main/book/src/design/terminology.md>`_ + +.. [#note-snapshot] The snapshot function returns the bc-block at depth 1 from the deepest header, i.e., the parent of ``headers_bc[0]``. This means the snapshot is a bc-block at depth ``σ+1`` relative to the tip of the snapshotted chain. This ensures that a bft-block referring to a snapshot provides evidence (via the ``σ`` headers) that the snapshot was confirmed at the time of the proposal.
zips/draft-shieldedlabs-crosslink-ledger-state.rst +261 −0
@@ -0,0 +1,261 @@ +:: + + ZIP: Unassigned {numbers are assigned by ZIP editors} + Title: RSM-SL-v1: Crosslink Ledger State and Ledger Mutations + Owners: Nate Wilcox <nate@shieldedlabs.com> + Credits: Daira-Emma Hopwood + Jack Grigg + Kris Nuttycombe + Status: Draft + Category: Consensus + Created: 2026-06-03 + License: MIT + Discussions-To: TBD (no specific discussion thread yet) + + +Terminology +=========== + +The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this +text are to be interpreted as described in BCP 14 [#BCP14]_ when, and only +when, they appear in all capitals. + +The terms "Mainnet" and "Testnet" in this document are to be interpreted as +defined in the Zcash protocol specification [#protocol-networks]_. + +The terms below are to be interpreted as follows: + +RSM-SL-v1 + The Shielded Labs v1 instantiation of the roster state module referenced by + the Crosslink Overview ZIP [#zip-crosslink-overview]_. + +Idealized ledger state + A point-in-time abstract data structure used for specification and consensus + reasoning. Implementations MAY use equivalent internal layouts, but MUST + produce exactly the same externally verifiable state transitions as if they + had updated this idealized structure directly. + +Bond + A delegated ZEC amount associated with a Finalizer identifier and tracked by + this specification's ledger state rules. + +Candidate Roster + A deterministic mapping from Finalizer identifiers to voting weights, + computed by summing all currently effective bonds for each Finalizer. + +Active Finalizer set + The top ``K`` Finalizers by voting weight in the Candidate Roster, where + ``K = 100``. + +Most-recent-final ancestor + For any PoW tip block, the unique most recent ancestor on that tip's chain + that is finalized under CCC-SL [#zip-ccc-sl]_. + + +Abstract +======== + +This ZIP specifies the Crosslink ledger-state changes required by RSM-SL-v1. +It defines the idealized point-in-time ledger state extension, and the ledger +mutation rules that update this state, including issuance distribution and +roster mutations. + +The specification is layered: + +* abstract Proof-of-Stake actions over ledger state, and +* concrete consensus extensions to Zcash transaction fields and semantics. + + +Motivation +========== + +The Crosslink Overview ZIP defines RSM-SL-v1 conceptually but leaves the +consensus state and mutation details to a companion specification. Nodes need a +single, deterministic definition of: + +* how Finalizer voting weights are derived from on-chain bonds, +* how the active BFT roster is selected, and +* how roster-related state evolves as blocks are applied and reverted. + +Without this ZIP, implementations may diverge on ledger state interpretation, +producing incompatible active rosters and finality inputs. + + +Requirements +============ + +This ZIP MUST specify the following: + +* An idealized ledger state extension over the existing Zcash ledger state, + including bonds, Finalizer identifiers, and cryptographic material needed for + self-authenticating roster membership. +* Candidate Roster construction by summing currently effective bonds per + Finalizer, and Active Finalizer set selection as the top ``K = 100`` by + voting weight. +* Dual-state interpretation in which ledger processing distinguishes finalized + state from tip state, with each tip having an objectively verifiable + most-recent-final ancestor. +* Ledger mutation rules for issuance distribution and roster mutations. +* A two-layer mutation definition: + + 1. abstract PoS actions, and + 2. concrete Zcash transaction-field and transaction-semantic extensions. + + +Non-requirements +================ + +The following are out of scope for this ZIP: + +* Pre-existing Zcash ledger state, except where it is extended or requires new + considerations due to Crosslink. +* The Crosslink mechanism itself (including chain selection and finality-status + verification), specified in CCC-SL [#zip-ccc-sl]_. +* Internal BFT protocol design, except that the Active Finalizer set is an + input provided by this ZIP. +* Networking behavior outside transaction format and transaction semantics. +* Topics designated as separate ZIPs in the Crosslink overview + [#zip-crosslink-overview]_. + + +Specification +============= + +Idealized Ledger State Extension +-------------------------------- + +Let ``S_zec`` denote the existing Zcash ledger state. This ZIP defines an +extended idealized state ``S_xl`` that behaves as: + +* ``S_xl = (S_zec, S_roster, S_finality_views, S_issuance)``. +* ``S_roster`` includes at minimum: + + * bond records keyed by bond identifier, + * Finalizer identity records, + * cryptographic verification keys and status metadata, + * deterministic activation/deactivation metadata needed for roster + computation. + +* ``S_finality_views`` tracks finalized and tip-relative views so that, for each + accepted tip, the corresponding most-recent-final ancestor is objectively + derivable from block data and finalized commitments. +* ``S_issuance`` tracks distribution state required to apply issuance rules that + involve Finalizers. + +Consensus behavior MUST be equivalent to transitions over ``S_xl`` even when an +implementation does not materialize ``S_xl`` as one in-memory object. + +Candidate Roster and Active Finalizers +-------------------------------------- + +For each state ``S_xl`` at a given chain point: + +* Candidate voting weight for Finalizer ``f`` is the sum of all currently + effective bond amounts targeting ``f``. +* Candidate Roster computation MUST be deterministic for every honest node given + the same chain history. +* The Active Finalizer set is the top ``K = 100`` Finalizers by candidate voting + weight. +* Tie-breaking for equal weights MUST be deterministic and based only on + consensus-visible data. +* The active roster output MUST be suitable as an input to CFP-SL voting-weight + selection. + +Finalized and Tip State Relationship +------------------------------------ + +Ledger processing MUST expose both: + +* a finalized state view anchored at finalized history, and +* a tip state view for each accepted PoW tip. + +For every accepted tip, nodes MUST be able to derive an objectively verifiable +most-recent-final ancestor from consensus data. Reorganizations MUST preserve +this invariant and recompute dependent tip state deterministically. + +Ledger Mutations: Abstract Action Layer +--------------------------------------- + +This ZIP defines abstract actions that mutate ``S_xl``: + +* ``BondCreate``: create a bond linking stake to a Finalizer identifier. +* ``BondAdjust``: increase or decrease an existing bond according to consensus + constraints. +* ``BondDeactivate``: transition stake out of active weighting, including + unbonding behavior. +* ``FinalizerRegister`` and ``FinalizerUpdate``: manage Finalizer identity and + associated cryptographic keys. +* ``FinalizerDeactivate``: remove a Finalizer from future roster eligibility. +* ``Slash``: apply deterministic penalties for provable misbehavior. +* ``DistributeIssuance``: apply issuance distribution updates affecting miner + and Finalizer-related allocation state. + +Each action MUST define preconditions, state transition effects, and reversion +behavior under chain rollback. + +Ledger Mutations: Concrete Zcash Transaction Semantics +------------------------------------------------------ + +Consensus transaction rules are extended so that specific transaction patterns +encode the abstract actions above. This layer MUST define: + +* the concrete transaction fields and encodings used for roster-related actions, +* validity checks for signatures, authorization, and amount constraints, +* ordering and interaction rules when multiple roster actions appear in one + block, +* rejection behavior for malformed, unauthorized, or semantically conflicting + actions. + +Applying a valid block MUST induce exactly the same abstract action sequence on +``S_xl`` at all honest nodes. + +Issuance Distribution and Roster Interaction +-------------------------------------------- + +Issuance distribution rules covered by this ZIP MUST specify: + +* which issuance components are affected by roster/finalizer state, +* when issuance state updates occur relative to other per-block mutations, and +* deterministic accounting behavior under normal progression and reorgs. + +Detailed policy values (for example, exact allocation percentages) MAY be set by +separate process or funding ZIPs, but this ZIP defines the consensus state +transition hooks that enforce whichever policy is activated. + + +Rationale +========= + +Separating this specification from CCC-SL keeps concerns modular: + +* CCC-SL specifies the hybrid-consensus construction and finality properties. +* This ZIP specifies the ledger-state machine that supplies active roster input + and applies roster-related mutations inside Zcash consensus processing. + +This split keeps each ZIP auditable while preserving deterministic integration. + + +Deployment +========== + +This ZIP is intended to activate through the Zcash network-upgrade mechanism +[#zip-0200]_ alongside the other required Crosslink ZIPs. + + +Reference Implementation +======================== + +A prototype implementation is under development in the Shielded Labs +``zebra-crosslink`` and ``crosslink_monolith`` repositories, referenced from +ZIP [#zip-crosslink-overview]_. + + +References +========== + +.. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" <https://www.rfc-editor.org/info/bcp14>`_ +.. [#protocol] `Zcash Protocol Specification, Version 2022.3.8 or later <protocol/protocol.pdf>`_ +.. [#protocol-networks] `Zcash Protocol Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet <protocol/protocol.pdf#networks>`_ +.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism <zip-0200.rst>`_ +.. [#zip-ccc-sl] `ZIP [Unassigned]: CCC-SL: Crosslink Consensus Construction from Shielded Labs <draft-shieldedlabs-crosslink-construction.rst>`_ +.. [#zip-crosslink-overview] `ZIP [Unassigned]: Shielded Labs Crosslink v1: Protocol Overview and Architecture <draft-shieldedlabs-crosslink-overview.rst>`_
zips/draft-shieldedlabs-crosslink-overview.rst +726 −0
@@ -0,0 +1,726 @@ +:: + + ZIP: Unassigned {numbers are assigned by ZIP editors} + Title: Shielded Labs Crosslink v1: Protocol Overview and Architecture + Owners: Nate Wilcox <nate@shieldedlabs.com> + Credits: Daira-Emma Hopwood + Jack Grigg + Kris Nuttycombe + Status: Draft + Category: Informational + Created: 2026-04-08 + License: MIT + Discussions-To: TBD (no specific discussion thread yet) + + +Terminology +=========== + +The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this +document are to be interpreted as described in BCP 14 [#BCP14]_ when, and only +when, they appear in all capitals. + +The terms "Mainnet" and "Testnet" in this document are to be interpreted as +defined in the Zcash protocol specification [#protocol-networks]_. + +The terms below are to be interpreted as follows: + +Zcash Trailing Finality Layer (TFL) + An initiative by the former Electric Coin Company (ECC) to augment the + Zcash Proof-of-Work consensus with a Proof-of-Stake finality layer, + documented in the TFL book [#tfl-book]_. The TFL initiative produced the + theoretical design basis for Shielded Labs Crosslink v1. + +Crosslink Consensus Construction from the TFL Book (CCC-TFLv2) + The abstract hybrid consensus construction documented in the TFL book + [#tfl-book]_, version 2. CCC-TFLv2 describes how to integrate a best-chain + (PoW) protocol with a BFT (PoS) protocol and provides a formal security + analysis of the resulting hybrid. This construction is the direct theoretical + basis for ``CCC-SL``. + +Shielded Labs Crosslink v1 + The complete protocol and working implementation produced by the Shielded + Labs non-profit, extending CCC-TFLv2 with additional practical and + theoretical design details necessary for a production deployment. Shielded + Labs Crosslink v1 is a superset of the TFL in several respects: it includes + a fully prototyped working implementation, and it extends the older TFL + design with additional components (``CFP-SL``, ``RSM-SL-v1``, ``CNTP-SL``) + that are not fully specified in the TFL book. This ZIP and its companions + specify the protocols of Shielded Labs Crosslink v1. + +Crosslink Consensus Construction from Shielded Labs (CCC-SL) + The abstract hybrid consensus construction that is the core of Shielded Labs + Crosslink v1, inspired by CCC-TFLv2. CCC-SL treats the Zcash PoW protocol + and ``CFP-SL`` as somewhat opaque subprotocols, each performing their own + consensus, while requiring specific cross-referencing modifications to each. + CCC-SL is specified in ZIP [#zip-ccc-sl]_. + +Crosslink Finalization Protocol from Shielded Labs (CFP-SL) + The Proof-of-Stake BFT protocol used as the finalization subprotocol in + Shielded Labs Crosslink v1, with "adaptation modifications" to interface + with ``CCC-SL``. ``CFP-SL`` provides Crosslink Finality by running Byzantine + Fault Tolerant consensus over snapshots of the Zcash PoW chain. + +Roster State Module (RSM) + An abstract interface required by ``CFP-SL``. The RSM provides the latest + ``Active Roster Mapping`` from cryptographically self-authenticating vote + verifier identities to their associated voting weights. The Active Roster + Mapping also defines ``Roster Evolution Rules``, which are a subset of + ledger state evolution rules composing Zcash's ledger state consensus. + +RSM-SL-v1 + The specific instantiation of the Roster State Module for Shielded Labs + Crosslink v1. RSM-SL-v1 defines all staking rules that users interact with + directly: staking ZEC to a Finalizer identity, unbonding periods, amount + quantization, slashing conditions, and related rules. + +Crosslink Network Transport Protocol from Shielded Labs (CNTP-SL) + The network transport layer for Shielded Labs Crosslink v1, enabling + ``CFP-SL`` to safely and efficiently disseminate finality updates. + ``CNTP-SL`` provides pragmatic protections against network threats (DoS, + message tampering, etc.) and improvements over the status quo Zcash p2p + protocol, including transport-layer encryption, faster block and ledger + syncing, and firewall traversal. + +Active Roster Mapping + A mapping from Finalizer vote-verifier public keys to their associated + voting weights, maintained by the Roster State Module. This mapping defines + which parties are authorized to participate in ``CFP-SL`` voting at a given + point in the ledger history. + +Finalizer + A participant in the ``CFP-SL`` subprotocol who holds an active entry in + the Active Roster Mapping and participates in BFT consensus to finalize + PoW blocks. + +Roster Evolution Rules + The subset of ledger state evolution rules (within Zcash's consensus) that + govern how the Active Roster Mapping changes over time: new stakers joining, + unstaking and unbonding, slashing, and similar events. + +Crosslink Finality + The finality property provided by Shielded Labs Crosslink v1, as defined in + the zebra-crosslink design documentation [#zebra-crosslink-terminology]_. + Crosslink Finality has five key characteristics: + + 1. **Accountable**: Safety violations can be attributed to specific + Finalizers, enabling slashing penalties. + 2. **Irreversible**: Once a block achieves Crosslink Finality, it cannot be + reverted by the protocol under any circumstances permitted by the security + assumptions. + 3. **Objectively verifiable**: Any third party with access to the chain data + can independently verify whether a given block has achieved Crosslink + Finality without trusting any particular node. + 4. **Globally consistent**: All honest nodes that agree on the chain data + agree on which blocks have achieved Crosslink Finality. + 5. **Asymmetric cost-of-attack defense**: An adversary seeking to violate + Crosslink Finality must expend significantly more resources than honest + participants spend to maintain it. + +Trailing Finality + A protocol property wherein transactions become final some time after first + appearing in PoW blocks. + +Bounded Availability + The property that the best-chain ledger does not grow unboundedly ahead of + the finalized ledger during a finality stall, preventing indefinite + accumulation of unfinalized transactions. + +Finality Gap + The number of best-chain (PoW) blocks that have not yet been finalized by + ``CFP-SL`` at a given time. + +Stalled Mode + A mode entered when the finality gap exceeds a threshold ``L``, indicating + an exceptional or emergency condition. In Stalled Mode, PoW block producers + are constrained by the ``CCC-SL`` rules to produce only stalled blocks. + + +Abstract +======== + +This ZIP describes the high-level design goals, motivations, and architecture +of **Shielded Labs Crosslink v1**, a complete protocol and implementation +produced by the Shielded Labs non-profit to add Crosslink Finality to the +Zcash network. + +Shielded Labs Crosslink v1 builds on the Zcash Trailing Finality Layer (TFL) +initiative and its ``CCC-TFLv2`` hybrid construction, extending it into a +deployable system with a fully specified finalization protocol (``CFP-SL``), +staking rules (``RSM-SL-v1``), and network transport layer (``CNTP-SL``). The +core hybrid consensus mechanism is ``CCC-SL``, which is formally specified in +ZIP [#zip-ccc-sl]_. + +This document is intended as the top-level overview for the entire Shielded +Labs Crosslink v1 protocol suite. It does not itself specify consensus rules, +but provides the rationale, component definitions, architecture diagram, and +cross-references needed to understand and evaluate the companion ZIPs. + + +Background: The TFL Initiative and CCC-TFLv2 +============================================= + +The Zcash Trailing Finality Layer (TFL) was an initiative by the former +Electric Coin Company (ECC) to introduce Crosslink Finality to Zcash through +a hybrid Proof-of-Work / Proof-of-Stake consensus design. The TFL design book +[#tfl-book]_ documents this initiative and produces the Crosslink Consensus +Construction (version 2, ``CCC-TFLv2``), which provides the theoretical +framework and security analysis for integrating a PoW chain with a BFT +finality layer. + +Shielded Labs Crosslink v1 is a successor to the TFL initiative, produced by +the Shielded Labs non-profit. While ``CCC-TFLv2`` provides the abstract +consensus foundation, many practical design and implementation details were +left unspecified in the TFL book. Shielded Labs has extended the TFL work in +several important ways: + +* **CCC-SL**: A fully specified consensus construction closely following + CCC-TFLv2 but with practical adaptations and Zcash-specific details. + +* **CFP-SL**: A complete specification and prototype implementation of the + BFT finalization protocol (the ``Π_bft`` component left abstract in + CCC-TFLv2). + +* **RSM-SL-v1**: A full specification of the staking rules and roster + management (the "PoS staking mechanics" left unspecified in CCC-TFLv2). + +* **CNTP-SL**: A network transport layer for finality updates (entirely new + relative to CCC-TFLv2, which does not address the network layer). + +* **Working prototype**: A complete prototype implementation based on Zebra + [#zebra-crosslink]_ demonstrating all components working together. + +Readers who wish to understand the theoretical foundations of the consensus +construction are encouraged to read the TFL book [#tfl-book]_ alongside these +ZIPs, with the understanding that Shielded Labs Crosslink v1 may use different +terminology and make different design trade-offs in some areas. + + +Motivation +========== + +Probabilistic vs. Crosslink Finality +-------------------------------------- + +The current Zcash consensus protocol uses Nakamoto-style Proof-of-Work, which +provides only *probabilistic* finality: a transaction confirmed at depth ``k`` +can theoretically be reversed by an adversary with sufficient hash rate. +Although deep reorgs are costly and increasingly unlikely as depth increases, +they are not impossible. This limitation has several practical consequences: + +* **Exchange and service delays**: Exchanges and other services must wait for + many confirmations before crediting deposits, increasing friction for users. + +* **Bridge trust assumptions**: Cross-chain bridges and atomic swaps must + account for reorg risk, often requiring conservative confirmation depths or + additional trust assumptions. + +* **Wallet complexity**: Wallets must communicate uncertainty about + transaction finality to users, complicating UX. + +Crosslink Finality — the property that a finalized transaction *cannot* be +reversed by the protocol — removes these limitations. Any system that can +rely on Crosslink Finality can offer faster, safer service with simpler +reasoning about transaction status. + +Why Proof-of-Stake for Finality? +--------------------------------- + +Proof-of-Stake (PoS) consensus protocols using Byzantine Fault Tolerant (BFT) +algorithms are well-established approaches for providing Crosslink Finality. +Tendermint, PBFT, Casper, and related protocols all achieve this goal with +strong theoretical foundations. Integrating a BFT PoS layer into Zcash as a +*finality layer* — rather than replacing PoW entirely — allows the ecosystem to: + +1. **Retain PoW security**: The PoW chain continues to provide its well-understood + liveness and censorship-resistance properties. + +2. **Add PoS staking rewards**: ZEC holders can participate in network security + by staking ZEC (directly or by delegating to a Finalizer), earning protocol + rewards. + +3. **Minimize disruption**: The transition preserves existing wallets, services, + and tooling with minimal required changes. + +4. **Enable future evolution**: A successful hybrid PoW/PoS transition builds + confidence and infrastructure for potential future full PoS transitions. + +Why CCC-SL Rather Than Snap-and-Chat? +--------------------------------------- + +An earlier candidate for the hybrid construction was the Snap-and-Chat +protocol from the Ebb-and-Flow paper [#ebb-and-flow]_. The TFL initiative +identified several issues with Snap-and-Chat [#tfl-book]_, motivating the +development of CCC-TFLv2 (and by extension CCC-SL): + +* Snap-and-Chat's "sanitization" step complicates transaction finality + semantics in ways that interact poorly with Zcash's shielded transaction + model. + +* Snap-and-Chat does not implement bounded availability, which is a safety + property important for protecting users during finality stalls. + +* The security analysis of CCC-TFLv2 / CCC-SL is more rigorous and complete + than what is available for Snap-and-Chat. + +The Case for Bounded Availability +----------------------------------- + +A key design goal of CCC-SL is *bounded availability*: preventing the PoW +chain from growing unboundedly ahead of the finalized chain during a finality +stall. Without this property, a period of ``CFP-SL`` failure could allow +unbounded accumulation of unfinalized transactions. When ``CFP-SL`` recovered, +users would face uncertainty about which transactions would ultimately be +finalized and which would be reversed. + +Bounded availability addresses this by entering "Stalled Mode" when the +finality gap exceeds a threshold ``L``. In Stalled Mode, PoW block producers +are constrained to produce only "stalled blocks" — blocks that do not include +new user transactions spending into the unfinalized zone. This limits user +exposure during finalization failures. + + +Requirements +============ + +Shielded Labs Crosslink v1 MUST satisfy the following requirements: + +Finality Requirements +--------------------- + +* The protocol MUST provide Crosslink Finality for transactions included in + finalized blocks. + +* The expected time-to-finality SHOULD be below 30 minutes under normal + network conditions. + +* The protocol MUST maintain Local Finalization Linearity: from any single + node's perspective, the locally-finalized chain can only grow forward, never + roll back. + +Safety Requirements +-------------------- + +* The cost-of-attack for a 1-hour rollback of the PoW chain MUST NOT be + reduced compared to the current Zcash consensus protocol, given a reasonably + rigorous security argument. + +* The cost-of-attack to halt the chain MUST be larger than the 24-hour revenue + of PoW mining rewards, given a reasonably rigorous security argument. + +Backward Compatibility Requirements +------------------------------------- + +* All currently supported wallet operations (addresses, payment flow, ZEC + transfers, backup/restore, etc.) MUST continue to function without change + through the protocol transition, assuming wallets rely on the lightwalletd + protocol or a full-node API. + +* Mining pool operators relying on zcashd-compatible ``GetBlockTemplate`` + MUST NOT be required to make software changes, with the narrow exception of + software that hardcodes block reward amounts rather than deriving them from + ``GetBlockTemplate``. + +* The ZEC supply cap and issuance schedule MUST be preserved. + +* Block explorers that display transaction and block information MUST continue + to function with the same user experience through the transition. + +Bounded Availability Requirements +----------------------------------- + +* ``CCC-SL`` MUST implement bounded availability: the finality depth of any + non-stalled bc-block MUST NOT exceed ``L``, where ``L`` is a protocol + parameter. (Stalled blocks may exist at any finality depth; Bounded + Availability bounds the depth of *transaction-carrying* blocks only.) + +* ``L`` MUST be set significantly larger than the bc-confirmation-depth ``σ``, + with a minimum of ``L ≥ 2σ``. + +Staking Requirements +-------------------- + +* ZEC holders MUST be able to earn protocol rewards by operating as Finalizers + or delegating ZEC to Finalizers via ``RSM-SL-v1``. + +* Finalizers MUST NOT have discretionary control over delegated funds; they + MUST NOT be able to steal delegated ZEC. + +* The protocol MUST allow slashing of Finalizer stake for provable misbehavior. + + +Non-requirements +================ + +The following are explicitly out of scope for Shielded Labs Crosslink v1: + +* Minimizing time-to-finality as a primary goal over other considerations such + as protocol simplicity or impact on existing use cases. + +* In-protocol liquid staking derivatives. + +* Maximizing the Finalizer count ceiling. The design may have a relatively low + ceiling of hundreds to a few thousand Finalizers. + +* Reducing overall network energy usage (this cannot be achieved for a + hybrid PoW/PoS design without loss of security). + + +Specification +============= + +Protocol Component Overview +----------------------------- + +Shielded Labs Crosslink v1 is composed of five major protocol components that +interact with the existing Zcash PoW consensus and ledger rules: + +1. **CCC-SL** — the hybrid consensus construction at the core of Crosslink v1. +2. **CFP-SL** — the BFT PoS finalization protocol run by Finalizers. +3. **RSM-SL-v1** — the Roster State Module that manages the Active Roster + Mapping and staking rules. +4. **CNTP-SL** — the network transport layer for finality updates. +5. **Zcash PoW consensus** (existing, with minimal CCC-SL modifications). + +Component Diagram +----------------- + +The following diagram illustrates the components of Shielded Labs Crosslink v1 +and their interactions. Arrows indicate data flow or dependency:: + + ┌──────────────────────────────────────────────────────────┐ + │ Shielded Labs Crosslink v1 │ + │ │ + ┌──────────┐ │ ┌────────────────────────────────────────────────────┐ │ + │ Zcash │ │ │ CCC-SL (Crosslink Consensus Construction │ │ + │ PoW │◄─┼──│ from Shielded Labs) │ │ + │ (Π_bc) │──┼─►│ • context_bft field in bc-block headers │ │ + └──────────┘ │ │ • Finality gap / Stalled Mode enforcement │ │ + ▲ │ │ • Locally finalized chain (localfin) │ │ + │ │ │ • Locally bounded-available chain (localba) │ │ + │ │ └──────────────────────┬─────────────────────────────┘ │ + │ │ │ │ + │ │ ┌──────────────────────▼─────────────────────────────┐ │ + │ │ │ CFP-SL (Crosslink Finalization Protocol │ │ + │ │ │ from Shielded Labs) │ │ + └────────┼──│ • BFT PoS consensus over PoW chain snapshots │ │ + │ │ • headers_bc in bft-proposals and bft-blocks │ │ + │ │ • Final Agreement property │ │ + │ │ • Adaptation modifications for CCC-SL interface │ │ + │ └────────────┬──────────────────┬────────────────────┘ │ + │ │ │ │ + │ ┌────────────▼───────────┐ ┌──▼──────────────────────┐ │ + │ │ RSM-SL-v1 │ │ CNTP-SL │ │ + │ │ (Roster State Module) │ │ (Crosslink Network │ │ + │ │ │ │ Transport Protocol) │ │ + │ │ • Active Roster │ │ │ │ + │ │ Mapping │ │ • Finality update │ │ + │ │ • Roster Evolution │ │ dissemination │ │ + │ │ Rules │ │ • Transport encryption │ │ + │ │ • Staking rules: │ │ • Faster sync │ │ + │ │ - ZEC delegation │ │ • Firewall traversal │ │ + │ │ - Unbonding periods │ │ • DoS protection │ │ + │ │ - Slashing │ │ │ │ + │ │ - Quantization │ │ │ │ + │ └────────────────────────┘ └─────────────────────────┘ │ + │ │ + └───────────────────────────────────────────────────────────┘ + +Component Descriptions +----------------------- + +CCC-SL: Crosslink Consensus Construction from Shielded Labs + CCC-SL is the core hybrid consensus construction specifying how the Zcash + PoW subprotocol and ``CFP-SL`` interact. It is closely based on CCC-TFLv2 + and provides the following key mechanisms: + + * **Cross-referencing fields**: Each PoW block header includes a + ``context_bft`` field referencing a ``CFP-SL`` block; each ``CFP-SL`` + proposal includes a ``headers_bc`` field with ``σ`` PoW block headers. + These fields allow each chain to objectively verify properties of the + other. + + * **Locally finalized chain**: Each node maintains a locally finalized + bc-chain (``localfin``) that only ever advances forward, never rolling + back. + + * **Locally bounded-available chain**: Each node also maintains a confirmed + (but not necessarily finalized) bc-chain view (``localba``) at a chosen + confirmation depth. + + * **Stalled Mode**: When the finality gap (number of unfinalized PoW blocks) + exceeds ``L``, CCC-SL enforces Stalled Mode, constraining PoW block + producers to produce only stalled blocks. + + CCC-SL is formally specified in ZIP [#zip-ccc-sl]_. + +CFP-SL: Crosslink Finalization Protocol from Shielded Labs + CFP-SL is the BFT Proof-of-Stake consensus protocol run by Finalizers to + provide Crosslink Finality. It operates over snapshots of the Zcash PoW chain: + each CFP-SL proposal commits to a sequence of PoW block headers, and + finalized CFP-SL blocks determine which PoW blocks are considered final. + + CFP-SL is a modified version of an off-the-shelf BFT protocol, with + adaptation modifications to: + + * Include ``headers_bc`` in proposals and blocks (required by CCC-SL). + * Consult the Active Roster Mapping from ``RSM-SL-v1`` for voter weights. + * Verify PoW header validity before voting on proposals. + + The specific off-the-shelf BFT algorithm used by CFP-SL will be specified in + a companion ZIP. CFP-SL must satisfy the **Final Agreement** property: in any + execution where safety assumptions hold, all honest nodes' views of finalized + CFP-SL blocks are consistent. + +RSM-SL-v1: Roster State Module (Shielded Labs v1) + RSM-SL-v1 is the specific instantiation of the abstract Roster State Module + interface required by CFP-SL. It maintains the Active Roster Mapping that + determines which Finalizer identities are authorized to vote in CFP-SL and + with what weight. + + RSM-SL-v1 defines all staking rules that users interact with directly, + including: + + * **ZEC delegation**: Staking ZEC to a Finalizer vote-verifier identity. + * **Unbonding periods**: The mandatory waiting period before staked ZEC can + be withdrawn after unbonding. + * **Amount quantization**: Minimum and increment sizes for staking amounts. + * **Slashing**: Conditions and amounts for penalizing provably misbehaving + Finalizers, enforced as Roster Evolution Rules. + * **Roster Evolution Rules**: Ledger state evolution rules that govern how + the Active Roster Mapping changes over time as part of Zcash's broader + ledger state consensus. + + RSM-SL-v1 is specified in ZIP [#zip-rsm-sl-v1]_. + +CNTP-SL: Crosslink Network Transport Protocol from Shielded Labs + CNTP-SL is the network transport layer providing the communication substrate + for Shielded Labs Crosslink v1. Although not strictly logically required for + a correct Crosslink deployment (any sufficiently reliable broadcast network + would suffice), CNTP-SL provides important practical properties: + + * **Finality update dissemination**: Efficient propagation of CFP-SL blocks + and finality updates to all network participants, including light clients. + * **DoS protection**: Network-layer defenses against denial-of-service + attacks targeting the finalization protocol. + * **Transport-layer encryption**: Authenticated, encrypted communication + between Crosslink v1 nodes. + * **Faster sync protocols**: Improved block and ledger synchronization + compared to the status quo Zcash p2p protocol. + * **Firewall traversal**: Support for nodes behind NAT/firewalls. + + CNTP-SL will be specified in a companion ZIP. + +Interaction Between Components +-------------------------------- + +The components of Shielded Labs Crosslink v1 interact as follows: + +1. **Zcash PoW ↔ CCC-SL**: CCC-SL augments PoW block validity rules with + the ``context_bft`` cross-reference requirement and the Stalled Mode + policy. Honest PoW block producers consult their CFP-SL node to determine + the current BFT chain tip for ``context_bft``. + +2. **CCC-SL ↔ CFP-SL**: CCC-SL defines the interface requirements CFP-SL must + satisfy (Final Agreement, the ``headers_bc`` format, and the + ``bftLastFinal`` function). CFP-SL produces finalized blocks that CCC-SL + uses to compute ``localfin``. CFP-SL proposals include PoW block headers + that CCC-SL verifies. + +3. **CFP-SL ↔ RSM-SL-v1**: CFP-SL queries RSM-SL-v1 for the current Active + Roster Mapping to determine voter weights and authorized identities for each + round of BFT consensus. RSM-SL-v1's Roster Evolution Rules are enforced as + part of Zcash ledger state transitions, so the Active Roster Mapping changes + as the PoW ledger evolves. + +4. **CFP-SL ↔ CNTP-SL**: CNTP-SL provides the network transport over which + CFP-SL messages (proposals, votes, finalized blocks) are communicated + between Finalizers and propagated to all network participants. + +5. **Zcash PoW ↔ RSM-SL-v1**: The Roster Evolution Rules in RSM-SL-v1 are + expressed as standard Zcash ledger state evolution rules, enforced by the + PoW consensus mechanism. Staking and unstaking transactions appear on the + PoW chain and update the Active Roster Mapping. + +Relationship to the Existing Zcash Protocol +--------------------------------------------- + +The Zcash PoW subprotocol within Shielded Labs Crosslink v1 is closely related +to the existing Zcash NU5/NU6 consensus protocol but is not identical. The +CCC-SL construction requires the following changes (specified in detail in ZIP +[#zip-ccc-sl]_): + +* Each PoW block header MUST include a ``context_bft`` field referencing a + CFP-SL block, committing the PoW block producer to their view of the + finalization chain. + +* PoW block validity rules are extended with contextual checks enforcing the + finality gap constraint and Stalled Mode policy. + +The RSM-SL-v1 staking rules add new transaction types and ledger state to the +Zcash protocol, specified in ZIP [#zip-rsm-sl-v1]_. + +Network Upgrade Mechanism +-------------------------- + +Shielded Labs Crosslink v1 would be deployed via the existing Zcash network +upgrade mechanism [#zip-0200]_ as a consensus rule change. The precise +activation height(s) will be determined in subsequent process ZIPs once all +component specifications are finalized. + +Reward Distribution +-------------------- + +Activating Shielded Labs Crosslink v1 requires adjusting the Zcash block +reward to provide rewards to Finalizers (via RSM-SL-v1) while maintaining the +existing ZEC supply schedule. The specific reward allocation between PoW miners +and Finalizers is not specified in this ZIP; it will be addressed in a separate +funding ZIP. + +The ZEC supply cap of 21 million ZEC and the overall issuance schedule MUST +be preserved. + + +Security Considerations +======================= + +Hybrid Protocol Security +------------------------- + +The security of Shielded Labs Crosslink v1 depends on the security of both the +Zcash PoW subprotocol and ``CFP-SL``, as well as the correctness of ``CCC-SL``. +The CCC-SL specification (ZIP [#zip-ccc-sl]_) includes a security analysis +establishing the key properties: Crosslink Finality, Prefix Consistency, and +Bounded Availability. + +CFP-SL Failure +--------------- + +If ``CFP-SL`` experiences a safety failure (e.g., due to more than one-third +of staked weight being controlled by adversarial Finalizers), the CCC-SL +construction's finalization safety hazard detection will record the event. The +bounded availability property limits the damage from CFP-SL liveness failures +by entering Stalled Mode when the finality gap grows too large. + +PoW Protocol Failure +--------------------- + +If the Zcash PoW subprotocol experiences a deep reorg, but CFP-SL has not yet +finalized the affected blocks, CCC-SL will simply not finalize those blocks. If +the reorg affects already-finalized blocks, the finalization safety hazard +detection will record the event — but such an event can only occur if safety +assumptions about CFP-SL (e.g., that fewer than one-third of staked weight is +adversarial) are also violated. + +Staked ZEC Risk +--------------- + +ZEC staked to Finalizers via RSM-SL-v1 may be subject to slashing penalties +for provable misbehavior. The protocol design MUST ensure that slashing +penalties cannot be imposed on honest Finalizers, and that the slashing +conditions and amounts are deterministic and auditable. + +Privacy Considerations +----------------------- + +Shielded Labs Crosslink v1 introduces new on-chain data (CFP-SL blocks, +Finalizer votes, cross-references between chains, and staking transactions). +Care must be taken to ensure that this new data does not leak information about +shielded transactions. The privacy implications of Finalizer identity and +staking is analyzed in ZIP [#zip-rsm-sl-v1]_. + + +Reference Implementation +======================== + +A complete prototype implementation of Shielded Labs Crosslink v1 is being +developed based on Zebra in the ``zebra-crosslink`` repository [#zebra-crosslink]_ +and integrated in the ``crosslink_monolith`` repository [#crosslink-monolith]_. +These implementations are experimental and should not be used in production. + + +Appendix: Divergences Between Reference Sources +================================================ + +The Shielded Labs Crosslink v1 ZIPs draw on three main reference sources: + +1. **The TFL book** [#tfl-book]_ — the original ECC design document specifying + ``CCC-TFLv2``. +2. **The zebra-crosslink design book** [#zebra-crosslink-cl2]_ — Shielded Labs' + working design documentation, which is based on the TFL book but records + intentional divergences. +3. **These ZIPs** (this document and the CCC-SL construction ZIP) — the formal + protocol specifications for Shielded Labs Crosslink v1. + +The zebra-crosslink design book ``book/src`` is treated as the authoritative +source for terminology and design decisions when sources diverge. The following +known divergences exist between these sources: + +Finality Terminology +--------------------- + +* **TFL book** uses "Assured Finality" as the name of the formal safety + property of the hybrid construction. +* **zebra-crosslink** ``security-properties.md`` [#zebra-crosslink-security]_ + refers to the same concept as "Irreversible Finality". +* **zebra-crosslink** ``terminology.md`` [#zebra-crosslink-terminology]_ + defines "Crosslink Finality" as the user-facing name for this property, with + five defining characteristics (accountable, irreversible, objectively + verifiable, globally consistent, asymmetric cost-of-attack defense). +* **These ZIPs** adopt "Crosslink Finality" as the primary term, following + ``terminology.md`` as the authoritative source. + +Stalled Mode +------------ + +* **CCC-TFLv2** (TFL book) and **CCC-SL** (these ZIPs) include Stalled Mode: + when the finality depth exceeds ``L``, bc-block producers MUST produce only + stalled blocks (blocks that do not include new unfinalized-output-spending + transactions). +* **zebra-crosslink** explicitly omits Stalled Mode from its current design. + The ``cl2-construction.md`` file in the zebra-crosslink design book contains + a prominent warning: "The ``zebra-crosslink`` design in this book diverges + from this text by *not* including 'Stalled Mode' rules." +* **These ZIPs** retain Stalled Mode from CCC-TFLv2, as it is a key component + of the Bounded Availability property. This divergence from the current + zebra-crosslink implementation is intentional and will need to be resolved + before deployment. + +``finality_depth`` Naming +-------------------------- + +* **TFL book** defines ``finality_depth(H)`` as the height of ``H`` minus the + height of ``snapshot(LF(H))``, and uses ``finality_depth(H) > L`` as the + condition for Stalled Mode. +* **These ZIPs** use the equivalent expression + ``tip_height(H) - fin_height(H) > L``, where ``fin_height(H)`` is the + height of ``candidate(H)``. The quantity ``candidate(H)`` is closely + related to ``snapshot(LF(H))`` via the ``lastCommonAncestor`` function. + The two formulations are equivalent in normal operation. + +Construction Name +----------------- + +* **TFL book** and **zebra-crosslink** refer to the hybrid construction as + "Crosslink 2" (or "CL2"). +* **These ZIPs** use "CCC-SL" (Crosslink Consensus Construction from Shielded + Labs) to distinguish the Shielded Labs adaptation from the abstract + CCC-TFLv2 construction. + + +References +========== + +.. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" <https://www.rfc-editor.org/info/bcp14>`_ +.. [#protocol] `Zcash Protocol Specification, Version 2022.3.8 or later <protocol/protocol.pdf>`_ +.. [#protocol-networks] `Zcash Protocol Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet <protocol/protocol.pdf#networks>`_ +.. [#zip-0200] `ZIP 200: Network Upgrade Mechanism <zip-0200.rst>`_ +.. [#zip-ccc-sl] `ZIP [Unassigned]: CCC-SL: Crosslink Consensus Construction from Shielded Labs <draft-shieldedlabs-crosslink-construction.rst>`_ +.. [#zip-rsm-sl-v1] `ZIP [Unassigned]: RSM-SL-v1: Crosslink Ledger State and Ledger Mutations <draft-shieldedlabs-crosslink-ledger-state.rst>`_ +.. [#tfl-book] `Zcash Trailing Finality Layer Design Book <https://electric-coin-company.github.io/tfl-book/>`_ +.. [#ebb-and-flow] `Ebb-and-Flow Protocols: A Resolution of the Availability-Finality Dilemma. David Neu, Joachim Neu, Ertem Nusret Tas, David Tse. <https://eprint.iacr.org/2020/1091.pdf>`_ +.. [#zebra-crosslink] `ShieldedLabs zebra-crosslink repository <https://github.com/ShieldedLabs/zebra-crosslink>`_ +.. [#crosslink-monolith] `ShieldedLabs crosslink_monolith repository <https://github.com/ShieldedLabs/crosslink_monolith>`_ +.. [#zebra-crosslink-terminology] `Shielded Labs zebra-crosslink design book: Terminology <https://github.com/ShieldedLabs/zebra-crosslink/blob/main/book/src/design/terminology.md>`_ +.. [#zebra-crosslink-cl2] `Shielded Labs zebra-crosslink design book: Crosslink 2 Construction <https://github.com/ShieldedLabs/zebra-crosslink/blob/main/book/src/design/cl2-construction.md>`_ +.. [#zebra-crosslink-security] `Shielded Labs zebra-crosslink design book: Security Properties <https://github.com/ShieldedLabs/zebra-crosslink/blob/main/book/src/design/security-properties.md>`_
zips/zip-CROSSLINK.md +86 −0
@@ -0,0 +1,86 @@ + ZIP: Unassigned-CROSSLINK-CAPSTONE + Title: The Crosslink Consensus Protocol + Owners: Nate Wilcox <nate+zips@shieldedlabs.net> + Andrew Reece <andrew@shieldedlabs.net> + Credits: Nate Wilcox + Daira Emma Hopwood + Jack Str4d Grigg + Andrew Reece + Status: Draft + Category: Consensus & Network & RPC & Wallet + Created: 2026-03-17 + License: MIT + Pull-Request: <https://github.com/zcash/zips/pull/???> + + +# Terminology + +{Edit this to reflect the key words that are actually used.} +The key words "MUST", "REQUIRED", "MUST NOT", "SHOULD", and "MAY" in this +document are to be interpreted as described in BCP 14 [^BCP14] when, and +only when, they appear in all capitals. + +The character § is used when referring to sections of the Zcash Protocol Specification. [^protocol] + +The terms "Mainnet" and "Testnet" are to be interpreted as described in § 3.12 ‘Mainnet and Testnet’. [^protocol-networks] + +The term "full validator" in this document is to be interpreted as defined in § 3.3 ‘The Block Chain’. [^protocol-blockchain]. + +The terms below are to be interpreted as follows: + +{Term to be defined} + +: {Definition.} + +{Another term} + +: {Definition.} + + +# Abstract + + +# Motivation + + +# Privacy Implications + + +# Requirements + + +# Non-requirements + + +# Specification + +<details> +<summary> +{details heading} +</summary> + +{ details body } +</details> +<br/> + +# Rationale + + +# Deployment + + +# Reference implementation + + +# Open issues + + +# References + +[^BCP14]: [Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"](https://www.rfc-editor.org/info/bcp14) + +[^protocol]: [Zcash Protocol Specification, Version 2025.6.3 [NU6.1] or later](protocol/protocol.pdf) + +[^protocol-blockchain]: [Zcash Protocol Specification, Version 2025.6.3 [NU6.1]. Section 3.3: The Block Chain](protocol/protocol.pdf#blockchain) + +[^protocol]: [Zcash Protocol Specification, Version 2025.6.3 [NU6.1]. Section 3.12: Mainnet and Testnet](protocol/protocol.pdf#networks)