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-6b053e98.ttf.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.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-9960930a.css"><link rel="stylesheet" href="../../../../../static.files/rustdoc-5d1d17d0.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.86.0-nightly (f3d1d47fd 2025-01-20)" data-channel="nightly" data-search-js="search-ccb196c1.js" data-settings-js="settings-0f613d39.js" ><script src="../../../../../static.files/storage-59e33391.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../../../../static.files/main-5f194d8c.js"></script><noscript><link rel="stylesheet" href="../../../../../static.files/noscript-893ab5e7.css"></noscript><link rel="alternate icon" type="image/png" href="../../../../../static.files/favicon-32x32-6580c154.png"><link rel="icon" type="image/svg+xml" href="../../../../../static.files/favicon-044be391.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_<wbr>chain</a><span class="version">0.21.1</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Module decode</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#details" title="Details">Details</a></li><li><a href="#examples" title="Examples">Examples</a></li></ul><h3><a href="#structs">Module Items</a></h3><ul class="block"><li><a href="#structs" title="Structs">Structs</a></li><li><a href="#enums" title="Enums">Enums</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="../index.html">In bdk_<wbr>chain::<wbr>bitcoin::<wbr>bech32::<wbr>primitives</a></h2></div></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"><span class="rustdoc-breadcrumbs"><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></span><h1>Module <span>decode</span><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"></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>
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>
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>
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>
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;
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::<Bech32>(s).is_err());
37 <span class="macro">assert!</span>(CheckedHrpstring::new::<Bech32m>(s).is_err());
38 <span class="macro">assert!</span>(SegwitHrpstring::new(s).is_err());
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::<Bech32>(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::<Bech32m>(s).is_err());
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::<Bech32m>(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::<Bech32>(s).is_err());
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><dl class="item-table"><dt><a class="struct" href="struct.AsciiToFe32Iter.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::AsciiToFe32Iter">Ascii<wbr>ToFe32<wbr>Iter</a></dt><dd>Iterator adaptor that maps an iterator of valid bech32 character ASCII bytes to an
64 iterator of field elements.</dd><dt><a class="struct" href="struct.ByteIter.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::ByteIter">Byte<wbr>Iter</a></dt><dd>An iterator over a parsed HRP string data as bytes.</dd><dt><a class="struct" href="struct.CheckedHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::CheckedHrpstring">Checked<wbr>Hrpstring</a></dt><dd>An HRP string that has been parsed and had the checksum validated.</dd><dt><a class="struct" href="struct.CodeLengthError.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::CodeLengthError">Code<wbr>Length<wbr>Error</a></dt><dd>Encoding HRP and data into a bech32 string exceeds the checksum code length.</dd><dt><a class="struct" href="struct.Fe32Iter.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::Fe32Iter">Fe32<wbr>Iter</a></dt><dd>An iterator over a parsed HRP string data as field elements.</dd><dt><a class="struct" href="struct.SegwitCodeLengthError.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::SegwitCodeLengthError">Segwit<wbr>Code<wbr>Length<wbr>Error</a></dt><dd>Encoding HRP, witver, and program into an address exceeds maximum allowed.</dd><dt><a class="struct" href="struct.SegwitHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::SegwitHrpstring">Segwit<wbr>Hrpstring</a></dt><dd>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.</dd><dt><a class="struct" href="struct.UncheckedHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::UncheckedHrpstring">Unchecked<wbr>Hrpstring</a></dt><dd>An HRP string that has been parsed but not yet had the checksum checked.</dd></dl><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><dl class="item-table"><dt><a class="enum" href="enum.CharError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::CharError">Char<wbr>Error</a></dt><dd>Character errors in a bech32 encoded string.</dd><dt><a class="enum" href="enum.CheckedHrpstringError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::CheckedHrpstringError">Checked<wbr>Hrpstring<wbr>Error</a></dt><dd>An error while constructing a <a href="struct.CheckedHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::CheckedHrpstring"><code>CheckedHrpstring</code></a> type.</dd><dt><a class="enum" href="enum.ChecksumError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::ChecksumError">Checksum<wbr>Error</a></dt><dd>Errors in the checksum of a bech32 encoded string.</dd><dt><a class="enum" href="enum.PaddingError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::PaddingError">Padding<wbr>Error</a></dt><dd>Error validating the padding bits on the witness data.</dd><dt><a class="enum" href="enum.SegwitHrpstringError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::SegwitHrpstringError">Segwit<wbr>Hrpstring<wbr>Error</a></dt><dd>An error while constructing a <a href="struct.SegwitHrpstring.html" title="struct bdk_chain::bitcoin::bech32::primitives::decode::SegwitHrpstring"><code>SegwitHrpstring</code></a> type.</dd><dt><a class="enum" href="enum.UncheckedHrpstringError.html" title="enum bdk_chain::bitcoin::bech32::primitives::decode::UncheckedHrpstringError">Unchecked<wbr>Hrpstring<wbr>Error</a></dt><dd>Errors when parsing a bech32 encoded string.</dd></dl></section></div></main></body></html>
projects / bitcoindevkit.org / blob