Merge rust-bitcoin/rust-bitcoin#2692: Add docs for custom signets

30a09670e8 Add docs for custom signets (Tobin C. Harding)

Pull request description:

  We have started using `AsRef<Params>` in a few places as a function parameter. If a user of the library wishes to use these functions they need to create a type that can implement this trait. Because we use `non_exhaustive` on the `Params` struct it is not possible to just construct a `Params` type. This may be surprising for some folk.

  Add module level docs to the `consensus::params` module with an example of how to create a type that can be used to describe a custom signet network. Use fields inspired by Mutiny Wallet's described usage.

  Close: #2690

ACKs for top commit:
  sanket1729:
    ACK 30a09670e8.
  apoelstra:
    ACK 30a09670e8 this is great; would like to see more `const` but for example code no big deal

Tree-SHA512: 50881763aea99641e24871b0eae60650174c48f620742944e7d5617fcf1edff73a20b2a8f043433f6f114ff5f3f4691703fc37b28880c305bb052c2d75d1eeeb
This commit is contained in:
Andrew Poelstra 2024-04-17 17:08:50 +00:00
commit 7a8dafb748
No known key found for this signature in database
GPG Key ID: C588D63CE41B97C1
1 changed files with 59 additions and 0 deletions

View File

@ -5,6 +5,65 @@
//! This module provides a predefined set of parameters for different Bitcoin //! This module provides a predefined set of parameters for different Bitcoin
//! chains (such as mainnet, testnet). //! chains (such as mainnet, testnet).
//! //!
//! # Custom Signets Example
//!
//! In various places in this crate we take `AsRef<Params>` as a parameter, in order to create a
//! custom type that can be used is such places you might want to do the following:
//!
//! ```
//! use bitcoin::consensus::Params;
//! use bitcoin::{p2p, Script, ScriptBuf, Network, Target};
//!
//! const POW_TARGET_SPACING: u64 = 120; // Two minutes.
//! const MAGIC: [u8; 4] = [1, 2, 3, 4];
//!
//! pub struct CustomParams {
//! params: Params,
//! magic: [u8; 4],
//! challenge_script: ScriptBuf,
//! }
//!
//! impl CustomParams {
//! /// Creates a new custom params.
//! pub fn new() -> Self {
//! let mut params = Params::new(Network::Signet);
//! params.pow_target_spacing = POW_TARGET_SPACING;
//!
//! // This would be something real (see BIP-325).
//! let challenge_script = ScriptBuf::new();
//!
//! Self {
//! params,
//! magic: MAGIC,
//! challenge_script,
//! }
//! }
//!
//! /// Returns the custom magic bytes.
//! pub fn magic(&self) -> p2p::Magic { p2p::Magic::from_bytes(self.magic) }
//!
//! /// Returns the custom signet challenge script.
//! pub fn challenge_script(&self) -> &Script { &self.challenge_script }
//! }
//!
//! impl AsRef<Params> for CustomParams {
//! fn as_ref(&self) -> &Params { &self.params }
//! }
//!
//! impl Default for CustomParams {
//! fn default() -> Self { Self::new() }
//! }
//!
//! # { // Just check the code above is usable.
//! # let target = Target::MAX_ATTAINABLE_SIGNET;
//! #
//! # let signet = Params::SIGNET;
//! # let _ = target.difficulty(signet);
//! #
//! # let custom = CustomParams::new();
//! # let _ = target.difficulty(custom);
//! # }
//! ```
use crate::network::Network; use crate::network::Network;
#[cfg(doc)] #[cfg(doc)]