monero_oxide/
block.rs

1use std_shims::{
2  vec,
3  vec::Vec,
4  io::{self, Read, Write},
5};
6
7use crate::{
8  io::*,
9  primitives::{UpperBound, keccak256},
10  merkle::merkle_root,
11  transaction::{Input, Transaction},
12};
13
14pub(crate) const CORRECT_BLOCK_HASH_202612: [u8; 32] =
15  hex_literal::hex!("426d16cff04c71f8b16340b722dc4010a2dd3831c22041431f772547ba6e331a");
16pub(crate) const EXISTING_BLOCK_HASH_202612: [u8; 32] =
17  hex_literal::hex!("bbd604d2ba11ba27935e006ed39c9bfdd99b76bf4a50654bc1e1e61217962698");
18
19/// A Monero block's header.
20#[derive(Clone, PartialEq, Eq, Debug)]
21pub struct BlockHeader {
22  /// The hard fork of the protocol this block follows.
23  ///
24  /// Per the C++ codebase, this is the `major_version`.
25  pub hardfork_version: u8,
26  /// A signal for a proposed hard fork.
27  ///
28  /// Per the C++ codebase, this is the `minor_version`.
29  pub hardfork_signal: u8,
30  /// Seconds since the epoch.
31  pub timestamp: u64,
32  /// The previous block's hash.
33  pub previous: [u8; 32],
34  /// The nonce used to mine the block.
35  ///
36  /// Miners should increment this while attempting to find a block with a hash satisfying the PoW
37  /// rules.
38  pub nonce: u32,
39}
40
41impl BlockHeader {
42  /// The upper bound for a block header's size.
43  pub const SIZE_UPPER_BOUND: UpperBound<usize> = UpperBound(
44    <u8 as VarInt>::UPPER_BOUND +
45      <u8 as VarInt>::UPPER_BOUND +
46      <u64 as VarInt>::UPPER_BOUND +
47      32 +
48      4,
49  );
50
51  /// Write the BlockHeader.
52  pub fn write<W: Write>(&self, w: &mut W) -> io::Result<()> {
53    VarInt::write(&self.hardfork_version, w)?;
54    VarInt::write(&self.hardfork_signal, w)?;
55    VarInt::write(&self.timestamp, w)?;
56    w.write_all(&self.previous)?;
57    w.write_all(&self.nonce.to_le_bytes())
58  }
59
60  /// Serialize the BlockHeader to a `Vec<u8>`.
61  pub fn serialize(&self) -> Vec<u8> {
62    let mut serialized = vec![];
63    self.write(&mut serialized).expect("write failed but <Vec as io::Write> doesn't fail");
64    serialized
65  }
66
67  /// Read a BlockHeader.
68  pub fn read<R: Read>(r: &mut R) -> io::Result<BlockHeader> {
69    Ok(BlockHeader {
70      hardfork_version: VarInt::read(r)?,
71      hardfork_signal: VarInt::read(r)?,
72      timestamp: VarInt::read(r)?,
73      previous: read_bytes(r)?,
74      nonce: read_bytes(r).map(u32::from_le_bytes)?,
75    })
76  }
77}
78
79/// A Monero block.
80#[derive(Clone, PartialEq, Eq, Debug)]
81#[expect(clippy::partial_pub_fields)]
82pub struct Block {
83  /// The block's header.
84  pub header: BlockHeader,
85  /// The miner's transaction.
86  ///
87  /// This is private so we can ensure [`Block::number`] is infallible.
88  miner_transaction: Transaction,
89  /// The transactions within this block.
90  pub transactions: Vec<[u8; 32]>,
91}
92
93impl Block {
94  /// The maximum amount of transactions a block may have, including the miner transaction.
95  /*
96    Definition of maximum amount of transaction:
97    https://github.com/monero-project/monero
98      /blob/8d4c625713e3419573dfcc7119c8848f47cabbaa/src/cryptonote_config.h#L42
99
100    Limitation of the amount of transactions within the `transactions` field:
101    https://github.com/monero-project/monero
102      /blob/8d4c625713e3419573dfcc7119c8848f47cabbaa/src/cryptonote_basic/cryptonote_basic.h#L571
103
104    This would mean the actual limit is `0x10000000 + 1`, including the miner transaction, except:
105    https://github.com/monero-project/monero
106      /blob/8d4c625713e3419573dfcc7119c8848f47cabbaa/src/crypto/tree-hash.c#L55
107
108    calculation of the Merkle tree representing all transactions will fail if this many
109    transactions is consumed by the `transactions` field alone.
110  */
111  pub const MAX_TRANSACTIONS: usize = 0x1000_0000;
112
113  /// Construct a new `Block`.
114  ///
115  /// This MAY apply miscellaneous consensus rules as useful for the sanity of working with this
116  /// type. The result is not guaranteed to follow all Monero consensus rules or any specific set
117  /// of consensus rules.
118  pub fn new(
119    header: BlockHeader,
120    miner_transaction: Transaction,
121    transactions: Vec<[u8; 32]>,
122  ) -> Option<Block> {
123    // Check this correctly defines the block's number
124    // https://github.com/monero-project/monero/blob/a1dc85c5373a30f14aaf7dcfdd95f5a7375d3623
125    //   /src/cryptonote_core/blockchain.cpp#L1365-L1382
126    {
127      let inputs = &miner_transaction.prefix().inputs;
128      if inputs.len() != 1 {
129        None?;
130      }
131      match inputs[0] {
132        Input::Gen(_number) => {}
133        Input::ToKey { .. } => None?,
134      }
135    }
136
137    Some(Block { header, miner_transaction, transactions })
138  }
139
140  /// The zero-indexed position of this block within the blockchain.
141  pub fn number(&self) -> usize {
142    match &self.miner_transaction {
143      Transaction::V1 { prefix, .. } | Transaction::V2 { prefix, .. } => {
144        match prefix.inputs.first() {
145          Some(Input::Gen(number)) => *number,
146          _ => panic!("invalid miner transaction accepted into block"),
147        }
148      }
149    }
150  }
151
152  /// The block's miner's transaction.
153  pub fn miner_transaction(&self) -> &Transaction {
154    &self.miner_transaction
155  }
156
157  /// Write the Block.
158  pub fn write<W: Write>(&self, w: &mut W) -> io::Result<()> {
159    self.header.write(w)?;
160    self.miner_transaction.write(w)?;
161    VarInt::write(&self.transactions.len(), w)?;
162    for tx in &self.transactions {
163      w.write_all(tx)?;
164    }
165    Ok(())
166  }
167
168  /// Serialize the Block to a `Vec<u8>`.
169  pub fn serialize(&self) -> Vec<u8> {
170    let mut serialized = vec![];
171    self.write(&mut serialized).expect("write failed but <Vec as io::Write> doesn't fail");
172    serialized
173  }
174
175  /// Serialize the block as generally required for the proof of work hash.
176  ///
177  /// This is distinct from the serialization required for the block hash. To get the block hash,
178  /// use the [`Block::hash`] function.
179  ///
180  /// Please note that for block #202,612, regardless of the network, the proof of work hash will
181  /// be fixed to a specific value and this preimage will be irrelevant.
182  pub fn serialize_pow_hash(&self) -> Vec<u8> {
183    let mut blob = self.header.serialize();
184
185    let mut transactions = Vec::with_capacity(self.transactions.len() + 1);
186    transactions.push(self.miner_transaction.hash());
187    transactions.extend_from_slice(&self.transactions);
188
189    blob.extend_from_slice(
190      &merkle_root(transactions)
191        .expect("the tree will not be empty, the miner tx is always present"),
192    );
193    VarInt::write(&(1 + self.transactions.len()), &mut blob)
194      .expect("write failed but <Vec as io::Write> doesn't fail");
195    blob
196  }
197
198  /// Get the hash of this block.
199  pub fn hash(&self) -> [u8; 32] {
200    let mut hashable = self.serialize_pow_hash();
201    // Monero pre-appends a VarInt of the block-to-hash's length before getting the block hash,
202    // but doesn't do this when getting the proof of work hash :)
203    let mut hashing_blob = Vec::with_capacity(<usize as VarInt>::UPPER_BOUND + hashable.len());
204    VarInt::write(
205      &u64::try_from(hashable.len()).expect("length of block hash's preimage exceeded u64::MAX"),
206      &mut hashing_blob,
207    )
208    .expect("write failed but <Vec as io::Write> doesn't fail");
209    hashing_blob.append(&mut hashable);
210
211    let hash = keccak256(hashing_blob);
212    // https://github.com/monero-project/monero/blob/8e9ab9677f90492bca3c7555a246f2a8677bd570
213    //   /src/cryptonote_basic/cryptonote_format_utils.cpp#L1468-L1477
214    if hash == CORRECT_BLOCK_HASH_202612 {
215      return EXISTING_BLOCK_HASH_202612;
216    }
217    hash
218  }
219
220  /// Read a Block.
221  ///
222  /// This MAY error if miscellaneous Monero conseusus rules are broken, as useful when
223  /// deserializing. The result is not guaranteed to follow all Monero consensus rules or any
224  /// specific set of consensus rules.
225  pub fn read<R: Read>(r: &mut R) -> io::Result<Block> {
226    let header = BlockHeader::read(r)?;
227
228    let miner_transaction = Transaction::read(r)?;
229
230    let transactions: usize = VarInt::read(r)?;
231    if transactions >= Self::MAX_TRANSACTIONS {
232      Err(io::Error::other("amount of transaction exceeds limit"))?;
233    }
234    let transactions = (0 .. transactions).map(|_| read_bytes(r)).collect::<Result<_, _>>()?;
235
236    Block::new(header, miner_transaction, transactions)
237      .ok_or_else(|| io::Error::other("block failed sanity checks"))
238  }
239}
monero_oxide/block.rs

monero_oxide/
block.rs
