---
# System prepended metadata

title: JAM Quickstart

---

# JAM Quickstart

## Real Quick Start

Spawn a 6-validator JAM test network running locally

1. **Build the node binary**:
   ```bash
   cargo build -p polkajam
   ```

2. **Start the telemetry sink**:
   ```bash
   cargo run -p jam-telemetry-dumper
   ```

3. **Spawn the test network** (in another terminal):
   ```bash
   cargo run -p polkajam-testnet -- --telemetry localhost:19900
   ```

## Resources

- **Node RPC server**:
  - [Specification](https://github.com/polkadot-fellows/JIPs/blob/main/JIP-2.md)
  - [Implementation](https://github.com/paritytech/polkajam/blob/main/crates/jam-std-common/src/rpc.rs)

- **Telemetry**:
  - [Specification](https://github.com/polkadot-fellows/JIPs/blob/main/JIP-3.md)
  - [Implementation](https://github.com/paritytech/polkajam/blob/main/crates/jam-std-common/src/telemetry.rs)

- **JAM Types**:
  - [Rust](https://github.com/paritytech/polkajam/blob/main/crates/jam-types/src/types.rs)
  - [Python](https://github.com/davxy/jam-types-py): a bit rough, feel free to contribute
  - [ASN.1 grammar](https://github.com/davxy/jam-test-vectors/blob/master/lib/jam-types.asn): easy reference, no encoding details


## Running Binaries

For brevity, commands in this guide are shown without the `cargo run -p <crate> --` prefix.

When you see a command like:
```bash
foo <options>
```

You should execute it as:
```bash
cargo run -p foo -- <options>
```

**Note**: The `--` separator is important, it separates cargo arguments from the binary's arguments.

---

## Spawn Test Network and Interaction

### Build Polkajam Node Binary

**Crate**: `polkajam`

Build the JAM node binary (required before spawning the network):

```bash
cargo build -p polkajam
```

### Spawn Tiny Test Network

**Crate**: `polkajam-testnet`

Launch a local test network with these characteristics:

- **6 validator nodes**
- **Telemetry enabled**: Each node reports to the specified telemetry server
- **Pre-built binary required**: Ensure you've built the `polkajam` binary first

Start the network:

```bash
polkajam-testnet --telemetry localhost:19900
```

### Services Compiler

**Crate**: `jam-pvm-build`

Compiles PVM programs into JAM services that can be deployed to the network.

```bash
jam-pvm-build --help
```

The compiler requires certain `rustc` dependencies. If they're not installed, the first run will fail.
To automatically install all required dependencies:

```bash
jam-pvm-build --auto-install
```

Build a service from source:

```bash
jam-pvm-build services/stress-service
```

This generates `jam-stress-service.jam` in the current directory, which can then be uploaded to the network using `jamt`.

---

## Network Tools

### Jam-Top: Network Monitor

**Crate**: `jamtop`

A `top`-like CLI tool for real-time network monitoring. Unlike the telemetry dumper, this actively queries the network using the built-in node RPC server (JIP-2) and displays:

- **Core activity**: Work being processed on each core
- **Services**: Identifiers and details of deployed services

Once your network is running, start the monitor:

```bash
jamtop
```

### Jam-Tool: Network Interaction

**Crate**: `jamt`

A CLI tool for interacting with the JAM network. Primary capabilities include:

- **Submit work packages** to the network
- **Upload new services** via the `bootstrap` service
- **Trigger service actions** with custom payloads

For more details on `bootstrap` service messages, see the [source code](https://github.com/paritytech/polkajam/blob/main/services/bootstrap-service/src/lib.rs).

**Example**: Spawn Service via `bootstrap` service (payload [ref](https://github.com/paritytech/polkajam/blob/451f0bcc93a6b5e7b570fe897ee2804a5fe9ce07/services/bootstrap-service/src/lib.rs#L92)):

```bash
jamt create-service jam-stress-service.jam
```

If you know the payload format that a service expects, you can use `jamt` to interact with any service by providing the encoded payload as a hex string.

**Example**: Assuming there is a service running with id `ff871391` (service IDs can be seen via `jamtop`) that expects a **refine** input message encoded as `0x010203`, you can trigger the service refinement:

```bash
jamt ff871391 010203
```

Payload interpretation is completely up to the service—the data is opaque to JAM itself. Each service can use its own custom codec and messaging format.

For example, the `bootstrap` service interprets the payload as an array of [`Instruction` messages](https://github.com/paritytech/polkajam/blob/451f0bcc93a6b5e7b570fe897ee2804a5fe9ce07/services/bootstrap-service/src/lib.rs#L34) encoded with jam-codec. However, this is completely up to each service's implementation (for instance, a *parachains service* could use SCALE encoding to maintain backwards compatibility).

As you can see from the `bootstrap` service code, the message is processed in the `refine` procedure and the refine output payload is re-encoded as a vector of `Instructions` for the `accumulate` procedure.

As an example, if the service instance is `jam-stress-service`, the payload is simply data used as input for hashing. It can be any arbitrary sequence of bytes and is not decoded into anything meaningful ([ref](https://github.com/paritytech/polkajam/blob/451f0bcc93a6b5e7b570fe897ee2804a5fe9ce07/services/stress-service/src/lib.rs#L27)).

### Telemetry Dumper: Simple Telemetry Sink

**Crate**: `jam-telemetry-dumper`

A basic telemetry sink that listens for and displays network events.

```bash
jam-telemetry-dumper --help
```

**Default configuration**:
- **Interface**: Listens on all interfaces
- **Port**: `19900`

#### Telemetry Events

While interacting with the network (e.g., via the `jamt` tool), you can observe telemetry messages for events like:
- `WorkPackageSubmission`
- `WorkPackageBeingShared`
- `WorkPackageReceived`
- `Refined`
- `WorkReportBuilt`

Events are linked together to form chains of related actions. Each follow-up message includes an event ID referencing the message that triggered it:

For example:
- **`WorkPackageSubmission`**: Builder submits a work package (generates an event ID)
- **`WorkPackageReceived`**: Package received; includes a `submission_or_share_id` field linking back to the `WorkPackageSubmission` event
- This continues for subsequent events in the processing pipeline

This enables you to trace the full lifecycle of work packages through the network (ref JIP-3).


---

## Fuzzing

### Relevant Resources

- [jam-test-vectors](https://github.com/davxy/jam-test-vectors)
- [jam-conformance](https://github.com/davxy/jam-conformance)
- [Conformance Matrix room](https://matrix.to/#/#jam-conformance:matrix.org)

### Running the Fuzzer

TODO

