Block Synchronization Contract

blksync.xsat

Actions

Initialize block bucket
Sharding of upload chunks
Delete block shards
Verify the validity of the block

Quickstart

# initbucket @synchronizer
$ cleos push action blksync.xsat initbucket '{"synchronizer": "alice", "height": 840000, "hash": "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5", "block_size": 2325617, "num_chunks": 11}' -p alice

# pushchunk @synchronizer
$ cleos push action blksync.xsat pushchunk '{"synchronizer": "alice", "height": 840000, "hash": "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5", "chunk_id": 0, "data": "<data>"}' -p alice

# delchunk @synchronizer
$ cleos push action blksync.xsat delchunk '{"synchronizer": "alice", "height": 840000, "hash": "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5", "chunk_id": 0}' -p alice

# delbucket @synchronizer
$ cleos push action blksync.xsat delbucket '{"synchronizer": "alice", "height": 840000, "hash": "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5"}' -p alice

# verify @synchronizer
$ cleos push action blksync.xsat verify '{"synchronizer": "alice", "height": 840000, "hash": "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5", "nonce": 1}' -p alice

Table Information

$ cleos get table blksync.xsat <synchronizer> blockbuckets
# by status
$ cleos get table blksync.xsat <synchronizer> blockbuckets --index 2 --key-type uint64_t -U <status> -L <status>
# by blockid
$ cleos get table blksync.xsat <synchronizer> blockbuckets --index 3 --key-type sha256 -U <blockid> -L <blockid>

$ cleos get table blksync.xsat <height> passedindexs
# by hash
$ cleos get table blksync.xsat <height> block.chunk  --index 3 --key-type sha256 -U <hash> -L <hash>

$ cleos get table blksync.xsat <height> blockminer

ENUM `block_status`

typedef uint8_t block_status;
static const block_status uploading = 1;
static const block_status upload_complete = 2;
static const block_status verify_merkle = 3;
static const block_status verify_parent_hash = 4;
static const block_status waiting_miner_verification = 5;
static const block_status verify_fail = 6;
static const block_status verify_pass = 7;

TABLE `globalid`

scope

blksync.xsat

params

{uint64_t} bucket_id - latest bucket_id

example

{
  "bucket_id": 1
}

STRUCT `verify_info_data`

params

{name} miner - block miner account
{vector<string>} btc_miners - btc miner account
{checksum256} previous_block_hash - hash in internal byte order of the previous block’s header
{checksum256} work - block workload
{checksum256} witness_reserve_value - witness reserve value in the block
{std::optional<checksum256>} - witness commitment in the block
{bool} has_witness - whether any of the transactions in the block contains witness
{checksum256} header_merkle - the merkle root of the block
{std::vector<checksum256>} relay_header_merkle - check header merkle relay data
{std::vector<checksum256>} relay_witness_merkle - check witness merkle relay data
{uint64_t} num_transactions - the number of transactions in the block
{uint64_t} processed_position - the location of the block that has been resolved
{uint64_t} processed_transactions - the number of processed transactions
{uint32_t} timestamp - the block time in seconds since epoch (Jan 1 1970 GMT)
{uint32_t} bits - the bits

example

{
  "miner": "",
  "btc_miners": [
      "1BM1sAcrfV6d4zPKytzziu4McLQDsFC2Qc"
  ],
  "previous_block_hash": "000000000000000000029bfa01a7cee248f85425e0d0b198f4947717d4d3441e",
  "work": "000000000000000000000000000000000000000000004e9235f043634662e0cb",
  "witness_reserve_value": "0000000000000000000000000000000000000000000000000000000000000000",
  "witness_commitment": "aeaa22969e5aac88afd1ac14b19a3ad3a58f5eb0dd151ddddfc749297ebfb020",
  "has_witness": 1,
  "header_merkle": "f3f07d3e4636fa1ae5300b3bc148c361beafd7b3309d30b7ba136d0e59a9a0e5",
  "relay_header_merkle": [
     "d1c9861b0d129b34bb6b733c624bbe0a9b10ff01c6047dced64586ef584987f4",
     "bd95f641a29379f0b5a26961de4bb36bd9568a67ca0615be3fb0a28152ff1806",
     "667eb5d36c67667ae4f10bd30a62e3797e8700e1fbb5e3f754a7526f2b7db1e2",
     "5193ac78b5ef8f570ed24946fbcb96d71284faa27b86296093a93eb5c1cfac06"
  ],
  "relay_witness_merkle": [
     "8a080509ebf6baca260d466c2669200d9b4de750f6a190382c4e8ab6ab6859db",
     "d65d4261be51ca1193e718a6f0cfe6415b6f122f4c3df87861e7452916b45d78",
     "95aa96164225b76afa32a9b2903241067b0ea71228cc2d51b9321148c4e37dd3",
     "0dfca7530a6e950ecdec67c60e5d9574404cc97b333a4e24e3cf2eadd5eb76bd"
  ],
  "num_transactions": 4899,
  "processed_transactions": 4096,
  "processed_position": 1197889,
  "timestamp": 1713608213,
  "bits": 386089497
}

