diff --git a/README.md b/README.md index bd229b4..a6c8dab 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,39 @@ + # Feather Core **Feather Core** is a template blockchain built using Cosmos SDK and CometBFT and created with the Feather CLI. It is meant to be used together with **Feather 🪶**. +- [Features](#features) +- [Installing](#installing) +- [Developing](#developing) +- [Configuring](#configuring) + - [For Development](#for-development) + - [For Production](#for-production) +- [Publishing](#publishing) +- [Approving Join Requests](#approving-join-requests) +- [Interfaces](#interfaces) + ## Features -* All default Cosmos SDK modules -* The Cosmos [IBC](https://ibc.cosmos.network/) module -* The Osmosis [Token Factory](https://github.com/CosmWasm/token-factory) module -* The Terra [Alliance](https://alliance.terra.money/) module +- All default Cosmos SDK modules +- The Cosmos [IBC](https://ibc.cosmos.network/) module +- The Osmosis [Token Factory](https://github.com/CosmWasm/token-factory) module +- The Terra [Alliance](https://alliance.terra.money/) module -## Installation +## Installing Install dependencies: -* `go` -* `jq` -* `make` -* `gcc` +- `go` +- `jq` +- `make` +- `gcc` +- `feather` Build and install the chain binary: ```bash -# Run this in the repo root, where README.md lives. +# Run this in the repo root, where this `README.md` lives. feather dev build ``` @@ -44,56 +56,55 @@ feather dev sandbox init feather-cored start ``` -## Configuration +## Configuring ### For Development Configure the `config/localnet/config.json` file if you want to test run your chain before deploying to production with Feather. -```yaml +```js { - # Should uniquely identify your blockchain network. - # Naming convention: `[-a-zA-Z0-9]{3,47}` - "chain_id": "test-chain", - # List of genesis accounts, with their bank balances at genesis. - "accounts": [ + // Naming convention: `[-a-zA-Z0-9]{3,47}`. + "chain_id": "localnet-1", + // List of genesis accounts, with their bank balances at genesis. + "accounts": [ + { + "name": "alice", + "coins": [ { - "name": "alice", - "coins": [ - { - "denom": "token", - "amount": "20000" - }, - { - "denom": "stake", - "amount": "200000000" - } - ] + "denom": "token", + "amount": "20000" }, { - "name": "bob", - "coins": [ - { - "denom": "token", - "amount": "10000" - }, - { - "denom": "stake", - "amount": "100000000" - } - ] + "denom": "stake", + "amount": "200000000" } - ], - # List of genesis validators, with their staked coins at genesis. - "validators": [ + ] + }, + { + "name": "bob", + "coins": [ + { + "denom": "token", + "amount": "10000" + }, { - "name": "alice", - "bonded": { - "denom": "stake", - "amount": "100000000" - } + "denom": "stake", + "amount": "100000000" } - ] + ] + } + ], + // List of genesis validators, with their staked coins at genesis. + "validators": [ + { + "name": "alice", + "bonded": { + "denom": "stake", + "amount": "100000000" + } + } + ] } ``` @@ -101,57 +112,86 @@ Configure the `config/localnet/config.json` file if you want to test run your ch Configure the `config/mainnet/config.json` if you would like to do any of the following: -1. Change the default bond denom of the chain. -2. Change the name of the chain and chain binary. -3. Change the address prefixes of user accounts, validator accounts or consensus accounts. -4. Change parameters from the `x/staking` module when the chain is deployed by Feather. -5. Configure the LCD/RPC/Prometheus endpoints when the chain is deployed by Feather. +1. Change the default bond denom of the chain +2. Change the name of the chain and chain binary +3. Change the genesis account balances +4. Change the address prefixes of user accounts, validator accounts or consensus accounts +5. Change parameters from the `x/staking` module when the chain is deployed by Feather +6. Configure the LCD/RPC/Prometheus endpoints when the chain is deployed by Feather -```yaml +```js { - # Actual chain id when chain is deployed by Feather. - "chain_id": "feather-1", - # Name of the chain and chain binary (suffixed with 'd'). - "app_name": "feather-core", - # Metadata registered in the cosmos sdk package. - "app_binary_name": "feather-cored", - # Address prefixes - "account_address_prefix": "pfeath", - "account_pubkey_prefix": "pfeathpub", - "validator_address_prefix": "pfeathvaloper", - "validator_pubkey_prefix": "pfeathvaloperpub", - "consensus_node_address_prefix": "pfeathvalcons", - "consensus_node_pubkey_prefix": "pfeathvalconspub", - # Staking bond denominator (i.e. coin currency used for staking) - "bond_denom": "stake", - # Amount of bond denom for staking available at genesis. - # This is split among approved genesis validators by Feather. - "bond_supply": "1000000000", - # Cooldown time after unbonding from a validator before an account can stake again. - "unbonding_time": "1814400s", - # Max number of validators the chain supports. - "max_validators": 130, - "max_entries": 7, - "min_commission_rate": "0", - # Whether to start the LCD server with the chain. - "lcd_enabled": true, - # Exposes a swagger page documenting exposed API endpoints at IP:. - "lcd_swagger_enabled": true, - # Configurable LCD server port. - "lcd_port": 1317, - # Enable this if querying the blockchain from a CORS-enabled app, like web browsers. - "lcd_enable_unsafe_cors": false, - # Whether to start the RPC server with the chain. - "rpc_enabled": true, - # Configurable RPC server port. - "rpc_port": 26657, - # Whether to enable Prometheus metrics. - "prometheus_enabled": true, - # Configurable Prometheus port. - "prometheus_port": 26660 + // Actual chain ID when chain is deployed by Feather. + // Must uniquely identify your blockchain network. + // Naming convention: `[-a-zA-Z0-9]{3,47}`. + "chain_id": "feather-1", + // Human readable name of the chain. + "app_name": "feather-core", + // Metadata registered in the cosmos sdk package (typically `app_name` suffixed with "d"). + "app_binary_name": "feather-cored", + // Address prefixes for user, validator, and consensus accounts. + "account_address_prefix": "pfeath", + "account_pubkey_prefix": "pfeathpub", + "validator_address_prefix": "pfeathvaloper", + "validator_pubkey_prefix": "pfeathvaloperpub", + "consensus_node_address_prefix": "pfeathvalcons", + "consensus_node_pubkey_prefix": "pfeathvalconspub", + // Staking bond denominator (i.e. coin denom used for staking). + "bond_denom": "stake", + // Amount of `bond_denom` used for staking at genesis. + // This is split amongst approved genesis validators by Feather. + "bond_supply": "1000000000", + // Cooldown time after unbonding from a validator before an account can stake again. + "unbonding_time": "1814400s", + // Max number of validators the chain supports. + "max_validators": 130, + "max_entries": 7, + // Minimum commission rate for validators. + "min_commission_rate": "0", + // List of genesis accounts, with their bank balances at genesis. + // Unlike the `accounts` in `config/localnet/config.json`, the `name` field is replaced with the actual `address`. + "accounts": [ + { + "address": "pfeath1...aaa", + "coins": [ + { + "denom": "stake", + "amount": "4000000000" + }, + { + "denom": "token", + "amount": "3000000000" + } + ] + } + ], + // Whether to start the LCD server with the chain. + "lcd_enabled": true, + // Exposes a swagger page documenting exposed API endpoints at IP:. + "lcd_swagger_enabled": true, + // Configurable LCD server port. + "lcd_port": 1317, + // Enable this if querying the blockchain from a CORS-enabled app, like web browsers. + "lcd_enable_unsafe_cors": false, + // Whether to start the RPC server with the chain. + "rpc_enabled": true, + // Configurable RPC server port. + "rpc_port": 26657, + // Whether to enable Prometheus metrics. + "prometheus_enabled": true, + // Configurable Prometheus port. + "prometheus_port": 26660 } ``` +The total supply of a coin during chain genesis is the sum of the following: + +1. The `bond_supply` field +2. The sum of the `amount` fields of the `accounts` array +3. If the coin is the `bond_denom`, the number of validators multiplied by `1000000` (the minimum amount of `bond_denom` required for a validator's self-delegation) + +In the example `config.json` above, assuming we have exactly 5 validators, the total supply of `stake` is `5005000000` and the total supply of `token` is `3000000000` at chain genesis. + ## Publishing You must publish your chain with Feather for other Feather users to discover and deploy validators for your chain. @@ -181,9 +221,9 @@ export LAUNCH_ID="" feather prod chains show $LAUNCH_ID ``` -## Approving join requests +## Approving Join Requests -Feather validators may submit a [gentx](https://docs.cosmos.network/v0.46/run-node/run-node.html) request to join your chain as a validator. Feather will only include approved validators in the final deployed chain. +Feather validators may submit a [gentx](https://docs.cosmos.network/v0.46/run-node/run-node.html) request to join your chain as a validator. As a chain deployer, you will need to choose which validators to approve for your chain and run the following commands: ```bash export LAUNCH_ID='' @@ -197,12 +237,13 @@ export REQUEST_ID='' feather prod requests approve --key $KEY --launch-id $LAUNCH_ID --request-id $REQUEST_ID ``` -## Interface +## Interfaces Feather Core **must** adhere to this interface to work correctly with Feather. **Feather will not launch your chain if it fails the interface verification.** -* Do not change the root `Makefile`. Use a non-standard makefile name with the `-f` or `--file` option if you need one for your own needs. -* Do not change the location of the `main` package (must be in `cmd/`) -* Do not change the **location** of the `simulation_test.go` file. (must be `app/simulation_test.go`) -* Do not change the **contents** of the `simulation_test.go` file. -* Do not change the location of the files under the root `config` directory. +- Do not change the root `Makefile` + - Use a non-standard makefile name with the `-f` or `--file` option if you need one for your own needs +- Do not change the location of the `main` package (must be in `cmd/`) +- Do not change the **location** of the `simulation_test.go` file (must be `app/simulation_test.go`) +- Do not change the **contents** of the `simulation_test.go` file +- Do not change the location of the files in the root `config` directory diff --git a/config/localnet/config.json b/config/localnet/config.json index 7a220bd..89acbff 100644 --- a/config/localnet/config.json +++ b/config/localnet/config.json @@ -1,40 +1,40 @@ { - "chain_id": "test-chain", - "accounts": [ + "chain_id": "localnet-1", + "accounts": [ + { + "name": "alice", + "coins": [ { - "name": "alice", - "coins": [ - { - "denom": "token", - "amount": "20000" - }, - { - "denom": "stake", - "amount": "200000000" - } - ] + "denom": "token", + "amount": "20000" }, { - "name": "bob", - "coins": [ - { - "denom": "token", - "amount": "10000" - }, - { - "denom": "stake", - "amount": "100000000" - } - ] + "denom": "stake", + "amount": "200000000" } - ], - "validators": [ + ] + }, + { + "name": "bob", + "coins": [ { - "name": "alice", - "bonded": { - "denom": "stake", - "amount": "100000000" - } + "denom": "token", + "amount": "10000" + }, + { + "denom": "stake", + "amount": "100000000" } - ] -} \ No newline at end of file + ] + } + ], + "validators": [ + { + "name": "alice", + "bonded": { + "denom": "stake", + "amount": "100000000" + } + } + ] +} diff --git a/config/mainnet/config.json b/config/mainnet/config.json index 788eded..996e98b 100644 --- a/config/mainnet/config.json +++ b/config/mainnet/config.json @@ -1,25 +1,26 @@ { - "chain_id": "feather-1", - "app_name": "feather-core", - "app_binary_name": "feather-cored", - "account_address_prefix": "pfeath", - "account_pubkey_prefix": "pfeathpub", - "validator_address_prefix": "pfeathvaloper", - "validator_pubkey_prefix": "pfeathvaloperpub", - "consensus_node_address_prefix": "pfeathvalcons", - "consensus_node_pubkey_prefix": "pfeathvalconspub", - "bond_denom": "stake", - "bond_supply": "1000000000", - "unbonding_time": "1814400s", - "max_validators": 130, - "max_entries": 7, - "min_commission_rate": "0", - "lcd_enabled": true, - "lcd_swagger_enabled": true, - "lcd_port": 1317, - "lcd_enable_unsafe_cors": false, - "rpc_enabled": true, - "rpc_port": 26657, - "prometheus_enabled": true, - "prometheus_port": 26660 -} \ No newline at end of file + "chain_id": "feather-1", + "app_name": "feather-core", + "app_binary_name": "feather-cored", + "account_address_prefix": "pfeath", + "account_pubkey_prefix": "pfeathpub", + "validator_address_prefix": "pfeathvaloper", + "validator_pubkey_prefix": "pfeathvaloperpub", + "consensus_node_address_prefix": "pfeathvalcons", + "consensus_node_pubkey_prefix": "pfeathvalconspub", + "bond_denom": "stake", + "bond_supply": "1000000000", + "unbonding_time": "1814400s", + "max_validators": 130, + "max_entries": 7, + "min_commission_rate": "0", + "accounts": [], + "lcd_enabled": true, + "lcd_swagger_enabled": true, + "lcd_port": 1317, + "lcd_enable_unsafe_cors": false, + "rpc_enabled": true, + "rpc_port": 26657, + "prometheus_enabled": true, + "prometheus_port": 26660 +}