Merge pull request #162 from daira/crosslink2

Crosslink 2

Author: daira

.gitignore

@@ -1,3 +1,6 @@
 build/
 src/**/*.generated.svg
 result
+
+*.swp
+*.save

README.md

@@ -6,13 +6,13 @@ This repository is the source text and rendering configuration for the book. To
 
 The `mdbook` tool renders the contents into a pretty format from `markdown` based source code
 
-## Github CI
+## GitHub CI
 
-There are two github CI workflows:
+There are two GitHub CI workflows:
 
-- `merge-acceptance.yaml`: triggers on `pull_request` to check that `mdbook build` succeeds and there aren't dangling `md` files (e.g. you remove an entry in `SUMMARY.md` but forget to rm the file.)
+- `merge-acceptance.yaml`: triggers on `pull_request` to check that `mdbook build` succeeds and there aren’t dangling `md` files (e.g. you remove an entry in `SUMMARY.md` but forget to rm the file.)
 - `render-site.yaml`: triggers on `push` to `main` to render the site to https://electric-coin-company.github.io/tfl-book/
-  - **Warning:** this workflow relies on full read/write access to the `gh-pages` branch. Don't mess with that branch unless you're very confident in the impacts.
+  - **Warning:** this workflow relies on full read/write access to the `gh-pages` branch. Don’t mess with that branch unless you're very confident in the impacts.
 
 ## `git-hooks`
 
@@ -46,38 +46,38 @@ Note: Nix users can rely on `flake.nix` which packages the final rendered HTML i
 
 ## Release Process
 
-Releases are defined as distinct revisions that embody a consistent set of changes from the prior releases, identified by a version with `XXX.YYY.ZZZ` format. Releases serve a few purposes. They:
+Releases are defined as distinct revisions that embody a consistent set of changes from the prior releases, identified by a version with `XXX.YYY.ZZZ` format. Releases serve a few purposes. They
 
-- ensure that readers can better notice changes or updates between readings or in discussions with others,
-- signify that the authors have converged after a period of editing onto a coherent integrated result,
-- signify an approximate maturity of the design, based on the version number, and
+- ensure that readers can better notice changes or updates between readings or in discussions with others;
+- signify that the authors have converged after a period of editing onto a coherent integrated result;
+- signify approximate maturity of the design, based on the version number; and
 - serve as a natural milestone for announcements on design updates.
 
 ### Versioning Schema
 
-The versioning scheme isn't precise and roughly follows this rubrik:
+The versioning scheme isn’t precise and roughly follows this rubrik:
 
 When a version `X.Y.Z` increments, the scope of change since the prior release is implied by the new version:
 
 - `<X+1>.0.0` - This release represents a complete, well analyzed design which the authors believe could be a suitable candidate for Zcash (or other crypto networks) to productionize by developing conforming implementations that activate in production.
 - `X.<Y+1>.0` - This release introduces or changes substantial design decisions or analyses, or it changes the presentation (such as the order or content of chapters) significantly. A reader of only the prior release may be missing essential details in understanding this new release.
-- `X.Y.<Z+1>` - This release improves the wording, layout, rendering, or other content in a manner that doesn't rise to the threshold of the previous case.
+- `X.Y.<Z+1>` - This release improves the wording, layout, rendering, or other content in a manner that doesn’t rise to the threshold of the previous case.
 
 ### Release Process
 
 To create a new release:
 
 1. Decide that the `main` branch is in a coherent state without likely sources of confusion or self-inconsistency.
