hypercall_types/

validator_rsm.rs

use alloy::{
    primitives::{keccak256, Address, FixedBytes, U256},
    sol,
    sol_types::{Eip712Domain, SolStruct, SolValue},
};

use crate::directives::{HYPERCALL_MAINNET_CHAIN_ID, HYPERCALL_TESTNET_CHAIN_ID};

/// EIP-712 domain name for validator-attested RSM metadata.
pub const VALIDATOR_RSM_DOMAIN_NAME: &str = "HypercallValidatorRsm";
/// EIP-712 domain version for validator-attested RSM metadata.
pub const VALIDATOR_RSM_DOMAIN_VERSION: &str = "1";
/// Schema version for the validator-RSM typed-data payload.
pub const VALIDATOR_RSM_TYPE_VERSION: u16 = 1;

/// Validation errors for validator-RSM typed-data construction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ValidatorRsmError {
    /// The chain id is not one of the Hypercall chain ids accepted for validator-RSM attestations.
    UnsupportedChainId(u64),
    /// The verifying contract is the zero address, which would make signatures replayable.
    ZeroVerifyingContract,
}

impl std::fmt::Display for ValidatorRsmError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::UnsupportedChainId(chain_id) => {
                write!(f, "Unsupported RSM attestation chain id: {}", chain_id)
            }
            Self::ZeroVerifyingContract => {
                write!(f, "RSM attestation verifying contract must not be zero")
            }
        }
    }
}

impl std::error::Error for ValidatorRsmError {}

sol! {
    /// Batch metadata attested by the single validator before RSM directive submission.
    #[derive(Debug, PartialEq, Eq)]
    struct ValidatorRsmBatchMetadata {
        uint64 batchSeq;
        bytes32 prevBlockHash;
        bytes32 commandsHash;
        bytes32 batchRoot;
        uint64 commandCount;
        uint64 firstSeq;
        bytes32 directiveHash;
    }
}

/// Build the EIP-712 domain for validator-RSM batch metadata.
pub fn rsm_attestation_domain(
    chain_id: u64,
    verifying_contract: Address,
) -> Result<Eip712Domain, ValidatorRsmError> {
    if chain_id != HYPERCALL_TESTNET_CHAIN_ID && chain_id != HYPERCALL_MAINNET_CHAIN_ID {
        return Err(ValidatorRsmError::UnsupportedChainId(chain_id));
    }
    if verifying_contract == Address::ZERO {
        return Err(ValidatorRsmError::ZeroVerifyingContract);
    }

    Ok(Eip712Domain {
        name: Some(VALIDATOR_RSM_DOMAIN_NAME.into()),
        version: Some(VALIDATOR_RSM_DOMAIN_VERSION.into()),
        chain_id: Some(U256::from(chain_id)),
        verifying_contract: Some(verifying_contract),
        salt: None,
    })
}

/// Hash the typed batch metadata struct using the EIP-712 struct hash.
pub fn rsm_batch_metadata_struct_hash(metadata: &ValidatorRsmBatchMetadata) -> FixedBytes<32> {
    metadata.eip712_hash_struct()
}

/// Hash the accepted batch metadata exactly as the contract stores accepted block continuity.
pub fn rsm_batch_metadata_block_hash(metadata: &ValidatorRsmBatchMetadata) -> FixedBytes<32> {
    keccak256(metadata.abi_encode())
}

/// Build the exact metadata object that `ValidatorRsm.sol` hashes and stores.
///
/// The directive bytes must be the final ABI-encoded directive submitted to the
/// on-chain RSM entrypoint. This keeps the directive preimage at the Rust call
/// site while committing only its hash in the attested metadata.
pub fn rsm_batch_metadata_from_block_fields(
    batch_seq: u64,
    prev_block_hash: [u8; 32],
    commands_hash: [u8; 32],
    batch_root: [u8; 32],
    command_count: u64,
    first_seq: u64,
    directive: &[u8],
) -> ValidatorRsmBatchMetadata {
    ValidatorRsmBatchMetadata {
        batchSeq: batch_seq,
        prevBlockHash: FixedBytes::from(prev_block_hash),
        commandsHash: FixedBytes::from(commands_hash),
        batchRoot: FixedBytes::from(batch_root),
        commandCount: command_count,
        firstSeq: first_seq,
        directiveHash: rsm_directive_hash(directive),
    }
}

/// Verify a stored block hash against the Solidity-compatible metadata hash.
pub fn verify_rsm_batch_metadata_block_hash(
    metadata: &ValidatorRsmBatchMetadata,
    expected_block_hash: FixedBytes<32>,
) -> bool {
    rsm_batch_metadata_block_hash(metadata) == expected_block_hash
}

/// Hash the exact encoded RSM directive bytes that the validator attests.
pub fn rsm_directive_hash(directive: &[u8]) -> FixedBytes<32> {
    keccak256(directive)
}

