Cannons

The cannon document is an optional where you can specify:

where to source transactions from (ahead-of-time generated file or generate in realtime)
what kinds of transactions to generate
where to send transactions (to a file, or a node in the topology)

The cannon document is not required for a environment to run, but the document needs to be present at apply time to work.

This document is required if you want to use a cannon timeline action.

You can have more than one cannon per environment.

Fields

The different top level fields you can specify in a cannon document and what they mean. You can skip to examples by clicking here.

The required fields are italicized.

name

The name of the cannon document.

This is so you can refer to this cannon in other documents.

description

The optional description for a cannon document.

source

Where the transactions should come from.

query

Sets the query service for the cannon to use.

Has two modes local ledger or a node in the environment. Optional defaults to the local ledger.

local

An optional field that if provided uses the node in the environment specified to sync from.

Defaults to None, i.e. agent uses it's own local ledger as is.

source:
  query:
    sync-from: client/1 # optional

node

An optional field that if provided uses the node in the environment specified pulls that node's state root over RPC.

source:
  query: client/1 # required

compute

Sets the compute service for the cannon to use.

Has two modes agent or demox. Optional defaults to the agent.

agent

This tells the cannon to use agents in the environment.

You can optionally provide a list of agent labels to specify which agents to use.

source:
  compute:
    labels: foo,bar

demox

This tells the cannon to use Demox's API to generate the executions.

Requires the url for the API.

source:
  compute:
    demox-api: https://exampleurl.com/api/v1

sink

Sinks specify where transactions should go, and optionally how many attempts should be made before timing out.

file-name

Specify a file to write transactions to. This will reside inside the environment's data directory under this name.

sink:
  file-name: txs.json

The format of the file is:

{tx_1_info...}
{tx_2_info...}

target

Specify the node target(s) the tx's should be fired at.

sink:
  target: client/1

broadcast-attempts, broadcast-timeout, authorize-attempts, authorize-timeout

Options for configuring when to drop broadcast/authorization attempts.

The broadcast-* options are not relevant if target is not configured.

The broadcast-timeout and authorize-timeout options (seconds) start immediately after an attempt. A broadcast will not be re-broadcast/dropped until the next block occurs.

The broadcast-attempts and authorize-attempts are limitless when absent. A setting of 0 means a failure will not result in another attempt. A setting of 2 means two attempts will be made before dropping.

sink:
  target: '*/*'
  broadcast-attempts: 3
  authorize-attempts: 3
  broadcast-timeout: 60 # 1 minute timeout on failure
  authorize-timeout: 60 # 1 minute timeout on failure

Examples

A few different examples of topology docs.

Record txs to a file

---
version: cannon.snarkos.testing.monadic.us/v1

name: realtime-txs-record-to-file

source:
  query: "*/*" # node targets
  labels: [local] # compute labels

sink:
  file-name: txs.json

Playback Fire Right Away

---
version: cannon.snarkos.testing.monadic.us/v1

name: txs-from-file-to-target-node

source:
  # playback mode
  file-name: txs.json

sink:
  # realtime mode
  target: validator/test-1
  # 2 minute timeouts
  broadcast-timeout: 120
  authorize-timeout: 120
  # additionally record to a file
  file-name: out.json

snops