spec: fix broken links

docs/protocol/src/addresses_keys.md

@@ -4,7 +4,7 @@ The key hierarchy is a modification of the design in Zcash [Sapling].  The main
 differences are that it is designed for use with BLS12-377 rather than
 BLS12-381, that it uses Poseidon as a hash and PRF, `decaf377` as the embedded
 group, and that it includes support for [fuzzy message
-detection](../crypto/fmd.md).
+detection](./crypto/fmd.md).
 
 All key material within a particular spend authority - an *account* - is ultimately derived from
 a single root secret.  The internal key components and their derivations are
@@ -15,7 +15,7 @@ described in the following sections:
 * [Viewing Keys](./addresses_keys/viewing_keys.md) describes derivation of the full, incoming, and outgoing viewing keys;
 * [Addresses and Detection Keys](./addresses_keys/addresses.md) describes derivation of multiple, publicly unlinkable addresses for a single account, each with their own detection key.
 
-The diagram in the [Overview](../concepts/addresses_keys.md) section describes
+The diagram in the [Overview](./concepts/addresses_keys.md) section describes
 the key hierarchy from an external, functional point of view.  Here, we zoom in
 to the internal key components, whose relations are depicted in the following
 diagram.  Each internal key component is represented with a box; arrows depict

docs/protocol/src/addresses_keys/addresses.md

@@ -21,7 +21,7 @@ Each diversifier $d$ is used to generate a *diversified basepoint* $B_d$ as
 $$B_d = H_{\mathbb G}^{\mathsf d}(d),$$
 where 
 $$H_{\mathbb G}^{\mathsf d} : \{0, 1\}^{128} \rightarrow \mathbb G$$
-performs [hash-to-group] for `decaf377` as follows: first, apply BLAKE2b-512
+performs [hash-to-group](../crypto/decaf377/group_hash.md) for `decaf377` as follows: first, apply BLAKE2b-512
 with personalization `b"Penumbra_Divrsfy"` to the input, then, interpret the
 64-byte output as an integer in little-endian byte order and reduce it modulo
 $q$, and finally, use the resulting $\mathbb F_q$ element as input to the
@@ -30,7 +30,7 @@ $q$, and finally, use the resulting $\mathbb F_q$ element as input to the
 ## Detection Keys
 
 Each address has an associated *detection key*, allowing the creator of the
-address to delegate a [probabilistic detection capability][fmd] to a third-party
+address to delegate a [probabilistic detection capability](../crypto/fmd.md) to a third-party
 scanning service.
 
 The detection key consists of one component,

docs/protocol/src/addresses_keys/transaction_crypto.md

@@ -44,7 +44,7 @@ In the rest of this section, we describe how each key is derived.
 
 A shared secret `shared_secret` is derived between sender and recipient by performing Diffie-Hellman
 key exchange between:
-* an ephemeral secret ($esk \in \mathbb F_r$) and the diversified transmission key $pk_d$ of the recipient (described in more detail in the [Addresses](../protocol/addresses_keys/addresses.md) section),
+* an ephemeral secret ($esk \in \mathbb F_r$) and the diversified transmission key $pk_d$ of the recipient (described in more detail in the [Addresses](./addresses.md) section),
 * the ephemeral public key $epk$ (where $epk = [esk] B_d$), provided as a public field in the action, and the recipient's incoming viewing key $ivk$.
 
 This allows both sender and recipient to generate the shared secret based on the keys they possess.

docs/protocol/src/assets.md

@@ -58,7 +58,7 @@ rate-1 Poseidon hashing with domain separator
 `from_le_bytes(b"penumbra.value.generator")` and then the `decaf377` CDH
 map-to-group method.
 
-## Homomorphic Commitments
+## Homomorphic Value Commitments
 
 We use the value generator associated to an asset ID to construct homomorphic
 commitments to (typed) value.  To do this, we first define the *blinding

docs/protocol/src/concepts/addresses_keys.md