/// Compute the EIP-712 signing digest for validator-RSM batch metadata.
pub fn rsm_batch_metadata_signing_hash(
    metadata: &ValidatorRsmBatchMetadata,
    chain_id: u64,
    verifying_contract: Address,
) -> Result<FixedBytes<32>, ValidatorRsmError> {
    let domain = rsm_attestation_domain(chain_id, verifying_contract)?;
    Ok(metadata.eip712_signing_hash(&domain))
}

/// Verify a signing digest against the Solidity-compatible EIP-712 digest.
pub fn verify_rsm_batch_metadata_signing_hash(
    metadata: &ValidatorRsmBatchMetadata,
    chain_id: u64,
    verifying_contract: Address,
    expected_signing_hash: FixedBytes<32>,
) -> Result<bool, ValidatorRsmError> {
    Ok(
        rsm_batch_metadata_signing_hash(metadata, chain_id, verifying_contract)?
            == expected_signing_hash,
    )
}

#[cfg(test)]
mod tests {
    use super::*;
    use alloy::primitives::{address, b256};

    fn vector_contract() -> Address {
        address!("0x1111111111111111111111111111111111111111")
    }

    fn vector_metadata() -> ValidatorRsmBatchMetadata {
        ValidatorRsmBatchMetadata {
            batchSeq: 7,
            prevBlockHash: b256!(
                "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
            ),
            commandsHash: b256!(
                "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
            ),
            batchRoot: b256!("0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"),
            commandCount: 3,
            firstSeq: 42,
            directiveHash: b256!(
                "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
            ),
        }
    }

    #[test]
    fn rsm_batch_metadata_type_hash_matches_vector() {
        assert_eq!(
            format!(
                "{:#x}",
                keccak256(ValidatorRsmBatchMetadata::eip712_encode_type().as_bytes())
            ),
            "0x5eab7bc9925825c6321b3737a205ae360c425df72b286c62fcb6d6461889fdec"
        );
    }

    #[test]
    fn rsm_attestation_domain_separator_matches_vector() {
        let domain = rsm_attestation_domain(HYPERCALL_TESTNET_CHAIN_ID, vector_contract()).unwrap();
        assert_eq!(
            format!("{:#x}", domain.hash_struct()),
            "0x1064700185b52737a64ef42071090ce253524f99cc4a31103c862c3093183917"
        );
    }

    #[test]
    fn rsm_batch_metadata_struct_hash_matches_vector() {
        assert_eq!(
            format!("{:#x}", rsm_batch_metadata_struct_hash(&vector_metadata())),
            "0x467441eb6abda1b71c63dea883a5c908be089aa182cb2b92c8d92ecd8383a65a"
        );
    }

    #[test]
    fn rsm_batch_metadata_signing_hash_matches_vector() {
        assert_eq!(
            format!(
                "0x{}",
                hex::encode(
                    rsm_batch_metadata_signing_hash(
                        &vector_metadata(),
                        HYPERCALL_TESTNET_CHAIN_ID,
                        vector_contract()
                    )
                    .unwrap()
                )
            ),
            "0x29d7c6368cb595fb0bab304268eeba68545f00fa973119f5713a4093f9d29298"
        );
    }

    #[test]
    fn rsm_batch_metadata_block_hash_matches_solidity_vector() {
        assert_eq!(
            format!("{:#x}", rsm_batch_metadata_block_hash(&vector_metadata())),
            "0xc321d2803249bd565800c1dd0160762abe459f87efe066c1e07034100e8f7383"
        );
    }

    #[test]
    fn rsm_directive_hash_uses_exact_encoded_bytes() {
        let directive = hex::decode("1234abcd00010203040506070809").unwrap();
        let mut changed = directive.clone();
        changed.push(0);

        assert_eq!(
            format!("{:#x}", rsm_directive_hash(&directive)),
            "0x23c304adf8d57cbac7834a6ce5df58c8d3206ebb0eb1d92e31e5af712dff6998"
        );
        assert_ne!(rsm_directive_hash(&directive), rsm_directive_hash(&changed));
    }

    #[test]
    fn rsm_batch_metadata_from_block_fields_matches_solidity_hash_path() {
        let directive = hex::decode("1234abcd00010203040506070809").unwrap();
        let metadata = rsm_batch_metadata_from_block_fields(
            7, [0xaa; 32], [0xbb; 32], [0xcc; 32], 3, 42, &directive,
        );

        assert_eq!(metadata.batchSeq, 7);
        assert_eq!(metadata.prevBlockHash, FixedBytes::from([0xaa; 32]));
        assert_eq!(metadata.commandsHash, FixedBytes::from([0xbb; 32]));
        assert_eq!(metadata.batchRoot, FixedBytes::from([0xcc; 32]));
        assert_eq!(metadata.commandCount, 3);
        assert_eq!(metadata.firstSeq, 42);
        assert_eq!(metadata.directiveHash, rsm_directive_hash(&directive));
        assert_eq!(
            format!("{:#x}", metadata.directiveHash),
            "0x23c304adf8d57cbac7834a6ce5df58c8d3206ebb0eb1d92e31e5af712dff6998"
        );
        assert_eq!(
            format!("{:#x}", rsm_batch_metadata_block_hash(&metadata)),
            "0x726924a7662fdda1b8c7034dac4030348be82c23d092feacb58ea17308583d6d"
        );
        assert_eq!(
            format!(
                "{:#x}",
                rsm_batch_metadata_signing_hash(
                    &metadata,
                    HYPERCALL_TESTNET_CHAIN_ID,
                    vector_contract()
                )
                .unwrap()
            ),
            "0xd9fd769dd0090b48ea792e9682d674f8e858cb17ddcfcd5673de81b942b64bfa"
        );
    }

