specification: file organization in protocol spec

docs/protocol/src/SUMMARY.md

@@ -17,7 +17,6 @@
     - [Group Hash](./crypto/decaf377/group_hash.md)
     - [Test Vectors](./crypto/decaf377/test_vectors.md)
   - [Randomizable Signatures](./crypto/decaf377-rdsa.md)
-  - [Key Agreement](./crypto/decaf377-ka.md)
   - [Poseidon for BLS12-377](./crypto/poseidon.md)
     - [Overview of Poseidon Construction](./crypto/poseidon/overview.md)
     - [Poseidon Parameter Generation](./crypto/poseidon/paramgen.md)
@@ -30,7 +29,6 @@
     - [Parameter Considerations](./crypto/fmd/considerations.md)
   - [Flow Encryption](./crypto/flow.md)
     - [Ideal Functionality](./crypto/flow/ideal.md)
-    - [The `eddy` construction](./crypto/flow/eddy.md)
     - [Distributed Key Generation](./crypto/flow-encryption/dkg.md)
     - [Homomorphic Threshold Encryption](./crypto/flow-encryption/threshold-encryption.md)
     - [Flow Encryption and Consensus](./crypto/flow-encryption/flow-consensus.md)
@@ -54,20 +52,18 @@
   - [Transaction Memo](./transactions/memo.md)
 - [Multi-Asset Shielded Pool](./shielded_pool.md)
   - [Note Plaintexts](./shielded_pool/note_plaintexts.md)
-  - [Note Commitments](./shielded_pool/note_commitments.md)
   - [Note Ciphertexts](./shielded_pool/note_ciphertexts.md)
+  - [Note Commitments](./shielded_pool/note_commitments.md)
   - [Transaction Actions](./shielded_pool/action.md)
     - [`Spend`](./shielded_pool/action/spend.md)
     - [`Output`](./shielded_pool/action/output.md)
 - [Decentralized Exchange](./dex.md)
   - [Sealed-Bid Batch Swaps](./dex/swap.md)
   - [Concentrated Liquidity](./dex/concentrated_liquidity.md)
-  - [LPNFTs](./dex/lpnft.md)
   - [On-Chain Routing](./dex/routing.md)
   - [Transaction Actions](./dex/action.md)
     - [`Swap`](./dex/action/swap.md)
     - [`SwapClaim`](./dex/action/swap_claim.md)
-    - [`Position` Actions](./dex/action/position.md)
 - [Staking and Delegation](./stake.md)
   - [Staking Tokens](./stake/tokens.md)
   - [Validator Rewards and Fees](./stake/validator-rewards.md)
@@ -77,20 +73,13 @@
   - [Example Staking Dynamics](./stake/example.md)
   - [Arithmetic](./stake/arithmetic.md)
   - [Transaction Actions](./stake/action.md)
-    - [`Delegate`](./stake/action/delegate.md)
-    - [`Undelegate`](./stake/action/undelegate.md)
     - [`UndelegateClaim`](./stake/action/undelegate_claim.md)
 - [Governance](./governance.md)
   - [Transaction Actions](./governance/action.md)
     - [`DelegatorVote`](./governance/action/delegator_vote.md)
-    - [`ValidatorVote`](./governance/action/validator_vote.md)
-    - [`Proposal` Actions](./governance/action/proposal.md)
 - [IBC Integration](./ibc.md)
   - [Transaction Actions](./ibc/action.md)
     - [`IbcRelay`](./ibc/action/ibc_relay.md)
     - [`Ics20Withdrawal`](./ibc/action/ics20_withdrawal.md)
 - [Community Pool](./community_pool.md)
-  - [Transaction Actions](./community_pool/action.md)
-    - [`CommunityPoolSpend`](./community_pool/action/spend.md)
-    - [`CommunityPoolOutput`](./community_pool/action/output.md)
-    - [`CommunityPoolDeposit`](./community_pool/action/deposit.md)
+  - [Transaction Actions](./community_pool/action.md)

docs/protocol/src/addresses_keys/addresses.md

@@ -8,6 +8,14 @@ attaches a *detection key* to each address, allowing a user to outsource
 probabilistic transaction detection to a relatively untrusted third-party
 scanning service.
 
