Skip to main content

Syscalls

In smart contract development, it’s often necessary to use transaction-related functions—such as loadScript mentioned in the Quick Start guide. This chapter introduces VM Syscalls and their corresponding high-level abstractions.

Syscalls (bindings)​

The syscalls, enums, and constants provided in the bindings are mostly direct wrappers around VM syscalls in ckb-js-vm, with function names and parameters nearly identical to their VM counterparts. For detailed behavior, refer to the RFCs; we won’t repeat them here.

QueryIter​

A advanced iterator to manipulate cells/inputs/headers/witnesses.

Syntax​

export type QueryFunction<T> = (
  index: number,
  source: bindings.SourceType,
) => T;
export class QueryIter<T> implements Iterator<T> {
  private queryFn: QueryFunction<T>;
  private index: number;
  private source: bindings.SourceType;
  ...
}

Remarks​

The functions listed in Load Cells info can be used with QueryIter. In some cases, a custom QueryIter can also be constructed.

Example​

let cellIters = new HighLevel.QueryIter(
  HighLevel.loadCell,
  bindings.SOURCE_INPUT
);
for (let it of cellIters) {
  // ...
}

let iters = new HighLevel();

Load Cells info​

The following functions are used to load transaction information.

Syntax​

function loadCell(index: number, source: bindings.SourceType): CellOutput
function loadInput(index: number, source: bindings.SourceType): CellInput
function loadWitness(index: number, source: bindings.SourceType): ArrayBuffer
function loadWitnessArgs(index: number, source: bindings.SourceType): WitnessArgs
function loadCellCapacity(index: number, source: bindings.SourceType): bigint
function loadCellOccupiedCapacity(index: number, source: bindings.SourceType): bigint
function loadCellData(index: number, source: bindings.SourceType): ArrayBuffer
function loadCellTypeHash(index: number, source: bindings.SourceType): ArrayBuffer
function loadCellLock(index: number, source: bindings.SourceType): Script
function loadCellLockHash(index: number, source: bindings.SourceType): Bytes
function loadCellType(index: number, source: bindings.SourceType): Script | null
function loadHeaderEpochNumber(index: number, source: bindings.SourceType): bigint
function loadHeaderEpochStartBlockNumber(index: number, source: bindings.SourceType): bigint
function loadHeaderEpochLength(index: number, source: bindings.SourceType): bigint
function loadHeader(index: number, source: bindings.SourceType): Header
function loadInputSince(index: number, source: bindings.SourceType): bigint
function loadInputOutPoint(index: number, source: bindings.SourceType): OutPoint

Parameters​

index: The index of the cell to load

source: The source to load the cell from

Return​

Return the get value. (Different functions will have different return values)

loadTransaction​

Load all transaction information.

Syntax​

function loadTransaction(): Transaction

Parameters​

None

Return​

Molecule struct Transaction.

loadTxHash​

Load transaction hash

Syntax​

function loadTxHash(): Bytes

Parameters​

None

Return​

The hash of the current transaction, fixed length 32 bytes.

loadScriptHash​

Load current script hash

Syntax​

function loadScriptHash(): Bytes

Parameters​

None

return​

Load current script hash, fixed length 32 bytes.

loadScript​

Load script

Syntax​

function loadScript(): Script

Parameters​

None

Return​

The current script.

findCellByDataHash​

Find cell by data_hash.

Iterate and find the cell which data hash equals dataHash, return the index of the first cell found, otherwise return null.

Syntax​

function findCellByDataHash(
  dataHash: Bytes,
  source: bindings.SourceType,
): number | null

Parameters​

dataHash: The data hash to search for (must be 32 bytes) source: The source to search in.

Return​

The index of the found cell or null if not found

lookForDepWithHash2​

Look for a dep cell with specific code hash

Syntax​

function lookForDepWithHash2(codeHash: Bytes, hashType: number): number

Parameters​

codeHash: The code hash to search for (must be 32 bytes) hashType: The type of hash to search for (type or data)

Return​

The index of the found cell.

lookForDepWithDataHash​

Look for a dep cell with specific data hash

Syntax​

function lookForDepWithDataHash(dataHash: Bytes): number

Parameters​

dataHash: The data hash to search for (must be 32 bytes)

Return​

The index of the found cell

checkTypeId​

