Skip to Content
SupraNova (Bridge)Relay a Message

Relay a Message

A relayer delivers a message to its destination chain. The relayer collects the message event and the proofs that the destination verifier needs, and submits them in one transaction.

SupraNova’s relayers deliver Token Bridge transfers only, so an application that sends its own messages relays them itself or arranges for a relayer. Anyone can also deliver a delayed Token Bridge transfer. See Recover a Transfer.

SupraNova does not distribute relayer software. For each direction, this page lists the public endpoints that serve each part of the proof bundle, and explains how to submit the bundle. Verification explains what each proof shows, and Message and Proof Formats gives the byte formats.

Before you relay

  • Check that the message has not been delivered. On an EVM chain, call isMessageProcessed(sourceChainId, consumer, messageId) on Hypernova, where consumer is the contract that verifies the message. On SupraMVM, check the receiving module’s own record. For a Token Bridge transfer, see Track a Transfer.
  • Check that the destination verifier’s committee is current. A message cannot be verified until the verifier holds the keys of the committee that signed it. Anyone can submit a committee update. See Committee Updaters.
  • Fund the relaying account. The account pays the verification fee and the gas on the destination chain.

From SupraMVM to an EVM chain

This direction needs only a Supra RPC node. The examples use https://rpc-testnet.supra.com. On Mainnet, use https://rpc-mainnet.supra.com. Each node publishes its API reference at /docs/.

Find the message event

Fetch the source transaction:

curl "https://rpc-testnet.supra.com/rpc/v4/transactions/<TX_HASH>?include_proof=true"

The events are listed in output.Move.events. The message event has the type <PACKAGE>::hypernova_core_from_supra::MessagePostedEvent, where <PACKAGE> is the package of hypernova_core_from_supra in Contract Addresses. Keep its type, data and hash.

To scan for messages instead, call GET /rpc/v4/events/{event_type} with start_height and end_height.

Get the proof bundle

The proofs are available once the block that contains the message is certified:

curl -X POST https://rpc-testnet.supra.com/rpc/v4/proofs/events \ -H 'Content-Type: application/json' \ -d '{"items":[{"transaction_hash":"<TX_HASH>","event_types":["<PACKAGE>::hypernova_core_from_supra::MessagePostedEvent"]}]}'

The response holds:

  • inclusion_certificate: the Transactions Inclusion Certificate of the latest certified block, whose height is block_height.
  • items[].transaction_inclusion_proof: the transaction Merkle proof against that certificate’s SupraMVM accumulator root.
  • items[].events[].event_emission_proof: the event Merkle proof against the transaction’s event accumulator root.

The response does not include the event data. Take it from the previous step.

Build the call arguments

Hashes in the response have no 0x prefix. Add it before you pass them to a contract.

ArgumentValue
moveEvent.typeTagThe UTF-8 bytes of the event type, with the package address written without its 0x prefix.
moveEvent.dataThe Binary Canonical Serialization (BCS) encoding of the event’s data. See Message and Proof Formats. keccak256(typeTag || data) must equal the event’s hash.
eventInclusionProof.eventMerkleProofFrom event_emission_proof: proof.siblings as proof, merkle_root_hash_value as root, and leaf_index as index.
eventInclusionProof.transactionHashThe source transaction hash.
eventInclusionProof.transactionMerkleProofFrom transaction_inclusion_proof: proof.siblings, merkle_root_hash_value and leaf_index, as above.
certificate.certifyingCommitteeHashinclusion_certificate.certifying_committee.
certificate.dataFrom inclusion_certificate.data: movevm_merkle_accumulator_tree_root, evm_merkle_accumulator_tree_root, block_height, and epoch_id.chain_id and epoch_id.epoch.
certificate.signatureinclusion_certificate.signature.BlsThresholdSignature.signature, converted to the 256-byte EIP-2537 encoding. See Message and Proof Formats.

Receive a Message declares the structs.

Submit

Send exactly the verification fee as the transaction value. Read it with sourceEnabledChainVerificationFee(chainId) on Hypernova, where chainId is the SupraMVM chain ID.

  • For your application, call your contract’s entry point. The entry point forwards the fee to verifyMessagePostedOnSupra on Hypernova. See Receive a Message.
  • For a Token Bridge transfer, call receiveTokensFromSupra(moveEvent, eventInclusionProof, certificate) on the TokenBridge proxy. The relayer reward goes to the account that submits the transaction.

Supra RPC nodes keep a limited history. A node answers 410 for data it has pruned, and returns the oldest block it still serves in the x-supra-oldest-block header. To relay an older message, use an archive node.

From Ethereum to SupraMVM

This direction needs an Ethereum execution RPC endpoint and a beacon node. The values on Testnet differ because Sepolia already uses the proof format of Ethereum’s Gloas upgrade. See Ethereum Consensus Verification.

Find the message log

Fetch the receipt of the source transaction with eth_getTransactionReceipt. The message is the log that the Hypernova contract emits with keccak256("MessagePosted(address,uint256,uint64,bytes)") as its first topic. Note the block number, the receipt’s transactionIndex, and the log’s position within the receipt.

Wait until the block can be verified

The receiving side’s verification strategy decides when a block can be verified. See Finality. For a Token Bridge transfer, read the strategy with get_verification_method_and_safety_level on token_bridge_service.

