# GoatNode Whitepaper

Version: 1.2 (implementation-aligned)
Date: 2026-04-24
Status: Draft for current codebase

## Abstract

GoatNode is a Seeker-first active DePIN game loop on Solana. The protocol converts verified SKR stake into next-day fuel, then requires active user actions (feed taps) to transform fuel into XP, progression, and activity telemetry. The design goal is simple: reward participation, not passive wallet holding.

This whitepaper documents the protocol exactly as implemented in the current repository, including data model, economic formulas, API behavior, security checks, and operational jobs.

This revision adds the B2B telemetry access layer, including authenticated heatmap APIs, data export formats, and quota-based access controls.

## 1. Problem Statement

Most mobile crypto experiences optimize for passive holding or occasional transactions. GoatNode targets an alternate model:

- tie progression to active daily participation,
- bridge on-chain stake to game resources,
- capture useful real-world telemetry from the active loop,
- keep progression deterministic and auditable.

## 2. Design Principles

- Stake-to-utility: stake is converted into actionable fuel.
- Time-bounded participation: fuel unlocks and cooldowns enforce cadence.
- Proof of action: feed calls require transaction-backed proof.
- Deterministic progression: XP, tiering, and marketplace pricing are formula-based.
- Operational resilience: retry queues and day-bound snapshots recover from transient failures.

## 3. System Overview

### 3.1 High-Level Components

- Frontend: Next.js pages and API routes.
- Wallet/auth layer: wallet signatures and memo transaction fallback auth.
- Solana integration: reads staking state, verifies payment proofs, verifies feed proof transactions.
- Database: PostgreSQL via Prisma.
- Worker: cron-based daily snapshot and NFT retry queue.
- B2B telemetry API: authenticated heatmap query and export endpoints over aggregated TapEvent data.

### 3.2 Core Data Objects

- User: wallet identity, fuel state, XP, streaks, tier, tap power, NFT references.
- WaitlistEntry: synchronized stake snapshot and loyal status.
- DailyFuelPool: global per-day capacity and remaining fuel.
- TapEvent: per-feed telemetry and network metadata, including signal strength, carrier context, altitude/floor, and local time slices.
- Data quality scoring: each TapEvent stores a normalized `dataQualityScore` (0-100) based on telemetry completeness.
- MarketplacePurchase: on-chain payment-backed tap power upgrades.
- NftMintPayment and NftUpdateJob: mint accounting and metadata update retries.
- Heatmap cells (derived): runtime aggregation by geospatial grid over TapEvent records with network, carrier, signal, altitude, and temporal breakdowns.

## 4. Protocol Mechanics

### 4.1 Stake-to-Fuel Conversion

Current implementation converts stake to next-day fuel with a daily streak multiplier:

- next_day_fuel = floor(staked_skr * multiplier)
- multiplier = 1 + (streak_days * 0.01), where streak_days = consecutive days of active fuel consumption
- minimum multiplier: 1.0 (no streak); maximum practical multiplier: 1.1 (10-day streak)

Interpretation:

- 1 staked SKR yesterday -> 1 fuel available today
- Users who consume active fuel daily get a cumulative 1% fuel bonus per consecutive day

### 4.2 Daily Snapshot and Day Rollover

At UTC day rollover, user state swaps as follows:

- current_fuel <- next_day_fuel
- daily_fuel_budget <- next_day_fuel
- fuel_spent_today <- 0
- next_day_fuel <- fresh value from live stake read

A global daily pool is reset to:

- totalFuel = 1,000,000
- remainingFuel = 1,000,000

### 4.3 Phase Unlocking and Cooldown

- Day is partitioned into feed phases based on the feed cycle constants in code.
- Base cycle defaults to 1h active + 2h cooldown, with dynamic cooldown reductions by NFT count.
- Unlocked fuel for the current phase is derived from daily budget and current phase index.
- If no fuel is unlocked in the current phase, feed is rejected.

### 4.4 Feed Execution

Each feed call requires:

- authenticated wallet session or wallet proof,
- valid phase availability,
- sufficient user fuel,
- sufficient global pool fuel.

