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 d2820d64f..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] -lightwalletd-tonic = ["tonic"] -transparent-inputs = ["hdwallet", "zcash_primitives/transparent-inputs"] +## 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 = [ - "proptest", + "dep:proptest", "orchard/test-dependencies", "zcash_primitives/test-dependencies", - "incrementalmerkletree/test-dependencies" + "incrementalmerkletree/test-dependencies", ] -unstable = ["byteorder"] -unstable-serialization = ["byteorder"] + +#! ### 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/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 { /// 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_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 9345ccba8..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", ] -transparent-inputs = ["hdwallet", "zcash_client_backend/transparent-inputs"] + +## 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_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/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/Cargo.toml b/zcash_primitives/Cargo.toml index 9d705349b..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"] -transparent-inputs = ["hdwallet", "ripemd", "secp256k1"] + +## 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 = [ - "proptest", + "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/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..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. @@ -15,7 +19,6 @@ pub mod block; pub mod consensus; pub mod constants; -pub mod keys; pub mod legacy; pub mod memo; pub mod merkle_tree; diff --git a/zcash_proofs/Cargo.toml b/zcash_proofs/Cargo.toml index 812364ce1..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"] -bundled-prover = ["wagyu-zcash-parameters"] + +## 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"] -download-params = ["minreq", "directories"] + +## 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.