Data Structures of Nervos CKB

NumberCategoryStatusAuthorOrganizationCreated
0019InformationalDraftXuejie XiaoNervos Foundation2019-03-26

Data Structures of Nervos CKB

This documents explains all the basic data structures used in CKB.

Cell

Example

{
"capacity": "0x19995d0ccf",
"lock": {
"code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
"args": "0x0a486fb8f6fe60f76f001d6372da41be91172259",
"hash_type": "type"
},
"type": null
}

Description

NameTypeDescription
capacityuint64The size of the cell (in shannons). When a new cell is generated (via transaction), one of the verification rule is capacity_in_bytes >= len(capacity) + len(data) + len(type) + len(lock). This value also represents the balance of CKB coin, just like the nValue field in the Bitcoin's CTxOut. (E.g. Alice owns 100 CKB coins means she can unlock a group of cells that has 100 amount of bytes (which is 10_000_000_000 amount of shannons) in total.). The actual value is returned in hex string format.
typeScriptA Script that defines the type of the cell. It limits how the data field of the new cells can be changed from old cells. type is required to has a data structure of script. This field is optional.
lockScriptA Script that defines the ownership of the cell, just like the scriptPubKey field in the Bitcoin's CTxOut. Whoever can provide unlock arguments that makes the execution of this script success can consume this cell as input in an transaction (i.e. has the ownership of this cell).

More information about Cell can be found in the whitepaper.

Script

Example

{
"code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
"args": "0x0a486fb8f6fe60f76f001d6372da41be91172259",
"hash_type": "type"
}

Description

NameTypeDescription
code_hashH256(hash)The hash of ELF formatted RISC-V binary that contains a CKB script. For space efficiency consideration, the actual script is attached to current transaction as a dep cell. Depending on the value of hash_type, the hash specified here should either match the hash of cell data part in the dep cell, or the hash of type script in the dep cell. The actual binary is loaded into an CKB-VM instance when they are specified upon the transaction verification.
argsBytesThe argument as the script input. The argument here is imported into the CKB-VM instance as the input argument for the scripts.
hash_typeString, could be type or dataThe interpretation of code hash when looking for matched dep cells. If this is data, code_hash should match the blake2b hash of data in a dep cell; if this is type, code_hash should instead match the type script hash of a dep cell.

When a script is validated, CKB will run it in a RISC-V VM, args must be loaded via special CKB syscalls. UNIX standard argc/argv convention is not used in CKB. For more information on the CKB VM please refer to CKB VM RFC.

For more information regarding how Script structure is implemented please refer to the CKB repo.

Transaction

Example

{
"version": "0x0",
"cell_deps": [
{
"out_point": {
"tx_hash": "0xbd864a269201d7052d4eb3f753f49f7c68b8edc386afc8bb6ef3e15a05facca2",
"index": "0x0"
},
"dep_type": "dep_group"
}
],
"header_deps": [
"0xaa1124da6a230435298d83a12dd6c13f7d58caf7853f39cea8aad992ef88a422"
],
"inputs": [
{
"previous_output": {
"tx_hash": "0x8389eba3ae414fb6a3019aa47583e9be36d096c55ab2e00ec49bdb012c24844d",
"index": "0x1"
},
"since": "0x0"
}
],
"outputs": [
{
"capacity": "0x746a528800",
"lock": {
"code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
"args": "0x56008385085341a6ed68decfabb3ba1f3eea7b68",
"hash_type": "type"
},
"type": null
},
{
"capacity": "0x1561d9307e88",
"lock": {
"code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
"args": "0x886d23a7858f12ebf924baaacd774a5e2cf81132",
"hash_type": "type"
},
"type": null
}
],
"outputs_data": [
"0x",
"0x"
],
"witnesses": ["0x55000000100000005500000055000000410000004a975e08ff99fa0001
42ff3b86a836b43884b5b46f91b149f7cc5300e8607e633b7a29c94dc01c6616a12f62e74a1
415f57fcc5a00e41ac2d7034e90edf4fdf800"
]
}

Description

Transaction

NameTypeDescription
versionuint32The version of the transaction. It‘s used to distinguish transactions when there's a fork happened to the blockchain system.
cell_deps[CellDep]An array of outpoint pointing to the cells that are dependencies of this transaction. Only live cells can be listed here. The cells listed are read-only.
header_deps[H256(hash)]An array of H256 hashes pointing to block headers that are dependencies of this transaction. Notice maturity rules apply here: a transaction can only reference a header that is at least 4 epochs old.
inputs[CellInput]An array of referenced cell inputs. See below for explanations of underlying data structure
outputs[Cells], see above for detailsAn array of cells that are used as outputs, i.e. the newly generated cells. These are the cells may be used as inputs for other transactions. Each of the Cell has the same structure to the Cell section above.
outputs_data[Bytes]An array of cell data for each cell output. The actual data are kept separated from outputs for the ease of CKB script handling and for the possibility of future optimizations.
witnesses[Bytes]Witnesses provided by transaction creator to make the execution of corresponding lock script success. One example here, is that signatures might be include here to make sure a signature verification lock script passes.

CellDep

NameTypeDescription
out_pointOutPointA cell outpoint that point to the cells used as deps. Dep cells are dependencies of a transaction, it could be used to include code that are loaded into CKB VM, or data that could be used in script execution.
dep_typeString, either code or dep_groupThe way to interpret referenced cell deps. A cell dep could be referenced in 2 ways: for a cell dep with code as dep_type, the dep cell is directly included in the transaction. If a cell dep dep_type uses dep_group, however, CKB would first load this dep cell, assume the content of this cell contains a list of cell deps, then use the extracted list of cell deps to replace current cell dep, and include them in current transaction. This provides a quicker and smaller(in terms of transaction size) to include multiple commonly used dep cells in one CellDep construct.

