Merge rust-bitcoin/rust-bitcoin#2795: Make `Address:p2sh_from_hash` public

3615410d21 api: Run just check-api (Tobin C. Harding)
a3d2d1a184 Make Address:p2sh_from_hash public (Tobin C. Harding)

Pull request description:

  We previously made this function Private and added a comment that doing so was somehow better to remove the footgun of hashing the wrong length script. However in hindsight this was a bad idea and users want the functionality.

  Make the `Address:p2sh_from_hash` public and document it as we do for `Address::p2sh`.

  This is an additive change and is expected to be backported to `v0.32`, as part of the fix to #2784. Please note it introduces the footgun that is described in the function rustdoc. This will be improved as a separate patch and added to the current release.

ACKs for top commit:
  apoelstra:
    ACK 3615410d21

Tree-SHA512: 535bb7894eeef8ecb5afb7bf6e5c483cd42c6a4282d1c116e5bf86cd1364a8327bbec1efb8634a578f07ad2832c1e5daf7fe7e844574b88b1ad355a443627bef

api/bitcoin/all-features.txt

@@ -7057,6 +7057,7 @@ pub fn bitcoin::address::Address::is_spend_standard(&self) -> bool
 pub fn bitcoin::address::Address::matches_script_pubkey(&self, script: &bitcoin::blockdata::script::Script) -> bool
 pub fn bitcoin::address::Address::p2pkh(pk: impl core::convert::Into<bitcoin::PubkeyHash>, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2sh(script: &bitcoin::blockdata::script::Script, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> core::result::Result<bitcoin::address::Address, bitcoin::address::error::P2shError>
+pub fn bitcoin::address::Address::p2sh_from_hash(hash: bitcoin::blockdata::script::ScriptHash, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2shwpkh(pk: &bitcoin::CompressedPublicKey, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2shwsh(script: &bitcoin::blockdata::script::Script, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2tr<C: secp256k1::context::Verification>(secp: &secp256k1::Secp256k1<C>, internal_key: bitcoin::key::UntweakedPublicKey, merkle_root: core::option::Option<bitcoin::taproot::TapNodeHash>, hrp: impl core::convert::Into<bitcoin::address::KnownHrp>) -> bitcoin::address::Address

api/bitcoin/default-features.txt

@@ -6725,6 +6725,7 @@ pub fn bitcoin::address::Address::is_spend_standard(&self) -> bool
 pub fn bitcoin::address::Address::matches_script_pubkey(&self, script: &bitcoin::blockdata::script::Script) -> bool
 pub fn bitcoin::address::Address::p2pkh(pk: impl core::convert::Into<bitcoin::PubkeyHash>, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2sh(script: &bitcoin::blockdata::script::Script, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> core::result::Result<bitcoin::address::Address, bitcoin::address::error::P2shError>
+pub fn bitcoin::address::Address::p2sh_from_hash(hash: bitcoin::blockdata::script::ScriptHash, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2shwpkh(pk: &bitcoin::CompressedPublicKey, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2shwsh(script: &bitcoin::blockdata::script::Script, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2tr<C: secp256k1::context::Verification>(secp: &secp256k1::Secp256k1<C>, internal_key: bitcoin::key::UntweakedPublicKey, merkle_root: core::option::Option<bitcoin::taproot::TapNodeHash>, hrp: impl core::convert::Into<bitcoin::address::KnownHrp>) -> bitcoin::address::Address

api/bitcoin/no-features.txt

@@ -6096,6 +6096,7 @@ pub fn bitcoin::address::Address::is_spend_standard(&self) -> bool
 pub fn bitcoin::address::Address::matches_script_pubkey(&self, script: &bitcoin::blockdata::script::Script) -> bool
 pub fn bitcoin::address::Address::p2pkh(pk: impl core::convert::Into<bitcoin::PubkeyHash>, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2sh(script: &bitcoin::blockdata::script::Script, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> core::result::Result<bitcoin::address::Address, bitcoin::address::error::P2shError>
+pub fn bitcoin::address::Address::p2sh_from_hash(hash: bitcoin::blockdata::script::ScriptHash, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2shwpkh(pk: &bitcoin::CompressedPublicKey, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2shwsh(script: &bitcoin::blockdata::script::Script, network: impl core::convert::Into<bitcoin::network::NetworkKind>) -> bitcoin::address::Address
 pub fn bitcoin::address::Address::p2tr<C: secp256k1::context::Verification>(secp: &secp256k1::Secp256k1<C>, internal_key: bitcoin::key::UntweakedPublicKey, merkle_root: core::option::Option<bitcoin::taproot::TapNodeHash>, hrp: impl core::convert::Into<bitcoin::address::KnownHrp>) -> bitcoin::address::Address

bitcoin/src/address/mod.rs

@@ -384,8 +384,13 @@ impl Address {
         Ok(Address::p2sh_from_hash(hash, network))
     }
 
-    // This is intentionally not public so we enforce script length checks.
+    /// Creates a pay to script hash P2SH address from a script hash.
-    fn p2sh_from_hash(hash: ScriptHash, network: impl Into<NetworkKind>) -> Address {
+    ///
+    /// # Warning
+    ///
+    /// The `hash` pre-image (redeem script) must not exceed 520 bytes in length
+    /// otherwise outputs created from the returned address will be un-spendable.
+    pub fn p2sh_from_hash(hash: ScriptHash, network: impl Into<NetworkKind>) -> Address {
         Self(AddressInner::P2sh { hash, network: network.into() }, PhantomData)
     }