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.