pystarport is like a [cosmos starport](https://github.com/tendermint/starport)
without the scaffolding feature. it's mainly used for development and testing. It's developed for the Crypto.org Chain, but
it can also be used for any cosmos-sdk based projects.
## Configuration
a typical configuration for a devnet is like this:
```
chainmaind:
cmd: chain-maind # chain binary to use, optional
validators: # genesis validators
- coins: 10cro
staked: 10cro
- coins: 10cro
staked: 10cro
accounts: # genesis accounts
- name: community
coins: 100cro
- name: ecosystem
coins: 200cro
- name: reserve
coins: 200cro
vesting_coins: 100cro # if not provided, the all of coins will be vested
vesting: "1d"
- name: launch
coins: 100cro
genesis: # patch genesis states
app_state:
staking:
params:
unbonding_time: "10s"
```
The `validators` section defines how many nodes to run, for each node, a home directory is initialized in
`data/node{i}`, and a validator account with specified coins is created.
The `accounts` defines other non-validator accounts, they are created in `node0`'s keyring.
In the `genesis` section you can override any genesis configuration with the same json path.
## Usage
```
NAME
pystarport serve - prepare and start a devnet from scatch
SYNOPSIS
pystarport serve <flags>
DESCRIPTION
prepare and start a devnet from scatch
FLAGS
--data=DATA
Type: str
Default: './data'
path to the root data directory
--config=CONFIG
Type: str
Default: './config.yaml'
path to the configuration file
--base_port=BASE_PORT
Type: int
Default: 26650
the base port to use, the service ports of different nodes are calculated based on this
--cmd=CMD
Type: str
Default: 'chain-maind'
the chain binary to use
```
## Port rules
The rules to calculate service ports based on base port is defined in the
[`ports.py`](https://github.com/crypto-org-chain/chain-main/blob/master/pystarport/pystarport/ports.py) module.
For example, with default base port `26650`, the url of api servers of the nodes would be:
- Node0: http://127.0.0.1:26654
- Node1: http://127.0.0.1:26664
> The swagger doc of node0 is http://127.0.0.1:26654/swagger/
>
> The default rpc port used by `chain-maind` is `26657`, that's the default node0's rpc port, so you can use
> `chain-maind` without change to access node0's rpc.
## Supervisor
`pystarport` embeded a [supervisor](http://supervisord.org/) to manage processes of multiple nodes, you can use
`pystarport supervisorctl` to manage the processes:
```
$ pystarport supervisorctl status
node0 RUNNING pid 35210, uptime 0:00:29
node1 RUNNING pid 35211, uptime 0:00:29
$ pystarport supervisorctl help
default commands (type help <topic>):
=====================================
add exit open reload restart start tail
avail fg pid remove shutdown status update
clear maintail quit reread signal stop version
```
Or enter an interactive shell:
```
$ pystarport supervisorctl
node0 RUNNING pid 35210, uptime 0:01:53
node1 RUNNING pid 35211, uptime 0:01:53
supervisor>
```
## Cli
After started the chain, you can use `chain-maind` cli directly, there are also some wrapper commands provided by
`pystarport cli`. It understands the directory structure and port rules, also assuming `keyring-backend=test`, and there
are shortcuts for commonly used commands, so arguments are shorter.
```
$ pystarport cli - --help
...
```
## Transaction Bot
A simple transaction bot that works for cluster created by pystarport as well as a local node
Copy and modify `bot.yaml.sample` to `bot.yaml` with your desired bot configurations.
### If you are running on a pystarport created cluster:
1. Make sure you have provide the `node` for each job in the `bot.yaml`
2. Run the command
```
$ pystarport bot --chain-id=[cluster_chain_id] - start
```
### If you are running on a local node
```
$ pstarport bot --node_rpc=tcp://127.0.0.1:26657 --data=/path/to/your/local/node/home/ - start
```
## docker-compose
When used with `docker-compose` or multiple machines, you need to config hostnames, and you probabely want to use a same
`base_port` since you don't have port conflicts, you can config the `validators` like this:
```yaml
validators:
- coins: 10cro
staked: 10cro
base_port: 26650
hostname: node0
- coins: 10cro
staked: 10cro
base_port: 26650
hostname: node1
```
`pystarport init --gen_compose_file` will also generate a `docker-compose.yml` file for you.
## IBC
It can setup multiple devnets at once, and connect them with ibc relayer.
```
ibc-0:
validators:
- coins: 10cro
staked: 10cro
base_port: 26650
- coins: 10cro
staked: 10cro
accounts:
- name: relayer
coins: 100cro
genesis:
app_state:
transfer:
params:
receive_enabled: true
send_enabled: true
ibc-1:
validators:
- coins: 10cro
staked: 10cro
base_port: 26750
- coins: 10cro
staked: 10cro
base_port: 26760
accounts:
- name: relayer
coins: 100cro
genesis:
app_state:
transfer:
params:
receive_enabled: true
send_enabled: true
relayer: # refer here (https://hermes.informal.systems/config.html) for more configs
global:
strategy: 'packets'
log_level: 'info'
chains:
- id: "ibc-0" # id is needed to match chain id
trusting_period: "20s"
- id: "ibc-1" # id is needed to match chain id
trusting_period: "20s"
```
With following commands to setup ibc, you are ready to play with ibc functionalities:
```
# spawn the devnets
pystarport serve --config ibc.yaml
# setup ibc channel
hermes -c data/relayer.toml create channel ibc-0 ibc-1 --port-a transfer --port-b transfer
# start relayer process
supervisorctl -c data/tasks.ini start relayer-demo
```
## Development
### Set up development environment
More about [poetry](https://python-poetry.org/docs/).
```
poetry install
```
### Recommended VS Code workspace settings
Remember to run `poetry env info` after `poetry install` and update this `python.defaultInterpreterPath`
```json
{
"python.formatting.provider": "black",
// after running `poetry env info`, change python.defaultInterpreterPath to Path under Virtualenv
"python.defaultInterpreterPath": "~/Library/Caches/pypoetry/virtualenvs/to_be_updated",
"editor.formatOnSave": true,
"python.linting.flake8Enabled": true,
"python.formatting.blackArgs": [
"--line-length=88"
],
"python.sortImports.args": [
"--profile",
"black"
],
"[python]": {
"editor.codeActionsOnSave": {
"source.organizeImports": true
}
}
}
```
## Test
### Install jsonnet
More about [jsonnet](https://jsonnet.org).
```
make test
```
## FAQ
### Have this error on Mac: `AF_UNIX path too long´
Set environment variable `TMPPATH=/tmp` to shorten the unix domain socket path.
Raw data
{
"_id": null,
"home_page": "https://github.com/crypto-com/pystarport",
"name": "pystarport",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "CRO,blockchain,crypto.com,cosmos",
"author": "chain-dev-team",
"author_email": "chain-dev@crypto.com",
"download_url": "",
"platform": null,
"description": "pystarport is like a [cosmos starport](https://github.com/tendermint/starport)\nwithout the scaffolding feature. it's mainly used for development and testing. It's developed for the Crypto.org Chain, but\nit can also be used for any cosmos-sdk based projects.\n\n## Configuration\n\na typical configuration for a devnet is like this:\n\n```\nchainmaind:\n cmd: chain-maind # chain binary to use, optional\n validators: # genesis validators\n - coins: 10cro\n staked: 10cro\n - coins: 10cro\n staked: 10cro\n accounts: # genesis accounts\n - name: community\n coins: 100cro\n - name: ecosystem\n coins: 200cro\n - name: reserve\n coins: 200cro\n vesting_coins: 100cro # if not provided, the all of coins will be vested\n vesting: \"1d\"\n - name: launch\n coins: 100cro\n genesis: # patch genesis states\n app_state:\n staking:\n params:\n unbonding_time: \"10s\"\n```\n\nThe `validators` section defines how many nodes to run, for each node, a home directory is initialized in\n`data/node{i}`, and a validator account with specified coins is created.\n\nThe `accounts` defines other non-validator accounts, they are created in `node0`'s keyring.\n\nIn the `genesis` section you can override any genesis configuration with the same json path.\n\n## Usage\n\n```\nNAME\n pystarport serve - prepare and start a devnet from scatch\n\nSYNOPSIS\n pystarport serve <flags>\n\nDESCRIPTION\n prepare and start a devnet from scatch\n\nFLAGS\n --data=DATA\n Type: str\n Default: './data'\n path to the root data directory\n --config=CONFIG\n Type: str\n Default: './config.yaml'\n path to the configuration file\n --base_port=BASE_PORT\n Type: int\n Default: 26650\n the base port to use, the service ports of different nodes are calculated based on this\n --cmd=CMD\n Type: str\n Default: 'chain-maind'\n the chain binary to use\n```\n\n## Port rules\n\nThe rules to calculate service ports based on base port is defined in the\n[`ports.py`](https://github.com/crypto-org-chain/chain-main/blob/master/pystarport/pystarport/ports.py) module.\n\nFor example, with default base port `26650`, the url of api servers of the nodes would be:\n\n- Node0: http://127.0.0.1:26654\n- Node1: http://127.0.0.1:26664\n\n> The swagger doc of node0 is http://127.0.0.1:26654/swagger/\n>\n> The default rpc port used by `chain-maind` is `26657`, that's the default node0's rpc port, so you can use\n> `chain-maind` without change to access node0's rpc.\n\n## Supervisor\n\n`pystarport` embeded a [supervisor](http://supervisord.org/) to manage processes of multiple nodes, you can use\n`pystarport supervisorctl` to manage the processes:\n\n```\n$ pystarport supervisorctl status\nnode0 RUNNING pid 35210, uptime 0:00:29\nnode1 RUNNING pid 35211, uptime 0:00:29\n$ pystarport supervisorctl help\n\ndefault commands (type help <topic>):\n=====================================\nadd exit open reload restart start tail\navail fg pid remove shutdown status update\nclear maintail quit reread signal stop version\n```\n\nOr enter an interactive shell:\n\n```\n$ pystarport supervisorctl\nnode0 RUNNING pid 35210, uptime 0:01:53\nnode1 RUNNING pid 35211, uptime 0:01:53\nsupervisor>\n```\n\n## Cli\n\nAfter started the chain, you can use `chain-maind` cli directly, there are also some wrapper commands provided by\n`pystarport cli`. It understands the directory structure and port rules, also assuming `keyring-backend=test`, and there\nare shortcuts for commonly used commands, so arguments are shorter.\n\n```\n$ pystarport cli - --help\n...\n```\n\n## Transaction Bot\n\nA simple transaction bot that works for cluster created by pystarport as well as a local node\n\nCopy and modify `bot.yaml.sample` to `bot.yaml` with your desired bot configurations.\n\n### If you are running on a pystarport created cluster:\n1. Make sure you have provide the `node` for each job in the `bot.yaml`\n2. Run the command\n```\n$ pystarport bot --chain-id=[cluster_chain_id] - start\n```\n\n### If you are running on a local node\n```\n$ pstarport bot --node_rpc=tcp://127.0.0.1:26657 --data=/path/to/your/local/node/home/ - start\n```\n\n## docker-compose\n\nWhen used with `docker-compose` or multiple machines, you need to config hostnames, and you probabely want to use a same\n`base_port` since you don't have port conflicts, you can config the `validators` like this:\n\n```yaml\nvalidators:\n - coins: 10cro\n staked: 10cro\n base_port: 26650\n hostname: node0\n - coins: 10cro\n staked: 10cro\n base_port: 26650\n hostname: node1\n```\n\n`pystarport init --gen_compose_file` will also generate a `docker-compose.yml` file for you.\n\n## IBC\n\nIt can setup multiple devnets at once, and connect them with ibc relayer.\n\n```\nibc-0:\n validators:\n - coins: 10cro\n staked: 10cro\n base_port: 26650\n - coins: 10cro\n staked: 10cro\n accounts:\n - name: relayer\n coins: 100cro\n genesis:\n app_state:\n transfer:\n params:\n receive_enabled: true\n send_enabled: true\nibc-1:\n validators:\n - coins: 10cro\n staked: 10cro\n base_port: 26750\n - coins: 10cro\n staked: 10cro\n base_port: 26760\n accounts:\n - name: relayer\n coins: 100cro\n genesis:\n app_state:\n transfer:\n params:\n receive_enabled: true\n send_enabled: true\nrelayer: # refer here (https://hermes.informal.systems/config.html) for more configs\n global:\n strategy: 'packets'\n log_level: 'info'\n chains:\n - id: \"ibc-0\" # id is needed to match chain id\n trusting_period: \"20s\"\n - id: \"ibc-1\" # id is needed to match chain id\n trusting_period: \"20s\"\n\n```\n\nWith following commands to setup ibc, you are ready to play with ibc functionalities:\n\n```\n# spawn the devnets\npystarport serve --config ibc.yaml\n# setup ibc channel\nhermes -c data/relayer.toml create channel ibc-0 ibc-1 --port-a transfer --port-b transfer\n# start relayer process\nsupervisorctl -c data/tasks.ini start relayer-demo\n```\n\n## Development\n### Set up development environment\nMore about [poetry](https://python-poetry.org/docs/).\n```\npoetry install\n```\n### Recommended VS Code workspace settings\nRemember to run `poetry env info` after `poetry install` and update this `python.defaultInterpreterPath`\n```json\n{\n \"python.formatting.provider\": \"black\",\n // after running `poetry env info`, change python.defaultInterpreterPath to Path under Virtualenv\n \"python.defaultInterpreterPath\": \"~/Library/Caches/pypoetry/virtualenvs/to_be_updated\",\n \"editor.formatOnSave\": true,\n \"python.linting.flake8Enabled\": true,\n \"python.formatting.blackArgs\": [\n \"--line-length=88\"\n ],\n \"python.sortImports.args\": [\n \"--profile\",\n \"black\"\n ],\n \"[python]\": {\n \"editor.codeActionsOnSave\": {\n \"source.organizeImports\": true\n }\n }\n}\n```\n\n## Test\n### Install jsonnet\nMore about [jsonnet](https://jsonnet.org).\n```\nmake test\n```\n\n\n## FAQ\n\n### Have this error on Mac: `AF_UNIX path too long\u00b4\n\nSet environment variable `TMPPATH=/tmp`\u00a0to shorten the unix domain socket path.\n\n",
"bugtrack_url": null,
"license": "Apache",
"summary": "Spawn local devnets for cosmos-sdk chains",
"version": "0.2.5",
"split_keywords": [
"cro",
"blockchain",
"crypto.com",
"cosmos"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f48464328b0b906e5a204a85078304a970af72061a13bc7820733b5872718787",
"md5": "a2bd8e4a4b4a34ab843eb93391eace13",
"sha256": "aaaa8f533b9c408218feffb47b2527828a1a9d32394dab8471dc330af1702974"
},
"downloads": -1,
"filename": "pystarport-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a2bd8e4a4b4a34ab843eb93391eace13",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 35745,
"upload_time": "2023-02-07T05:19:08",
"upload_time_iso_8601": "2023-02-07T05:19:08.566234Z",
"url": "https://files.pythonhosted.org/packages/f4/84/64328b0b906e5a204a85078304a970af72061a13bc7820733b5872718787/pystarport-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-07 05:19:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "crypto-com",
"github_project": "pystarport",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pystarport"
}
JSON
