UTXO Management Contract

utxomng.xsat

This contract stores Bitcoin UTXO data and keep it updated, allowing developers to retrieve UTXO data by reading the contract's table.

Actions

• Initialize configuration

• Add UTXO

• Delete UTXO

• Add block header

• Delete block header

• Parse UTXO

ENUM parsing_status

typedef uint8_t parsing_status;
static const parsing_status waiting = 1;
static const parsing_status parsing = 2;
static const parsing_status deleting_data = 3;
static const parsing_status distributing_rewards = 4;
static const parsing_status migrating = 5;

TABLE chainstate

scope

utxomng.xsat

params

• {uint64_t} num_utxos - total number of UTXOs

• {uint64_t} head_height - header block height for consensus success

• {uint64_t} irreversible_height - irreversible block height

• {uint64_t} irreversible_hash - irreversible block hash

• {uint64_t} migrating_height - block height in migration

• {uint64_t} migrating_hash - block hash in migration

• {uint64_t} migrating_num_utxos - the total number of UTXOs in the migration

• {uint64_t} migrated_num_utxos - number of UTXOs that have been migrated

• {uint32_t} num_provider_validators - the number of validators that have endorsed the current parsed block

• {uint32_t} num_validators_assigned - the number of validators that have been allocated rewards

• {name} miner - block miner account

• {name} synchronizer - block synchronizer account

• {name} parser - the account number of the parsing block

• {uint64_t} parsed_height - parsed block height

• {uint64_t} parsing_height - the current height being parsed

• {map<checksum256, parsing_progress_row>} parsing_progress_of - parsing progress @see parsing_progress_row

• {uint8_t} status - parsing status @see parsing_status

example

{
    "num_utxos": 26240,
    "head_height": 840031,
    "irreversible_height": 840002,
    "irreversible_hash": "00000000000000000002c0cc73626b56fb3ee1ce605b0ce125cc4fb58775a0a9",
    "migrating_height": 840003,
    "migrating_hash": "00000000000000000001cfe8671cb9269dfeded2c4e900e365fffae09b34b119",
    "migrating_num_utxos": 16278,
    "migrated_num_utxos": 10000,
    "num_provider_validators": 2,
    "num_validators_assigned": 0,
    "miner": "",
    "synchronizer": "alice",
    "parser": "alice",
    "parsed_height": 840008,
    "parsing_height": 840009,
    "parsing_progress_of": [
        {
            "first": "00000000000000000000c6075e66b667adcdb8935e6d9a877f5cf140c806ae87",
            "second": {
                "bucket_id": 11,
                "num_utxos": 0,
                "num_transactions": 0,
                "parsed_transactions": 0,
                "parsed_position": 0,
                "parsed_vin": 0,
                "parsed_vout": 0,
                "parser": "alice",
                "parse_expiration_time": "2024-08-08T02:44:43"
            }
        }
    ],
    "status": 5
}

TABLE config

scope

utxomng.xsat

params

• {uint16_t} parse_timeout_seconds - parsing timeout duration

• {uint16_t} num_validators_per_distribution - number of endorsing users each time rewards are distributed

• {uint16_t} num_retain_data_blocks - number of blocks to retain data

• {uint16_t} retained_spent_utxo_blocks - number of blocks to retained spent utxo

• {uint16_t} num_txs_per_verification - the number of tx for each verification (2^n)

• {uint8_t} num_merkle_layer - verify the number of merkle levels (log(num_txs_per_verification))

• {uint16_t} num_miner_priority_blocks - miners who produce blocks give priority to verifying the number of blocks

example

{
    "parse_timeout_seconds": 600,
    "num_validators_per_distribution": 100,
    "num_retain_data_blocks": 100,
    "retained_spent_utxo_blocks": 5000,
    "num_txs_per_verification": 1024,
    "num_merkle_layer": 10,
    "num_miner_priority_blocks": 10
}

TABLE utxos

scope

utxomng.xsat

params

• {uint64_t} id - primary key

• {checksum256} txid - transaction id

• {uint32_t} index - vout index

• {std::vector<uint8_t>} scriptpubkey - vout's script public key

• {uint32_t} value - utxo quantity

example

{
    "id": 2,
    "txid": "2bb85f4b004be6da54f766c17c1e855187327112c231ef2ff35ebad0ea67c69e",
    "index": 0,
    "scriptpubkey": "51203b8b3ab1453eb47e2d4903b963776680e30863df3625d3e74292338ae7928da1",
    "value": 1797928002
}

