# UI Guide

A page-by-page walkthrough of the COTI Nodes web app (see [Networks](/coti-documentation/node-ecosystem.md#networks) for the testnet and mainnet URLs). Read [features.md](/coti-documentation/node-ecosystem/features.md) first for the product-level overview; this page describes what each screen shows and how to use it.

## Site map

The top-level navigation exposes three tabs: **Overview**, **My Node**, and **Eligibility**. The spin-up and edit flows are reachable from links inside those pages rather than from the top nav.

| Route          | Tab / Surface           | Purpose                                                               |
| -------------- | ----------------------- | --------------------------------------------------------------------- |
| `/`            | Overview                | Public dashboard: live heartbeats, ecosystem stats, nodes table       |
| `/join`        | (from "Spin up a Node") | Choose between local install and hosted provider                      |
| `/setup`       | (from Join)             | 7-step guided installation wizard                                     |
| `/my-nodes`    | My Node                 | Per-operator dashboard (wallet-gated)                                 |
| `/edit-node`   | (from My Node)          | Edit node NFT metadata: name, image URI, more-info URL                |
| `/eligibility` | Eligibility             | Node reward eligibility: two paths (USDC + COTI vs COTI-only) + notes |
| `/terms`       | (footer)                | Terms of service                                                      |

## Overview (`/`)

The landing page has several sections.

<figure><img src="/files/kpCI7bFr2ZDnWGPWO8W7" alt="Overview hero with Spin up a Node CTA, Live Node Heartbeats panel, and the three ecosystem stats cards"><figcaption><p>Overview hero, Live Node Heartbeats, and ecosystem stats.</p></figcaption></figure>

### Hero + live heartbeats

A **"Spin up a Node"** CTA sits alongside the **Live Node Heartbeats** panel. The panel shows:

* The current count of nodes observed by the peer-discovery service.
* How many seconds have passed since the last refresh.
* A purely decorative pulse visualization.

### Ecosystem stats

Three cards summarize the most recent closed epoch and all-time totals:

* **Reward-eligible nodes (last epoch)** — how many nodes met the rules last epoch.
* **COTI dropped (last epoch)** — total rewards distributed last epoch.
* **Total COTI earned** — cumulative rewards paid across all epochs.

Clicking the clock icons on the first two cards opens an **Epoch Status** modal with the current epoch number and time remaining.

### Nodes table

<figure><img src="/files/kNkBScarBCbcCr7djjrY" alt="Nodes table listing node operator, total rewards, status, uptime, and latency"><figcaption><p>Every node the ecosystem knows about, sortable and searchable.</p></figcaption></figure>

Columns:

* **Node operator** — NFT avatar, node name, and the truncated node address. Nodes without a minted NFT show "NFT Not Found".
* **Total rewards** — cumulative COTI earned.
* **Status** — Active / Syncing / Offline (see [Glossary → Node status](/coti-documentation/node-ecosystem/ui-guide/glossary.md#node-status)).
* **Uptime** — all-time percentage and a proportional bar.
* **Latency** — most-recent RPC latency with a color-coded rank (Fast / Good / Slow).

The search box filters on node name, node address, and status. Clicking a row opens a **Node Details** modal with the node's NFT metadata, rewards breakdown, and a link to the operator's recent activity.

## Join COTI Nodes (`/join`)

<figure><img src="/files/RIL38z03xOy246IW5bpU" alt="Join page with two options: Local Node (Vibe Coding) and Hosted Node Provider (Coming Soon)"><figcaption><p>Entry point for new operators.</p></figcaption></figure>

Two cards:

* **Local node (Vibe Coding)** — routes to `/setup`, the guided installer. This is the primary, fully-supported path.
* **Hosted node provider** — currently labeled **Coming Soon**. Reserved for a future marketplace of third-party providers and not usable yet.

## Spin up a Node (`/setup`)

The installation wizard is a 7-step flow. The header shows **Spin COTI Node** and a horizontal **SetupBar** with short step labels — **Watch Video**, **Terms of Use**, **Generate Keys**, **Setup FQDN**, **Run Command**, **Monitor Node**, **Node Live** — aligned with the sections below. The main panel swaps content per step. The primary **Next** button advances; **Back** goes to the previous step.

### Step 1 — Watch the setup video

<figure><img src="/files/FaToryCuibDFaQCKnp2v" alt="Setup step 1 with a short walkthrough video and bullet summary"><figcaption><p>Step 1: short video walkthrough.</p></figcaption></figure>

A short video plus a bulleted summary: what the command does, what happens after, and that there is no configuration required.

### Step 2 — Accept the terms

<figure><img src="/files/SdfpuSlh6V5r78D8uaxA" alt="Setup step 2 presenting the Terms of Use with a checkbox"><figcaption><p>Step 2: terms of use for node operators.</p></figcaption></figure>

The Terms of Use must be checked before the wizard advances. A **Download Full Terms of Use (PDF)** link exposes the complete document. Trying to continue without checking the box surfaces an inline error.

### Step 3 — Generate node keys

<figure><img src="/files/KsRdHhei8HdH0jdqIEKd" alt="Setup step 3 showing a generated public/private key pair with a Download Key Backup button and a confirmation checkbox"><figcaption><p>Step 3: locally-generated node keys with an option to bring your own.</p></figcaption></figure>

Two paths:

* **Generate node keys locally** — the wizard generates a fresh private key in the browser, derives the node address, and offers a **Download Key Backup** button. You must tick **"I've saved my keys in a secure location"** to proceed.
* **Bring your own key** — paste an existing 64-hex private key. The wizard derives the address and confirms it. If that address already owns a node NFT, a modal offers to clear the field so you don't accidentally re-run setup for an existing node.

If the just-generated address differs from the currently connected wallet, a yellow notice explains that you will need to connect the new wallet later to see the node's warm-up state, NFT, and rewards.

{% hint style="warning" %}
The private key is the identity of your node and the wallet that will receive the Soulbound NFT and rewards. It is generated locally and never transmitted. Back it up before continuing.
{% endhint %}

### Step 4 — Setup FQDN

<figure><img src="/files/k4Jfu7ZELhsuJGqBPUGJ" alt="Setup FQDN step with Generate FQDN for Me and Bring your own FQDN choices"><figcaption><p>Step 4: choose a COTI-generated hostname or bring your own FQDN.</p></figcaption></figure>

The panel title is **Setup FQDN**, with the line **Connect your FQDN (Fully Qualified Domain Name) to your node.** You pick how the public hostname is supplied:

* **Generate FQDN for Me** — the default path for the **COTI-managed hostname** (tunnel / **`--with-frp`** install). You do not create DNS at your registrar; the one-liner and edge routing are described in [**Wizard tunnel**](/coti-documentation/node-ecosystem/installation/installation-wizard-tunnel.md). When you click it, the wizard allocates the name and updates the same step: a green **FQDN generated successfully!** banner appears, and a read-only **Node FQDN** field shows the assigned hostname (for example a `*.fullnode.<network>.coti.network`-style name on testnet — the exact zone depends on the environment).

<figure><img src="/files/NXnfaVnmu3yd5f6Hwz46" alt="Setup FQDN after generation: green success banner and Node FQDN read-only field"><figcaption><p>After <strong>Generate FQDN for Me</strong>: success confirmation and the assigned hostname before <strong>Next</strong>.</p></figcaption></figure>

* **Bring your own FQDN** — for a hostname **you** control. The wizard shows a **Node FQDN** text field (label includes an example such as `node.yourdomain.com`, placeholder **Enter your FQDN.**). An **Important** callout reminds you to configure an **A or CNAME** record at your DNS provider pointing to your server’s public IP **before** you continue, so the name is reachable on the network. Tick **"I have completed my FQDN settings"** (with the line *I verify that my FQDN points to my node's IP.*) to run a live DNS lookup via `dns.google.com/resolve`:

  * Success — you can proceed with **Next**.
  * Failure — an inline error explains that the domain did not resolve; fix the record at your registrar and retry.

  **← Back to Generation.** returns to the choice screen if you want **Generate FQDN for Me** instead. This path matches **Nginx + TLS** on your server — see [**Own domain (Nginx + TLS)**](/coti-documentation/node-ecosystem/installation/installation-own-domain.md).

<figure><img src="/files/lRwuHiBwP5RtE9DEBTq5" alt="Bring your own FQDN: Node FQDN input, A or CNAME notice, verification checkbox, and Back to Generation link"><figcaption><p><strong>Bring your own FQDN</strong>: enter your hostname, confirm DNS, or go back to the generated-FQDN path.</p></figcaption></figure>

{% hint style="warning" %}
**This FQDN is the address the ecosystem will use to reach your node's JSON-RPC for uptime monitoring.** **Own domain + Nginx** needs a live DNS record to your server and reachable **80/443**. **COTI tunnel** (`--with-frp`) uses the COTI-assigned hostname and edge TLS. Overview: [**Installation**](/coti-documentation/node-ecosystem/installation.md). Without a reachable public RPC name your node cannot earn rewards.
{% endhint %}

### Step 5 — Run the command

<figure><img src="/files/jse0uMAmE2eirY649J4G" alt="Setup step 5 showing a terminal card with the generated curl | sudo bash one-liner and a Learn more about installation link"><figcaption><p>Step 5: the installer command tailored to your key and FQDN.</p></figcaption></figure>

The wizard displays the one-liner tailored to the key and FQDN from the previous steps:

```bash
curl -sL https://fullnode.<network>.coti.io | sudo bash -s -- "<PRIVATE_KEY>" "<FQDN>"
```

Copy and run it as root on your server. A **"Learn more about installation"** link opens the [**Installation** overview](/coti-documentation/node-ecosystem/installation.md). Tick **"I've run this command"** to advance.

### Step 6 — Waiting for node connection

<figure><img src="/files/Nsxsugxin2mYYBjqjdQb" alt="Setup step 6 with a spinner and the message Listening for node heartbeat"><figcaption><p>Step 6: the wizard polls peer discovery every ~60 seconds and advances automatically once your node is seen.</p></figcaption></figure>

The wizard polls the peer-discovery service every \~60 seconds and waits for your node address to show up in the peer set. Three states:

* **Searching** — spinner + "Listening for node heartbeat". You can safely close the tab and return later.
* **Detected** — green check + "Heartbeat Detected!". The wizard auto-advances in a few seconds.
* **Timeout** — after the initial grace period, a retry countdown appears and the wizard retries automatically.

{% hint style="info" %}
This step only confirms that peers can *see* your node. It does not mean your node is hot or that an NFT has been minted. That is the **warm-up period** (see [Glossary → Warming up](/coti-documentation/node-ecosystem/ui-guide/glossary.md#warming-up)), tracked on the **My Node** tab.
{% endhint %}

### Step 7 — Your node is live

<figure><img src="/files/zr0ckysr6m5gBQ7AGwLh" alt="Setup step 7 with a success card showing Status Online, Uptime tracking Started, and a Go to Dashboard button"><figcaption><p>Step 7: node is on the network and uptime tracking has started.</p></figcaption></figure>

A success card with a **Go to Dashboard** button that routes to **My Node**. It also confirms that uptime tracking has started — the node has been registered with the monitoring stack via its FQDN.

If the connected wallet differs from the node address, the wizard shows a warning explaining that the dashboard only lists nodes owned by the connected wallet — connect the node wallet (or import its private key into MetaMask) to see the node on the dashboard.

## My Node (`/my-nodes`)

The per-operator dashboard. It requires a connected wallet; the wallet must own a Soulbound Node NFT to show full content.

### Warmup (in progress / complete)

<figure><img src="/files/Gbp9gdn6R1HJED35zUi9" alt="My Node screen showing the Warmup Complete card with the progress bar at 100%"><figcaption><p>The warm-up card near the end of the warm-up period, with the progress bar full. The NFT is about to be minted.</p></figcaption></figure>

While the node is warming up, the page shows a **Warmup In Progress** card with an elapsed / required progress bar (for example `18h 30m / 72h (26%)`) and copy explaining that the operator should keep the node online to complete the warm-up.

When the threshold is reached (progress reaches 100%, as in the screenshot above), the card flips to **Warmup Complete**. The Soulbound NFT is minted shortly thereafter and the full dashboard replaces the warm-up card automatically.

### No node detected

<figure><img src="/files/LS4yWwRjwL9QhHeKLHx8" alt="My Node screen showing No Node Detected for a wallet without a node NFT"><figcaption><p>Empty state for wallets that do not own a node NFT.</p></figcaption></figure>

If the connected wallet has not started setup and does not own a node NFT, the page shows a "No Node Detected" card with a link back to the overview. Operators who just finished `/setup` but see this screen are likely connected with the wrong wallet — the NFT is minted to the **node address**, not the wallet used to navigate the site.

### Full dashboard

<figure><img src="/files/xWpKiPdRUQy79IxrK8i5" alt="My Node dashboard: identity card with LIVE, Total Earned and claimable, three stat cards, Eligibility This Epoch with Path 1 and Path 2"><figcaption><p>Full operator dashboard once the NFT has been minted: identity, stats, and this-epoch eligibility paths.</p></figcaption></figure>

Once the NFT exists, the dashboard shows:

* **Node identity card** — NFT image, node name, **`LIVE`** badge when the node is considered online, truncated node address, and **Edit** → `/edit-node`. **Total Earned** (all-time COTI from rewards) appears with a secondary **claimable** line (accrued balance not yet withdrawn) and a **Claim Now** button that sends a claim transaction on the rewards contract into the connected wallet. Operators who prefer to claim off-site can call the contract directly.
* **At-a-glance stats** (three cards) — **All-Time Uptime** with a performance badge (for example **Excellent**), **Eligibility Streak (Days)** with a streak-style badge (for example **On Fire**), and **COTI Claimed** (lifetime claimed amount) with a complementary badge (for example **Stacking**). Icons and colors reinforce each metric.
* **Eligibility** — section title **Eligibility** with **This Epoch** and a shield icon. The same **two-path** layout as **`/eligibility`**: **Path 1 — USDC + COTI** and **Path 2 — COTI only** separated by **OR**. Each path card can show a corner status (for example **Not yet** while requirements are incomplete). Rows list **USDC Holdings**, **COTI Holdings** (Path 2 includes *No USDC required* helper copy), and **Uptime**, each as **current / threshold** with a progress bar: green when the row is satisfied, yellow or orange when not; row icons mark met vs not met. You are eligible for the epoch when **either** path is fully satisfied (all its rows green).

<figure><img src="/files/f6hoKHXscdZXUGfT9H69" alt="Past Epochs table with Epoch USDC COTI Earned Uptime bars and Eligible status, plus pagination footer"><figcaption><p><strong>Past Epochs</strong>: per-epoch snapshots, uptime bars, eligibility badges, and pagination.</p></figcaption></figure>

* **Past Epochs** — subtitle *Historical eligibility data.* A paginated table with columns **Epoch**, **USDC**, **COTI**, **Earned**, **Uptime** (percentage with a horizontal bar), and **Status** (**Eligible** / **Ineligible** as a pill). The footer shows how many epochs are on the current page versus the total (for example *Showing 4 of 90 past epochs*), a page indicator (for example `1 / 23`), and **Previous** / **Next** controls.

## Edit Node (`/edit-node`)

<figure><img src="/files/3pCQM640i6141J0PDLcw" alt="Edit Node Details form beside Configuration Summary with NFT preview and token details"><figcaption><p><strong>Edit Node</strong>: two-column layout — form on the left, live summary on the right.</p></figcaption></figure>

The header breadcrumb reads **My Node / \<node name>** so you can see which node you are editing.

Two cards sit side by side:

* **Edit Node Details** — copy explains that **changes are saved to the node's NFT metadata**. Fields:
  * **Node Name** — display name for the node.
  * **Node Image URI** — HTTPS URL for the node's avatar image (shown in ecosystem UIs).
  * **More Info URL** — optional link (placeholder `https://...`) for extra context (site, docs, etc.).
  * **Submit Node Configuration** — primary action; submitting triggers the wallet flow to update on-chain NFT metadata (signature / transaction, depending on implementation).
* **Configuration Summary** — live preview: rendered **image** from the URI, **Name**, **URL** (or **N/A** when empty), **Node ID (Token)** as the NFT token id, and the **NFT contract address** for reference.

After a successful update, refreshed metadata appears on **My Node** and in the public nodes table once the app reloads chain or indexer data.

## Eligibility (`/eligibility`)

<figure><img src="/files/PVh8oRPh2xYZPFNAxeuY" alt="Node Reward Eligibility page with Path 1 USDC plus COTI and Path 2 COTI only separated by OR"><figcaption><p><strong>Node Reward Eligibility</strong>: two paths, numeric thresholds from the rewards contract, and an <strong>OR</strong> between paths.</p></figcaption></figure>

The page opens with an **Eligibility Criteria** pill, the title **Node Reward Eligibility**, and the subtitle *Two ways to qualify. Meet either path's requirements — and run a node — to earn rewards.*

Under **Eligibility Paths**, two cards sit on either side of a centered **OR** divider:

* **Path 1 — USDC + COTI** — *Hold both USDC and COTI on the COTI network, plus run a node.* Lists **USDC Holdings** (stablecoins on COTI network), **COTI Holdings** (non-custodial wallets; not CEX), and **Uptime** (while running your node). You must satisfy **all three** rows on this path for Path 1 to count.
* **Path 2 — COTI only** — *Hold COTI alone — no USDC required — plus run a node.* Lists **COTI Holdings** at the **solo** threshold (higher than Path 1’s COTI bar) and **Uptime**. Both must be met for Path 2 to count.

The exact numbers (for example `1+` / `2+` / `98%+`) are loaded from the on-chain eligibility rules and can differ by network or governance updates.

Below the cards, an info strip states that you can meet **either** path for rewards eligibility, that balances refresh about every **24 hours**, and includes a **Check My Eligibility** button: if the connected wallet already holds a node NFT, it routes to **My Node**; otherwise it opens a modal that summarizes status and can steer you to **`/setup`**.

Further down, **Important Notes** (*Things to Know*) expands on topics such as the two-path rule, that **COTI on centralized exchanges does not count**, continuous checks, and that node status is evaluated dynamically.

Authoritative rule logic is summarized under [Features → Eligibility checks](/coti-documentation/node-ecosystem/features.md#4-eligibility-checks) and [Glossary → Eligibility](/coti-documentation/node-ecosystem/ui-guide/glossary.md#eligibility).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coti.io/coti-documentation/node-ecosystem/ui-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.