From b7bba9bbb2dba1ecceaa1b4ea5eab353648a2c83 Mon Sep 17 00:00:00 2001
From: Jack Grigg <jack@electriccoin.co>
Date: Thu, 14 Dec 2023 18:17:20 +0000
Subject: [PATCH 1/3] zcash_primitives: Remove `keys` module

---
 zcash_client_backend/src/decrypt.rs | 2 +-
 zcash_primitives/CHANGELOG.md       | 4 +++-
 zcash_primitives/src/keys.rs        | 1 -
 zcash_primitives/src/lib.rs         | 1 -
 4 files changed, 4 insertions(+), 4 deletions(-)
 delete mode 100644 zcash_primitives/src/keys.rs

diff --git a/zcash_client_backend/src/decrypt.rs b/zcash_client_backend/src/decrypt.rs
index 3cbae49ab..62c1fb8bd 100644
--- a/zcash_client_backend/src/decrypt.rs
+++ b/zcash_client_backend/src/decrypt.rs
@@ -41,7 +41,7 @@ pub struct DecryptedOutput<Note> {
     /// True if this output was recovered using an [`OutgoingViewingKey`], meaning that
     /// this is a logical output of the transaction.
     ///
-    /// [`OutgoingViewingKey`]: zcash_primitives::keys::OutgoingViewingKey
+    /// [`OutgoingViewingKey`]: sapling::keys::OutgoingViewingKey
     pub transfer_type: TransferType,
 }
 
diff --git a/zcash_primitives/CHANGELOG.md b/zcash_primitives/CHANGELOG.md
index 441e178bc..6cc4d3090 100644
--- a/zcash_primitives/CHANGELOG.md
+++ b/zcash_primitives/CHANGELOG.md
@@ -110,8 +110,10 @@ and this library adheres to Rust's notion of
 ### Removed
 - `zcash_primitives::constants`:
   - All `const` values (moved to `sapling_crypto::constants`).
-- `zcash_primitives::keys`:
+- `zcash_primitives::keys` module, as it was empty after the removal of:
   - `PRF_EXPAND_PERSONALIZATION`
+  - `OutgoingViewingKey` (use `sapling_crypto::keys::OutgoingViewingKey`
+    instead).
   - `prf_expand, prf_expand_vec` (use `zcash_spec::PrfExpand` instead).
 - `zcash_primitives::sapling` module (use the `sapling-crypto` crate instead).
 - `zcash_primitives::transaction::components::sapling`:
diff --git a/zcash_primitives/src/keys.rs b/zcash_primitives/src/keys.rs
deleted file mode 100644
index c263127ba..000000000
--- a/zcash_primitives/src/keys.rs
+++ /dev/null
@@ -1 +0,0 @@
-pub use crate::sapling::keys::OutgoingViewingKey;
diff --git a/zcash_primitives/src/lib.rs b/zcash_primitives/src/lib.rs
index 17362155b..884bceffc 100644
--- a/zcash_primitives/src/lib.rs
+++ b/zcash_primitives/src/lib.rs
@@ -15,7 +15,6 @@
 pub mod block;
 pub mod consensus;
 pub mod constants;
-pub mod keys;
 pub mod legacy;
 pub mod memo;
 pub mod merkle_tree;

From 0df4c6f043facb50795f57956ee0108ad6a3dd78 Mon Sep 17 00:00:00 2001
From: Jack Grigg <jack@electriccoin.co>
Date: Wed, 3 Jan 2024 19:49:36 +0000
Subject: [PATCH 2/3] Remove implicit feature flags for optional dependencies

All optional dependencies are enabled as part of dedicated feature
flags.
---
 zcash_client_backend/Cargo.toml | 10 +++++-----
 zcash_client_sqlite/Cargo.toml  |  2 +-
 zcash_history/Cargo.toml        |  2 +-
 zcash_primitives/Cargo.toml     |  4 ++--
 zcash_proofs/Cargo.toml         |  4 ++--
 5 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/zcash_client_backend/Cargo.toml b/zcash_client_backend/Cargo.toml
index d2820d64f..3f63b034e 100644
--- a/zcash_client_backend/Cargo.toml
+++ b/zcash_client_backend/Cargo.toml
@@ -100,16 +100,16 @@ zcash_address = { workspace = true, features = ["test-dependencies"] }
 time = ">=0.3.22, <0.3.24" # time 0.3.24 has MSRV 1.67
 
 [features]
