Crosslink Design

As we proceed we intend to produce design documentation that is abstracted from implementation, but more comprehensive than the TFL Book design because it encompasses all of a specific concrete integrated hybrid protocol with full PoW, BFT, and PoS scope.

• The keystone document for this is an in-progress ZIP Draft which will enter the formal ZIP process as it matures.
• Additionally, we are tracking Architecture Design Rationales as we prototype the complete design. More detail is provided in the Implementation Approach section below.

Design Adherence, Safety, & Analysis

Note the scope of these decisions may deviate from the more rigorous yet abstract TFL Book §3.3 The Crosslink Construction!

This means the prototype may violate some of the security assumptions or other goals of that design, so we make no assurances the prototype is not safe. We have three possible types of rationale for these deviations:

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

Architecture Design Rationales

We use an approach of documenting many design decisions via "Architecture Design Rationale" documents, inspired by the upstream development process. These are especially important for our Prototype-then-Productionize approach, since they record key decisions we should review for production readiness.

Currently ADRs are very rough and tracked on this zebra-crosslink ADR Google Sheet.

Moving forward we will begin to incorporate them into this codebase.