On success:

- user current fuel is decremented by effective tap power,
- XP increases,
- points increase,
- tap telemetry is persisted,
- daily global pool is decremented.

### 4.5 XP and Goat Points

XP gain per feed:

- streakMultiplier = 1 + 0.01 * streakDays
- xpGain = 0.01 * fuelSpent * streakMultiplier

Goat Points gain per feed:

- goatPointsGain = floor(0.01 * fuelSpent * nftAmount * streakMultiplier)

Where:

- fuelSpent = effective fuel consumed by the feed action (tap power spend)
- nftAmount = counted GoatNode NFT amount used by feed utility logic (capped set)
- streakMultiplier = same multiplier used for XP

XP and Goat Points are intentionally separate generation tracks.

### 4.6 Tiering

Tier thresholds:

- BABY: xp < 5,000
- WORKER: 5,000 <= xp < 25,000
- ALPHA: xp >= 25,000

### 4.7 Tap Power Marketplace

- Min tap power: 1
- Max tap power: 10
- Upgrade is sequential (only next level can be bought).
- Price formula:

  price(level) = 300 * 2^(level - 2) SKR for level >= 2

Examples:

- level 2: 300 SKR
- level 3: 600 SKR
- level 4: 1200 SKR

Payment is accepted only after on-chain verification that required SKR reached the treasury wallet.

### 4.8 NFT Lifecycle

Current NFT constants:

- max supply: 9,999
- mint price: 5,000 SKR
- mint system: candy machine

Tier promotions trigger NFT metadata updates where applicable. Failed updates are queued and retried by the worker with bounded backoff.

### 4.9 Multi-NFT Utility Policy (Configured)

GoatNode applies utility for wallets holding multiple GoatNode NFTs with a hard counted cap of 10 NFTs.

- Counted NFT cap: 10
- XP bonus from NFT count: 0 (no direct XP multiplier)
- Goat Points can scale with counted NFT amount
- Cooldown bonus: reduced from base 120 minutes down to a minimum of 60 minutes at 10 NFTs

Definitions:

- nft_count = min(owned_goatnode_nfts, 10)
- extra_nfts = max(0, nft_count - 1)

Fuel formula:

- effective_next_day_fuel = floor(staked_skr * (1 + 0.01 * nft_count))

Cooldown formula:

- base_cooldown_seconds = 7200
- reduction_per_extra_nft_seconds = 400 (6 minutes 40 seconds)
- effective_cooldown_seconds = max(3600, 7200 - 400 * extra_nfts)

This cooldown schedule yields:

- 1 NFT: 120 minutes
- each extra NFT: minus 6 minutes 40 seconds
- 10 NFTs: 60 minutes total cooldown

## 5. Security Model

### 5.1 API Authentication

Request authentication supports fresh wallet proof and reusable sessions:

- signed message (`GoatNode:<wallet>:<timestamp>`), or
- memo transaction fallback with the same payload,
- server-issued session token created after successful wallet proof.

Security conditions:

- timestamp freshness window: 5 minutes,
- signer must match claimed wallet address,
- memo payload must match expected value if used,
- session tokens are signed server-side with HMAC and expire automatically.

### 5.2 Feed Action Proof

Feed endpoint accepts a valid wallet session by default and can optionally verify a legacy feed proof transaction:

- legacy transaction exists and succeeded,
- legacy transaction age <= 10 minutes,
- claimed wallet is a signer,
- legacy memo payload equals expected proof string.

### 5.3 Treasury Payment Verification

Marketplace purchase verification checks:

- transaction success and freshness,
- signer wallet correctness,
- pre/post token balances for wallet and treasury,
- treasury received at least required SKR (with decimal tolerance).

## 6. Data and Telemetry

Per-feed telemetry may include:

- latency,
- GPS coordinates and accuracy,
- network type/effective type,
- downlink estimate,
- connection RTT,
- bluetooth availability.

This data enables network-quality analysis while preserving the protocol's action-first progression model.

### 6.1 Aggregated Heatmap Products

GoatNode exposes aggregated telemetry views for B2B/enterprise consumers.