-lightwalletd-tonic = ["tonic"]
-transparent-inputs = ["hdwallet", "zcash_primitives/transparent-inputs"]
+lightwalletd-tonic = ["dep:tonic"]
+transparent-inputs = ["dep:hdwallet", "zcash_primitives/transparent-inputs"]
 test-dependencies = [
-    "proptest",
+    "dep:proptest",
     "orchard/test-dependencies",
     "zcash_primitives/test-dependencies",
     "incrementalmerkletree/test-dependencies"
 ]
-unstable = ["byteorder"]
-unstable-serialization = ["byteorder"]
+unstable = ["dep:byteorder"]
+unstable-serialization = ["dep:byteorder"]
 unstable-spanning-tree = []
 
 [lib]
diff --git a/zcash_client_sqlite/Cargo.toml b/zcash_client_sqlite/Cargo.toml
index 9345ccba8..00e07cec3 100644
--- a/zcash_client_sqlite/Cargo.toml
+++ b/zcash_client_sqlite/Cargo.toml
@@ -79,7 +79,7 @@ test-dependencies = [
     "zcash_client_backend/test-dependencies",
     "incrementalmerkletree/test-dependencies",
 ]
-transparent-inputs = ["hdwallet", "zcash_client_backend/transparent-inputs"]
+transparent-inputs = ["dep:hdwallet", "zcash_client_backend/transparent-inputs"]
 unstable = ["zcash_client_backend/unstable"]
 
 [lib]
diff --git a/zcash_history/Cargo.toml b/zcash_history/Cargo.toml
index a14ae93b5..9ab8d41ed 100644
--- a/zcash_history/Cargo.toml
+++ b/zcash_history/Cargo.toml
@@ -20,7 +20,7 @@ blake2b_simd.workspace = true
 proptest = { workspace = true, optional = true }
 
 [features]
-test-dependencies = ["proptest"]
+test-dependencies = ["dep:proptest"]
 
 [lib]
 bench = false
diff --git a/zcash_primitives/Cargo.toml b/zcash_primitives/Cargo.toml
index 9d705349b..e0e824f3e 100644
--- a/zcash_primitives/Cargo.toml
+++ b/zcash_primitives/Cargo.toml
@@ -100,10 +100,10 @@ pprof = { version = "0.11", features = ["criterion", "flamegraph"] } # MSRV 1.56
 [features]
 default = ["multicore"]
 multicore = ["orchard/multicore", "sapling/multicore"]
-transparent-inputs = ["hdwallet", "ripemd", "secp256k1"]
+transparent-inputs = ["dep:hdwallet", "dep:ripemd", "dep:secp256k1"]
 temporary-zcashd = []
 test-dependencies = [
-    "proptest",
+    "dep:proptest",
     "orchard/test-dependencies",
     "sapling/test-dependencies",
 ]
diff --git a/zcash_proofs/Cargo.toml b/zcash_proofs/Cargo.toml
index 812364ce1..9fb228262 100644
--- a/zcash_proofs/Cargo.toml
+++ b/zcash_proofs/Cargo.toml
@@ -45,9 +45,9 @@ byteorder.workspace = true
 
 [features]
 default = ["local-prover", "multicore"]
-bundled-prover = ["wagyu-zcash-parameters"]
+bundled-prover = ["dep:wagyu-zcash-parameters"]
 directories = ["dep:home", "dep:known-folders", "dep:xdg"]
-download-params = ["minreq", "directories"]
+download-params = ["dep:minreq", "directories"]
 local-prover = ["directories"]
 multicore = ["bellman/multicore", "zcash_primitives/multicore"]
 

From 2ea83243a7259c0366152d83c9e77311cf0d68c5 Mon Sep 17 00:00:00 2001
From: Jack Grigg <jack@electriccoin.co>
Date: Wed, 3 Jan 2024 20:14:41 +0000
Subject: [PATCH 3/3] Document the feature flags

