@typeberry/lib

Convenience package providing unified access to all Typeberry core packages.

Overview

@typeberry/lib is a meta-package that re-exports all Typeberry modules through subpath imports. This simplifies imports when working with multiple Typeberry packages and ensures version compatibility across the entire stack.

All imports use the pattern @typeberry/lib/<module> to access individual packages with full ESM and CommonJS support.

Usage

Installation

npm install @typeberry/lib

Importing

Instead of installing and importing individual packages:

// Without @typeberry/lib - requires installing each package separately
import { Blake2b } from "@typeberry/hash";
import { Encoder } from "@typeberry/codec";
import { ed25519 } from "@typeberry/crypto";

Import directly from @typeberry/lib using subpath imports:

// With @typeberry/lib - single package installation
import { Blake2b } from "@typeberry/lib/hash";
import { Encoder } from "@typeberry/lib/codec";
import { ed25519 } from "@typeberry/lib/crypto";

const blake2b = await Blake2b.createHasher();
const encoded = Encoder.encodeObject(schema, value);
const keypair = await ed25519.generateKeypair();

Available Modules

The following modules are available as subpath imports (e.g., @typeberry/lib/block):

block - Block structures and types
block-json - JSON serialization for blocks
bytes - Byte array utilities
codec - JAM/GP codec implementation
collections - Specialized data structures
config - Configuration types
config-node - Node configuration utilities
crypto - Cryptographic primitives (Ed25519, Sr25519, BLS)
database - Database abstractions
erasure-coding - Erasure coding implementation
fuzz-proto - Fuzzing protocol support
hash - Hashing functions (Blake2b, etc.)
importer - Typeberry importer utilities
jam-host-calls - JAM-specific host calls
json-parser - JSON parsing utilities
logger - Logging framework
mmr - Merkle Mountain Range implementation
numbers - Fixed-size numeric types
ordering - Ordering and comparison utilities
pvm-host-calls - PVM host call implementations
pvm-interface - PVM interface and program utilities
pvm-interpreter - PVM bytecode interpreter
shuffling - Shuffling algorithms
state - State management
state-json - JSON serialization for state
state-merkleization - State Merkleization
state-vectors - State test vectors
transition - State transition functions
trie - Trie data structures
utils - General utilities
workers-api - Workers API utilities

Examples

All examples below are extracted from actual test files in examples/ directory, ensuring they compile and work correctly.

Basic Import

import { Decoder } from "@typeberry/lib/codec";
import { InMemoryState } from "@typeberry/lib/state";
import { BytesBlob } from "@typeberry/lib/bytes";
import { Block, tryAsServiceId } from "@typeberry/lib/block";

// Import from @typeberry/lib using subpath imports
const config = await import("@typeberry/lib/config");

// create empty in-memory state representation
const state = InMemoryState.empty(config.tinyChainSpec);
assert.equal(state.entropy.length, 4);
assert.equal(state.getService(tryAsServiceId(0)), null);

// attempt to decode block from an empty blob
assert.throws(() => {
  Decoder.decodeObject(Block.Codec, BytesBlob.empty());
});

Working with Numbers

import { isU8, tryAsU32, tryAsU8 } from "@typeberry/lib/numbers";

// Create typed numbers
const smallNumber = tryAsU8(42);
const largeNumber = tryAsU32(1000000);

// Type checking
assert.ok(isU8(42));
assert.strictEqual(smallNumber, 42);
assert.strictEqual(largeNumber, 1000000);

Hashing with Blake2b

import { Blake2b } from "@typeberry/lib/hash";

// Create a Blake2b hasher
const hasher = await Blake2b.createHasher();

// Hash some data
const data = new Uint8Array([1, 2, 3, 4, 5]);
const hash = hasher.hashBytes(data);

// hash is a 32-byte Blake2b hash
assert.strictEqual(hash.length, 32);

Hashing a String

import { Blake2b } from "@typeberry/lib/hash";

const hasher = await Blake2b.createHasher();

// Hash a string directly
const hash = hasher.hashString("Hello, world!");