+## Privacy Implications
+
+While diversified addresses are described as *publicly unlinkable*, a detection entity given multiple detection keys can empirically link the corresponding diversified addresses via the clue keys $\mathsf{ck_d}$ contained within them. This is because the detection entity, by reporting detected transactions to the same user, empirically knows that the detection keys $\mathsf{dtk_d}$ are linked. If the detection entity observes two addresses belonging to the user, they can link them because the clue key appears in each address and is derived solely from the detection key. 
+
+In a simplified scenerio, a user with diversified addresses ${addr_1}$ and ${addr_2}$ gives the associated detection keys ${dtk_{d_1}}$ and ${dtk_{d_2}}$ to the detection entity. The detection entity detects relevant transactions using the clue keys ${ck_{d_1}}$ and ${ck_{d_2}}$, and reports the detected transactions for ${dtk_{d_1}}$ and ${dtk_{d_2}}$ back to the user. The detection entity can naively observe that transactions related to ${ck_{d_1}}$ and ${ck_{d_2}}$ are reported back to the same user, and therefore the addresses linked to these detection keys belong to the same user. There's a notion of linkability here since the diversified addresses can be linked by the detection entity through the detection keys, from which the clue keys are derived. 
+
+To mitigate the linkability of diversified addresses when using detection keys, a user should consider using multiple third parties: distribute detection keys to different detection entities instead of a single one, reducing the risk that any single entity has enough keys to link diversified addresses.
+
 ## Diversifiers
 
 Addresses are parameterized by *diversifiers*, 16-byte tags used to derive up to

docs/protocol/src/concepts/addresses_keys.md

@@ -37,10 +37,10 @@ flowchart BT
 
 From bottom to top:
 
-- the *seed phrase* is the root key material. Multiple *accounts* - each with
+- the *seed phrase* is the root key material. Multiple *wallets* - each with
 separate spend authority - can be derived from this root seed phrase.
-- the *spending key* is the capability representing spending authority for a given account;
-- the *full viewing key* represents the capability to view all transactions related to the account;
+- the *spending key* is the capability representing spending authority for a given wallet;
+- the *full viewing key* represents the capability to view all transactions related to the wallet;
 - the *outgoing viewing key* represents the capability to view only outgoing transactions, and is used to recover information about previously sent transactions;
 - the *incoming viewing key* represents the capability to view only incoming transactions, and is used to scan the block chain for incoming transactions.
 
@@ -59,7 +59,10 @@ relevant transactions, as well as some amount of unrelated cover traffic.
 Unlike incoming viewing keys, detection keys are not shared between diversified
 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](../addresses_keys.md) chapter.