---
 Cargo.lock                      | 22 +++++++++++++++++++++-
 Cargo.toml                      |  5 ++++-
 zcash_client_backend/Cargo.toml | 18 +++++++++++++++++-
 zcash_client_backend/src/lib.rs |  4 ++++
 zcash_client_sqlite/Cargo.toml  | 14 ++++++++++++++
 zcash_client_sqlite/src/lib.rs  |  6 ++----
 zcash_primitives/Cargo.toml     | 21 +++++++++++++++++++++
 zcash_primitives/src/lib.rs     |  4 ++++
 zcash_proofs/Cargo.toml         | 15 +++++++++++++++
 zcash_proofs/src/lib.rs         |  4 ++++
 10 files changed, 106 insertions(+), 7 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 84b077925..2815edac3 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -638,6 +638,15 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "document-features"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef5282ad69563b5fc40319526ba27e0e7363d552a896f0297d54f767717f9b95"
+dependencies = [
+ "litrs",
+]
+
 [[package]]
 name = "either"
 version = "1.9.0"
@@ -1237,6 +1246,12 @@ version = "0.4.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "969488b55f8ac402214f3f5fd243ebb7206cf82de60d3172994707a4bcc2b829"
 
+[[package]]
+name = "litrs"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ce301924b7887e9d637144fdade93f9dfff9b60981d4ac161db09720d39aa5"
+
 [[package]]
 name = "lock_api"
 version = "0.4.11"
