Untitled Git - bitcoindevkit.org/blob

   1 <!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Decoding of bech32 encoded strings as specified by BIP-173 and BIP-350."><title>bdk_chain::bitcoin::bech32::primitives::decode - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../../../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../../../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../../../../../static.files/rustdoc-dd39b87e5fcfba68.css"><meta name="rustdoc-vars" data-root-path="../../../../../" data-static-root-path="../../../../../static.files/" data-current-crate="bdk_chain" data-themes="" data-resource-suffix="" data-rustdoc-version="1.80.0-nightly (78a775127 2024-05-11)" data-channel="nightly" data-search-js="search-d52510db62a78183.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../../../../../static.files/storage-118b08c4c78b968e.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../../../../static.files/main-20a3ad099b048cf2.js"></script><noscript><link rel="stylesheet" href="../../../../../static.files/noscript-df360f571f6edeae.css"></noscript><link rel="alternate icon" type="image/png" href="../../../../../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../../../../../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button><a class="logo-container" href="../../../../../bdk_chain/index.html"><img src="https://github.com/bitcoindevkit/bdk/raw/master/static/bdk.png" alt=""></a></nav><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="../../../../../bdk_chain/index.html"><img src="https://github.com/bitcoindevkit/bdk/raw/master/static/bdk.png" alt="logo"></a><h2><a href="../../../../../bdk_chain/index.html">bdk_chain</a><span class="version">0.20.0</span></h2></div><h2 class="location"><a href="#">Module decode</a></h2><div class="sidebar-elems"><section><ul class="block"><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li></ul></section><h2><a href="../index.html">In bdk_chain::bitcoin::bech32::primitives</a></h2></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Module <a href="../../../../index.html">bdk_chain</a>::<wbr><a href="../../../index.html">bitcoin</a>::<wbr><a href="../../index.html">bech32</a>::<wbr><a href="../index.html">primitives</a>::<wbr><a class="mod" href="#">decode</a><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><span class="out-of-band"><button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Decoding of bech32 encoded strings as specified by <a href="https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki">BIP-173</a> and <a href="https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki">BIP-350</a>.</p>
   2 <p>You should only need to use this module directly if you want control over exactly what is
   3 checked and when it is checked (correct bech32 characters, valid checksum, valid checksum for
   4 specific checksum algorithm, etc). If you are parsing/validating modern (post BIP-350) bitcoin
   5 segwit addresses consider using the <a href="../../segwit/index.html" title="mod bdk_chain::bitcoin::bech32::segwit"><code>crate::segwit</code></a> API.</p>
   6 <p>If you do find yourself using this module directly then consider using the most general type
   7 that serves your purposes, each type can be created by parsing an address string to <code>new</code>. You
   8 likely do not want to arbitrarily transition from one type to the next even though possible. And
   9 be prepared to spend some time with the bips - you have been warned :)</p>
  10 <h2 id="details"><a class="doc-anchor" href="#details">§</a>Details</h2>
  11 <p>A Bech32 string is at most 90 characters long and consists of:</p>
  12 <ul>
  13 <li>The human-readable part, which is intended to convey the type of data, or anything else that
  14 is relevant to the reader. This part MUST contain 1 to 83 US-ASCII characters.</li>
  15 <li>The separator, which is always “1”.</li>
  16 <li>The data part, which is at least 6 characters long and only consists of alphanumeric
  17 characters excluding “1”, “b”, “i”, and “o”.</li>
  18 </ul>
  19 <p>The types in this module heavily lean on the wording in BIP-173: <em>We first
  20 describe the general checksummed base32 format called Bech32 and then define Segregated Witness
  21 addresses using it.</em></p>
  22 <ul>
  23 <li><code>UncheckedHrpstring</code>: Parses the general checksummed base32 format and provides checksum validation.</li>
  24 <li><code>CheckedHrpstring</code>: Provides access to the data encoded by a general checksummed base32 string and segwit checks.</li>
  25 <li><code>SegwitHrpstring</code>: Provides access to the data encoded by a segwit address.</li>
  26 </ul>
  27 <h2 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h2>
  28 <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bech32::{Bech32, Bech32m, Fe32, Hrp};
  29 <span class="kw">use </span>bech32::primitives::decode::{CheckedHrpstring, SegwitHrpstring, UncheckedHrpstring};
  30 <span class="kw">use </span>bech32::segwit::VERSION_1;
  31
  32 <span class="comment">// An arbitrary HRP and a string of valid bech32 characters.
  33 </span><span class="kw">let </span>s = <span class="string">"abcd143hj65vxw49rts6kcw35u6r6tgzguyr03vvveeewjqpn05efzq444444"</span>;
  34 <span class="macro">assert!</span>(UncheckedHrpstring::new(s).is_ok());
  35 <span class="comment">// But it has an invalid checksum.
  36 </span><span class="macro">assert!</span>(CheckedHrpstring::new::&lt;Bech32&gt;(s).is_err());
  37 <span class="macro">assert!</span>(CheckedHrpstring::new::&lt;Bech32m&gt;(s).is_err());
  38 <span class="macro">assert!</span>(SegwitHrpstring::new(s).is_err());
  39
  40 <span class="comment">// An arbitrary HRP, a string of valid bech32 characters, and a valid bech32 checksum.
  41 </span><span class="kw">let </span>s = <span class="string">"abcd14g08d6qejxtdg4y5r3zarvary0c5xw7kxugcx9"</span>;
  42 <span class="macro">assert!</span>(UncheckedHrpstring::new(s).is_ok());
  43 <span class="macro">assert!</span>(CheckedHrpstring::new::&lt;Bech32&gt;(s).is_ok());
  44 <span class="comment">// But not a valid segwit address.
  45 </span><span class="macro">assert!</span>(SegwitHrpstring::new(s).is_err());
  46 <span class="comment">// And not a valid bech32m checksum.
  47 </span><span class="macro">assert!</span>(CheckedHrpstring::new::&lt;Bech32m&gt;(s).is_err());
  48
  49 <span class="comment">// A valid Bitcoin taproot address.
  50 </span><span class="kw">let </span>s = <span class="string">"bc1pdp43hj65vxw49rts6kcw35u6r6tgzguyr03vvveeewjqpn05efzq7un9w0"</span>;
  51 <span class="macro">assert!</span>(UncheckedHrpstring::new(s).is_ok());
  52 <span class="macro">assert!</span>(CheckedHrpstring::new::&lt;Bech32m&gt;(s).is_ok());
  53 <span class="macro">assert!</span>(SegwitHrpstring::new(s).is_ok());
  54 <span class="comment">// But not a valid segwit v0 checksum.
  55 </span><span class="macro">assert!</span>(CheckedHrpstring::new::&lt;Bech32&gt;(s).is_err());
  56
  57 <span class="comment">// Get the HRP, witness version, and encoded data.
  58 </span><span class="kw">let </span>address = <span class="string">"bc1pdp43hj65vxw49rts6kcw35u6r6tgzguyr03vvveeewjqpn05efzq7un9w0"</span>;
  59 <span class="kw">let </span>segwit = SegwitHrpstring::new(address).expect(<span class="string">"valid segwit address"</span>);
  60 <span class="kw">let </span>_encoded_data = segwit.byte_iter();
  61 <span class="macro">assert_eq!</span>(segwit.hrp(), Hrp::parse(<span class="string">"bc"</span>).unwrap());
  62 <span class="macro">assert_eq!</span>(segwit.witness_version(), VERSION_1);</code></pre></div>
  63 </div></details><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.AsciiToFe32Iter.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::AsciiToFe32Iter">AsciiToFe32Iter</a></div><div class="desc docblock-short">Iterator adaptor that maps an iterator of valid bech32 character ASCII bytes to an
  64 iterator of field elements.</div></li><li><div class="item-name"><a class="struct" href="struct.ByteIter.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::ByteIter">ByteIter</a></div><div class="desc docblock-short">An iterator over a parsed HRP string data as bytes.</div></li><li><div class="item-name"><a class="struct" href="struct.CheckedHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::CheckedHrpstring">CheckedHrpstring</a></div><div class="desc docblock-short">An HRP string that has been parsed and had the checksum validated.</div></li><li><div class="item-name"><a class="struct" href="struct.CodeLengthError.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::CodeLengthError">CodeLengthError</a></div><div class="desc docblock-short">Encoding HRP and data into a bech32 string exceeds the checksum code length.</div></li><li><div class="item-name"><a class="struct" href="struct.Fe32Iter.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::Fe32Iter">Fe32Iter</a></div><div class="desc docblock-short">An iterator over a parsed HRP string data as field elements.</div></li><li><div class="item-name"><a class="struct" href="struct.SegwitCodeLengthError.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::SegwitCodeLengthError">SegwitCodeLengthError</a></div><div class="desc docblock-short">Encoding HRP, witver, and program into an address exceeds maximum allowed.</div></li><li><div class="item-name"><a class="struct" href="struct.SegwitHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::SegwitHrpstring">SegwitHrpstring</a></div><div class="desc docblock-short">An valid length HRP string that has been parsed, had the checksum validated, had the witness
  65 version validated, had the witness data length checked, and the had witness version and checksum
  66 removed.</div></li><li><div class="item-name"><a class="struct" href="struct.UncheckedHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::UncheckedHrpstring">UncheckedHrpstring</a></div><div class="desc docblock-short">An HRP string that has been parsed but not yet had the checksum checked.</div></li></ul><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="enum" href="enum.CharError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::CharError">CharError</a></div><div class="desc docblock-short">Character errors in a bech32 encoded string.</div></li><li><div class="item-name"><a class="enum" href="enum.CheckedHrpstringError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::CheckedHrpstringError">CheckedHrpstringError</a></div><div class="desc docblock-short">An error while constructing a <a href="struct.CheckedHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::CheckedHrpstring"><code>CheckedHrpstring</code></a> type.</div></li><li><div class="item-name"><a class="enum" href="enum.ChecksumError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::ChecksumError">ChecksumError</a></div><div class="desc docblock-short">Errors in the checksum of a bech32 encoded string.</div></li><li><div class="item-name"><a class="enum" href="enum.PaddingError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::PaddingError">PaddingError</a></div><div class="desc docblock-short">Error validating the padding bits on the witness data.</div></li><li><div class="item-name"><a class="enum" href="enum.SegwitHrpstringError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::SegwitHrpstringError">SegwitHrpstringError</a></div><div class="desc docblock-short">An error while constructing a <a href="struct.SegwitHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::SegwitHrpstring"><code>SegwitHrpstring</code></a> type.</div></li><li><div class="item-name"><a class="enum" href="enum.UncheckedHrpstringError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::UncheckedHrpstringError">UncheckedHrpstringError</a></div><div class="desc docblock-short">Errors when parsing a bech32 encoded string.</div></li></ul></section></div></main></body></html>