diff --git a/zebra-chain/src/block.rs b/zebra-chain/src/block.rs index caf2e80ef..ada83e3e2 100644 --- a/zebra-chain/src/block.rs +++ b/zebra-chain/src/block.rs @@ -111,6 +111,7 @@ impl Block { /// > for SIGHASH transaction hashes, as specified in [ZIP-244]. /// /// + /// /// [ZIP-244]: https://zips.z.cash/zip-0244 pub fn check_transaction_network_upgrade_consistency( &self, @@ -154,7 +155,7 @@ impl Block { /// Count how many Sapling transactions exist in a block, /// i.e. transactions "where either of vSpendsSapling or vOutputsSapling is non-empty" - /// (https://zips.z.cash/zip-0221#tree-node-specification). + /// . pub fn sapling_transactions_count(&self) -> u64 { self.transactions .iter() @@ -166,7 +167,7 @@ impl Block { /// Count how many Orchard transactions exist in a block, /// i.e. transactions "where vActionsOrchard is non-empty." - /// (https://zips.z.cash/zip-0221#tree-node-specification). + /// . pub fn orchard_transactions_count(&self) -> u64 { self.transactions .iter() @@ -187,7 +188,7 @@ impl Block { /// /// /// - /// `utxos` must contain the [`Utxo`]s of every input in this block, + /// `utxos` must contain the [`transparent::Utxo`]s of every input in this block, /// including UTXOs created by earlier transactions in this block. /// (It can also contain unrelated UTXOs, which are ignored.) /// diff --git a/zebra-chain/src/block/arbitrary.rs b/zebra-chain/src/block/arbitrary.rs index 80d830f6a..c79795238 100644 --- a/zebra-chain/src/block/arbitrary.rs +++ b/zebra-chain/src/block/arbitrary.rs @@ -314,7 +314,7 @@ impl Arbitrary for LedgerState { /// Generate an arbitrary [`LedgerState`]. /// /// The default strategy arbitrarily skips some coinbase transactions, and - /// has an arbitrary start height. To override, use a specific [`LegderState`] + /// has an arbitrary start height. To override, use a specific [`LedgerState`] /// strategy method. fn arbitrary_with(ledger_override: Self::Parameters) -> Self::Strategy { ( @@ -545,7 +545,7 @@ impl Block { /// Fix `transaction` so it obeys more consensus rules. /// -/// Spends [`OutPoint`]s from `utxos`, and adds newly created outputs. +/// Spends [`transparent::OutPoint`]s from `utxos`, and adds newly created outputs. /// /// If the transaction can't be fixed, returns `None`. pub fn fix_generated_transaction( @@ -625,7 +625,7 @@ where } } -/// Find a valid [`OutPoint`] in `utxos` to spend in `transaction`. +/// Find a valid [`transparent::OutPoint`] in `utxos` to spend in `transaction`. /// /// Modifies `transaction` and updates `spend_restriction` if needed. /// diff --git a/zebra-chain/src/block/commitment.rs b/zebra-chain/src/block/commitment.rs index 620738a1d..f8a9fa12b 100644 --- a/zebra-chain/src/block/commitment.rs +++ b/zebra-chain/src/block/commitment.rs @@ -66,7 +66,7 @@ pub enum Commitment { /// need to verify the chain history root from `Canopy + 1 block` onwards, /// using a new history tree based on the `Canopy` activation block. /// - /// NU5 and later upgrades use the [`ChainHistoryBlockTxAuthCommitment`] + /// NU5 and later upgrades use the [`Commitment::ChainHistoryBlockTxAuthCommitment`] /// variant. /// /// TODO: this field is verified during contextual verification @@ -85,7 +85,7 @@ pub enum Commitment { /// This commitment supports the FlyClient protocol and non-malleable /// transaction IDs. See ZIP-221 and ZIP-244 for details. /// - /// See also the [`ChainHistoryRoot`] variant. + /// See also the [`Commitment::ChainHistoryRoot`] variant. /// /// TODO: this field is verified during contextual verification ChainHistoryBlockTxAuthCommitment(ChainHistoryBlockTxAuthCommitmentHash), diff --git a/zebra-chain/src/block/header.rs b/zebra-chain/src/block/header.rs index 171cce7de..c7a297b02 100644 --- a/zebra-chain/src/block/header.rs +++ b/zebra-chain/src/block/header.rs @@ -53,9 +53,9 @@ pub struct Header { /// Zcash blocks contain different kinds of commitments to their contents, /// depending on the network and height. /// - /// The interpretation of this field has been changed multiple times, without - /// incrementing the block [`version`]. Therefore, this field cannot be - /// parsed without the network and height. Use + /// The interpretation of this field has been changed multiple times, + /// without incrementing the block [`version`](Self::version). Therefore, + /// this field cannot be parsed without the network and height. Use /// [`Block::commitment`](super::Block::commitment) to get the parsed /// [`Commitment`](super::Commitment). pub commitment_bytes: [u8; 32], diff --git a/zebra-chain/src/block/merkle.rs b/zebra-chain/src/block/merkle.rs index 6a5f70a90..62152aa9c 100644 --- a/zebra-chain/src/block/merkle.rs +++ b/zebra-chain/src/block/merkle.rs @@ -47,7 +47,7 @@ use crate::transaction::{self, Transaction}; /// > 1 2 3 4 5 6 1 2 3 4 5 6 5 6 /// > ``` /// > -/// > for transaction lists [1,2,3,4,5,6] and [1,2,3,4,5,6,5,6] (where 5 and +/// > for transaction lists \[1,2,3,4,5,6\] and \[1,2,3,4,5,6,5,6\] (where 5 and /// > 6 are repeated) result in the same root hash A (because the hash of both /// > of (F) and (F,F) is C). /// > diff --git a/zebra-chain/src/history_tree.rs b/zebra-chain/src/history_tree.rs index 7b133edc3..de0e305f4 100644 --- a/zebra-chain/src/history_tree.rs +++ b/zebra-chain/src/history_tree.rs @@ -54,7 +54,7 @@ enum InnerHistoryTree { } /// History tree (Merkle mountain range) structure that contains information about -/// the block history, as specified in [ZIP-221][https://zips.z.cash/zip-0221]. +/// the block history, as specified in [ZIP-221](https://zips.z.cash/zip-0221). #[derive(Debug)] pub struct NonEmptyHistoryTree { network: Network, @@ -75,8 +75,8 @@ pub struct NonEmptyHistoryTree { impl NonEmptyHistoryTree { /// Recreate a [`HistoryTree`] from previously saved data. /// - /// The parameters must come from the values of [HistoryTree::size], - /// [HistoryTree::peaks] and [HistoryTree::current_height] of a HistoryTree. + /// The parameters must come from the values of [`NonEmptyHistoryTree::size`], + /// [`NonEmptyHistoryTree::peaks`] and [`NonEmptyHistoryTree::current_height`] of a HistoryTree. pub fn from_cache( network: Network, size: u32, diff --git a/zebra-chain/src/orchard/action.rs b/zebra-chain/src/orchard/action.rs index 9e1270d45..316ccfa10 100644 --- a/zebra-chain/src/orchard/action.rs +++ b/zebra-chain/src/orchard/action.rs @@ -91,12 +91,12 @@ impl ZcashDeserialize for Action { // https://zips.z.cash/protocol/protocol.pdf#concreteorchardkeyagreement // See [`keys::EphemeralPublicKey::zcash_deserialize`]. ephemeral_key: keys::EphemeralPublicKey::zcash_deserialize(&mut reader)?, - // Type is `Sym.C`, i.e. `𝔹^Y^{[N]}`, i.e. arbitrary-sized byte arrays + // Type is `Sym.C`, i.e. `𝔹^Y^{\[N\]}`, i.e. arbitrary-sized byte arrays // https://zips.z.cash/protocol/protocol.pdf#concretesym but fixed to // 580 bytes in https://zips.z.cash/protocol/protocol.pdf#outputencodingandconsensus // See [`note::EncryptedNote::zcash_deserialize`]. enc_ciphertext: note::EncryptedNote::zcash_deserialize(&mut reader)?, - // Type is `Sym.C`, i.e. `𝔹^Y^{[N]}`, i.e. arbitrary-sized byte arrays + // Type is `Sym.C`, i.e. `𝔹^Y^{\[N\]}`, i.e. arbitrary-sized byte arrays // https://zips.z.cash/protocol/protocol.pdf#concretesym but fixed to // 80 bytes in https://zips.z.cash/protocol/protocol.pdf#outputencodingandconsensus // See [`note::WrappedNoteKey::zcash_deserialize`]. diff --git a/zebra-chain/src/orchard/commitment.rs b/zebra-chain/src/orchard/commitment.rs index 2d33d4468..64c523061 100644 --- a/zebra-chain/src/orchard/commitment.rs +++ b/zebra-chain/src/orchard/commitment.rs @@ -42,7 +42,7 @@ where pub struct CommitmentRandomness(pallas::Scalar); impl From for CommitmentRandomness { - /// rcm = ToScalar^Orchard((PRF^expand_rseed ([5])) + /// rcm = ToScalar^Orchard((PRF^expand_rseed (\[5\])) /// /// fn from(rseed: SeedRandomness) -> Self { diff --git a/zebra-chain/src/orchard/keys.rs b/zebra-chain/src/orchard/keys.rs index 8124983fe..e0601b6f0 100644 --- a/zebra-chain/src/orchard/keys.rs +++ b/zebra-chain/src/orchard/keys.rs @@ -253,7 +253,7 @@ impl From for SpendAuthorizingKey { /// Invokes Blake2b-512 as _PRF^expand_, t=6, to derive a /// `SpendAuthorizingKey` from a `SpendingKey`. /// - /// ask := ToScalar^Orchard(PRF^expand(sk, [6])) + /// ask := ToScalar^Orchard(PRF^expand(sk, \[6\])) /// /// /// @@ -380,7 +380,7 @@ impl From<[u8; 32]> for NullifierDerivingKey { } impl From for NullifierDerivingKey { - /// nk = ToBase^Orchard(PRF^expand_sk ([7])) + /// nk = ToBase^Orchard(PRF^expand_sk (\[7\])) /// /// fn from(sk: SpendingKey) -> Self { @@ -429,7 +429,7 @@ impl fmt::Debug for IvkCommitRandomness { impl Eq for IvkCommitRandomness {} impl From for IvkCommitRandomness { - /// rivk = ToScalar^Orchard(PRF^expand_sk ([8])) + /// rivk = ToScalar^Orchard(PRF^expand_sk (\[8\])) /// /// fn from(sk: SpendingKey) -> Self { @@ -962,7 +962,7 @@ impl From<(IncomingViewingKey, Diversifier)> for TransmissionKey { /// This includes _KA^Orchard.DerivePublic(ivk, G_d)_, which is just a /// scalar mult _\[ivk\]G_d_. /// - /// KA^Orchard.DerivePublic(sk, B) := [sk] B + /// KA^Orchard.DerivePublic(sk, B) := \[sk\] B /// /// /// diff --git a/zebra-chain/src/orchard/note.rs b/zebra-chain/src/orchard/note.rs index 544ae0c58..3a4787063 100644 --- a/zebra-chain/src/orchard/note.rs +++ b/zebra-chain/src/orchard/note.rs @@ -83,7 +83,7 @@ impl From for [u8; 32] { } impl From for Psi { - /// rcm = ToScalar^Orchard((PRF^expand_rseed ([9])) + /// rcm = ToScalar^Orchard((PRF^expand_rseed (\[9\])) /// /// fn from(rseed: SeedRandomness) -> Self { diff --git a/zebra-chain/src/orchard/note/nullifiers.rs b/zebra-chain/src/orchard/note/nullifiers.rs index 33a506bdd..5f05b5366 100644 --- a/zebra-chain/src/orchard/note/nullifiers.rs +++ b/zebra-chain/src/orchard/note/nullifiers.rs @@ -32,7 +32,7 @@ fn poseidon_hash(_x: pallas::Base, _y: pallas::Base) -> pallas::Base { /// PRF^nfOrchard: F_𝑞P × F_𝑞P → F_𝑞P /// /// Instantiated using the PoseidonHash hash function defined in [§5.4.1.10 -/// ‘PoseidonHash Function’][poseidon]: +/// ‘PoseidonHash Function’][poseidonhash]: /// /// PRF^nfOrchard(nk*, ρ*) := PoseidonHash(nk*, ρ*) /// diff --git a/zebra-chain/src/orchard/shielded_data.rs b/zebra-chain/src/orchard/shielded_data.rs index 7a2fb5fe1..3ec59dd59 100644 --- a/zebra-chain/src/orchard/shielded_data.rs +++ b/zebra-chain/src/orchard/shielded_data.rs @@ -162,7 +162,7 @@ impl AuthorizedAction { /// Actions are 5 * 32 + 580 + 80 bytes so the total size of each Action is 820 bytes. /// [7.5 Action Description Encoding and Consensus][ps] /// -/// [ps] +/// [ps]: pub const ACTION_SIZE: u64 = 5 * 32 + 580 + 80; /// The size of a single Signature @@ -170,7 +170,7 @@ pub const ACTION_SIZE: u64 = 5 * 32 + 580 + 80; /// Each Signature is 64 bytes. /// [7.1 Transaction Encoding and Consensus][ps] /// -/// [ps] +/// [ps]: pub const SPEND_AUTH_SIG_SIZE: u64 = 64; /// The size of a single AuthorizedAction diff --git a/zebra-chain/src/orchard/sinsemilla.rs b/zebra-chain/src/orchard/sinsemilla.rs index 6928a20d8..df4b61638 100644 --- a/zebra-chain/src/orchard/sinsemilla.rs +++ b/zebra-chain/src/orchard/sinsemilla.rs @@ -106,7 +106,7 @@ fn incomplete_addition( /// the Sinsemilla hash for the Orchard incremental Merkle tree (§ 5.4.1.3 /// ‘MerkleCRH^Orchard Hash Function’). /// -/// SinsemillaHashToPoint(𝐷: B^Y^[N] , 𝑀 : B ^[{0 .. 𝑘·𝑐}] ) → P ∪ {⊥} +/// SinsemillaHashToPoint(𝐷: B^Y^\[N\] , 𝑀 : B ^[{0 .. 𝑘·𝑐}] ) → P ∪ {⊥} /// /// /// @@ -147,7 +147,7 @@ pub fn sinsemilla_hash_to_point(D: &[u8], M: &BitVec) -> Option /// @@ -165,7 +165,7 @@ pub fn sinsemilla_hash(D: &[u8], M: &BitVec) -> Option { /// hash, and adding a randomized point on the Pallas curve (with complete /// addition, vs incomplete addition as used in [`sinsemilla_hash_to_point`]). /// -/// SinsemillaCommit_r(D, M) := SinsemillaHashToPoint(D || "-M", M) + [r]GroupHash^P(D || "-r", "") +/// SinsemillaCommit_r(D, M) := SinsemillaHashToPoint(D || "-M", M) + \[r\]GroupHash^P(D || "-r", "") /// /// #[allow(non_snake_case)] diff --git a/zebra-chain/src/orchard/tree.rs b/zebra-chain/src/orchard/tree.rs index 06eb48e74..42ad806c9 100644 --- a/zebra-chain/src/orchard/tree.rs +++ b/zebra-chain/src/orchard/tree.rs @@ -287,8 +287,9 @@ pub struct NoteCommitmentTree { /// serialized with the tree). This is particularly important since we decided /// to instantiate the trees from the genesis block, for simplicity. /// - /// We use a [`RwLock`] for this cache, because it is only written once per tree update. - /// Each tree has its own cached root, a new lock is created for each clone. + /// We use a [`RwLock`](std::sync::RwLock) for this cache, because it is + /// only written once per tree update. Each tree has its own cached root, a + /// new lock is created for each clone. cached_root: std::sync::RwLock>, } diff --git a/zebra-chain/src/parameters/arbitrary.rs b/zebra-chain/src/parameters/arbitrary.rs index 966dfe4a3..12440946d 100644 --- a/zebra-chain/src/parameters/arbitrary.rs +++ b/zebra-chain/src/parameters/arbitrary.rs @@ -5,7 +5,7 @@ use proptest::prelude::*; use super::NetworkUpgrade; impl NetworkUpgrade { - /// Generates network upgrades with [`BranchId`]s + /// Generates network upgrades. pub fn branch_id_strategy() -> BoxedStrategy { prop_oneof![ Just(NetworkUpgrade::Overwinter), diff --git a/zebra-chain/src/parameters/network_upgrade.rs b/zebra-chain/src/parameters/network_upgrade.rs index 1a9178047..3316ba42c 100644 --- a/zebra-chain/src/parameters/network_upgrade.rs +++ b/zebra-chain/src/parameters/network_upgrade.rs @@ -305,7 +305,8 @@ impl NetworkUpgrade { /// Returns `true` if `height` is the activation height of any network upgrade /// on `network`. /// - /// Use [`activation_height`] to get the specific network upgrade. + /// Use [`NetworkUpgrade::activation_height`] to get the specific network + /// upgrade. pub fn is_activation_height(network: Network, height: block::Height) -> bool { NetworkUpgrade::activation_list(network).contains_key(&height) } @@ -331,8 +332,8 @@ impl NetworkUpgrade { /// Returns the target block spacing for the network upgrade. /// - /// Based on `PRE_BLOSSOM_POW_TARGET_SPACING` and - /// `POST_BLOSSOM_POW_TARGET_SPACING` from the Zcash specification. + /// Based on [`PRE_BLOSSOM_POW_TARGET_SPACING`] and + /// [`POST_BLOSSOM_POW_TARGET_SPACING`] from the Zcash specification. pub fn target_spacing(&self) -> Duration { let spacing_seconds = match self { Genesis | BeforeOverwinter | Overwinter | Sapling => PRE_BLOSSOM_POW_TARGET_SPACING, @@ -344,7 +345,7 @@ impl NetworkUpgrade { /// Returns the target block spacing for `network` and `height`. /// - /// See [`target_spacing()`] for details. + /// See [`NetworkUpgrade::target_spacing`] for details. pub fn target_spacing_for_height(network: Network, height: block::Height) -> Duration { NetworkUpgrade::current(network, height).target_spacing() } @@ -425,7 +426,7 @@ impl NetworkUpgrade { /// Returns the averaging window timespan for `network` and `height`. /// - /// See [`averaging_window_timespan()`] for details. + /// See [`NetworkUpgrade::averaging_window_timespan`] for details. pub fn averaging_window_timespan_for_height( network: Network, height: block::Height, diff --git a/zebra-chain/src/primitives/redpallas/batch.rs b/zebra-chain/src/primitives/redpallas/batch.rs index d048272ca..a8bb91759 100644 --- a/zebra-chain/src/primitives/redpallas/batch.rs +++ b/zebra-chain/src/primitives/redpallas/batch.rs @@ -132,11 +132,10 @@ impl<'msg, M: AsRef<[u8]>> From<(VerificationKeyBytes, Signature Result<(), Error> { match self.inner { Inner::Binding { vk_bytes, sig, c } => VerificationKey::::try_from(vk_bytes) diff --git a/zebra-chain/src/sapling/commitment.rs b/zebra-chain/src/sapling/commitment.rs index ea69a0fe0..0f33cab1a 100644 --- a/zebra-chain/src/sapling/commitment.rs +++ b/zebra-chain/src/sapling/commitment.rs @@ -312,11 +312,11 @@ impl TryFrom for NotSmallOrderValueCommitment { /// /// # Consensus /// - /// > cv and rk [MUST NOT be of small order][1], i.e. [h_J]cv MUST NOT be 𝒪_J - /// > and [h_J]rk MUST NOT be 𝒪_J. + /// > cv and rk [MUST NOT be of small order][1], i.e. \[h_J\]cv MUST NOT be 𝒪_J + /// > and \[h_J\]rk MUST NOT be 𝒪_J. /// - /// > cv and epk [MUST NOT be of small order][2], i.e. [h_J]cv MUST NOT be 𝒪_J - /// > and [ℎ_J]epk MUST NOT be 𝒪_J. + /// > cv and epk [MUST NOT be of small order][2], i.e. \[h_J\]cv MUST NOT be 𝒪_J + /// > and \[ℎ_J\]epk MUST NOT be 𝒪_J. /// /// [1]: https://zips.z.cash/protocol/protocol.pdf#spenddesc /// [2]: https://zips.z.cash/protocol/protocol.pdf#outputdesc diff --git a/zebra-chain/src/sapling/commitment/pedersen_hashes.rs b/zebra-chain/src/sapling/commitment/pedersen_hashes.rs index 4f75c3536..5e41854e8 100644 --- a/zebra-chain/src/sapling/commitment/pedersen_hashes.rs +++ b/zebra-chain/src/sapling/commitment/pedersen_hashes.rs @@ -104,7 +104,7 @@ pub fn pedersen_hash(domain: [u8; 8], M: &BitVec) -> jubjub::Fq { /// commitment tree. It takes as input a Pedersen commitment P, and hashes it /// with another input x. /// -/// MixingPedersenHash(P, x) := P + [x]FindGroupHash^J^(r)("Zcash_J_", "") +/// MixingPedersenHash(P, x) := P + \[x\]FindGroupHash^J^(r)("Zcash_J_", "") /// /// #[allow(non_snake_case)] @@ -118,7 +118,7 @@ pub fn mixing_pedersen_hash(P: jubjub::ExtendedPoint, x: jubjub::Fr) -> jubjub:: /// construction, and adding a randomized point on the Jubjub curve. /// /// WindowedPedersenCommit_r (s) := \ -/// PedersenHashToPoint("Zcash_PH", s) + [r]FindGroupHash^J^(r)("Zcash_PH", "r") +/// PedersenHashToPoint("Zcash_PH", s) + \[r\]FindGroupHash^J^(r)("Zcash_PH", "r") /// /// pub fn windowed_pedersen_commitment(r: jubjub::Fr, s: &BitVec) -> jubjub::ExtendedPoint { diff --git a/zebra-chain/src/sapling/keys.rs b/zebra-chain/src/sapling/keys.rs index b0737d2af..897dd309d 100644 --- a/zebra-chain/src/sapling/keys.rs +++ b/zebra-chain/src/sapling/keys.rs @@ -1055,7 +1055,7 @@ impl TryFrom<[u8; 32]> for EphemeralPublicKey { /// # Consensus /// /// > Check that a Output description's cv and epk are not of small order, - /// > i.e. [h_J]cv MUST NOT be 𝒪_J and [h_J]epk MUST NOT be 𝒪_J. + /// > i.e. \[h_J\]cv MUST NOT be 𝒪_J and \[h_J\]epk MUST NOT be 𝒪_J. /// /// [1]: https://zips.z.cash/protocol/protocol.pdf#outputdesc fn try_from(bytes: [u8; 32]) -> Result { @@ -1106,7 +1106,7 @@ impl TryFrom> for ValidatingKey { /// # Consensus /// /// > Check that a Spend description's cv and rk are not of small order, - /// > i.e. [h_J]cv MUST NOT be 𝒪_J and [h_J]rk MUST NOT be 𝒪_J. + /// > i.e. \[h_J\]cv MUST NOT be 𝒪_J and \[h_J\]rk MUST NOT be 𝒪_J. /// /// [1]: https://zips.z.cash/protocol/protocol.pdf#spenddesc fn try_from(key: redjubjub::VerificationKey) -> Result { diff --git a/zebra-chain/src/sapling/output.rs b/zebra-chain/src/sapling/output.rs index 688605f97..74dfa7eef 100644 --- a/zebra-chain/src/sapling/output.rs +++ b/zebra-chain/src/sapling/output.rs @@ -158,12 +158,12 @@ impl ZcashDeserialize for OutputInTransactionV4 { // https://zips.z.cash/protocol/protocol.pdf#concretesaplingkeyagreement // See [`keys::EphemeralPublicKey::zcash_deserialize`]. ephemeral_key: keys::EphemeralPublicKey::zcash_deserialize(&mut reader)?, - // Type is `Sym.C`, i.e. `B^Y^{[N]}`, i.e. arbitrary-sized byte arrays + // Type is `Sym.C`, i.e. `B^Y^{\[N\]}`, i.e. arbitrary-sized byte arrays // https://zips.z.cash/protocol/protocol.pdf#concretesym but fixed to // 580 bytes in https://zips.z.cash/protocol/protocol.pdf#outputencodingandconsensus // See [`note::EncryptedNote::zcash_deserialize`]. enc_ciphertext: note::EncryptedNote::zcash_deserialize(&mut reader)?, - // Type is `Sym.C`, i.e. `B^Y^{[N]}`, i.e. arbitrary-sized byte arrays. + // Type is `Sym.C`, i.e. `B^Y^{\[N\]}`, i.e. arbitrary-sized byte arrays. // https://zips.z.cash/protocol/protocol.pdf#concretesym but fixed to // 80 bytes in https://zips.z.cash/protocol/protocol.pdf#outputencodingandconsensus // See [`note::WrappedNoteKey::zcash_deserialize`]. @@ -221,12 +221,12 @@ impl ZcashDeserialize for OutputPrefixInTransactionV5 { // https://zips.z.cash/protocol/protocol.pdf#concretesaplingkeyagreement // See [`keys::EphemeralPublicKey::zcash_deserialize`]. ephemeral_key: keys::EphemeralPublicKey::zcash_deserialize(&mut reader)?, - // Type is `Sym.C`, i.e. `B^Y^{[N]}`, i.e. arbitrary-sized byte arrays + // Type is `Sym.C`, i.e. `B^Y^{\[N\]}`, i.e. arbitrary-sized byte arrays // https://zips.z.cash/protocol/protocol.pdf#concretesym but fixed to // 580 bytes in https://zips.z.cash/protocol/protocol.pdf#outputencodingandconsensus // See [`note::EncryptedNote::zcash_deserialize`]. enc_ciphertext: note::EncryptedNote::zcash_deserialize(&mut reader)?, - // Type is `Sym.C`, i.e. `B^Y^{[N]}`, i.e. arbitrary-sized byte arrays. + // Type is `Sym.C`, i.e. `B^Y^{\[N\]}`, i.e. arbitrary-sized byte arrays. // https://zips.z.cash/protocol/protocol.pdf#concretesym but fixed to // 80 bytes in https://zips.z.cash/protocol/protocol.pdf#outputencodingandconsensus // See [`note::WrappedNoteKey::zcash_deserialize`]. @@ -242,6 +242,7 @@ impl ZcashDeserialize for OutputPrefixInTransactionV5 { pub(crate) const OUTPUT_PREFIX_SIZE: u64 = 32 + 32 + 32 + 580 + 80; /// An output contains: a 32 byte cv, a 32 byte cmu, a 32 byte ephemeral key /// a 580 byte encCiphertext, an 80 byte outCiphertext, and a 192 byte zkproof +/// /// [ps]: https://zips.z.cash/protocol/protocol.pdf#outputencoding pub(crate) const OUTPUT_SIZE: u64 = OUTPUT_PREFIX_SIZE + 192; diff --git a/zebra-chain/src/sapling/shielded_data.rs b/zebra-chain/src/sapling/shielded_data.rs index ff337da31..3ea6f3dfc 100644 --- a/zebra-chain/src/sapling/shielded_data.rs +++ b/zebra-chain/src/sapling/shielded_data.rs @@ -149,7 +149,7 @@ where /// transaction. /// /// Use the [`ShieldedData::outputs`] method to get an iterator over the - /// [`Outputs`]s in this `TransferData`. + /// [`Output`]s in this `TransferData`. maybe_outputs: Vec, }, @@ -162,7 +162,7 @@ where /// At least one output, in the order they appear in the transaction. /// /// Use the [`ShieldedData::outputs`] method to get an iterator over the - /// [`Outputs`]s in this `TransferData`. + /// [`Output`]s in this `TransferData`. outputs: AtLeastOne, }, } diff --git a/zebra-chain/src/sapling/spend.rs b/zebra-chain/src/sapling/spend.rs index cd3ab7289..7a9c0f78d 100644 --- a/zebra-chain/src/sapling/spend.rs +++ b/zebra-chain/src/sapling/spend.rs @@ -181,8 +181,8 @@ impl ZcashDeserialize for Spend { /// /// /// This rule is also implemented in - /// [`zebra_state::service::check::anchor`] and - /// [`zebra_chain::transaction::serialize`]. + /// `zebra_state::service::check::anchors` and + /// [`crate::transaction::serialize`]. /// /// The "anchor encoding for v4 transactions" is implemented here. fn zcash_deserialize(mut reader: R) -> Result { diff --git a/zebra-chain/src/sapling/tree.rs b/zebra-chain/src/sapling/tree.rs index eab6bc7e6..b0cfb302b 100644 --- a/zebra-chain/src/sapling/tree.rs +++ b/zebra-chain/src/sapling/tree.rs @@ -292,7 +292,7 @@ pub struct NoteCommitmentTree { /// tree). This is particularly important since we decided to instantiate /// the trees from the genesis block, for simplicity. /// - /// We use a [`RwLock`] for this cache, because it is only written once per + /// We use a [`RwLock`](std::sync::RwLock) for this cache, because it is only written once per /// tree update. Each tree has its own cached root, a new lock is created /// for each clone. cached_root: std::sync::RwLock>, @@ -376,7 +376,8 @@ impl NoteCommitmentTree { } impl Clone for NoteCommitmentTree { - /// Clones the inner tree, and creates a new `RwLock` with the cloned root data. + /// Clones the inner tree, and creates a new [`RwLock`](std::sync::RwLock) + /// with the cloned root data. fn clone(&self) -> Self { let cached_root = *self .cached_root diff --git a/zebra-chain/src/serialization/arbitrary.rs b/zebra-chain/src/serialization/arbitrary.rs index 2c84ad909..953e8643c 100644 --- a/zebra-chain/src/serialization/arbitrary.rs +++ b/zebra-chain/src/serialization/arbitrary.rs @@ -35,7 +35,7 @@ impl Arbitrary for DateTime32 { /// /// Zebra uses these times internally, typically via [`Utc::now`]. /// -/// Some parts of the Zcash network protocol ([`Version`] messages) also use times +/// Some parts of the Zcash network protocol (`Version` messages) also use times /// with an 8-byte seconds value. Unlike this function, they have zero /// nanoseconds values. (So they never have `chrono` leap seconds.) pub fn datetime_full() -> impl Strategy> { @@ -53,7 +53,7 @@ pub fn datetime_full() -> impl Strategy> { /// The nanoseconds value is always zero. /// /// The Zcash protocol typically uses 4-byte seconds values, except for the -/// [`Version`] message. +/// `Version` message. /// /// TODO: replace this strategy with `any::()`. pub fn datetime_u32() -> impl Strategy> { diff --git a/zebra-chain/src/sprout/joinsplit.rs b/zebra-chain/src/sprout/joinsplit.rs index 4d70884e7..cb8b04a72 100644 --- a/zebra-chain/src/sprout/joinsplit.rs +++ b/zebra-chain/src/sprout/joinsplit.rs @@ -104,7 +104,9 @@ impl JoinSplit

{ /// /// /// - /// See [`Transaction::sprout_value_balance`] for details. + /// See [`sprout_value_balance`][svb] for details. + /// + /// [svb]: crate::transaction::Transaction::sprout_value_balance pub fn value_balance(&self) -> Amount { let vpub_new = self .vpub_new @@ -161,7 +163,7 @@ impl ZcashDeserialize for JoinSplit

{ // The type is validated when validating the proof, see // [`groth16::Item::try_from`]. In #3179 we plan to validate here instead. zkproof: P::zcash_deserialize(&mut reader)?, - // Types are `Sym.C`, i.e. `B^Y^{[N]}`, i.e. arbitrary-sized byte arrays + // Types are `Sym.C`, i.e. `B^Y^{\[N\]}`, i.e. arbitrary-sized byte arrays // https://zips.z.cash/protocol/protocol.pdf#concretesym but fixed to // 601 bytes in https://zips.z.cash/protocol/protocol.pdf#joinsplitencodingandconsensus // See [`note::EncryptedNote::zcash_deserialize`]. diff --git a/zebra-chain/src/sprout/tests/test_vectors.rs b/zebra-chain/src/sprout/tests/test_vectors.rs index ef1595dde..39c48f916 100644 --- a/zebra-chain/src/sprout/tests/test_vectors.rs +++ b/zebra-chain/src/sprout/tests/test_vectors.rs @@ -78,7 +78,7 @@ pub const ROOTS: [&str; 16] = [ /// Empty (unused) Sprout note commitment tree leaf node. /// -/// Uncommitted^Sprout = [0]^(l^Sprout_Merkle). +/// Uncommitted^Sprout = \[0\]^(l^Sprout_Merkle). /// /// pub const EMPTY_LEAF: [u8; 32] = [0; 32]; diff --git a/zebra-chain/src/sprout/tree.rs b/zebra-chain/src/sprout/tree.rs index 60cd5904a..ad99f9f96 100644 --- a/zebra-chain/src/sprout/tree.rs +++ b/zebra-chain/src/sprout/tree.rs @@ -230,8 +230,9 @@ pub struct NoteCommitmentTree { /// the tree). This is particularly important since we decided to /// instantiate the trees from the genesis block, for simplicity. /// - /// We use a [`RwLock`] for this cache, because it is only written once per tree update. - /// Each tree has its own cached root, a new lock is created for each clone. + /// We use a [`RwLock`](std::sync::RwLock) for this cache, because it is + /// only written once per tree update. Each tree has its own cached root, a + /// new lock is created for each clone. cached_root: std::sync::RwLock>, } @@ -292,7 +293,7 @@ impl NoteCommitmentTree { /// Returns an as-yet unused leaf node value of a Sprout note commitment tree. /// - /// Uncommitted^Sprout = [0]^(l^[Sprout_Merkle]). + /// Uncommitted^Sprout = \[0\]^(l^[Sprout_Merkle]). /// /// [Sprout_Merkle]: https://zips.z.cash/protocol/protocol.pdf#constants pub fn uncommitted() -> [u8; 32] { diff --git a/zebra-chain/src/transaction.rs b/zebra-chain/src/transaction.rs index e9afa82ed..f2b6db03a 100644 --- a/zebra-chain/src/transaction.rs +++ b/zebra-chain/src/transaction.rs @@ -230,7 +230,7 @@ impl Transaction { /// Does this transaction have shielded inputs? /// - /// See [`has_transparent_or_shielded_inputs`] for details. + /// See [`Self::has_transparent_or_shielded_inputs`] for details. pub fn has_shielded_inputs(&self) -> bool { self.joinsplit_count() > 0 || self.sapling_spends_per_anchor().count() > 0 @@ -248,7 +248,7 @@ impl Transaction { /// Does this transaction have shielded outputs? /// - /// See [`has_transparent_or_shielded_outputs`] for details. + /// See [`Self::has_transparent_or_shielded_outputs`] for details. pub fn has_shielded_outputs(&self) -> bool { self.joinsplit_count() > 0 || self.sapling_outputs().count() > 0 @@ -1197,11 +1197,13 @@ impl Transaction { } /// Return a list of sprout value balances, - /// the changes in the transaction value pool due to each sprout [`JoinSplit`]. + /// the changes in the transaction value pool due to each sprout `JoinSplit`. /// /// Each value balance is the sprout `vpub_new` field, minus the `vpub_old` field. /// - /// See `sprout_value_balance` for details. + /// See [`sprout_value_balance`][svb] for details. + /// + /// [svb]: crate::transaction::Transaction::sprout_value_balance fn sprout_joinsplit_value_balances( &self, ) -> impl Iterator> + '_ { @@ -1238,7 +1240,7 @@ impl Transaction { } /// Return the sprout value balance, - /// the change in the transaction value pool due to sprout [`JoinSplit`]s. + /// the change in the transaction value pool due to sprout `JoinSplit`s. /// /// The sum of all sprout `vpub_new` fields, minus the sum of all `vpub_old` fields. /// @@ -1319,8 +1321,8 @@ impl Transaction { } } - /// Return the orchard value balance, - /// the change in the transaction value pool due to orchard [`Action`]s. + /// Return the orchard value balance, the change in the transaction value + /// pool due to [`orchard::Action`]s. /// /// Returns the `valueBalanceOrchard` field in this transaction. /// diff --git a/zebra-chain/src/transaction/arbitrary.rs b/zebra-chain/src/transaction/arbitrary.rs index c326e9a21..32b93248c 100644 --- a/zebra-chain/src/transaction/arbitrary.rs +++ b/zebra-chain/src/transaction/arbitrary.rs @@ -278,7 +278,8 @@ impl Transaction { /// /// # Panics /// - /// If any spent [`Output`] is missing from `outpoints`. + /// If any spent [`transparent::Output`] is missing from + /// [`transparent::OutPoint`]s. // // TODO: take some extra arbitrary flags, which select between zero and non-zero // remaining value in each chain value pool @@ -420,7 +421,8 @@ impl Transaction { /// /// # Panics /// - /// If any spent [`Output`] is missing from `outpoints`. + /// If any spent [`transparent::Output`] is missing from + /// [`transparent::OutPoint`]s. // // TODO: split this method up, after we've implemented chain value balance adjustments // diff --git a/zebra-chain/src/transaction/hash.rs b/zebra-chain/src/transaction/hash.rs index 63f9837a7..68a0fb786 100644 --- a/zebra-chain/src/transaction/hash.rs +++ b/zebra-chain/src/transaction/hash.rs @@ -1,29 +1,32 @@ //! Transaction identifiers for Zcash. //! //! Zcash has two different transaction identifiers, with different widths: -//! * [`Hash`]: a 32-byte transaction ID, which uniquely identifies mined transactions +//! * [`struct@Hash`]: a 32-byte transaction ID, which uniquely identifies mined transactions //! (transactions that have been committed to the blockchain in blocks), and //! * [`WtxId`]: a 64-byte witnessed transaction ID, which uniquely identifies unmined transactions //! (transactions that are sent by wallets or stored in node mempools). //! //! Transaction version 5 uses both these unique identifiers: -//! * [`Hash`] uniquely identifies the effects of a v5 transaction (spends and outputs), +//! * [`struct@Hash`] uniquely identifies the effects of a v5 transaction (spends and outputs), //! so it uniquely identifies the transaction's data after it has been mined into a block; //! * [`WtxId`] uniquely identifies the effects and authorizing data of a v5 transaction //! (signatures, proofs, and scripts), so it uniquely identifies the transaction's data //! outside a block. (For example, transactions produced by Zcash wallets, or in node mempools.) //! -//! Transaction versions 1-4 are uniquely identified by legacy [`Hash`] transaction IDs, +//! Transaction versions 1-4 are uniquely identified by legacy [`struct@Hash`] transaction IDs, //! whether they have been mined or not. So Zebra, and the Zcash network protocol, //! don't use witnessed transaction IDs for them. //! //! There is no unique identifier that only covers the effects of a v1-4 transaction, //! so their legacy IDs are malleable, if submitted with different authorizing data. -//! So the same spends and outputs can have a completely different [`Hash`]. +//! So the same spends and outputs can have a completely different [`struct@Hash`]. //! -//! Zebra's [`UnminedTxId`] and [`UnminedTx`] enums provide the correct unique ID for -//! unmined transactions. They can be used to handle transactions regardless of version, -//! and get the [`WtxId`] or [`Hash`] when required. +//! Zebra's [`UnminedTxId`][1] and [`UnminedTx`][1] enums provide the correct +//! unique ID for unmined transactions. They can be used to handle transactions +//! regardless of version, and get the [`WtxId`] or [`struct@Hash`] when +//! required. +//! +//! [1]: crate::transaction::UnminedTx use std::{ convert::{TryFrom, TryInto}, diff --git a/zebra-chain/src/transaction/joinsplit.rs b/zebra-chain/src/transaction/joinsplit.rs index 9882ce8aa..0735bb6e3 100644 --- a/zebra-chain/src/transaction/joinsplit.rs +++ b/zebra-chain/src/transaction/joinsplit.rs @@ -85,7 +85,9 @@ impl JoinSplitData

{ /// /// /// - /// See [`Transaction::sprout_value_balance`] for details. + /// See [`sprout_value_balance`][svb] for details. + /// + /// [svb]: crate::transaction::Transaction::sprout_value_balance pub fn value_balance(&self) -> Result, amount::Error> { self.joinsplit_value_balances().sum() } @@ -93,14 +95,16 @@ impl JoinSplitData

{ /// Return a list of sprout value balances, /// the changes in the transaction value pool due to each sprout [`JoinSplit`]. /// - /// See [`Transaction::sprout_value_balance`] for details. + /// See [`sprout_value_balance`][svb] for details. + /// + /// [svb]: crate::transaction::Transaction::sprout_value_balance pub fn joinsplit_value_balances( &self, ) -> Box> + '_> { Box::new(self.joinsplits().map(JoinSplit::value_balance)) } - /// Collect the Sprout note commitments for this transaction, if it contains [`Output`]s, + /// Collect the Sprout note commitments for this transaction, if it contains `Output`s, /// in the order they appear in the transaction. pub fn note_commitments(&self) -> impl Iterator { self.joinsplits() diff --git a/zebra-chain/src/transaction/unmined.rs b/zebra-chain/src/transaction/unmined.rs index 071902ae9..eae465c4f 100644 --- a/zebra-chain/src/transaction/unmined.rs +++ b/zebra-chain/src/transaction/unmined.rs @@ -1,16 +1,19 @@ //! Unmined Zcash transaction identifiers and transactions. //! -//! Transaction version 5 is uniquely identified by [`WtxId`] when unmined, -//! and [`Hash`] in the blockchain. The effects of a v5 transaction (spends and outputs) -//! are uniquely identified by the same [`Hash`] in both cases. +//! Transaction version 5 is uniquely identified by [`WtxId`] when unmined, and +//! [`struct@Hash`] in the blockchain. The effects of a v5 transaction +//! (spends and outputs) are uniquely identified by the same +//! [`struct@Hash`] in both cases. //! -//! Transaction versions 1-4 are uniquely identified by legacy [`Hash`] transaction IDs, -//! whether they have been mined or not. So Zebra, and the Zcash network protocol, -//! don't use witnessed transaction IDs for them. +//! Transaction versions 1-4 are uniquely identified by legacy +//! [`struct@Hash`] transaction IDs, whether they have been mined or not. +//! So Zebra, and the Zcash network protocol, don't use witnessed transaction +//! IDs for them. //! -//! Zebra's [`UnminedTxId`] and [`UnminedTx`] enums provide the correct unique ID for -//! unmined transactions. They can be used to handle transactions regardless of version, -//! and get the [`WtxId`] or [`Hash`] when required. +//! Zebra's [`UnminedTxId`] and [`UnminedTx`] enums provide the correct unique +//! ID for unmined transactions. They can be used to handle transactions +//! regardless of version, and get the [`WtxId`] or [`struct@Hash`] when +//! required. use std::{fmt, sync::Arc}; @@ -68,14 +71,14 @@ pub enum UnminedTxId { /// /// Used to uniquely identify unmined version 1-4 transactions. /// (After v1-4 transactions are mined, they can be uniquely identified - /// using the same [`transaction::Hash`].) + /// using the same [`struct@Hash`].) Legacy(Hash), /// A witnessed unmined transaction identifier. /// /// Used to uniquely identify unmined version 5 transactions. /// (After v5 transactions are mined, they can be uniquely identified - /// using only the [`transaction::Hash`] in their `WtxId.id`.) + /// using only the [`struct@Hash`] in their `WtxId.id`.) /// /// For more details, see [`WtxId`]. Witnessed(WtxId), @@ -125,12 +128,13 @@ impl fmt::Display for UnminedTxId { } impl UnminedTxId { - /// Create a new `UnminedTxId` using a v1-v4 legacy transaction ID. + /// Create a new [`UnminedTxId`] using a v1-v4 legacy transaction ID. /// /// # Correctness /// /// This method must only be used for v1-v4 transaction IDs. - /// [`Hash`] does not uniquely identify unmined v5 transactions. + /// [`struct@Hash`] does not uniquely identify unmined v5 + /// transactions. pub fn from_legacy_id(legacy_tx_id: Hash) -> UnminedTxId { Legacy(legacy_tx_id) } @@ -154,7 +158,7 @@ impl UnminedTxId { /// Returns a mutable reference to the unique ID /// that will be used if this transaction gets mined into a block. /// - /// See [mined_id] for details. + /// See [`Self::mined_id`] for details. #[cfg(any(test, feature = "proptest-impl"))] pub fn mined_id_mut(&mut self) -> &mut Hash { match self { diff --git a/zebra-chain/src/transparent.rs b/zebra-chain/src/transparent.rs index 2a970f90e..0ac6054b1 100644 --- a/zebra-chain/src/transparent.rs +++ b/zebra-chain/src/transparent.rs @@ -100,7 +100,8 @@ pub struct OutPoint { /// /// # Correctness /// - /// Consensus-critical serialization uses [`ZcashSerialize`]. + /// Consensus-critical serialization uses + /// [`ZcashSerialize`](crate::serialization::ZcashSerialize). /// [`serde`]-based hex serialization must only be used for testing. #[cfg_attr(any(test, feature = "proptest-impl"), serde(with = "hex"))] pub hash: transaction::Hash, @@ -111,7 +112,7 @@ pub struct OutPoint { } impl OutPoint { - /// Returns a new OutPoint from an in-memory output `index`. + /// Returns a new [`OutPoint`] from an in-memory output `index`. /// /// # Panics /// @@ -197,8 +198,8 @@ impl Input { } } - /// If this is a `PrevOut` input, returns this input's outpoint. - /// Otherwise, returns `None`. + /// If this is a [`Input::PrevOut`] input, returns this input's + /// [`OutPoint`]. Otherwise, returns `None`. pub fn outpoint(&self) -> Option { if let Input::PrevOut { outpoint, .. } = self { Some(*outpoint) @@ -207,9 +208,9 @@ impl Input { } } - /// Set this input's outpoint. + /// Set this input's [`OutPoint`]. /// - /// Should only be called on `PrevOut` inputs. + /// Should only be called on [`Input::PrevOut`] inputs. /// /// # Panics /// @@ -226,12 +227,12 @@ impl Input { } } - /// Get the value spent by this input, by looking up its [`Outpoint`] in `outputs`. - /// See `value` for details. + /// Get the value spent by this input, by looking up its [`OutPoint`] in `outputs`. + /// See [`Self::value`] for details. /// /// # Panics /// - /// If the provided `Output`s don't have this input's `Outpoint`. + /// If the provided [`Output`]s don't have this input's [`OutPoint`]. pub(crate) fn value_from_outputs( &self, outputs: &HashMap, @@ -253,13 +254,14 @@ impl Input { } } - /// Get the value spent by this input, by looking up its [`Outpoint`] in `utxos`. + /// Get the value spent by this input, by looking up its [`OutPoint`] in + /// [`Utxo`]s. /// /// This amount is added to the transaction value pool by this input. /// /// # Panics /// - /// If the provided `Utxo`s don't have this input's `Outpoint`. + /// If the provided [`Utxo`]s don't have this input's [`OutPoint`]. pub fn value(&self, utxos: &HashMap) -> Amount { if let Some(outpoint) = self.outpoint() { // look up the specific Output and convert it to the expected format @@ -275,12 +277,14 @@ impl Input { } } - /// Get the value spent by this input, by looking up its [`Outpoint`] in `ordered_utxos`. - /// See `value` for details. + /// Get the value spent by this input, by looking up its [`OutPoint`] in + /// [`OrderedUtxo`]s. + /// + /// See [`Self::value`] for details. /// /// # Panics /// - /// If the provided `OrderedUtxo`s don't have this input's `Outpoint`. + /// If the provided [`OrderedUtxo`]s don't have this input's [`OutPoint`]. pub fn value_from_ordered_utxos( &self, ordered_utxos: &HashMap, diff --git a/zebra-chain/src/transparent/utxo.rs b/zebra-chain/src/transparent/utxo.rs index 7a91c5f88..ec17a7048 100644 --- a/zebra-chain/src/transparent/utxo.rs +++ b/zebra-chain/src/transparent/utxo.rs @@ -111,6 +111,9 @@ impl OrderedUtxo { /// A restriction that must be checked before spending a transparent output of a /// coinbase transaction. /// +/// TODO: fix the comment below because +/// [`CoinbaseSpendRestriction::check_spend`] doesn't exist. +/// /// See [`CoinbaseSpendRestriction::check_spend`] for the consensus rules. #[derive(Copy, Clone, Debug, PartialEq, Eq)] #[cfg_attr( @@ -138,7 +141,7 @@ pub fn utxos_from_ordered_utxos( .collect() } -/// Compute an index of [`Output`]s, given an index of [`Utxo`]s. +/// Compute an index of [`transparent::Output`]s, given an index of [`Utxo`]s. pub fn outputs_from_utxos( utxos: HashMap, ) -> HashMap { diff --git a/zebra-chain/src/value_balance.rs b/zebra-chain/src/value_balance.rs index 05d53a226..9d37874c1 100644 --- a/zebra-chain/src/value_balance.rs +++ b/zebra-chain/src/value_balance.rs @@ -167,7 +167,7 @@ impl ValueBalance { impl ValueBalance { /// Returns the sum of this value balance, and the chain value pool changes in `block`. /// - /// `utxos` must contain the [`Utxo`]s of every input in this block, + /// `utxos` must contain the [`transparent::Utxo`]s of every input in this block, /// including UTXOs created by earlier transactions in this block. /// /// Note: the chain value pool has the opposite sign to the transaction @@ -221,7 +221,7 @@ impl ValueBalance { /// Returns the sum of this value balance, and the chain value pool changes in `transaction`. /// - /// `outputs` must contain the [`Output`]s of every input in this transaction, + /// `outputs` must contain the [`transparent::Output`]s of every input in this transaction, /// including UTXOs created by earlier transactions in its block. /// /// Note: the chain value pool has the opposite sign to the transaction @@ -263,7 +263,7 @@ impl ValueBalance { /// Returns the sum of this value balance, and the chain value pool change in `input`. /// - /// `outputs` must contain the [`Output`] spent by `input`, + /// `outputs` must contain the [`transparent::Output`] spent by `input`, /// (including UTXOs created by earlier transactions in its block). /// /// Note: the chain value pool has the opposite sign to the transaction diff --git a/zebra-network/src/address_book.rs b/zebra-network/src/address_book.rs index f2c05e1bc..7aeea1736 100644 --- a/zebra-network/src/address_book.rs +++ b/zebra-network/src/address_book.rs @@ -56,8 +56,9 @@ pub struct AddressBook { /// /// Some peers in this list might have open outbound or inbound connections. /// - /// We reverse the comparison order, because the standard library ([`BTreeMap`]) - /// sorts in ascending order, but [`OrderedMap`] sorts in descending order. + /// We reverse the comparison order, because the standard library + /// ([`BTreeMap`](std::collections::BTreeMap)) sorts in ascending order, but + /// [`OrderedMap`] sorts in descending order. by_addr: OrderedMap>, /// The maximum number of addresses in the address book. diff --git a/zebra-network/src/config.rs b/zebra-network/src/config.rs index 5ad0aa7a9..ec1a4562a 100644 --- a/zebra-network/src/config.rs +++ b/zebra-network/src/config.rs @@ -39,7 +39,7 @@ pub struct Config { /// /// If a specific listener address is configured, Zebra will advertise /// it to other nodes. But by default, Zebra uses an unspecified address - /// ("0.0.0.0" or "[::]"), which is not advertised to other nodes. + /// ("0.0.0.0" or "\[::\]"), which is not advertised to other nodes. /// /// Zebra does not currently support: /// - [Advertising a different external IP address #1890](https://github.com/ZcashFoundation/zebra/issues/1890), or diff --git a/zebra-network/src/constants.rs b/zebra-network/src/constants.rs index 09961a0aa..5078c520c 100644 --- a/zebra-network/src/constants.rs +++ b/zebra-network/src/constants.rs @@ -110,8 +110,8 @@ pub const INVENTORY_ROTATION_INTERVAL: Duration = Duration::from_secs(53); /// The default peer address crawler interval. /// -/// This should be at least [`HANDSHAKE_TIMEOUT`](constants::HANDSHAKE_TIMEOUT) -/// lower than all other crawler intervals. +/// This should be at least [`HANDSHAKE_TIMEOUT`] lower than all other crawler +/// intervals. /// /// This makes the following sequence of events more likely: /// 1. a peer address crawl, diff --git a/zebra-network/src/isolated/tor.rs b/zebra-network/src/isolated/tor.rs index e1ce25253..e9922511d 100644 --- a/zebra-network/src/isolated/tor.rs +++ b/zebra-network/src/isolated/tor.rs @@ -16,7 +16,7 @@ mod tests; lazy_static::lazy_static! { /// The shared isolated [`TorClient`] instance. /// - /// TODO: turn this into a tower service that takes a hostname, and returns an `arti_client::DataStream` + /// TODO: turn this into a tower service that takes a hostname, and returns an [`arti_client::DataStream`] /// (or a task that updates a watch channel when it's done?) pub static ref SHARED_TOR_CLIENT: Arc>>> = Arc::new(Mutex::new(None)); diff --git a/zebra-network/src/lib.rs b/zebra-network/src/lib.rs index af6c752f2..de0dcb689 100644 --- a/zebra-network/src/lib.rs +++ b/zebra-network/src/lib.rs @@ -47,11 +47,13 @@ //! //! Inbound Zcash Listener Task: //! * accepts inbound connections on the listener port -//! * initiates Zcash [`Handshake`]s, which creates [`Connection`] tasks for each inbound connection +//! * initiates Zcash [`peer::Handshake`]s, which creates [`peer::Connection`] +//! tasks for each inbound connection //! //! Outbound Zcash Connector Service: //! * initiates outbound connections to peer addresses -//! * initiates Zcash [`Handshake`]s, which creates [`Connection`] tasks for each outbound connection +//! * initiates Zcash [`peer::Handshake`]s, which creates [`peer::Connection`] +//! tasks for each outbound connection //! //! Zebra uses direct TCP connections to share blocks and mempool transactions with other peers. //! @@ -65,16 +67,16 @@ //! //! [`peer::Client`] Service: //! * provides an interface for outbound requests to an individual peer -//! * accepts [`Request`]s assigned to this peer by the [`PeerSet`] -//! * sends each request to the peer as Zcash [`Message`] -//! * waits for the inbound response [`Message`] from the peer, and returns it as a [`Response`] +//! * accepts [`Request`]s assigned to this peer by the `PeerSet` +//! * sends each request to the peer as Zcash [`Message`][1] +//! * waits for the inbound response [`Message`][1] from the peer, and returns it as a [`Response`] //! //! [`peer::Connection`] Service: //! * manages connection state: awaiting a request, or handling an inbound or outbound response //! * provides an interface for inbound requests from an individual peer -//! * accepts inbound Zcash [`Message`]s from this peer +//! * accepts inbound Zcash [`Message`][1]s from this peer //! * handles each message as a [`Request`] to the inbound service -//! * sends the [`Response`] to the peer as Zcash [`Message`]s +//! * sends the [`Response`] to the peer as Zcash [`Message`][1]s //! * drops peer connections if the inbound request queue is overloaded //! //! Since the Zcash network protocol is bidirectional, @@ -113,8 +115,10 @@ //! * adds seed peer addresses to the [`AddressBook`] //! //! Peer Crawler Task: -//! * discovers new peer addresses by sending [`Addr`] requests to connected peers +//! * discovers new peer addresses by sending `Addr` requests to connected peers //! * initiates new outbound peer connections in response to application demand +//! +//! [1]: protocol::external::Message #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")] #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")] diff --git a/zebra-network/src/meta_addr.rs b/zebra-network/src/meta_addr.rs index 36f362c35..a98a64a05 100644 --- a/zebra-network/src/meta_addr.rs +++ b/zebra-network/src/meta_addr.rs @@ -34,8 +34,11 @@ pub(crate) mod tests; /// /// Zebra also tracks how recently a peer has sent us messages, and derives peer /// liveness based on the current time. This derived state is tracked using -/// [`AddressBook::maybe_connected_peers`] and -/// [`AddressBook::reconnection_peers`]. +/// [`maybe_connected_peers`][mcp] and +/// [`reconnection_peers`][rp]. +/// +/// [mcp]: crate::AddressBook::maybe_connected_peers +/// [rp]: crate::AddressBook::reconnection_peers #[derive(Copy, Clone, Debug, Eq, PartialEq)] #[cfg_attr(any(test, feature = "proptest-impl"), derive(Arbitrary))] pub enum PeerAddrState { @@ -309,7 +312,7 @@ impl MetaAddr { /// and the services must be the services from that peer's handshake. /// /// Otherwise: - /// - malicious peers could interfere with other peers' `AddressBook` state, + /// - malicious peers could interfere with other peers' [`AddressBook`](crate::AddressBook) state, /// or /// - Zebra could advertise unreachable addresses to its own peers. pub fn new_responded(addr: &SocketAddr, services: &PeerServices) -> MetaAddrChange { @@ -851,9 +854,11 @@ impl Ord for MetaAddr { /// with `Responded` peers sorted first as a group. /// /// This order should not be used for reconnection attempts: use - /// [`AddressBook::reconnection_peers`] instead. + /// [`reconnection_peers`][rp] instead. /// /// See [`CandidateSet`] for more details. + /// + /// [rp]: crate::AddressBook::reconnection_peers fn cmp(&self, other: &Self) -> Ordering { use std::net::IpAddr::{V4, V6}; use Ordering::*; diff --git a/zebra-network/src/peer/client/tests.rs b/zebra-network/src/peer/client/tests.rs index d11cc740b..09dbf69eb 100644 --- a/zebra-network/src/peer/client/tests.rs +++ b/zebra-network/src/peer/client/tests.rs @@ -81,7 +81,7 @@ impl ClientTestHarness { .expect("heartbeat shutdown receiver endpoint has already been dropped"); } - /// Closes the receiver endpoint of [`ClientRequests`] that are supposed to be sent to the + /// Closes the receiver endpoint of [`ClientRequest`]s that are supposed to be sent to the /// remote peer. /// /// The remote peer that would receive the requests is mocked for testing. @@ -92,7 +92,7 @@ impl ClientTestHarness { .close(); } - /// Drops the receiver endpoint of [`ClientRequests`], forcefully closing the channel. + /// Drops the receiver endpoint of [`ClientRequest`]s, forcefully closing the channel. /// /// The remote peer that would receive the requests is mocked for testing. pub fn drop_outbound_client_request_receiver(&mut self) { @@ -118,7 +118,7 @@ impl ClientTestHarness { } } - /// Drops the receiver endpoint of [`InventoryChanges`], forcefully closing the channel. + /// Drops the receiver endpoint of [`InventoryChange`]s, forcefully closing the channel. /// /// The inventory registry that would track the changes is mocked for testing. /// diff --git a/zebra-network/src/peer/connector.rs b/zebra-network/src/peer/connector.rs index 6e73a3de9..7c774d251 100644 --- a/zebra-network/src/peer/connector.rs +++ b/zebra-network/src/peer/connector.rs @@ -20,7 +20,7 @@ use crate::{ BoxError, Request, Response, }; -/// A wrapper around [`peer::Handshake`] that opens a TCP connection before +/// A wrapper around [`Handshake`] that opens a TCP connection before /// forwarding to the inner handshake service. Writing this as its own /// [`tower::Service`] lets us apply unified timeout policies, etc. pub struct Connector diff --git a/zebra-network/src/peer/error.rs b/zebra-network/src/peer/error.rs index 223d7fdc2..eb42cde4b 100644 --- a/zebra-network/src/peer/error.rs +++ b/zebra-network/src/peer/error.rs @@ -40,19 +40,19 @@ pub enum PeerError { #[error("Peer closed connection")] ConnectionClosed, - /// Zebra dropped the [`Connection`]. + /// Zebra dropped the [`Connection`](crate::peer::Connection). #[error("Internal connection dropped")] ConnectionDropped, - /// Zebra dropped the [`Client`]. + /// Zebra dropped the [`Client`](crate::peer::Client). #[error("Internal client dropped")] ClientDropped, - /// A [`Client`]'s internal connection task exited. + /// A [`Client`](crate::peer::Client)'s internal connection task exited. #[error("Internal peer connection task exited")] ConnectionTaskExited, - /// Zebra's [`Client`] cancelled its heartbeat task. + /// Zebra's [`Client`](crate::peer::Client) cancelled its heartbeat task. #[error("Internal client cancelled its heartbeat task")] ClientCancelledHeartbeatTask, @@ -64,7 +64,7 @@ pub enum PeerError { #[error("Sending Client request timed out")] ConnectionSendTimeout, - /// Receiving a response to a [`peer::Client`] request took too long. + /// Receiving a response to a [`Client`](crate::peer::Client) request took too long. #[error("Receiving client response timed out")] ConnectionReceiveTimeout, @@ -94,7 +94,9 @@ pub enum PeerError { /// or peers can download and verify the missing data. /// /// If the peer has some of the data, the request returns an [`Ok`] response, - /// with any `notfound` data is marked as [`Missing`](InventoryResponse::Missing). + /// with any `notfound` data is marked as [`Missing`][m]. + /// + /// [m] crate::protocol::external::InventoryResponse::Missing #[error("Remote peer could not find any of the items: {0:?}")] NotFoundResponse(Vec), @@ -205,7 +207,7 @@ impl ErrorSlot { } } -/// Error returned when the `ErrorSlot` already contains an error. +/// Error returned when the [`ErrorSlot`] already contains an error. #[derive(Clone, Debug)] pub struct AlreadyErrored { /// The original error in the error slot. diff --git a/zebra-network/src/peer/handshake.rs b/zebra-network/src/peer/handshake.rs index 063bb96aa..0c4f967f7 100644 --- a/zebra-network/src/peer/handshake.rs +++ b/zebra-network/src/peer/handshake.rs @@ -1,4 +1,4 @@ -//! Initial [`Handshake`s] with Zebra peers over a `PeerTransport`. +//! Initial [`Handshake`]s with Zebra peers over a [`PeerTransport`]. use std::{ cmp::min, @@ -747,7 +747,8 @@ pub struct HandshakeRequest where PeerTransport: AsyncRead + AsyncWrite + Unpin + Send + 'static, { - /// The tokio [`TcpStream`] or Tor [`DataStream`] to the peer. + /// The tokio [`TcpStream`](tokio::net::TcpStream) or Tor + /// [`DataStream`](arti_client::DataStream) to the peer. pub data_stream: PeerTransport, /// The address of the peer, and other related information. diff --git a/zebra-network/src/protocol/external/addr/in_version.rs b/zebra-network/src/protocol/external/addr/in_version.rs index e2e2d7b1e..5305c943c 100644 --- a/zebra-network/src/protocol/external/addr/in_version.rs +++ b/zebra-network/src/protocol/external/addr/in_version.rs @@ -1,6 +1,6 @@ //! Zcash `version` message node address serialization. //! -//! The [`AddrInVersion`] format is the same as the `addr` ([`v1`]) message, +//! The [`AddrInVersion`] format is the same as the `addr` ([`super::v1`]) message, //! but without the timestamp field. use std::{ diff --git a/zebra-network/src/protocol/external/arbitrary.rs b/zebra-network/src/protocol/external/arbitrary.rs index e2090d80d..830b11386 100644 --- a/zebra-network/src/protocol/external/arbitrary.rs +++ b/zebra-network/src/protocol/external/arbitrary.rs @@ -126,14 +126,14 @@ impl Arbitrary for Version { /// Returns a random canonical Zebra `SocketAddr`. /// -/// See [`canonical_ip_addr`] for details. +/// See [`canonical_ip_addr`](super::addr::canonical_ip_addr) for details. pub fn canonical_socket_addr_strategy() -> impl Strategy { any::().prop_map(canonical_socket_addr) } /// Returns a random `SocketAddrV6` for use in `addr` (v1) Zcash network messages. /// -/// See [`canonical_ip_addr`] for details. +/// See [`canonical_ip_addr`](super::addr::canonical_ip_addr) for details. pub fn addr_v1_ipv6_mapped_socket_addr_strategy() -> impl Strategy { any::().prop_map(ipv6_mapped_socket_addr) } diff --git a/zebra-network/src/protocol/external/message.rs b/zebra-network/src/protocol/external/message.rs index 436e96ffc..a55c20630 100644 --- a/zebra-network/src/protocol/external/message.rs +++ b/zebra-network/src/protocol/external/message.rs @@ -83,12 +83,14 @@ pub enum Message { start_height: block::Height, /// Whether the remote peer should announce relayed - /// transactions or not, see [BIP 0037](https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki) + /// transactions or not, see [BIP 0037]. /// - /// Zebra does not implement the bloom filters in BIP 0037. + /// Zebra does not implement the bloom filters in [BIP 0037]. /// Instead, it only relays: /// - newly verified best chain block hashes and mempool transaction IDs, /// - after it reaches the chain tip. + /// + /// [BIP 0037]: https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki relay: bool, }, @@ -277,6 +279,7 @@ pub enum Message { /// This was defined in [BIP35], which is included in Zcash. /// /// [Bitcoin reference](https://en.bitcoin.it/wiki/Protocol_documentation#mempool) + /// /// [BIP35]: https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki Mempool, @@ -287,6 +290,7 @@ pub enum Message { /// Zebra currently ignores this message. /// /// [Bitcoin reference](https://en.bitcoin.it/wiki/Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock) + /// /// [BIP37]: https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki FilterLoad { /// The filter itself is simply a bit field of arbitrary @@ -312,6 +316,7 @@ pub enum Message { /// Zebra currently ignores this message. /// /// [Bitcoin reference](https://en.bitcoin.it/wiki/Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock) + /// /// [BIP37]: https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki FilterAdd { /// The data element to add to the current filter. @@ -330,6 +335,7 @@ pub enum Message { /// Zebra currently ignores this message. /// /// [Bitcoin reference](https://en.bitcoin.it/wiki/Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock) + /// /// [BIP37]: https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki FilterClear, } diff --git a/zebra-network/src/protocol/internal/request.rs b/zebra-network/src/protocol/internal/request.rs index e4b79b6e1..ea922f16b 100644 --- a/zebra-network/src/protocol/internal/request.rs +++ b/zebra-network/src/protocol/internal/request.rs @@ -153,11 +153,11 @@ pub enum Request { /// how we interpret advertisements from zcashd, which sometimes advertises /// multiple transactions at once. /// - /// This is implemented by sending an `inv` message containing the - /// unmined transaction ID, allowing the remote peer to choose whether to download + /// This is implemented by sending an `inv` message containing the unmined + /// transaction ID, allowing the remote peer to choose whether to download /// it. Remote peers who choose to download the transaction will generate a /// [`Request::TransactionsById`] against the "inbound" service passed to - /// [`zebra_network::init`]. + /// [`init`](crate::init). /// /// v4 transactions use a legacy transaction ID, and /// v5 transactions use a witnessed transaction ID. @@ -178,7 +178,7 @@ pub enum Request { /// block hash, allowing the remote peer to choose whether to download /// it. Remote peers who choose to download the block will generate a /// [`Request::BlocksByHash`] against the "inbound" service passed to - /// [`zebra_network::init`]. + /// [`init`](crate::init). /// /// The peer set routes this request specially, sending it to *half of* /// the available peers. diff --git a/zebra-node-services/src/mempool.rs b/zebra-node-services/src/mempool.rs index e83132be8..d4b6b1042 100644 --- a/zebra-node-services/src/mempool.rs +++ b/zebra-node-services/src/mempool.rs @@ -30,7 +30,7 @@ pub enum Request { TransactionsById(HashSet), /// Query matching transactions in the mempool, - /// using a unique set of [`Hash`]s. Pre-V5 transactions are matched + /// using a unique set of [`struct@Hash`]s. Pre-V5 transactions are matched /// directly; V5 transaction are matched just by the Hash, disregarding /// the [`AuthDigest`]. TransactionsByMinedId(HashSet), @@ -79,9 +79,9 @@ pub enum Response { /// Returns matching transactions from the mempool. /// - /// Since the [`TransactionsById`] request is unique, + /// Since the [`Request::TransactionsById`] request is unique, /// the response transactions are also unique. The same applies to - /// [`TransactionByMinedId`] requests, since the mempool does not allow + /// [`Request::TransactionsByMinedId`] requests, since the mempool does not allow /// different transactions with different mined IDs. Transactions(Vec), diff --git a/zebra-state/src/arbitrary.rs b/zebra-state/src/arbitrary.rs index b74ae4fb2..bd322e020 100644 --- a/zebra-state/src/arbitrary.rs +++ b/zebra-state/src/arbitrary.rs @@ -72,6 +72,7 @@ impl PreparedBlock { /// with fake zero-valued spent UTXOs. /// /// Only for use in tests. + #[cfg(test)] pub fn test_with_zero_spent_utxos(&self) -> ContextuallyValidBlock { ContextuallyValidBlock::test_with_zero_spent_utxos(self) } @@ -80,6 +81,7 @@ impl PreparedBlock { /// using a fake chain value pool change. /// /// Only for use in tests. + #[cfg(test)] pub fn test_with_chain_pool_change( &self, fake_chain_value_pool_change: ValueBalance, @@ -91,13 +93,14 @@ impl PreparedBlock { /// with no chain value pool change. /// /// Only for use in tests. + #[cfg(test)] pub fn test_with_zero_chain_pool_change(&self) -> ContextuallyValidBlock { ContextuallyValidBlock::test_with_zero_chain_pool_change(self) } } impl ContextuallyValidBlock { - /// Create a block that's ready for non-finalized [`Chain`] contextual validation, + /// Create a block that's ready for non-finalized `Chain` contextual validation, /// using a [`PreparedBlock`] and fake zero-valued spent UTXOs. /// /// Only for use in tests. diff --git a/zebra-state/src/request.rs b/zebra-state/src/request.rs index 1007bcf07..98bb5c9d6 100644 --- a/zebra-state/src/request.rs +++ b/zebra-state/src/request.rs @@ -89,7 +89,7 @@ pub struct PreparedBlock { /// The height of the block. pub height: block::Height, /// New transparent outputs created in this block, indexed by - /// [`Outpoint`](transparent::Outpoint). + /// [`OutPoint`](transparent::OutPoint). /// /// Each output is tagged with its transaction index in the block. /// (The outputs of earlier transactions in a block can be spent by later @@ -112,7 +112,7 @@ pub struct PreparedBlock { /// A contextually validated block, ready to be committed directly to the finalized state with /// no checks, if it becomes the root of the best non-finalized chain. /// -/// Used by the state service and non-finalized [`Chain`]. +/// Used by the state service and non-finalized `Chain`. #[derive(Clone, Debug, PartialEq, Eq)] pub struct ContextuallyValidBlock { /// The block to commit to the state. @@ -125,7 +125,7 @@ pub struct ContextuallyValidBlock { pub(crate) height: block::Height, /// New transparent outputs created in this block, indexed by - /// [`Outpoint`](transparent::Outpoint). + /// [`OutPoint`](transparent::OutPoint). /// /// Note: although these transparent outputs are newly created, they may not /// be unspent, since a later transaction in a block can spend outputs of an @@ -135,7 +135,7 @@ pub struct ContextuallyValidBlock { pub(crate) new_outputs: HashMap, /// The outputs spent by this block, indexed by the [`transparent::Input`]'s - /// [`Outpoint`](transparent::Outpoint). + /// [`OutPoint`](transparent::OutPoint). /// /// Note: these inputs can come from earlier transactions in this block, /// or earlier blocks in the chain. @@ -164,7 +164,7 @@ pub struct FinalizedBlock { /// The height of the block. pub height: block::Height, /// New transparent outputs created in this block, indexed by - /// [`Outpoint`](transparent::Outpoint). + /// [`OutPoint`](transparent::OutPoint). /// /// Note: although these transparent outputs are newly created, they may not /// be unspent, since a later transaction in a block can spend outputs of an @@ -188,15 +188,15 @@ impl From<&PreparedBlock> for PreparedBlock { // This allows moving work out of the single-threaded state service. impl ContextuallyValidBlock { - /// Create a block that's ready for non-finalized [`Chain`] contextual validation, + /// Create a block that's ready for non-finalized `Chain` contextual validation, /// using a [`PreparedBlock`] and the UTXOs it spends. /// /// When combined, `prepared.new_outputs` and `spent_utxos` must contain - /// the [`Utxo`]s spent by every transparent input in this block, + /// the [`Utxo`](transparent::Utxo)s spent by every transparent input in this block, /// including UTXOs created by earlier transactions in this block. /// /// Note: a [`ContextuallyValidBlock`] isn't actually contextually valid until - /// [`Chain::update_chain_state_with`] returns success. + /// `Chain::update_chain_state_with` returns success. pub fn with_block_and_spent_utxos( prepared: PreparedBlock, mut spent_outputs: HashMap, @@ -282,7 +282,8 @@ impl From for FinalizedBlock { } #[derive(Clone, Debug, PartialEq, Eq)] -/// A query about or modification to the chain state, via the [`StateService`]. +/// A query about or modification to the chain state, via the +/// [`StateService`](crate::service::StateService). pub enum Request { /// Performs contextual validation of the given block, committing it to the /// state if successful. @@ -370,8 +371,9 @@ pub enum Request { /// [`block::Height`] using `.into()`. Block(HashOrHeight), - /// Request a UTXO identified by the given Outpoint, waiting until it becomes - /// available if it is unknown. + /// Request a UTXO identified by the given + /// [`OutPoint`](transparent::OutPoint), waiting until it becomes available + /// if it is unknown. /// /// This request is purely informational, and there are no guarantees about /// whether the UTXO remains unspent or is on the best chain, or any chain. @@ -432,7 +434,8 @@ pub enum Request { } #[derive(Clone, Debug, PartialEq, Eq)] -/// A read-only query about the chain state, via the [`ReadStateService`]. +/// A read-only query about the chain state, via the +/// [`ReadStateService`](crate::service::ReadStateService). pub enum ReadRequest { /// Looks up a block by hash or height in the current best chain. /// @@ -455,7 +458,8 @@ pub enum ReadRequest { /// Looks up the balance of a set of transparent addresses. /// - /// Returns an [`Amount`] with the total balance of the set of addresses. + /// Returns an [`Amount`](zebra_chain::amount::Amount) with the total + /// balance of the set of addresses. AddressBalance(HashSet), /// Looks up a Sapling note commitment tree either by a hash or height. diff --git a/zebra-test/src/command.rs b/zebra-test/src/command.rs index be901933c..2ffef044e 100644 --- a/zebra-test/src/command.rs +++ b/zebra-test/src/command.rs @@ -328,7 +328,7 @@ impl TestChild { /// To never match any log lines, use `RegexSet::empty()`. /// /// This method is a [`TestChild::with_failure_regexes`] wrapper for - /// strings, [`Regex`]es, and [`RegexSet`]s. + /// strings, `Regex`es, and [`RegexSet`]s. /// /// # Panics /// @@ -944,7 +944,7 @@ impl TestOutput { /// Checks each line in the output of a command, using a closure to determine /// if the line is valid. /// - /// See [`output_check`] for details. + /// See [`Self::output_check`] for details. #[instrument(skip(self, line_predicate, output))] pub fn any_output_line

( &self, @@ -975,7 +975,7 @@ impl TestOutput { /// Tests if any lines in the output of a command contain `s`. /// - /// See [`any_output_line`] for details. + /// See [`Self::any_output_line`] for details. #[instrument(skip(self, output))] pub fn any_output_line_contains( &self, diff --git a/zebra-test/src/mock_service.rs b/zebra-test/src/mock_service.rs index ba5c70b05..b50eaf453 100644 --- a/zebra-test/src/mock_service.rs +++ b/zebra-test/src/mock_service.rs @@ -231,9 +231,9 @@ impl MockServiceBuilder { self } - /// Create a [`MockService`] to be used in `proptest`s. + /// Create a [`MockService`] to be used in [`mod@proptest`]s. /// - /// The assertions performed by [`MockService`] use the macros provided by [`proptest`], like + /// The assertions performed by [`MockService`] use the macros provided by [`mod@proptest`], like /// [`prop_assert`]. pub fn for_prop_tests( self, @@ -455,7 +455,7 @@ impl MockService MockService { /// Expect a specific request to be received. /// @@ -468,7 +468,7 @@ impl MockService MockService MockService MockService; /// Controls how long we wait for a transaction download request to complete. /// -/// This is currently equal to [`crate::components::sync::BLOCK_DOWNLOAD_TIMEOUT`] for +/// This is currently equal to [`BLOCK_DOWNLOAD_TIMEOUT`] for /// consistency, even though parts of the rationale used for defining the value /// don't apply here (e.g. we can drop transactions hashes when the queue is full). pub(crate) const TRANSACTION_DOWNLOAD_TIMEOUT: Duration = BLOCK_DOWNLOAD_TIMEOUT; /// Controls how long we wait for a transaction verify request to complete. /// -/// This is currently equal to [`crate::components::sync::BLOCK_VERIFY_TIMEOUT`] for +/// This is currently equal to [`BLOCK_VERIFY_TIMEOUT`] for /// consistency. /// /// This timeout may lead to denial of service, which will be handled in