From da559e68498591db62caef25b9fd9a7d5b09024e Mon Sep 17 00:00:00 2001 From: julienrbrt <29894366+julienrbrt@users.noreply.github.com> Date: Wed, 21 May 2025 21:04:03 +0000 Subject: [PATCH 1/4] docs(config): update config doc --- docs/docs/08-references/03-config.md | 89 ++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/docs/08-references/03-config.md diff --git a/docs/docs/08-references/03-config.md b/docs/docs/08-references/03-config.md new file mode 100644 index 0000000000..08e951ba1e --- /dev/null +++ b/docs/docs/08-references/03-config.md @@ -0,0 +1,89 @@ +--- +sidebar_position: 4 +description: Configuration file example. +title: Configuration file example +--- + +## Configuration file example + +```yaml title="config.yml" +include: (string list) # Include incorporate a separate config.yml file directly in your current config file. +validation: (string) # Specifies the type of validation the blockchain uses (e.g., sovereign). +version: (uint) # Defines the configuration version number. +build: # Contains build configuration options. + main: (string) # Path to the main build file. + binary: (string) # Path to the binary file. + ldflags: (string list) # List of custom linker flags for building the binary. + proto: # Contains proto build configuration options. + path: (string) # Relative path where the application's proto files are located. +accounts: (list) # Lists the options for setting up Cosmos Accounts. + name: (string) # Local name associated with the Account's key pair. + coins: (string list) # List of token balances for the account. + mnemonic: (string) # Mnemonic phrase for the account. + address: (string) # Address of the account. + cointype: (string) # Coin type number for HD derivation (default is 118). + account_number: (string) # Account number for HD derivation (must be ≤ 2147483647). + address_index: (string) # Address index number for HD derivation (must be ≤ 2147483647). +faucet: # Configuration for the faucet. + name: (string) # Name of the faucet account. + coins: (string list) # Types and amounts of coins the faucet distributes. + coins_max: (string list) # Maximum amounts of coins that can be transferred to a single user. + rate_limit_window: (string) # Timeframe after which the limit will be refreshed. + host: (string) # Host address of the faucet server. + port: (uint) # Port number for the faucet server. + tx_fee: (string) # Tx fee the faucet needs to pay for each transaction. +client: # Configures client code generation. + typescript: # Relative path where the application's Typescript files are located. + path: (string) # Relative path where the application's Typescript files are located. + composables: # Configures Vue 3 composables code generation. + path: (string) # Relative path where the application's composable files are located. + hooks: # Configures React hooks code generation. + path: (string) # Relative path where the application's hooks files are located. + openapi: # Configures OpenAPI spec generation for the API. + path: (string) # Relative path where the application's OpenAPI files are located. +genesis: (key/value) # Custom genesis block modifications. Follow the nesting of the genesis file here to access all the parameters. +default_denom: (string) # Default staking denom (default is stake). +validators: (list) # Contains information related to the list of validators and settings. + name: (string) # Name of the validator. + bonded: (string) # Amount staked by the validator. + app: (key/value) # Overwrites the appd's config/app.toml configurations. + config: (key/value) # Overwrites the appd's config/config.toml configurations. + client: (key/value) # Overwrites the appd's config/client.toml configurations. + home: (string) # Overwrites the default home directory used for the application. + gentx: # Overwrites the appd's config/gentx.toml configurations. + amount: (string) # Amount for the current Gentx. + moniker: (string) # Optional moniker for the validator. + keyring-backend: (string) # Backend for the keyring. + chain-id: (string) # Network chain ID. + commission-max-change-rate: (string) # Maximum commission change rate percentage per day. + commission-max-rate: (string) # Maximum commission rate percentage (e.g., 0.01 = 1%). + commission-rate: (string) # Initial commission rate percentage (e.g., 0.01 = 1%). + details: (string) # Optional details about the validator. + security-contact: (string) # Optional security contact email for the validator. + website: (string) # Optional website for the validator. + account-number: (int) # Account number of the signing account (offline mode only). + broadcast-mode: (string) # Transaction broadcasting mode (sync|async|block) (default is 'sync'). + dry-run: (bool) # Simulates the transaction without actually performing it, ignoring the --gas flag. + fee-account: (string) # Account that pays the transaction fees instead of the signer. + fee: (string) # Fee to pay with the transaction (e.g.: 10uatom). + from: (string) # Name or address of the private key used to sign the transaction. + gas: (string) # Gas limit per transaction; set to 'auto' to calculate sufficient gas automatically (default is 200000). + gas-adjustment: (string) # Factor to multiply against the estimated gas (default is 1). + gas-prices: (string) # Gas prices in decimal format to determine the transaction fee (e.g., 0.1uatom). + generate-only: (bool) # Creates an unsigned transaction and writes it to STDOUT. + identity: (string) # Identity signature (e.g., UPort or Keybase). + ip: (string) # Node's public IP address (default is '192.168.1.64'). + keyring-dir: (string) # Directory for the client keyring; defaults to the 'home' directory if omitted. + ledger: (bool) # Uses a connected Ledger device if true. + min-self-delegation: (string) # Minimum self-delegation required for the validator. + node: (string) # <host>:<port> for the Tendermint RPC interface (default 'tcp://localhost:26657') + node-id: (string) # Node's NodeID + note: (string) # Adds a description to the transaction (formerly --memo). + offline: (bool) # Operates in offline mode, disallowing any online functionality. + output: (string) # Output format (text|json) (default 'json'). + output-document: (string) # Writes the genesis transaction JSON document to the specified file instead of the default location. + pubkey: (string) # Protobuf JSON encoded public key of the validator. + sequence: (uint) # Sequence number of the signing account (offline mode only). + sign-mode: (string) # Chooses sign mode (direct|amino-json), an advanced feature. + timeout-height: (uint) # Sets a block timeout height to prevent the transaction from being committed past a certain height. +``` \ No newline at end of file From 94257e5c94ceaccdcdce64396b7fc928650623ad Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Wed, 21 May 2025 23:06:53 +0200 Subject: [PATCH 2/4] change file location --- docs/docs/08-configuration/01-config.md | 410 ++++-------------- docs/docs/08-references/03-config.md | 89 ---- .../internal/tools/gen-config-doc/cmd/root.go | 4 +- 3 files changed, 88 insertions(+), 415 deletions(-) delete mode 100644 docs/docs/08-references/03-config.md diff --git a/docs/docs/08-configuration/01-config.md b/docs/docs/08-configuration/01-config.md index 411d4a2490..08e951ba1e 100644 --- a/docs/docs/08-configuration/01-config.md +++ b/docs/docs/08-configuration/01-config.md @@ -1,327 +1,89 @@ --- -sidebar_position: 1 -description: Primary configuration file to describe the development environment for your blockchain. -title: Configuration File Documentation +sidebar_position: 4 +description: Configuration file example. +title: Configuration file example --- -# Configuration File Reference - -After scaffolding a blockchain with Ignite CLI, you will find a configuration file at the root of your newly created directory. - -The `config.yml` file generated in your blockchain folder uses key-value pairs -to describe the development environment for your blockchain. - -Only a default set of parameters is provided. If more nuanced configuration is -required, you can add these parameters to the `config.yml` file. - -## Validation - -Ignite uses the `validation` field to determine the kind of validation -of your blockchain. There are currently two supported kinds of validation: - -- `sovereign` which is the standard kind of validation where your blockchain - has its own validator set. This is the default value when this field is not - in the config file. -- `consumer` indicates your blockchain is a consumer chain, in the sense of - Replicated Security. That means it doesn't have a validator set, but - inherits the one of a provider chain. - -While the `sovereign` chain is the default validation when you run the `ignite scaffold -chain`, to scaffold a consumer chain, you have to run `ignite scaffold chain ---consumer`. - -This field is, at this time of writing, only used by Ignite at the genesis -generation step, because the genesis of a sovereign chain and a consumer chain -are different. - -## Accounts - -A list of user accounts created during genesis of the blockchain. - -```yml -accounts: - - name: alice - coins: ['20000token', '200000000stake'] - - name: bob - coins: ['10000token', '100000000stake'] -``` - -Ignite uses information from `accounts` when initializing the chain with `ignite -chain init` and `ignite chain start`. In the example above Ignite will add two -accounts to the `genesis.json` file of the chain. - -`name` is a local name of a key pair associated with an account. Once the chain -is initialized and started, you will be able to use `name` when signing -transactions. With the configuration above, you'd be able to sign transactions -both with Alice's and Bob's accounts like so `exampled tx bank send ... --from -alice`. - -`coins` is a list of token balances for the account. If a token denomination is -in this list, it will exist in the genesis balance and will be a valid token. -When initialized with the config file above, a chain will only have two accounts -at genesis (Alice and Bob) and two native tokens (with denominations `token` and -`stake`). - -By default, every time a chain is re-initialized, Ignite will create a new key -pair for each account. So even though the account name can remain the same -(`bob`), every chain reinitialize it will have a different mnemonic and address. - -If you want an account to have a specific address, provide the `address` field -with a valid bech32 address. The prefix (by default, `cosmos`) should match the -one expected by your chain. When an account is provided with an `address` a key -pair will not be generated, because it's impossible to derive a key from an -address. An account with a given address will be added to the genesis file (with -an associated token balance), but because there is no key pair, you will not be -able to broadcast transactions from that address. This is useful when you have -generated a key pair outside of Ignite (for example, using your chain's CLI or -in an extension wallet) and want to have a token balance associated with the -address of this key pair. - -```yml -accounts: - - name: bob - coins: ['20000token', '200000000stake'] - address: cosmos1s39200s6v4c96ml2xzuh389yxpd0guk2mzn3mz -``` - -If you want an account to be initialized from a specific mnemonic, provide the -`mnemonic` field with a valid mnemonic. A private key, a public key and an -address will be derived from a mnemonic. - -```yml -accounts: - - name: bob - coins: ['20000token', '200000000stake'] - mnemonic: cargo ramp supreme review change various throw air figure humble soft steel slam pole betray inhale already dentist enough away office apple sample glue -``` - -You cannot have both `address` and `mnemonic` defined for a single account. - -Some accounts are used as validator accounts (see `validators` section). -Validator accounts cannot have an `address` field, because Ignite needs to be -able to derive a private key (either from a random mnemonic or from a specific -one provided in the `mnemonic` field). Validator accounts should have enough -tokens of the staking denomination for self-delegation. - -By default, the `alice` account is used as a validator account, its key is -derived from a mnemonic generated randomly at genesis, the staking denomination -is `stake`, and this account has enough `stake` for self-delegation. - -If your chain is using its own -[cointype](https://github.com/satoshilabs/slips/blob/master/slip-0044.md), you -can use the `cointype` field to provide the integer value - -```yml -accounts: - - name: bob - coins: ['20000token', '200000000stake'] - cointype: 7777777 -``` - -## Validators - -Commands like `ignite chain init` and `ignite chain serve` initialize and launch -a validator node for development purposes. - -```yml -validators: - - name: alice - bonded: '100000000stake' -``` - -`name` refers to key name in the `accounts` list. - -`bonded` is the self-delegation amount of a validator. The `bonded` amount -should not be lower than `1000000` nor higher than the account's -balance in the `account` list. - -Validators store their node configuration files in the data directory. By -default, Ignite uses the name of the project as the name of the data directory, -for example, `$HOME/.example/`. To use a different path for the data directory -you can customize the `home` property. - -Configuration in the data directory is reset frequently by Ignite. To persist -some changes to configuration files you can use `app`, `config` and `client` -properties that correspond to `$HOME/.example/config/app.toml`, -`$HOME/.example/config/config.toml` and `$HOME/.example/config/client.toml`. - -```yml -validators: - - name: alice - bonded: '100000000stake' - home: "~/.mychain" - app: - pruning: "nothing" - config: - moniker: "mychain" - client: - output: "json" -``` - -To see which properties are available for `config.toml`, `app.toml` and -`client.toml`, initialize a chain with `ignite chain init` and open the file you -want to know more about. - -Currently, Ignite starts only one validator node, so the first item in the -`validators` list is used (the rest is ignored). Support for multiple validators -is in progress. - -## Build - -The `build` property lets you customize how Ignite builds your chain's binary. - -By default, Ignite builds the `main` package from `cmd/PROJECT_NAME/main.go`. If -you more than one `main` package in your project, or you have renamed the -directory, use the `main` property to provide the path to the `main` Go package: - -```yml -build: - main: cmd/hello/cmd -``` - -Ignite compiles your project into a binary and uses the project's name with a -`d` suffix as name for the binary. To customize the binary name use the `binary` -property: - -```yml -build: - binary: "helloworldd" -``` - -To customize the linker flags used in the build process: - -```yml -build: - ldflags: [ "-X main.Version=development", "-X main.Date=01/05/2022T19:54" ] -``` - -By default, custom protocol buffer (proto) files are located in the `proto` -directory. If your project keeps proto files in a different directory, you -should tell Ignite about this: - -```yml -build: - proto: - path: "myproto" -``` - -## Faucet - -The faucet service sends tokens to addresses. - -```yml -faucet: - name: bob - coins: ["5token", "100000stake"] -``` - -`name` refers to a key name in the `accounts` list. This is a required property. - -`coins` is the amount of tokens that will be sent to a user by the faucet. This -is a required property. - -`coins_max` is a maximum amount of tokens that can be sent to a single address. -To reset the token limit use the `rate_limit_window` property (in seconds). - -The default the faucet works on port `4500`. To use a different port number use -the `port` property. - -```yml -faucet: - name: faucet - coins: [ "100token", "5foo" ] - coins_max: [ "2000token", "1000foo" ] - port: 4500 - rate_limit_window: 3600 -``` - -## Genesis - -Genesis file is the initial block in the blockchain. It is required to launch a -blockchain, because it contains important information like token balances, and -modules' state. Genesis is stored in `$DATA_DIR/config/genesis.json`. - -Since the genesis file is reinitialized frequently during development, you can -set persistent options in the `genesis` property: - -```yml -genesis: - app_state: - staking: - params: - bond_denom: "denom" -``` - -To know which properties a genesis file supports, initialize a chain and look up -the genesis file in the data directory. - -## Client code generation - -Ignite can generate client-side code for interacting with your chain with the -`ignite generate` set of commands. Use the following properties to customize the -paths where the client-side code is generated. - -```yml -client: - openapi: - path: "docs/static/openapi.yml" - typescript: - path: "ts-client" - composables: - path: "vue/src/composables" - hooks: - path: "react/src/hooks" -``` - -## Include - -In your main `config.yml`, use the `include` field to reference other local or remote YAML files. -It allows you to split your chain configuration across multiple files, making it easier to manage and reuse configuration parts. - -```yml -version: 1 -include: - - "./accounts.yml" - - "./validators.yml" -``` - -Include remote files via URL or server path are also valid: - -```yml -version: 1 -include: - - "localhost:3045/accounts.yml" - - "https://ignite.com/config/validators.yml" -``` - -#### Common Use Cases: - -Split your config into a base setup and an external `accounts.yml` for better separation of concerns: - -- `config.yml` -```yml -version: 1 -include: - - "./accounts.yml" -client: - typescript: - path: ts-client -``` - -- `accounts.yml` -```yml -accounts: - - name: alice - coins: - - 20000token - - 200000000stake - - name: bob - coins: - - 20000token - - 200000000stake -faucet: - name: alice - coins: - - 5token - - 100000stake -``` +## Configuration file example + +```yaml title="config.yml" +include: (string list) # Include incorporate a separate config.yml file directly in your current config file. +validation: (string) # Specifies the type of validation the blockchain uses (e.g., sovereign). +version: (uint) # Defines the configuration version number. +build: # Contains build configuration options. + main: (string) # Path to the main build file. + binary: (string) # Path to the binary file. + ldflags: (string list) # List of custom linker flags for building the binary. + proto: # Contains proto build configuration options. + path: (string) # Relative path where the application's proto files are located. +accounts: (list) # Lists the options for setting up Cosmos Accounts. + name: (string) # Local name associated with the Account's key pair. + coins: (string list) # List of token balances for the account. + mnemonic: (string) # Mnemonic phrase for the account. + address: (string) # Address of the account. + cointype: (string) # Coin type number for HD derivation (default is 118). + account_number: (string) # Account number for HD derivation (must be ≤ 2147483647). + address_index: (string) # Address index number for HD derivation (must be ≤ 2147483647). +faucet: # Configuration for the faucet. + name: (string) # Name of the faucet account. + coins: (string list) # Types and amounts of coins the faucet distributes. + coins_max: (string list) # Maximum amounts of coins that can be transferred to a single user. + rate_limit_window: (string) # Timeframe after which the limit will be refreshed. + host: (string) # Host address of the faucet server. + port: (uint) # Port number for the faucet server. + tx_fee: (string) # Tx fee the faucet needs to pay for each transaction. +client: # Configures client code generation. + typescript: # Relative path where the application's Typescript files are located. + path: (string) # Relative path where the application's Typescript files are located. + composables: # Configures Vue 3 composables code generation. + path: (string) # Relative path where the application's composable files are located. + hooks: # Configures React hooks code generation. + path: (string) # Relative path where the application's hooks files are located. + openapi: # Configures OpenAPI spec generation for the API. + path: (string) # Relative path where the application's OpenAPI files are located. +genesis: (key/value) # Custom genesis block modifications. Follow the nesting of the genesis file here to access all the parameters. +default_denom: (string) # Default staking denom (default is stake). +validators: (list) # Contains information related to the list of validators and settings. + name: (string) # Name of the validator. + bonded: (string) # Amount staked by the validator. + app: (key/value) # Overwrites the appd's config/app.toml configurations. + config: (key/value) # Overwrites the appd's config/config.toml configurations. + client: (key/value) # Overwrites the appd's config/client.toml configurations. + home: (string) # Overwrites the default home directory used for the application. + gentx: # Overwrites the appd's config/gentx.toml configurations. + amount: (string) # Amount for the current Gentx. + moniker: (string) # Optional moniker for the validator. + keyring-backend: (string) # Backend for the keyring. + chain-id: (string) # Network chain ID. + commission-max-change-rate: (string) # Maximum commission change rate percentage per day. + commission-max-rate: (string) # Maximum commission rate percentage (e.g., 0.01 = 1%). + commission-rate: (string) # Initial commission rate percentage (e.g., 0.01 = 1%). + details: (string) # Optional details about the validator. + security-contact: (string) # Optional security contact email for the validator. + website: (string) # Optional website for the validator. + account-number: (int) # Account number of the signing account (offline mode only). + broadcast-mode: (string) # Transaction broadcasting mode (sync|async|block) (default is 'sync'). + dry-run: (bool) # Simulates the transaction without actually performing it, ignoring the --gas flag. + fee-account: (string) # Account that pays the transaction fees instead of the signer. + fee: (string) # Fee to pay with the transaction (e.g.: 10uatom). + from: (string) # Name or address of the private key used to sign the transaction. + gas: (string) # Gas limit per transaction; set to 'auto' to calculate sufficient gas automatically (default is 200000). + gas-adjustment: (string) # Factor to multiply against the estimated gas (default is 1). + gas-prices: (string) # Gas prices in decimal format to determine the transaction fee (e.g., 0.1uatom). + generate-only: (bool) # Creates an unsigned transaction and writes it to STDOUT. + identity: (string) # Identity signature (e.g., UPort or Keybase). + ip: (string) # Node's public IP address (default is '192.168.1.64'). + keyring-dir: (string) # Directory for the client keyring; defaults to the 'home' directory if omitted. + ledger: (bool) # Uses a connected Ledger device if true. + min-self-delegation: (string) # Minimum self-delegation required for the validator. + node: (string) # <host>:<port> for the Tendermint RPC interface (default 'tcp://localhost:26657') + node-id: (string) # Node's NodeID + note: (string) # Adds a description to the transaction (formerly --memo). + offline: (bool) # Operates in offline mode, disallowing any online functionality. + output: (string) # Output format (text|json) (default 'json'). + output-document: (string) # Writes the genesis transaction JSON document to the specified file instead of the default location. + pubkey: (string) # Protobuf JSON encoded public key of the validator. + sequence: (uint) # Sequence number of the signing account (offline mode only). + sign-mode: (string) # Chooses sign mode (direct|amino-json), an advanced feature. + timeout-height: (uint) # Sets a block timeout height to prevent the transaction from being committed past a certain height. +``` \ No newline at end of file diff --git a/docs/docs/08-references/03-config.md b/docs/docs/08-references/03-config.md deleted file mode 100644 index 08e951ba1e..0000000000 --- a/docs/docs/08-references/03-config.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -sidebar_position: 4 -description: Configuration file example. -title: Configuration file example ---- - -## Configuration file example - -```yaml title="config.yml" -include: (string list) # Include incorporate a separate config.yml file directly in your current config file. -validation: (string) # Specifies the type of validation the blockchain uses (e.g., sovereign). -version: (uint) # Defines the configuration version number. -build: # Contains build configuration options. - main: (string) # Path to the main build file. - binary: (string) # Path to the binary file. - ldflags: (string list) # List of custom linker flags for building the binary. - proto: # Contains proto build configuration options. - path: (string) # Relative path where the application's proto files are located. -accounts: (list) # Lists the options for setting up Cosmos Accounts. - name: (string) # Local name associated with the Account's key pair. - coins: (string list) # List of token balances for the account. - mnemonic: (string) # Mnemonic phrase for the account. - address: (string) # Address of the account. - cointype: (string) # Coin type number for HD derivation (default is 118). - account_number: (string) # Account number for HD derivation (must be ≤ 2147483647). - address_index: (string) # Address index number for HD derivation (must be ≤ 2147483647). -faucet: # Configuration for the faucet. - name: (string) # Name of the faucet account. - coins: (string list) # Types and amounts of coins the faucet distributes. - coins_max: (string list) # Maximum amounts of coins that can be transferred to a single user. - rate_limit_window: (string) # Timeframe after which the limit will be refreshed. - host: (string) # Host address of the faucet server. - port: (uint) # Port number for the faucet server. - tx_fee: (string) # Tx fee the faucet needs to pay for each transaction. -client: # Configures client code generation. - typescript: # Relative path where the application's Typescript files are located. - path: (string) # Relative path where the application's Typescript files are located. - composables: # Configures Vue 3 composables code generation. - path: (string) # Relative path where the application's composable files are located. - hooks: # Configures React hooks code generation. - path: (string) # Relative path where the application's hooks files are located. - openapi: # Configures OpenAPI spec generation for the API. - path: (string) # Relative path where the application's OpenAPI files are located. -genesis: (key/value) # Custom genesis block modifications. Follow the nesting of the genesis file here to access all the parameters. -default_denom: (string) # Default staking denom (default is stake). -validators: (list) # Contains information related to the list of validators and settings. - name: (string) # Name of the validator. - bonded: (string) # Amount staked by the validator. - app: (key/value) # Overwrites the appd's config/app.toml configurations. - config: (key/value) # Overwrites the appd's config/config.toml configurations. - client: (key/value) # Overwrites the appd's config/client.toml configurations. - home: (string) # Overwrites the default home directory used for the application. - gentx: # Overwrites the appd's config/gentx.toml configurations. - amount: (string) # Amount for the current Gentx. - moniker: (string) # Optional moniker for the validator. - keyring-backend: (string) # Backend for the keyring. - chain-id: (string) # Network chain ID. - commission-max-change-rate: (string) # Maximum commission change rate percentage per day. - commission-max-rate: (string) # Maximum commission rate percentage (e.g., 0.01 = 1%). - commission-rate: (string) # Initial commission rate percentage (e.g., 0.01 = 1%). - details: (string) # Optional details about the validator. - security-contact: (string) # Optional security contact email for the validator. - website: (string) # Optional website for the validator. - account-number: (int) # Account number of the signing account (offline mode only). - broadcast-mode: (string) # Transaction broadcasting mode (sync|async|block) (default is 'sync'). - dry-run: (bool) # Simulates the transaction without actually performing it, ignoring the --gas flag. - fee-account: (string) # Account that pays the transaction fees instead of the signer. - fee: (string) # Fee to pay with the transaction (e.g.: 10uatom). - from: (string) # Name or address of the private key used to sign the transaction. - gas: (string) # Gas limit per transaction; set to 'auto' to calculate sufficient gas automatically (default is 200000). - gas-adjustment: (string) # Factor to multiply against the estimated gas (default is 1). - gas-prices: (string) # Gas prices in decimal format to determine the transaction fee (e.g., 0.1uatom). - generate-only: (bool) # Creates an unsigned transaction and writes it to STDOUT. - identity: (string) # Identity signature (e.g., UPort or Keybase). - ip: (string) # Node's public IP address (default is '192.168.1.64'). - keyring-dir: (string) # Directory for the client keyring; defaults to the 'home' directory if omitted. - ledger: (bool) # Uses a connected Ledger device if true. - min-self-delegation: (string) # Minimum self-delegation required for the validator. - node: (string) # <host>:<port> for the Tendermint RPC interface (default 'tcp://localhost:26657') - node-id: (string) # Node's NodeID - note: (string) # Adds a description to the transaction (formerly --memo). - offline: (bool) # Operates in offline mode, disallowing any online functionality. - output: (string) # Output format (text|json) (default 'json'). - output-document: (string) # Writes the genesis transaction JSON document to the specified file instead of the default location. - pubkey: (string) # Protobuf JSON encoded public key of the validator. - sequence: (uint) # Sequence number of the signing account (offline mode only). - sign-mode: (string) # Chooses sign mode (direct|amino-json), an advanced feature. - timeout-height: (uint) # Sets a block timeout height to prevent the transaction from being committed past a certain height. -``` \ No newline at end of file diff --git a/ignite/internal/tools/gen-config-doc/cmd/root.go b/ignite/internal/tools/gen-config-doc/cmd/root.go index cbea0ac6db..09edc27da1 100644 --- a/ignite/internal/tools/gen-config-doc/cmd/root.go +++ b/ignite/internal/tools/gen-config-doc/cmd/root.go @@ -21,8 +21,8 @@ const ( flagOutput = "output" flagFilename = "filename" - defaultFilename = "03-config.md" - defaultDocPath = "docs/docs/08-references" + defaultFilename = "01-config.md" + defaultDocPath = "docs/docs/08-configuration" ) // NewRootCmd creates a new root command. From ccc46311d9438edd02f7d61f2b6e0e5dbaee9c00 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Wed, 21 May 2025 23:08:49 +0200 Subject: [PATCH 3/4] correction --- docs/docs/08-configuration/01-config.md | 410 ++++++++++++++---- .../08-configuration/02-config_example.md | 10 +- .../internal/tools/gen-config-doc/cmd/root.go | 2 +- 3 files changed, 330 insertions(+), 92 deletions(-) diff --git a/docs/docs/08-configuration/01-config.md b/docs/docs/08-configuration/01-config.md index 08e951ba1e..411d4a2490 100644 --- a/docs/docs/08-configuration/01-config.md +++ b/docs/docs/08-configuration/01-config.md @@ -1,89 +1,327 @@ --- -sidebar_position: 4 -description: Configuration file example. -title: Configuration file example +sidebar_position: 1 +description: Primary configuration file to describe the development environment for your blockchain. +title: Configuration File Documentation --- -## Configuration file example - -```yaml title="config.yml" -include: (string list) # Include incorporate a separate config.yml file directly in your current config file. -validation: (string) # Specifies the type of validation the blockchain uses (e.g., sovereign). -version: (uint) # Defines the configuration version number. -build: # Contains build configuration options. - main: (string) # Path to the main build file. - binary: (string) # Path to the binary file. - ldflags: (string list) # List of custom linker flags for building the binary. - proto: # Contains proto build configuration options. - path: (string) # Relative path where the application's proto files are located. -accounts: (list) # Lists the options for setting up Cosmos Accounts. - name: (string) # Local name associated with the Account's key pair. - coins: (string list) # List of token balances for the account. - mnemonic: (string) # Mnemonic phrase for the account. - address: (string) # Address of the account. - cointype: (string) # Coin type number for HD derivation (default is 118). - account_number: (string) # Account number for HD derivation (must be ≤ 2147483647). - address_index: (string) # Address index number for HD derivation (must be ≤ 2147483647). -faucet: # Configuration for the faucet. - name: (string) # Name of the faucet account. - coins: (string list) # Types and amounts of coins the faucet distributes. - coins_max: (string list) # Maximum amounts of coins that can be transferred to a single user. - rate_limit_window: (string) # Timeframe after which the limit will be refreshed. - host: (string) # Host address of the faucet server. - port: (uint) # Port number for the faucet server. - tx_fee: (string) # Tx fee the faucet needs to pay for each transaction. -client: # Configures client code generation. - typescript: # Relative path where the application's Typescript files are located. - path: (string) # Relative path where the application's Typescript files are located. - composables: # Configures Vue 3 composables code generation. - path: (string) # Relative path where the application's composable files are located. - hooks: # Configures React hooks code generation. - path: (string) # Relative path where the application's hooks files are located. - openapi: # Configures OpenAPI spec generation for the API. - path: (string) # Relative path where the application's OpenAPI files are located. -genesis: (key/value) # Custom genesis block modifications. Follow the nesting of the genesis file here to access all the parameters. -default_denom: (string) # Default staking denom (default is stake). -validators: (list) # Contains information related to the list of validators and settings. - name: (string) # Name of the validator. - bonded: (string) # Amount staked by the validator. - app: (key/value) # Overwrites the appd's config/app.toml configurations. - config: (key/value) # Overwrites the appd's config/config.toml configurations. - client: (key/value) # Overwrites the appd's config/client.toml configurations. - home: (string) # Overwrites the default home directory used for the application. - gentx: # Overwrites the appd's config/gentx.toml configurations. - amount: (string) # Amount for the current Gentx. - moniker: (string) # Optional moniker for the validator. - keyring-backend: (string) # Backend for the keyring. - chain-id: (string) # Network chain ID. - commission-max-change-rate: (string) # Maximum commission change rate percentage per day. - commission-max-rate: (string) # Maximum commission rate percentage (e.g., 0.01 = 1%). - commission-rate: (string) # Initial commission rate percentage (e.g., 0.01 = 1%). - details: (string) # Optional details about the validator. - security-contact: (string) # Optional security contact email for the validator. - website: (string) # Optional website for the validator. - account-number: (int) # Account number of the signing account (offline mode only). - broadcast-mode: (string) # Transaction broadcasting mode (sync|async|block) (default is 'sync'). - dry-run: (bool) # Simulates the transaction without actually performing it, ignoring the --gas flag. - fee-account: (string) # Account that pays the transaction fees instead of the signer. - fee: (string) # Fee to pay with the transaction (e.g.: 10uatom). - from: (string) # Name or address of the private key used to sign the transaction. - gas: (string) # Gas limit per transaction; set to 'auto' to calculate sufficient gas automatically (default is 200000). - gas-adjustment: (string) # Factor to multiply against the estimated gas (default is 1). - gas-prices: (string) # Gas prices in decimal format to determine the transaction fee (e.g., 0.1uatom). - generate-only: (bool) # Creates an unsigned transaction and writes it to STDOUT. - identity: (string) # Identity signature (e.g., UPort or Keybase). - ip: (string) # Node's public IP address (default is '192.168.1.64'). - keyring-dir: (string) # Directory for the client keyring; defaults to the 'home' directory if omitted. - ledger: (bool) # Uses a connected Ledger device if true. - min-self-delegation: (string) # Minimum self-delegation required for the validator. - node: (string) # <host>:<port> for the Tendermint RPC interface (default 'tcp://localhost:26657') - node-id: (string) # Node's NodeID - note: (string) # Adds a description to the transaction (formerly --memo). - offline: (bool) # Operates in offline mode, disallowing any online functionality. - output: (string) # Output format (text|json) (default 'json'). - output-document: (string) # Writes the genesis transaction JSON document to the specified file instead of the default location. - pubkey: (string) # Protobuf JSON encoded public key of the validator. - sequence: (uint) # Sequence number of the signing account (offline mode only). - sign-mode: (string) # Chooses sign mode (direct|amino-json), an advanced feature. - timeout-height: (uint) # Sets a block timeout height to prevent the transaction from being committed past a certain height. -``` \ No newline at end of file +# Configuration File Reference + +After scaffolding a blockchain with Ignite CLI, you will find a configuration file at the root of your newly created directory. + +The `config.yml` file generated in your blockchain folder uses key-value pairs +to describe the development environment for your blockchain. + +Only a default set of parameters is provided. If more nuanced configuration is +required, you can add these parameters to the `config.yml` file. + +## Validation + +Ignite uses the `validation` field to determine the kind of validation +of your blockchain. There are currently two supported kinds of validation: + +- `sovereign` which is the standard kind of validation where your blockchain + has its own validator set. This is the default value when this field is not + in the config file. +- `consumer` indicates your blockchain is a consumer chain, in the sense of + Replicated Security. That means it doesn't have a validator set, but + inherits the one of a provider chain. + +While the `sovereign` chain is the default validation when you run the `ignite scaffold +chain`, to scaffold a consumer chain, you have to run `ignite scaffold chain +--consumer`. + +This field is, at this time of writing, only used by Ignite at the genesis +generation step, because the genesis of a sovereign chain and a consumer chain +are different. + +## Accounts + +A list of user accounts created during genesis of the blockchain. + +```yml +accounts: + - name: alice + coins: ['20000token', '200000000stake'] + - name: bob + coins: ['10000token', '100000000stake'] +``` + +Ignite uses information from `accounts` when initializing the chain with `ignite +chain init` and `ignite chain start`. In the example above Ignite will add two +accounts to the `genesis.json` file of the chain. + +`name` is a local name of a key pair associated with an account. Once the chain +is initialized and started, you will be able to use `name` when signing +transactions. With the configuration above, you'd be able to sign transactions +both with Alice's and Bob's accounts like so `exampled tx bank send ... --from +alice`. + +`coins` is a list of token balances for the account. If a token denomination is +in this list, it will exist in the genesis balance and will be a valid token. +When initialized with the config file above, a chain will only have two accounts +at genesis (Alice and Bob) and two native tokens (with denominations `token` and +`stake`). + +By default, every time a chain is re-initialized, Ignite will create a new key +pair for each account. So even though the account name can remain the same +(`bob`), every chain reinitialize it will have a different mnemonic and address. + +If you want an account to have a specific address, provide the `address` field +with a valid bech32 address. The prefix (by default, `cosmos`) should match the +one expected by your chain. When an account is provided with an `address` a key +pair will not be generated, because it's impossible to derive a key from an +address. An account with a given address will be added to the genesis file (with +an associated token balance), but because there is no key pair, you will not be +able to broadcast transactions from that address. This is useful when you have +generated a key pair outside of Ignite (for example, using your chain's CLI or +in an extension wallet) and want to have a token balance associated with the +address of this key pair. + +```yml +accounts: + - name: bob + coins: ['20000token', '200000000stake'] + address: cosmos1s39200s6v4c96ml2xzuh389yxpd0guk2mzn3mz +``` + +If you want an account to be initialized from a specific mnemonic, provide the +`mnemonic` field with a valid mnemonic. A private key, a public key and an +address will be derived from a mnemonic. + +```yml +accounts: + - name: bob + coins: ['20000token', '200000000stake'] + mnemonic: cargo ramp supreme review change various throw air figure humble soft steel slam pole betray inhale already dentist enough away office apple sample glue +``` + +You cannot have both `address` and `mnemonic` defined for a single account. + +Some accounts are used as validator accounts (see `validators` section). +Validator accounts cannot have an `address` field, because Ignite needs to be +able to derive a private key (either from a random mnemonic or from a specific +one provided in the `mnemonic` field). Validator accounts should have enough +tokens of the staking denomination for self-delegation. + +By default, the `alice` account is used as a validator account, its key is +derived from a mnemonic generated randomly at genesis, the staking denomination +is `stake`, and this account has enough `stake` for self-delegation. + +If your chain is using its own +[cointype](https://github.com/satoshilabs/slips/blob/master/slip-0044.md), you +can use the `cointype` field to provide the integer value + +```yml +accounts: + - name: bob + coins: ['20000token', '200000000stake'] + cointype: 7777777 +``` + +## Validators + +Commands like `ignite chain init` and `ignite chain serve` initialize and launch +a validator node for development purposes. + +```yml +validators: + - name: alice + bonded: '100000000stake' +``` + +`name` refers to key name in the `accounts` list. + +`bonded` is the self-delegation amount of a validator. The `bonded` amount +should not be lower than `1000000` nor higher than the account's +balance in the `account` list. + +Validators store their node configuration files in the data directory. By +default, Ignite uses the name of the project as the name of the data directory, +for example, `$HOME/.example/`. To use a different path for the data directory +you can customize the `home` property. + +Configuration in the data directory is reset frequently by Ignite. To persist +some changes to configuration files you can use `app`, `config` and `client` +properties that correspond to `$HOME/.example/config/app.toml`, +`$HOME/.example/config/config.toml` and `$HOME/.example/config/client.toml`. + +```yml +validators: + - name: alice + bonded: '100000000stake' + home: "~/.mychain" + app: + pruning: "nothing" + config: + moniker: "mychain" + client: + output: "json" +``` + +To see which properties are available for `config.toml`, `app.toml` and +`client.toml`, initialize a chain with `ignite chain init` and open the file you +want to know more about. + +Currently, Ignite starts only one validator node, so the first item in the +`validators` list is used (the rest is ignored). Support for multiple validators +is in progress. + +## Build + +The `build` property lets you customize how Ignite builds your chain's binary. + +By default, Ignite builds the `main` package from `cmd/PROJECT_NAME/main.go`. If +you more than one `main` package in your project, or you have renamed the +directory, use the `main` property to provide the path to the `main` Go package: + +```yml +build: + main: cmd/hello/cmd +``` + +Ignite compiles your project into a binary and uses the project's name with a +`d` suffix as name for the binary. To customize the binary name use the `binary` +property: + +```yml +build: + binary: "helloworldd" +``` + +To customize the linker flags used in the build process: + +```yml +build: + ldflags: [ "-X main.Version=development", "-X main.Date=01/05/2022T19:54" ] +``` + +By default, custom protocol buffer (proto) files are located in the `proto` +directory. If your project keeps proto files in a different directory, you +should tell Ignite about this: + +```yml +build: + proto: + path: "myproto" +``` + +## Faucet + +The faucet service sends tokens to addresses. + +```yml +faucet: + name: bob + coins: ["5token", "100000stake"] +``` + +`name` refers to a key name in the `accounts` list. This is a required property. + +`coins` is the amount of tokens that will be sent to a user by the faucet. This +is a required property. + +`coins_max` is a maximum amount of tokens that can be sent to a single address. +To reset the token limit use the `rate_limit_window` property (in seconds). + +The default the faucet works on port `4500`. To use a different port number use +the `port` property. + +```yml +faucet: + name: faucet + coins: [ "100token", "5foo" ] + coins_max: [ "2000token", "1000foo" ] + port: 4500 + rate_limit_window: 3600 +``` + +## Genesis + +Genesis file is the initial block in the blockchain. It is required to launch a +blockchain, because it contains important information like token balances, and +modules' state. Genesis is stored in `$DATA_DIR/config/genesis.json`. + +Since the genesis file is reinitialized frequently during development, you can +set persistent options in the `genesis` property: + +```yml +genesis: + app_state: + staking: + params: + bond_denom: "denom" +``` + +To know which properties a genesis file supports, initialize a chain and look up +the genesis file in the data directory. + +## Client code generation + +Ignite can generate client-side code for interacting with your chain with the +`ignite generate` set of commands. Use the following properties to customize the +paths where the client-side code is generated. + +```yml +client: + openapi: + path: "docs/static/openapi.yml" + typescript: + path: "ts-client" + composables: + path: "vue/src/composables" + hooks: + path: "react/src/hooks" +``` + +## Include + +In your main `config.yml`, use the `include` field to reference other local or remote YAML files. +It allows you to split your chain configuration across multiple files, making it easier to manage and reuse configuration parts. + +```yml +version: 1 +include: + - "./accounts.yml" + - "./validators.yml" +``` + +Include remote files via URL or server path are also valid: + +```yml +version: 1 +include: + - "localhost:3045/accounts.yml" + - "https://ignite.com/config/validators.yml" +``` + +#### Common Use Cases: + +Split your config into a base setup and an external `accounts.yml` for better separation of concerns: + +- `config.yml` +```yml +version: 1 +include: + - "./accounts.yml" +client: + typescript: + path: ts-client +``` + +- `accounts.yml` +```yml +accounts: + - name: alice + coins: + - 20000token + - 200000000stake + - name: bob + coins: + - 20000token + - 200000000stake +faucet: + name: alice + coins: + - 5token + - 100000stake +``` diff --git a/docs/docs/08-configuration/02-config_example.md b/docs/docs/08-configuration/02-config_example.md index 5ef5353104..08e951ba1e 100644 --- a/docs/docs/08-configuration/02-config_example.md +++ b/docs/docs/08-configuration/02-config_example.md @@ -1,10 +1,10 @@ --- -sidebar_position: 2 -description: Configuration File Example. -title: Configuration File Example +sidebar_position: 4 +description: Configuration file example. +title: Configuration file example --- -## Configuration File Example +## Configuration file example ```yaml title="config.yml" include: (string list) # Include incorporate a separate config.yml file directly in your current config file. @@ -42,7 +42,7 @@ client: # Configures client code generation. openapi: # Configures OpenAPI spec generation for the API. path: (string) # Relative path where the application's OpenAPI files are located. genesis: (key/value) # Custom genesis block modifications. Follow the nesting of the genesis file here to access all the parameters. -minimal: (bool) # Indicates if the blockchain is minimal with the required Cosmos SDK modules. +default_denom: (string) # Default staking denom (default is stake). validators: (list) # Contains information related to the list of validators and settings. name: (string) # Name of the validator. bonded: (string) # Amount staked by the validator. diff --git a/ignite/internal/tools/gen-config-doc/cmd/root.go b/ignite/internal/tools/gen-config-doc/cmd/root.go index 09edc27da1..fbdac08e1c 100644 --- a/ignite/internal/tools/gen-config-doc/cmd/root.go +++ b/ignite/internal/tools/gen-config-doc/cmd/root.go @@ -21,7 +21,7 @@ const ( flagOutput = "output" flagFilename = "filename" - defaultFilename = "01-config.md" + defaultFilename = "02-config_example.md" defaultDocPath = "docs/docs/08-configuration" ) From 3a8e81f49017838ce23ae6c137c49ffd598ca45c Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Wed, 21 May 2025 23:09:44 +0200 Subject: [PATCH 4/4] updates --- docs/docs/08-configuration/02-config_example.md | 10 +++++----- .../gen-config-doc/templates/doc/files/{{Name}}.plush | 8 ++++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/docs/08-configuration/02-config_example.md b/docs/docs/08-configuration/02-config_example.md index 08e951ba1e..b38e49eef0 100644 --- a/docs/docs/08-configuration/02-config_example.md +++ b/docs/docs/08-configuration/02-config_example.md @@ -1,10 +1,10 @@ --- -sidebar_position: 4 -description: Configuration file example. -title: Configuration file example +sidebar_position: 2 +description: Configuration File Example. +title: Configuration File Example --- -## Configuration file example +## Configuration File Example ```yaml title="config.yml" include: (string list) # Include incorporate a separate config.yml file directly in your current config file. @@ -86,4 +86,4 @@ validators: (list) # Contains information related to the list of validators and sequence: (uint) # Sequence number of the signing account (offline mode only). sign-mode: (string) # Chooses sign mode (direct|amino-json), an advanced feature. timeout-height: (uint) # Sets a block timeout height to prevent the transaction from being committed past a certain height. -``` \ No newline at end of file +``` diff --git a/ignite/internal/tools/gen-config-doc/templates/doc/files/{{Name}}.plush b/ignite/internal/tools/gen-config-doc/templates/doc/files/{{Name}}.plush index 1f56a82675..0bf857ba86 100644 --- a/ignite/internal/tools/gen-config-doc/templates/doc/files/{{Name}}.plush +++ b/ignite/internal/tools/gen-config-doc/templates/doc/files/{{Name}}.plush @@ -1,10 +1,10 @@ --- -sidebar_position: 4 -description: Configuration file example. -title: Configuration file example +sidebar_position: 2 +description: Configuration File Example. +title: Configuration File Example --- -## Configuration file example +## Configuration File Example ```yaml title="config.yml" <%= Config %>