ibc.chain
ibc.chain
This contract implements eosio blockchain lightweight client, it is also called SPV client in Bitcoin combine with merkle path validation, this lightweight client can be used to verify transaction existence.
Actions called by the administrator
setglobal( chain_name, chain_id, consensus_algo )
chain_name, The name of the original blockchain of this light client, such as
eos
,bos
.chain_id, chain id of the original blockchain of this light client.
consensus_algo, consensus algorithm of the original blockchain of this light client, must be one of
pipeline
(represent DPOS pipeline bft consensus, such as the current EOSIO mainnet consensus) andbatch
(represent DPOS batch pbft consensus, such as the new BOS 3 seconds LIB consensus).require auth of _self
forceinit( )
three table ( _chaindb, _prodsches, _sections ) will be clear.
this action is needed when repairing the ibc system manually, please refer to TROUBLESHOOTING for detailed IBC system recovery process.
require auth of _self
Actions called by ibc_plugin
chaininit( header, active_schedule, blockroot_merkle )
header, packed block header data.
active_schedule, the active_schedule of this block
blockroot_merkle, the blockroot_merkle of this block
set the first block header of the light client, the
genesis header
of the light client, and all subsequent headers' validation is based on this headerthis action is called by ibc_plugin once automatically
require auth of _self, or if light client not initialized, can be called with any account's auth
pushsection( headers, blockroot_merkle )
headers, packed a bunch of headers' data.
blockroot_merkle, the blockroot_merkle of the first block of
headers
create a new section or add a bunch of continuous headers to an existing section
this action is called by ibc_plugin repeatedly as needed
can be called with any account's auth
rmfirstsctn( )
delete the old section and chaindb data in order to save contract memory consumption.
this function is called by ibc_plugin repeatedly as needed
can be called with any account's auth
Resource requirement
It's better to have not less than 5MB RAM for a light client of pipeline
consensus blockchains, and it's better to have not less than 2MB RAM for a light client of batch
consensus blockchains. Consumption of CPU and NET is very small.
Contract Design
Core Concept
In a blockchain with POW consensus, such as BTC and ETH, in order to get a trusted light client, starting from a block number, all block headers thereafter must be passed to the light client.
However, eosio uses DPOS consensus mechanism, so we don't need to pass all headers continually to get trusted headers, as long as we pass a bunch of continuous headers, then we collect enough BPs validation, and then we can get trusted points.
More efficiently, in a blockchain of batch
consensus (such as BOS), we only need one block header and corresponding BPs signatures, then we can confirm that this header is in LIB.
In order to maintain the trusted evidence chain of the light client, the most critical thing is to maintain the replacement of the BPs schedule.
The two tables chaindb
and sections
are combined to form the core data structures of this contract, and section
is the core concept. A section consists of a bunch of continuous block headers (such as block header from 10000 to 10300, then this section contains 301 block headers), the section record in table sections
do not store block headers data directly, just store information about these continuous headers, specific headers' data are stored in the chaindb
table.
section_type's definition as below:
Members description:
first
the first header's block number.last
the last header's block number.newprod_block_num
the header's block number whose member new_producers is not empty, if all headers' new_producers in this section is empty, newprod_block_num will always be zero.valid
this is a very important member, only when this value is true, then irreversible headers in this section can be used to verify cross-chain transactions. Under what circumstances will valid become true? there are two cases:There is no BPs schedule change in this section Then, When the section's length (length = last - first + 1) greater than lib_depth, the value becomes true.
There is BPs schedule change in this section No mater the current valid's value is ture or not, whenever a header contains new_producers be added to this section, the valid value of this section becomes false, the next process is a BPs schedule replacement process, and only after this process is over, then valid can be set to true.
producers
andblock_nums
these two data are used to record BP changes in the block generation process. using these two data, it ensures that each BP can produce up to 12 blocks continuity, and ensure that the last 15 BPs cannot be repeated, this will prevent BPs from doing evil.Note:
newprod_block_num
,valid
,producers
andblock_nums
are only used in a EOSIO blockchains with Pipeline BFT consensus (such as EOS mainnet), in a EOSIO blockchain with PBFT consensus (such as BOSCore with LIB boost), they are always the default values.
between sections There is no need for continuity between two sections. Any number of headers can be spaced, but these neglected headers cannot contain new_producers, that is to say, the process of BPs schedule replacement cannot be ignored, and the BPs replacement process must be complete within a section, only in this way can the light-client work properly.
Functions
assert_anchor_block_and_transaction_mroot(...)
This static function is called directly by the ibc.token contract to validate cross-chain transactions.
Attack Dimensions and Security Scheme
Hackers may want to attack this contract in a variety of ways, below are some possible ways of attacking they want to try and describe how this contract can defend against these attacks.
One BP collude with the relay to do evil Attack mode: One BP and the relay collude to do evil and push continuously headers generated by this BP. Defense: Each BP can only produce up to 12 blocks continuity, more than 12 headers will assert failed.
less than 15 continuous BPs on current active schedule collude with a relay to do evil The lib_depth is a const number 325, this can defend against such attack.
relay do evil As long as the initial block header of the ibc.chain contract is correct, a relay cannot push headers that are not correctly signed by BPs, so the relay either chooses to push headers signed by BPs or strikes.
© 2019 GitHub, Inc.
Last updated