UI Guide

A page-by-page walkthrough of the COTI Nodes web app (see Networks for the testnet and mainnet URLs). Read 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.

Overview hero, Live Node Heartbeats, and ecosystem stats.

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

Every node the ecosystem knows about, sortable and searchable.

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).

• 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)

Entry point for new operators.

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

Step 1: short video walkthrough.

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

Step 2: terms of use for node operators.

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

Step 3: locally-generated node keys with an option to bring your own.

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.

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.

Step 4 — Setup FQDN

Step 4: choose a COTI-generated hostname or bring your own FQDN.

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. 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).

After Generate FQDN for Me: success confirmation and the assigned hostname before Next.

• 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).

Bring your own FQDN: enter your hostname, confirm DNS, or go back to the generated-FQDN path.

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. Without a reachable public RPC name your node cannot earn rewards.

Step 5 — Run the command

Step 5: the installer command tailored to your key and FQDN.

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

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. Tick "I've run this command" to advance.

Step 6 — Waiting for node connection

Step 6: the wizard polls peer discovery every ~60 seconds and advances automatically once your node is seen.

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.

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), tracked on the My Node tab.

Step 7 — Your node is live

Step 7: node is on the network and uptime tracking has started.

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)

The warm-up card near the end of the warm-up period, with the progress bar full. The NFT is about to be minted.

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

Empty state for wallets that do not own a node NFT.

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

Full operator dashboard once the NFT has been minted: identity, stats, and this-epoch eligibility paths.

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).

Past Epochs: per-epoch snapshots, uptime bars, eligibility badges, and pagination.

• 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)

Edit Node: two-column layout — form on the left, live summary on the right.

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)

Node Reward Eligibility: two paths, numeric thresholds from the rewards contract, and an OR between paths.

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 and Glossary → Eligibility.