// Returns a 32-byte hash
assert.strictEqual(hash.length, 32);

Hashing Multiple Blobs

import { Blake2b } from "@typeberry/lib/hash";

const hasher = await Blake2b.createHasher();

// Hash multiple byte arrays together
const data1 = new Uint8Array([1, 2, 3]);
const data2 = new Uint8Array([4, 5, 6]);
const hash = hasher.hashBlobs([data1, data2]);

// Returns a single hash of all inputs
assert.strictEqual(hash.length, 32);

Bytes - Parsing Hex Strings

import { BytesBlob } from "@typeberry/lib/bytes";

// Parse hex string with 0x prefix
const hexString = "0x48656c6c6f";
const bytes = BytesBlob.parseBlob(hexString);

// Convert to regular Uint8Array
const data = bytes.raw;

// Verify the data
const text = new TextDecoder().decode(data);
assert.strictEqual(text, "Hello");

Bytes - Creating Bytes

import { Bytes } from "@typeberry/lib/bytes";

// Create fixed-size bytes
const data = Bytes.fill(32, 0x42);

assert.strictEqual(data.length, 32);
assert.strictEqual(data.raw[0], 0x42);

JAM/GP Codec - Basic Usage

import { Decoder, Encoder, codec } from "@typeberry/lib/codec";
import { Bytes } from "@typeberry/lib/bytes";

// Define a schema for fixed-size bytes
const hashSchema = codec.bytes(32);

// Create test data

const testHash = Bytes.fill(32, 0x42);

// Encode data
const encoded = Encoder.encodeObject(hashSchema, testHash);

// Decode data
const decoded = Decoder.decodeObject(hashSchema, encoded);

assert.deepStrictEqual(decoded, testHash);

PVM Interpreter - Basic Usage

import { Interpreter } from "@typeberry/lib/pvm-interpreter";
import { Status, tryAsGas } from "@typeberry/lib/pvm-interface";
import { BytesBlob } from "@typeberry/lib/bytes";

// Load a PVM program from hex
const programHex = "0x0000213308013309012803009577ff51070c648ac8980864a928f3648733083309013200499352d500";
const program = BytesBlob.parseBlob(programHex);

// Create interpreter and initialize with program
const pvm = new Interpreter();
pvm.resetGeneric(program.raw, 0, tryAsGas(1000));

// dump the program data
console.table(pvm.dumpProgram());

// Run the program
pvm.runProgram();

// Program executed successfully
assert.equal(pvm.getStatus(), Status.OOG);
assert.equal(pvm.getPC(), 12);

PVM Interpreter - Accessing Registers

import { Interpreter } from "@typeberry/lib/pvm-interpreter";
import { tryAsGas } from "@typeberry/lib/pvm-interface";
import { BytesBlob } from "@typeberry/lib/bytes";

const programHex = "0x0000210408010409010503000277ff07070c528a08980852a905f3528704080409111300499352d500";
const program = BytesBlob.parseBlob(programHex);

const pvm = new Interpreter();
pvm.resetGeneric(program.raw, 0, tryAsGas(1000));
pvm.runProgram();

// Access register values after execution
const reg0 = pvm.registers.getU64(0);

// Registers contain BigInt values
assert.strictEqual(typeof reg0, "bigint");

PVM Interpreter - Gas Tracking

import { Interpreter } from "@typeberry/lib/pvm-interpreter";
import { tryAsGas } from "@typeberry/lib/pvm-interface";
import { BytesBlob } from "@typeberry/lib/bytes";

const programHex = "0x0000210408010409010503000277ff07070c528a08980852a905f3528704080409111300499352d500";
const program = BytesBlob.parseBlob(programHex);

const initialGas = tryAsGas(1000);
const pvm = new Interpreter();
pvm.resetGeneric(program.raw, 0, initialGas);
pvm.runProgram();

// Check remaining gas after execution
const remainingGas = pvm.gas.get();

// Gas should have been consumed
assert.ok(remainingGas < initialGas);