hypercall_blocks/

header.rs

use serde::{Deserialize, Serialize};

/// Serializable signed block header stored in the WAL block log.
///
/// The header commits to an ordered batch of engine commands through
/// `commands_hash`, and to the previous block through `prev_block_hash`.
/// The signature is stored next to the signed fields, but is intentionally
/// excluded from `block_hash()`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BlockLogHeader {
    /// Monotonic block number, starting at zero.
    pub batch_seq: u64,
    /// Hash of the previous block header. Zero for the genesis block.
    pub prev_block_hash: [u8; 32],
    /// `keccak256(cmd1_identity_hash || cmd2_identity_hash || ...)`.
    pub commands_hash: [u8; 32],
    /// Composite commitment root for state, risk, command, obligation, and intent roots.
    pub batch_root: [u8; 32],
    /// Number of commands committed by this block.
    pub command_count: u64,
    /// Global command sequence number of the first command in this block.
    pub first_seq: u64,
    /// Timestamp in milliseconds when the block was finalized.
    pub timestamp: u64,
    /// Public address of the signer encoded as raw EVM address bytes.
    pub signer: [u8; 20],
    /// Signature bytes over `block_hash()`. Empty means unsigned.
    pub signature: Vec<u8>,
}

impl BlockLogHeader {
    /// Build an unsigned block-log header from ordered command identity hashes.
    ///
    /// This is intentionally pure. Callers provide sequencing, timestamp,
    /// signer identity, and batch root. The function derives only the command
    /// commitment and command count.
    pub fn unsigned_from_identity_hashes(
        batch_seq: u64,
        prev_block_hash: [u8; 32],
        identity_hashes: &[[u8; 32]],
        batch_root: [u8; 32],
        first_seq: u64,
        timestamp: u64,
        signer: [u8; 20],
    ) -> Self {
        Self {
            batch_seq,
            prev_block_hash,
            commands_hash: compute_commands_hash(identity_hashes),
            batch_root,
            command_count: identity_hashes.len() as u64,
            first_seq,
            timestamp,
            signer,
            signature: Vec::new(),
        }
    }

    /// Compute the block hash over the signed fields. The signature is excluded.
    pub fn block_hash(&self) -> [u8; 32] {
        use sha3::{Digest, Keccak256};

        let mut h = Keccak256::new();
        h.update(self.batch_seq.to_be_bytes());
        h.update(self.prev_block_hash);
        h.update(self.commands_hash);
        h.update(self.batch_root);
        h.update(self.command_count.to_be_bytes());
        h.update(self.first_seq.to_be_bytes());
        h.update(self.timestamp.to_be_bytes());
        h.update(self.signer);
        h.finalize().into()
    }

    /// Compute the Solidity `ValidatorRsm.blockHash(metadata)` value for this header.
    ///
    /// This is intentionally distinct from `block_hash()`. The WAL block hash signs
    /// local log metadata, including timestamp and signer, while ValidatorRsm commits
    /// to the on-chain directive hash instead.
    pub fn validator_rsm_metadata_hash(&self, directive_hash: [u8; 32]) -> [u8; 32] {
        use sha3::{Digest, Keccak256};

        let mut encoded = Vec::with_capacity(32 * 7);
        push_abi_u64_word(&mut encoded, self.batch_seq);
        encoded.extend_from_slice(&self.prev_block_hash);
        encoded.extend_from_slice(&self.commands_hash);
        encoded.extend_from_slice(&self.batch_root);
        push_abi_u64_word(&mut encoded, self.command_count);
        push_abi_u64_word(&mut encoded, self.first_seq);
        encoded.extend_from_slice(&directive_hash);

        Keccak256::digest(encoded).into()
    }
}

/// Compute `keccak256(cmd1_identity_hash || cmd2_identity_hash || ...)`.
pub fn compute_commands_hash(identity_hashes: &[[u8; 32]]) -> [u8; 32] {
    use sha3::{Digest, Keccak256};

    let mut h = Keccak256::new();
    for hash in identity_hashes {
        h.update(hash);
    }
    h.finalize().into()
}

