feat(docs): new node operator documentation

README.md

@@ -1 +1,99 @@
-# TSN Node Operator
+# 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 <your-public-key> --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.

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"
+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"

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/<network_name>` 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_name>/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
+```