// Copyright 2019-2026 ChainSafe Systems
// SPDX-License-Identifier: Apache-2.0, MIT
use std::sync::{
OnceLock,
atomic::{AtomicBool, Ordering},
};
use super::{ElectionProof, Error, Ticket, TipsetKey};
use crate::{
beacon::{Beacon as _, BeaconEntry, BeaconSchedule},
shim::{
address::Address, clock::ChainEpoch, crypto::Signature, econ::TokenAmount,
sector::PoStProof, version::NetworkVersion,
},
utils::{encoding::blake2b_256, get_size::big_int_heap_size_helper, multihash::MultihashCode},
};
use cid::Cid;
use fvm_ipld_blockstore::Blockstore;
use fvm_ipld_encoding::CborStore as _;
use fvm_ipld_encoding::tuple::*;
use get_size2::GetSize;
use multihash_derive::MultihashDigest as _;
use num::BigInt;
use serde::{Deserialize, Serialize};
#[cfg(test)]
mod test;
#[cfg(test)]
pub use test::*;
#[derive(Deserialize_tuple, Serialize_tuple, Clone, Hash, Eq, PartialEq, Debug)]
pub struct RawBlockHeader {
/// The address of the miner actor that mined this block
pub miner_address: Address,
pub ticket: Option<Ticket>,
pub election_proof: Option<ElectionProof>,
/// The verifiable oracle randomness used to elect this block's author leader
pub beacon_entries: Vec<BeaconEntry>,
pub winning_post_proof: Vec<PoStProof>,
/// The set of parents this block was based on.
/// Typically one, but can be several in the case where there were multiple
/// winning ticket-holders for an epoch
pub parents: TipsetKey,
/// The aggregate chain weight of the parent set
#[serde(with = "crate::shim::fvm_shared_latest::bigint::bigint_ser")]
pub weight: BigInt,
/// The period in which a new block is generated.
/// There may be multiple rounds in an epoch.
pub epoch: ChainEpoch,
/// The CID of the parent state root after calculating parent tipset.
pub state_root: Cid,
/// The CID of the root of an array of `MessageReceipts`
pub message_receipts: Cid,
/// The CID of the Merkle links for `bls_messages` and `secp_messages`
pub messages: Cid,
/// Aggregate signature of miner in block
pub bls_aggregate: Option<Signature>,
/// Block creation time, in seconds since the Unix epoch
pub timestamp: u64,
pub signature: Option<Signature>,
pub fork_signal: u64,
/// The base fee of the parent block
pub parent_base_fee: TokenAmount,
}
impl RawBlockHeader {
pub fn cid(&self) -> Cid {
self.car_block().expect("CBOR serialization failed").0
}
pub fn car_block(&self) -> anyhow::Result<(Cid, Vec<u8>)> {
let data = fvm_ipld_encoding::to_vec(self)?;
let cid = Cid::new_v1(
fvm_ipld_encoding::DAG_CBOR,
MultihashCode::Blake2b256.digest(&data),
);
Ok((cid, data))
}
pub(super) fn tipset_sort_key(&self) -> Option<([u8; 32], Vec<u8>)> {
let ticket_hash = blake2b_256(self.ticket.as_ref()?.vrfproof.as_bytes());
Some((ticket_hash, self.cid().to_bytes()))
}
/// Check to ensure block signature is valid
pub fn verify_signature_against(&self, addr: &Address) -> Result<(), Error> {
let signature = self
.signature
.as_ref()
.ok_or_else(|| Error::InvalidSignature("Signature is nil in header".into()))?;
signature.verify(&self.signing_bytes(), addr).map_err(|e| {
Error::InvalidSignature(format!("Block signature invalid: {e:#}").into())
})?;
Ok(())
}
/// Validates if the current header's Beacon entries are valid to ensure
/// randomness was generated correctly
pub fn validate_block_drand(
&self,
network_version: NetworkVersion,
b_schedule: &BeaconSchedule,
parent_epoch: ChainEpoch,
prev_entry: &BeaconEntry,
) -> Result<(), Error> {
let (cb_epoch, curr_beacon) = b_schedule
.beacon_for_epoch(self.epoch)
.map_err(|e| Error::Validation(format!("{e:#}").into()))?;
tracing::trace!(
"beacon network at {}: {:?}, is_chained: {}",
self.epoch,
curr_beacon.network(),
curr_beacon.network().is_chained()
);
// Before quicknet upgrade, we had "chained" beacons, and so required two entries at a fork
if curr_beacon.network().is_chained() {
let (pb_epoch, _) = b_schedule
.beacon_for_epoch(parent_epoch)
.map_err(|e| Error::Validation(format!("{e:#}").into()))?;
if cb_epoch != pb_epoch {
// Fork logic
if self.beacon_entries.len() != 2 {
return Err(Error::Validation(
format!(
"Expected two beacon entries at beacon fork, got {}",
self.beacon_entries.len()
)
.into(),
));
}
#[allow(clippy::indexing_slicing)]
curr_beacon
.verify_entries(&self.beacon_entries[1..], &self.beacon_entries[0])
.map_err(|e| Error::Validation(format!("{e:#}").into()))?;
return Ok(());
}
}
let max_round = curr_beacon
.max_beacon_round_for_epoch(network_version, self.epoch)
.map_err(|e| Error::Validation(format!("{e:#}").into()))?;
// We don't expect to ever actually meet this condition
if max_round == prev_entry.round() {
if !self.beacon_entries.is_empty() {
return Err(Error::Validation(
format!(
"expected not to have any beacon entries in this block, got: {}",
self.beacon_entries.len()
)
.into(),
));
}
return Ok(());
}
// We skip verifying the genesis entry when randomness is "chained".
if curr_beacon.network().is_chained() && prev_entry.round() == 0 {
// This basically means that the drand entry of the first non-genesis tipset isn't verified IF we are starting on Drand mainnet (the "chained" drand)
// Networks that start on drand quicknet, or other unchained randomness sources, will still verify it
return Ok(());
}
let last = match self.beacon_entries.last() {
Some(last) => last,
None => {
return Err(Error::Validation(
"Block must include at least 1 beacon entry".into(),
));
}
};
if last.round() != max_round {
return Err(Error::Validation(
format!(
"expected final beacon entry in block to be at round {}, got: {}",
max_round,
last.round()
)
.into(),
));
}
// ref: https://github.com/filecoin-project/lotus/blob/27abf0f16a7f2a83305910f3c2a1844764d20b75/chain/beacon/beacon.go#L95
if curr_beacon.network().is_unchained() {
for (idx, beacon_entry) in self.beacon_entries.iter().enumerate() {
let lookup_epoch = parent_epoch + 1 + idx as i64;
let expected_round = curr_beacon
.max_beacon_round_for_epoch(network_version, lookup_epoch)
.map_err(|e| Error::Validation(format!("{e:#}").into()))?;
if beacon_entry.round() != expected_round {
return Err(Error::Validation(
format!(
"expected max round for epoch {} to be {}, got: {}",
lookup_epoch,
expected_round,
beacon_entry.round(),
)
.into(),
));
}
}
}
if !curr_beacon
.verify_entries(&self.beacon_entries, prev_entry)
.map_err(|e| Error::Validation(format!("{e:#}").into()))?
{
return Err(Error::Validation("beacon entry was invalid".into()));
}
Ok(())
}
/// Serializes the header to bytes for signing purposes i.e. without the
/// signature field
pub fn signing_bytes(&self) -> Vec<u8> {
let mut blk = self.clone();
blk.signature = None;
fvm_ipld_encoding::to_vec(&blk).expect("block serialization cannot fail")
}
}
// The derive macro does not compile for some reason
impl GetSize for RawBlockHeader {
fn get_heap_size_with_tracker<T: get_size2::GetSizeTracker>(
&self,
mut tracker: T,
) -> (usize, T) {
let Self {
miner_address,
ticket,
election_proof,
beacon_entries,
winning_post_proof,
parents,
weight,
epoch: _,
state_root: _,
message_receipts: _,
messages: _,
bls_aggregate,
timestamp: _,
signature,
fork_signal: _,
parent_base_fee,
} = self;
(
miner_address.get_heap_size_with_tracker(&mut tracker).0
+ ticket.get_heap_size_with_tracker(&mut tracker).0
+ election_proof.get_heap_size_with_tracker(&mut tracker).0
+ beacon_entries.get_heap_size_with_tracker(&mut tracker).0
+ winning_post_proof
.get_heap_size_with_tracker(&mut tracker)
.0
+ parents.get_heap_size_with_tracker(&mut tracker).0
+ big_int_heap_size_helper(weight)
+ bls_aggregate.get_heap_size_with_tracker(&mut tracker).0
+ signature.get_heap_size_with_tracker(&mut tracker).0
+ parent_base_fee.get_heap_size_with_tracker(&mut tracker).0,
tracker,
)
}
}
/// A [`RawBlockHeader`] which caches calls to [`RawBlockHeader::cid`] and [`RawBlockHeader::verify_signature_against`]
#[cfg_attr(test, derive(Default))]
#[derive(Debug, GetSize, derive_more::Deref)]
pub struct CachingBlockHeader {
#[deref]
uncached: RawBlockHeader,
#[get_size(ignore)]
cid: OnceLock<Cid>,
has_ever_been_verified_against_any_signature: AtomicBool,
}
impl PartialEq for CachingBlockHeader {
fn eq(&self, other: &Self) -> bool {
// Epoch check is redundant but cheap.
self.uncached.epoch == other.uncached.epoch && self.cid() == other.cid()
}
}
impl Eq for CachingBlockHeader {}
impl Clone for CachingBlockHeader {
fn clone(&self) -> Self {
Self {
uncached: self.uncached.clone(),
cid: self.cid.clone(),
has_ever_been_verified_against_any_signature: AtomicBool::new(
self.has_ever_been_verified_against_any_signature
.load(Ordering::Acquire),
),
}
}
}
impl From<RawBlockHeader> for CachingBlockHeader {
fn from(value: RawBlockHeader) -> Self {
Self::new(value)
}
}
impl CachingBlockHeader {
pub fn new(uncached: RawBlockHeader) -> Self {
Self {
uncached,
cid: OnceLock::new(),
has_ever_been_verified_against_any_signature: AtomicBool::new(false),
}
}
pub fn into_raw(self) -> RawBlockHeader {
self.uncached
}
/// Returns [`None`] if the blockstore doesn't contain the CID.
pub fn load(store: &impl Blockstore, cid: Cid) -> anyhow::Result<Option<Self>> {
if let Some(uncached) = store.get_cbor::<RawBlockHeader>(&cid)? {
Ok(Some(Self {
uncached,
cid: cid.into(),
has_ever_been_verified_against_any_signature: AtomicBool::new(false),
}))
} else {
Ok(None)
}
}
pub fn cid(&self) -> &Cid {
self.cid.get_or_init(|| self.uncached.cid())
}
pub fn verify_signature_against(&self, addr: &Address) -> Result<(), Error> {
match self
.has_ever_been_verified_against_any_signature
.load(Ordering::Acquire)
{
true => Ok(()),
false => match self.uncached.verify_signature_against(addr) {
Ok(()) => {
self.has_ever_been_verified_against_any_signature
.store(true, Ordering::Release);
Ok(())
}
Err(e) => Err(e),
},
}
}
}
impl From<CachingBlockHeader> for RawBlockHeader {
fn from(value: CachingBlockHeader) -> Self {
value.into_raw()
}
}
impl Serialize for CachingBlockHeader {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
self.uncached.serialize(serializer)
}
}
impl<'de> Deserialize<'de> for CachingBlockHeader {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
RawBlockHeader::deserialize(deserializer).map(Self::new)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::beacon::{
BeaconEntry, BeaconPoint, BeaconSchedule, mock_beacon::MockBeacon,
tests::drand::new_beacon_quicknet,
};
use crate::blocks::{CachingBlockHeader, Error};
use crate::shim::clock::ChainEpoch;
use crate::shim::{address::Address, version::NetworkVersion};
use crate::utils::encoding::from_slice_with_fallback;
use crate::utils::encoding::hex;
use crate::utils::multihash::MultihashCode;
use cid::Cid;
use fvm_ipld_encoding::{DAG_CBOR, to_vec};
use rstest::{fixture, rstest};
impl quickcheck::Arbitrary for CachingBlockHeader {
fn arbitrary(g: &mut quickcheck::Gen) -> Self {
use crate::blocks::{Ticket, VRFProof};
// TODO(forest): https://github.com/ChainSafe/forest/issues/3571
CachingBlockHeader::new(RawBlockHeader {
miner_address: Address::new_id(0),
ticket: Some(Ticket::new(VRFProof::new(Vec::arbitrary(g)))),
epoch: ChainEpoch::arbitrary(g),
..Default::default()
})
}
}
#[test]
fn symmetric_header_encoding() {
// This test vector is pulled from space race, and contains a valid signature
let bz = hex::decode("904300e8078158608798de4e49e02ee129920224ea767650aa6e693857431cc95b5a092a57d80ef4d841ebedbf09f7680a5e286cd297f40100b496648e1fa0fd55f899a45d51404a339564e7d4809741ba41d9fcc8ac0261bf521cd5f718389e81354eff2aa52b338201586084d8929eeedc654d6bec8bb750fcc8a1ebf2775d8167d3418825d9e989905a8b7656d906d23dc83e0dad6e7f7a193df70a82d37da0565ce69b776d995eefd50354c85ec896a2173a5efed53a27275e001ad72a3317b2190b98cceb0f01c46b7b81821a00013cbe5860ae1102b76dea635b2f07b7d06e1671d695c4011a73dc33cace159509eac7edc305fa74495505f0cd0046ee0d3b17fabc0fc0560d44d296c6d91bcc94df76266a8e9d5312c617ca72a2e186cadee560477f6d120f6614e21fb07c2390a166a25981820358c0b965705cec77b46200af8fb2e47c0eca175564075061132949f00473dcbe74529c623eb510081e8b8bd34418d21c646485d893f040dcfb7a7e7af9ae4ed7bd06772c24fb0cc5b8915300ab5904fbd90269d523018fbf074620fd3060d55dd6c6057b4195950ac4155a735e8fec79767f659c30ea6ccf0813a4ab2b4e60f36c04c71fb6c58efc123f60c6ea8797ab3706a80a4ccc1c249989934a391803789ab7d04f514ee0401d0f87a1f5262399c451dcf5f7ec3bb307fc6f1a41f5ff3a5ddb81d82a5827000171a0e402209a0640d0620af5d1c458effce4cbb8969779c9072b164d3fe6f5179d6378d8cd4300310001d82a5827000171a0e402208fbc07f7587e2efebab9ff1ab27c928881abf9d1b7e5ad5206781415615867aed82a5827000171a0e40220e5658b3d18cd06e1db9015b4b0ec55c123a24d5be1ea24d83938c5b8397b4f2fd82a5827000171a0e402209967f10c4c0e336b3517d3a972f701dadea5b41ce33defb126b88e650cf884545861028ec8b64e2d93272f97edcab1f56bcad4a2b145ea88c232bfae228e4adbbd807e6a41740cc8cb569197dae6b2cbf8c1a4035e81fd7805ccbe88a5ec476bcfa438db4bd677de06b45e94310533513e9d17c635940ba8fa2650cdb34d445724c5971a5f44387e5861028a45c70a39fe8e526cbb6ba2a850e9063460873d6329f26cc2fc91972256c40249dba289830cc99619109c18e695d78012f760e7fda1b68bc3f1fe20ff8a017044753da38ca6384de652f3ee13aae5b64e6f88f85fd50d5c862fed3c1f594ace004500053724e0").unwrap();
let header = from_slice_with_fallback::<CachingBlockHeader>(&bz).unwrap();
assert_eq!(to_vec(&header).unwrap(), bz);
// Verify the signature of this block header using the resolved address used to
// sign. This is a valid signature, but if the block header vector
// changes, the address should need to as well.
header
.verify_signature_against(
&"f3vfs6f7tagrcpnwv65wq3leznbajqyg77bmijrpvoyjv3zjyi3urq25vigfbs3ob6ug5xdihajumtgsxnz2pa"
.parse()
.unwrap())
.unwrap();
}
#[test]
fn beacon_entry_exists() {
// Setup
let block_header = CachingBlockHeader::new(RawBlockHeader {
miner_address: Address::new_id(0),
..Default::default()
});
let beacon_schedule = BeaconSchedule(vec![BeaconPoint::new(0, <MockBeacon>::default())]);
let chain_epoch = 0;
let beacon_entry = BeaconEntry::new(1, vec![]);
// Validate_block_drand
if let Err(e) = block_header.validate_block_drand(
NetworkVersion::V16,
&beacon_schedule,
chain_epoch,
&beacon_entry,
) {
// Assert error is for not including a beacon entry in the block
match e {
Error::Validation(why) => {
assert_eq!(why, "Block must include at least 1 beacon entry");
}
_ => {
panic!("validate block drand must detect a beacon entry in the block header");
}
}
}
}
#[test]
fn test_genesis_parent() {
assert_eq!(
Cid::new_v1(
DAG_CBOR,
MultihashCode::Sha2_256.digest(&FILECOIN_GENESIS_BLOCK)
),
*FILECOIN_GENESIS_CID
);
}
#[fixture]
#[once]
fn schedule() -> BeaconSchedule {
BeaconSchedule(vec![BeaconPoint::new(0, new_beacon_quicknet())])
}
#[derive(Debug)]
struct BeaconEntriesCase {
parent_epoch: ChainEpoch,
prev_round: u64,
epoch: ChainEpoch,
rounds: Vec<u64>,
accepted: bool,
}
#[rstest]
#[case::no_null_round(BeaconEntriesCase {
parent_epoch: 6216199,
prev_round: 30662992,
epoch: 6216200,
rounds: vec![30663002],
accepted: true,
})]
#[case::null_round_both_entries(BeaconEntriesCase {
parent_epoch: 6216198,
prev_round: 30662982,
epoch: 6216200,
rounds: vec![30662992, 30663002],
accepted: true,
})]
#[case::null_round_invalid_entry(BeaconEntriesCase {
parent_epoch: 6216198,
prev_round: 30662982,
epoch: 6216200,
rounds: vec![30662990, 30663002],
accepted: false,
})]
#[case::null_round_missing_null_entry(BeaconEntriesCase {
parent_epoch: 6216198,
prev_round: 30662982,
epoch: 6216200,
rounds: vec![30663002],
accepted: false,
})]
#[case::null_round_missing_own_entry(BeaconEntriesCase {
parent_epoch: 6216198,
prev_round: 30662982,
epoch: 6216200,
rounds: vec![30662992],
accepted: false,
})]
#[case::extra_trailing_entry(BeaconEntriesCase {
parent_epoch: 6216199,
prev_round: 30662992,
epoch: 6216200,
rounds: vec![30663002, 30663002],
accepted: false,
})]
#[case::null_round_extra_trailing_entry(BeaconEntriesCase {
parent_epoch: 6216198,
prev_round: 30662982,
epoch: 6216200,
rounds: vec![30662992, 30663002, 30663002],
accepted: false,
})]
#[tokio::test]
async fn validate_beacon_entries_on_quicknet(
schedule: &BeaconSchedule,
#[case] case: BeaconEntriesCase,
) {
let BeaconEntriesCase {
parent_epoch,
prev_round,
epoch,
rounds,
accepted,
} = case;
let (_, curr_beacon) = schedule.beacon_for_epoch(epoch).unwrap();
let mut beacon_entries = Vec::with_capacity(rounds.len());
for round in rounds {
beacon_entries.push(curr_beacon.entry(round).await.unwrap());
}
let prev_entry = BeaconEntry::new(prev_round, vec![]);
let header = RawBlockHeader {
miner_address: Address::new_id(0),
epoch,
beacon_entries,
..Default::default()
};
let result =
header.validate_block_drand(NetworkVersion::V22, schedule, parent_epoch, &prev_entry);
assert_eq!(
result.is_ok(),
accepted,
"epoch {epoch}, parent {parent_epoch}: {result:?}"
);
}
}