@@ -62,4 +62,4 @@ addresses, allowing fine-grained control of delegation.
 
 This diagram shows only the user-visible parts of the key hierarchy.
 Internally, each of these keys has different components, described in detail in
-the [Addresses and Keys](../protocol/addresses_keys.md) chapter.
+the [Addresses and Keys](../addresses_keys.md) chapter.

docs/protocol/src/concepts/transactions.md

@@ -53,23 +53,23 @@ description leaves the value balance unchanged.
 #### Trading
 
 - **Swap** descriptions perform the first phase of
-[ZSwap](../zswap.md), consuming tokens of one type from a
+a swap, consuming tokens of one type from a
 transaction's value balance, burning them, and producing a swap commitment for
 use in the second stage;
 
 - **SwapClaim** descriptions perform the second phase of
-[ZSwap](../zswap.md), allowing a user who burned tokens of one
+a swap, allowing a user who burned tokens of one
 type to mint tokens of the other type at the chain-specified clearing price, and
 adding the new tokens to a transaction's value balance;
 
 #### Market-making
 
-- **OpenPosition** descriptions open [concentrated liquidity
-positions](../zswap.md#concentrated-liquidity), consuming value of the traded types from the
+- **OpenPosition** descriptions open concentrated liquidity
+positions, consuming value of the traded types from the
 transaction's value balance and adding the specified position to the AMM state;
 
-- **ClosePosition** descriptions close [concentrated liquidity
-positions](../zswap.md#concentrated-liquidity), removing the specified position to the AMM
+- **ClosePosition** descriptions close concentrated liquidity
+positions, removing the specified position to the AMM
 state and adding the value of the position, plus any accumulated fees or
 liquidity rewards, to the transaction's value balance.
 

docs/protocol/src/crypto/flow/ideal.md

@@ -81,7 +81,7 @@ In the case of same-block decryption,
 this assumption requires some care to integrate with the process for coming to
 consensus on the block containing transactions to batch and decrypt, but this is
 out-of-scope for flow encryption itself.  See [Flow Encryption and
-Consensus](../../protocol/flow-consensus.md) for details on this aspect in
+Consensus](../flow-encryption/flow-consensus.md) for details on this aspect in
 Penumbra specifically.
 
 ###### `FlowEnc/PreDecrypt`
@@ -133,7 +133,7 @@ that in the case where decryptors are validators, they can jointly learn the
 batched flow at the same time as they finalize a block and commit its state
 changes.  This property is important to avoid requiring a pipelined execution
 model.  For more details, see [Flow Encryption and
-Consensus](../../protocol/flow-consensus.md).
+Consensus](../flow-encryption/flow-consensus.md).
 
 Note that we do not require that any *specific* subset of decryption shares is
 used to get the (unique) decryption result in `FlowEnc/Decrypt`.  This permits a

docs/protocol/src/crypto/fmd/system_mapping.md

@@ -9,7 +9,7 @@ Each Penumbra diversified address includes as part of the encoded address an
 S-FMD *clue key*. This key can be used to derive a *clue* for a given output.
 
 See the
-[Addresses](../../protocol/addresses_keys/addresses.md) section for more details.
+[Addresses](../../addresses_keys/addresses.md) section for more details.
 
 ## Detection Keys
 

docs/protocol/src/dex.md

@@ -93,7 +93,7 @@ them to transmute one asset type to another, provably updating their private
 state without interacting with any other users' private state.
 
 This mechanism is described in more detail in the [Sealed-Bid Batch
-Swaps](./zswap/swap.md) section.
+Swaps](./dex/swap.md) section.
 
 ## Concentrated Liquidity
 
@@ -148,67 +148,7 @@ as long as they take care to avoid linking their positions (e.g., by timing or
 amount).
 
 Handling of concentrated liquidity is described in more detail in the