Validates that the script follows the Type ID rule. 一般用于创建唯一的 Script。

Syntax​

export function checkTypeId(offset: number): void

Parameters​

offset: Byte offset in script args where Type ID starts

Throws Error​

Throws with TypeIDError code if validation fails or ID cannot be retrieved.

Remarks​

note
  • Checks if the Type ID (32-byte value) stored in script args at specified offset is valid according to Type ID rules. Internally uses validateTypeId.
  • ckb-js-vm will occupy the first 35 bytes of args, so offset must be greater than or equal to 35.

Type ID describes a way of using a special type script which can create a singleton type - there's only one live cell of this type. With Type ID nobody could create another code cell with the same type script hash, which makes it a useful companion to Type hash type.

By CKB RFC

The above RFC introduces the concept of Type ID. The ckb-js-std library provides a utility function, HighLevel.checkTypeId, to validate whether a script conforms to the Type ID rules.

The function classifies the validation logic based on the usage scenario of the Type ID:

  • Minting: GroupInput is empty, and GroupOutput only one cell.
  • Transfer: Both GroupInput and GroupOutput only one cell.
  • Burning: GroupInput only one cell, and GroupOutput is empty.

If there are multiple cells in either GroupInput or GroupOutput, the function throw Error.

For Transfer and Burning cases, the function immediately returns.

In the Minting case, the following data is used to compute the Type ID (i.e., the hash):

  • The first CellInput of the transaction (retrieved via load_input(0, Source::Input)?);
  • The index of the current cell.

Since all input cells in the transaction are consumed and the index ensures that no other cell in the same transaction can compute the same hash, uniqueness of the Type ID is guaranteed.

Example​

The contract: check-type-id

The tests in tests/src/type-id.test.ts. When minting, You need to create type-id through inputCell and index and check it in the contract. check type-id minting success and check type-id minting failed.

When transaction, Will not check again. check type-id transaction success.

spawnCell​

Spawn a new process from a cell.

Syntax​

export function spawnCell(
  codeHash: ArrayBuffer,
  hashType: number,
  offset: number,
  length: number,
  args: SpawnArgs
): number;

Parameters​

  • codeHash : The code hash of the cell to spawn
  • hashType : The hash type of the code (use SCRIPTHASH_TYPE* constants)
  • offset : The offset in the cell data (defaults to 0)
  • length : The length of code to execute (defaults to reading until the end)
  • args : Spawn arguments including argv and inherited file descriptors

Return​

The process ID of the spawned process

spawn​

Spawn a new process from a specified source.

Syntax​

export function spawn(
  index: number,
  source: SourceType,
  offset: number,
  length: number,
  args: SpawnArgs
): number;

Parameters​

  • index : The index of the source to spawn from
  • source : The type of source (use SOURCE_* constants)
  • offset : The offset in the source data (defaults to 0)
  • length : The length of code to execute (defaults to reading until the end)
  • args : Spawn arguments including argv and inherited file descriptors

Return​

The process ID of the spawned process

pipe​

Create a new pipe

Syntax​

export function pipe(): [number, number];

Return​

A tuple of [read_fd, write_fd] for the pipe.

inheritedFds​

Get inherited file descriptors

Syntax​

export function inheritedFds(): number[];

Return​

Array of inherited file descriptor numbers.

read​

Read from a file descriptor

Syntax​

export function read(fd: number, length: number): ArrayBuffer;

Parameters​

  • fd : The file descriptor to read from
  • length : Number of bytes to read

Return​

The read data as ArrayBuffer.

Remarks​

The length of returned data might be smaller than length.

write​

Write data to a file descriptor

Syntax​

export function write(fd: number, data: ArrayBuffer): void;

Parameters​

  • fd : The file descriptor to write to
  • data : The data to write as ArrayBuffer

Remarks​

All data will be written atomically - no partial writes will occur

    • If the write cannot complete fully, it will throw an error
    • The function blocks until all data is written

close​

Close a file descriptor

Syntax​

export function close(fd: number): void;

Parameters​

  • fd : The file descriptor to close

wait​

Wait for a process to exit

Syntax​

export function wait(pid: number): number;

Parameters​

  • pid : The process ID to wait for

Return​

The exit status of the process

processId​

Get the current process ID

Syntax​

export function processId(): number;

Return​

The current process ID