Add `Coinbase(Transaction)` newtype to distinguish coinbase transactions #4563

jrakibi · 2025-05-27T09:41:48Z

Coinbase transactions are structurally and semantically different from normal transactions.

We introduce a distinct Coinbase(Transaction) newtype to make this distinction explicit at the type level, helping to catch logic that shouldn't apply to coinbases (e.g attempting to look up coinbase inputs in the UTXO set).

This PR is split into several patches to keep changes reviewable and to document the rationale behind each step.

github-actions · 2025-05-27T09:43:18Z

🚨 API BREAKING CHANGE DETECTED

To see the changes click details on "Check semver breaks / PR Semver - stable toolchain" job then expand "Run semver checker script" and scroll to the end of the section.

coveralls · 2025-05-27T10:18:41Z

Pull Request Test Coverage Report for Build 15969096369

Details

116 of 122 (95.08%) changed or added relevant lines in 2 files are covered.
2 unchanged lines in 2 files lost coverage.
Overall coverage increased (+0.07%) to 83.611%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
bitcoin/src/blockdata/block.rs	93	99	93.94%

Files with Coverage Reduction	New Missed Lines	%
bitcoin/src/blockdata/transaction.rs	1	93.34%
bitcoin/src/psbt/mod.rs	1	86.65%

Totals
Change from base Build 15948098312:	0.07%
Covered Lines:	21397
Relevant Lines:	25591

💛 - Coveralls

tcharding · 2025-05-27T10:24:25Z

Why is this draft mate? Are you chasing concept ack or full review?

jrakibi · 2025-05-27T10:39:18Z

Why is this draft mate? Are you chasing concept ack or full review?

I just marked it as a draft to double-check a few things before opening it up. it's ready for full review now

tcharding

I'm going to give an unhelpful review: something doesn't quite feel right about this but I can't work out what. Perhaps one of the other fellas can shed light on it. The fact that we map all the errors using |_| is a hint I think. I'll re-review after the error variant thing is fixed, maybe something will fall out.

tcharding · 2025-05-28T07:52:54Z

bitcoin/src/blockdata/transaction.rs

+
+
+impl<'a> TryFrom<&'a Transaction> for &'a Coinbase {
+    type Error = CoinbaseError;


This error includes a variant that is never returned.

I feel like a better approach for error handling would be to rename Bip34Error to something more generic and use it for both methods: coinbase() and bip34_block_height()

That way I can have all error variants related to coinbase operations in one place instead of creating two separate error types !

In this repo we favour having exact errors that only include variants that are returned by the function.

Makes sense, thanks for the clarification

Kixunil

At minimum, I want the transparent_newtype macro to be used so that we don't have to burn brain power on thinking about unsafe. The remaining requests are fairly important though might be controversial.

Kixunil · 2025-05-30T16:52:10Z

bitcoin/src/blockdata/block.rs

+#[non_exhaustive]
+pub enum CoinbaseError {
+    /// Block has no transactions.
+    NoTransactions,


I guess this is acceptable for now but we really should have a type invariant that a block must have at least one tx.

Fixed
We're not using CoinbaseError anymore. Moved error handling to block-level validation with NoTransactions and InvalidCoinbase in InvalidBlockError instead of a separate CoinbaseError

Kixunil · 2025-05-30T16:53:22Z

bitcoin/src/blockdata/transaction.rs

+/// This type exists to distinguish coinbase transactions from regular ones at the type level.
+#[derive(Clone, PartialEq, Eq, Debug, Hash)]
+#[repr(transparent)]
+pub struct Coinbase(Transaction);


This needs to use the transparent_newtype macro from internals.

Kixunil · 2025-05-30T16:54:51Z

bitcoin/src/blockdata/transaction.rs

+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}


I'm not really convinced about this. It's generally an anti-pattern to do this kind of "inheritance". I'd rather conservatively remove it now and perhaps add it later if not having it is way too annoying (but most likely it's not correct to add it anyway).

Kixunil · 2025-05-30T16:57:47Z

