docs: add amount example for units crate by Zeegaths · Pull Request #43 · rust-bitcoin/rust-bitcoin.github.io

Zeegaths · 2026-03-12T14:58:50Z

Add cookbook entry for Amount covering the "Amount" section from #4694.

What it covers:

Justifies the MAX = 21 million decision
Demonstrates creating amounts using constants (MAX, ONE_BTC, ONE_SAT, ZERO, FIFTY_BTC)
Explains result handling differences between from_sat_u32 and from_sat
Demonstrates parsing amounts from strings using parse
Covers formatting with display_in, display_dynamic, and the alloc-gated string methods
Shows basic NumOpResult usage with arithmetic and underflow handling

Closes the "Amount" section of #4694.

cookbook/src/units/amount.md

apoelstra · 2026-03-14T20:43:28Z

cookbook/src/units/amount.md

+
+**Setup**
+
+If using `rust-bitcoin`, `Amount` is re-exported automatically:


In 1ede28e:

I'd drop the word "automatically" and maybe drop the prefix "re-".

cookbook/src/units/amount.md

apoelstra · 2026-03-14T20:47:43Z

Overall this looks amazing, thanks! I just commented a few nits.

Zeegaths · 2026-03-15T13:14:45Z

Overall this looks amazing, thanks! I just commented a few nits.

Thanks for this! made the changes. I could pick up the rest of the docs?

tcharding · 2026-03-15T22:37:30Z

Thanks for the contribution.

I could pick up the rest of the docs?

I'll review quite heavily then so that it saves you time on the next ones.

tcharding · 2026-03-15T22:38:17Z

cookbook/src/units/amount.md

@@ -0,0 +1,168 @@
+# Amount
+
+In this section, we will demonstrate different ways of working with Bitcoin amounts using the `Amount` type. The examples in this section will:


I think we should try to use little 'b' for the currency and big 'B' for the network.

tcharding · 2026-03-15T22:40:06Z

cookbook/src/units/amount.md

+    let zero = Amount::ZERO;
+    println!("Zero amount: {} satoshis", zero.to_sat());
+
+    // No result handling for small amounts


Suggested change

// No result handling for small amounts

// No result handling for small amounts.

tcharding · 2026-03-15T22:40:38Z

cookbook/src/units/amount.md

+    // Result handling for larger amounts
+    let large = Amount::from_sat(100_000_000).expect("valid amount");
+    println!("Large Amount = {}", large);
+


Perhaps something like this is better?

// The amount constructor errors if input value is to large. let large = Amount::from_sat(100_000_000).expect("valid amount"); println!("Large Amount = {}", large); // Error free construction for amounts under approx 42 BTC ([u32::MAX]). let small = Amount::from_sat_u32(50_000); println!("Small Amount = {}", small);

tcharding · 2026-03-15T22:41:13Z

cookbook/src/units/amount.md

+    let large = Amount::from_sat(100_000_000).expect("valid amount");
+    println!("Large Amount = {}", large);
+
+    // Parsing string type to Amount - result handling needed for potential error


Everything that is code needs back ticks. Here Amount and a bunch of function names elsewhere.

tcharding · 2026-03-15T22:42:13Z

cookbook/src/units/amount.md

