JAM CLI Tool (jamt) Features

jamt.md

JAM CLI Tool (jamt) Features

The JAM CLI tool (jamt) is a command-line interface for interacting with the JAM blockchain. Here's a comprehensive overview of its features and commands.

Global Options

• --rpc <RPC>: Specify the RPC connection URL (default: ws://localhost:19800)
• --bootstrap-service-id <BOOTSTRAP_SERVICE_ID>: Set the Bootstrap service ID (default: 0)
• --provision <PROVISION>: Strategy for providing data to services (default: bootstrap)
  • Possible values: none, direct, bootstrap
• --force-core <FORCE_CORE>: Force operations on a particular core
• --queue: Queue work-items instead of immediate submission
• --help: Display help information
• --version: Display version information

Data Formats

Code Format

The <CODE> parameter is a binary blob that represents the service code. It should be provided as a file path containing the compiled service code. The code is identified by its hash in the blockchain.

The code hash is a 32-byte OpaqueHash that uniquely identifies the service code. The code itself is stored as a ByteSequence (variable-length byte array) in the blockchain.

Memo Format

The [MEMO] parameter is an optional string that can be provided with transfers or service creation. It can contain any UTF-8 encoded text and is used to provide additional context or information about the operation.

The memo is stored as a ByteSequence in the blockchain and is processed during the on_transfer phase of service execution. The gas cost for processing memos is determined by the service's min_memo_gas parameter.

Payload Format

The [PAYLOAD] parameter is a binary blob that represents the work-item payload. It should be provided as a hexadecimal string prefixed with "0x". The payload can contain any binary data that the service is designed to process.

The payload is part of a WorkItem structure that includes:

{
    "service": <ServiceId>,           // 32-bit unsigned integer
    "code_hash": "0x...",            // 32-byte hash
    "payload": "0x...",              // Variable-length byte sequence
    "refine_gas_limit": <Gas>,       // 64-bit unsigned integer
    "accumulate_gas_limit": <Gas>,   // 64-bit unsigned integer
    "import_segments": [             // Optional import specifications
        {
            "tree_root": "0x...",    // 32-byte hash
            "index": <U16>           // 16-bit unsigned integer
        }
    ],
    "extrinsic": [                   // Optional extrinsic specifications
        {
            "hash": "0x...",         // 32-byte hash
            "len": <U32>             // 32-bit unsigned integer
        }
    ],
    "export_count": <U16>           // 16-bit unsigned integer
}

Service Information

When inspecting a service, the returned information follows the ServiceInfo structure:

{
    "code_hash": "0x...",           // 32-byte hash of the service code
    "balance": <U64>,               // 64-bit unsigned integer
    "min_item_gas": <Gas>,          // 64-bit unsigned integer
    "min_memo_gas": <Gas>,          // 64-bit unsigned integer
    "bytes": <U64>,                 // 64-bit unsigned integer
    "items": <U32>                  // 32-bit unsigned integer
}

Preimage Format

When providing a preimage, the data follows the Preimage structure:

{
    "requester": <ServiceId>,       // 32-bit unsigned integer
    "blob": "0x..."                // Variable-length byte sequence
}

Commands

1. Create Service

Creates a new service on the blockchain.

jamt create-service [OPTIONS] <CODE> [AMOUNT] [MEMO]

Options:

• --min-item-gas <MIN_ITEM_GAS>: Minimum accumulation gas per work-item (default: 1000000)
• --min-memo-gas <MIN_MEMO_GAS>: Minimum on-transfer gas per memo (default: 1000000)

Arguments:

• CODE: The code to use for the service
• AMOUNT: Initial endowment for the service (default: 0)
• MEMO: Memo given to the service for the endowment (default: empty)

2. Item

Builds and submits a work package with a single work-item.

jamt item [OPTIONS] <SERVICE_ID> [PAYLOAD]

Options:

• --refine-gas <REFINE_GAS>: Gas for work-item refinement
• --accumulate-gas <ACCUMULATE_GAS>: Gas for work-item accumulation
• --exports <EXPORTS>: Expected number of exports (default: 0)

Arguments:

• SERVICE_ID: Target service for the work-item
• PAYLOAD: Work-item payload (default: empty)

3. Transfer

Makes a transfer from the Bootstrap service.

jamt transfer [OPTIONS] <SERVICE_ID> [AMOUNT] [MEMO]

Options:

• --gas <GAS>: Amount of gas to use for the transfer (defaults to minimum transfer amount of destination service)

Arguments:

• SERVICE_ID: Target service for the transfer
• AMOUNT: Amount to transfer (default: 0)
• MEMO: Memo to transfer (default: empty)

4. Inspect

Retrieves information about a block.

jamt inspect [ID] <COMMAND>

Arguments:

• ID: Block to query (default: best, possible values: best, final)

Subcommands:

• slot: Get the slot of the block
• service: Get information about a service
• storage: Get an item from a service's storage
• preimage: Get a preimage stored in a service's storage
• request: Get a preimage request in a service's storage

5. Provide

Submits a solicited preimage to the chain.

jamt provide <REQUESTER> <PREIMAGE>

Arguments:

• REQUESTER: The service that has requested the preimage
• PREIMAGE: The preimage blob (hexadecimal string prefixed with "0x")

6. Queue

Inspects the queue of pending work-items.

jamt queue

7. Pack

Submits all enqueued work-items.

jamt pack

8. VM Commands

A collection of commands for managing CoreVM services.

Subcommands:

• new: Create a new CoreVM service and load code
• upgrade: Update code (requires owner service transmission capability)

Usage Examples

1. Create a new service:

jamt create-service service.wasm 1000 "Initial endowment"

2. Submit a work-item:

jamt item 1 "0x0102030405"

3. Make a transfer:

jamt transfer 1 1000 "Transfer memo"

4. Provide a preimage:

jamt provide 1 "0x81095e6122e3bc9d961e00014a7fc833"

5. Create a new CoreVM service:

jamt vm new

Notes

• The tool connects to a local JAM node by default (ws://localhost:19800)
• Work-items can be queued for batch submission using the --queue flag
• Gas settings can be customized for both refinement and accumulation phases
• The Bootstrap service (ID: 0) is used by default for certain operations
• All binary data (code, payloads, preimages) should be provided as hexadecimal strings prefixed with "0x"
• Memos can contain any UTF-8 encoded text
• Service IDs are numeric identifiers (32-bit unsigned integers)
• Gas values are 64-bit unsigned integers
• Hash values are 32-byte arrays represented as hexadecimal strings
• Work items can include import segments and extrinsics for data availability
• The number of exports must be specified when submitting work items
• Service information includes balance, gas limits, and storage statistics