From 2d148e1d8f8d73f31e7da38da266eb8d631e601c Mon Sep 17 00:00:00 2001
From: Chris Gianelloni <wolf31o2@blinklabs.io>
Date: Sun, 30 Mar 2025 11:51:45 -0400
Subject: [PATCH] docs(readme): running section

Signed-off-by: Chris Gianelloni <wolf31o2@blinklabs.io>
---
 README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 64 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index e6f44dcf..1a59a33a 100644
--- a/README.md
+++ b/README.md
@@ -11,12 +11,68 @@
 
 # Dingo
 
-This is a work in progress and is currently under heavy development
+⚠️ This is a work in progress and is currently under heavy development
 
 <div align="center">
   <img src="./.github/dingo-20241210.png" alt="dingo screenshot" width="640">
 </div>
 
+## Running
+
+Dingo does not support a configuration file of its own and uses environment
+variables to modify its own behavior.
+
+This behavior can be changed via the following environment variables:
+
+- `CARDANO_BIND_ADDR`
+  - IP address to bind for listening (default: `0.0.0.0`)
+- `CARDANO_CONFIG`
+  - Full path to the Cardano node configuration (default:
+    `./config/cardano/preview/config.json`)
+  - Use your own configuration files for different networks
+  - Genesis configuration files are read from the same directory by default
+- `CARDANO_DATABASE_PATH`
+  - A directory which contains the ledger database files (default:
+    `.dingo`)
+  - This is the location for persistent data storage for the ledger
+- `CARDANO_INTERSECT_TIP`
+  - Ignore prior chain history and start from current position (default:
+    `false`)
+  - This is experimental and will likely break... use with caution
+- `CARDANO_METRICS_PORT`
+  - TCP port to bind for listening for Prometheus metrics (default: `12798`)
+- `CARDANO_NETWORK`
+  - Named Cardano network (default: `preview`)
+- `CARDANO_PRIVATE_BIND_ADDR`
+  - IP address to bind for listening for Ouroboros NtC (default:
+    `127.0.0.1`)
+- `CARDANO_PRIVATE_PORT`
+  - TCP port to bind for listening for Ouroboros NtC (default: `3002`)
+- `CARDANO_RELAY_PORT`
+  - TCP port to bind for listening for Ouroboros NtN (default: `3001`)
+- `CARDANO_SOCKET_PATH`
+  - UNIX socket path for listening (default: `dingo.socket`)
+  - This socket speaks Ouroboros NtC and is used by client software
+- `CARDANO_TOPOLOGY`
+  - Full path to the Cardano node topology (default: "")
+- `CARDANO_UTXORPC_PORT`
+  - TCP port to bind for listening for UTxO RPC (default: `9090`)
+- `TLS_CERT_FILE_PATH` - SSL certificate to use, requires `TLS_KEY_FILE_PATH`
+    (default: empty)
+- `TLS_KEY_FILE_PATH` - SSL certificate key to use (default: empty)
+
+### Example
+
+Running on mainnet (:sweat_smile:):
+
+```bash
+CARDANO_NODE=mainnet ./dingo
+```
+
+Dingo will drop a `dingo.socket` file which can be used by other clients, such
+as `cardano-cli` or software like `adder` or `kupo`. This has only had limited
+testing, so success/failure reports are very welcome and encouraged!
+
 ## Features
 
 - [x] Network
@@ -52,7 +108,9 @@ This is a work in progress and is currently under heavy development
     - [x] Pool registration
     - [x] Stake registration/delegation
     - [ ] Governance
-  - [x] Transaction validation
+  - [ ] Transaction validation
+    - [x] UTxO rules
+    - [ ] Smart contracts
 - [x] Mempool
   - [x] Accept transactions from local clients
   - [x] Distribute transactions to other nodes
@@ -65,9 +123,12 @@ Additional planned features can be found in our issue tracker and project boards
 [Catalyst Fund 12 - Go Node (Dingo)](https://github.com/orgs/blinklabs-io/projects/16)<br/>
 [Catalyst Fund 13 - Archive Node](https://github.com/orgs/blinklabs-io/projects/17)
 
+Check the issue tracker for known issues. Due to rapid development, bugs happen
+especially as there is functionality which has not yet been developed.
+
 ## Development / Building
 
-This requires Go 1.22 or better is installed. You also need `make`.
+This requires Go 1.23 or better is installed. You also need `make`.
 
 ```bash
 # Build