docs: Noosphere section — protocol guide, agent operations, hello-world tutorial

docs/readme/noosphere.md

@@ -4,6 +4,10 @@ description: A Gateway to Verifiable Off-Chain Intelligence
 
 # Noösphere
 
+> **📘 Builder manual:** the full Noosphere documentation — running an agent, selling compute
+> per-call with x402, and requesting compute from smart contracts — lives at
+> [**docs.hpp.io/noosphere**](/noosphere).
+
 Smart contracts are powerful but limited — they can’t think, adapt, or process complex real-world data. As Web3 intersects with AI, RWA, and scientific computation, this becomes a major bottleneck. Noosphere introduces a verifiable off-chain intelligence layer, enabling smart contracts to securely delegate inference and computation
 
 ### Limitations of Smart Contracts

docusaurus.config.ts

@@ -105,6 +105,18 @@ const config: Config = {
         editUrl: 'https://github.com/hpp-io/docs/tree/main/',
       },
     ],
+    // Noosphere docs — the verifiable off-chain compute network on HPP, served
+    // at /noosphere as a standalone product section (same pattern as /x402).
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        id: 'noosphere',
+        path: 'noosphere',
+        routeBasePath: 'noosphere',
+        sidebarPath: './sidebarsNoosphere.ts',
+        editUrl: 'https://github.com/hpp-io/docs/tree/main/',
+      },
+    ],
   ],
   themes: [
     '@docusaurus/theme-mermaid',
@@ -113,7 +125,7 @@ const config: Config = {
       {
         hashed: true,
         indexDocs: true,
-        docsRouteBasePath: ['/', 'hub', 'hpp-router', 'x402', 'hpp-coder'],
+        docsRouteBasePath: ['/', 'hub', 'hpp-router', 'x402', 'hpp-coder', 'noosphere'],
         highlightSearchTermsOnTargetPage: true,
         language: ['en'],
       },
@@ -165,6 +177,13 @@ const config: Config = {
           label: 'HPP Coder',
           position: 'right',
         },
+        {
+          type: 'docSidebar',
+          sidebarId: 'noosphereSidebar',
+          docsPluginId: 'noosphere',
+          label: 'Noosphere',
+          position: 'right',
+        },
         {
           href: 'https://github.com/hpp-io/docs',
           label: 'GitHub',

noosphere/configuration.md

@@ -0,0 +1,121 @@
+---
+title: Configuration
+sidebar_label: Configuration
+description: The Noosphere agent's config.json, block by block — chain, containers, verifiers, scheduler, payload storage, and VRF.
+---
+
+# Configuration
+
+The agent is configured by a single `config.json` (generate one interactively with
+`npm run generate:config`; template in
+[`config.example.json`](https://github.com/hpp-io/noosphere-agent-js/blob/main/config.example.json)).
+Secrets are never written into the file — use `${ENV_VAR}` substitution and put values in `.env`.
+
+## Blocks
+
+| Block | Purpose |
+| --- | --- |
+| `chain` | RPC/WS endpoints, Router & Coordinator addresses, wallet (keystore path + receiving address). Addresses per network: [Registry & deployments](./registry-and-deployments.md) |
+| `containers[]` | The Docker images this agent can run — see [Container contract](./container-contract.md#registering-the-container) |
+| `verifiers[]` | Verifier contracts this agent serves, each optionally paired with a proof-service container |
+| `scheduler` / `retry` | Scheduled-subscription interval commitment and retry policy |
+| `payload` | Large input/output storage (below) |
+| `vrf` | Opt-in NoosphereVRF epoch serving (pair with the registry's `noosphere-vrng` container) |
+| `x402Seller` | The separate per-call selling rail — configured here but documented with its own product: [Sell from an agent](/x402/sell-from-an-agent) |
+
+## `chain`
+
+```jsonc
+"chain": {
+  "enabled": true,
+  "rpcUrl": "https://sepolia.hpp.io",
+  "wsRpcUrl": "wss://sepolia.hpp.io",
+  "routerAddress": "0x480a4f7506548773040d47dd7b6372dbf71358d4",
+  "coordinatorAddress": "0xeda4a7957e8f5de6cd6bd747c3ccd5e1c295302c",
+  "deploymentBlock": 295062,        // start scanning from here — use a recent block
+  "processingInterval": 5000,       // ms between chain-processing passes
+  "wallet": {
+    "keystorePath": "./.noosphere/keystore.json",
+    "paymentAddress": "0xYourReceivingWallet"   // written by setup:wallet, or set by hand
+  }
+}
+```
+
+`npm run generate:config` fills the addresses for the network you pick (from its built-in
+per-network presets; the [community registry](./registry-and-deployments.md) supplies the
+container/verifier catalog). It leaves `paymentAddress` as the zero address — set it, or let
+`npm run setup:wallet` fill it when you create the agent's payment wallet.
+
+:::note
+`config.json` is parsed as plain JSON against the agent's TypeScript types — there is **no
+schema validation**, so a misspelled key is silently ignored. `${ENV_VAR}` substitution works
+in any string value; an unset variable is left as the literal `${…}` with only a console
+warning.
+:::
+
+## `containers[]`
+
+```jsonc
+"containers": [
+  {
+    "id": "hf-sentiment",            // referenced by subscriptions / registry ID
+    "name": "hf-sentiment",          // docker name (agent prefixes it)
+    "image": "hf-sentiment:latest",
+    "port": "8090",                  // where /computation listens inside
+    "env": { "HF_TOKEN": "${HF_TOKEN}" }
+  }
+]
+```
+
+## `verifiers[]`
+
+Serve proof-checked subscriptions: each entry names the on-chain verifier contract and,
+when the proof is produced off-chain, the companion proof-service container.
+`PROOF_SERVICE_PRIVATE_KEY` in `.env` signs proof submissions.
+
+## `scheduler` / `retry` / `containerExecution`
+
+```jsonc
+"scheduler": { "enabled": true, "cronIntervalMs": 60000, "syncPeriodMs": 3000 },
+"retry":     { "maxRetries": 3, "retryIntervalMs": 30000 }
+```
+
+An optional `containerExecution` block (`timeout`, `connectionRetries`,
+`connectionRetryDelayMs`) tunes how the agent calls your containers.
+
+## `payload`
+
+Large inputs/outputs stay off-chain; the agent resolves URI-based payloads:
+
+| Scheme | Use case | Env |
+| --- | --- | --- |
+| `data:` | Inline base64 below `payload.uploadThreshold` | — |
+| `ipfs://` | IPFS / Pinata | `PINATA_API_KEY`, `PINATA_API_SECRET`, `IPFS_GATEWAY` |
+| `https://` | S3-compatible storage (R2/S3/MinIO) | `R2_ENDPOINT`, `R2_BUCKET`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_PUBLIC_URL_BASE` |
+
+```jsonc
+"payload": { "uploadThreshold": 1024, "defaultStorage": "s3" }
+```
+
+Defaults when the block is omitted: `uploadThreshold: 1024`, `defaultStorage: "ipfs"`.
+IPFS/S3 backends can also be configured inline via `payload.ipfs { … }` / `payload.s3 { … }`
+instead of env vars.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `KEYSTORE_PASSWORD` | Decrypts the agent keystore *(required)* |
+| *(any)* | `${ENV_VAR}` substitution is generic — reference any variable from a `config.json` string value |
+| `EXPRESS_PORT` | Agent API port (default `4000`) |
+| `PROOF_SERVICE_PRIVATE_KEY` | Only for verifiers with a proof service |
+| `R2_*` / `PINATA_*` / `IPFS_*` | Payload storage backends (above) |
+
+## Networks
+
+| Network | Chain ID | RPC |
+| --- | --- | --- |
+| HPP Mainnet | `190415` | `https://mainnet.hpp.io` |
+| HPP Sepolia | `181228` | `https://sepolia.hpp.io` |
+
+Full contract addresses: [Registry & deployments](./registry-and-deployments.md).

noosphere/container-contract.md

@@ -0,0 +1,99 @@
+---
+title: Container contract
+sidebar_label: Container contract
+description: The one-endpoint interface every Noosphere container implements — POST /computation in, { output } out.
+---
+
+# Container contract
+
+Everything an agent runs for the compute network is an ordinary Docker image that implements
+**one endpoint**:
+
+```
+POST /computation
+Content-Type: application/json
+
+{ "input": "<raw input>", ...extra fields }
+```
+
+→ responds
+
+```json
+{ "output": "<string result>" }
+```
+
+That's the whole interface. The agent starts your container, forwards the request inputs to
+`localhost:<port>/computation`, and delivers `output` on-chain as the subscription result.
+
+## Rules of thumb
+
+- **`output` is a string.** Return structured results as a JSON-encoded string; consumers decode it.
+- **Stateless requests.** Each call should be self-contained; keep model state (weights, caches)
+  in the image or a mounted volume.
+- **Fail loudly.** A non-200 response or a crash means no delivery is submitted — the consumer
+  is never charged for failed work.
+- **Size the port.** The `containers[]` entry declares the internal port the agent posts to.
+
+## A complete example (~30 lines)
+
+[`examples/hf-sentiment`](https://github.com/hpp-io/noosphere-agent-js/tree/main/examples/hf-sentiment)
+wraps a free HuggingFace model with FastAPI:
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+from transformers import pipeline
+
+app = FastAPI()
+clf = pipeline("sentiment-analysis",
+               model="distilbert-base-uncased-finetuned-sst-2-english")
+
+class Req(BaseModel):
+    input: str = ""
+    text: str | None = None
+
+@app.post("/computation")
+def compute(req: Req):
+    result = clf(req.text or req.input)[0]
+    return {"output": f"{result['label']} ({result['score']:.4f})"}
+```
+
+```dockerfile
+FROM python:3.11-slim
+RUN pip install --no-cache-dir fastapi uvicorn "transformers<5" torch \
+      --extra-index-url https://download.pytorch.org/whl/cpu
+COPY app.py .
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8090"]
+```
+
+Swap the `pipeline(...)` task and the input/output mapping for any other model — text
+generation, summarization, translation, embeddings, your own fine-tune.
+
+> Pin `"transformers<5"` if you use seq2seq pipelines (summarization/translation) — v5 removed
+> those tasks.
+
+## Registering the container
+
+```jsonc
+"containers": [
+  {
+    "id": "hf-sentiment",          // referenced by services / subscriptions
+    "name": "hf-sentiment",        // docker container name (agent prefixes it)
+    "image": "hf-sentiment:latest",
+    "port": "8090",                // where /computation listens inside
+    "env": { "HF_TOKEN": "${HF_TOKEN}" }   // optional, ${VAR} comes from .env
+  }
+]
+```
+
+The agent pulls the image if needed and manages the container lifecycle (start on demand via
+the Docker socket). To make the container requestable by other consumers, publish it to the
+[community registry](./registry-and-deployments.md#contributing-to-the-registry) — subscriptions
+reference containers by their registry ID
+([Request compute on-chain](./request-onchain-compute.mdx)).
+
+## Large inputs and outputs
+
+For payloads too big for a request body or on-chain storage, the agent resolves URI-based
+payloads (`data:`, `ipfs://`, `https://` S3-compatible) via the `payload` config block — see
+[Configuration](./configuration.md#payload).

noosphere/dashboard.mdx

@@ -0,0 +1,59 @@
+---
+title: The dashboard
+sidebar_label: Dashboard
+description: The Noosphere agent's web dashboard — node health, scheduler and event counters, wallets, x402 seller earnings, and on-chain compute history, panel by panel.
+---
+
+# The dashboard
+
+Every agent ships a web dashboard: `npm run dev` → **http://localhost:3100**. It's the fastest
+answer to "is my node healthy, and what has it earned?". Screenshots below are from a live
+production agent.
+
+## Agent (home)
+
+![Agent dashboard — scheduler, events, wallet](/img/noosphere/dashboard-agent.png)
+
+| Panel | What it tells you |
+| --- | --- |
+| **Header badges** | `Healthy` = agent API is up · `WebSocket` = live chain connection (falls back to polling if your RPC has no WS) |
+| **Scheduler** | The scheduled-subscription engine: how many subscriptions it's *Tracking*, *Active* interval commitments, *Pending Txs* in flight, its commitment/sync intervals, and its `Running` status |
+| **Events (All Requests)** | Lifetime request counters — *Total / Completed / Failed / Skipped / Expired*. **Completed going up = you are earning.** Failed → check container logs; Skipped = requests for containers you don't serve or that another agent won |
+| **Agent Wallet** | The delivery-signing wallet: address, **gas balance** (keep it funded!), the Router/Coordinator addresses the node is wired to, your payment wallets, and the RPC in use |
+| **Available Containers** · **Verifiers** | Which images are up (with ports) and which verifier contracts + proof services this node serves |
+
+## x402 Seller
+
+*(Shown when `x402Seller.enabled` — see [Sell from an agent](/x402/sell-from-an-agent).)*
+
+![x402 seller tab — earnings, services, paid jobs](/img/noosphere/dashboard-seller.png)
+
+| Panel | What it tells you |
+| --- | --- |
+| **KPI cards** | *Earnings 30d* · *Paid calls 24h* (+ all-time) · *Settle success 24h* · *Services* (direct / on-chain) |
+| **Receiving (payTo) vs Agent gas (EOA)** | The two wallets, side by side: where buyer payments land (direct settlement, no custody) vs what funds delivery gas for the on-chain rail |
+| **Services** | Each service's settlement mode, price (USDC.e/call), schemes, calls (24h), earnings (30d) |
+| **Recent paid jobs** | Live feed: time, service, payer, scheme, amount, **settle tx** (on-chain proof), status |
+
+Raw data behind this tab: `GET /api/seller/{summary,wallets,services,jobs,earnings}` on the
+agent API (`:4000`).
+
+## Computing History
+
+![Computing history — deliveries with fees and profit](/img/noosphere/dashboard-history.png)
+
+Every on-chain delivery your node made: subscription, interval, container, the delivery
+transaction, the **fee earned vs gas spent — your profit per job**. Use it to sanity-check
+pricing: if gas regularly eats the fee, the subscription's `feeAmount` is too low for your
+network conditions.
+
+**Prepare History** (header button) shows the scheduler's interval commitments — useful when
+you're debugging why a scheduled subscription was or wasn't picked up.
+
+## Reading the dashboard like an operator
+
+- **Am I healthy?** Header badges + Scheduler `Running`.
+- **Am I earning?** Events *Completed* rising (on-chain rail) · Seller *Recent paid jobs*
+  filling (x402 rail).
+- **Am I about to stop earning?** Agent Wallet balance low → deliveries will start reverting.
+- **Was that job worth it?** Computing History → fee vs gas per delivery.