### Install Cosmopilot with Helm Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/03-installation.md Use this command to install Cosmopilot in the 'cosmopilot-system' namespace. Ensure prerequisites are met. ```bash helm install \ cosmopilot oci://ghcr.io/nibiruchain/helm/cosmopilot \ --namespace cosmopilot-system \ --create-namespace ``` -------------------------------- ### Start Blockchain Node Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/02-chain-compatibility.md Starts the blockchain node. Ensure the `--home` flag is set to specify the home directory path. The `--trace-store` flag is also supported for trace output. ```bash start --home [additional-flags] ``` -------------------------------- ### Install Cosmopilot Helm Chart Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Install Cosmopilot using the Helm chart. Options include installing the latest version, a specific version, or disabling webhooks if cert-manager is not installed. ```bash helm install \ cosmopilot oci://ghcr.io/nibiruchain/helm/cosmopilot \ --namespace cosmopilot-system \ --create-namespace ``` ```bash helm install \ cosmopilot oci://ghcr.io/nibiruchain/helm/cosmopilot \ --namespace cosmopilot-system \ --create-namespace \ --version 1.35.2 ``` ```bash helm install \ cosmopilot oci://ghcr.io/nibiruchain/helm/cosmopilot \ --namespace cosmopilot-system \ --create-namespace \ --set webHooksEnabled=false ``` -------------------------------- ### Start Node for Snapshot Integrity Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/02-chain-compatibility.md Starts the node with specific flags for snapshot integrity verification. Requires `--grpc-only` and `--home` flags. ```bash start --grpc-only --home ``` -------------------------------- ### Install Specific Cosmopilot Version with Helm Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/03-installation.md Install a specific version of Cosmopilot by specifying the --version flag. Ensure the version number is correct. ```bash helm install \ cosmopilot oci://ghcr.io/nibiruchain/helm/cosmopilot \ --namespace cosmopilot-system \ --create-namespace \ --version 1.35.2 ``` -------------------------------- ### CosmoGuard Basic Configuration Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/12-cosmoguard.md Example CosmoGuard configuration allowing only the /status endpoint on RPC with caching enabled. This is a starting point for defining access rules. ```yaml cache: ttl: 10s rpc: rules: - action: allow paths: - /status methods: - GET cache: enable: true ``` -------------------------------- ### Install Cosmopilot Disabling Webhooks Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/03-installation.md If cert-manager is not installed, disable webhooks using the --set webHooksEnabled=false flag. This is an alternative installation method. ```bash helm install \ cosmopilot oci://ghcr.io/nibiruchain/helm/cosmopilot \ --namespace cosmopilot-system \ --create-namespace \ --set webHooksEnabled=false ``` -------------------------------- ### Setup Vault for TmKMS Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Prepare HashiCorp Vault for TmKMS integration by enabling the transit secrets engine, creating a policy for the consensus key, and generating a token. Store the Vault token in a Kubernetes secret. ```bash # Setup Vault for TmKMS vault secrets enable transit # Create policy for the key export KEY=my-consensus-key cat < init --chain-id --home ``` -------------------------------- ### Configure Node Startup Time Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/04-node-config.md Adjust the startup probe timeout. Defaults to 1h. ```yaml config: startupTime: 3h ``` -------------------------------- ### Configure startup flags Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/04-node-config.md Appends additional command-line flags to the main application process. ```yaml config: runFlags: ["--reject-config-defaults=true"] ``` -------------------------------- ### Deploy and Verify Devnet Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Commands to apply the configuration and verify the generated genesis and validator credentials. ```bash # Deploy the devnet kubectl apply -f devnet.yaml # Check genesis was created kubectl get configmap nibiru-devnet-genesis -o yaml # View validator account kubectl get secret nibiru-devnet-validator-account -o jsonpath='{.data.mnemonic}' | base64 -d ``` -------------------------------- ### Configure Basic VPA Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/15-vertical-pod-autoscaling.md Enable VPA and define CPU and memory scaling rules for a ChainNode. This configuration sets minimum and maximum resource limits and specifies usage thresholds for scaling up or down. ```yaml spec: vpa: enabled: true cpu: cooldown: 30m min: 750m max: 8000m rules: - direction: up usagePercent: 90 duration: 5m stepPercent: 50 - direction: down usagePercent: 40 duration: 30m stepPercent: 50 memory: cooldown: 30m min: 4Gi max: 32Gi rules: - direction: up usagePercent: 90 duration: 5m stepPercent: 75 - direction: down usagePercent: 40 duration: 30m stepPercent: 50 ``` -------------------------------- ### Add Account to Genesis (SDK v0.45 and Earlier) Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/02-chain-compatibility.md Adds an account to the genesis file for SDK versions v0.45 and earlier. Requires the account address, coins, and home path. ```bash add-genesis-account
--home ``` -------------------------------- ### Configure Per-Rule Cooldown for VPA Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/15-vertical-pod-autoscaling.md Override the default metric-level cooldown for specific VPA rules. This example shows a shorter cooldown for the scale-up rule, allowing more frequent scaling up compared to the default. ```yaml spec: vpa: enabled: true cpu: cooldown: 30m min: 750m max: 8000m rules: - direction: up usagePercent: 90 duration: 5m stepPercent: 50 cooldown: 5m - direction: down usagePercent: 40 duration: 30m stepPercent: 50 ``` -------------------------------- ### List Available Volume Snapshots Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/06-restoring-from-snapshot.md Command to list all available volume snapshots in the Kubernetes cluster. ```bash $ kubectl get volumesnapshots ``` -------------------------------- ### Custom Snapshot Restore with Init Commands Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/06-restoring-from-snapshot.md Specify additional init commands to run during data volume initialization. This is useful for downloading and extracting data from a tarball. ```yaml persistence: additionalInitCommands: - image: alpine # Optional. Defaults to app image. command: ["sh"] # Optional. Defaults to image entrypoint. args: ["-c", "wget -qO- https://remote.tarball.here | tar xvf - -C /home/app/data"] ``` -------------------------------- ### Add Account to Genesis (SDK v0.47+) Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/02-chain-compatibility.md Adds an account to the genesis file for SDK versions v0.47 and later. Requires the account address, coins, and home path. ```bash genesis add-genesis-account
--home ``` -------------------------------- ### Apply updated configuration Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/02-deploy-node-set.md Use kubectl to apply the modified manifest and trigger scaling. ```bash $ kubectl apply -f nodeset.yaml ``` -------------------------------- ### Configure Basic Genesis Initialization Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/10-initializing-new-network.md Defines the chain ID, stake amount, and initial assets for a new testnet network. ```yaml validator: init: chainID: my-testnet-1 stakeAmount: "1000000unibi" assets: - "100000000unibi" - "500000000uusdt" ``` -------------------------------- ### Execute Custom Genesis Commands Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/10-initializing-new-network.md Uses additionalInitCommands to run custom containers for advanced genesis modifications, such as adding a sudo root account. ```yaml validator: init: chainID: my-testnet-1 stakeAmount: "1000000unibi" assets: - "100000000unibi" - "500000000uusdt" additionalInitCommands: - image: ghcr.io/nibiruchain/nibiru:1.5.0 # optional, defaults to the image use by the ChainNode. command: [ "sh", "-c" ] # optional, defaults to image entrypoint. args: - > nibid genesis add-sudo-root-account \ $(nibid keys show account -a --home=/home/app --keyring-backend test) \ --home=/home/app ``` -------------------------------- ### Add Manual Upgrade Configuration Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/08-upgrades.md Use this configuration to define a manual upgrade directly in .spec.app.upgrades. This ensures a straightforward binary swap. ```yaml app: upgrades: - height: 3000 image: yourimage:yourtag ``` -------------------------------- ### GenesisInitConfig Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/03-reference/crds/crds.md Specifies configurations and initialization commands for creating a new genesis. ```APIDOC ## GenesisInitConfig GenesisInitConfig specifies configs and initialization commands for creating a new genesis. ### Fields - **chainID** (string) - Required - ChainID of the chain to initialize. - **accountMnemonicSecret** (string) - Optional - Name of the secret containing the mnemonic of the account to be used by this validator. Defaults to `-account`. Will be created if it does not exist. - **accountHDPath** (string) - Optional - HD path of accounts. Defaults to `m/44'/118'/0'/0/0`. - **accountPrefix** (string) - Optional - Prefix for accounts. Defaults to `nibi`. - **valPrefix** (string) - Optional - Prefix for validator operator accounts. Defaults to `nibivaloper`. - **commissionMaxChangeRate** (string) - Optional - Maximum commission change rate percentage (per day). Defaults to `0.1`. - **commissionMaxRate** (string) - Optional - Maximum commission rate percentage. Defaults to `0.1`. - **commissionRate** (string) - Optional - Initial commission rate percentage. Defaults to `0.1`. - **minSelfDelegation** (string) - Optional - Minimum self delegation required on the validator. Defaults to `1`. NOTE: In most chains this is a required flag. However, in a few other chains (Cosmos Hub for example), this flag does not even exist anymore. In those cases, set it to an empty string and cosmopilot will skip it. - **assets** ([]string) - Required - Assets is the list of tokens and their amounts to be assigned to this validators account. - **stakeAmount** (string) - Required - Amount to be staked by this validator. - **accounts** ([][AccountAssets](#accountassets)) - Optional - Accounts specify additional accounts and respective assets to be added to this chain. - **chainNodeAccounts** ([][ChainNodeAssets](#chainnodeassets)) - Optional - List of ChainNodes whose accounts should be included in genesis. NOTE: Cosmopilot will wait for the ChainNodes to exist and have accounts before proceeding. - **unbondingTime** (string) - Optional - Time required to totally unbond delegations. Defaults to `1814400s` (21 days). - **votingPeriod** (string) - Optional - Voting period for this chain. Defaults to `120h`. - **additionalInitCommands** ([][InitCommand](#initcommand)) - Optional - Additional commands to run on genesis initialization. Note: App home is at `/home/app` and `/temp` is a temporary volume shared by all init containers. ``` -------------------------------- ### Download Genesis from URL Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/03-genesis.md Specify a URL to fetch the genesis file directly. Ensure the URL points to a publicly accessible genesis file for the desired network or version. ```yaml genesis: url: https://raw.githubusercontent.com/NibiruChain/Networks/main/Mainnet/cataclysm-1/genesis.json ``` -------------------------------- ### FromNodeRPCConfig Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/03-reference/crds/crds.md Configuration to retrieve genesis from an existing node. ```APIDOC ## FromNodeRPCConfig ### Description Holds configuration to retrieve genesis from an existing node using RPC endpoint. ### Request Body - **secure** (bool) - Optional - Defines protocol to use. - **hostname** (string) - Required - Hostname or IP address of the RPC server. - **port** (*int) - Optional - TCP port used for RPC queries on the RPC server. ``` -------------------------------- ### Check Ingress Resources Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Verify that the ingress resources have been created successfully after deploying the ChainNodeSet configuration. This command lists all ingress resources in the current namespace. ```bash # Check ingress resources kubectl get ingress ``` -------------------------------- ### List Volume Snapshots Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Command to list existing volume snapshots in the cluster. ```bash # List volume snapshots kubectl get volumesnapshots # NAME READYTOUSE SOURCEPVC RESTORESIZE AGE ``` -------------------------------- ### Apply the node manifest Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/01-deploy-node.md Command to deploy the defined ChainNode resource to the Kubernetes cluster. ```bash $ kubectl apply -f node.yaml ``` -------------------------------- ### Collect Genesis Transactions (SDK v0.45 and Earlier) Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/02-chain-compatibility.md Collects all generated genesis transactions into the genesis file for SDK v0.45 and earlier. Requires the home path. ```bash collect-gentxs --home ``` -------------------------------- ### Create ConfigMap for Genesis File Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/03-genesis.md Use kubectl to create a Kubernetes ConfigMap containing the genesis file. Ensure the ConfigMap is created in the same namespace as your ChainNode or ChainNodeSet. ```bash kubectl create configmap custom-genesis --from-file=genesis.json ``` -------------------------------- ### Initialize a New Blockchain Network Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Define a ChainNodeSet to automate genesis creation, validator configuration, and account funding for a testnet. ```yaml apiVersion: apps.k8s.nibiru.org/v1 kind: ChainNodeSet metadata: name: nibiru-devnet spec: app: image: ghcr.io/nibiruchain/nibiru version: 1.5.0 app: nibid validator: info: moniker: nibiru-0 website: https://nibiru.fi # Genesis initialization configuration init: chainID: nibiru-devnet-0 stakeAmount: 100000000unibi assets: - "100000000000000unibi" - "1000000000000000000unusd" # Account configuration accountPrefix: nibi valPrefix: nibivaloper accountHDPath: "m/44'/118'/0'/0/0" # Commission settings commissionRate: "0.1" commissionMaxRate: "0.1" commissionMaxChangeRate: "0.1" # Testnet-friendly timing unbondingTime: 60s votingPeriod: 60s # Additional funded accounts accounts: - address: nibi10jf963eruna3clq4c4jwsj3k4jf5snp3z3q372 assets: ["100000000unibi", "500000000uusdt"] # Fund accounts from other ChainNodes (for multi-validator setup) chainNodeAccounts: - chainNode: nibiru-devnet-validator-1 assets: ["100000000000000unibi"] # Custom genesis modifications additionalInitCommands: - command: ["sh", "-c"] args: - > nibid genesis add-sudo-root-account \ $(nibid keys show account -a --home=/home/app --keyring-backend test) \ --home=/home/app config: override: app.toml: minimum-gas-prices: 0.025unibi # Sidecar containers (e.g., price feeder) sidecars: - name: pricefeeder image: ghcr.io/nibiruchain/pricefeeder:1.0.3 env: - name: FEEDER_MNEMONIC valueFrom: secretKeyRef: name: nibiru-devnet-validator-account key: mnemonic - name: CHAIN_ID value: nibiru-devnet-0 - name: GRPC_ENDPOINT value: localhost:9090 nodes: - name: fullnodes instances: 1 config: override: app.toml: minimum-gas-prices: 0.025unibi pruning: custom pruning-keep-recent: "100" ``` -------------------------------- ### Collect Genesis Transactions (SDK v0.47+) Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/02-chain-compatibility.md Collects all generated genesis transactions into the genesis file for SDK v0.47+. Requires the home path. ```bash genesis collect-gentxs --home ``` -------------------------------- ### StateSyncConfig Configuration Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/03-reference/crds/crds.md Configure settings for enabling state-sync snapshots on a node. ```APIDOC ## StateSyncConfig Configuration ### Description StateSyncConfig holds configurations for enabling state-sync snapshots on a node. ### Parameters #### Request Body - **snapshotInterval** (int) - Required - Block interval at which local state sync snapshots are taken (0 to disable). - **snapshotKeepRecent** (int) - Optional - Number of recent snapshots to keep and serve (0 to keep all). Defaults to 2. ``` -------------------------------- ### Show Cosmopilot Helm Values Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/04-configuration.md Run this command to display all available Helm values for the Cosmopilot chart. This is useful for understanding customization options. ```bash helm show values oci://ghcr.io/nibiruchain/helm/cosmopilot ``` -------------------------------- ### Build TmKMS Fork with HashiCorp Support Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/11-tmkms.md Clone and build the custom TmKMS fork from the NibiruChain repository, ensuring the 'hashicorp' and 'softsign' features are enabled. ```bash $ git clone --branch v0.14.0-vault https://github.com/NibiruChain/tmkms $ cd tmkms $ cargo build --release --features hashicorp,softsign ``` -------------------------------- ### Configure Periodic Snapshots Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/05-persistence-and-backup.md Set up automated volume snapshots with specific frequency and retention periods. ```yaml persistence: snapshot: frequency: 24h # Take a snapshot every 24 hours retention: 72h # Retain snapshots of the last 3 days ``` -------------------------------- ### Manage Validator via CLI Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Commands for creating the validator key secret, applying the configuration, and verifying validator status. ```bash # Create validator key secret (if using existing key) kubectl create secret generic my-validator-key \ --from-file=priv_validator_key.json # Apply validator configuration kubectl apply -f validator.yaml # Check validator status kubectl get chainnode my-validator # NAME STATUS IP VERSION CHAINID VALIDATOR BONDSTATUS JAILED # my-validator Running 10.8.5.40 1.0.0 cataclysm-1 true bonded false ``` -------------------------------- ### Manage ChainNodeSet via CLI Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Commands for applying the manifest, checking status, and scaling node groups using kubectl. ```bash # Apply the ChainNodeSet kubectl apply -f chainnodeset.yaml # Check status kubectl get chainnodesets # NAME STATUS VERSION CHAINID LATESTHEIGHT INSTANCES AGE # nibiru-cataclysm-1 Running 1.0.0 cataclysm-1 1234567 3 5m # Scale a node group kubectl patch chainnodeset nibiru-cataclysm-1 --type='json' \ -p='[{"op": "replace", "path": "/spec/nodes/0/instances", "value": 3}]' ``` -------------------------------- ### Test gRPC Endpoint with grpcurl Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/01-deploy-node.md After setting up port-forwarding, use `grpcurl` to interact with the gRPC endpoint. This command lists available services on the specified port. ```bash grpcurl --plaintext localhost:9090 list ``` -------------------------------- ### Persistence Configuration Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/03-reference/crds/crds.md Configure the persistence settings for a node, including volume size, storage class, auto-resizing options, and snapshot configurations. ```APIDOC ## Persistence Configuration ### Description Persistence configuration for a node. ### Parameters #### Request Body - **size** (string) - Optional - Size of the persistent volume for storing data. Can't be updated when autoResize is enabled. Defaults to `50Gi`. - **storageClass** (string) - Optional - Name of the storage class to use for the PVC. Uses the default class if not specified. - **autoResize** (bool) - Optional - Automatically resize PVC. Defaults to `true`. - **autoResizeThreshold** (int) - Optional - Percentage of data usage at which an auto-resize event should occur. Defaults to `80`. - **autoResizeIncrement** (string) - Optional - Increment size on each auto-resize event. Defaults to `50Gi`. - **autoResizeMaxSize** (string) - Optional - Size at which auto-resize will stop incrementing PVC size. Defaults to `2Ti`. - **additionalInitCommands** ([]InitCommand) - Optional - Additional commands to run on data initialization. Useful for downloading and extracting snapshots. App home is at `/home/app` and data dir is at `/home/app/data`. There is also `/temp`, a temporary volume shared by all init containers. - **snapshots** (VolumeSnapshotsConfig) - Optional - Whether cosmopilot should create volume snapshots according to this config. - **restoreFromSnapshot** (PvcSnapshot) - Optional - Restore from the specified snapshot when creating the PVC for this node. - **initTimeout** (string) - Optional - Time to wait for data initialization pod to be successful. Defaults to `5m`. ``` -------------------------------- ### Configure State-Sync Snapshots Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/04-node-config.md Define snapshot intervals and retention policies for state synchronization. ```yaml config: stateSync: snapshotInterval: 250 snapshotKeepRecent: 5 # optional. Defaults to 2. ``` -------------------------------- ### Configure External State-Sync Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/06-restoring-from-snapshot.md Manually configure state-sync for external nodes by overriding TOML configuration files. Specify RPC servers, trust height, and trust hash. ```yaml config: override: config.toml: statesync: enable: true rpc_servers: https://rpc.nibiru.fi:443,https://rpc.nibiru.fi:443 trust_height: 17849562 trust_hash: A8A55B09347E9BCC6A626D25EDEE2BA063812D2AC335B5EDCDB400239AD8CFE0 ``` -------------------------------- ### Create Kubernetes ConfigMap for CosmoGuard Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/12-cosmoguard.md Command to create a Kubernetes ConfigMap from a local CosmoGuard configuration file. Replace with your target namespace. ```bash kubectl create configmap cosmoguard-config --from-file=cosmoguard.yaml=/path/to/your/cosmoguard.yaml -n ``` -------------------------------- ### Configure State Sync Restore (Cosmopilot Managed) Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Define a ChainNode with state-sync enabled for quick bootstrapping. Cosmopilot automates trust height and hash configuration. Higher resources can be allocated during state-sync. ```yaml apiVersion: apps.k8s.nibiru.org/v1 kind: ChainNode metadata: name: new-fullnode spec: app: app: nibid image: ghcr.io/nibiruchain/nibiru version: 1.0.0 genesis: url: https://example.com/genesis.json # Enable state-sync restore (from Cosmopilot-managed nodes) stateSyncRestore: true # Optional: Higher resources during state-sync resources: requests: cpu: "500m" memory: "1Gi" limits: cpu: "1" memory: "2Gi" stateSyncResources: requests: cpu: "1000m" memory: "2Gi" limits: cpu: "2" memory: "4Gi" ``` -------------------------------- ### Required CLI Commands Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/02-chain-compatibility.md Essential CLI commands that your chain binary must support for Cosmopilot compatibility. ```APIDOC ## Required CLI Commands The following CLI commands must be supported by your chain binary for full Cosmopilot compatibility. Note that some commands differ between SDK versions. ### Node Initialization ```bash init --chain-id --home ``` This command initializes the chain home directory and generates default configuration files (`config.toml`, `app.toml`, etc.). ### Node Operation ```bash start --home [additional-flags] ``` Starts the blockchain node. Must support the following flags: - `--home` - Specify the home directory path - `--trace-store` - Path for trace output (FIFO) For snapshot integrity verification, the following is also required: ```bash start --grpc-only --home ``` ### Key Management ```bash keys add --recover --keyring-backend test --home ``` Recovers an account from a mnemonic. The `--keyring-backend test` flag must be supported for automated key management. ### Genesis Commands These commands are only required when [initializing a new network](/02-usage/10-initializing-new-network).
SDK v0.47+ (Default) ```bash # Add account to genesis genesis add-genesis-account
--home # Generate genesis transaction genesis gentx \ --moniker \ --chain-id \ --keyring-backend test \ --yes \ [--commission-max-change-rate ] \ [--commission-max-rate ] \ [--commission-rate ] \ [--min-self-delegation ] \ [--details
] \ [--website ] \ [--identity ] \ --home # Collect genesis transactions genesis collect-gentxs --home ```
SDK v0.45 and Earlier ```bash # Add account to genesis add-genesis-account
--home # Generate genesis transaction gentx \ --moniker \ --chain-id \ --keyring-backend test \ --yes \ [--commission-max-change-rate ] \ [--commission-max-rate ] \ [--commission-rate ] \ [--min-self-delegation ] \ [--details
] \ [--website ] \ [--identity ] \ --home # Collect genesis transactions collect-gentxs --home ```
### Validator Creation This command is only required when running a [validator node](/02-usage/09-validator). ```bash tx staking create-validator \ --amount \ --moniker \ --chain-id \ --pubkey \ --gas-prices \ --from \ --keyring-backend test \ --yes \ [--commission-max-change-rate ] \ [--commission-max-rate ] \ [--commission-rate ] \ [--min-self-delegation ] \ [--details
] \ [--website ] \ [--identity ] \ --node \ --home ``` ``` -------------------------------- ### Set Pod Resources Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/04-node-config.md Define CPU and memory requests and limits for the main application container. ```yaml resources: requests: cpu: "500m" memory: "1Gi" limits: cpu: "1" memory: "2Gi" ``` -------------------------------- ### Generate Genesis Transaction (SDK v0.45 and Earlier) Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/02-chain-compatibility.md Generates a genesis transaction for SDK v0.45 and earlier. Requires account, stake amount, moniker, chain ID, and home path. Optional flags for commission and validator details are available. ```bash gentx \ --moniker \ --chain-id \ --keyring-backend test \ --yes \ [--commission-max-change-rate ] \ [--commission-max-rate ] \ [--commission-rate ] \ [--min-self-delegation ] \ [--details
] \ [--website ] \ [--identity ] \ --home ``` -------------------------------- ### Cosmos Fullnode Deployment Configuration Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/04-examples/cosmoshub/mainnet-fullnode.md Kubernetes YAML definition for a Cosmoshub mainnet fullnode. Includes image, genesis URL, chain ID, node count, persistence, and app.toml overrides for gas prices and pruning. ```yaml apiVersion: apps.k8s.nibiru.org/v1 kind: ChainNodeSet metadata: name: cosmos spec: app: image: ghcr.io/cosmos/gaia version: v25.2.0 app: gaiad genesis: url: https://github.com/osmosis-labs/networks/raw/main/osmosis-1/genesis.json chainID: cosmoshub-4 useDataVolume: true nodes: - name: fullnodes instances: 1 persistence: size: 100Gi initTimeout: 30m additionalInitCommands: - image: ghcr.io/nibiruchain/node-tools command: [ "sh" ] args: - "-c" - | SNAPSHOT_URL="https://storage1.quicksync.io/cosmos/mainnet/daily/latest.tar.zst" && \ echo "Downloading snapshot: $SNAPSHOT_URL" && \ wget -qO- "$SNAPSHOT_URL" | zstd -d | tar -C /home/app -xvf - config: volumes: - name: wasm size: 1Gi path: /home/app/wasm deleteWithNode: true override: app.toml: minimum-gas-prices: 0.025uatom pruning: custom pruning-keep-recent: "100" pruning-interval: "10" ``` -------------------------------- ### Apply and Monitor State Sync Node Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Apply the state-sync node configuration using kubectl and monitor its progress. The node status will change from 'StateSyncing' to 'Running' as it catches up. ```bash # Apply state-sync node kubectl apply -f statesync-node.yaml # Monitor state-sync progress kubectl get chainnode new-fullnode -w # NAME STATUS IP VERSION CHAINID LATESTHEIGHT # new-fullnode StateSyncing 10.8.5.50 1.0.0 cataclysm-1 0 # new-fullnode Running 10.8.5.50 1.0.0 cataclysm-1 17849600 ``` -------------------------------- ### Cosmos Testnet Fullnode Configuration Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/04-examples/cosmoshub/testnet-with-fullnode.md Defines the deployment of a Cosmos testnet fullnode with specific application, validator, and node configurations. Includes settings for image, version, gas prices, pruning, and initialization commands. ```yaml apiVersion: apps.k8s.nibiru.org/v1 kind: ChainNodeSet metadata: name: cosmos-testnet spec: app: image: ghcr.io/cosmos/gaia version: v25.2.0 app: gaiad sdkVersion: v0.47 validator: info: moniker: cosmopilot config: volumes: - name: wasm size: 1Gi path: /home/app/wasm deleteWithNode: true override: app.toml: minimum-gas-prices: 0.025uatom init: chainID: cosmos-hub-0 assets: ["1000000000000000000uatom"] stakeAmount: 100000000uatom minSelfDelegation: "" accountPrefix: cosmos valPrefix: cosmosvaloper additionalInitCommands: # Use uATOM as default denom - image: busybox command: [ "sh", "-c" ] args: - > sed -i 's/stake/uatom/g' /home/app/config/genesis.json; sed -i 's/uatomrs/stakers/g' /home/app/config/genesis.json; sed -i 's/uatomd/staked/g' /home/app/config/genesis.json; nodes: - name: fullnodes instances: 1 config: override: app.toml: minimum-gas-prices: 0.025uatom pruning: custom pruning-keep-recent: "100" pruning-interval: "10" ``` -------------------------------- ### PdbConfig Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/03-reference/crds/crds.md PdbConfig defines the configuration for a Pod Disruption Budget. ```APIDOC ## PdbConfig PdbConfig configures the Pod Disruption Budget for a pod. ### Fields - **enabled** (bool) - Required - Enabled specifies whether to deploy a Pod Disruption Budget. - **minAvailable** (*int) - Optional - MinAvailable indicates minAvailable field set in PDB. Defaults to the number of instances in the group minus 1, i.e. it allows only a single disruption. ``` -------------------------------- ### ExposeConfig Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/03-reference/crds/crds.md Configuration for exposing P2P endpoints. ```APIDOC ## ExposeConfig ### Description Allows configuring how P2P endpoint is exposed to public. ### Request Body - **p2p** (*bool) - Optional - Whether to expose p2p endpoint for this node. - **p2pServiceType** (*corev1.ServiceType) - Optional - P2pServiceType indicates how P2P port will be exposed. - **annotations** (map[string]string) - Optional - Annotations to be appended to the p2p service. ``` -------------------------------- ### Provide Validator Information Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/10-initializing-new-network.md Includes validator metadata such as moniker and website alongside standard initialization parameters. ```yaml validator: info: moniker: nibiru website: https://nibiru.fi init: chainID: my-testnet-1 stakeAmount: "1000000unibi" assets: - "100000000unibi" - "500000000uusdt" ``` -------------------------------- ### Enable EVM support Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/04-node-config.md Enables EVM RPC ports for the node service. ```yaml evmEnabled: true ``` -------------------------------- ### Configure node-utils Resources Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/04-node-config.md Set resource requests and limits for the node-utils sidecar container. ```yaml config: nodeUtilsResources: requests: cpu: "300m" memory: "100Mi" limits: cpu: "300m" memory: "100Mi" ``` -------------------------------- ### CosmoseedConfig Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/03-reference/crds/crds.md Defines settings for deploying seed nodes via Cosmoseed, including enablement, instance count, and network configurations. ```APIDOC ## CosmoseedConfig ### Description Defines settings for deploying seed nodes via Cosmoseed. ### Fields - **enabled** (*bool) - Optional - Whether to enable deployment of Cosmoseed. If false or unset, no seed node instances will be created. - **instances** (*int) - Optional - Number of seed node instances to deploy. Defaults to 1. - **expose** (*[ExposeConfig](#exposeconfig)) - Optional - Configuration for exposing the P2P endpoint (e.g., via LoadBalancer or NodePort). - **resources** (corev1.ResourceRequirements) - Optional - Compute Resources to be applied on the cosmoseed container. - **allowNonRoutable** (*bool) - Optional - Used to enforce strict routability rules for peer addresses. Set to false to only accept publicly routable IPs (recommended for public networks). Set to true to allow local/private IPs (e.g., in testnets or dev environments). Defaults to `false`. - **maxInboundPeers** (*int) - Optional - Maximum number of inbound P2P connections. Defaults to `2000`. - **maxOutboundPeers** (*int) - Optional - Maximum number of outbound P2P connections. Defaults to `20`. - **peerQueueSize** (*int) - Optional - Size of the internal peer queue used by dial workers in the PEX reactor. This queue holds peers to be dialed; dial workers consume from it. If the queue is full, new discovered peers may be discarded. Use together with `DialWorkers` to control peer discovery throughput. Defaults to `1000`. - **dialWorkers** (*int) - Optional - Number of concurrent dialer workers used for outbound peer discovery. Each worker fetches peers from the queue (`PeerQueueSize`) and attempts to dial them. Higher values increase parallelism, but may increase CPU/network load. Defaults to `20`. - **maxPacketMsgPayloadSize** (*int) - Optional - Maximum size (in bytes) of packet message payloads over P2P. Defaults to `1024`. - **additionalSeeds** (*string) - Optional - Additional seed nodes to append to the node’s default seed list. Comma-separated list in the format `nodeID@ip:port`. - **logLevel** (*string) - Optional - Log level of cosmoseed. Defaults to `info`. - **ingress** (*[CosmoseedIngressConfig](#cosmoseedingressconfig)) - Optional - Ingress configuration for cosmoseed nodes. ``` -------------------------------- ### Enable Seed Mode Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/04-node-config.md Toggle seed mode for the node. ```yaml config: seedMode: true ``` -------------------------------- ### Generate Genesis Transaction (SDK v0.47+) Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/01-getting-started/02-chain-compatibility.md Generates a genesis transaction for SDK v0.47+. Requires account, stake amount, moniker, chain ID, and home path. Optional flags for commission and validator details are available. ```bash genesis gentx \ --moniker \ --chain-id \ --keyring-backend test \ --yes \ [--commission-max-change-rate ] \ [--commission-max-rate ] \ [--commission-rate ] \ [--min-self-delegation ] \ [--details
] \ [--website ] \ [--identity ] \ --home ``` -------------------------------- ### Deploy Seed Nodes with Cosmoseed Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Configure seed node parameters within a ChainNodeSet to facilitate peer discovery. ```yaml apiVersion: apps.k8s.nibiru.org/v1 kind: ChainNodeSet metadata: name: nibiru-mainnet spec: app: app: nibid image: ghcr.io/nibiruchain/nibiru version: 1.0.0 genesis: url: https://example.com/genesis.json nodes: - name: fullnode instances: 3 # Cosmoseed configuration cosmoseed: enabled: true instances: 2 # Number of seed nodes allowNonRoutable: false # Only accept public IPs (recommended) maxInboundPeers: 2000 # Max inbound connections maxOutboundPeers: 20 # Max outbound connections peerQueueSize: 1000 # Internal peer queue size dialWorkers: 20 # Concurrent dial workers logLevel: info # P2P exposure expose: p2p: true p2pServiceType: LoadBalancer # HTTP ingress for monitoring ingress: host: seeds.example.com ingressClass: nginx resources: requests: cpu: "100m" memory: "256Mi" ``` -------------------------------- ### Monitor VPA Status via kubectl Source: https://context7.com/nibiruchain/cosmopilot/llms.txt Use standard kubectl commands to inspect VPA events and current resource allocations. ```bash # Monitor VPA events kubectl describe chainnode autoscaling-node | grep -A5 "Events:" # Check current resource allocation kubectl get pod -l app.kubernetes.io/instance=autoscaling-node -o jsonpath='{.items[0].spec.containers[0].resources}' ``` -------------------------------- ### Define a ChainNode manifest Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/01-deploy-node.md Base YAML configuration for deploying a Nibiru node, specifying the application image, genesis URL, and network peers. ```yaml apiVersion: apps.k8s.nibiru.org/v1 kind: ChainNode metadata: name: nibiru-cataclysm-1-fullnode spec: app: app: nibid # Binary to be used image: ghcr.io/nibiruchain/nibiru # Container image repository of the application version: 1.0.0 # Version to be used genesis: url: https://raw.githubusercontent.com/NibiruChain/Networks/refs/heads/main/Mainnet/cataclysm-1/genesis.json peers: - id: 151acb0de556f4a059f9bd40d46190ee91f06422 address: 34.38.151.176 - id: d3c7f343d7ed815b73eef34d7d37948f10a1deab address: 34.76.80.206 - id: 36a232cf6a3fb166750f003e3abd5249e86aeed8 address: 15.235.115.154 port: 16700 - id: 98cadded622d291141f8a83972fa046267df94b6 address: 38.109.200.36 port: 44441 - id: d2c01f9aee9fedbd9e14c42fff5179d7f53f72f9 address: 174.138.180.190 port: 60656 - id: 8d8324141897243927359345bb4b1bb78a1e1df1 address: 65.109.56.235 ``` -------------------------------- ### Handle Governance Upgrades Without Images Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/08-upgrades.md When a governance upgrade lacks a container image, manually add it using this configuration and set `forceOnChain` to `true`. This integrates the manual entry into the governance process. ```yaml app: upgrades: - height: 3000 image: yourimage:yourtag forceOnChain: true # Optional. Use only for governance upgrades. ``` -------------------------------- ### Port-forward to Node Services Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/01-deploy-node.md Use `kubectl port-forward` to expose node endpoints like RPC, LCD, and gRPC locally. Ensure the service name and ports match your deployment. ```bash kubectl port-forward svc/nibiru-cataclysm-1-fullnode-internal 26657 1317 9090 ``` -------------------------------- ### Create Vault Token with Policy Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/11-tmkms.md Generate a Vault token with the specified policy and set it as a Kubernetes secret for Cosmopilot. ```bash $ export KEY=my-consensus-key $ vault token create \ -policy=$KEY \ -no-default-policy \ -non-interactive \ -period=10d ``` ```bash $ export VAULT_TOKEN= $ kubectl create secret generic vault --from-literal=token=$VAULT_TOKEN ``` -------------------------------- ### Enable Cosmoseed in ChainNodeSet Source: https://github.com/nibiruchain/cosmopilot/blob/main/docs/02-usage/13-cosmoseed.md Configure the cosmoseed section within a ChainNodeSet to deploy seed nodes with optional P2P exposure and HTTP ingress. ```yaml cosmoseed: enabled: true instances: 2 # optional, defaults to 1 allowNonRoutable: true # optional, defaults to false expose: # optional P2P exposure p2p: true p2pServiceType: LoadBalancer ingress: # optional HTTP ingress for monitoring host: seeds.example.com ingressClass: nginx # optional, defaults to nginx ```