Storage

The storage document is where you can specify:

The generation or downloading of a genesis block.
You can specify how many validators there are in the initial committee.
Can specify how much each validator has bonded.
Can add additional accounts with or without a balance.
Can specify how the ledger should be re-loaded.
How often checkpoints of the ledger should be made.

The storage document is required for a environment to run.

Fields

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

The required fields are italicized.

version

The version of the storage document.

id

The unique identifier of the storage document.

This allows you to re-use a storage among different environments.

description

The optional description for a storage document.

binaries

Allows you to specify multiple runner binaries for an environment.

You can specify a binary in a few ways, but it's always binary_name: field/sub-fields.

Longhand url:

binaries:
  default:
    source: url
    # case sensitive sha
    sha256: a95e329b13627165283e59c5435586d681fdbbe517f45e868178f9453cb55e72
    size: 124

Longhand path:

binaries:
  compute:
    source: /path/to/binary
    # for path based ones you can auto derive sha and size.
    sha256: auto
    size: auto

Shorthand url/path:

binaries:
  # For paths this will use auto.
  fix-bug-1285: path
  # For url's use at your own risk as sha will not be verified.
  fix-performance-1298: url

default

An optional specifically named binary information you can provide to be used as the default node runner binary.

If not provided defaults to the AOT_BIN environment variable.

compute

An optional specifically named binary information you can provide to be used as the default compute binary.

If not provided falls back to the default binary.

source

The url or path for a binary version to be served from.

sha256

The sha of the binary, verified when downloaded by the agent.

size

The size of the binary in bytes.

regen

An optional number used if you want to wipe the old storage.

The recommendation is to increment this number, delete the env, and then apply it again.

The default value is 0.

persist

Tells the agents whether or not they should re-download the storage data. If enabled will save storage to a local db instance.

false by default, which means this behavior is disabled.

retention-policy

An optional field where you can specify a comma separated values of:

How long you want checkpoints to be taken for.
How often you want checkpoints to be taken.

Some examples of rules:

4h:1h - for 4 hours, keep a checkpoint every hour
1W:U - for 1 week, keep every checkpoint
4W:1D - for 4 weeks, keep a checkpoint every day
6M:1W - for 6 months, keep a checkpoint every week
1Y:1M - for 1 year, keep a checkpoint every month
U:6M - for all time, keep a checkpoint every 6 months

For example, retention-policy: 4h:1h,1W:U.

Additionally you can do retention-policy: default. Which is equivalent to 4h:1h,1D:8h,1W:1D,4W:1W,4M:1M,U:1Y.

connect

An optional url from which to download a genesis block and create a storage from that.

generate

The generate field is more complex as you can provide more options if desired.

[NOTE] By default generate: {} is valid.

genesis

Another subset of options to pass to the genesis.block generation.

[WARNING] This option conflicts with the connect option.

bonded-balances:
  aleo1yspxekr97q4fu9kkxk88f4874pl96r9zxqwtp7rtn2xc5wqgqggspjljf8: 10000000000000
  aleo1pc5zapsghnp3r6qme0dhcvjslzgef89kggsvap8f7vxs3m38lqpsjn6v47: 10000000000000

Good if you already know their private keys.

or the size of the committee and their balance amount:

committee-size: 10 # must be 4 or greater
bonded-balance: 100000000 # must be 10 million or greater.

By default it is a committee_size: 4 and bonded_balance: 10_000_000.

accounts

An optional field that has no default. Allows you to specify more accounts to be made with a specific seed if desired. These can then be use in other documents.

accounts:
  example: 3
  foo:
    count: 3
    seed: 1
  bar:
    count: 6 # the first 3 of these will be the same as the first 3 of `foo`
    seed: 1

transactions

An optional field that has no default.

If specified creates AOT credits.aleo/public_tranfer transactions.

transactions:
  - file: bulk.json # the file to write the tx's to.
    total: 1000 # how many tx'r to write.
    amount: 5000 # the amount to transfer.
    sources: [committee.0] # the accounts to transfer from.
    destinations: [accounts.*] # the accounts to transfer to.

Examples

A few different examples of storage docs.

Default Generation

version: storage.snarkos.testing.monadic.us/v1

id: base

generate: {}

A Custom Generation

version: storage.snarkos.testing.monadic.us/v1

id: genesis-params-0

retention-policy: default
generate:
  genesis:
    seed: 1
    private-key: APrivateKey1zkp7QWqPSmrK4durW7Y6uwpbnubWtFGJeYoXtN4jaAPFJmv
    additional-accounts: 6
    additional-accounts-balance: 10000000000
    bonded-balances:
      # APrivateKey1zkp7QWqPSmrK4durW7Y6uwpbnubWtFGJeYoXtN4jaAPFJmv
      aleo1yspxekr97q4fu9kkxk88f4874pl96r9zxqwtp7rtn2xc5wqgqggspjljf8: 10000000000000
      # APrivateKey1zkpGnbnQcbFpt5uwFinvErShe28jWYdYXyeEywRosLbkSZP
      aleo1pc5zapsghnp3r6qme0dhcvjslzgef89kggsvap8f7vxs3m38lqpsjn6v47: 10000000000000
      # APrivateKey1zkpJeComnGsa2NoYo7eXXUkZveoxy6mxnAS36Timz46cNmq
      aleo1u8lu8a9vqrw0m3wxph5v8hqj3m9vrzwwmt3d3e483468r5gy8qpsvgwjdl: 10000000000000
      # APrivateKey1zkp3gbZsmjfn3P2AVndY3AU9wu5kVkT5NetY6ztxCdEUgbP
      aleo1yy7yx4kvqp4hmnexa2lyrg7fdptuazwuv35976gsuv073m9lg5zs6d8sek: 10000000000000

  # generate additional accounts, accessible via example.$, foo.0, or bar.1 in `key` fields in later documents
  accounts:
    example: 3
    foo:
      count: 3
      seed: 1
    bar:
      count: 6 # the first 3 of these will be the same as the first 3 of `foo`
      seed: 1
persist: false
regen: 1

External Genesis Block

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

id: canary-clients
name: canary-clients

connect: https://pub-d74d58a8616c4d54bc1a948b4d001970.r2.dev/block.genesis

generate:
  accounts:
    extra: 5

Multiple Binaries

To see how to use these in the topology click here.

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

id: example-binary

generate:
  genesis:
    seed: 1

# Can be later accessed in the nodes document by name.
binaries:
  default:
    sha256: auto
    size: auto

  compute: ./path/to/compute/file

  example_http:
    source: https://example.com/example_file
    sha256: a95e329b13627165283e59c5435586d681fdbbe517f45e868178f9453cb55e72
    size: 123 # auto is not available for url sources

  example_http_short: https://example.com/example_file

snops