Under the Safe strategy, the attested block must be at least the safety level, in slots, after the target block. The attested block’s Sync Committee signature must carry at least as many signatures as get_sync_committee_threshold returns. get_sync_committee_threshold is a view function of hypernova_core.

Collect the proofs

ComponentSource
Attested header and Sync Committee signatureGET /eth/v1/beacon/light_client/optimistic_update on the beacon node. For the Finality strategy, use finality_update, which also returns the finalized header and its finality branch. Expand the 64-byte sync_committee_bits into 512 booleans, least significant bit first.
Target block headerGET /eth/v1/beacon/headers/{slot}. On Ethereum Mainnet, the target slot is (block timestamp − 1606824023) / 12. On Sepolia, it is the first later slot whose execution payload bid has the block’s hash as parent_block_hash.
Ancestry proof, target within 8,192 slotsA state proof of block_roots[slot % 8192] against the state root of the attested block, or of the finalized block for the Finality strategy, at generalized index 565248 + slot % 8192 on Mainnet or 2883584 + slot % 8192 on Testnet. On Mainnet, also pass this index as block_roots_index.
Ancestry proof, older targetA state proof of the period’s historical_summaries entry, at generalized index 6106906624 + 2i on Mainnet or 197971148800 + 2i on Testnet, where i = (slot − Capella slot) / 8192. The Capella slot is 6,209,536 on Ethereum Mainnet and 1,818,624 on Sepolia. Add a proof of the block root within the period, built from the period’s 8,192 block roots.
Receipt proofA Merkle Patricia Trie proof, built from all receipts of the block (eth_getBlockReceipts), for the key RLP(transactionIndex), the Recursive Length Prefix (RLP) encoding of the transaction index. The transaction must have succeeded.
Receipts root and its proof (Mainnet)The execution payload’s receipts root, proven against the target block root at generalized index 6435.
Execution block hash proof and header (Testnet)The execution block hash, proven against the target block root at generalized index 25384, and the RLP-encoded execution header.

To build the block-root proof for an older target, fetch each root of the period with GET /eth/v1/beacon/blocks/{slot}/root, and repeat the previous root for an empty slot.

State proofs are not part of the standard beacon API. Lodestar beacon nodes serve them at GET /eth/v0/beacon/proof/state/{state_id}. Otherwise, compute them from the full state that the debug API returns. Many public nodes do not serve light-client updates, old states or old receipts, so an older message may need an archive node.

Fill in the message fields

ArgumentValue
message_idtopics[2] of the log.
source_chain_idThe Ethereum chain ID.
source_hn_addrThe Ethereum Hypernova address, left-padded to 32 bytes.
destination_chain_idThe SupraMVM chain ID.
destination_hn_addrThe package address of hypernova_core.
log_hashkeccak256(address || topics || data) of the log, where address is the 20-byte Hypernova address.
log_indexThe log’s position within its receipt, not the block-wide logIndex.
tx_indexThe receipt’s transactionIndex.

The verifier checks the log hash, its topics and the emitting contract. The verifier does not check message_id or the chain IDs against the log, so a receiving module reads them from the verified log. See Security Best Practices.

Submit

hypernova_core charges the verification fee in SUPRA to the signing account. get_fee_per_verification on hypernova_core returns the fee.

  • For your application, call your module’s entry function. It passes the proofs to proof_verifier::process_data_optimistic_or_safe or process_data_finality in the hypernova_core package, or to their _v2 versions on Testnet. See Receive a Message.
  • For a Token Bridge transfer, call execute_optimistic_or_safe or execute_finality on token_bridge_service, whichever matches the Token Bridge’s stored strategy, or their _v2 versions on Testnet. token_bridge_service deposits the relayer reward to the signing account.

The Mainnet entry point takes the arguments in this order:

public entry fun execute_optimistic_or_safe( account: &signer, // Attested header and Sync Committee signature recent_block_slot: u64, recent_block_proposer_index: u64, recent_block_parent_root: vector<u8>, recent_block_state_root: vector<u8>, recent_block_body_root: vector<u8>, recent_block_sync_committee_bits: vector<bool>, recent_block_sync_committee_signature: vector<u8>, recent_block_signature_slot: u64, // Ancestry proof: set is_historical and fill the matching branch is_historical: bool, block_roots_index: u64, block_root_proof: vector<vector<u8>>, historical_block_root_proof: vector<vector<u8>>, historical_block_summary_root: vector<u8>, historical_block_summary_root_proof: vector<vector<u8>>, historical_block_summary_root_gindex: u64, // Target block header slot: u64, proposer_index: u64, parent_root: vector<u8>, state_root: vector<u8>, body_root: vector<u8>, // Receipt proof tx_index: u64, receipts_root_proof: vector<vector<u8>>, receipts_root_gindex: u64, receipt_proof: vector<vector<u8>>, receipts_root: vector<u8>, // Message fields message_id: vector<u8>, source_chain_id: u64, source_hn_addr: vector<u8>, destination_chain_id: u64, destination_hn_addr: vector<u8>, log_hash: vector<u8>, log_index: u64 )

execute_finality adds the finalized header and its finality branch between recent_block_body_root and recent_block_sync_committee_bits: recent_block_slot_finalized, recent_block_proposer_index_finalized, recent_block_parent_root_finalized, recent_block_state_root_finalized, recent_block_body_root_finalized and recent_block_finality_branch. The Testnet _v2 functions drop block_roots_index and replace the receipts root arguments with execution_block_hash_proof and execution_header_rlp. See Release Notes.

Last updated on