diff --git a/doc/src/adr02-atomkraft-init.md b/doc/src/adr02-atomkraft-init.md index 6e72e87..3fdb584 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,91 @@ 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. + +A typical `atomkraft.toml` may look like this. + +``` +[chain] +binary = "gaia" + +[modelator.apalache] +jar = "/path/to/apalache/jar" + +[tests] +lightweight = ["authz", "cosmwasm"] +``` + +### `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. + +The config values are stored in `chain.toml` file. + +### `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]`.