CellInput

NameTypeDescription
previous_outputOutPointA cell outpoint that point to the cells used as inputs. Input cells are in fact the output of previous transactions, hence they are noted as previous_output here. These cells are referred through outpoint, which contains the transaction hash of the previous transaction, as well as this cell's index in its transaction's output list.
sinceuint64Since value guarding current referenced inputs. Please refer to the Since RFC for details on this field.

OutPoint

NameTypeDescription
hashH256(hash)The hash of the transaction that this cell belongs to.
indexuint32The index of the cell in its transaction's output list.

More information about the Transaction of Nervos CKB can be found in whitepaper.

Block

Example

{
"uncles": [
{
"proposals": [
],
"header": {
"compact_target": "0x1a9c7b1a",
"hash": "0x87764caf4a0e99302f1382421da1fe2f18382a49eac2d611220056b0854868e3",
"number": "0x129d3",
"parent_hash": "0x815ecf2140169b9d283332c7550ce8b6405a120d5c21a7aa99d8a75eb9e77ead",
"nonce": "0x78b105de64fc38a200000004139b0200",
"timestamp": "0x16e62df76ed",
"transactions_root": "0x66ab0046436f97aefefe0549772bf36d96502d14ad736f7f4b1be8274420ca0f",
"proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"uncles_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"version": "0x0",
"epoch": "0x7080291000049",
"dao": "0x7088b3ee3e738900a9c257048aa129002cd43cd745100e000066ac8bd8850d00"
}
}
],
"proposals": [
"0x5b2c8121455362cf70ff"
],
"transactions": [
{
"version": "0x0",
"cell_deps": [
],
"header_deps": [
],
"inputs": [
{
"previous_output": {
"tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"index": "0xffffffff"
},
"since": "0x129d5"
}
],
"outputs": [
{
"capacity": "0x1996822511",
"lock": {
"code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
"args": "0x2ec3a5fb4098b14f4887555fe58d966cab2c6a63",
"hash_type": "type"
},
"type": null
}
],
"outputs_data": [
"0x"
],
"witnesses": ["0x590000000c00000055000000490000001000000030000000310000009b
d7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce801140000002
ec3a5fb4098b14f4887555fe58d966cab2c6a6300000000"
],
"hash": "0x84395bf085f48de9f8813df8181e33d5a43ab9d92df5c0e77d711e1d47e4746d"
}
],
"header": {
"compact_target": "0x1a9c7b1a",
"hash": "0xf355b7bbb50627aa26839b9f4d65e83648b80c0a65354d78a782744ee7b0d12d",
"number": "0x129d5",
"parent_hash": "0x4dd7ae439977f1b01a8c9af7cd4be2d7bccce19fcc65b47559fe34b8f32917bf",
"nonce": "0x91c4b4746ffb69fe000000809a170200",
"timestamp": "0x16e62dfdb19",
"transactions_root": "0x03c72b4c2138309eb46342d4ab7b882271ac4a9a12d2dcd7238095c2d131caa6",
"proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"uncles_hash": "0x90eb89b87b4af4c391f3f25d0d9f59b8ef946d9627b7e86283c68476fee7328b",
"version": "0x0",
"epoch": "0x7080293000049",
"dao": "0xae6c356c8073890051f05bd38ea12900939dbc2754100e0000a0d962db850d00"
}
}

Description

Block

NameTypeDescription
headerHeaderThe block header of the block. This part contains some metadata of the block. See the Header section below for the details of this part.
transactions[Transaction]An array of committed transactions contained in the block. Each element of this array has the same structure as the Transaction structure above.
proposals[string]An array of hex-encoded short transaction ID of the proposed transactions.
uncles[UncleBlock]An array of uncle blocks of the block. See the UncleBlock section below for the details of this part.

Header

(header is a sub-structure of block and UncleBlock.)

NameTypeDescription
compact_targetuint32The difficulty of the PoW puzzle represented in compact target format.
numberuint64The block height.
parent_hashH256(hash)The hash of the parent block.
nonceuint128The nonce. Similar to the nonce in Bitcoin. Represent the solution of the PoW puzzle
timestampuint64A Unix time timestamp in milliseconds.
transactions_rootH256(hash)The hash of concatenated transaction hashes CBMT root and transaction witness hashes CBMT root.
proposals_hashH256(hash)The hash of concatenated proposal ids. (all zeros when proposals is empty)
uncles_hashH256(hash)The hash of concatenated hashes of uncle block headers. (all zeros when uncles is empty)
versionuint32The version of the block. This is for solving the compatibility issues might be occurred after a fork.
epochuint64Current epoch information. Assume number represents the current epoch number, index represents the index of the block in the current epoch(start at 0), length represents the length of current epoch. The value store here will then be (number & 0xFFFFFF) \| ((index & 0xFFFF) << 24) \| ((length & 0xFFFF) << 40)
daoBytesData containing DAO related information. Please refer to Nervos DAO RFC for details on this field.

UncleBlock

(UncleBlock is a sub-structure of Block.)

NameTypeDescription
headerHeaderThe block header of the uncle block. The inner structure of this part is same as the Header structure above.
proposals[string]An array of short transaction IDs of the proposed transactions in the uncle block.