+        Amount::ONE_BTC.display_in(Denomination::Bitcoin).show_denomination()
+    );
+    println!(
+        "Display in Satoshi with denomination: {}",


Lower case 's' for currency. Also I believe it should be pluralized 'Display in satoshis ...'

tcharding · 2026-03-15T22:42:38Z

cookbook/src/units/amount.md

+    println!("Display dynamic: {}", Amount::ONE_SAT.display_dynamic()); // shows in satoshis
+    println!("Display dynamic: {}", Amount::ONE_BTC.display_dynamic()); // shows in BTC
+
+    // to_string_in and to_string_with_denomination require alloc feature


Suggested change

// to_string_in and to_string_with_denomination require alloc feature

// `to_string_in` and `to_string_with_denomination` both require the `alloc` feature.

tcharding · 2026-03-15T22:45:46Z

cookbook/src/units/amount.md

+**Parsing and Formatting**
+
+When parsing small amounts, result handling is not strictly necessary unless 
+you want extra caution. We use `.expect()` to handle results for larger amounts.


Did you use an LLM to create these docs or create them yourself?

tcharding · 2026-03-15T22:46:34Z

cookbook/src/units/amount.md

+When formatting output, the preferred method is `.display_in()`. It can be 
+combined with `fmt::Formatter` options to precisely control zeros, padding, and 
+alignment — similar to how floats work in `core`, except that it's more precise, 
+meaning no rounding occurs. It also works without `alloc`, making it suitable for 
+`no_std` environments such as hardware wallets or embedded signing devices.


This sounds like LLM output to me and not super useful for a user who is coding at a level that they would read the cookbook.

tcharding · 2026-03-15T22:47:19Z

cookbook/src/units.md

@@ -0,0 +1,21 @@
+Bitcoin is majorly expressed as BTC(bitcoins), mBTC(millibitcoins), sats(satoshis) or bits.


I'm not keen on this line. Because of the wording: 'majorly express in'. But I rekon better to just mention sats and BTC, but that could be subjective.

I think "usually expressed in" is more idiomotic English.

BTW, these weird expressions make me think this is not LLM output. Though I agree that it often explains things that are too basic to be worth explaining.

tcharding · 2026-03-15T22:49:12Z

cookbook/src/units.md

+The BTC unit represents a 10^8 value so as to have sub-unit precision instead of large whole numbers.
+This allows divisions of 1/10th, 1/100th and so on.


This whole sentence is a bit odd IMO.

tcharding · 2026-03-15T22:50:29Z

cookbook/src/units.md

+
+The satoshi, named after the original bitcoin creator, Satoshi Nakamoto, is the smallest unit of bitcoin currency representing a hundred millionth of one Bitcoin (0.00000001 BTC).
+
+The Bitcoin source code uses satoshi to specify any Bitcoin amount and all amounts on the blockchain are denominated in satoshi before they get converted for display.


Are we documenting the protocol or the rust-bitcoin lib, its not obvious to me from some of these docs which direction we are going in?

I kinda liked these two sentences. Yes, they're "off-topic" in that they're about the protocol rather than this library, but they're useful context for why we have such a weird and large API for Amount.

apoelstra · 2026-03-16T18:02:04Z

Sigh. Guess you were right @tcharding

I wonder if it makes sense to move this repo to Forgejo....we hadn't really considered stopping hosting rust-bitcoin.org on Github. On the one hand, self-hosting a website is pretty-much the easiest thing we can do. On the other hand it's still kinda a PITA.

apoelstra reviewed Mar 14, 2026

View reviewed changes

cookbook/src/units/amount.md Outdated Show resolved Hide resolved

apoelstra reviewed Mar 14, 2026

View reviewed changes

cookbook/src/units/amount.md Show resolved Hide resolved

docs: add amount example for units crate

e1c8a0c

Zeegaths force-pushed the docs-amount-example branch from 1ede28e to e1c8a0c Compare March 15, 2026 13:04

tcharding reviewed Mar 15, 2026

View reviewed changes

Zeegaths closed this Mar 16, 2026


		Setup

		If using `rust-bitcoin`, `Amount` is re-exported automatically:

		@@ -0,0 +1,168 @@
		# Amount

		In this section, we will demonstrate different ways of working with Bitcoin amounts using the `Amount` type. The examples in this section will:

	// No result handling for small amounts
	// No result handling for small amounts.

	// to_string_in and to_string_with_denomination require alloc feature
	// `to_string_in` and `to_string_with_denomination` both require the `alloc` feature.

		@@ -0,0 +1,21 @@
		Bitcoin is majorly expressed as BTC(bitcoins), mBTC(millibitcoins), sats(satoshis) or bits.

		The BTC unit represents a 10^8 value so as to have sub-unit precision instead of large whole numbers.
		This allows divisions of 1/10th, 1/100th and so on.


		The satoshi, named after the original bitcoin creator, Satoshi Nakamoto, is the smallest unit of bitcoin currency representing a hundred millionth of one Bitcoin (0.00000001 BTC).

		The Bitcoin source code uses satoshi to specify any Bitcoin amount and all amounts on the blockchain are denominated in satoshi before they get converted for display.

Conversation

Zeegaths commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

apoelstra Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

apoelstra commented Mar 14, 2026

Uh oh!

Zeegaths commented Mar 15, 2026

Uh oh!

tcharding commented Mar 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tcharding Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apoelstra commented Mar 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Zeegaths commented Mar 12, 2026 •

edited

Loading

apoelstra Mar 14, 2026 •

edited

Loading

tcharding Mar 15, 2026 •

edited

Loading