typeberry 🫐

Typeberry is a TypeScript implementation of JAM protocol by Fluffy Labs.

NOTE: Since we are taking part in the JAM Prize, we do not accept any external PRs unless the contributor waives any claims to the prize and copy rights for the submitted code. By creating the PR you accept this requirement.

Links

• Documentation
• Performance Charts

Implementation status

Gray Paper compliance can be controlled via GP_VERSION environment variable.

• [x] 0.7.1
• [x] 0.7.2

JAM Prize requirements

• [x] Milestone 1
  • [x] Block import
  • [x] W3F test vectors
  • [x] JAM Conformance Fuzzer
  • [x] Performance optimisations
• [ ] Milestone 2
  • [x] Networking (partial)
  • [x] Fast PVM (ananas)
• [ ] Milestone 3
  • [ ] PVM Recompiler
• [ ] Milestone 4
• [ ] Milestone 5

Requirements

$ node --version
v 22.9.0

We recommend NVM to install and manage different node versions.

Installing dependencies

$ npm ci

Running typeberry

$ npm start

Running fuzz-target

$ npm start -- fuzz-target

Running with Docker

Build and run typeberry using Docker:

# Build the Docker image
$ docker build -t typeberry .

# Run with default settings
$ docker run typeberry

# Run with custom arguments
$ docker run typeberry --config /app/configs/typeberry-dev.json --node-name my-node

# Run with environment variables (e.g., for logging)
$ docker run -e JAM_LOG=trace GP_VERSION=0.7.2 typeberry

# Run with volume mounts for persistent data
$ docker run -v $(pwd)/database:/app/database typeberry

The Docker container uses a minimal Alpine Linux image and forwards all arguments to npm start.

Running the JSON RPC

JSON-RPC does not require typeberry to be running, so we just need to point the binary to the correct database.

Note the DB needs to be already initialized.

$ npm start -w @typeberry/rpc 

Additional tooling

• @typeberry/convert - convert common JAM formats
• @typeberry/jam - main typeberry/jam node binary
• @typeberry/lib - typeberry-as-library. All utilities exposed as ESM, browser-compatible library.
• JAM search - search across all public JAM-related channels
• State Viewer - load & inspect state of test vectors
• PVM Debugger - load & inspect a PVM program
• Gray Paper Reader - view the Gray Paper
• Ananas - AssemblyScript PVM interpreter

Formatting & linting

$ npm run qa

Formatting & linting is done by biomejs). You can run separate tools using commands below. Note that all safe fixes will be applied automatically.

$ npm run format # format the code
$ npm run lint   # lint the code & organise imports

A shorthand to run all the checks and apply safe fixes all at once is:

$ npm run qa-fix

Running unit tests

$ npm run test

Running tests from a single package:

$ npm run test -w @typeberry/trie

Running benchmarks

This command will run all benchmarks from ./benchmarks/ folder

$ npm start -w @typeberry/benchmark

Since each benchmark file is also runnable, it's easy to run just one benchmark, e.g:

$ npm exec tsx ./benchmarks/math/mul_overflow.ts

Running JSON test vectors

To run JSON test cases coming from the official JAM test vectors repository you need to first check out the repository with test cases and then use test-runner to execute them.

$ git clone https://github.com/w3f/jamtestvectors.git
$ npm run w3f -w @typeberry/test-runner  --  jamtestvectors/**/*.json ../jamtestvectors/erasure_coding/vectors/*

Since there are multiple sources of test vectors (and their versions may differ), all relevant ones can be easily checked out from our test vectors repository.

Obviously it's also possible to run just single test case or part of the test cases by altering the glob pattern in the path.

Selecting PVM Backend

By default, test vectors are run with both PVM backends (built-in and Ananas). You can select a specific PVM backend using the --pvm option:

# Run tests with built-in PVM only
$ npm run w3f-davxy:0.7.1 -w @typeberry/test-runner -- --pvm builtin

# Run tests with Ananas PVM only
$ npm run w3f-davxy:0.7.1 -w @typeberry/test-runner -- --pvm ananas

# Run tests with both PVMs (default)
$ npm run w3f-davxy:0.7.1 -w @typeberry/test-runner

This option is useful for debugging PVM-specific issues or running faster tests by testing only one implementation at a time.

Running JSON RPC E2E tests

To run JSON RPC E2E test-vectors test-vectors repository needs to be checked out with ref matching our tests. Then to run tests:

$ npm run test:e2e -w @typeberry/rpc

Adding a new component / package

$ npm init -w ./packages/core/mycomponent
$ npm init -w ./packages/jam/mycomponent

This command will automatically update the workspaces field in top-level package.json.

Codestyle

A brief, but evolving description of our codestyle and guideliness is availabe in CODESTYLE.

Add Typeberry's remote notes to Gray Paper Reader

1. Open Gray Paper Reader and go to Notes > Settings (⚙️).
2. Click "+ New Source".
3. Set Source Name to Typeberry.
4. Paste the following in Source URL:

https://fluffylabs.dev/typeberry/links.json

5. Select All Versions.
6. Click OK.
7. Ensure the ✅ next to Typeberry is enabled.