TABLE pendingutxos

scope

utxomng.xsat

params

• {uint64_t} id - primary key

• {uint64_t} height - block height

• {checksum256} hash - block hash

• {checksum256} txid - transaction id

• {uint32_t} index - vout index

• {std::vector<uint8_t>} scriptpubkey - script public key

• {uint32_t} value - utxo quantity

• {name} type - utxo type (vin or vout)

example

{
    "id": 2,
    "height": 840000,
    "hash": "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5",
    "txid": "2bb85f4b004be6da54f766c17c1e855187327112c231ef2ff35ebad0ea67c69e",
    "index": 0,
    "scriptpubkey": "51203b8b3ab1453eb47e2d4903b963776680e30863df3625d3e74292338ae7928da1",
    "value": 1797928002,
    "type": "vout"
}

TABLE spentutxos

scope

utxomng.xsat

params

• {uint64_t} id - primary key

• {uint64_t} height - block height

• {checksum256} txid - transaction id

• {uint32_t} index - vout index

• {std::vector<uint8_t>} scriptpubkey - script public key

• {uint32_t} value - utxo quantity

example

{
    "id": 2,
    "height": 840000,
    "txid": "2bb85f4b004be6da54f766c17c1e855187327112c231ef2ff35ebad0ea67c69e",
    "index": 0,
    "scriptpubkey": "51203b8b3ab1453eb47e2d4903b963776680e30863df3625d3e74292338ae7928da1",
    "value": 1797928002
}

TABLE blocks

scope

utxomng.xsat

params

• {uint64_t} height - block height

• {checksum256} hash - block hash

• {checksum256} cumulative_work - the cumulative workload of the block

• {uint32_t} version - block version

• {checksum256} previous_block_hash - hash in internal byte order of the previous block’s header

• {checksum256} merkle - the merkle root is derived from the hashes of all transactions included in this block

• {uint32_t} timestamp - the block time is a Unix epoch time

• {uint32_t} bits - an encoded version of the target threshold this block’s header hash must be less than or equal to

• {uint32_t} nonce - an arbitrary number miners change to modify the header hash in order to produce a hash less than or

example

{
    "height": 840011,
    "hash": "00000000000000000002d12efb02bcf70580b2eebf4b775578844640512e30f3",
    "cumulative_work": "0000000000000000000000000000000000000000753f3af9322a2a893cb6ece4",
    "version": 747323392,
    "previous_block_hash": "00000000000000000000da20f7d8e9e6412d4f1d8b62d88264cddbdd48256ba0",
    "merkle": "476eac37dd22a59952c5812f715a3e39b68663e40d80d756ba44d7d59e7d6a0a",
    "timestamp": 1713576761,
    "bits": 386089497,
    "nonce": 1492849681
}

TABLE block.extra

scope

utxomng.xsat

params

• {uint64_t} height - block height

• {uint64_t} bucket_id - the associated bucket number is used to obtain block data

example

{
    "height": 840001,
    "bucket_id": 1
}

TABLE consensusblk

scope

utxomng.xsat

params

• {uint64_t} bucket_id - the associated bucket number is used to obtain block data

• {uint64_t} height - block height

• {checksum256} hash - block hash

• {checksum256} cumulative_work - the cumulative workload of the block

• {uint32_t} version - block version

• {checksum256} previous_block_hash - hash in internal byte order of the previous block’s header

• {checksum256} merkle - the merkle root is derived from the hashes of all transactions included in this block

• {uint32_t} timestamp - the block time is a Unix epoch time

• {uint32_t} bits - an encoded version of the target threshold this block’s header hash must be less than or equal to

• {uint32_t} nonce - an arbitrary number miners change to modify the header hash in order to produce a hash less than or

• {name} miner - block miner account

• {name} synchronizer - block synchronizer account

• {name} parser - the last parser of the parsing block

• {uint64_t} num_utxos - the total number of vin and vout of the block

• {bool} parse - is it an parsed block

• {bool} irreversible - is it an irreversible block

• {time_point_sec} created_at - created at time

example

{
    "bucket_id": 5,
    "height": 840003,
    "hash": "00000000000000000001cfe8671cb9269dfeded2c4e900e365fffae09b34b119",
    "cumulative_work": "0000000000000000000000000000000000000000753cc66782a80f6f099fe68c",
    "version": 704643072,
    "previous_block_hash": "00000000000000000002c0cc73626b56fb3ee1ce605b0ce125cc4fb58775a0a9",
    "merkle": "2daee999cac85a7663bbc3a0e24bd7c86e009c005e7d801ef104d134b420179b",
    "timestamp": 1713572633,
    "bits": 386089497,
    "nonce": 213198539,
    "miner": "",
    "synchronizer": "alice",
    "parser": "alice",
    "num_utxos": 16278,
    "parse": 1,
    "irreversible": 1,
    "created_at": "2024-08-13T00:00:00"
}

