milksad
/
rust-bitcoin-unsafe-fast
14
0
Fork 0
Code Issues Pull Requests Activity

Merge rust-bitcoin/rust-bitcoin#704: util/address: Improve docs 

822c99222d Improve constructor rustdocs for Address (Tobin Harding)
804a38cb67 Improve documentation of `WitnessVersion` (Tobin Harding)
eb8278fd2e util/address: Improve docs (Tobin Harding)

Pull request description:

  Improve documentation of the `address` module by doing:

  - Add full stops to all sentences
  - Use code ticks even inside links e.g., [`WitnessVersion`]
  - Use 100 character line length
  - Do grammar fixes
  - Use comment sections (e.g. `# Returns`)
  - Use 3rd person for function comments e.g. 'Converts foo to bar' instead of 'Convert foo to bar'
  - Use ticks for scriptPubkey

  This patch does a single file because a bunch of these changes pick an
  arbitrary stlye, if we can bikeshed on this PR then future PRs should be
  able to progress more quickly. I'll take lack of comment on any of the
  above as approval and I'll attempt to be uniform when doing the rest of
  the codebase. I plan on just chipping away at this, I can only do so
  much docs work in a day without getting bored of it :)

  Notes:

  - I didn't touch 'segwit' vs 'SegWit', seems both are widely used.
  - Using ticks inside links may be an overkill but seems more correct?
  - I'm not totally sure where the line is in the Rust ecosystem between
    readability in an editor and rendering as HTML, open to input on this.

ACKs for top commit:
  Kixunil:
    ACK 822c99222d
  dr-orlovsky:
    ACK 822c99222d

Tree-SHA512: bfbaeec74803dd0704ed3e39b9a4966db34dbb3d7ea850ed6230abf220b877687ac1479f4940b7bf39d7e8172cd62c36b232bfaa8186a92cc58b3d7e642674f6
This commit is contained in:
Dr Maxim Orlovsky 2021-11-23 18:00:25 +01:00
parent 435298c427 822c99222d
commit d614b6c759
No known key found for this signature in database
GPG Key ID: FFC0250947E5C6F7
1 changed files with 97 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
src/util/address.rs
View File

