From f4922f6fe761bf14bc8f4709fb92eda50fff85e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dawid=20Ci=C4=99=C5=BCarkiewicz?= Date: Fri, 27 May 2022 16:45:21 -0700 Subject: [PATCH 1/4] Update `BlockHeader::version` documentation --- src/blockdata/block.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/blockdata/block.rs b/src/blockdata/block.rs index 06a53298..eec8425b 100644 --- a/src/blockdata/block.rs +++ b/src/blockdata/block.rs @@ -42,7 +42,12 @@ use crate::VarInt; #[derive(Copy, PartialEq, Eq, Clone, Debug)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct BlockHeader { - /// The protocol version. Should always be 1. + /// Originally protocol version, but repurposed for soft-fork signaling. + /// + /// ### Relevant BIPs + /// + /// * [BIP9 - Version bits with timeout and delay](https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki) (current usage) + /// * [BIP34 - Block v2, Height in Coinbase](https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki) pub version: i32, /// Reference to the previous block in the chain. pub prev_blockhash: BlockHash, From 7c2ca3d20beaae670c0a99a3dcd425c353ebe99b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dawid=20Ci=C4=99=C5=BCarkiewicz?= Date: Fri, 27 May 2022 16:50:07 -0700 Subject: [PATCH 2/4] Add `BlockHeader` Bitcoin Core reference link --- src/blockdata/block.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/blockdata/block.rs b/src/blockdata/block.rs index eec8425b..18140c50 100644 --- a/src/blockdata/block.rs +++ b/src/blockdata/block.rs @@ -39,6 +39,10 @@ use crate::VarInt; /// A block header, which contains all the block's information except /// the actual transactions +/// +/// # Bitcoin Core References +/// +/// * [CBlockHeader definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/block.h#L20) #[derive(Copy, PartialEq, Eq, Clone, Debug)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct BlockHeader { From 325ea8fb7d16322bc45015713d1f8939ce4450ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dawid=20Ci=C4=99=C5=BCarkiewicz?= Date: Fri, 27 May 2022 19:50:24 -0700 Subject: [PATCH 3/4] Add "Relevant BIPs` to `Address` --- src/blockdata/block.rs | 2 +- src/util/address.rs | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/src/blockdata/block.rs b/src/blockdata/block.rs index 18140c50..24fac3d9 100644 --- a/src/blockdata/block.rs +++ b/src/blockdata/block.rs @@ -40,7 +40,7 @@ use crate::VarInt; /// A block header, which contains all the block's information except /// the actual transactions /// -/// # Bitcoin Core References +/// ### Bitcoin Core References /// /// * [CBlockHeader definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/block.h#L20) #[derive(Copy, PartialEq, Eq, Clone, Debug)] diff --git a/src/util/address.rs b/src/util/address.rs index afa4c714..b0b9765d 100644 --- a/src/util/address.rs +++ b/src/util/address.rs @@ -536,6 +536,15 @@ impl<'a> fmt::Display for AddressEncoding<'a> { } /// A Bitcoin address. +/// +/// ### Relevant BIPs +/// +/// * [BIP13 - Address Format for pay-to-script-hash](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki) +/// * [BIP16 - Pay to Script Hash](https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki) +/// * [BIP141 - Segregated Witness (Consensus layer)](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki) +/// * [BIP142 - Address Format for Segregated Witness](https://github.com/bitcoin/bips/blob/master/bip-0142.mediawiki) +/// * [BIP341 - Taproot: SegWit version 1 spending rules](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) +/// * [BIP350 - Bech32m format for v1+ witness addresses](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct Address { /// The type of the address. From 1875c912c346161e07452969862ab4dc8798e193 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dawid=20Ci=C4=99=C5=BCarkiewicz?= Date: Fri, 27 May 2022 20:34:12 -0700 Subject: [PATCH 4/4] Extend docstring for more types --- src/blockdata/block.rs | 21 +++++++++++++++---- src/blockdata/script.rs | 15 +++++++++++++- src/blockdata/transaction.rs | 40 +++++++++++++++++++++++++++++++++--- 3 files changed, 68 insertions(+), 8 deletions(-) diff --git a/src/blockdata/block.rs b/src/blockdata/block.rs index 24fac3d9..b827c278 100644 --- a/src/blockdata/block.rs +++ b/src/blockdata/block.rs @@ -37,8 +37,12 @@ use crate::blockdata::constants::{max_target, WITNESS_SCALE_FACTOR}; use crate::blockdata::script; use crate::VarInt; -/// A block header, which contains all the block's information except -/// the actual transactions +/// Bitcoin block header. +/// +/// Contains all the block's information except the actual transactions, but +/// including a root of a [merkle tree] commiting to all transactions in the block. +/// +/// [merkle tree]: https://en.wikipedia.org/wiki/Merkle_tree /// /// ### Bitcoin Core References /// @@ -164,8 +168,17 @@ impl BlockHeader { } } -/// A Bitcoin block, which is a collection of transactions with an attached -/// proof of work. +/// Bitcoin block. +/// +/// A collection of transactions with an attached proof of work. +/// +/// See [Bitcoin Wiki: Block][wiki-block] for more information. +/// +/// [wiki-block]: https://en.bitcoin.it/wiki/Block +/// +/// ### Bitcoin Core References +/// +/// * [CBlock definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/block.h#L62) #[derive(PartialEq, Eq, Clone, Debug)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct Block { diff --git a/src/blockdata/script.rs b/src/blockdata/script.rs index 839a7c29..0cc0a695 100644 --- a/src/blockdata/script.rs +++ b/src/blockdata/script.rs @@ -46,7 +46,20 @@ use crate::util::taproot::{LeafVersion, TapBranchHash, TapLeafHash}; use secp256k1::{Secp256k1, Verification, XOnlyPublicKey}; use crate::schnorr::{TapTweak, TweakedPublicKey, UntweakedPublicKey}; -/// A Bitcoin script. +/// Bitcoin script. +/// +/// A list of instructions in a simple, [Forth]-like, stack-based programming language +/// that Bitcoin uses. +/// +/// [Forth]: https://en.wikipedia.org/wiki/Forth_(programming_language) +/// +/// See [Bitcoin Wiki: Script][wiki-script] for more information. +/// +/// [wiki-script]: https://en.bitcoin.it/wiki/Script +/// +/// ### Bitcoin Core References +/// +/// * [CScript definition](https://github.com/bitcoin/bitcoin/blob/d492dc1cdaabdc52b0766bf4cba4bd73178325d0/src/script/script.h#L410) #[derive(Clone, Default, PartialOrd, Ord, PartialEq, Eq, Hash)] pub struct Script(Box<[u8]>); diff --git a/src/blockdata/transaction.rs b/src/blockdata/transaction.rs index c35a1b65..2dd73861 100644 --- a/src/blockdata/transaction.rs +++ b/src/blockdata/transaction.rs @@ -53,6 +53,10 @@ const UINT256_ONE: [u8; 32] = [ ]; /// A reference to a transaction output. +/// +/// ### Bitcoin Core References +/// +/// * [COutPoint definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/transaction.h#L26) #[derive(Copy, Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)] pub struct OutPoint { /// The referenced transaction's txid. @@ -187,7 +191,15 @@ impl ::core::str::FromStr for OutPoint { } } -/// A transaction input, which defines old coins to be consumed +/// Bitcoin transaction input. +/// +/// It contains the location of the previous transaction's output, +/// that it spends and set of scripts that satisfy its spending +/// conditions. +/// +/// ### Bitcoin Core References +/// +/// * [CTxIn definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/transaction.h#L65) #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct TxIn { @@ -220,7 +232,17 @@ impl Default for TxIn { } } -/// A transaction output, which defines new coins to be created from old ones. +/// Bitcoin transaction output. +/// +/// Defines new coins to be created as a result of the transaction, +/// along with spending conditions ("script", aka "output script"), +/// which an input spending it must satisfy. +/// +/// An output that is not yet spent by an input is called Unspent Transaction Output ("UTXO"). +/// +/// ### Bitcoin Core References +/// +/// * [CTxOut definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/transaction.h#L148) #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct TxOut { @@ -237,7 +259,19 @@ impl Default for TxOut { } } -/// A Bitcoin transaction, which describes an authenticated movement of coins. +/// Bitcoin transaction. +/// +/// An authenticated movement of coins. +/// +/// See [Bitcoin Wiki: Transaction][wiki-transaction] for more information. +/// +/// [wiki-transaction]: https://en.bitcoin.it/wiki/Transaction +/// +/// ### Bitcoin Core References +/// +/// * [CTtransaction definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/transaction.h#L279) +/// +/// ### Serialization notes /// /// If any inputs have nonempty witnesses, the entire transaction is serialized /// in the post-BIP141 Segwit format which includes a list of witnesses. If all