fn push_abi_u64_word(out: &mut Vec<u8>, value: u64) {
    out.extend_from_slice(&[0u8; 24]);
    out.extend_from_slice(&value.to_be_bytes());
}

#[cfg(test)]
mod tests {
    use super::*;

    fn baseline_header() -> BlockLogHeader {
        BlockLogHeader {
            batch_seq: 1,
            prev_block_hash: [2; 32],
            commands_hash: [3; 32],
            batch_root: [4; 32],
            command_count: 5,
            first_seq: 6,
            timestamp: 1_700_000_000,
            signer: [7; 20],
            signature: vec![8; 65],
        }
    }

    #[test]
    fn unsigned_header_derives_commands_hash_and_count() {
        let identities = [[1u8; 32], [2u8; 32], [3u8; 32]];
        let header = BlockLogHeader::unsigned_from_identity_hashes(
            7,
            [9; 32],
            &identities,
            [10; 32],
            42,
            1_700_000_000,
            [11; 20],
        );

        assert_eq!(header.batch_seq, 7);
        assert_eq!(header.prev_block_hash, [9; 32]);
        assert_eq!(header.commands_hash, compute_commands_hash(&identities));
        assert_eq!(header.batch_root, [10; 32]);
        assert_eq!(header.command_count, 3);
        assert_eq!(header.first_seq, 42);
        assert_eq!(header.timestamp, 1_700_000_000);
        assert_eq!(header.signer, [11; 20]);
        assert!(header.signature.is_empty());
    }

    #[test]
    fn command_hash_order_matters() {
        let a = [1u8; 32];
        let b = [2u8; 32];

        assert_ne!(
            compute_commands_hash(&[a, b]),
            compute_commands_hash(&[b, a])
        );
    }

    #[test]
    fn command_hash_empty_batch_is_still_domain_data() {
        let empty = compute_commands_hash(&[]);

        assert_ne!(empty, [0u8; 32]);
        assert_eq!(empty, compute_commands_hash(&[]));
    }

    #[test]
    fn command_hash_single_batch_is_deterministic_and_not_identity() {
        let identity = [0xabu8; 32];
        let hash = compute_commands_hash(&[identity]);

        assert_eq!(hash, compute_commands_hash(&[identity]));
        assert_ne!(hash, identity);
    }

    #[test]
    fn command_hash_large_batch_is_deterministic() {
        let hashes: Vec<[u8; 32]> = (0..10_000u32)
            .map(|i| {
                let mut hash = [0u8; 32];
                hash[..4].copy_from_slice(&i.to_be_bytes());
                hash
            })
            .collect();

        assert_eq!(
            compute_commands_hash(&hashes),
            compute_commands_hash(&hashes)
        );
    }

    #[test]
    fn block_hash_is_deterministic() {
        let header = baseline_header();

        assert_eq!(header.block_hash(), header.block_hash());
    }

    #[test]
    fn block_hash_excludes_signature() {
        let mut header = baseline_header();
        let hash = header.block_hash();

        header.signature = vec![0xff; 65];

        assert_eq!(hash, header.block_hash());
    }

    #[test]
    fn block_hash_changes_when_signed_field_changes() {
        let baseline = baseline_header();
        let baseline_hash = baseline.block_hash();

        let mut changed = baseline.clone();
        changed.batch_seq += 1;
        assert_ne!(baseline_hash, changed.block_hash());

        let mut changed = baseline.clone();
        changed.prev_block_hash = [0x10; 32];
        assert_ne!(baseline_hash, changed.block_hash());

        let mut changed = baseline.clone();
        changed.commands_hash = [0x20; 32];
        assert_ne!(baseline_hash, changed.block_hash());

        let mut changed = baseline.clone();
        changed.batch_root = [0x30; 32];
        assert_ne!(baseline_hash, changed.block_hash());

        let mut changed = baseline.clone();
        changed.command_count += 1;
        assert_ne!(baseline_hash, changed.block_hash());

        let mut changed = baseline.clone();
        changed.first_seq += 1;
        assert_ne!(baseline_hash, changed.block_hash());

        let mut changed = baseline.clone();
        changed.timestamp += 1;
        assert_ne!(baseline_hash, changed.block_hash());

        let mut changed = baseline;
        changed.signer = [0x40; 20];
        assert_ne!(baseline_hash, changed.block_hash());
    }

