Skip to main content

CKB Syscalls for Script

A collection of CKB-VM syscalls. Also include relevant constant, such as return codes, sources, Cell fields, header fields, and input fields.

CKB-VM Syscalls​

VM Ver.Syscall IDC Function NameRust Function NameDescription
193ckb_exitexitImmediately terminate the execution of the currently running Script and exit with the specified return code.
12061ckb_load_tx_hashload_tx_hashCalculate the hash of the current transaction and copy it using partial loading.
12051ckb_load_transactionload_transactionSerialize the full transaction of the running Script using the Molecule Encoding 1 format and copy it using partial loading.
12062ckb_load_script_hashload_script_hashCalculate the hash of currently running Script and copy it using partial loading.
12052ckb_load_scriptload_scriptSerialize the currently running Script using the Molecule Encoding 1 format and copy it using partial loading.
12071ckb_load_cellload_cellSerialize the specified Cell in the current transaction using the Molecule Encoding 1 format and copy it using partial loading.
12081ckb_load_cell_by_fieldload_cell_by_fieldLoad a single field from the specified Cell in the current transaction and copy it using partial loading.
12092ckb_load_cell_dataload_cell_dataLoad the data from the Cell data field in the specified Cell from the current transaction and copy it using partial loading.
12091ckb_load_cell_data_as_codeload_cell_codeLoad the data from the Cell data field in the specified Cell from the current transaction, mark the loaded memory page as executable, and copy it using partial loading. The loaded code can then be executed by CKB-VM at a later time.
12073ckb_load_inputload_inputSerialize the specified input Cell in the current transaction using the Molecule Encoding 1 format and copy it using partial loading.
12083ckb_load_input_by_fieldload_input_by_fieldLoad a single field from the specified input Cell in the current transaction and copy it using partial loading.
12072ckb_load_headerload_headerSerialize the specified header associated with an input Cell, dep Cell, or header dep using the Molecule Encoding 1 format and copy it using partial loading.
12082ckb_load_header_by_fieldload_header_by_fieldLoad a single field from the specified header associated with an input Cell, dep Cell, or header dep and copy it using partial loading.
12074ckb_load_witnessload_witnessLoad the specified witness in the current transaction and copy it using partial loading.
12177ckb_debugdebugPrint the specified message in CKB's terminal output for the purposes of debugging.
22041ckb_vm_versionvm_versionReturn the version of CKB-VM being used to execute the current Script.
22042ckb_current_cyclescurrent_cyclesReturn the number of cycles consumed by the currently running Script immediately before executing this syscall. This syscall will consume an additional 500 cycles.
22043ckb_execexecRun a Script executable from the specified Cell using the current VM context. This replaces the original calling running Script executable with the new specified Script executable. This is similar to the exec call found in several operating systems.
22101ckb_spawnspawnRun a Script executable from the specified Cell using the current VM context, but return to the original calling Script executable upon termination. This is similar to the spawn function found in several operating systems and programming languages.
22104ckb_load_extensionload_block_extensionLoad the extension field data and copy it using partial loading.
22602ckb_waitPause until the execution of a process specified by pid has ended.
22603ckb_process_idGet the current process id.
22604ckb_pipeCreate a pipe with read-write pair of file descriptions.
22605ckb_writeWrite data to a pipe via a file descriptor.
22606ckb_readRead data from a pipe via a file descriptor.
22607ckb_inherited_file_descriptorsRetrieve the file descriptors available to the current process, which are passed in from the parent process.
22608ckb_closeManually close a file descriptor.

Constants​

Return Codes​

These are the return codes used by the CKB-VM syscalls.

Const No.C ExampleDescription
0CKB_SUCCESSNo error.
1CKB_INDEX_OUT_OF_BOUNDIndex out of bounds (e.g., no such input Cell).
2CKB_ITEM_MISSINGThe requested resource does not exist.
3CKB_LENGTH_NOT_ENOUGHThe supplied memory buffer is too small.
4CKB_INVALID_DATAThe data provided is invalid.
5CKB_WAIT_FAILUREThe file descriptor is invalid during syscall Wait.
6CKB_INVALID_FDThe file descriptor is not owned by this process.
7CKB_OTHER_END_CLOSEDThe other end of the pipe is closed.
8CKB_MAX_VMS_SPAWNEDThe maximum count of spawned processes has been reached.
9CKB_MAX_FDS_CREATEDThe maximum count of created pipes has been reached.

Source​

These are the sources for syscalls that query the transaction for input Cells, output Cells, dep Cells, and header deps.

Const No.C ExampleDescription
0x1CKB_SOURCE_INPUTAll input Cells in the transaction.
0x0100000000000001CKB_SOURCE_GROUP_INPUTOnly the input Cells in the transaction using the same Script as currently running Script.
2CKB_SOURCE_OUTPUTAll output Cells in the transaction.
0x0100000000000002CKB_SOURCE_GROUP_OUTPUTOnly the output Cells in the transaction using the same Script as currently running Script.
3CKB_SOURCE_CELL_DEPAll dep Cells in the transaction.
4CKB_SOURCE_HEADER_DEPAll header deps in the transaction.