- Query endpoint: `GET /api/heatmap`
- Export endpoint: `GET /api/heatmap/export?format=csv|geojson`

Each response is radius-filtered around input coordinates and bucketed into geographic grid cells. Returned metrics include:

- sample counts,
- average latency,
- average connection RTT,
- average downlink,
- bluetooth availability rate,
- network-type breakdown,
- first/last seen timestamps.

## 7. API Surface (Current)

- `POST /api/user/login`: upsert user, refresh day state when UTC day changes.
- `POST /api/sync`: stake verification and next-day fuel sync.
- `GET/POST /api/waitlist`: read or update waitlist and projected fuel.
- `POST /api/goat/feed`: execute feed action with proof checks and telemetry write.
- `POST /api/marketplace/buy`: unlock next tap power level after treasury payment verification.
- `GET /api/heatmap`: API-key protected geospatial aggregation endpoint.
- `GET /api/heatmap/export?format=csv|geojson`: API-key protected export endpoint.

## 8. B2B Access Control and Quotas

Heatmap endpoints require API key authorization and enforce per-key daily quota limits.

Supported key transport:

- `x-api-key` header,
- `Authorization: Bearer <key>`,
- `apiKey` query fallback.

Quota metadata is returned in response headers:

- `X-RateLimit-Limit`,
- `X-RateLimit-Remaining`,
- `X-RateLimit-Reset`.

Current implementation note: quota counters are in-memory per service instance and reset on restart/redeploy.

## 9. Operations and Reliability

Worker responsibilities:

- 00:00 UTC snapshot to rotate fuel day state.
- Every 10 minutes: retry pending NFT update jobs.

Reliability safeguards:

- idempotent upserts for day pool and user bootstrap,
- bounded retry progression for NFT update queue,
- throttle on feed endpoint to reduce spam bursts,
- transactional updates for feed and marketplace purchase paths.

## 10. Access Control Posture

Current app UX policy in code:

- disconnected wallets are redirected to the home briefing page,
- geolocation permission is required for app usage beyond initial setup routes,
- protected routes require an active wallet connection.

This is UX-level gating. Critical state changes still depend on signed/authenticated server-side checks.

## 11. Current Constraints

- Daily global fuel cap is fixed, not adaptive.
- Governance controls are not yet exposed in this repository.
- Reward sinks/sources beyond XP and tap power are intentionally minimal at this stage.
- NFT flow depends on Candy Machine configuration and operational keys.
- Heatmap quota accounting is not yet persisted/distributed for strict billing semantics.

## 12. Near-Term Evolution (Implementation-Oriented)

- Add formal policy docs for parameter governance and change management.
- Expand anti-abuse heuristics on telemetry consistency checks.
- Introduce stronger audit logs for admin and queue operations.
- Publish versioned protocol spec alongside implementation changes.
- Add persistent quota metering (Redis/Postgres) and enterprise API-key lifecycle controls.
- Add client-level usage reporting and billing exports for B2B contracts.

## 13. Glossary

- SKR: primary token used for staking and certain payments.
- Fuel: daily spendable action budget derived from stake.
- Tap Power: max fuel consumed per feed action.
- Streak: consecutive day completion signal affecting XP multiplier.
- Tier: XP milestone state (`BABY`, `WORKER`, `ALPHA`).
- Heatmap Cell: aggregated telemetry bucket for a fixed geographic grid region.

## 14. Legal and Policy Surface

GoatNode publishes legal documentation through in-app routes and a canonical legal-docs page.

- Legal hub route: `/legal`
- Canonical legal docs route: `/legal-docs`
- Embedded policy sections in legal hub:
  - Privacy Policy
  - Terms of Service
  - License
  - Copyright

The legal hub embeds the policy sections for user readability, while the standalone legal-docs
route acts as the canonical text surface for references and external linking.

Policy updates are reflected by updated effective dates in the legal UI. Continued use of GoatNode
after policy changes constitutes acceptance of updated terms where allowed by applicable law.

## Disclaimer

This document describes the present repository behavior and constants at the time of writing. It is not financial advice and is not a promise of future protocol parameters or token economics.