Syscoin Core Developer Portal

Comprehensive guides and documentation to help you start working with Syscoin as quickly as possible, and support if you get stuck.

Get Started

Superblock Validation Battles

An In-depth Look at the Superblock Validation Process of Syscoin Bridge


Document Updates Pending

Superblock validation has been further simplified since the initial documentation of the process. This document will receive updates soon.

The Syscoin Battle Manager is an Ethereum contract that evaluates responses to Superblock challenges. The Submitter of a Superblock should respond to every challenge by providing specific information about the structure of their Superblock. If the Submitter is able to respond to all challenges, the Superblock may become approved. Specifically, a Superblock becomes semi-approved if there are any challenges in its history and such a Superblock may become approved if three semi-approved Superblocks are submitted on the top of it. Alternatively, a Superblock becomes semi-approved if it is put on the top of another semi-approved Superblock. A Superblock may skip semi-approved state and become directly approved in the case that it is built on the top of an approved Superblock and no one challenges it.

A Superblock is a representation of 60 blocks on the Syscoin blockchain that is announced to the Superblocks smart contract in order to later allow proving the existence of burn transactions on Syscoin blockchain to the ERC-20 Manager contract. Superblocks are represented by the following structure in the Superblocks contract.

struct SuperblockInfo {
        bytes32 blocksMerkleRoot;
        uint accumulatedWork;
        uint timestamp;
        bytes32 lastHash;
        bytes32 parentId;
        address submitter;
        bytes32 ancestors;
        uint32 lastBits;
        uint32 index;
        uint32 height;
        Status status;

There are three verification steps in the event of a Superblock challenge. These steps must be executed in order:

  1. QueryMerkleRootHashes
  2. QueryLastBlockHeader
  3. VerifySuperblock
    a. validateLastBlocks
    b. validateProofOfWork

When an honest Agent detects a Superblock not matching what they calculate locally, it challenges the Superblock, requiring the Submitter to provide proper responses. The first challenge is QueryMerkleRootHashes to which the Submitter must reply with respondMerkleRootHashes. In this response, the Submitter simply provides all 60 hashes of the blocks that the Superblock is supposed to represent. If the Submitter does not provide this reply within 10 minutes, the Challenger wins. If the response is Submitted, the Battle Manager contract verifies that the root of the Merkle tree built from the submitted 60 hashes equals to the value of blocksMerkleRoot in the Superblock. It also checks that the last (and possibly an interim block see below) of the submitted block hashes is equal to the value of lastHash in the superblock. Notably, it also saves the last two of the 60 provided block hashes for later use. If the response is successfully verified by the contract, the challenge continues. The interim block is one with index below 57, so block 0 to 57 may not connect with previous block hash == to the next block leading up to the last block header which is also fully verified. The Challenger would verify that the chain of blocks connects up to the last block. If one doesn't connect, the Challenger provides that block to ensure that the submitter is honestly submitting a chain of blocks with no forks in between. The logic of the interim block check is described below:

syscoinchain: a-b-c-...-y-z
    attacker sb: a-b-c-D-e-f-G-h-i-...-y-z
    challenger looks from z down to a, first mismatch is G
    So the Challenger now asks the contract to ask for block h. If the attacker provides it, its previous block will be g, not G

The Challenger continues by sending the QueryLastBlockHeader challenge. The submitter has to reply with respondLastBlockHeader within 10 minutes again. In this response, the submitter provides a full block header of the last of the 60 blocks as well as potentially an interim block if the challenger gives a non-zero index of the block. The Battle Manager contract calculates a hash of this block header and compares it to the stored hash of the last block from the previous step, which is equal to the value of lastHash in the Superblock and similarly for the interim block. Then the Battle Manager contract verifies that the submitted block headers have correct proof of work on them. If everything meets expectations, the challenge continues.

The Challenger continues by executing the final step: VerifySuperblock. This consists of two steps. First, validateLastBlocks is called, in which the Battle Manager contract verifies that the previous hash of the last block - for which header was submitted in the previous step - is equal to the second from the last block hash submitted in the first step. The code follows:

bytes32 blockSha256Hash = session.blockHashes[session.blockHashes.length - 1];
    BlockInfo storage blockInfo = session.blocksInfo;
    bytes32 prevBlockSha256Hash = session.blockHashes[session.blockHashes.length - 2];
    if(blockInfo.prevBlock != prevBlockSha256Hash){

The Battle Manager contract also verifies that previously the submitted block header's timestamp and hash are equal to values of the Superblock timestamp and lastHash values. Finally, the timestamp of the Superblock must not be lower than that of the previous Superblock.

The second step of VerifySuperblock is validateProofOfWork. Here it is verified that the previously submitted block header's bits value (encoded target) is equal to the Superblock lastBits value. It is then checked that accumulated work value accumulatedWork of the Superblock is greater than that of its parent. Then the Battle Manager contract calculates a range of valid values for the block difficulty target in the last block of the Superblock and compares that to the value of lastBits of the superblock. Finally, the accumulated work is calculated from the difficulty target value and compared to the claimed accumulatedWork value of the Superblock. If all checks pass, Submitter Agent wins the challenge and can Challenger's deposit. Otherwise, if Challenger wins, it can take Submitter's deposit.

The challenges prevent the attacker from submitting an invalid Superblock.


  • Incentives and collateralization will guarantee that there is always at least one honest Submitter Agent and one honest Challenger Agent online.
  • There are no huge reorgs (i.e. 100+ block) on the Syscoin and Ethereum blockchains

Updated 10 months ago

Superblock Validation Battles

An In-depth Look at the Superblock Validation Process of Syscoin Bridge

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.