docs: add crosslink chain semantics reference for byte order, staking cycle, fat pointer, and bond privacy

[Zk-nd3r]

Summary

• Add CHAIN_SEMANTICS.md at the repo root because the monorepo root does not currently have a top-level docs/ directory.
• Capture four questions that came up repeatedly in the workshop channel today: finalizer pub_key byte order, the 150/70 staking cycle, fat pointer quorum semantics, and bond privacy.
• Keep each answer pinned to code, or to explicit channel consensus where the rationale was discussed verbally rather than encoded directly.

Why these sections exist

• Finalizer pub_key byte order: human-facing finalizer formatting reverses bytes, while get_tfl_roster_zats returns raw-order hex from RosterMember.pub_key.
  Sources: librustzcash/zcash_primitives/src/bft.rs:335-356, tenderlink/src/lib.rs:594-597, tenderlink/src/lib.rs:825-839, librustzcash/zcash_primitives/src/transaction/mod.rs:1415-1438, zebra-crosslink/wallet/src/lib.rs:3431-3487, zebra-gui/src/ui.rs:2847-2850.
• Staking cycle: consensus fixes the cycle at 150 PoW blocks with a 70-block window, and the shipped GUI keys staking-day UX off the finalized PoW tip.
  Sources: zebra-crosslink/zebra-consensus/src/transaction.rs:863-870, zebra-crosslink/zebra-consensus/src/transaction.rs:936-967, zebra-crosslink/zebra-consensus/src/error.rs:239-247, zebra-crosslink/zebra-crosslink/src/viz2.rs:155-160, zebra-gui/src/lib.rs:66-68, zebra-gui/src/ui.rs:1142.
• Fat pointer signer semantics: the signer list is built from matching non-NIL precommit signatures for the decided proposal and reflects a 2f+1 quorum threshold, not the full participant set.
  Sources: zebra-crosslink/zebra-chain/src/block/header.rs:110-111, zebra-crosslink/zebra-rpc/src/methods.rs:1958-1972, librustzcash/zcash_primitives/src/bft.rs:423-425, librustzcash/zcash_primitives/src/bft.rs:493-519, tenderlink/src/lib.rs:132-154, tenderlink/src/lib.rs:576, tenderlink/src/lib.rs:844-856, tenderlink/src/lib.rs:985-991, tenderlink/src/lib.rs:1142-1148.
• Bond privacy: the current code path is per-bond, keyed by unique_pubkey, and the privacy rationale was confirmed in the channel today as a tooling issue rather than a hidden protocol alternative.
  Sources: librustzcash/zcash_primitives/src/transaction/mod.rs:1445-1463, zebra-crosslink/wallet/src/lib.rs:935-936, zebra-crosslink/wallet/src/lib.rs:1951-1969, zebra-crosslink/wallet/src/lib.rs:4288-4300, zebra-gui/src/ui.rs:1144-1149, plus channel consensus from today for the privacy tradeoff note.

Test plan

• Not run. cargo check is not required for this docs-only change.

[Zk-nd3r]

Rebased onto s1_dev and re-verified every claim against current code. Two of them had gone wrong since April and are fixed here:

• Staking day: the GUI indicator keys off the unfinalized tip, not the finalized one. e5dddf6 swapped bc_finalized_tip_height for bc_tip_height in zebra-gui/src/ui.rs:1575. The doc now says so, and notes that consensus checks the height of the block the transaction lands in, so the two can disagree at a window boundary or across a reorg.
• Fat pointer: get_vote_template leaves the finalizer pubkey zeroed. inflate is what fills it in per signature (librustzcash/zcash_primitives/src/bft.rs:729-745). The original text attributed both to get_vote_template.

Also added: STAKING_PERIOD and STAKING_DAY_WINDOW now live in zcash_primitives rather than zebra-consensus, RetargetDelegationBond is exempt from the window, there is a hardcoded height exception list at zebra-crosslink/zebra-consensus/src/transaction.rs:962-966, and the 2f+1 rule degenerates to unanimity when f == 0.

Citations are now path plus symbol name so they stay usable as line numbers drift. Still no equivalent doc anywhere in the tree.