+
+### Privacy Implications
+
+Users should be aware that giving out multiple detection keys to a detection entity can carry a subset of the privacy implications, described in [Addresses and Detection Keys](https://protocol.penumbra.zone/main/addresses_keys/addresses.html#detection-keys).

docs/protocol/src/crypto/flow-encryption/flow-consensus.md

@@ -1 +1,3 @@
 # Flow Encryption and Consensus
+
+Flow encryption is marked for the next version of the protocol. The documentation will be expanded to include detailed information on flow encryption and its implementation, reflecting the ongoing enhancements in the core protocol. 

docs/protocol/src/dex/swap.md

@@ -39,7 +39,7 @@ The swap commitment is then constructed using the above domain separator and
 hashing together the above contents along with an `inner` value computed using
 rate-4 poseidon hashing:
 
-`note_commitment = hash_7(ds, (rseed, f, t_f, B_d, pk_d, ck_d, inner))`
+`swap_commitment = hash_7(ds, (rseed, f, t_f, B_d, pk_d, ck_d, inner))`
 
 `inner = hash_4(ds, (t_1, t_2, \Delta_1, \Delta_2))`
 

docs/protocol/src/sct/nullifiers.md

@@ -68,7 +68,7 @@ These are the current types of state fragment recorded by Penumbra:
 The nullifier key for a note is the nullifier key component of the full viewing
 key for the address controlling the note.
 
-**Uniqueness**: TODO
+**Uniqueness**: Nullifiers are unique, to prevent faerie gold attacks, as they are derived from the position in the state commitment tree which is unique. 
 
 ### Swaps
 

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

@@ -38,7 +38,7 @@ The invariants that the Spend upholds are described below.
 
 #### Local Justification
 
-1. We verify the auth_sig using the randomized verification key, which must not be 0, provided on the spend body, even if the amount of the note is 0. A note's transmission key binds the authority via the `ivk` and `B_d` in the [Diversified Address Integrity](#diversified-address-integrity) check.
+1. We verify the auth_sig using the randomized verification key, provided on the spend body, even if the amount of the note is 0. The randomized verification key is derived using additive blinding, ensuring a non-zero key is produced. A note's transmission key binds the authority via the `ivk` and `B_d` in the [Diversified Address Integrity](#diversified-address-integrity) check.
 
 2. The following checks prevent spending a positioned note twice:
 
@@ -136,7 +136,7 @@ where $B_{SpendAuth}$ is the conventional `decaf377` basepoint as described in [
 
 ### [Merkle auth path verification](#merkle-auth-path-verification)
 
-The zk-SNARK certifies that for non-zero values $v \ne 0$, the witnessed Merkle authentication path is a valid Merkle path to the provided public anchor. Only for notes with non-zero values $v \ne 0$, the note is unrooted from the state commitment tree to allow for these "dummy" spends to pass stateless verification. Dummy spends may be added for metadata resistance (e.g. to ensure there are two spends and two outputs in each transaction).
+The zk-SNARK certifies that for non-zero values $v \ne 0$, the witnessed Merkle authentication path is a valid Merkle path to the provided public anchor. Only for notes with zero values ($v = 0$) the note is unrooted from the state commitment tree to allow for these "dummy" spends to pass stateless verification. Dummy spends may be added for metadata resistance (e.g. to ensure there are two spends and two outputs in each transaction).
 
 ### Diversified Base is not Identity
 

docs/protocol/src/shielded_pool/note_ciphertexts.md

@@ -1,3 +1,17 @@
 # Note Ciphertexts
 
-TK.
+Encrypting a note plaintext involves the following steps:
+
+1. Derive Ephemeral Secret Key: Use [decaf377-ka](https://github.com/penumbra-zone/decaf377-ka) to derive an ephemeral secret key *esk*.
+
+2. Derive Diversified Public Key: Generate a diversified public key from the secret key *epk*.
+
+3. Shared Secret Derivation: Perform a secure Diffie-Hellman key exchange to derive the shared secret between the sender and recipient.
+
+4. Symmetric Key Generation: Generate a symmetric [ChaCha20-Poly1305](https://protocol.penumbra.zone/main/addresses_keys/transaction_crypto.html#random-memo-key) payload key from the shared secret and ephemeral public key.
+
+5. Encryption: Encrypt with note plaintext, represented as a vector of bytes, using the ChaCha20-Poly1305 encryption algorithm.
+
+6. Construct the encrypted note ciphertext object.
+
+The note ciphertext is **176** bytes in length.

docs/protocol/src/shielded_pool/note_commitments.md

@@ -14,7 +14,7 @@ The note commitment is generated using rate-5 Poseidon hashing with domain separ
 The note commitment is then constructed using the above domain separator and
 hashing together the above contents along with the note blinding factor $rcm$:
 
-`note_commitment = hash_5(ds, (rcm, v, ID, B_d, pk_d))`
+`note_commitment = hash_6(ds, (rcm, v, ID, B_d, pk_d, ck_d))`
 
 The note blinding factor $rcm$ is derived from the `rseed` 32-byte value in the
 note. Define `prf_expand(label, key, input)` as BLAKE2b-512 with

docs/protocol/src/shielded_pool/note_plaintexts.md

@@ -5,6 +5,6 @@ Plaintext notes contain:
 * the value to be transmitted which consists of an integer amount $v$ along with a scalar (32 bytes) $ID$ identifying the asset.
 * $rseed$, a 32-byte random value, which will later be used to derive the note blinding factor used for the
 note commitment and an ephemeral secret key.
-* the destination address, described in more detail in the [Addresses](../addresses_keys/addresses.md) section.
+* the destination address controlling the note, described in more detail in the [Addresses](../addresses_keys/addresses.md) section.
 
 The note can only be spent by the holder of the spend key that corresponds to the diversified transmission key $pk_d$ in the note.