-[Concentrated Liquidity](./zswap/concentrated_liquidity.md) section.
-
-## Liquidity Compensation
-
-Systems that support both staking and liquidity provision need a mechanism to
-manage the [competitive equilibrium][staking-lending-competition] between these
-two uses of the staking token.  If staking rewards are too high relative to LP
-returns, LPs will choose to stake instead, causing liquidity to dry up.  On the
-other hand, if LP returns are too high relative to staking rewards, stakers will
-choose to provide liquidity instead, weakening the chain's economic security.
-
-Penumbra's staking design, which provides native delegation tokens for each
-validator, poses additional challenges.  LPs are disincentivized to provide
-liquidity in the staking token, if they could otherwise provide liquidity for a
-delegation token and get staking rewards as well as LP returns.  This is
-undesirable for a number of reasons: it fragments liquidity across many
-different delegation tokens, it undermines the security model to some extent (by
-making it easier to unload delegation tokens before misbehavior is detected),
-and it drives staking centralization (since larger validators would presumably
-have deeper liquidity in their delegation token, making it a more attractive
-asset).  
-
-To address these challenges, and allow the protocol to stabilize competition
-between staking and liquidity provision, ZSwap uses a mechanism called
-*liquidity compensation*, so named because it compensates LPs for the
-opportunity cost of not staking.  Instead of issuing staking rewards only to
-delegators, the total issuance in each epoch is split between delegators and
-liquidity providers.  To determine the split, the chain sets a target ratio of
-bonded stake to stake used for liquidity provision, and compares the actual
-ratio to the target ratio, similarly to the way that other systems adjust
-staking rewards based on the proportion of tokens staked.
-
-At the end of each epoch, the share of issuance used for liquidity compensation
-is allocated to each eligible liquidity position active during that epoch, pro
-rata to liquidity provided.  Eligible liquidity positions are any positions in
-trading pairs where one asset is the staking token, and the other asset is not a
-delegation token.
-
-This mechanism has several nice properties:
-
-- Although the amount of liquidity compensation is determined on the basis of
-value locked, it's allocated on the basis of liquidity provided.  This
-incentivizes LPs to efficiently deploy their capital, since LPs who can create
-finer liquidity positions will receive disproportionate liquidity compensation
-rewards.
-
-- Because markets in delegation tokens are not eligible for liquidity
-compensation, marketmakers providing liquidity between bonded and unbonded forms
-of the staking token must take on the opportunity cost of not staking the
-unbonded side.  Therefore, fees in those markets must be sufficient to cover
-that opportunity cost, so that there's no free, instant withdrawal from a
-delegation pool.
-
-- The mechanism is credibly neutral, applying to any trading pair involving the
-staking token, rather than artificially subsidizing certain tokens via
-governance proposals.
-
-This mechanism is described in more detail in the [Liquidity
-Compensation](./zswap/liquidity_compensation.md) section.
-
-
+[Concentrated Liquidity](./dex/concentrated_liquidity.md) section.
 
 
 [bwh]: https://ethresear.ch/t/why-you-cant-build-a-private-uniswap-with-zkps/7754

docs/protocol/src/dex/action/swap.md

@@ -61,12 +61,12 @@ The zk-SNARK certifies that the public input fee commitment $cv_f$ was derived f
 
 $cv_f = [-v_f] G_{v_f} + [\widetilde{v_f}] G_{\widetilde{v}}$
 
-where $G_{\widetilde{v}}$ is a constant generator and $G_{v_f}$ is an asset-specific generator point derived in-circuit from the asset ID $ID_{v_f}$ as described in [Value Commitments](../../protocol/value_commitments.md).
+where $G_{\widetilde{v}}$ is a constant generator and $G_{v_f}$ is an asset-specific generator point derived in-circuit from the asset ID $ID_{v_f}$ as described in [Assets and Values](../../assets.md).
 
 ### Balance Commitment Integrity
 
 The zk-SNARK certifies that the total public input balance commitment $cv$ was derived from the witnessed values as:
 
 $cv = [-v_1] G_1 + [-v_2] G_2 + cv_f$
 
