# Block Synchronization Contract

## blksync.xsat

### Actions

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

### Quickstart

```bash
# 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

```bash
$ 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&#x20;

blksync.xsat

#### params

* `{uint64_t} bucket_id` - latest bucket\_id

#### example

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```bash
$ 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

```bash
$ 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

```bash
$ 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

```bash
$ 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

```bash
$ 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

```bash
$ 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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.exsat.network/developer-guides/native-layer-developer-guides/exsat-consensus-contracts/block-synchronization-contract.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.