docs: Noosphere section — protocol guide, agent operations, hello-world tutorial - #26
Merged
Conversation
A standalone docs instance (same pattern as /x402) covering both what Noosphere is and how to use each side of it: - Overview — the verifiable off-chain compute network, its two revenue rails (on-chain subscriptions, x402 per-call selling), role-based paths - How it works — consumers, Router/Coordinator/Billing, agents and containers, transient vs scheduled subscriptions, compute wallets, verification levels, VRF, with a request-lifecycle sequence diagram - Quickstart: run an agent — install → config → keystore → run, dashboard, Docker deployment, the on-chain worker rail - Sell compute (x402) — free HF model to first payment in 10 minutes, buyer guarantees, execution receipts, HTTP/MCP/Explorer reach, pricing - Buy compute — find services on the explorer, pay from code or an AI agent, buyer protections - Request compute on-chain — TransientComputeClient walk-through with the real _receiveCompute signature, subscription parameters, trust levels - Reference — the POST /computation container contract (with a complete FastAPI example) and the full config.json reference Registers the docs plugin instance, sidebar, navbar entry, and search scope; links the main-docs Noosphere intro to the manual. Build passes with Docusaurus link checking.
Corrected model after review: Noosphere and x402 are independent products that happen to share the agent/containers. Core Noosphere = BOTH request and settlement on-chain (subscriptions, Router/Coordinator, Billing + compute-wallet escrow); x402 = per-call HTTP selling with off-protocol stablecoin settlement, documented at /x402 only. - Remove the x402 pages from this section (sell-compute, buy-compute); x402 appears only as a one-paragraph cross-reference for operators. - Overview + How it works rewritten protocol-first: Router/Coordinator/ Billing/WalletFactory roles, commitment lifecycle, transient vs scheduled, compute-wallet escrow, verification as a dial (redundancy → registry verifiers), brief NoosphereVRF section. - NEW Registry & deployments page: live contract addresses for Mainnet (190415) and Sepolia (181228) from noosphere-registry, the container catalog (hello-world/llm/freqtrade/vrng), verifiers, RegistryManager usage (API checked against the SDK source), contribution flow. - Run an agent rewritten as a protocol-worker guide (delivery gas, participation levels: worker / verified compute / VRF operator). - Configuration rewritten protocol-first; x402Seller is one row pointing to /x402. Container contract page de-x402'd. - Grounded in a review of the full repo family: noosphere-evm README + contracts, noosphere-sdk packages, noosphere-registry network files, agent-js. Legacy Java services (hub/gateway/scheduler) excluded. Build passes with link checking.
The agent-operator's x402 selling guide lives where it belongs — in the x402 product docs, next to the SDK seller quickstart — keeping the /noosphere section protocol-pure while still serving operators who want the per-call rail: - no-code path: container -> config.json (x402Seller block) -> paid routes + MCP tools, with the 10-minute HuggingFace walk-through - buyer guarantees (schema-gated 400 before payment, no charge on failure, non-custodial), execution receipts - reach: HTTP / MCP bridge / explorer listing (register-before-first-sale, pending-until-approved), pricing, operating tips - wired into the x402 sidebar + intro seller table; /noosphere cross-links (intro, run-an-agent, configuration) now point at it Build passes with link checking.
…l in /x402 Full exclusion had erased half of an operator's revenue picture from the Noosphere docs. Applied the junction rule — each product surfaces the junction from its own perspective; the concept owner keeps the detail: - Overview gains 'One agent, two markets': a parallel-markets comparison table (buyers, request path, settlement, funds-to-start, verification) that states the boundary explicitly — this docs = on-chain protocol, per-call selling detail = /x402. Path table gains the per-call seller row; the redundant footer info-box is dropped. - Run an agent: the tail tip becomes a real section — what the x402 rail is, a which-rail-when decision table, the one config switch (x402Seller.enabled), then a single deep link to /x402/sell-from-an-agent for pricing/schemas/receipts/explorer listing. No step-by-step or config-field duplication: how-to detail stays solely in /x402/sell-from-an-agent. Build passes with link checking.
…ts, dashboard page, first-request tutorial, real screenshots Reviewed as a newcomer who just found Noosphere and wants to run an agent: the old pages gave four commands and stopped. Now: - Run an agent: full walk-through with the REAL terminal transcripts (generate:config's interactive session, init's keystore output, healthy startup logs), a what-you'll-need/what-you'll-have frame, and an 'Is it working?' checklist mapping each check to a dashboard panel. - NEW Dashboard page: panel-by-panel reference for the agent home, x402 Seller tab, and Computing History — illustrated with screenshots captured from a live production agent — plus 'reading it like an operator' (am I healthy / earning / about to stop earning / was that job worth it). - NEW Tutorial: your first compute request — end to end on Sepolia: forge-deploy the sample MyTransientClient against the live Router, npm run send:request (real transcript: payment wallet -> subscription -> request), watch the delivery land, cast-read the result back. No-funds path via the repo's anvil e2e script. Grounded in the actual scripts (send-request.ts, e2e-test.sh, generate-config.ts). - Sidebar: concepts -> tutorial -> operator (agent + dashboard) -> contract developers -> reference; intro's path table leads with the tutorial. Build passes with link checking; screenshots in static/img/noosphere/.
…side A second sequence diagram right after the on-chain lifecycle — same agent, none of the protocol contracts: 402 terms -> signed USDC.e authorization -> verify -> run container -> settle -> response. Plus a four-row contrast table (who asks / contracts involved / payment / how results return) and the single deep link to /x402/sell-from-an-agent. Seeing both flows next to each other is the clearest statement of what 'separate rail' means.
A public manual must not link readers into a 404. noosphere-starter-app is currently PRIVATE on GitHub; removed its row from the pieces table (restore it if/when the repo goes public). Verified no other page in noosphere/, x402/, or docs/ links a private hpp-io repo.
… get a real path Two structural fixes from review: - 'Run an agent' category contained a doc of the same name — now the category holds distinctly-named steps: 'Set up the node' (the setup shared by both rails, ending in an explicit Choose-your-rail fork) and 'Serve the compute network' (the on-chain rail: funding, the earning loop, participation levels, earning-loop troubleshooting). - Operators who only want per-call selling had no path — the category now carries a 'Sell per-call (x402) ↗' sidebar link straight to /x402/sell-from-an-agent (detail stays owned there; no duplication), and node-setup's fork table sends each rail to its guide. - Tutorial relabeled 'first on-chain request' (honest scope) and its next-steps table names /x402/sell-from-an-agent as the x402 counterpart tutorial. Inbound links updated (intro, x402 guide). Build passes with link checking.
…— Docker install to both rails, with screenshots and a flow GIF Rebuilt the tutorial from an actual zero-to-finish run on HPP Sepolia (fresh clone -> Docker agent -> first x402 sale -> first on-chain delivery). Every command, transcript, address, tx hash, and screenshot in the page happened: - Part 1: Docker install — cast wallet new -> init (keystore import) -> the real minimal config.docker.json -> docker up -> real startup logs -> fresh-dashboard + seller-zero screenshots - Part 2: x402 — the buyer example paid the tutorial agent /bin/zsh.001 USDC.e (settle tx 0x304020…); response receipt shown verbatim; seller-tab screenshot with the job - Part 3: on-chain — setup:wallet (discovered REQUIRED: deliveries revert InvalidWallet without a factory-made payment wallet), consumer deploy, the four-tx cast ceremony (wallet -> approve -> subscribe -> request), agent delivery in 12ms at block 295109, Events/History screenshots, on-chain outputHash readback; honest notes on delivery races (a prod agent won an earlier request) and on compiling the consumer against the deployed protocol version - A 3-frame GIF shows the dashboard progressing fresh -> first sale -> first delivery - Accuracy fixes fed back into Set-up-the-node (init imports a key, not generates) and Serve-the-compute-network (new one-time setup:wallet step with the InvalidWallet explanation) Build passes with link checking.
…e zero-setup entry point A hosted browser dApp on HPP Sepolia now exists that exercises the protocol end to end — on-chain LLM chat (create a compute subscription, ask, receive the callback answer) and NoosphereVRF raffle/dice. Wired it in as the first rung of the ladder: - Overview: 'Try it in your browser first' section with a screenshot, and a zero-setup row leading the Choose-your-path table - Tutorial: a want-a-feel-first tip up top - Request compute on-chain: 'see it live' note — the playground's chat is exactly this client pattern behind a UI - How it works: VRF section points at the live raffle/dice Site link only (the app's repository is private).
… earns its place Review caught the page showing near-identical screens repeatedly: the header GIF cycled the same three dashboards that then reappeared as statics, the delivered-state dashboard was visually identical to the fresh one (only the Events numbers differ), the seller-zero shot carried almost no information, and the history capture was half whitespace. - Dropped the GIF and the seller-zero screenshot (text covers it) - The delivery moment is now a tight crop of just the Scheduler/Events cards (Completed: 1) instead of a third full-dashboard shot - Computing History cropped to the table - Honest caption for the Failed/Skipped leftovers from the capture session (one being the delivery race explained in 3.5) Four images remain, each showing something the previous ones don't: fresh dashboard -> seller tab with the paid job -> events completing -> history table.
- how-it-works: lifecycle diagram corrected — inputs stay stored on the client (requestCompute note + sendRequest(subId, interval)), agents pull via getComputeInputs; payment section = first valid delivery wins, budget feeAmount x executions - request-onchain-compute: minimal client rewritten to the deployed interface — 7-arg createSubscription (no redundancy, real routeId) and era _receiveCompute with PayloadData payloads; params table and trust levels updated; note that repo main targets the next protocol version - intro / serve-compute-network: dropped redundancy wording (deployed protocol has single-delivery, first-valid-wins semantics)
Compile-verified the minimal client verbatim against the deployed v1.0.0 sources — the ComputeClient base declares typeAndVersion() abstract, so the example did not compile without it.
Fact-check against noosphere-agent-js source, deployed contracts, the registry, and a live agent run: - configuration: chain block now matches the real AgentConfig (routerAddress/coordinatorAddress/deploymentBlock/processingInterval), keystorePath is a file path, paymentAddress semantics corrected (generator writes zero address; setup:wallet fills it — nothing defaults to the agent EOA); added scheduler/retry/containerExecution; payload defaults (ipfs, 1024); no-schema-validation warning - node-setup: generate:config transcript and startup logs replaced with real captured output (previous blocks were paraphrased) - registry-and-deployments: removed non-existent RegistryManager .getDeployment(); routeId guidance inverted — bytes32(0) has no default route, sendRequest reverts CoordinatorNotFound - how-it-works: callback is invoked by the Router (not Coordinator); protocol fee comes out of feeAmount, not on top - first-request: buyer part rebuilt on public packages (sample repo is private); faucet + USDC.e funding path in prereqs; noosphere-evm clone pinned to the deployed protocol commit 80bce17; $WALLET and $SUB now extracted from receipts (verified live); compute-wallet terminology - sell-from-an-agent: payTo requirement stated (keystore EOA is never a payout fallback); discovery signing comment corrected
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a Noosphere documentation section (new docs instance at
/noosphere, navbar entry).Contents
Commands, outputs, and screenshots come from a real run on HPP Sepolia; code samples and addresses were verified against the deployed contracts.
docusaurus build(including the broken-link check) passes.