Getting Started with Peanut Butter AND JAM

This guide is based on the Peanut Butter AND JAM (PBJ) implementation of the JAM protocol. Read the Gray Paper for the authoritative specification.

Note: The PBJ source repository is currently private for the duration of the JAM contest. You do not need repo access to get started: use the Docker image or pre-built binaries from the links below. Source and build-from-source instructions will be available when the repo is public.

Running the Docker container

Use the PBJ fuzzer-target Docker image to run the node in a container without building from source.

Prerequisites

Docker installed and running (Install Docker)
A writable directory for the Unix socket (e.g. /tmp)

Pull and run

# Pull the image
docker pull shimonchick/pbnjam-fuzzer-target:latest

# Run with a test socket (mount /tmp so the socket can be shared)
docker run --rm -v /tmp:/tmp shimonchick/pbnjam-fuzzer-target:latest --socket /tmp/jam_test.sock --spec tiny

You should see the target listening on the socket. Press Ctrl+C to stop.

Custom socket path

SOCKET_PATH="/tmp/my_socket.sock"

docker run --rm \
  -v /tmp:/tmp \
  shimonchick/pbnjam-fuzzer-target:latest \
  bun run infra/node/fuzzer-target.ts --socket "$SOCKET_PATH" --spec tiny

Parameters

--socket <path>: Unix domain socket path for fuzzer communication
--spec tiny: Chain specification (tiny or full)
-v /tmp:/tmp: Mounts the host directory so the socket is shared; use a path that exists on your machine

Troubleshooting

Image not found: Run docker pull shimonchick/pbnjam-fuzzer-target:latest. (Building from source requires access to the PBJ repo, which is currently private.)
Socket permission errors: Run with your user: docker run --rm -v /tmp:/tmp --user $(id -u):$(id -g) shimonchick/pbnjam-fuzzer-target:latest ...

Download and run the binary

Pre-built fuzzer target binaries are published on GitHub Releases. Linux (x64) only for now.

Releases: https://github.com/Esscrypt/pbnj-fuzzer-releases/releases

Prerequisites

Linux (x64) (macOS/Windows binaries may be added later)
gunzip (standard on Linux)

Run the fuzzer target

Download fuzzer-target.gz from the latest release.
Decompress, make executable, and run:

gunzip -c fuzzer-target.gz > fuzzer-target && chmod +x fuzzer-target && ./fuzzer-target --socket /tmp/jam_target.sock --spec tiny

Use your own socket path and --spec tiny or --spec full as needed. The target will listen on the socket until you stop it (Ctrl+C).

Key Resources

When the PBJ repo is public, it will include test vectors for Safrole, PVM, erasure coding, and codec, plus build and run-from-source instructions. Until then, use Docker or the binaries above.

Bandersnatch VRF README

The Bandersnatch VRF package provides Verifiable Random Functions (VRFs) over the Bandersnatch curve: IETF VRF (RFC-9381-style), Pedersen VRF, and Ring VRF (including a WASM-backed variant), plus hash-to-curve and CLI tooling.

README: https://github.com/Esscrypt/bandersnatch-vrf

Bandersnatch VRF documentation

Repository & docs: https://github.com/Esscrypt/bandersnatch-vrf
npm: @pbnjam/bandersnatch-vrf

Getting Help

Gray Paper: https://graypaper.com/
Community Docs: https://docs.jamcha.in/

Remember

The Gray Paper is authoritative — When in doubt, consult the Gray Paper.
Test vectors are correct — Fix implementation, not tests.
Documentation is required — Always reference Gray Paper sections.
Performance matters — But not at the expense of correctness.