-where the first two terms are from the input amounts and assets, with the corresponding asset-specific generators $G_1, G_2$ derived in-circuit as described in [Value Commitments](../../protocol/value_commitments.md), and $cv_f$ is the fee commitment.
+where the first two terms are from the input amounts and assets, with the corresponding asset-specific generators $G_1, G_2$ derived in-circuit as described in [Value Commitments](../../assets.md), and $cv_f$ is the fee commitment.

docs/protocol/src/dex/action/swap_claim.md

@@ -111,7 +111,7 @@ using the witnessed values above and where `ds` is a constant domain separator:
 
 `ds = from_le_bytes(BLAKE2b-512(b"penumbra.nullifier")) mod q`
 
-as described in [Nullifiers](../notes/nullifiers.md).
+as described in [Nullifiers](../../sct/nullifiers.md).
 
 ### Nullifier Key Linking
 

docs/protocol/src/governance/action/delegator_vote.md

@@ -89,7 +89,7 @@ The zk-SNARK certifies that the public input balance commitment $cv$ was derived
 
 $cv = [v] G_v + [\widetilde{v}] G_{\widetilde{v}}$
 
-where $G_{\widetilde{v}}$ is a constant generator and $G_v$ is an asset-specific generator point derived in-circuit as described in [Value Commitments](../../protocol/value_commitments.md). For delegator votes, $[\widetilde{v}] = 0$.
+where $G_{\widetilde{v}}$ is a constant generator and $G_v$ is an asset-specific generator point derived in-circuit as described in [Assets and Values](../../assets.md). For delegator votes, $[\widetilde{v}] = 0$.
 
 ### Nullifier Integrity
 
@@ -101,7 +101,7 @@ using the witnessed values above and where `ds` is a constant domain separator:
 
 `ds = from_le_bytes(BLAKE2b-512(b"penumbra.nullifier")) mod q`
 
-as described in [Nullifiers](../notes/nullifiers.md).
+as described in [Nullifiers](../../sct/nullifiers.md).
 
 ### Diversified Address Integrity
 
@@ -113,7 +113,7 @@ where $B_d$ is the witnessed diversified basepoint and $ivk$ is the incoming vie
 
 `ivk = hash_2(from_le_bytes(b"penumbra.derive.ivk"), nk, decaf377_s(ak)) mod r`
 
-as described in [Viewing Keys](../addresses_keys/viewing_keys.md).
+as described in [Viewing Keys](../../addresses_keys/viewing_keys.md).
 
 ### Spend Authority
 

docs/protocol/src/penumbra.md

@@ -94,15 +94,14 @@ encrypted votes and decrypt only the per-epoch totals.
 
 ## Private DEX
 
-Penumbra provides private, sealed-bid batch swaps using
-[ZSwap](./zswap.md).  ZSwap allows users to privately swap between any
-pair of assets.  Individual swaps do not reveal trade amounts.  Instead, all
-swaps in each block are executed in a single batch.  Only the total amount in
-each batch is revealed, and only after the batch has been finalized. This
-prevents front-running and provides better execution, but also provides
-long-term privacy for individual swaps.  Users can also provide liquidity by
-anonymously creating concentrated liquidity positions.  These
-positions reveal the amount of liquidity and the bounds in which it is
-concentrated, but are not otherwise linked to any identity, so that (with some
-care) users can privately approximate arbitrary trading functions without
-revealing their specific views about prices.
+Penumbra provides private, sealed-bid batch swaps using [ZSwap](./dex.md).
+ZSwap allows users to privately swap between any pair of assets.  Individual
+swaps do not reveal trade amounts.  Instead, all swaps in each block are
+executed in a single batch.  Only the total amount in each batch is revealed,
+and only after the batch has been finalized. This prevents front-running and
+provides better execution, but also provides long-term privacy for individual
+swaps.  Users can also provide liquidity by anonymously creating concentrated
+liquidity positions.  These positions reveal the amount of liquidity and the
+bounds in which it is concentrated, but are not otherwise linked to any
+identity, so that (with some care) users can privately approximate arbitrary
+trading functions without revealing their specific views about prices.

