pystarport


Namepystarport JSON
Version 0.2.5 PyPI version JSON
download
home_pagehttps://github.com/crypto-com/pystarport
SummarySpawn local devnets for cosmos-sdk chains
upload_time2023-02-07 05:19:08
maintainer
docs_urlNone
authorchain-dev-team
requires_python>=3.8,<4.0
licenseApache
keywords cro blockchain crypto.com cosmos
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            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"
}
        
Elapsed time: 0.03672s