diff --git a/doc/src/adr02-atomkraft-init.md b/doc/src/adr02-atomkraft-init.md index 6e72e87..c89008b 100644 --- a/doc/src/adr02-atomkraft-init.md +++ b/doc/src/adr02-atomkraft-init.md @@ -2,7 +2,7 @@ | authors | revision | revision date | | --------------- | -------: | ------------: | -| Ranadeep Biswas | 1 | July 13, 2022 | +| Ranadeep Biswas | 2 | July 18, 2022 | ## Status @@ -14,19 +14,135 @@ We are figuring out how a user will use Atomkraft - produce tests, interact with The idea is to provide an `atomkraft` cli, which initializes a [poetry](https://python-poetry.org) project with [pytest](https://docs.pytest.org) dependency and other necessary configurations. -## Decision +## Summary -To set up an `atomkraft` project, +- Set up a poetry project at the current directory. +- Perform lightweight smoke tests right out of the box. +- Configure chain parameters via CLI. -- `atomkraft init BINARY DIR` is executed which sets up a poetry project at `DIR`. -- After changing the directory to `DIR`, a user should be able to execute some kick-the-tire tests (included in Atomkraft) for standard Cosmos-SDK modules right out of the box. -- The chain parameters can be queried/modified using `atomkraft chain config CONFIGFILE KEYPATH [VALUE]` -- A testnet can be started via `atomkraft chain up [-d]`. -- A testnet can be shut down via `atomkraft chain down`. +### `atomkraft init BINARY [TEST]...` -## Summary +This command is used to initialize an Atomkraft project in the current directory. +It uses [copier](https://pypi.org/project/copier) to copy a template and dynamically update project variables. + +#### Arguments + +- `BINARY` is path to Cosmos-SDK chain binary. + - "gaiad" + - "/opt/cosmos-chains/junod" +- `[TEST]...` is a list of provided lightweight tests that can be included in the project. + - "authz" + - "cosmwasm" + - "feegrant" + +#### Template directory structure + +``` +. +├── atomkraft.toml +├── chain.toml +├── modelator.toml +├── models +├── reactors +│ ├─── authz.py +│ └─── cosmwasm.py +├── reports +├── tests +│ ├─── conftest.py +│ ├─── test_authz.py +│ └─── test_cosmwasm.py +└── traces +``` + +#### `atomkraft.toml` + +This file is used for any top-level project configuration. + +- The lightweight tests are marked in `atomkraft.toml` file. + +##### Sample + +``` +[chain] +binary = "gaia" + +[modelator.apalache] +jar = "/path/to/apalache/jar" + +[tests] +lightweight = ["authz", "cosmwasm"] +``` + +#### `chain.toml` + +The chain config values are stored in `chain.toml` file. + +##### Sample + +``` +name = "cosmoshub" +prefix = "cosmos" +denom = "uatom" +coin = 118 + +[app] +"api.enable" = True +"api.swagger" = True +"api.enabled-unsafe-cors" = True +"minimum-gas-prices" = "0.10uatom" +"rosetta.enable" = False + +[config] +"instrumentation.prometheus" = False +"p2p.addr_book_strict" = False +"p2p.allow_duplicate_ip" = True + +[genesis] +"app_state.gov.voting_params.voting_period" = "600s" +"app_state.mint.minter.inflation" = "0.300000000000000000" +``` + +#### `modelator.toml` + +Configs for Modelator. + +##### Sample + +``` +[[models]] +model = "path/to/module.tla" +config = "path/to/module.cfg" +constants = {"N": 3, "FOO": "bar" } +invariants = ["Inv1", "Inv2"] +samples = ["Ex1", "Ex2"] +md_monitor = "path/to/monitor.md" +html_monitor = "path/to/monitor.html" +``` + +### `atomkraft chain config FILE KEY [VALUE]` + +This command can be used to query or update chain parameters. + +#### Arguments + +- `KEY` is a nested key. + - `coin` + - `"app.api.enable"` + - `"config.p2p.allow_duplicate_ip"` + - `"genesis.app_state.gov.voting_params.voting_period"` + +Note, `app`, `config` and `genesis` prefixes. They correspond to the usual `app.toml`, `config.toml`, and `genesis.json` files in a Cosmos-SDK chain node data directory. + +- `VALUE` is used to overwrite the current value. If it is skipped, the current value is printed. + +### `atomkraft chain test-drive` + +After running `atomkraft init` (with included tests) and `atomkraft chain config`, the project should be ready to perform some lightweight tests. + +`atomkraft chain test-drive` will run the light-weight tests using `reactors/*py` and `tests/test_*py`. + +## Future work -- `atomkraft init` to initialize atomkraft project as a poetry project with python 3.10 and pytest dependency -- `atomkraft test-drive` to execute a set of standard Cosmos-SDK tests using provided chain binary. -- `atomkraft chain config CONFIGFILE KEYPATH [VALUE]` to update chain configuration. -- `atomkraft chain [up|down]` to control a testnet. +- Spawn independent testnet via `atomkraft chain [up|down]`. +- Spawn blockchain explorer via `atomkraft chain explorer [up|down] [PORT]`. +- Spawn testnet with an explorer via `atomkraft chain --explorer [up|down]`.