# Parity JAM SDK

The Parity JAM SDK is at a very early stage of development but is functional for developing JAM services and authorizers.

The current version, 0.1.21, consists of four main components:

- JAM Types & PVM Common
- JAM Bootstrap Service & Null Authorizer
- JAM PVM Builder (`jam-pvm-build`)
- JAM Client Tooling: `jamt` and `jamtop`

## JAM Types & PVM Common

This the basic API of the SDK, including traits, types, functions and macros needed for expressing Services and Authorizers, including their invocations, returns and host functions.

There are two crates: [`jam-types`](https://docs.rs/jam-types/latest/jam_types/) and [`jam-pvm-common`](https://docs.rs/jam-pvm-common/latest/jam_pvm_common/).

## JAM Bootstrap Service & Null Authorizer

These are two basic PVM modules useful for creating sensible JAM Genesis configurations. They can be found in crates.io under [`jam-null-authorizer`](https://crates.io/crates/jam-null-authorizer) and [`jam-bootstrap-service`](https://crates.io/crates/jam-bootstrap-service).

After installing [`rustup`](https://rustup.rs), Bootstrap service can be downloaded using `cargo clone`:

$ cargo install cargo-clone # NOTE only needed once
...
$ cargo clone jam-bootstrap-service

The code for null authorizer can be cloned in a similar manner.

## JAM PVM Builder

The [JAM PVM Builder](https://crates.io/crates/jam-pvm-builder) is CLI tool which allows PVM code blobs be built, either services or authorizers.

After installing [`rustup`](https://rustup.rs), it can be installed with:

$ rustup toolchain install nightly-2024-11-01 -c rust-src # NOTE only needed once
$ cargo install jam-pvm-build

Its usage can be seen in the usual way:

$ jam-pvm-build --help
CLI utility for building PVM code blobs, particularly services and authorizers.

Usage: jam-pvm-build [OPTIONS] [PATH]

Arguments:
  [PATH]
          Path of crate to build, defaults to current directory

Options:
  -o, --output <OUTPUT>
          Output path

  -m, --module <MODULE>
          Module type to build
          
          [default: automatic]

          Possible values:
          - automatic:  Automatically derive the module type from the crate name
          - service:    Service
          - authorizer: Authorizer

      --auto-install
          Install rustc dependencies if missing

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

For example, the `jam-null-authorizer` could be built using just:

$ cargo clone jam-null-authorizer
...
$ jam-pvm-build ./jam-null-authorizer

You could find the PVM binary `jam-bootstrap-service.pvm` in the current directory.

## JAM Client Tooling

All JAM Client Tooling currently assumes the abillity to connect to the JAM network through via a trusted node through its RPC. The RPC should be in line with [JIP-2](https://hackmd.io/@polkadot/jip2) for these tools to work.

The default RPC endpoint is assumed to be `ws://localhost:19800`. This can be redirected if desired through the `JAM_RPC` environment variable.

### `jamt`: The JAM Tool

This is a CLI utility for interacting with JAM networks. It assumes the existance of the JAM Bootstramp service as service 0. It provides the means to create new services, transfer funds to services and introduce work-items/packages onto JAM.

It can be installed with:

$ cargo install jamt
...
$ jamt --help
JAM CLI tool

Usage: jamt [OPTIONS] <COMMAND>

Commands:
  create-service  Create a new service
  item            Build and submit a work package with a single work-item
  transfer        Make a transfer from the Bootstrap service
  inspect         Get information concerning a block
  queue           Inspect the queue
  pack            Submit all enqueued work-items
  help            Print this message or the help of the given subcommand(s)

Options:
      --rpc <RPC>
          The URL for the RPC connection [env: JAM_RPC=] [default: ws://localhost:19800]
  -b, --bootstrap-service-id <BOOTSTRAP_SERVICE_ID>
          The service ID of the Bootstrap service [default: 0]
  -p, --no-auto-provide
          Do not automatically provide any data to the chain as required
  -c, --force-core <FORCE_CORE>
          Force the operation to happen on a particular core if relevant
  -q, --queue
          When creating a work-item, do not package and submit. Instead queue up the item for a later submission, potentially with other items
  -h, --help
          Print help
  -V, --version
          Print version

### `jamtop`

This is a CLI utility similar in nature to the classic Unix `top`, but instead of displaying a table of processes and real-time load information of the physical host machine, it displays a table of services and real-time load information for the JAM.

It can be installed with:

$ cargo install jamtop
...
$ jamtop --help
Table of processes for JAM

Usage: jamtop [OPTIONS]

Options:
      --rpc <RPC>  The URL for the RPC connection [env: JAM_RPC=] [default: ws://localhost:19800]
  -h, --help       Print help
  -V, --version    Print version