@ -55,24 +55,24 @@ use util::schnorr::{TapTweak, UntweakedPublicKey, TweakedPublicKey};
/// Address error. /// Address error.
#[derive(Debug, PartialEq, Eq, Clone)] #[derive(Debug, PartialEq, Eq, Clone)]
pub enum Error { pub enum Error {
/// Base58 encoding error /// Base58 encoding error.
Base58(base58::Error), Base58(base58::Error),
/// Bech32 encoding error /// Bech32 encoding error.
Bech32(bech32::Error), Bech32(bech32::Error),
/// The bech32 payload was empty /// The bech32 payload was empty.
EmptyBech32Payload, EmptyBech32Payload,
/// The wrong checksum algorithm was used. See BIP-0350. /// The wrong checksum algorithm was used. See BIP-0350.
InvalidBech32Variant { InvalidBech32Variant {
/// Bech32 variant that is required by the used Witness version /// Bech32 variant that is required by the used Witness version.
expected: bech32::Variant, expected: bech32::Variant,
/// The actual Bech32 variant encoded in the address representation /// The actual Bech32 variant encoded in the address representation.
found: bech32::Variant found: bech32::Variant
}, },
/// Script version must be 0 to 16 inclusive /// Script version must be 0 to 16 inclusive.
InvalidWitnessVersion(u8), InvalidWitnessVersion(u8),
/// Unable to parse witness version from string /// Unable to parse witness version from string.
UnparsableWitnessVersion(ParseIntError), UnparsableWitnessVersion(ParseIntError),
/// Bitcoin script opcode does not match any known witness version, the script is malformed /// Bitcoin script opcode does not match any known witness version, the script is malformed.
MalformedWitnessVersion, MalformedWitnessVersion,
/// The witness program must be between 2 and 40 bytes in length. /// The witness program must be between 2 and 40 bytes in length.
InvalidWitnessProgramLength(usize), InvalidWitnessProgramLength(usize),
@ -139,15 +139,15 @@ impl From<bech32::Error> for Error {
/// The different types of addresses. /// The different types of addresses.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum AddressType { pub enum AddressType {
/// pay-to-pubkey-hash /// Pay to pubkey hash.
P2pkh, P2pkh,
/// pay-to-script-hash /// Pay to script hash.
P2sh, P2sh,
/// pay-to-witness-pubkey-hash /// Pay to witness pubkey hash.
P2wpkh, P2wpkh,
/// pay-to-witness-script-hash /// Pay to witness script hash.
P2wsh, P2wsh,
/// pay-to-taproot /// Pay to taproot.
P2tr, P2tr,
} }
@ -177,49 +177,49 @@ impl FromStr for AddressType {
} }
} }
/// Version of the WitnessProgram: first byte of `scriptPubkey` in /// Version of the witness program.
/// transaction output for transactions starting with opcodes ranging from 0
/// to 16 (inclusive).
/// ///
/// Structure helps to limit possible version of the witness according to the /// Helps limit possible versions of the witness according to the specification. If a plain `u8`
/// specification; if a plain `u8` type was be used instead it would mean that /// type was used instead it would mean that the version may be > 16, which would be incorrect.
/// version may be > 16, which is incorrect. ///
/// First byte of `scriptPubkey` in transaction output for transactions starting with opcodes
/// ranging from 0 to 16 (inclusive).
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)] #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
#[repr(u8)] #[repr(u8)]
pub enum WitnessVersion { pub enum WitnessVersion {
/// Initial version of Witness Program. Used for P2WPKH and P2WPK outputs /// Initial version of witness program. Used for P2WPKH and P2WPK outputs
V0 = 0, V0 = 0,
/// Version of Witness Program used for Taproot P2TR outputs /// Version of witness program used for Taproot P2TR outputs.
V1 = 1, V1 = 1,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V2 = 2, V2 = 2,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V3 = 3, V3 = 3,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V4 = 4, V4 = 4,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V5 = 5, V5 = 5,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V6 = 6, V6 = 6,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V7 = 7, V7 = 7,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V8 = 8, V8 = 8,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V9 = 9, V9 = 9,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V10 = 10, V10 = 10,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V11 = 11, V11 = 11,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V12 = 12, V12 = 12,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V13 = 13, V13 = 13,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V14 = 14, V14 = 14,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V15 = 15, V15 = 15,
/// Future (unsupported) version of Witness Program /// Future (unsupported) version of witness program.
V16 = 16, V16 = 16,
} }
@ -246,23 +246,23 @@ impl WitnessVersion {
/// ([`bech32::u5`]) into [`WitnessVersion`] variant. /// ([`bech32::u5`]) into [`WitnessVersion`] variant.
/// ///
/// # Returns /// # Returns
/// Version of the Witness program /// Version of the Witness program.
/// ///
/// # Errors /// # Errors
/// If the integer does not corresponds to any witness version, errors with /// If the integer does not correspond to any witness version, errors with
/// [`Error::InvalidWitnessVersion`] /// [`Error::InvalidWitnessVersion`].
pub fn from_u5(value: ::bech32::u5) -> Result<Self, Error> { pub fn from_u5(value: ::bech32::u5) -> Result<Self, Error> {
WitnessVersion::from_num(value.to_u8()) WitnessVersion::from_num(value.to_u8())
} }
/// Converts 8-bit unsigned integer value into [`WitnessVersion`] variant. /// Converts an 8-bit unsigned integer value into [`WitnessVersion`] variant.
/// ///
/// # Returns /// # Returns
/// Version of the Witness program /// Version of the Witness program.
/// ///
/// # Errors /// # Errors
/// If the integer does not corresponds to any witness version, errors with /// If the integer does not correspond to any witness version, errors with
/// [`Error::InvalidWitnessVersion`] /// [`Error::InvalidWitnessVersion`].
pub fn from_num(no: u8) -> Result<Self, Error> { pub fn from_num(no: u8) -> Result<Self, Error> {
Ok(match no { Ok(match no {
0 => WitnessVersion::V0, 0 => WitnessVersion::V0,
@ -289,11 +289,11 @@ impl WitnessVersion {
/// Converts bitcoin script opcode into [`WitnessVersion`] variant. /// Converts bitcoin script opcode into [`WitnessVersion`] variant.
/// ///
/// # Returns /// # Returns
/// Version of the Witness program (for opcodes in range of `OP_0`..`OP_16`) /// Version of the Witness program (for opcodes in range of `OP_0`..`OP_16`).
/// ///
/// # Errors /// # Errors
/// If the opcode does not correspond to any witness version, errors with /// If the opcode does not correspond to any witness version, errors with
/// [`Error::UnparsableWitnessVersion`] /// [`Error::MalformedWitnessVersion`].
pub fn from_opcode(opcode: opcodes::All) -> Result<Self, Error> { pub fn from_opcode(opcode: opcodes::All) -> Result<Self, Error> {
match opcode.into_u8() { match opcode.into_u8() {
0 => Ok(WitnessVersion::V0), 0 => Ok(WitnessVersion::V0),
@ -311,7 +311,7 @@ impl WitnessVersion {
/// ///
/// # Errors /// # Errors
/// If the opcode does not correspond to any witness version, errors with /// If the opcode does not correspond to any witness version, errors with
/// [`Error::UnparsableWitnessVersion`] for the rest of opcodes /// [`Error::MalformedWitnessVersion`] for the rest of opcodes.
pub fn from_instruction(instruction: Instruction) -> Result<Self, Error> { pub fn from_instruction(instruction: Instruction) -> Result<Self, Error> {
match instruction { match instruction {
Instruction::Op(op) => WitnessVersion::from_opcode(op), Instruction::Op(op) => WitnessVersion::from_opcode(op),
@ -324,12 +324,12 @@ impl WitnessVersion {
/// ///
/// NB: this is not the same as an integer representation of the opcode signifying witness /// NB: this is not the same as an integer representation of the opcode signifying witness
/// version in bitcoin script. Thus, there is no function to directly convert witness version /// version in bitcoin script. Thus, there is no function to directly convert witness version
/// into a byte since the conversion requires context (bitcoin script or just a version number) /// into a byte since the conversion requires context (bitcoin script or just a version number).
pub fn into_num(self) -> u8 { pub fn into_num(self) -> u8 {
self as u8 self as u8
} }
/// Determine the checksum variant. See BIP-0350 for specification. /// Determines the checksum variant. See BIP-0350 for specification.
pub fn bech32_variant(&self) -> bech32::Variant { pub fn bech32_variant(&self) -> bech32::Variant {
match self { match self {
WitnessVersion::V0 => bech32::Variant::Bech32, WitnessVersion::V0 => bech32::Variant::Bech32,
@ -339,14 +339,14 @@ impl WitnessVersion {
} }
impl From<WitnessVersion> for ::bech32::u5 { impl From<WitnessVersion> for ::bech32::u5 {
/// Converts [`WitnessVersion`] instance into corresponding Bech32(m) u5-value ([`bech32::u5`]) /// Converts [`WitnessVersion`] instance into corresponding Bech32(m) u5-value ([`bech32::u5`]).
fn from(version: WitnessVersion) -> Self { fn from(version: WitnessVersion) -> Self {
::bech32::u5::try_from_u8(version.into_num()).expect("WitnessVersion must be 0..=16") ::bech32::u5::try_from_u8(version.into_num()).expect("WitnessVersion must be 0..=16")
} }
} }
impl From<WitnessVersion> for opcodes::All { impl From<WitnessVersion> for opcodes::All {
/// Converts [`WitnessVersion`] instance into corresponding Bitcoin scriptopcode (`OP_0`..`OP_16`) /// Converts [`WitnessVersion`] instance into corresponding Bitcoin scriptopcode (`OP_0`..`OP_16`).
fn from(version: WitnessVersion) -> opcodes::All { fn from(version: WitnessVersion) -> opcodes::All {
match version { match version {
WitnessVersion::V0 => opcodes::all::OP_PUSHBYTES_0, WitnessVersion::V0 => opcodes::all::OP_PUSHBYTES_0,
@ -355,24 +355,24 @@ impl From<WitnessVersion> for opcodes::All {
} }
} }
/// The method used to produce an address /// The method used to produce an address.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Payload { pub enum Payload {
/// P2PKH address /// P2PKH address.
PubkeyHash(PubkeyHash), PubkeyHash(PubkeyHash),
/// P2SH address /// P2SH address.
ScriptHash(ScriptHash), ScriptHash(ScriptHash),
/// Segwit addresses /// Segwit address.
WitnessProgram { WitnessProgram {
/// The witness program version /// The witness program version.
version: WitnessVersion, version: WitnessVersion,
/// The witness program /// The witness program.
program: Vec<u8>, program: Vec<u8>,
}, },
} }
impl Payload { impl Payload {
/// Get a [Payload] from an output script (scriptPubkey). /// Constructs a [Payload] from an output script (`scriptPubkey`).
pub fn from_script(script: &script::Script) -> Option<Payload> { pub fn from_script(script: &script::Script) -> Option<Payload> {
Some(if script.is_p2pkh() { Some(if script.is_p2pkh() {
let mut hash_inner = [0u8; 20]; let mut hash_inner = [0u8; 20];
@ -408,18 +408,19 @@ impl Payload {
} }
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
/// A Bitcoin address /// A Bitcoin address.
pub struct Address { pub struct Address {
/// The type of the address /// The type of the address.
pub payload: Payload, pub payload: Payload,
/// The network on which this address is usable /// The network on which this address is usable.
pub network: Network, pub network: Network,
} }
serde_string_impl!(Address, "a Bitcoin address"); serde_string_impl!(Address, "a Bitcoin address");
impl Address { impl Address {
/// Creates a pay to (compressed) public key hash address from a public key /// Creates a pay to (compressed) public key hash address from a public key.
/// This is the preferred non-witness type address ///
/// This is the preferred non-witness type address.
#[inline] #[inline]
pub fn p2pkh(pk: &ecdsa::PublicKey, network: Network) -> Address { pub fn p2pkh(pk: &ecdsa::PublicKey, network: Network) -> Address {
let mut hash_engine = PubkeyHash::engine(); let mut hash_engine = PubkeyHash::engine();
@ -431,8 +432,10 @@ impl Address {
} }
} }
/// Creates a pay to script hash P2SH address from a script /// Creates a pay to script hash P2SH address from a script.
/// This address type was introduced with BIP16 and is the popular type to implement multi-sig these days. ///
/// This address type was introduced with BIP16 and is the popular type to implement multi-sig
/// these days.
#[inline] #[inline]
pub fn p2sh(script: &script::Script, network: Network) -> Result<Address, Error> { pub fn p2sh(script: &script::Script, network: Network) -> Result<Address, Error> {
if script.len() > MAX_SCRIPT_ELEMENT_SIZE{ if script.len() > MAX_SCRIPT_ELEMENT_SIZE{
@ -444,10 +447,12 @@ impl Address {
}) })
} }
/// Create a witness pay to public key address from a public key /// Creates a witness pay to public key address from a public key.
/// This is the native segwit address type for an output redeemable with a single signature
/// ///
/// Will only return an Error when an uncompressed public key is provided. /// This is the native segwit address type for an output redeemable with a single signature.
///
/// # Errors
/// Will only return an error if an uncompressed public key is provided.
pub fn p2wpkh(pk: &ecdsa::PublicKey, network: Network) -> Result<Address, Error> { pub fn p2wpkh(pk: &ecdsa::PublicKey, network: Network) -> Result<Address, Error> {
if !pk.compressed { if !pk.compressed {
return Err(Error::UncompressedPubkey); return Err(Error::UncompressedPubkey);
@ -465,10 +470,12 @@ impl Address {
}) })
} }
/// Create a pay to script address that embeds a witness pay to public key /// Creates a pay to script address that embeds a witness pay to public key.
/// This is a segwit address type that looks familiar (as p2sh) to legacy clients
/// ///
/// Will only return an Error when an uncompressed public key is provided. /// This is a segwit address type that looks familiar (as p2sh) to legacy clients.
///
/// # Errors
/// Will only return an Error if an uncompressed public key is provided.
pub fn p2shwpkh(pk: &ecdsa::PublicKey, network: Network) -> Result<Address, Error> { pub fn p2shwpkh(pk: &ecdsa::PublicKey, network: Network) -> Result<Address, Error> {
if !pk.compressed { if !pk.compressed {
return Err(Error::UncompressedPubkey); return Err(Error::UncompressedPubkey);
@ -487,7 +494,7 @@ impl Address {
}) })
} }
/// Create a witness pay to script hash address /// Creates a witness pay to script hash address.
pub fn p2wsh(script: &script::Script, network: Network) -> Address { pub fn p2wsh(script: &script::Script, network: Network) -> Address {
Address { Address {
network: network, network: network,
@ -498,8 +505,9 @@ impl Address {
} }
} }
/// Create a pay to script address that embeds a witness pay to script hash address /// Creates a pay to script address that embeds a witness pay to script hash address.
/// This is a segwit address type that looks familiar (as p2sh) to legacy clients ///
/// This is a segwit address type that looks familiar (as p2sh) to legacy clients.
pub fn p2shwsh(script: &script::Script, network: Network) -> Address { pub fn p2shwsh(script: &script::Script, network: Network) -> Address {
let ws = script::Builder::new() let ws = script::Builder::new()
.push_int(0) .push_int(0)
@ -512,7 +520,7 @@ impl Address {
} }
} }
/// Create a pay to taproot address from untweaked key /// Creates a pay to taproot address from an untweaked key.
pub fn p2tr<C: Verification>( pub fn p2tr<C: Verification>(
secp: &Secp256k1<C>, secp: &Secp256k1<C>,
internal_key: UntweakedPublicKey, internal_key: UntweakedPublicKey,
@ -528,9 +536,9 @@ impl Address {
} }
} }
/// Create a pay to taproot address from a pre-tweaked output key. /// Creates a pay to taproot address from a pre-tweaked output key.
/// ///
/// This method is not recommended for use and [Address::p2tr()] should be used where possible. /// This method is not recommended for use, [`Address::p2tr()`] should be used where possible.
pub fn p2tr_tweaked( pub fn p2tr_tweaked(
output_key: TweakedPublicKey, output_key: TweakedPublicKey,
network: Network network: Network
@ -544,7 +552,9 @@ impl Address {
} }
} }
/// Get the address type of the address. /// Gets the address type of the address.
///
/// # Returns
/// None if unknown, non-standard or related to the future witness version. /// None if unknown, non-standard or related to the future witness version.
pub fn address_type(&self) -> Option<AddressType> { pub fn address_type(&self) -> Option<AddressType> {
match self.payload { match self.payload {
@ -568,16 +578,15 @@ impl Address {
} }
} }
/// Check whether or not the address is following Bitcoin /// Checks whether or not the address is following Bitcoin standardness rules.
/// standardness rules.
/// ///
/// SegWit addresses with unassigned witness versions or non-standard /// SegWit addresses with unassigned witness versions or non-standard program sizes are
/// program sizes are considered non-standard. /// considered non-standard.
pub fn is_standard(&self) -> bool { pub fn is_standard(&self) -> bool {
self.address_type().is_some() self.address_type().is_some()
} }
/// Get an [Address] from an output script (scriptPubkey). /// Constructs an [`Address`] from an output script (`scriptPubkey`).
pub fn from_script(script: &script::Script, network: Network) -> Option<Address> { pub fn from_script(script: &script::Script, network: Network) -> Option<Address> {
Some(Address { Some(Address {
payload: Payload::from_script(script)?, payload: Payload::from_script(script)?,
@ -585,7 +594,7 @@ impl Address {
}) })
} }
/// Generates a script pubkey spending to this address /// Generates a script pubkey spending to this address.
pub fn script_pubkey(&self) -> script::Script { pub fn script_pubkey(&self) -> script::Script {
self.payload.script_pubkey() self.payload.script_pubkey()
} }
@ -641,7 +650,7 @@ impl Address {
} }
// Alternate formatting `{:#}` is used to return uppercase version of bech32 addresses which should // Alternate formatting `{:#}` is used to return uppercase version of bech32 addresses which should
// be used in QR codes, see [Address::to_qr_uri] // be used in QR codes, see [`Address::to_qr_uri`].
impl fmt::Display for Address { impl fmt::Display for Address {
fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result { fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
match self.payload { match self.payload {
@ -698,8 +707,10 @@ impl<W: fmt::Write> fmt::Write for UpperWriter<W> {
} }
} }
/// Extract the bech32 prefix. /// Extracts the bech32 prefix.
/// Returns the same slice when no prefix is found. ///
/// # Returns
/// The input slice if no prefix is found.
fn find_bech32_prefix(bech32: &str) -> &str { fn find_bech32_prefix(bech32: &str) -> &str {
// Split at the last occurrence of the separator character '1'. // Split at the last occurrence of the separator character '1'.
match bech32.rfind('1') { match bech32.rfind('1') {