@@ -2087,7 +2102,7 @@ dependencies = [
 [[package]]
 name = "sapling-crypto"
 version = "0.0.1"
-source = "git+https://github.com/zcash/sapling-crypto.git?rev=71711b9e4b775a625318070e0f56b7b652f12306#71711b9e4b775a625318070e0f56b7b652f12306"
+source = "git+https://github.com/zcash/sapling-crypto.git?rev=4ec6a48daab0af1fe6cb930f6a150030ce91d0e9#4ec6a48daab0af1fe6cb930f6a150030ce91d0e9"
 dependencies = [
  "aes",
  "bellman",
@@ -2096,6 +2111,7 @@ dependencies = [
  "blake2s_simd",
  "bls12_381",
  "byteorder",
+ "document-features",
  "ff",
  "fpe",
  "group",
@@ -2995,6 +3011,7 @@ dependencies = [
  "bs58",
  "byteorder",
  "crossbeam-channel",
+ "document-features",
  "group",
  "gumdrop",
  "hdwallet",
@@ -3033,6 +3050,7 @@ dependencies = [
  "assert_matches",
  "bs58",
  "byteorder",
+ "document-features",
  "group",
  "hdwallet",
  "incrementalmerkletree",
@@ -3118,6 +3136,7 @@ dependencies = [
  "byteorder",
  "chacha20poly1305",
  "criterion",
+ "document-features",
  "equihash",
  "ff",
  "fpe",
@@ -3156,6 +3175,7 @@ dependencies = [
  "blake2b_simd",
  "bls12_381",
  "byteorder",
+ "document-features",
  "group",
  "home",
  "jubjub",
diff --git a/Cargo.toml b/Cargo.toml
index 0b48649fa..c06009d87 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -66,6 +66,9 @@ rand_core = "0.6"
 blake2b_simd = "1"
 sha2 = "0.10"
 
+# Documentation
+document-features = "0.2"
+
 # Encodings
 base64 = "0.21"
 bech32 = "0.9"
@@ -112,5 +115,5 @@ panic = 'abort'
 codegen-units = 1
 
 [patch.crates-io]
-sapling = { package = "sapling-crypto", git = "https://github.com/zcash/sapling-crypto.git", rev = "71711b9e4b775a625318070e0f56b7b652f12306" }
+sapling = { package = "sapling-crypto", git = "https://github.com/zcash/sapling-crypto.git", rev = "4ec6a48daab0af1fe6cb930f6a150030ce91d0e9" }
 orchard = { git = "https://github.com/zcash/orchard.git", rev = "189257391a5726d7f3f2568d547a5ef8603c7156" }
diff --git a/zcash_client_backend/Cargo.toml b/zcash_client_backend/Cargo.toml
index 3f63b034e..7b3eae55e 100644
--- a/zcash_client_backend/Cargo.toml
+++ b/zcash_client_backend/Cargo.toml
@@ -74,6 +74,9 @@ nom = "7"
 
 # Dependencies used internally:
 # (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
+# - Documentation
+document-features.workspace = true
+
 # - Encodings
 byteorder = { workspace = true, optional = true }
 percent-encoding.workspace = true
@@ -100,16 +103,29 @@ zcash_address = { workspace = true, features = ["test-dependencies"] }
 time = ">=0.3.22, <0.3.24" # time 0.3.24 has MSRV 1.67
 
 [features]
+## Enables the `tonic` gRPC client bindings for connecting to a `lightwalletd` server.
 lightwalletd-tonic = ["dep:tonic"]
+
+## Enables receiving transparent funds and shielding them.
 transparent-inputs = ["dep:hdwallet", "zcash_primitives/transparent-inputs"]
+
+## Exposes APIs that are useful for testing, such as `proptest` strategies.
 test-dependencies = [
     "dep:proptest",
     "orchard/test-dependencies",
     "zcash_primitives/test-dependencies",
-    "incrementalmerkletree/test-dependencies"
+    "incrementalmerkletree/test-dependencies",
 ]
+
+#! ### Experimental features
+
+## Exposes unstable APIs. Their behaviour may change at any time.
 unstable = ["dep:byteorder"]
+
+## Exposes APIs for unstable serialization formats. These may change at any time.
 unstable-serialization = ["dep:byteorder"]
+
+## Exposes the [`data_api::scanning::spanning_tree`] module.
 unstable-spanning-tree = []
 
 [lib]
diff --git a/zcash_client_backend/src/lib.rs b/zcash_client_backend/src/lib.rs
index b8a45ba89..486ca7d47 100644
--- a/zcash_client_backend/src/lib.rs
+++ b/zcash_client_backend/src/lib.rs
@@ -2,6 +2,10 @@
 //!
 //! `zcash_client_backend` contains Rust structs and traits for creating shielded Zcash
 //! light clients.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 // Catch documentation errors caused by code changes.
 #![deny(rustdoc::broken_intra_doc_links)]
diff --git a/zcash_client_sqlite/Cargo.toml b/zcash_client_sqlite/Cargo.toml
index 00e07cec3..9087ba36b 100644
--- a/zcash_client_sqlite/Cargo.toml
+++ b/zcash_client_sqlite/Cargo.toml
@@ -53,6 +53,7 @@ uuid = "1.1"
 
 # Dependencies used internally:
 # (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
+document-features.workspace = true
 maybe-rayon.workspace = true
 
 [dev-dependencies]
@@ -71,15 +72,28 @@ zcash_address = { workspace = true, features = ["test-dependencies"] }
 
 [features]
 default = ["multicore"]
+
+## Enables multithreading support for creating proofs and building subtrees.
 multicore = ["maybe-rayon/threads", "zcash_primitives/multicore"]
+
+## Configures the light client for use with the Zcash mainnet. By default, the light
+## client is configured for use with the Zcash testnet.
 mainnet = []
+
+## Exposes APIs that are useful for testing, such as `proptest` strategies.
 test-dependencies = [
     "incrementalmerkletree/test-dependencies",
     "zcash_primitives/test-dependencies",
     "zcash_client_backend/test-dependencies",
     "incrementalmerkletree/test-dependencies",
 ]
+
+## Enables receiving transparent funds and shielding them.
 transparent-inputs = ["dep:hdwallet", "zcash_client_backend/transparent-inputs"]
+
+#! ### Experimental features
+
+## Exposes unstable APIs. Their behaviour may change at any time.
 unstable = ["zcash_client_backend/unstable"]
 
 [lib]
diff --git a/zcash_client_sqlite/src/lib.rs b/zcash_client_sqlite/src/lib.rs
index f000eebe8..745a701f4 100644
--- a/zcash_client_sqlite/src/lib.rs
+++ b/zcash_client_sqlite/src/lib.rs
@@ -18,10 +18,8 @@
 //!   **MUST NOT** write to the database without using these APIs. Callers **MAY** read
 //!   the database directly in order to extract information for display to users.
 //!
-//! # Features
-//!
-//! The `mainnet` feature configures the light client for use with the Zcash mainnet. By
-//! default, the light client is configured for use with the Zcash testnet.
+//! ## Feature flags
+#![doc = document_features::document_features!()]
 //!
 //! [`WalletRead`]: zcash_client_backend::data_api::WalletRead
 //! [`WalletWrite`]: zcash_client_backend::data_api::WalletWrite
diff --git a/zcash_primitives/Cargo.toml b/zcash_primitives/Cargo.toml
index e0e824f3e..c7512a6ef 100644
--- a/zcash_primitives/Cargo.toml
+++ b/zcash_primitives/Cargo.toml
@@ -66,6 +66,9 @@ bip0039 = { version = "0.10", features = ["std", "all-languages"] }
 
 # Dependencies used internally:
 # (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
+# - Documentation
+document-features.workspace = true
+
 # - Encodings
 byteorder.workspace = true
 hex.workspace = true
@@ -99,15 +102,33 @@ pprof = { version = "0.11", features = ["criterion", "flamegraph"] } # MSRV 1.56
 
 [features]
 default = ["multicore"]
+
+## Enables multithreading support for creating proofs.
 multicore = ["orchard/multicore", "sapling/multicore"]
+
+## Enables spending transparent notes with the transaction builder.
 transparent-inputs = ["dep:hdwallet", "dep:ripemd", "dep:secp256k1"]
+
+### A temporary feature flag that exposes granular APIs needed by `zcashd`. These APIs
+### should not be relied upon and will be removed in a future release.
 temporary-zcashd = []
+
+## Exposes APIs that are useful for testing, such as `proptest` strategies.
 test-dependencies = [
     "dep:proptest",
     "orchard/test-dependencies",
     "sapling/test-dependencies",
 ]
+
+#! ### Experimental features
+#!
+#! ⚠️ Enabling these features will likely make your code incompatible with current Zcash
+#! consensus rules!
+
+## Exposes the in-development NU6 features.
 unstable-nu6 = []
+
+## Exposes early in-development features that are not yet planned for any network upgrade.
 zfuture = []
 
 [lib]
diff --git a/zcash_primitives/src/lib.rs b/zcash_primitives/src/lib.rs
index 884bceffc..e45cc8c5f 100644
--- a/zcash_primitives/src/lib.rs
+++ b/zcash_primitives/src/lib.rs
@@ -2,6 +2,10 @@
 //!
 //! `zcash_primitives` is a library that provides the core structs and functions necessary
 //! for working with Zcash.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
 // Catch documentation errors caused by code changes.
diff --git a/zcash_proofs/Cargo.toml b/zcash_proofs/Cargo.toml
index 9fb228262..dfa4966c7 100644
--- a/zcash_proofs/Cargo.toml
+++ b/zcash_proofs/Cargo.toml
@@ -34,6 +34,7 @@ tracing.workspace = true
 # Dependencies used internally:
 # (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
 blake2b_simd.workspace = true
+document-features.workspace = true
 home = { version = "0.5", optional = true }
 known-folders = { version = "1", optional = true }
 redjubjub = "0.7"
@@ -45,10 +46,24 @@ byteorder.workspace = true
 
 [features]
 default = ["local-prover", "multicore"]
+
+## Bundles the Sapling proving parameters inside the binary, which will increase its size
+## by around 50 MiB.
 bundled-prover = ["dep:wagyu-zcash-parameters"]
+
+## Enables APIs for determining the default location on the local filesystem for storing
+## the Sprout and Sapling proving parameters.
 directories = ["dep:home", "dep:known-folders", "dep:xdg"]
+
+## Enables APIs for downloading the Sprout and Sapling proving parameters to the default
+## location on the local filesystem.
 download-params = ["dep:minreq", "directories"]
+
+## Enables APIs for loading the Sapling proving parameters from the default location on
+## the local filesystem.
 local-prover = ["directories"]
+
+## Enables multithreading support for creating proofs.
 multicore = ["bellman/multicore", "zcash_primitives/multicore"]
 
 [lib]
diff --git a/zcash_proofs/src/lib.rs b/zcash_proofs/src/lib.rs
index be28a033c..4c094c183 100644
--- a/zcash_proofs/src/lib.rs
+++ b/zcash_proofs/src/lib.rs
@@ -2,6 +2,10 @@
 //!
 //! `zcash_proofs` contains the zk-SNARK circuits used by Zcash, and the APIs for creating
 //! and verifying proofs.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
 // Catch documentation errors caused by code changes.