TABLE `blockbuckets`

scope `validator`

params

{uint64_t} bucket_id - primary key, bucket_id is the scope associated with block.bucket
{uint64_t} height - block height
{uint32_t} size -block size
{uint32_t} uploaded_size - the latest release id
{uint8_t} num_chunks - number of chunks
{uint8_t} uploaded_num_chunks - number of chunks that have been uploaded
{uint32_t} chunk_size - the size of each chunk
{vector<uint8_t>} chunk_ids - the uploaded chunk_id
{string} reason - reason for verification failure
{block_status} status - current block status
{time_point_sec} updated_at - updated at time
{std::optional<verify_info_data>} verify_info - @see struct verify_info_data

example

{
  "bucket_id": 81,
  "height": 840062,
  "hash": "00000000000000000002fc5099a59501b26c34819ac52cc16141275f158c3c6a",
  "size": 1434031,
  "uploaded_size": 1434031,
  "num_chunks": 11,
  "uploaded_num_chunks": 11,
  "chunk_size": 256000,
  "chunk_ids": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
  "reason": "",
  "status": 3,
  "updated_at": "2024-08-19T00:00:00",
  "verify_info": {
      "miner": "",
      "btc_miners": [
          "1BM1sAcrfV6d4zPKytzziu4McLQDsFC2Qc"
      ],
      "previous_block_hash": "000000000000000000029bfa01a7cee248f85425e0d0b198f4947717d4d3441e",
      "work": "000000000000000000000000000000000000000000004e9235f043634662e0cb",
      "witness_reserve_value": "0000000000000000000000000000000000000000000000000000000000000000",
      "witness_commitment": "aeaa22969e5aac88afd1ac14b19a3ad3a58f5eb0dd151ddddfc749297ebfb020",
      "has_witness": 1,
      "header_merkle": "f3f07d3e4636fa1ae5300b3bc148c361beafd7b3309d30b7ba136d0e59a9a0e5",
      "relay_header_merkle": [
         "d1c9861b0d129b34bb6b733c624bbe0a9b10ff01c6047dced64586ef584987f4",
         "bd95f641a29379f0b5a26961de4bb36bd9568a67ca0615be3fb0a28152ff1806",
         "667eb5d36c67667ae4f10bd30a62e3797e8700e1fbb5e3f754a7526f2b7db1e2",
         "5193ac78b5ef8f570ed24946fbcb96d71284faa27b86296093a93eb5c1cfac06"
      ],
      "relay_witness_merkle": [
          "8a080509ebf6baca260d466c2669200d9b4de750f6a190382c4e8ab6ab6859db",
          "d65d4261be51ca1193e718a6f0cfe6415b6f122f4c3df87861e7452916b45d78",
          "95aa96164225b76afa32a9b2903241067b0ea71228cc2d51b9321148c4e37dd3",
          "0dfca7530a6e950ecdec67c60e5d9574404cc97b333a4e24e3cf2eadd5eb76bd"
      ],
      "num_transactions": 4899,
      "processed_transactions": 4096,
      "processed_position": 1197889,
      "timestamp": 1713608213,
      "bits": 386089497
  }
}

TABLE `passedindexs`

scope `height`

params

{uint64_t} id - primary key
{checksum256} hash - block hash
{checksum256} cumulative_work - the cumulative workload of the block
{uint64_t} bucket_id - bucket_id is used to obtain block data
{name} synchronizer - synchronizer account
{name} miner - miner account
{time_point_sec} created_at - created at time

example

{
  "id": 0,
  "hash": "000000000000000000029bfa01a7cee248f85425e0d0b198f4947717d4d3441e",
  "cumulative_work": "0000000000000000000000000000000000000000753f3af9322a2a893cb6ece4",
  "bucket_id": 80,
  "synchronizer": "test.xsat",
  "miner": "alice",
  "created_at": "2024-08-13T00:00:00"
}

TABLE `blockminer`

scope `height`

params

{uint64_t} id - primary key
{checksum256} hash - block hash
{name} miner - block miner account
{uint32_t} block_num - the block number that passed the first verification

example

{
  "id": 0,
  "hash": "000000000000000000029bfa01a7cee248f85425e0d0b198f4947717d4d3441e",
  "miner": "alice",
  "expired_block_num": 210000
}

TABLE `block.chunk`

scope `bucket_id`

params

{std::vector<char>} data - the block chunk for block

example

{
  "data": ""
}

STRUCT `verify_block_result`

