Skip to main content

ckb-js-std Introduction

In the Quick Start section under Simple Print Args, we briefly introduced ckb-js-std. This section and the ones that follow will cover it in more detail.

ckb-js-std currently consists of two parts:

  • bindings
  • core

@ckb-js-std/bindings​

This library provides low-level bindings to the C implementation of ckb-js-vm. It serves as the foundation layer that enables JavaScript/TypeScript to interact with the underlying C code. Key characteristics:

  • Contains declarations for binding functions to C implementations
  • Has no TypeScript implementation of its own
  • Primarily used as a dependency for higher-level libraries

Errors thrown by bindings functions​

It is possible that bindings functions throw exceptions that can be handled gracefully. The CKB VM defines standard error codes that your code should be prepared to handle:

CKB_INDEX_OUT_OF_BOUND 1
CKB_ITEM_MISSING 2

Common scenarios where these errors occur:

  • CKB_INDEX_OUT_OF_BOUND (1): Occurs when iterating beyond available items, such as when looping over cells, scripts, witnesses, etc. This error is expected and should be caught to terminate iteration loops.
  • CKB_ITEM_MISSING (2): Occurs when a type script is missing. This can be a valid state in some on-chain scrips.

You can handle these exceptions by checking the errorCode property of the thrown exception. Here's an example of properly handling the out-of-bounds case in an iterator:

next(): IteratorResult<T> {
try {
    const item = this.queryFn(this.index, this.source);
    this.index += 1;
    return { value: item, done: false };
} catch (err: any) {
    if (err.errorCode === bindings.INDEX_OUT_OF_BOUND) {
    // End iteration gracefully when we've reached the end of available items
    return { value: undefined, done: true };
    }
    // Re-throw any other errors with additional context
    throw new Error(`QueryIter error: ${err.message || err}`);
}
}

CKB Syscalls​

This part provides low-level bindings that closely follow the VM Syscalls specification. Most functions here correspond directly to the syscalls defined in the RFC.

Common Algorithms​

This part includes frequently used cryptographic algorithms. Since implementing these algorithms directly in JavaScript would consume a large number of cycles, they are implemented natively within the JS-VM for better performance:

  • Sha256
  • Keccak256
  • Blake2b
  • Ripemd160
  • secp256k1
  • schnorr
  • Smt
  • hex
  • base64
  • parseExtJSON

Other Utilities​

  • mount
  • evalJsScript
  • loadJsScript
  • loadFile
  • debug
  • sprintf
  • printf
  • console

@ckb-js-std/core​

Built on top of bindings, this module provides higher-level, easier-to-use interfaces. It also includes common utility functions for writing contracts. It consists of the following parts:

  • High-Level CKB Syscalls: Further abstractions over the syscall bindings, such as contract iterators.
  • Molecule and Contract-Related Structures: Includes data structures like Script, CellInput, etc.
  • Common Types: Utilities like Bytes, Num.
  • Logging
  • Hasher: Higher-level wrappers around the hashing algorithms provided by bindings.