From b7c5fd3859f47e32b404a31083398cd89957e041 Mon Sep 17 00:00:00 2001 From: Michael Buntarman Date: Wed, 28 May 2025 01:27:39 +0700 Subject: [PATCH] docs: reveal TRUF.NETWORK node to discover and detailed guide --- README.md | 92 ++++++++++++++++++++++++---- configs/network/v2/network-nodes.csv | 6 +- docs/creating-config.md | 61 +++++++++++++++--- 3 files changed, 134 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 2450ee7..b0e6610 100644 --- a/README.md +++ b/README.md @@ -23,43 +23,95 @@ Use `kwild` to create your initial configuration file: ```bash kwild setup init \ - -g ./configs/network/v2/genesis.json \ - --root-dir ./my-node-config/ \ - --p2p.bootnodes "" + --genesis ./configs/network/v2/genesis.json \ + --root ./my-node-config \ + --p2p.bootnodes "4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1#ed25519@node-1.mainnet.truf.network:26656,0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656" ``` For detailed instructions on configuration options more relevant to a production setup, refer to our [Configuration Guide](docs/creating-config.md). -### 2. Set Up PostgreSQL +### 2. Enable State Sync + +Edit the `config.toml` file in your node configuration directory to enable state sync. The following example assumes you used `./my-node-config` as your root directory in the previous step. Adjust the path if you used a different directory: + +```bash +# Edit the config.toml file +sed -i '/\[state_sync\]/,/^\[/ s/enable = false/enable = true/' ./my-node-config/config.toml +sed -i 's/trusted_providers = \[\]/trusted_providers = ["0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656"]/' ./my-node-config/config.toml +``` + +This will configure your node to use state sync for faster synchronization with the network. + +### 3. Set Up PostgreSQL For a quick setup, run Kwil's pre-configured PostgreSQL Docker image: ```bash docker run -d -p 5432:5432 --name tn-postgres \ -e "POSTGRES_HOST_AUTH_METHOD=trust" \ - -v postgres_data:/var/lib/postgresql/data \ + -v tn-pgdata:/var/lib/postgresql/data \ + --shm-size=1gb \ kwildb/postgres:latest ``` +The command above: +- `-v tn-pgdata:/var/lib/postgresql/data`: Creates a persistent volume named 'tn-pgdata' to store database data +- `--shm-size=1gb`: Allocates 1GB of shared memory for PostgreSQL operations (recommended for better performance) + +#### Installing pg_dump for Snapshots + +To enable state sync functionality, you'll need `pg_dump` installed. Here's how to install it: + +For Ubuntu/Debian: +```bash +sudo apt-get update +sudo apt-get install postgresql-client-16 +``` + +For CentOS/RHEL: +```bash +sudo yum install postgresql16 +``` + +For macOS (using Homebrew): +```bash +brew install postgresql@16 +``` + +Verify the installation: +```bash +pg_dump --version +``` + +This should show PostgreSQL version 16.x.x. The `pg_dump` utility is required for creating and restoring database snapshots during state sync. + If you prefer a custom PostgreSQL setup, ensure it meets the requirements specified in the [Kwil documentation](https://docs.kwil.com/docs/daemon/running-postgres). -**Security Warning**: Do not expose port 5432 publicly and make sure to set passwords for your database in production environments. +**Security Warning**: It is recommended to not expose port 5432 publicly in production environments. -### 3. Deploy TN Node +### 4. Deploy TN Node Run the kwild binary to deploy your node: ```bash -kwild start --root-dir ./my-node-config/ --statesync.enable=true --statesync.trusted_providers='revealed-soon' +kwild start -r ./my-node-config ``` +You can run kwild in the background by adding `&` at the end of the command: + +```bash +kwild start -r ./my-node-config & +``` + +This allows you to run other kwild commands in the same terminal session, such as checking node status or managing validators. + Ensure your firewall allows incoming connections on: -- JSON-RPC port (default: 8484) +- JSON-RPC port (default: 8484) - P2P port (default: 6600) The `--statesync.enable` and `--statesync.trusted_providers` flags are optional and will help your node sync faster with the network using snapshots provided by the RPC servers. -### 4. Verify Node Synchronization +### 5. Verify Node Synchronization Before proceeding to become a validator, ensure your node is fully synced with the network: @@ -69,7 +121,7 @@ kwild admin status Look for the `syncing: false` in the output, and check that your `best_block_height` is close to the current network height. -### 5. Become a Validator (Optional) +### 6. Become a Validator (Optional) To upgrade your node to a validator: @@ -92,9 +144,23 @@ Existing validators must approve your request. For each existing validator neede kwild validators approve ``` +The node ID format for validator operations is: `#`. For example: +```bash +kwild validators approve 03dbe22b9922b5c0f8f60c230446feaa1c132a93caa9dae83b5d4fab16c3404a22#secp256k1 +``` + +You can find your node's public key and key type by running: +```bash +kwild key info --key-file ./my-node-config/nodekey.json +``` + +Note: If you used a different directory name during setup (not `./my-node-config`), replace the path with your actual node configuration directory path. + +This will show your node's public key and key type, which you'll need for validator operations. + You can always reach out to the community for help with the validator process. -### 6. Submit Your Node to Available Node List (Optional) +### 7. Submit Your Node to Available Node List (Optional) To help others discover your node: @@ -119,7 +185,7 @@ Node IDs in TRUF.NETWORK follow the format: `#@#@:` + +You can find your node's public key and key type by running: +```bash +kwild key info --key-file ./your-config-dir/nodekey.json +``` + +Note: Replace `./your-config-dir` with your actual node configuration directory path. + ## Database Configuration Kwil provides a pre-configured PostgreSQL Docker image for quick setup: ```bash -docker run -p 5432:5432 --name kwil-postgres -e "POSTGRES_HOST_AUTH_METHOD=trust" \ - -v postgres_data:/var/lib/postgresql/data \ +docker run -p 5432:5432 --name tn-postgres -e "POSTGRES_HOST_AUTH_METHOD=trust" \ + -v tn_data:/var/lib/postgresql/data \ kwildb/postgres:latest ``` +### Installing pg_dump for State Sync + +State sync functionality requires the `pg_dump` utility for creating and restoring database snapshots. Here's how to install it: + +For Ubuntu/Debian: +```bash +sudo apt-get update +sudo apt-get install postgresql-client-16 +``` + +For CentOS/RHEL: +```bash +sudo yum install postgresql16 +``` + +For macOS (using Homebrew): +```bash +brew install postgresql@16 +``` + +Verify the installation: +```bash +pg_dump --version +``` + +This should show PostgreSQL version 16.x.x. The `pg_dump` utility is essential for: +- Creating database snapshots for state sync +- Restoring snapshots during node synchronization +- Ensuring consistent state across the network + ## Network Configuration ### Genesis File @@ -29,8 +70,9 @@ You should use this option to specify the genesis file provided in the `configs/ Example usage: ```bash -kwild setup init -g ./configs/network/v2/genesis.json \ - --p2p.bootnodes "" \ +kwild setup init -genesis ./configs/network/v2/genesis.json \ + --p2p.bootnodes "4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1#ed25519@node-1.mainnet.truf.network:26656,0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656" \ + --root ./my-node-config \ [other options] ``` @@ -55,9 +97,10 @@ Important: Recommendations: - Set critical nodes as bootnodes for initial network connection. We recommend that you add our TN nodes as bootnodes. - For example: `--p2p.bootnodes "revealed-soon"` + For example: `--p2p.bootnodes "4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1#ed25519@node-1.mainnet.truf.network:26656,0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656"` - Use the node list provided in `configs/network/v2/network-nodes.csv` as seeds for initial peer discovery - Configure trusted providers for state sync using `--statesync.trusted_providers` with node IDs from `configs/network/v2/network-nodes.csv` +- When specifying node IDs for peer connections, always use the full format: `#@:` ### Custom Database Configuration @@ -101,9 +144,9 @@ Remember to review and adjust these settings based on your specific requirements ```bash kwild setup init \ - -g ./configs/network/v2/genesis.json \ - --p2p.bootnodes "revealed-soon" \ - --p2p.external_address mynode.mycompany.com:port \ + -genesis ./configs/network/v2/genesis.json \ + --p2p.bootnodes "4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1#ed25519@node-1.mainnet.truf.network:26656,0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656" \ --root ./tn-config \ - --db.read_timeout 60s ``` + +Note: In the example above, the bootnode is specified using the full node ID format (`#@:`).