    #[test]
    fn rsm_batch_metadata_verify_helpers_reject_tampering() {
        let metadata = vector_metadata();
        let block_hash = rsm_batch_metadata_block_hash(&metadata);
        let signing_hash = rsm_batch_metadata_signing_hash(
            &metadata,
            HYPERCALL_TESTNET_CHAIN_ID,
            vector_contract(),
        )
        .unwrap();

        assert!(verify_rsm_batch_metadata_block_hash(&metadata, block_hash));
        assert!(verify_rsm_batch_metadata_signing_hash(
            &metadata,
            HYPERCALL_TESTNET_CHAIN_ID,
            vector_contract(),
            signing_hash
        )
        .unwrap());

        let mut tampered = metadata;
        tampered.commandCount += 1;
        assert!(!verify_rsm_batch_metadata_block_hash(&tampered, block_hash));
        assert!(!verify_rsm_batch_metadata_signing_hash(
            &tampered,
            HYPERCALL_TESTNET_CHAIN_ID,
            vector_contract(),
            signing_hash
        )
        .unwrap());
    }

    #[test]
    fn rsm_batch_metadata_field_mutations_change_signing_hash() {
        let base = vector_metadata();
        let base_hash =
            rsm_batch_metadata_signing_hash(&base, HYPERCALL_TESTNET_CHAIN_ID, vector_contract())
                .unwrap();

        let mut cases = Vec::new();

        let mut changed = base.clone();
        changed.batchSeq += 1;
        cases.push(changed);

        let mut changed = base.clone();
        changed.prevBlockHash = FixedBytes::from([0x11; 32]);
        cases.push(changed);

        let mut changed = base.clone();
        changed.commandsHash = FixedBytes::from([0x22; 32]);
        cases.push(changed);

        let mut changed = base.clone();
        changed.batchRoot = FixedBytes::from([0x33; 32]);
        cases.push(changed);

        let mut changed = base.clone();
        changed.commandCount += 1;
        cases.push(changed);

        let mut changed = base.clone();
        changed.firstSeq += 1;
        cases.push(changed);

        let mut changed = base;
        changed.directiveHash = FixedBytes::from([0x44; 32]);
        cases.push(changed);

        for changed in cases {
            let changed_hash = rsm_batch_metadata_signing_hash(
                &changed,
                HYPERCALL_TESTNET_CHAIN_ID,
                vector_contract(),
            )
            .unwrap();
            assert_ne!(base_hash, changed_hash);
        }
    }

    #[test]
    fn rsm_batch_metadata_field_mutations_change_block_hash() {
        let base = vector_metadata();
        let base_hash = rsm_batch_metadata_block_hash(&base);
        let mut changed = base.clone();
        changed.batchSeq += 1;
        assert_ne!(base_hash, rsm_batch_metadata_block_hash(&changed));

        let mut changed = base;
        changed.directiveHash = FixedBytes::from([0x44; 32]);
        assert_ne!(base_hash, rsm_batch_metadata_block_hash(&changed));
    }

    #[test]
    fn rsm_batch_metadata_domain_changes_affect_signing_hash() {
        let metadata = vector_metadata();
        let base_hash = rsm_batch_metadata_signing_hash(
            &metadata,
            HYPERCALL_TESTNET_CHAIN_ID,
            vector_contract(),
        )
        .unwrap();
        let other_chain_hash = rsm_batch_metadata_signing_hash(
            &metadata,
            HYPERCALL_MAINNET_CHAIN_ID,
            vector_contract(),
        )
        .unwrap();
        let other_contract_hash = rsm_batch_metadata_signing_hash(
            &metadata,
            HYPERCALL_TESTNET_CHAIN_ID,
            address!("0x2222222222222222222222222222222222222222"),
        )
        .unwrap();

        assert_ne!(base_hash, other_chain_hash);
        assert_ne!(base_hash, other_contract_hash);
    }

    #[test]
    fn rsm_attestation_domain_rejects_invalid_inputs() {
        assert_eq!(
            rsm_attestation_domain(1, vector_contract()).unwrap_err(),
            ValidatorRsmError::UnsupportedChainId(1)
        );
        assert_eq!(
            rsm_attestation_domain(HYPERCALL_TESTNET_CHAIN_ID, Address::ZERO).unwrap_err(),
            ValidatorRsmError::ZeroVerifyingContract
        );
    }
}