STRUCT parsing_progress_row

params

• {uint64_t} bucket_id - the bucket_id currently being parsed

• {uint64_t} num_transactions - the number of transactions currently parsing the block

• {uint64_t} parsed_transactions - number of transactions currently resolved

• {uint64_t} parsed_position - the position of the currently parsed block

• {uint64_t} parsed_vin - the current transaction has been resolved to the vin index

• {uint64_t} parsed_vout - the current transaction has been resolved to the vout index

• {name} parser - the account number of the parsing block

• {time_point_sec} parsed_expiration_time - timeout for parsing chunks

example

{
    "bucket_id": 3,
    "num_transactions": 0,
    "parsed_transactions": 0,
    "parsed_position": 0,
    "parsed_vin": 0,
    "parsed_vout": 0,
    "parser": "alice",
    "parsed_expiration_time": "2024-07-13T14:39:32"
}

STRUCT process_block_result

params

• {string} status - current parsing status (waiting, migrating, deleting_data, distributing_rewards, parsing, parsing_completed)

• {uint64_t} height - block height

• {checksum256} block_hash - block hash

example

{
    "status": "parsing",
    "height": 840000,
    "block_hash": "0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5"
}

ACTION init

• authority: utxomng.xsat

Initialize block information to start parsing.

params

• {uint64_t} height - block height

• {checksum256} hash - block hash

• {checksum256} cumulative_work - the cumulative workload of the block

ACTION config

• authority: utxomng.xsat

Setting parameters.

params

• {uint16_t} parse_timeout_seconds - parsing timeout duration

• {uint16_t} num_validators_per_distribution - number of endorsing users each time rewards are distributed

• {uint16_t} retained_spent_utxo_blocks - number of blocks to retain utxo

• {uint16_t} num_retain_data_blocks - number of blocks to retain data

• {uint8_t} num_merkle_layer - verify the number of merkle levels (log(num_txs_per_verification))

• {uint16_t} num_miner_priority_blocks - miners who produce blocks give priority to verifying the number of blocks

ACTION addutxo

• authority: utxomng.xsat

Add utxo data.

params

• {uint64_t} id - primary id

• {checksum256} txid - transaction id

• {uint32_t} index - vout index

• {vector<uint8_t>} scriptpubkey - script public key

• {uint64_t} value - utxo quantity

ACTION delutxo

• authority: utxomng.xsat

Delete utxo data.

params

• {uint64_t} id - utxo id

ACTION addblock

• authority: utxomng.xsat

Add history block header.

params

• {uint64_t} height - block height

• {checksum256} hash - block hash

• {checksum256} cumulative_work - the cumulative workload of the block

• {uint32_t} version - block version

• {checksum256} previous_block_hash - hash in internal byte order of the previous block’s header

• {checksum256} merkle - the merkle root is derived from the hashes of all transactions included in this block

• {uint32_t} timestamp - the block time is a Unix epoch time

• {uint32_t} bits - an encoded version of the target threshold this block’s header hash must be less than or equal to

• {uint32_t} nonce - an arbitrary number miners change to modify the header hash in order to produce a hash less than or

ACTION delblock

• authority: utxomng.xsat

Delete block header.

params

• {uint64_t} height - block height

ACTION delspentutxo

• authority: utxomng.xsat

Delete spent utxo.

params

• {uint64_t} row - number of rows to delete utxo

• {uint64_t} nonce - unique value for each call to prevent duplicate transactions

ACTION delblockdata

• authority: utxomng.xsat

Delete block data.

params

• {uint64_t} row - number of rows of block data to delete

• {uint64_t} nonce - unique value for each call to prevent duplicate transactions

ACTION processblock

• authority: synchronizer

Parse utxo

params

• {name} synchronizer - synchronizer account

• {uint64_t} process_rows - number of vins and vouts to be parsed

• {uint64_t} nonce - unique value for each call to prevent duplicate transactions

ACTION consensus

• authority: blksync.xsat or blkendt.xsat

Reach consensus logic

params

• {uint64_t} height - block height

• {checksum256} hash - block hash