pub struct Address<V = NetworkChecked>where
V: NetworkValidation,{
pub payload: Payload,
pub network: Network,
/* private fields */
}
Expand description
A Bitcoin address.
Parsing addresses
When parsing string as an address, one has to pay attention to the network, on which the parsed
address is supposed to be valid. For the purpose of this validation, Address
has
is_valid_for_network
method. In order to provide more safety,
enforced by compiler, Address
also contains a special marker type, which indicates whether network of the parsed
address has been checked. This marker type will prevent from calling certain functions unless the network
verification has been successfully completed.
The result of parsing an address is Address<NetworkUnchecked>
suggesting that network of the parsed address
has not yet been verified. To perform this verification, method require_network
can be called, providing network on which the address is supposed to be valid. If the verification succeeds,
Address<NetworkChecked>
is returned.
The types Address
and Address<NetworkChecked>
are synonymous, i. e. they can be used interchangeably.
use std::str::FromStr;
use bitcoin::{Address, Network};
use bitcoin::address::{NetworkUnchecked, NetworkChecked};
// variant 1
let address: Address<NetworkUnchecked> = "32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf".parse().unwrap();
let address: Address<NetworkChecked> = address.require_network(Network::Bitcoin).unwrap();
// variant 2
let address: Address = Address::from_str("32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf").unwrap()
.require_network(Network::Bitcoin).unwrap();
// variant 3
let address: Address<NetworkChecked> = "32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf".parse::<Address<_>>()
.unwrap().require_network(Network::Bitcoin).unwrap();
Formatting addresses
To format address into its textual representation, both Debug
(for usage in programmer-facing,
debugging context) and Display
(for user-facing output) can be used, with the following caveats:
Display
is implemented only forAddress<NetworkChecked>
:
let address: Address<NetworkChecked> = Address::from_str("132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM")
.unwrap().assume_checked();
assert_eq!(address.to_string(), "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM");
let address: Address<NetworkUnchecked> = Address::from_str("132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM")
.unwrap();
let s = address.to_string(); // does not compile
Debug
onAddress<NetworkUnchecked>
does not produce clean address but address wrapped by an indicator that its network has not been checked. This is to encourage programmer to properly check the network and useDisplay
in user-facing context.
let address: Address<NetworkUnchecked> = Address::from_str("132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM")
.unwrap();
assert_eq!(format!("{:?}", address), "Address<NetworkUnchecked>(132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM)");
let address: Address<NetworkChecked> = Address::from_str("132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM")
.unwrap().assume_checked();
assert_eq!(format!("{:?}", address), "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM");
Relevant BIPs
Fields§
§payload: Payload
The type of the address.
network: Network
The network on which this address is usable.
Implementations§
§impl<V> Address<V>where
V: NetworkValidation,
impl<V> Address<V>where V: NetworkValidation,
Methods on Address
that can be called on both Address<NetworkChecked>
and
Address<NetworkUnchecked>
.
§impl Address<NetworkChecked>
impl Address<NetworkChecked>
Methods and functions that can be called only on Address<NetworkChecked>
.
pub fn p2pkh(pk: &PublicKey, network: Network) -> Address<NetworkChecked>
pub fn p2pkh(pk: &PublicKey, network: Network) -> Address<NetworkChecked>
Creates a pay to (compressed) public key hash address from a public key.
This is the preferred non-witness type address.
pub fn p2sh(
script: &Script,
network: Network
) -> Result<Address<NetworkChecked>, Error>
pub fn p2sh( script: &Script, network: Network ) -> Result<Address<NetworkChecked>, Error>
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.
pub fn p2wpkh(
pk: &PublicKey,
network: Network
) -> Result<Address<NetworkChecked>, Error>
pub fn p2wpkh( pk: &PublicKey, network: Network ) -> Result<Address<NetworkChecked>, Error>
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.
Errors
Will only return an error if an uncompressed public key is provided.
pub fn p2shwpkh(
pk: &PublicKey,
network: Network
) -> Result<Address<NetworkChecked>, Error>
pub fn p2shwpkh( pk: &PublicKey, network: Network ) -> Result<Address<NetworkChecked>, Error>
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.
Errors
Will only return an Error if an uncompressed public key is provided.
pub fn p2wsh(script: &Script, network: Network) -> Address<NetworkChecked>
pub fn p2wsh(script: &Script, network: Network) -> Address<NetworkChecked>
Creates a witness pay to script hash address.
pub fn p2shwsh(script: &Script, network: Network) -> Address<NetworkChecked>
pub fn p2shwsh(script: &Script, network: Network) -> Address<NetworkChecked>
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.
pub fn p2tr<C>(
secp: &Secp256k1<C>,
internal_key: XOnlyPublicKey,
merkle_root: Option<TapNodeHash>,
network: Network
) -> Address<NetworkChecked>where
C: Verification,
pub fn p2tr<C>( secp: &Secp256k1<C>, internal_key: XOnlyPublicKey, merkle_root: Option<TapNodeHash>, network: Network ) -> Address<NetworkChecked>where C: Verification,
Creates a pay to taproot address from an untweaked key.
pub fn p2tr_tweaked(
output_key: TweakedPublicKey,
network: Network
) -> Address<NetworkChecked>
pub fn p2tr_tweaked( output_key: TweakedPublicKey, network: Network ) -> Address<NetworkChecked>
Creates a pay to taproot address from a pre-tweaked output key.
This method is not recommended for use, Address::p2tr()
should be used where possible.
pub fn address_type(&self) -> Option<AddressType>
pub fn address_type(&self) -> Option<AddressType>
Gets the address type of the address.
Returns
None if unknown, non-standard or related to the future witness version.
pub fn is_spend_standard(&self) -> bool
pub fn is_spend_standard(&self) -> bool
Checks whether or not the address is following Bitcoin standardness rules when spending from this address. NOT to be called by senders.
Spending Standardness
For forward compatibility, the senders must send to any Address
. Receivers
can use this method to check whether or not they can spend from this address.
SegWit addresses with unassigned witness versions or non-standard program sizes are considered non-standard.
pub fn is_standard(&self) -> bool
👎Deprecated since 0.30.0: Use Address::is_spend_standard instead
pub fn is_standard(&self) -> bool
Checks whether or not the address is following Bitcoin standardness rules.
SegWit addresses with unassigned witness versions or non-standard program sizes are considered non-standard.
pub fn from_script(
script: &Script,
network: Network
) -> Result<Address<NetworkChecked>, Error>
pub fn from_script( script: &Script, network: Network ) -> Result<Address<NetworkChecked>, Error>
Constructs an Address
from an output script (scriptPubkey
).
pub fn script_pubkey(&self) -> ScriptBuf
pub fn script_pubkey(&self) -> ScriptBuf
Generates a script pubkey spending to this address.
pub fn to_qr_uri(&self) -> String
pub fn to_qr_uri(&self) -> String
Creates a URI string bitcoin:address optimized to be encoded in QR codes.
If the address is bech32, both the schema and the address become uppercase. If the address is base58, the schema is lowercase and the address is left mixed case.
Quoting BIP 173 “inside QR codes uppercase SHOULD be used, as those permit the use of alphanumeric mode, which is 45% more compact than the normal byte mode.”
Note however that despite BIP21 explicitly stating that the bitcoin:
prefix should be
parsed as case-insensitive many wallets got this wrong and don’t parse correctly.
See compatibility table.
If you want to avoid allocation you can use alternate display instead:
write!(writer, "{:#}", address)?;
Returns true if the given pubkey is directly related to the address payload.
This is determined by directly comparing the address payload with either the hash of the given public key or the segwit redeem hash generated from the given key. For taproot addresses, the supplied key is assumed to be tweaked
Returns true if the supplied xonly public key can be used to derive the address.
This will only work for Taproot addresses. The Public Key is assumed to have already been tweaked.
pub fn matches_script_pubkey(&self, script_pubkey: &Script) -> bool
pub fn matches_script_pubkey(&self, script_pubkey: &Script) -> bool
Returns true if the address creates a particular script This function doesn’t make any allocations.
§impl Address<NetworkUnchecked>
impl Address<NetworkUnchecked>
Methods that can be called only on Address<NetworkUnchecked>
.
pub fn is_valid_for_network(&self, network: Network) -> bool
pub fn is_valid_for_network(&self, network: Network) -> bool
Parsed addresses do not always have one network. The problem is that legacy testnet, regtest and signet addresse use the same prefix instead of multiple different ones. When parsing, such addresses are always assumed to be testnet addresses (the same is true for bech32 signet addresses). So if one wants to check if an address belongs to a certain network a simple comparison is not enough anymore. Instead this function can be used.
use bitcoin::{Address, Network};
use bitcoin::address::NetworkUnchecked;
let address: Address<NetworkUnchecked> = "2N83imGV3gPwBzKJQvWJ7cRUY2SpUyU6A5e".parse().unwrap();
assert!(address.is_valid_for_network(Network::Testnet));
assert!(address.is_valid_for_network(Network::Regtest));
assert!(address.is_valid_for_network(Network::Signet));
assert_eq!(address.is_valid_for_network(Network::Bitcoin), false);
let address: Address<NetworkUnchecked> = "32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf".parse().unwrap();
assert!(address.is_valid_for_network(Network::Bitcoin));
assert_eq!(address.is_valid_for_network(Network::Testnet), false);
pub fn require_network(
self,
required: Network
) -> Result<Address<NetworkChecked>, Error>
pub fn require_network( self, required: Network ) -> Result<Address<NetworkChecked>, Error>
Checks whether network of this address is as required.
For details about this mechanism, see section Parsing addresses
on Address
.
pub fn assume_checked(self) -> Address<NetworkChecked>
pub fn assume_checked(self) -> Address<NetworkChecked>
Marks, without any additional checks, network of this address as checked.
Improper use of this method may lead to loss of funds. Reader will most likely prefer
require_network
as a safe variant.
For details about this mechanism, see section Parsing addresses
on Address
.
Trait Implementations§
§impl<V> Clone for Address<V>where
V: Clone + NetworkValidation,
impl<V> Clone for Address<V>where V: Clone + NetworkValidation,
§impl<V> Debug for Address<V>where
V: NetworkValidation,
impl<V> Debug for Address<V>where V: NetworkValidation,
§impl<'de> Deserialize<'de> for Address<NetworkUnchecked>
impl<'de> Deserialize<'de> for Address<NetworkUnchecked>
§fn deserialize<D>(
deserializer: D
) -> Result<Address<NetworkUnchecked>, <D as Deserializer<'de>>::Error>where
D: Deserializer<'de>,
fn deserialize<D>( deserializer: D ) -> Result<Address<NetworkUnchecked>, <D as Deserializer<'de>>::Error>where D: Deserializer<'de>,
§impl Display for Address<NetworkChecked>
impl Display for Address<NetworkChecked>
§impl From<Address<NetworkChecked>> for ScriptBuf
impl From<Address<NetworkChecked>> for ScriptBuf
§fn from(a: Address<NetworkChecked>) -> ScriptBuf
fn from(a: Address<NetworkChecked>) -> ScriptBuf
§impl FromStr for Address<NetworkUnchecked>
impl FromStr for Address<NetworkUnchecked>
Address can be parsed only with NetworkUnchecked
.
§impl<V> Hash for Address<V>where
V: Hash + NetworkValidation,
impl<V> Hash for Address<V>where V: Hash + NetworkValidation,
§impl<V> Ord for Address<V>where
V: Ord + NetworkValidation,
impl<V> Ord for Address<V>where V: Ord + NetworkValidation,
§impl<V> PartialEq<Address<V>> for Address<V>where
V: PartialEq<V> + NetworkValidation,
impl<V> PartialEq<Address<V>> for Address<V>where V: PartialEq<V> + NetworkValidation,
§impl<V> PartialOrd<Address<V>> for Address<V>where
V: PartialOrd<V> + NetworkValidation,
impl<V> PartialOrd<Address<V>> for Address<V>where V: PartialOrd<V> + NetworkValidation,
§fn partial_cmp(&self, other: &Address<V>) -> Option<Ordering>
fn partial_cmp(&self, other: &Address<V>) -> Option<Ordering>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more§impl Serialize for Address<NetworkChecked>
impl Serialize for Address<NetworkChecked>
§fn serialize<S>(
&self,
serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where
S: Serializer,
fn serialize<S>( &self, serializer: S ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where S: Serializer,
§impl Serialize for Address<NetworkUnchecked>
impl Serialize for Address<NetworkUnchecked>
§fn serialize<S>(
&self,
serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where
S: Serializer,
fn serialize<S>( &self, serializer: S ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where S: Serializer,
impl<V> Eq for Address<V>where V: Eq + NetworkValidation,
impl<V> StructuralEq for Address<V>where V: NetworkValidation,
impl<V> StructuralPartialEq for Address<V>where V: NetworkValidation,
Auto Trait Implementations§
impl<V> RefUnwindSafe for Address<V>where V: RefUnwindSafe,
impl<V> Send for Address<V>where V: Send,
impl<V> Sync for Address<V>where V: Sync,
impl<V> Unpin for Address<V>where V: Unpin,
impl<V> UnwindSafe for Address<V>where V: UnwindSafe,
Blanket Implementations§
§impl<T> Conv for T
impl<T> Conv for T
source§impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.§impl<T> FmtForward for T
impl<T> FmtForward for T
§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where Self: Binary,
self
to use its Binary
implementation when Debug
-formatted.§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where Self: Display,
self
to use its Display
implementation when
Debug
-formatted.§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where Self: LowerExp,
self
to use its LowerExp
implementation when
Debug
-formatted.§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where Self: LowerHex,
self
to use its LowerHex
implementation when
Debug
-formatted.§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where Self: Octal,
self
to use its Octal
implementation when Debug
-formatted.§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where Self: Pointer,
self
to use its Pointer
implementation when
Debug
-formatted.§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where Self: UpperExp,
self
to use its UpperExp
implementation when
Debug
-formatted.§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where Self: UpperHex,
self
to use its UpperHex
implementation when
Debug
-formatted.§fn fmt_list(self) -> FmtList<Self>where
&'a Self: for<'a> IntoIterator,
fn fmt_list(self) -> FmtList<Self>where &'a Self: for<'a> IntoIterator,
source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere T: ?Sized,
§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere Self: Sized,
§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere R: 'a,
self
and passes that borrow into the pipe function. Read more§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere R: 'a,
self
and passes that borrow into the pipe function. Read more§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> Rwhere
Self: Borrow<B>,
B: 'a + ?Sized,
R: 'a,
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> Rwhere Self: Borrow<B>, B: 'a + ?Sized, R: 'a,
§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> Rwhere
Self: BorrowMut<B>,
B: 'a + ?Sized,
R: 'a,
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> Rwhere Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,
§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> Rwhere
Self: AsRef<U>,
U: 'a + ?Sized,
R: 'a,
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> Rwhere Self: AsRef<U>, U: 'a + ?Sized, R: 'a,
self
, then passes self.as_ref()
into the pipe function.§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> Rwhere
Self: AsMut<U>,
U: 'a + ?Sized,
R: 'a,
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> Rwhere Self: AsMut<U>, U: 'a + ?Sized, R: 'a,
self
, then passes self.as_mut()
into the pipe
function.§impl<T> Tap for T
impl<T> Tap for T
§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Selfwhere
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,
Borrow<B>
of a value. Read more§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,
BorrowMut<B>
of a value. Read more§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Selfwhere
Self: AsRef<R>,
R: ?Sized,
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,
AsRef<R>
view of a value. Read more§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,
AsMut<R>
view of a value. Read more§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Selfwhere
Self: Deref<Target = T>,
T: ?Sized,
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Selfwhere Self: Deref<Target = T>, T: ?Sized,
Deref::Target
of a value. Read more§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere
Self: DerefMut<Target = T> + Deref,
T: ?Sized,
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere Self: DerefMut<Target = T> + Deref, T: ?Sized,
Deref::Target
of a value. Read more§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap()
only in debug builds, and is erased in release builds.§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut()
only in debug builds, and is erased in release
builds.§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Selfwhere
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,
.tap_borrow()
only in debug builds, and is erased in release
builds.§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,
.tap_borrow_mut()
only in debug builds, and is erased in release
builds.§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Selfwhere
Self: AsRef<R>,
R: ?Sized,
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,
.tap_ref()
only in debug builds, and is erased in release
builds.§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,
.tap_ref_mut()
only in debug builds, and is erased in release
builds.§impl<T> TryConv for T
impl<T> TryConv for T
§impl<S, T> UncheckedInto<T> for Swhere
T: UncheckedFrom<S>,
impl<S, T> UncheckedInto<T> for Swhere T: UncheckedFrom<S>,
§fn unchecked_into(self) -> T
fn unchecked_into(self) -> T
unchecked_from
.