JAM chain

A [jamchain] takes the place of the relaychain: a JAM network is rooted in its JAM nodes, and parachains can be anchored to it.

TOML

[jamchain]
id = "dev"
default_command = "polkajam"
protocol_params_type = "tiny"   # tiny (6 validators) | mini (78) | full (1023)

[[jamchain.nodes]]
name = "jam0"
mode = "validator"
# ... one entry per validator, plus any `ordinary` / `proxy` nodes

Builder

#![allow(unused)]
fn main() {
use zombienet_sdk::NetworkConfigBuilder;

let config = NetworkConfigBuilder::new()
    .with_jamchain(|j| {
        let mut j = j.with_id("dev").with_validator(|n| n.with_name("jam0"));
        for i in 1..6 {
            j = j.with_validator(|n| n.with_name(&format!("jam{i}")));
        }
        j.with_ordinary(|n| n.with_name("jam-or"))
    })
    .build()
    .unwrap();
}

Chain spec

By default zombienet builds the JIP-4 chain spec itself, with jam-chainspec. The default genesis has the network's validators, the bootstrap service as service 0 (hosting the null authorizer) and the null authorizer on every core.

The bootstrap service comes from [jamchain.genesis] bootstrap_service (a path or a url), or is embedded in zombienet with the jam feature (of zombienet-sdk, zombienet-orchestrator or the CLI), so no extra file is needed:

zombienet-sdk = { version = "...", features = ["jam"] }

The feature builds it from the jam-bootstrap-service crate when zombienet is compiled, which needs the rust-src component (rustup component add rust-src); it is off by default so other users don't need it. To embed a prebuilt blob instead, set ZOMBIE_JAM_BOOTSTRAP_SERVICE_BLOB to its path when building with the feature.

Without the feature and without bootstrap_service, building the spec fails and says so (unless with_defaults = false).

The built-in builder needs exactly as many validator nodes as the protocol parameters call for (6 for tiny, 78 for mini, 1023 for full).

How the spec is produced:

SetSpec
chain_spec_pathUsed as given (a path or a url).
nothing (default)Built in process, customized by [jamchain.genesis].

genesis can't be combined with chain_spec_path.

Migrating from 0.7

chain_spec_command and genesis_overrides were removed from [jamchain], and a network file that still sets them is refused. The node's gen-spec is no longer run.

Used chain_spec_command / genesis_overrides forNow
Services, auth queues, privileges[jamchain.genesis] (or its native config_file).
Fewer validators than the preset needsAdd validators, set genesis.protocol_parameters with a matching core_count, or use chain_spec_path.
A node on another jam-* versiongenesis.bootstrap_service pointing at that node's blob, or chain_spec_path.
JAM networks with different protocol parameters in one processSeparate processes, or chain_spec_path.

Customizing the genesis

[jamchain.genesis]
# Replace the embedded bootstrap service with another blob (a path or a url).
# bootstrap_service = "./blobs/jam-bootstrap-service.jam"
# Don't add the bootstrap service nor the null authorizer queues.
# with_defaults = false
# A native jam-chainspec JSON config, layered under the fields below. Its `id`,
# `genesis_validators` and `protocol_parameters` are replaced by zombienet's.
# config_file = "./my-chainspec-config.json"
# A full protocol parameters object, instead of the `protocol_params_type` preset.
# protocol_parameters = { ... }

[jamchain.genesis.services.5]
code = "./blobs/my-service.jam"          # a path or a url
balance = "min+1000000"                  # 1000 | "max" | "min" | "min+<amount>"
min_item_gas = 10
min_memo_gas = 10
deposit_offset = 0                       # an amount, or "max"
preimages = ["./blobs/my-authorizer.jam"]
storage = { "0x6772656574696e67" = "0x68656c6c6f" }

[jamchain.genesis.auth_queues]
0 = [{ code = "./blobs/my-authorizer.jam", config = "0x" }]   # hashed by zombienet
1 = ["null"]                                                   # or a 0x-prefixed hash

[jamchain.genesis.privileges]
manager = 0        # alias: bless
delegator = 0      # alias: designate
registrar = 0      # alias: register
assign = { 0 = 5 }
always_acc = { 5 = 1000000 }

Relative paths are resolved against the network definition's directory. Balances that don't fit a TOML integer (like u64::MAX) are written as strings, or as "max".

#![allow(unused)]
fn main() {
use zombienet_sdk::{jam::JamAuthorizer, NetworkConfigBuilder};

let config = NetworkConfigBuilder::new()
    .with_jamchain(|j| {
        j.with_id("dev")
            .with_genesis(|g| {
                g.with_service(5, |s| {
                    s.with_code("./blobs/my-service.jam")
                        .with_balance(zombienet_sdk::jam::JamBalance::MinimumPlus(1_000_000))
                        .with_preimage("./blobs/my-authorizer.jam")
                        .with_storage(b"greeting".to_vec(), b"hello".to_vec())
                })
                .with_auth_queue(0, [JamAuthorizer::code("./blobs/my-authorizer.jam")])
                .with_auth_queue(1, [JamAuthorizer::Null])
                .with_assigner([0], 5)
                // .with_bootstrap_service("https://example.com/jam-bootstrap-service.jam")
            })
            .with_validator(|n| n.with_name("jam0"))
            // ... 6 validators for tiny
    })
    .build()
    .unwrap();
}

The network's base directory gets jam_spec.json and, for a spec built in process, jam_genesis.json: the genesis that went into it, with the code hash of every service and where the bootstrap service came from.

The bootstrap service must suit the node: the embedded one is built from the jam-bootstrap-service version matching the jam-* crates zombienet uses. For a node on another version, point bootstrap_service at its blob, or give a pre-built spec with chain_spec_path.

The protocol parameters are process-wide, so all the JAM networks a process builds in process must use the same set (a network given a chain_spec_path is not affected).

The SDK also exports the embedded blobs for tests: zombienet_sdk::jam::NULL_AUTHORIZER_BLOB, null_authorizer_hash(), embedded_bootstrap_service() and, with the jam feature, BOOTSTRAP_SERVICE_BLOB, BOOTSTRAP_SERVICE_HASH and BOOTSTRAP_SERVICE_SOURCE.