bitcoin/src/blockdata/transaction.rs

+
+    fn try_from(tx: &'a Transaction) -> Result<Self, Self::Error> {
+        if tx.is_coinbase() {
+            Ok(unsafe { &*(tx as *const Transaction as *const Coinbase) })


transparent_newtype would avoid this.

Anyway, I'm not sure if we should have this impl. I think that being coinbase is more a property of a block rather than transaction. If we want to have a method I think it should be something like assume_first_transaction(tx: Transaction) -> Coinbase, and _ref for references.

Done! Used transparent_newtype macro and removed the try_from approach

Kixunil · 2025-05-30T17:07:38Z

bitcoin/src/blockdata/block.rs

@@ -315,7 +315,7 @@ impl BlockCheckedExt for Block<Checked> {
            return Err(Bip34Error::Unsupported);
        }

-        let cb = self.coinbase().map_err(|_| Bip34Error::NotPresent)?;
+        let cb = self.coinbase().map_err(|_| Bip34Error::NoCoinbase)?;


Thinking about it more, I think having a mostly-valid coinbase should be an invariant of Block. The only invalidity I'd allow is precisely BIP-34 check because that one requires block height which needs external information to check.

jrakibi · 2025-06-23T06:24:59Z

Apologise for the delay in addressing your feedback. I think all review comments have been addressed:

Used transparent_newtype macro for the Coinbase type, which eliminate unsafe concerns
Implemented block invariant validation - blocks must have at least one transaction, enforced during Block::validate() with NoTransactions and InvalidCoinbase error variants
Added assume_first_transaction & assume_first_transaction_ref methods as suggested
Separated error concerns - moved coinbase validation to block-level validation rather than adding variants to Bip34Error that would never be returned by BIP34 parsing
Made coinbase() infallible for checked blocks

apoelstra · 2025-06-23T19:27:33Z

bitcoin/src/blockdata/block.rs

+
+impl fmt::Display for CoinbaseError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        use CoinbaseError::*;


In 6dce354:

Please don't do wildcard imports like this. Just use Self:: prefixes on the variants in your match.

Noted. Also, I'm not using CoinbaseError anymore, I’ve already removed it

apoelstra · 2025-06-23T19:28:04Z

bitcoin/src/blockdata/transaction.rs

+
+impl Coinbase {
+    /// Computes the [`Txid`] of this coinbase transaction.
+    pub fn compute_txid(&self) -> Txid {


In 6dce354:

Why have these methods? They are available through Deref.

I've moved away from using implicit inheritance via Deref to avoid inheriting the entire Transaction API. Instead, we now expose only the methods that make sense for coinbase transactions.

inner() serves as an explicit escape hatch when full Transaction access is needed. This forces callers to be intentional about when they need the underlying Transaction functionalities.

Why shouldn't we inherit the entire Transaction API? A coinbase is a transaction.

apoelstra · 2025-06-23T19:30:26Z

primitives/src/block.rs

@@ -76,6 +76,12 @@ impl Block<Unchecked> {
        Block { header, transactions, witness_root: None, marker: PhantomData::<Unchecked> }
    }

+    /// Adds a transaction to the block.
+    #[inline]
+    pub fn push_transaction(&mut self, transaction: Transaction) {


In 1babd2c:

This method does not update the merkle root in the block header.

This method isn't used in this PR. Presumably you want to drop it, since adding it properly would be a bit involved (I guess we want to maintain at least the rightmost merkle path in the block?)

I think it fits better into block::Builder where the merkle root is only computed once all transactions were added.

apoelstra · 2025-06-23T19:35:12Z

Can you squash the review responses into the commits that they affect? It's very hard to review a "grab bag" commit of stuff that undoes changes from previous commits.

jrakibi · 2025-06-24T10:19:32Z

Thanks for the review.

I believe I’ve addressed all the feedback. You can also find the reasoning behind each change in the commit messages

tcharding · 2025-06-24T23:09:34Z

At minimum, I want the transparent_newtype macro to be used so that we don't have to burn brain power on thinking about unsafe

Being a mere mortal I cannot read that macro without devoting a whole bunch of time to it, which I don't want to right now but AFAICT the current usage does not enforce any invariants. So the Coinbase type also does not enforce the invariant that the inner Transaction is actually a coinbase transaction - is that what we want?

tcharding · 2025-06-24T23:11:10Z

bitcoin/src/blockdata/transaction.rs

+    /// Computes the [`Wtxid`] of this coinbase transaction.
+    pub fn compute_wtxid(&self) -> Wtxid {
+        self.0.compute_wtxid()
+    }


API suggestion:

/// Returns a reference to the inner transaction. pub fn as_inner(&self) -> &Transaction { &self.0 } /// Returns the inner transaction. pub fn into_inner(self) -> Transaction { self.0 }

ref: https://rust-lang.github.io/api-guidelines/naming.html

Good idea, added as_inner and into_inner as suggested
thanks for pointing to the guidelines

tcharding · 2025-06-24T23:11:43Z

bitcoin/src/blockdata/transaction.rs

+
+    impl Coinbase {
+        /// Creates a reference to `Coinbase` from a reference to the inner `Transaction`.
+        pub fn from_ref(inner: &_) -> &Self;


From looking at other call sites I think this should probably be from_transaction_ref.

Or if there is not supposed to be an invariant perhaps it should be from_first_transaction_ref or something (to match the naming of the other constructors).

There's definitely an invariant that the transaction is valid coinbase (including being zeroth in the block - something it cannot check). It wouldn't solve anything otherwise.

The name should be something like assume_coinbase_ref. It definitely needs the assume word (or unchecked but that is often used with UB). But I wonder if we need it to be public - it should only need to be called inside Block and some kind of CoinbaseBuilder.

I think it should be public. People will create coinbase transactions in all sorts of ways, including by reading them off the wire in ad-hoc mining protocols.

Renamed the method to assume_coinbase_ref to reflect that the caller must ensure it's a valid coinbase.

I Kept it public as per the feedback on ad-hoc mining protocols. Open to further changes if needed!

tcharding · 2025-06-29T22:48:24Z

Can you move the last commit into the commit that originally creates the function please mate.

This is repository specific, other repos may, and will, have different strategies. In this repo after review we make changes to the patch set and then force push. Its a reasonably common strategy, you should be able to find someone online explaining it. Or this prompt into opus gave me a pretty good response "when working on github with git why do some projects fix patches and force push instead of adding new patches onto the end after review".

Coinbase transactions have unique consensus rules and exceptions that distinguish them from regular txs. We represent them using a dedicated Coinbase(Transaction) new type We use the transparent_newtype macro from internals for safe reference conversion (&Transaction -> &Coinbase) without manual unsafe code also it automatically adds #[repr(transparent)] which guarantees that Coinbase has the exact same memory layout as Transaction

We provide explicit convenience methods (compute_txid, compute_wtxid) rather than implementing Deref to only expose methods that make sense for coinbase transactions. This prevents inheritance of the entire Transaction API. inner() serves as an escape hatch when full Transaction access is needed. This forces the user to be explicit about when they need the underlying Transaction functionalities. Following this approach, we avoid implicit inheritance through Deref. We also added assume_* methods to make it clear that the caller is responsible for ensuring the transaction is actually a coinbase transaction in the first position of a block

…action> This change has semantic meaning: it guarantees that every checked Block has a coinbase as its first transaction. The method is now infallible for validated blocks.

Add validation checks to Block::validate() to ensure blocks have a valid coinbase: - Check for empty transaction list (NoTransactions error) - Verify first transaction is coinbase (InvalidCoinbase error) The validation now happens during Block::validate() rather than requiring every caller to check coinbase presence separately.

Remove unnecessary error handling from bip34_block_height since coinbase() now returns &Coinbase instead of Option<&Transaction>. Use cb.inner() to access the underlying Transaction fields for input processing.

Add thorough test coverage for the new Coinbase type and validation logic

jrakibi · 2025-06-30T09:26:21Z

Can you move the last commit into the commit that originally creates the function please mate.

Done

This is repository specific, other repos may, and will, have different strategies. ...

Appreciate the time you take to explain these best practices

tcharding · 2025-06-30T22:32:02Z

bitcoin/src/blockdata/block.rs

-    /// Returns the coinbase transaction, if one is present.
-    fn coinbase(&self) -> Option<&Transaction> { self.transactions().first() }
+    /// Returns the coinbase transaction.
+    ///
+    /// This method is infallible because validation ensures a valid coinbase transaction is always present.
+    fn coinbase(&self) -> &Coinbase {


nit: On the trait method impls we don't need to repeat the docs. If you are keen you could add a patch at the front that removes the original line also the one on bip34_block_height.

In ba5fb26

tcharding

ACK 23ef6c4

tcharding · 2025-06-30T22:35:24Z

This has shaped up to be a nice PR.

Process comment: I ack'd so you can leave it as is if you want. Or you can see to the nit if you want to. Its trivial for me to re-ack since I posted the commit hash and can use git range-diff to see any changes you force push on their own.

Changes seen to already.

Kixunil · 2025-07-01T08:46:28Z

bitcoin/src/blockdata/transaction.rs

+    ///
+    /// This method does not validate that the transaction is actually a coinbase transaction.
+    /// The caller must ensure that this transaction is indeed the first transaction in a valid block.
+    pub fn assume_first_transaction(tx: Transaction) -> Self {


This should be just assume_coinbase. Coinbase has more validity requirements than just being the first, so simply saying "first" is misleading and enumerating all of them in the method name would make the name insanely long.

Kixunil · 2025-07-01T08:47:04Z

bitcoin/src/blockdata/transaction.rs

+    /// The caller must ensure that this transaction is indeed the first transaction in a valid block.
+    pub fn assume_first_transaction_ref(tx: &Transaction) -> &Self {
+        Self::assume_coinbase_ref(tx)
+    }


This isn't needed, the assume_coinbase_ref method already exists.

Kixunil · 2025-07-01T08:48:03Z

bitcoin/src/blockdata/transaction.rs

+    }
+
+    /// Returns a reference to the inner transaction.
+    pub fn as_inner(&self) -> &Transaction { &self.0 }


Do we want this name here? Maybe as_transaction or as_any_transaction or something along these lines?

I could go either way on this. Leaning toward agreeing with you since we've generally moved away from *_inner naming in this library.

Whatever we choose we should doc-alias it to the other.

Kixunil · 2025-07-01T08:49:08Z

bitcoin/src/blockdata/transaction.rs

+    }
+
+    /// Computes the [`Wtxid`] of this coinbase transaction.
+    pub fn compute_wtxid(&self) -> Wtxid {


IIRC coinbase transactions have a constant Wtxid so this method looks misleading and probably shouldn't exist.

Agreed, let's put just wtxid here but make sure there's a doc(alias="compute_wtxid"). I'm not sure if the compiler is smart enough to make use of doc aliases in its error messages.

Kixunil · 2025-07-01T08:50:24Z

bitcoin/src/blockdata/transaction.rs

+        Self::assume_coinbase_ref(tx)
+    }
+
+    /// Returns a reference to the inner transaction.


Perhaps should contain a disclaimer that accessing this might enable nonsensical usage.

How could it? A coinbase is a transaction.

Kixunil · 2025-07-01T08:52:53Z

bitcoin/src/blockdata/block.rs

+            return Err(InvalidBlockError::NoTransactions);
+        }
+
+        if !transactions[0].is_coinbase() {


FTR, perhaps the method name should be changed to looks_like_coinbase.

I think is_coinbase is fine. Though I think we should have an explicit conversion method that does Transaction -> Coinbase and this should be redefined just as self.to_coinbase().is_ok().

In principle any coinbase-looking transaction "is a coinbase" in the sense that you could make a block with it as the first transaction.

Kixunil · 2025-07-01T08:55:15Z

bitcoin/src/blockdata/block.rs

-        let cb = self.coinbase().ok_or(Bip34Error::NotPresent)?;
-        let input = cb.input.first().ok_or(Bip34Error::NotPresent)?;
+        let cb = self.coinbase();
+        let input = cb.as_inner().input.first().ok_or(Bip34Error::NotPresent)?;


As I understand it this commit is not standalone and thus a previous one will not compile. We require that each commit can be compiled so that git bisect can be used reliably.

Kixunil

At minimum, the compile error needs to be fixed.

github-actions bot added C-bitcoin PRs modifying the bitcoin crate C-primitives labels May 27, 2025

jrakibi marked this pull request as draft May 27, 2025 09:42

github-actions bot added the API break This PR requires a version bump for the next release label May 27, 2025

jrakibi marked this pull request as ready for review May 27, 2025 10:39

tcharding reviewed May 28, 2025

View reviewed changes

jrakibi mentioned this pull request May 30, 2025

Should we add a new NotCoinbase variant to Bip34Error? #4543

Open

Kixunil previously requested changes May 30, 2025

View reviewed changes

apoelstra reviewed Jun 23, 2025

View reviewed changes

jrakibi force-pushed the 26-06-add-coinbase-type branch from 7dfd510 to dfc9c4b Compare June 24, 2025 10:00

github-actions bot removed the C-primitives label Jun 24, 2025

tcharding reviewed Jun 24, 2025

View reviewed changes

jrakibi force-pushed the 26-06-add-coinbase-type branch from dfc9c4b to 0abadc3 Compare June 29, 2025 11:15

jrakibi added 6 commits June 30, 2025 17:08

Change Block::coinbase() to return &Coinbase instead of Option<&Trans…

ba5fb26

…action> This change has semantic meaning: it guarantees that every checked Block has a coinbase as its first transaction. The method is now infallible for validated blocks.

Update bip34_block_height to work with new Coinbase type

02f915e

Remove unnecessary error handling from bip34_block_height since coinbase() now returns &Coinbase instead of Option<&Transaction>. Use cb.inner() to access the underlying Transaction fields for input processing.

Add comprehensive tests for Coinbase type and block validation

23ef6c4

Add thorough test coverage for the new Coinbase type and validation logic

jrakibi force-pushed the 26-06-add-coinbase-type branch from 42d5517 to 23ef6c4 Compare June 30, 2025 09:24

tcharding reviewed Jun 30, 2025

View reviewed changes

tcharding approved these changes Jun 30, 2025

View reviewed changes

Kixunil reviewed Jul 1, 2025

View reviewed changes

Kixunil requested changes Jul 1, 2025

View reviewed changes



		impl<'a> TryFrom<&'a Transaction> for &'a Coinbase {
		type Error = CoinbaseError;

Add Coinbase(Transaction) newtype to distinguish coinbase transactions #4563

Are you sure you want to change the base?

Add Coinbase(Transaction) newtype to distinguish coinbase transactions #4563

Uh oh!

Conversation

jrakibi commented May 27, 2025

Uh oh!

github-actions bot commented May 27, 2025

Uh oh!

coveralls commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 15969096369

Details

💛 - Coveralls

Uh oh!

tcharding commented May 27, 2025

Uh oh!

jrakibi commented May 27, 2025

Uh oh!

tcharding left a comment

Choose a reason for hiding this comment

Uh oh!

tcharding May 28, 2025 • 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!

Kixunil left a comment

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!

Choose a reason for hiding this comment

Uh oh!

jrakibi commented Jun 23, 2025

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!

apoelstra commented Jun 23, 2025

Uh oh!

jrakibi commented Jun 24, 2025

Uh oh!

tcharding commented Jun 24, 2025

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

Add `Coinbase(Transaction)` newtype to distinguish coinbase transactions #4563

Add `Coinbase(Transaction)` newtype to distinguish coinbase transactions #4563

coveralls commented May 27, 2025 •

edited

Loading

tcharding May 28, 2025 •

edited

Loading