Cell Fields​

These are the field specifiers for syscalls that request a specific field of a cell.

Const No.C ExampleDescription
0CKB_CELL_FIELD_CAPACITYThe capacity (CKB) contained in the Cell.
1CKB_CELL_FIELD_DATA_HASHThe hash of the data within the data field of the Cell.
2CKB_CELL_FIELD_LOCKThe Lock Script of the Cell.
3CKB_CELL_FIELD_LOCK_HASHThe hash of the Lock Script of the Cell.
4CKB_CELL_FIELD_TYPEThe Type Script of the Cell.
5CKB_CELL_FIELD_TYPE_HASHThe hash of the Type Script of the Cell.
6CKB_CELL_FIELD_OCCUPIED_CAPACITYThe amount of capacity (CKB) that is currently being used by the Cell.

Header Fields​

These are the field specifiers for syscalls that request a specific field of a header dep.

Const No.C ExampleDescription
0CKB_HEADER_FIELD_EPOCH_NUMBERThe epoch number for the header dep.
1CKB_HEADER_FIELD_EPOCH_START_BLOCK_NUMBERThe block number of first block in the epoch for the header dep.
2CKB_HEADER_FIELD_EPOCH_LENGTHThe length of the epoch for the header dep.

Input Fields​

These are the field specifiers for syscalls that request a specific field of an input Cell.

Const No.C ExampleDescription
0CKB_INPUT_FIELD_OUT_POINTThe out point of the specified input Cell.
1CKB_INPUT_FIELD_SINCEThe since value of the specified input Cell.

Spawn Example​

Consider the creation of a dependency library with a straightforward function that receives strings, concatenates them, and subsequently returns the resulting string to the caller (a.k.a, echo).

#include <stdint.h>
#include <string.h>

#include "ckb_syscalls.h"

#define CKB_STDIN (0)
#define CKB_STDOUT (1)

// Function read_all reads from fd until an error or EOF and returns the data it read.
int ckb_read_all(uint64_t fd, void* buffer, size_t* length) {
    int err = 0;
    size_t read_length = 0;
    size_t full_length = *length;
    uint8_t* b = buffer;
    while (true) {
        size_t n = full_length - read_length;
        err = ckb_read(fd, b, &n);
        if (err == CKB_OTHER_END_CLOSED) {
            err = 0;
            *length = read_length;
            break;
        } else {
            if (err != 0) {
                goto exit;
            }
        }
        if (full_length - read_length == 0) {
            err = CKB_LENGTH_NOT_ENOUGH;
            if (err != 0) {
                goto exit;
            }
        }
        b += n;
        read_length += n;
        *length = read_length;
    }

exit:
    return err;
}

// Mimic stdio fds on linux
int create_std_fds(uint64_t* fds, uint64_t* inherited_fds) {
    int err = 0;

    uint64_t to_child[2] = {0};
    uint64_t to_parent[2] = {0};
    err = ckb_pipe(to_child);
    if (err != 0) {
        goto exit;
    }
    err = ckb_pipe(to_parent);
    if (err != 0) {
        goto exit;
    }

    inherited_fds[0] = to_child[0];
    inherited_fds[1] = to_parent[1];
    inherited_fds[2] = 0;

    fds[CKB_STDIN] = to_parent[0];
    fds[CKB_STDOUT] = to_child[1];

exit:
    return err;
}

int main() {
    int err = 0;

    const char* argv[] = {};
    uint64_t pid = 0;
    uint64_t fds[2] = {0};
    // it must be end with zero
    uint64_t inherited_fds[3] = {0};
    err = create_std_fds(fds, inherited_fds);
    if (err != 0) {
        goto exit;
    }

    spawn_args_t spgs = {
        .argc = 0,
        .argv = argv,
        .process_id = &pid,
        .inherited_fds = inherited_fds,
    };
    err = ckb_spawn(0, 3, 0, 0, &spgs);
    if (err != 0) {
        goto exit;
    }

    size_t length = 0;
    length = 12;
    err = ckb_write(fds[CKB_STDOUT], "Hello World!", &length);
    if (err != 0) {
        goto exit;
    }
    err = ckb_close(fds[CKB_STDOUT]);
    if (err != 0) {
        goto exit;
    }

    uint8_t buffer[1024] = {0};
    length = 1024;
    err = ckb_read_all(fds[CKB_STDIN], buffer, &length);
    if (err != 0) {
        goto exit;
    }
    err = memcmp("Hello World!", buffer, length);
    if (err != 0) {
        goto exit;
    }

exit:
    return err;
}