From c3e6ee7a835069ece0049a334abac46cca461cc0 Mon Sep 17 00:00:00 2001 From: Conor Schaefer Date: Wed, 12 Jul 2023 08:32:42 -0700 Subject: [PATCH] docs: fix broken links in protocol spec Used `cargo install mdbook-linkcheck` to identify broken internal links. There are still a few failing checks in the protocol spec, but they're all about threshold encryption articles not being listed in SUMMARY.md. Fine to circle back on that. Follow-up to https://github.com/penumbra-zone/penumbra/pull/2821 --- docs/protocol/book.toml | 5 +++++ docs/protocol/src/SUMMARY.md | 3 ++- docs/protocol/src/concepts/transactions.md | 4 ++-- .../src/crypto/flow-encryption/threshold-encryption.md | 2 +- docs/protocol/src/protocol.md | 2 +- docs/protocol/src/protocol/action_descriptions/outputs.md | 6 +++--- docs/protocol/src/protocol/action_descriptions/spend.md | 2 +- docs/protocol/src/protocol/action_descriptions/swap.md | 2 +- docs/protocol/src/protocol/notes/note_ciphertexts.md | 2 ++ docs/protocol/src/protocol/transaction_crypto.md | 6 +++--- docs/protocol/src/shielded_pool.md | 2 +- 11 files changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/protocol/book.toml b/docs/protocol/book.toml index 58fc77b8e9..ae8d613773 100644 --- a/docs/protocol/book.toml +++ b/docs/protocol/book.toml @@ -18,3 +18,8 @@ fold = { enable = true, level = 1 } git-repository-url = "https://github.com/penumbra-zone/penumbra" additional-js =["theme/js/mermaid.min.js", "theme/js/mermaid-init.js"] +# Documenting config for `mdbook-linkcheck`. We don't have this +# enabled in CI yet, but it's sure handy for fixing up links. +# [output.linkcheck] +# follow-web-links = false +# warning-policy = "ignore" diff --git a/docs/protocol/src/SUMMARY.md b/docs/protocol/src/SUMMARY.md index 940e3906ce..b3120ce94c 100644 --- a/docs/protocol/src/SUMMARY.md +++ b/docs/protocol/src/SUMMARY.md @@ -7,7 +7,8 @@ - [Notes, Nullifiers, and Trees](./concepts/notes_nullifiers_trees.md) - [Transactions](./concepts/transactions.md) - [Governance](./concepts/governance.md) -- [Cryptographic Primitives](./crypto.md) +- [Cryptographic Protocol](./protocol.md) + - [Cryptographic Primitives](./crypto.md) - [Proving Considerations](./crypto/proofs.md) - [The `decaf377` group](./crypto/decaf377.md) - [Costs and Alternatives](./crypto/decaf377/costs.md) diff --git a/docs/protocol/src/concepts/transactions.md b/docs/protocol/src/concepts/transactions.md index cd1937686e..a2c2018ede 100644 --- a/docs/protocol/src/concepts/transactions.md +++ b/docs/protocol/src/concepts/transactions.md @@ -57,12 +57,12 @@ description leaves the value balance unchanged. #### Trading - **Swap** descriptions perform the first phase of -[ZSwap](../zswap/auction.md), consuming tokens of one type from a +[ZSwap](../zswap.md), consuming tokens of one type from a transaction's value balance, burning them, and producing a swap commitment for use in the second stage; - **Sweep** descriptions perform the second phase of -[ZSwap](../zswap/auction.md), allowing a user who burned tokens of one +[ZSwap](../zswap.md), 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; diff --git a/docs/protocol/src/crypto/flow-encryption/threshold-encryption.md b/docs/protocol/src/crypto/flow-encryption/threshold-encryption.md index 2b929a7623..2400580367 100644 --- a/docs/protocol/src/crypto/flow-encryption/threshold-encryption.md +++ b/docs/protocol/src/crypto/flow-encryption/threshold-encryption.md @@ -2,7 +2,7 @@ The core of the flow encryption system requires a partially homomorphic encryption scheme, which allows for users to publish transactions that contain -*encrypted* [values](../../concepts/asset_amounts.md). These encrypted values +*encrypted* [values](../../concepts/assets_amounts.md). These encrypted values are then *aggregated*, using the homomorphism, by validators. The aggregate value (the "batched flow") is then decrypted using the threshold decryption scheme described here. diff --git a/docs/protocol/src/protocol.md b/docs/protocol/src/protocol.md index 8c754cd009..970310460c 100644 --- a/docs/protocol/src/protocol.md +++ b/docs/protocol/src/protocol.md @@ -5,7 +5,7 @@ described in more detail in the following sections: - The [Addressses and Keys](./protocol/addresses_keys.md) section describes the Penumbra key hierarchy and diversified addresses. -- The [Notes](./protocol/notes.md) section describes Penumbra's private notes and their contents. +- The [Notes](./protocol/notes/note_ciphertexts.md) section describes Penumbra's private notes and their contents. - The [Transaction Cryptography](./protocol/transaction_crypto.md) section describes the symmetric keys used at the level of an individual transaction. diff --git a/docs/protocol/src/protocol/action_descriptions/outputs.md b/docs/protocol/src/protocol/action_descriptions/outputs.md index bc99847a83..ade2f15db0 100644 --- a/docs/protocol/src/protocol/action_descriptions/outputs.md +++ b/docs/protocol/src/protocol/action_descriptions/outputs.md @@ -13,7 +13,7 @@ The output proof demonstrates the properties enumerated below for the private wi * Note amount $v$ (interpreted as an $\mathbb F_q$) and asset `ID` $\isin \mathbb G$ * Blinding factor $rcm \isin \mathbb F_q$ used to blind the note commitment * Diversified basepoint $B_d \isin \mathbb G$ corresponding to the address -* Transmission key $pk_d \isin \mathbb G$ corresponding to the address +* Transmission key $pk_d \isin \mathbb G$ corresponding to the address * Clue key $\mathsf{ck_d} \isin \mathbb F_q$ corresponding to the address * Blinding factor $\tilde v \isin \mathbb F_r$ used to blind the balance commitment @@ -38,11 +38,11 @@ The zk-SNARK certifies that the public input balance commitment $cv$ was derived $cv = [v] G_v + [\tilde v] G_{\tilde v}$ -where $G_{\tilde v}$ is a constant generator and $G_v$ is an asset-specific generator point derived as described in [Value Commitments](../value_commitments.md). +where $G_{\tilde v}$ is a constant generator and $G_v$ is an asset-specific generator point derived as described in [Value Commitments](../../protocol/value_commitments.md). ### Diversified Base is not Identity -The zk-SNARK certifies that the diversified basepoint $B_d$ is not identity. +The zk-SNARK certifies that the diversified basepoint $B_d$ is not identity. Note that we do _not_ check the integrity of the ephemeral public key $epk$ in the zk-SNARK. Instead this check should be performed at note decryption time as described above. diff --git a/docs/protocol/src/protocol/action_descriptions/spend.md b/docs/protocol/src/protocol/action_descriptions/spend.md index 752b081f34..601a547286 100644 --- a/docs/protocol/src/protocol/action_descriptions/spend.md +++ b/docs/protocol/src/protocol/action_descriptions/spend.md @@ -44,7 +44,7 @@ The zk-SNARK certifies that for non-zero values $v \ne 0$, the public input bala $cv = [v] G_v + [\tilde v] G_{\tilde v}$ -where $G_{\tilde v}$ is a constant generator and $G_v$ is an asset-specific generator point derived as described in [Value Commitments](../value_commitments.md). +where $G_{\tilde v}$ is a constant generator and $G_v$ is an asset-specific generator point derived as described in [Value Commitments](../../protocol/value_commitments.md). ### Nullifier Integrity diff --git a/docs/protocol/src/protocol/action_descriptions/swap.md b/docs/protocol/src/protocol/action_descriptions/swap.md index 307d949331..d9527cf702 100644 --- a/docs/protocol/src/protocol/action_descriptions/swap.md +++ b/docs/protocol/src/protocol/action_descriptions/swap.md @@ -42,7 +42,7 @@ The zk-SNARK certifies that the public input fee commitment $cv_f$ was derived f $cv_f = [v_f] G_{v_f} + [\tilde v_f] G_{\tilde v}$ -where $G_{\tilde v}$ is a constant generator and $G_{v_f}$ is an asset-specific generator point derived as described in [Value Commitments](../../protocol/value_commitments.md). +where $G_{\tilde v}$ is a constant generator and $G_{v_f}$ is an asset-specific generator point derived as described in [Value Commitments](../../protocol/value_commitments.md). ### Balance Commitment Integrity diff --git a/docs/protocol/src/protocol/notes/note_ciphertexts.md b/docs/protocol/src/protocol/notes/note_ciphertexts.md index e06bcedd92..f2549e5d41 100644 --- a/docs/protocol/src/protocol/notes/note_ciphertexts.md +++ b/docs/protocol/src/protocol/notes/note_ciphertexts.md @@ -1 +1,3 @@ # Note Ciphertexts + +TK. diff --git a/docs/protocol/src/protocol/transaction_crypto.md b/docs/protocol/src/protocol/transaction_crypto.md index b93298de34..79a1b54950 100644 --- a/docs/protocol/src/protocol/transaction_crypto.md +++ b/docs/protocol/src/protocol/transaction_crypto.md @@ -29,7 +29,7 @@ It is derived from the shared secret. It is used for a single action. * A *per-action swap payload key* used to encrypt a single swap. It is derived from the outgoing viewing key. It is used for a single action. * A *random payload key* used to encrypt a memo. It is generated randomly and is shared between all actions in a given transaction. -* An *outgoing cipher key* used to encrypt key material (the shared secret) to enable the sender to +* An *outgoing cipher key* used to encrypt key material (the shared secret) to enable the sender to later decrypt an outgoing swap, note, or memo. * An *OVK wrapped key* - this is the shared secret encrypted using the sender's outgoing cipher key. A sender can later use this field to recover the shared secret @@ -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 [Addressses](../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](../protocol/addresses_keys/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 posess. @@ -84,7 +84,7 @@ should be able to decrypt the per-transaction memo. ### Outgoing Cipher Key The symmetric outgoing cipher key is a 32-byte key derived from the sender's outgoing viewing key -$ovk$, the value commitment $cv$, the note commitment $cm$, the ephemeral +$ovk$, the value commitment $cv$, the note commitment $cm$, the ephemeral public key $epk$, and personalization string "Penumbra_OutCiph": ``` diff --git a/docs/protocol/src/shielded_pool.md b/docs/protocol/src/shielded_pool.md index 5d1ddac9df..07f96b48f6 100644 --- a/docs/protocol/src/shielded_pool.md +++ b/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*](./notes/note_plaintexts.md). Note commitments are described in [*Note Commitments*](./notes/note_commitments.md). \ No newline at end of file +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).