params

{string} status - verification status (uploading, upload_complete, verify_merkle, verify_parent_hash, waiting_miner_verification, verify_pass, verify_fail)
{string} reason - reason for verification failure
{checksum256} block_hash - block hash

example

{
  "status": "verify_pass",
  "reason": "",
  "block_hash": "000000000000000000029bfa01a7cee248f85425e0d0b198f4947717d4d3441e"
}

ACTION `consensus`

authority: utxomng.xsat

Consensus completion processing logic

params

{uint64_t} height - block height
{name} synchronizer - synchronizer account
{uint64_t} bucket_id - bucket id

example

$ cleos push action blksync.xsat consensus '[840000, "alice", 1]' -p utxomng.xsat

ACTION `delchunks`

authority: utxomng.xsat

Deletion of historical block data after parsing is completed

params

{uint64_t} bucket_id - bucket_id of block data to be deleted

example

$ cleos push action blksync.xsat delchunks '[1]' -p utxomng.xsat

ACTION `initbucket`

authority: synchronizer

Initialize the block information to be uploaded

params

{name} synchronizer - synchronizer account
{uint64_t} height - block height
{checksum256} hash - block hash
{uint32_t} size -block size
{uint8_t} num_chunks - number of chunks
{uint32_t} chunk_size - the size of each chunk

example

$ cleos push action blksync.xsat initbucket '["alice", 840000, "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5", 2325617, 9, 25600]' -p alice

ACTION `pushchunk`

authority: synchronizer

Upload block shard data

params

{name} synchronizer - synchronizer account
{uint64_t} height - block height
{checksum256} hash - block hash
{uint8_t} chunk_id - chunk id
{std::vector<char>} data - block data to be uploaded

example

$ cleos push action blksync.xsat pushchunk '["alice", 840000, "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5", 0, ""]' -p alice

ACTION `delchunk`

authority: synchronizer

Delete block shard data

params

{name} synchronizer - synchronizer account
{uint64_t} height - block height
{checksum256} hash - block hash
{uint8_t} chunk_id - chunk id

example

$ cleos push action blksync.xsat delchunk '["alice", 840000, "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5", 0]' -p alice

ACTION `delbucket`

authority: synchronizer

Delete the entire block data

params

{name} synchronizer - synchronizer account
{uint64_t} height - block height
{checksum256} hash - block hash

example

$ cleos push action blksync.xsat delbucket '["alice", 840000, "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5"]' -p alice

ACTION `verify`

authority: synchronizer

Verify block data

params

{name} synchronizer - synchronizer account
{uint64_t} height - block height
{checksum256} hash - block hash
{uint64_t} nonce - unique value for each call to prevent duplicate transactions

example

$ cleos push action blksync.xsat verify '["alice", 840000, "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5", 1]' -p alice

PreviousBlock Consensus Contract NextValidator Management Contract

Last updated 9 months ago

hashtagblksync.xsat

hashtagActions

hashtagQuickstart

hashtagTable Information

hashtagENUM block_status

hashtagTABLE globalid

hashtagscope

hashtagparams

hashtagexample

hashtagSTRUCT verify_info_data

hashtagparams

hashtagexample

hashtagTABLE blockbuckets

hashtagscope validator

hashtagparams

hashtagexample

hashtagTABLE passedindexs

hashtagscope height

hashtagparams

hashtagexample

hashtagTABLE blockminer

hashtagscope height

hashtagparams

hashtagexample

hashtagTABLE block.chunk

hashtagscope bucket_id

hashtagparams

hashtagexample

hashtagSTRUCT verify_block_result

hashtagparams

hashtagexample

hashtagACTION consensus

hashtagparams

hashtagexample

hashtagACTION delchunks

hashtagparams

hashtagexample

hashtagACTION initbucket

hashtagparams

hashtagexample

hashtagACTION pushchunk

hashtagparams

hashtagexample

hashtagACTION delchunk

hashtagparams

hashtagexample

hashtagACTION delbucket

hashtagparams

hashtagexample

hashtagACTION verify

hashtagparams

hashtagexample

blksync.xsat

Actions

Quickstart

Table Information

ENUM `block_status`

TABLE `globalid`

scope

params

example

STRUCT `verify_info_data`

params

example

TABLE `blockbuckets`

scope `validator`

params

example

TABLE `passedindexs`

scope `height`

params

example

TABLE `blockminer`

scope `height`

params

example

TABLE `block.chunk`

scope `bucket_id`

params

example

STRUCT `verify_block_result`

params

example

ACTION `consensus`

params

example

ACTION `delchunks`

params

example

ACTION `initbucket`

params

example

ACTION `pushchunk`

params

example

ACTION `delchunk`

params

example

ACTION `delbucket`

params

example

ACTION `verify`

params

example