    #[test]
    fn validator_rsm_metadata_hash_matches_solidity_vector() {
        let header = BlockLogHeader {
            batch_seq: 7,
            prev_block_hash: [0xaa; 32],
            commands_hash: [0xbb; 32],
            batch_root: [0xcc; 32],
            command_count: 3,
            first_seq: 42,
            timestamp: 1_700_000_000,
            signer: [0x11; 20],
            signature: vec![0x22; 65],
        };
        let directive_hash = [
            0x23, 0xc3, 0x04, 0xad, 0xf8, 0xd5, 0x7c, 0xba, 0xc7, 0x83, 0x4a, 0x6c, 0xe5, 0xdf,
            0x58, 0xc8, 0xd3, 0x20, 0x6e, 0xbb, 0x0e, 0xb1, 0xd9, 0x2e, 0x31, 0xe5, 0xaf, 0x71,
            0x2d, 0xff, 0x69, 0x98,
        ];

        assert_eq!(
            header.validator_rsm_metadata_hash(directive_hash),
            [
                0x72, 0x69, 0x24, 0xa7, 0x66, 0x2f, 0xdd, 0xa1, 0xb8, 0xc7, 0x03, 0x4d, 0xac, 0x40,
                0x30, 0x34, 0x8b, 0xe8, 0x2c, 0x23, 0xd0, 0x92, 0xfe, 0xac, 0xb5, 0x8e, 0xa1, 0x73,
                0x08, 0x58, 0x3d, 0x6d,
            ]
        );
    }

    #[test]
    fn validator_rsm_metadata_hash_uses_onchain_metadata_only() {
        let header = baseline_header();
        let directive_hash = [0x55; 32];
        let baseline_hash = header.validator_rsm_metadata_hash(directive_hash);

        let mut changed = header.clone();
        changed.timestamp += 1;
        assert_eq!(
            baseline_hash,
            changed.validator_rsm_metadata_hash(directive_hash)
        );

        let mut changed = header.clone();
        changed.signer = [0x66; 20];
        assert_eq!(
            baseline_hash,
            changed.validator_rsm_metadata_hash(directive_hash)
        );

        let mut changed = header.clone();
        changed.signature = vec![0x77; 65];
        assert_eq!(
            baseline_hash,
            changed.validator_rsm_metadata_hash(directive_hash)
        );

        let mut changed = header.clone();
        changed.command_count += 1;
        assert_ne!(
            baseline_hash,
            changed.validator_rsm_metadata_hash(directive_hash)
        );

        assert_ne!(
            baseline_hash,
            header.validator_rsm_metadata_hash([0x88; 32])
        );
    }

    #[test]
    fn block_chain_links_by_previous_hash() {
        let block0 = BlockLogHeader::unsigned_from_identity_hashes(
            0,
            [0; 32],
            &[[1; 32]],
            [0; 32],
            0,
            1_700_000_000,
            [9; 20],
        );
        let block1 = BlockLogHeader::unsigned_from_identity_hashes(
            1,
            block0.block_hash(),
            &[[2; 32]],
            [0; 32],
            1,
            1_700_000_001,
            [9; 20],
        );
        let block2 = BlockLogHeader::unsigned_from_identity_hashes(
            2,
            block1.block_hash(),
            &[[3; 32]],
            [0; 32],
            2,
            1_700_000_002,
            [9; 20],
        );

        assert_eq!(block0.prev_block_hash, [0; 32]);
        assert_eq!(block1.prev_block_hash, block0.block_hash());
        assert_eq!(block2.prev_block_hash, block1.block_hash());
        assert_ne!(block0.block_hash(), block1.block_hash());
        assert_ne!(block1.block_hash(), block2.block_hash());
    }
}