-2. Decide the new release's version as in [Versioning Schema](#versioning-schema) above.
+2. Decide the new release’s version as in [Versioning Schema](#versioning-schema) above.
 3. Create a release branch named `release-<NEW VERSION>`.
 4. Update the release branch with these changes:
   - `book.toml`: Modify the `title` to end with `vX.Y.Z`. This ensures the version is visible to readers on all pages.
   - `src/version-history.md`: Introduce a new heading `## X.Y.Z - <RELEASE TITLE>` above all prior entries (i.e. reverse chronologically).
-    - The `RELEASE TITLE` should be a short-hand title capturing the primary change of the release.
+    - The `RELEASE TITLE` should be a shorthand title capturing the primary change of the release.
     - The release body should always begin with a link titled `Issue Tracking` that navigates to the GitHub milestone page of completed issues in this release.
     - The rest of the release body should be a one- to three-sentence summary of changes. Readers who need more detail can follow issue tracking.
-  - `src/introduction.md`: The first paragraph says `This is <VERSION LINK> of the book.` Update that link to point to the new release's entry in `src/version-history.md`.
+  - `src/introduction.md`: The first paragraph says `This is <VERSION LINK> of the book.` Update that link to point to the new release’s entry in `src/version-history.md`.
 5. Submit those changes for GitHub pull-request review, resolve any blocking concerns, then merge to the `main` branch. Note: This step will render the release.
 6. Create a git tag on the git commit that merges into `main`: `git tag vX.Y.Z && git push --tags`
 
-Note: We don't use GitHub "releases" since there's no release artifact other than the already published rendering.
+Note: We don’t use GitHub "releases" since there’s no release artifact other than the already published rendering.

book.toml

@@ -1,7 +1,7 @@
 [book]
 authors = [
     "Nate Wilcox",
-    "Daira Emma Hopwood",
+    "Daira-Emma Hopwood",
 ]
 language = "en"
 multilingual = false
@@ -21,6 +21,8 @@ macros = "macros.txt"
 renderer = ["html"]
 # This is needed in order for \href and \url links to work.
 trust = true
+# Left-aligned displaymath
+fleqn = true
 
 [output.html]
 default-theme = "light"

git-hooks/pre-commit

@@ -2,26 +2,14 @@
 set -efuo pipefail
 
 function main
-{
-	log-run reject-unstaged-changes
-	log-run require-render-success
-	log-run ./util/find-orphaned-files.sh
-}
-
-# Used to log which check is being executed, then execute it:
-function log-run
-{
-	echo "$0: $1"
-	eval "$@"
-}
-
-function reject-unstaged-changes
 {
 	if [ "$(unstaged-changes | wc -l)" -gt 0 ]
 	then
-		echo 'Refusing to commit unstaged changes:'
+		echo 'Warning: you have unstaged changes:'
 		unstaged-changes
-		exit 1
+	else
+		require-render-success
+		./util/find-orphaned-files.sh
 	fi
 }
 

macros.txt

@@ -1 +1,82 @@
-\yaykatex:{\mathsf{yay}\;\href{https://katex.org}{\KaTeX}}
+\TODO:\htmlStyle{background-color:yellow;color:black;}{\textsf{TODO:}}
+\typecolon:\mathrel{\raisebox{.3ex}{\tiny ⦂}}
+\intersection:\cap
+\union:\cup
+\trunc:\lceil
+\agrees:\preceq\hspace{-0.5em}\succeq
+\conflicts:\hspace{0.5em}\big/\hspace{-1.06em}\agrees
+\setof:\{\;#1\;\}
+\Origin:\mathcal{O}
+\dot:\mathsf{.}
+\null:\varnothing
+\tab:\hspace{2em}
+\gets:\leftarrow
+
+\let:\text{let }
+\if:\text{if }
+\otherwise:\text{otherwise.}
+\then:\text{:}
+\else:\text{else:}
+\mut:\text{mut }
+\Time:\mathsf{Time}
+\Node:\mathsf{Node}
+\starchain:\star\textsf{-chain}
+\starblock:\star\textsf{-block}
+\LOG:\mathsf{LOG}
+\candidate:\mathsf{candidate}
+\snapshot:\mathsf{snapshot}
+\LF:\mathsf{LF}
+\snapshotlf:\snapshot(\LF(#1)\kern-0.1em)
+\checkpoint:\mathsf{checkpoint}
+\boolean:\mathsf{boolean}
+\true:\mathsf{true}
+\false:\mathsf{false}
+\len:\mathsf{len}
+\tailhead:\mathsf{tailhead}
+\proof:\mathsf{proof}
+\height:\mathsf{height}
+\score:\mathsf{score}
+\tip:\mathsf{tip}
+\besttip:\textsf{best-tip}
+\lastcommonancestor:\textsf{last-common-ancestor}
+\finalitydepth:\textsf{finality-depth}
+\bftlastfinal:\textsf{bft-last-final}
+\origbftlastfinal:\textsf{origbft-last-final}
+\bftblock:\textsf{bft-block}
+\bcblock:\textsf{bc-block}
+\bcchain:\textsf{bc-chain}
+\bcvalidchain:\textsf{bc-valid-chain}
+\bctransaction:\textsf{bc-transaction}
+\isstalledblock:\textsf{is-stalled-block}
+\iscoinbaseonlyblock:\textsf{is-coinbase-only-block}
+\updatefin:\textsf{update-fin}
+\headersbc:\mathsf{headers\_bc}
+\blockbc:\mathsf{block\_bc}
+\bcisforked:\mathsf{bc\_is\_forked}
+\contextbft:\mathsf{context\_bft}
+\consistent:\mathsf{consistent}
+\view:\mathsf{view}
+\lsf:\mathsf{lsf}
+\Score:\mathsf{Score}
+\Ch:\mathsf{Ch}
+\ch:\mathsf{ch}
+\localfin:\mathsf{fin}\kern0.04em
+\localba:\mathsf{ba}
+\candidate:\mathsf{candidate}
+\xlog:\mathsf{log}
+\GST:\mathsf{GST}
+\GAT:\mathsf{GAT}
+
+\star:\mathrm{*}
+\starbft:\mathrm{*bft}
+\starbc:\mathrm{*bc}
+\origbft:\mathrm{origbft}
+\origbc:\mathrm{origbc}
+\bft:\mathrm{bft}
+\bc:\mathrm{bc}
+\lc:\mathrm{lc}
+
+\confirm:\mathrm{lc}
+\fin:\mathrm{fin}
+\ba:\mathrm{ba}
+\da:\mathrm{da}

src/SUMMARY.md

@@ -8,14 +8,13 @@
   - [Get Involved](./introduction/get-involved.md)
 - [Terminology](./terminology.md)
 - [Design](./design.md)
-  - [Overview](./design/overview.md)
-    - [Design at a Glance](./design/overview/design-at-a-glance.md)
+  - [Design at a Glance](./design/design-at-a-glance.md)
   - [Design Goals](./design/goals.md)
   - [Crosslink](./design/crosslink.md)
-    - [The Arguments for Bounded Dynamic Availability and Finality Overrides](./design/crosslink/the-arguments-for-bounded-dynamic-availability-and-finality-overrides.md)
-    - [Notes On Snap And Chat](./design/crosslink/notes-on-snap-and-chat.md)
-    - [The Crosslink Construction](./design/crosslink/construction.md)
-    - [Security Analysis of Crosslink](./design/crosslink/security-analysis.md)
+    - [The Arguments for Bounded Availability and Finality Overrides](./design/crosslink/the-arguments-for-bounded-availability-and-finality-overrides.md)
+    - [Notes On Snap‑and‑Chat](./design/crosslink/notes-on-snap-and-chat.md)
+    - [The Crosslink 2 Construction](./design/crosslink/construction.md)
+    - [Security Analysis of Crosslink 2](./design/crosslink/security-analysis.md)
     - [Questions About Crosslink](./design/crosslink/questions.md)
     - [Potential Changes to Crosslink](./design/crosslink/potential-changes.md)
   - [Model Code Architecture]()

src/design.md

@@ -1 +1,14 @@
-# Design
+# Design Overview
+
+This design augments the existing Zcash Proof‑of‑Work (PoW) network with a new consensus layer which provides *trailing finality*, called the *Trailing Finality Layer (TFL)*.
+
+This layer enables blocks produced via PoW to become *final* which ensures they may never be rolled back. This enables safer and simpler wallets and other infrastructure, and aids trust-minimized cross-chain bridges.
+
+This consensus layer uses a finalizing *Proof-of-Stake (PoS)* consensus protocol, and enables ZEC holders to earn protocol rewards for contributing to the security of the Zcash network. By integrating a PoS layer with the current PoW Zcash protocol, this design specifies a *hybrid consensus protocol*.
+
+The integration of the current PoW consensus with the TFL produces a new top-level consensus protocol referred to as *PoW+TFL*.
+
+In the following subchapters we introduce the [Design at a Glance](./design/design-at-a-glance.md), then provide an overview of the major components of the design.
+
+Following this overview chapter, we proceed into a detailed [Protocol Specification (TODO)]().
+

src/design/crosslink.md

@@ -1,12 +1,12 @@
 # Crosslink
 
-Crosslink is the proposed [hybrid construction](../terminology.md#definition-hybrid-construction) for the Trailing Finality Layer.
+Crosslink is the proposed [hybrid construction](../terminology.md#definition-hybrid-construction) for the Trailing Finality Layer. The current version is Crosslink 2.
 
 ## Contents
 
-- [The Arguments for Bounded Dynamic Availability and Finality Overrides](./crosslink/the-arguments-for-bounded-dynamic-availability-and-finality-overrides.md)
-- [Notes On Snap And Chat](./crosslink/notes-on-snap-and-chat.md)
-- [The Crosslink Construction](./crosslink/construction.md)
-- [Security Analysis of Crosslink](./crosslink/security-analysis.md)
+- [The Arguments for Bounded Availability and Finality Overrides](./crosslink/the-arguments-for-bounded-availability-and-finality-overrides.md)
+- [Notes On Snap‑and‑Chat](./crosslink/notes-on-snap-and-chat.md)
+- [The Crosslink 2 Construction](./crosslink/construction.md)
+- [Security Analysis of Crosslink 2](./crosslink/security-analysis.md)
 - [Questions About Crosslink](./crosslink/questions.md)
 - [Potential Changes to Crosslink](./crosslink/potential-changes.md)