# 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