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.6.7
• [x] 0.7.0
• [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
Copy

We recommend NVM to install and manage different node versions.

Installing dependencies

$ npm ci
Copy

Running typeberry

$ npm start
Copy

Running fuzz-target

$ npm start -- fuzz-target
Copy

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
Copy

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 
Copy

Additional tooling

• @typeberry/convert - convert common JAM formats
• 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
Copy

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
Copy

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

$ npm run qa-fix
Copy

Running unit tests

$ npm run test
Copy

Running tests from a single package:

$ npm run test -w @typeberry/trie
Copy

Running benchmarks

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

$ npm start -w @typeberry/benchmark
Copy

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
Copy

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/*
Copy

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.

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
Copy

Adding a new component / package

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

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
Copy

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