docs/protocol/src/shielded_pool.md

@@ -6,4 +6,4 @@ However, the notes themselves are never published to the chain.  Instead, the sh
 
 To prevent double-spending, each note has a unique serial number, called a _nullifier_.  Each `Spend` action reveals the nullifier of the spent note, and the chain checks that the nullifier has not already been revealed in a previous transaction.  Because the nullifier can only be derived using the keys that control the note, third parties cannot link spends and outputs.
 
-The note and its contents are described in further detail in [*Note Plaintexts*](./protocol/notes/note_plaintexts.md). Note commitments are described in [*Note Commitments*](./protocol/notes/note_commitments.md).
+The note and its contents are described in further detail in [*Note Plaintexts*](./shielded_pool/note_plaintexts.md). Note commitments are described in [*Note Commitments*](./shielded_pool/note_commitments.md).

docs/protocol/src/shielded_pool/action/output.md

@@ -62,7 +62,9 @@ The zk-SNARK certifies that the public input balance commitment $cv$ was derived
 
 $cv = [v] G_v + [\widetilde{v}] G_{\widetilde{v}}$
 
-where $G_{\widetilde{v}}$ is a constant generator and $G_v$ is an asset-specific generator point derived in-circuit as described in [Value Commitments](../../protocol/value_commitments.md).
+where $G_{\widetilde{v}}$ is a constant generator and $G_v$ is an asset-specific
+generator point derived in-circuit as described in [Assets and
+Values](../../assets.md).
 
 ### Diversified Base is not Identity
 

docs/protocol/src/shielded_pool/action/spend.md

@@ -72,7 +72,7 @@ The zk-SNARK certifies that the public input balance commitment $cv$ was derived
 
 $cv = [v] G_v + [\widetilde{v}] G_{\widetilde{v}}$
 
-where $G_{\widetilde{v}}$ is a constant generator and $G_v$ is an asset-specific generator point derived in-circuit as described in [Value Commitments](../../protocol/value_commitments.md).
+where $G_{\widetilde{v}}$ is a constant generator and $G_v$ is an asset-specific generator point derived in-circuit as described in [Assets and Values](../../assets.md).
 
 ### [Nullifier Integrity](#nullifier-integrity)
 
@@ -84,7 +84,7 @@ using the witnessed values above and where `ds` is a constant domain separator:
 
 `ds = from_le_bytes(BLAKE2b-512(b"penumbra.nullifier")) mod q`
 
-as described in [Nullifiers](../notes/nullifiers.md).
+as described in [Nullifiers](../../sct/nullifiers.md).
 
 ### [Diversified address Integrity](#diversified-address-integrity)
 
@@ -96,7 +96,7 @@ where $B_d$ is the witnessed diversified basepoint and $ivk$ is the incoming vie
 
 `ivk = hash_2(from_le_bytes(b"penumbra.derive.ivk"), nk, decaf377_s(ak)) mod r`
 
-as described in [Viewing Keys](../addresses_keys/viewing_keys.md).
+as described in [Viewing Keys](../../addresses_keys/viewing_keys.md).
 
 ### Randomized verification key Integrity
 

docs/protocol/src/stake/action/undelegate_claim.md

@@ -55,7 +55,7 @@ $v_e = [-v_i] G_{v_i} + [p * v_i] G_{v_t}$
 
 where $G_{v_i}$ is the asset-specific generator corresponding to the input
 token with asset ID $ID_i$ and $G_{v_t}$ is the asset-specific generator corresponding to the
-target token with asset ID $ID_t$. Both these asset-specific bases are derived in-circuit as described in [Value Commitments](../../protocol/value_commitments.md).
+target token with asset ID $ID_t$. Both these asset-specific bases are derived in-circuit as described in [Assets and Values](../../assets.md).
 
 ## Undelegate Claim