diff --git a/README.md b/README.md index 8e3dc13..e0277cd 100644 --- a/README.md +++ b/README.md @@ -1 +1,99 @@ -# TSN Node Operator \ No newline at end of file +# TSN Node Operator Guide + +This guide will walk you through the process of setting up and running a Truflation Stream Network (TSN) node. By following these steps, you'll be able to deploy a node, optionally become a validator, and contribute to the TSN. + +## Prerequisites + +Before you begin, ensure you have the following: + +1. **Kwil-admin**: Used to generate the initial configuration file. + - Download from the [latest GitHub release](https://github.com/kwilteam/kwil-db/releases) + +2. **Docker**: Required for running the PostgreSQL image. + - Install from [Docker's official website](https://docs.docker.com/get-docker/) + +3. **TSN Binaries**: Necessary for node deployment. + - Download from the [latest GitHub release](https://github.com/truflation/tsn-db/releases) + +## Setup Steps + +### 1. Generate Initial Configuration + +Use `kwil-admin` to create your initial configuration file. For example: + +```bash +kwil-admin setup peer \ + -g ./configs/network/staging/genesis.json \ + --root-dir ./my-peer-config/ \ + --chain.p2p.persistent-peers c6d2ea1e573d207cc31b7e17c771ab8ca2091b22@staging.node-1.tsn.test.truflation.com:26656,34599966ce4b67628f4cfa99fdca74ea2d039018@staging.node-2.tsn.test.truflation.com:26656 +``` + +For detailed instructions on these and other configuration options more relevant to a production setup, refer to our [Configuration Guide](docs/creating-config.md). + +### 2. Set Up PostgreSQL + +For a quick setup, run Kwil's pre-configured PostgreSQL Docker image: + +```bash +docker run -d -p 5432:5432 --name tsn-postgres \ + -e "POSTGRES_HOST_AUTH_METHOD=trust" \ + kwildb/postgres:latest +``` + +If you prefer a custom PostgreSQL setup, ensure it meets the requirements specified in the [configuration guide](https://docs.kwil.com/docs/daemon/running-postgres). + +### 3. Deploy TSN Node + +Run the TSN binaries to deploy your node: + +```bash +kwild --root-dir ./my-peer-config/ +``` + +Ensure your firewall allows incoming connections on the JSON-RPC port (default: 8484) and P2P port (default: 26656). + +### 4. Become a Validator (Optional) + +To upgrade your node to a validator: + +1. Ensure your node is fully synced with the network. +2. Submit a validator join request: + + ```bash + kwil-admin validators join --rpcserver /path/to/your/node.sock + ``` + +3. Wait for approval from existing validators. You can check your join request status with: + + ```bash + kwil-admin validators join-status --rpcserver /path/to/your/node.sock + ``` + +You can always ping us for help in the validator process. + +### 5. Submit Your Node to Available Node List (Optional) + +To help others discover your node: + +1. Fork the TSN repository. +2. Add your node information to the `configs/network/available_nodes.json` file. +3. Submit a Pull Request with your changes. + +We'll review and merge your PR to include your node in the network's seed list. + +## Network Configuration Files + +Essential network configuration files are located in the `configs/network/` directory: + +- `genesis.json`: The network's genesis file. +- `network-nodes.csv`: List of available nodes for peer discovery. + +When setting up your node, refer to these files for network-specific parameters and peer information. + +## Additional Resources + +- [Kwil Documentation](https://docs.kwil.com) + +For further assistance, join our [Discord community](https://discord.com/invite/5AMCBYxfW4) or open an issue on our [GitHub repository](https://github.com/truflation/tsn-node-operator/issues). + +Welcome to the Truflation Stream Network! Your participation helps build a more robust and decentralized data infrastructure. diff --git a/configs/network/staging/network-nodes.csv b/configs/network/staging/network-nodes.csv index e1464c3..aa47274 100644 --- a/configs/network/staging/network-nodes.csv +++ b/configs/network/staging/network-nodes.csv @@ -1,3 +1,3 @@ -node_name,owner_title,owner_website,node_pubkey,p2p_rpc_endpoint -"Truflation Node 01","Truflation","https://truflation.com","4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1","https://staging.node-1.tsn.truflation.com:26656" -"Truflation Node 02","Truflation","https://truflation.com","0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae","https://staging.node-2.tsn.truflation.com:26656" \ No newline at end of file +node_name,owner_title,owner_website,node_pubkey,node_cometbft_id,p2p_rpc_endpoint +"Truflation Node 01","Truflation","https://truflation.com","4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1","c6d2ea1e573d207cc31b7e17c771ab8ca2091b22","http://staging.node-1.tsn.test.truflation.com:26656" +"Truflation Node 02","Truflation","https://truflation.com","0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae","34599966ce4b67628f4cfa99fdca74ea2d039018","http://staging.node-2.tsn.test.truflation.com:26656" diff --git a/docs/creating-config.md b/docs/creating-config.md new file mode 100644 index 0000000..6329191 --- /dev/null +++ b/docs/creating-config.md @@ -0,0 +1,111 @@ +# TSN Node Configuration Guide + +This guide outlines essential configurations for TSN Node operators. We'll use `kwil-admin` to generate the initial configuration file. + +## 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" \ + kwildb/postgres:latest +``` + +## Network Configuration + +### Genesis File + +``` +-g, --genesis string Path to genesis file +``` + +You should use this option to specify the genesis file provided in the `configs/network/` directory of the tsn-node-operator repository. This is crucial for joining the correct network. + +- The genesis file is mandatory for joining an existing TSN network. +- It defines the initial state of the blockchain, including initial validators and other network parameters. +- Using the correct genesis file ensures your node starts with the same state as other nodes in the network. + +Example usage: + +```bash +kwil-admin setup peer -g ./configs/network/staging/genesis.json \ + --chain.p2p.persistent-peers c6d2ea1e573d207cc31b7e17c771ab8ca2091b22@staging.node-1.tsn.test.truflation.com:26656,34599966ce4b67628f4cfa99fdca74ea2d039018@staging.node-2.tsn.test.truflation.com:26656 \ + [other options] +``` + +### Listening Addresses + +``` +--app.jsonrpc-listen-addr string JSON-RPC listen address (default "0.0.0.0:8484") +--chain.p2p.listen-addr string P2P listen address (default "tcp://0.0.0.0:26656") +--chain.p2p.external-address string P2P external address for peer advertising +--app.hostname string Server hostname for RPC endpoint +``` + +Important: +- Open the JSON-RPC port (8484) and P2P port (26656) in your firewall. +- Ensure the P2P external address is reachable by other peers. +- `hostname` and `p2p.external-address` can be the same or different based on your setup. + +### Peer Configuration + +``` +--chain.p2p.persistent-peers string Persistent P2P peers +--chain.p2p.seeds string Seed nodes for peer discovery +``` + +Recommendations: +- Set critical nodes as persistent peers for constant connectivity. We recommend that you add our TSN nodes as persistent peers. + For example: `--chain.p2p.persistent-peers c6d2ea1e573d207cc31b7e17c771ab8ca2091b22@staging.node-1.tsn.test.truflation.com:26656,34599966ce4b67628f4cfa99fdca74ea2d039018@staging.node-2.tsn.test.truflation.com:26656` +- Use the node list provided in `configs/network//network-nodes.csv` as seeds for initial peer discovery + +### Custom Database Configuration + +If using a custom PostgreSQL setup, configure these parameters: + +``` +--app.pg-db-host string PostgreSQL host address (default "127.0.0.1") +--app.pg-db-name string Database name (default "kwild") +--app.pg-db-pass string Database password +--app.pg-db-port string Database port (default "5432") +--app.pg-db-user string Database user name (default "kwild") +``` + +## Additional Configuration + +``` +--app.db-read-timeout duration Database read timeout (recommended: 60s, default: 5s) +-r, --root-dir string Kwild root directory (default "~/.kwild") +``` + +We recommend a 60s timeout due to the potentially long execution time of deeply nested TSN queries. The configuration file will be generated in the specified root directory. + +For a complete list of options: +- Refer to the [Kwil documentation](https://docs.kwil.com) +- Run `kwil-admin --help` + +After generating the configuration, you can manually edit the file for further customization. + +## Generating the Configuration + +Use `kwil-admin` to generate your configuration file: + +```bash +kwil-admin setup peer [flags] +``` + +Replace `[flags]` with the desired configuration options from this guide. + +Remember to review and adjust these settings based on your specific requirements and infrastructure. + +## Example Configuration + +```bash +kwil-admin setup peer \ + -g ./configs/network/staging/genesis.json \ + --chain.p2p.persistent-peers c6d2ea1e573d207cc31b7e17c771ab8ca2091b22@staging.node-1.tsn.test.truflation.com:26656,34599966ce4b67628f4cfa99fdca74ea2d039018@staging.node-2.tsn.test.truflation.com:26656 + --app.hostname mynode.mycompany.com \ + --chain.p2p.external-address http://mynode.mycompany.com:26656 \ + --root-dir ./tsn-config \ + --app.db-read-timeout 60s +``` \ No newline at end of file