Add Node Ecosystem documentation and assets

SUMMARY.md

@@ -74,6 +74,12 @@
     * [COTI Starter Grant](private-messaging/skills/coti-starter-grant.md)
 * [Running a COTI Node](running-a-coti-node/README.md)
   * [COTI Node Ecosystem Litepaper](running-a-coti-node/coti-node-ecosystem-litepaper.md)
+* [Node Ecosystem](node-ecosystem/README.md)
+  * [Features](node-ecosystem/features.md)
+  * [Installation](node-ecosystem/installation.md)
+  * [UI Guide](node-ecosystem/ui-guide.md)
+  * [Backend Services](node-ecosystem/backend-services.md)
+  * [Glossary](node-ecosystem/glossary.md)
 * [COTI Bridge](coti-bridge/README.md)
   * [Swap COTI V1 Funds to COTI V2](coti-bridge/swap-coti-v1-funds-to-coti-v2.md)
 * [Support and Community](support-and-community/README.md)

node-ecosystem/README.md

@@ -0,0 +1,78 @@
+# Node Ecosystem
+
+The **COTI Node Ecosystem** is the product surface that lets anyone run, monitor, and earn rewards from a COTI full node. It is composed of:
+
+* a web app that guides operators from zero to a live, reward-eligible node (see [Networks](#networks) below for the URLs),
+* an automated installer that stands up a COTI full node on Ubuntu 24.04 LTS in a single command,
+* a set of backend services that discover peers, mint node NFTs, monitor uptime, and distribute rewards each epoch.
+
+This section documents the product — what it does, how to install a node through it, how its UI is organized, and the terminology you will encounter along the way.
+
+## Networks
+
+The ecosystem runs on two networks. All guidance in this section applies to both unless noted; look up the right URL or value in the table below.
+
+| | **Testnet** | **Mainnet** |
+|---|---|---|
+| Web app | [dev.nodes.coti.io](https://dev.nodes.coti.io) | [nodes.coti.io](https://nodes.coti.io) |
+| Status page (public, hot nodes) | [testnet.uptime.coti.io](https://testnet.uptime.coti.io) | [uptime.coti.io](https://uptime.coti.io) |
+| Recommended node disk space | ≥ 100 GB | ≥ 700 GB |
+| Installer host | `fullnode.testnet.coti.io` | `fullnode.mainnet.coti.io` |
+
+The **status page** is the public [Better Stack](https://betterstack.com/) dashboard where every hot node's monitor is visible. It is the fastest way to eyeball the current health of the whole fleet.
+
+{% hint style="info" %}
+If you are looking for the protocol-level **Running a COTI Node** guide (hardware specs, manual Docker flow, ports, FAQ), see [**Running a COTI Node**](../running-a-coti-node/README.md). The current section focuses on the managed, UI-driven experience and the ecosystem that surrounds it.
+{% endhint %}
+
+## What the COTI Node Ecosystem gives you
+
+* **One-command install** of a COTI full node on a certified OS (Ubuntu 24.04 LTS) with HTTPS and a proxy already configured.
+* **Live visibility** into the node fleet — Who is online, which nodes are hot, how many earned rewards this epoch.
+* **Per-operator dashboard** for your own node(s): thermal state, uptime, latency, rewards history, eligibility.
+* **Automatic monitoring registration** in Better Stack once your node is recognized by the network.
+* **Rewards distribution** every epoch to operators who meet the eligibility rules (holdings + uptime).
+
+## High-level architecture
+
+```mermaid
+flowchart LR
+    Operator([Node operator])
+    UI["COTI Nodes web app"]
+    FullNode["COTI full node<br/>(operator server)"]
+    PDS["Peer Discovery"]
+    NFT["NFT service"]
+    BSI["Better Stack integration"]
+    NHM["Node Health Monitor"]
+    NRS["Node Rewards"]
+    BetterStack[(Better Stack)]
+    Chain[(COTI network)]
+
+    Operator -->|guided setup| UI
+    UI -->|one-liner installer| FullNode
+    FullNode -->|admin_peers, eth_blockNumber| PDS
+    PDS -->|"hot event"| NFT
+    NFT -->|mint Soulbound NFT| Chain
+    NFT --> BSI
+    BSI -->|register monitor via FQDN| BetterStack
+    BetterStack -->|probe RPC over HTTPS| NHM
+    NHM -->|health check| FullNode
+    NRS -->|read uptime + holdings| BetterStack
+    NRS -->|distribute rewards per epoch| Chain
+    UI -->|read stats + per-node data| PDS
+    UI --> NFT
+    UI --> BSI
+    UI --> NRS
+```
+
+{% hint style="warning" %}
+**A valid DNS (FQDN) is required to earn rewards.** The ecosystem measures your node's uptime by reaching its JSON-RPC endpoint through the domain name you configure. A node without a reachable DNS can still sync the chain, but it will **not** be credited with uptime and therefore will **not** receive rewards. See [installation.md](installation.md) for DNS prerequisites.
+{% endhint %}
+
+## Where to go next
+
+* **[Features](features.md)** — everything the product does, end-to-end.
+* **[Installation](installation.md)** — what the automated installer does on your server, and the DNS/server requirements.
+* **[UI guide](ui-guide.md)** — a page-by-page tour of the web app, with focus on the spin-up flow and the warm-up period.
+* **[Backend services](backend-services.md)** — the five services behind the ecosystem, described from an operator's perspective.
+* **[Glossary](glossary.md)** — thermal states, NFT states, warm-up windows, eligibility, and other terms you will see in the UI.

node-ecosystem/backend-services.md

@@ -0,0 +1,124 @@
+# Backend services
+
+The ecosystem is powered by five cooperating backend services. Operators do not interact with them directly — the web app (see [Networks](README.md#networks) for URLs) is the only interface. This page describes each service from the operator's perspective: **what it does for you** and **what its outputs look like in the UI**.
+
+```mermaid
+flowchart LR
+    YourNode["Your full node<br/>(RPC over FQDN)"]
+    PDS["Peer Discovery"]
+    NFT["NFT Service"]
+    BSI["Better Stack integration"]
+    NHM["Node Health Monitor"]
+    NRS["Node Rewards"]
+    Chain[(COTI network)]
+    BetterStack[(Better Stack)]
+
+    YourNode -->|"admin_peers"| PDS
+    PDS -->|"node becomes hot"| NFT
+    NFT -->|"mint Soulbound NFT"| Chain
+    NFT -->|"hand off monitoring"| BSI
+    BSI -->|"register FQDN"| BetterStack
+    BetterStack -->|"probe RPC"| NHM
+    NHM -->|"health check"| YourNode
+    NRS -->|"record epoch rewards"| Chain
+    BetterStack --> NRS
+```
+
+## Peer Discovery Service
+
+**What it does for you**
+
+Peer Discovery is the service that first *sees* your node. It repeatedly calls `admin_peers` on a set of reference nodes and records which peers are currently connected. As soon as your node shows up in those responses, it is considered **online** in the ecosystem.
+
+Peer Discovery is also responsible for the **thermal state machine**:
+
+* While your node is newly online, it is **cold** with the NFT not yet minted — it is **warming up**.
+* Once it has been continuously present for enough time (`HOT_THRESHOLD_HOURS` out of a rolling `HOT_WINDOW_HOURS` window), it transitions to **hot** and triggers NFT minting.
+* If a hot node goes offline long enough (`COLD_THRESHOLD_HOURS` out of a `COLD_WINDOW_HOURS` window), it **cools down** back to cold and must warm up again.
+
+**Where it shows up in the UI**
+
+* The home-page **Live node heartbeats** counter.
+* The **Nodes** table's **Status** column (active / syncing / offline).
+* The **Warmup In Progress** card on `/my-nodes` during the warm-up period.
+* The **Thermal** state badge (warming up / hot / cooling down / cold) on internal views.
+
+## NFT Service
+
+**What it does for you**
+
+The NFT service receives the "this node is hot" event from Peer Discovery and mints a **Soulbound Node NFT** to the operator's wallet. The NFT is the on-chain proof that the node exists, who owns it, and what its name and image are.
+
+Because the NFT is soulbound, it cannot be transferred — it is bound to the wallet that set up the node. If an operator regenerates keys, a new NFT is minted to the new wallet; the old one is not reused.
+
+**Where it shows up in the UI**
+
+* The node name and avatar shown everywhere the node appears (dashboard, nodes table, node-details modal).
+* The **Edit Node** flow (`/edit-node`) where you rename your node — the name is stored on the NFT.
+* The "No Node Detected" / "Warmup Complete" states on `/my-nodes`, which depend on whether the NFT exists for the connected wallet.
+
+## Better Stack Integration Service
+
+**What it does for you**
+
+Once your node has an NFT, the Better Stack integration service automatically registers your node's `https://<your-fqdn>/rpc` URL with [Better Stack](https://betterstack.com/) as a monitored endpoint. From that point on, Better Stack polls your node on a regular cadence and records the results.
+
+The operator does not configure or pay for Better Stack — the ecosystem manages the monitor centrally.
+
+**Where it shows up in the UI**
+
+* The **all-time uptime percentage** displayed for your node in the dashboard and nodes table.
+* A public **status page** that aggregates every hot node's monitor state (up / down). The URL is listed in [Networks](README.md#networks).
+
+{% hint style="info" %}
+Because monitoring happens over HTTPS against your FQDN, a node without a valid DNS cannot be monitored — see [installation.md](installation.md) and the [Glossary](glossary.md) FQDN entry.
+{% endhint %}
+
+## Node Health Monitor
+
+**What it does for you**
+
+The Node Health Monitor is the health-check target that Better Stack calls. When Better Stack asks "is this node healthy?", the Node Health Monitor runs a **multi-signal health check** against the node's JSON-RPC through its FQDN and returns a single **healthy / failing** verdict.
+
+The check is designed so that simply answering RPC calls is **not** sufficient — the service confirms that the node is actually operating, not just reachable. Only healthy results accrue uptime; failures are recorded with a reason so operators can diagnose issues.
+
+**Where it shows up in the UI**
+
+* As the underlying cause of your **uptime percentage** each epoch.
+* As the difference between "your node is reachable" and "your node is actually operating" — a reachable-but-unhealthy node does not count as up.
+
+## Node Rewards Service
+
+**What it does for you**
+
+At the end of each **103-hour epoch**, the rewards service:
+
+1. Snapshots each node operator's USDC and COTI holdings.
+2. Reads each node's uptime for the epoch from the monitoring platform.
+3. Applies the eligibility rules: **uptime is mandatory**, and the operator must meet **at least one** of the USDC-holdings threshold **or** the COTI-holdings threshold (with whitelist overrides for specific operators).
+4. Allocates each eligible node its share of the epoch's reward pool in the on-chain **rewards smart contract**.
+5. Records the per-epoch result: earned amount, snapshot values, uptime %, eligibility.
+
+Rewards are **not** pushed to the operator's wallet automatically. Once the contract is credited, the operator claims the accrued balance via the **Claim Now** button on the **My Node** dashboard, or by calling the rewards smart contract directly from any wallet they control.
+
+**Where it shows up in the UI**
+
+* The home-page **Reward-eligible nodes (last epoch)** and **COTI dropped (last epoch)** cards.
+* The **Total COTI earned** card (cumulative).
+* The **Total Rewards** column in the nodes table.
+* The **Total Earned** and **Claim Now** controls in the My Node node-identity card.
+* The **Rewards History** table on `/my-nodes`, including USDC, COTI, earned, uptime %, and Eligible / Ineligible per epoch.
+
+## How they work together
+
+For a newly-installed node, the lifecycle is:
+
+1. **Install finishes** → node comes up at `https://<fqdn>/rpc`.
+2. **Peer Discovery** sees the node in `admin_peers` responses and starts tracking presence.
+3. **Warm-up period** — the UI shows a progress bar until `HOT_THRESHOLD_HOURS` of presence is reached.
+4. **Peer Discovery** declares the node **hot** → **NFT Service** mints the Soulbound NFT.
+5. **Better Stack Integration** registers the node's FQDN with **Better Stack**.
+6. **Better Stack** starts calling the **Node Health Monitor**, which runs the health check against the node's RPC through the FQDN.
+7. At epoch boundaries, **Node Rewards** reads uptime + holdings and credits eligible nodes in the rewards smart contract; the operator claims from the **My Node** dashboard or directly from the contract.
+
+The operator only ever touches the web app and their own server — the five services coordinate everything in between.

node-ecosystem/features.md

@@ -0,0 +1,75 @@
+# Features
+
+The COTI Node Ecosystem packages node operation into a small number of high-level features. Each one is surfaced in the web app (see [Networks](README.md#networks) for the testnet and mainnet URLs) and backed by one or more of the ecosystem services described in [backend-services.md](backend-services.md).
+
+## 1. Guided installation
+
+A step-by-step wizard at **`/setup`** takes an operator from a fresh Ubuntu server to a running, HTTPS-fronted COTI full node.
+
+* Generates (or accepts) a node private key locally — the key never leaves the browser.
+* Validates the node's **FQDN** via a live DNS lookup before continuing.
+* Produces a single-line installer command, tailored to the node's key and domain, that the operator runs as root on the target server.
+* Watches the peer-discovery network and advances automatically once the node is seen by peers.
+
+See [installation.md](installation.md) for what the installer does on the server, and [ui-guide.md](ui-guide.md) for the wizard walkthrough.
+
+## 2. Live ecosystem view
+
+The home page of the web app exposes the current state of the node network:
+
+* **Live node heartbeats** — a running count of nodes currently observed by peer discovery.
+* **Reward-eligible nodes (last epoch)** — how many nodes met the rules in the previous epoch.
+* **COTI dropped (last epoch)** — total rewards distributed in the previous epoch.
+* **Total COTI earned** — cumulative rewards paid to operators to date.
+* **Nodes table** — every node the system knows about, with operator name, total rewards, online status, uptime, and latency.
+
+This view is read-only and does not require a wallet connection.
+
+## 3. Per-operator dashboard
+
+Once an operator connects a wallet that owns a COTI Node NFT, **`/my-nodes`** becomes the per-operator dashboard:
+
+* Current node status (active / syncing / offline) and thermal state (warming up / hot / cooling down / cold).
+* **Warm-up progress bar** for nodes that have just been installed and are not yet hot.
+* All-time totals: uptime, rewards, latency.
+* Per-epoch rewards history with USDC/COTI snapshots, uptime, earned amount, and eligibility status.
+* Edit node flow for renaming the node (the name is stored on the Soulbound NFT).
+
+## 4. Eligibility checks
+
+Anyone can preview whether their wallet meets the reward rules before installing a node. For a node to be eligible in a given epoch **both** conditions below must hold:
+
+* **Uptime (mandatory).** The node's per-epoch uptime must be ≥ the configured percentage.
+* **Holdings (either threshold is enough).** The operator's wallet must meet **at least one** of the following:
+  * **USDC** holdings on COTI network ≥ the configured threshold, **or**
+  * **COTI** holdings ≥ the configured threshold (custodial and non-custodial wallets both count).
+
+The **`/eligibility`** page explains the rules in plain language; the home page exposes a quick "Check My Eligibility" button.
+
+## 5. Automatic uptime monitoring
+
+Once a node has been continuously seen by peer discovery for long enough to be considered **hot**, the ecosystem:
+
+1. Mints a Soulbound **Node NFT** to the operator's wallet.
+2. Registers the node's RPC URL with **Better Stack** as a monitored endpoint.
+3. Runs a multi-signal health check against the node's RPC **through its DNS** to confirm the node is actually operating — simply responding is not enough.
+4. Aggregates the resulting uptime per epoch and exposes it in the per-operator dashboard.
+
+{% hint style="warning" %}
+**Rewards require a valid DNS.** The ecosystem only measures uptime by calling the node's RPC through the FQDN the operator supplies during setup. A node without a reachable FQDN cannot be monitored and therefore cannot earn rewards — even if it is fully synced on the network.
+{% endhint %}
+
+The operator does not interact with Better Stack directly — monitoring is fully automatic. A **public status page** aggregates every hot node's monitor and is available at the URL listed in [Networks](README.md#networks).
+
+## 6. Rewards distribution
+
+Rewards are distributed each **epoch** (103 hours). At the end of every epoch, the rewards service:
+
+1. Reads the node's per-epoch uptime from the monitoring platform.
+2. Reads the operator's USDC and COTI holdings at the epoch snapshot.
+3. Evaluates the eligibility rules (see [Feature 4](#4-eligibility-checks)).
+4. Records each eligible node's reward allocation in the on-chain **rewards smart contract**.
+
+Rewards are **not** auto-deposited to the operator's wallet. Once the contract has been credited, the operator claims the accrued balance either from the **Claim Now** button in the **My Node** dashboard or by calling the rewards smart contract directly from any wallet they control. Unclaimed rewards remain available until claimed.
+
+The per-operator dashboard shows each past epoch with uptime, holdings, earned amount, and an "Eligible / Ineligible" badge. See the [Node Ecosystem Litepaper](../running-a-coti-node/coti-node-ecosystem-litepaper.md) for the economic model.