Skip to content

Commit ce307b6

Browse files
JulioMCruzJulioMCruz
authored
docs: rewrite README + refresh llms.txt for the current solution (#37)
README now reflects the live two-sided market: credit-balance model, fee waterfall (75/20/5), multi-chain (Base+Celo, payment-chain=earning-chain), x402 deposits via PerkOS Stack, PerkosClaimVault pull-claims, and the $PERKOS monthly usage drop. Adds three Mermaid diagrams (system architecture, the economic loop, the month-end drop sequence), agent usage (curl + plugin), an endpoint reference table, and tokenomics/claim sections. llms.txt: frame the claim as USDC earnings + a monthly $PERKOS usage drop (5% accrued -> month-end buyback -> distributed by usage); note the plugin sets payChain + emits a 402 top-up hint.
1 parent 3cfb3d0 commit ce307b6

2 files changed

Lines changed: 234 additions & 91 deletions

File tree

‎App/public/llms.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ Privacy boundary: private organization records are ACL-protected and sensitive o
3030
- **Exemptions:** whitelisted agents (PerkOS internal / research) query for free.
3131
- **Insufficient funds:** `POST /skill/query` returns HTTP `402` `{ "creditError": "insufficient_credit", "balance", "price" }`; a paid tier with no wallet returns `{ "creditError": "wallet_required" }`. Top up via `/api/deposit` on the chain you're querying.
3232
- **Check balance / earnings:** `GET /api/credits/{wallet}` (authorized wallets; includes a `byChain` breakdown) or the [dashboard](https://knowledge.perkos.xyz/dashboard).
33-
- **Claim earnings (pull):** provider USDC earnings + the $PERKOS reward are claimed on-chain from the [dashboard](https://knowledge.perkos.xyz/dashboard) — the platform posts a per-chain Merkle root to the `PerkosClaimVault` (same address on Base + Celo) and you `claim()` what you're owed per chain. `GET /api/claims/{wallet}` returns your entry + proof per chain.
33+
- **Claim earnings (pull):** provider USDC earnings (the 75% split) **plus a monthly $PERKOS usage drop** — the 5% reward accrues per chain and at month end is market-bought into $PERKOS and distributed proportional to your total usage (spent + earned) — are claimed on-chain from the [dashboard](https://knowledge.perkos.xyz/dashboard). The platform posts a per-chain Merkle root to the `PerkosClaimVault` (same address on Base + Celo) and you `claim(account, cumUsdc, cumReward, proof)` what you're owed per chain. `GET /api/claims/{wallet}` returns your entry + proof per chain.
3434

3535
## Consume knowledge (ask / request)
3636

@@ -54,7 +54,7 @@ You earn credits whenever knowledge you contributed is consumed by a paid query
5454

5555
## Easiest path: the plugin
5656

57-
The **PerkOS-Knowledge-Plugin** (OpenClaw + Hermes runtimes) wraps all of the above as native tools — `perkos_knowledge_query`, `perkos_knowledge_submit_research`, `perkos_knowledge_requests_list`, `perkos_knowledge_request_{create,claim,fulfill,validate}`, `perkos_x402_policy` — and sets the identity headers from `KNOWLEDGE_AGENT_WALLET` / `KNOWLEDGE_AGENT_ID`.
57+
The **PerkOS-Knowledge-Plugin** (OpenClaw + Hermes + MCP runtimes) wraps all of the above as native tools — `perkos_knowledge_query`, `perkos_knowledge_submit_research`, `perkos_knowledge_requests_list`, `perkos_knowledge_request_{create,claim,fulfill,validate}`, `perkos_x402_policy` — sets the identity headers from `KNOWLEDGE_AGENT_WALLET` / `KNOWLEDGE_AGENT_ID`, picks the pay-chain from `KNOWLEDGE_PAY_CHAIN` (or per-call `payChain`), and turns a billing `402` into a plain-language top-up hint.
5858

5959
## Optional
6060

‎README.md‎

Lines changed: 232 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,267 @@
11
# PerkOS Knowledge
22

3-
Live paid knowledge skill for AI agents.
3+
**A two-sided, agent-native knowledge market.** Agents **consume** curated PerkOS/Web3 research by querying it — paying per query from a **prepaid USDC credit balance** — and **provide** knowledge by contributing research, **earning** credits whenever their contribution answers someone else's paid query. Multi-chain on **Base and Celo** (payment-chain = earning-chain). Live at **[knowledge.perkos.xyz](https://knowledge.perkos.xyz)**.
44

5-
PerkOS Knowledge is a remote, always-updated knowledge service where agents can query curated PerkOS/Web3 research and pay per use through x402 on Base, Celo, and Solana.
5+
It is like an AgentSkill, but live and paid:
66

7-
## Core idea
7+
- a local skill = static instructions/tools installed with an agent
8+
- PerkOS Knowledge = a remote paid skill/API with fresh, indexed, source-cited knowledge
89

9-
It is like an AgentSkill, but live:
10+
Agents keep their own LLM/runtime (PerkOS Ollama, OpenAI, Anthropic, local — anything); PerkOS Knowledge only returns ranked context.
1011

11-
- local skill = static instructions/tools installed with an agent
12-
- PerkOS Knowledge = remote paid skill/API with fresh indexed knowledge
12+
---
1313

14-
Agents call it when they need context, briefs, or custom research.
15-
16-
## Architecture
14+
## 1. System architecture
1715

1816
```mermaid
1917
flowchart LR
2018
subgraph Producers["Knowledge producers"]
21-
ResearchJobs["Research ingestion jobs"]
22-
Curators["Human and agent curation"]
19+
PA["Provider agents"]
20+
Cur["Human + agent curation"]
2321
end
2422
25-
subgraph Ingest["Ingestion layer"]
26-
Sync["Research sync worker"]
27-
IngestAPI["POST /api/ingest/research"]
28-
Sanitizer["Sanitization boundary"]
23+
subgraph Ingest["Ingestion + sanitization"]
24+
Ing["POST /api/ingest/research"]
25+
San["Sanitization boundary<br/>(private-by-default)"]
2926
end
3027
31-
subgraph App["Next.js App Router"]
32-
Landing["Landing page"]
33-
Search["GET/POST /knowledge/search"]
34-
Vector["GET/POST /knowledge/vector-search"]
35-
Briefs["GET /knowledge/brief/:agent"]
36-
Dashboard["/dashboard"]
37-
Admin["/admin"]
38-
Usage["GET /api/usage/:wallet"]
39-
Stats["GET /api/stats"]
40-
Health["/healthz and /api/health"]
41-
LLM["llms.txt and llms-full.txt"]
28+
subgraph App["Next.js App · knowledge.perkos.xyz"]
29+
Q["POST /skill/query<br/>(the paid entry point)"]
30+
Srch["/knowledge/search<br/>/knowledge/vector-search"]
31+
Dep["POST /api/deposit<br/>(x402 top-up)"]
32+
Acct["GET /api/credits/:wallet<br/>GET /api/claims/:wallet"]
33+
UI["/dashboard · /admin"]
34+
Contract["llms.txt · /skill/manifest<br/>/api/x402/policy"]
4235
end
4336
4437
subgraph Data["Private data services"]
45-
Postgres["Postgres research_items"]
46-
Qdrant["Qdrant vector index"]
38+
PG[("Postgres")]
39+
QD[("Qdrant vectors")]
4740
end
4841
49-
subgraph Access["Access and payment layer"]
50-
WalletGate["Wallet allowlist"]
51-
X402["x402 paid access roadmap"]
52-
Rails["Base, Celo, and Solana rails"]
42+
subgraph Money["Monetization layer"]
43+
Ledger["credit_ledger<br/>per (wallet, chain)"]
44+
Water["fee waterfall<br/>75 / 20 / 5"]
45+
Pool["reward_pool<br/>(5% accrues)"]
46+
Vault["PerkosClaimVault<br/>(same addr Base + Celo)"]
5347
end
5448
55-
subgraph Consumers["Consumers"]
56-
InternalAgents["PerkOS agents"]
57-
ExternalAgents["External autonomous agents"]
58-
Humans["Humans and operators"]
49+
subgraph Rails["x402 settlement"]
50+
Stack["PerkOS Stack facilitator"]
51+
Base[("Base USDC")]
52+
Celo[("Celo USDC")]
5953
end
6054
61-
ResearchJobs --> Sync --> IngestAPI --> Sanitizer
62-
Curators --> Sanitizer
63-
Sanitizer --> Postgres
64-
Sanitizer --> Qdrant
65-
66-
Postgres --> Search
67-
Postgres --> Briefs
68-
Postgres --> Stats
69-
Qdrant --> Vector
70-
71-
Landing --> LLM
72-
WalletGate --> Dashboard
73-
WalletGate --> Usage
74-
X402 --> Rails
75-
X402 -. protects paid endpoints .-> Search
76-
X402 -. protects paid endpoints .-> Vector
77-
X402 -. protects paid endpoints .-> Briefs
78-
79-
Search --> InternalAgents
80-
Vector --> InternalAgents
81-
Briefs --> InternalAgents
82-
LLM --> ExternalAgents
83-
Landing --> Humans
84-
Dashboard --> Humans
85-
Admin --> Humans
86-
Health --> Humans
55+
PA --> Ing --> San
56+
Cur --> San
57+
San --> PG & QD
58+
59+
PG --> Q & Srch
60+
QD --> Srch
61+
62+
Consumers["Consumer agents"] --> Q
63+
Contract --> Consumers
64+
65+
Q --> Ledger --> Water
66+
Water --> Pool
67+
Dep --> Stack --> Base & Celo
68+
Stack --> Ledger
69+
70+
Water -.->|"provider 75%"| Vault
71+
Pool -.->|"monthly $PERKOS drop"| Vault
72+
Vault --> Acct
73+
Ledger --> Acct
74+
75+
classDef money fill:#0b3,stroke:#063,color:#fff;
76+
class Ledger,Water,Pool,Vault,Stack money;
77+
```
78+
79+
**Privacy boundary:** private-by-default. Public responses are sanitized and source-cited; organization records are ACL-protected. Internal memory, credentials, infra notes, and wallet secrets are never indexed into public outputs.
80+
81+
---
82+
83+
## 2. The economic loop (how money moves)
84+
85+
Every paid query splits the charged amount through a **fee waterfall**, accrues a small reward, and pays providers through a **pull-based** claim vault. Nothing is pushed — participants `claim()` what they're owed.
86+
87+
```mermaid
88+
flowchart TD
89+
C(["Consumer agent"]) -->|"POST /skill/query · pays on Base or Celo"| DEB["Debit prepaid credits<br/>(402 if balance too low)"]
90+
DEB --> WF{{"Fee waterfall<br/>(admin-tunable, live at /api/x402/policy)"}}
91+
WF -->|"75%"| PROV["Provider earnings<br/>(split across answering items)"]
92+
WF -->|"20%"| PLAT["Platform revenue"]
93+
WF -->|"5%"| POOL["reward_pool<br/>(per chain)"]
94+
95+
PROV --> ROOT["Per-chain Merkle root<br/>posted to the vault"]
96+
POOL -->|"month end"| DROP["$PERKOS monthly usage drop"]
97+
DROP --> ROOT
98+
ROOT --> VAULT[("PerkosClaimVault")]
99+
VAULT -->|"claim(cumUsdc, cumReward, proof)"| WALLET([" Provider / user wallet "])
100+
101+
TOP(["Human or agent"]) -->|"POST /api/deposit (x402, gasless USDC)"| DEB
102+
103+
classDef money fill:#0b3,stroke:#063,color:#fff;
104+
class DEB,WF,PROV,POOL,DROP,VAULT,WALLET money;
105+
```
106+
107+
- **Provider earnings (USDC, 75%)** are split equally across the items that answered a paid query → attributed → claimable on the same chain the consumer paid on.
108+
- **Platform (20%)** funds operations.
109+
- **Reward (5%)** accrues per chain in `reward_pool` and becomes the monthly **$PERKOS usage drop** (next section).
110+
- Tiers and the exact split are **authoritative live at `/api/x402/policy`** — never hardcode them.
111+
112+
---
113+
114+
## 3. The $PERKOS monthly usage drop
115+
116+
The 5% reward is **not a refund** — at month end it becomes a **$PERKOS drop earned for using the platform**, distributed proportional to total usage. Design + runbook: [`docs/PERKOS-REWARDS-BUYBACK-DESIGN.md`](docs/PERKOS-REWARDS-BUYBACK-DESIGN.md).
117+
118+
```mermaid
119+
sequenceDiagram
120+
autonumber
121+
participant Op as Operator (treasury 0x3f0D)
122+
participant API as Knowledge API
123+
participant Uni as Uniswap Trading API
124+
participant Vault as PerkosClaimVault
125+
participant User as User wallet
126+
127+
Note over Op,API: scripts/monthly-drop.mjs --chain=base/celo --apply
128+
Op->>API: GET /api/admin/rewards/drop (budget + quote)
129+
API-->>Op: budget = Σ reward_pool (this month, chain)
130+
Op->>Uni: swap budget USDC → $PERKOS (Base v3 / Celo v4)
131+
Uni-->>Op: $PERKOS bought
132+
Op->>API: POST /api/admin/rewards/distribute (perkosBought)
133+
Note right of API: 40% stays with platform · 60% to users by usage<br/>(spent + earned) → token_rewards
134+
Op->>API: POST /api/admin/claims/build (per-chain Merkle root)
135+
Op->>Vault: transfer user $PERKOS + setMerkleRoot(root)
136+
Op->>API: POST /api/admin/claims/mark-posted
137+
User->>Vault: claim() → receives USDC earnings + $PERKOS drop
138+
```
139+
140+
- **Budget** = the 5% accrued that month, per chain. Scales purely with usage.
141+
- **Buyback** is a single monthly market-buy via the **Uniswap Trading API** (one flow covers Base v3 + Celo v4).
142+
- **Split:** `rewardPlatformBps` (default **40%**, admin-editable) stays with the platform; **60%** drops to users by `activity = USDC spent + USDC earned`.
143+
- The **orchestrator** [`App/scripts/monthly-drop.mjs`](App/scripts/monthly-drop.mjs) chains every leg. Dry-run by default; `--apply` sends real txs (the treasury signer needs native gas per chain).
144+
145+
```bash
146+
cd App
147+
node scripts/monthly-drop.mjs --chain=base # DRY-RUN: budget + quote + split
148+
node scripts/monthly-drop.mjs --chain=base --apply # swap → distribute → root → fund → post → mark-posted
149+
node scripts/monthly-drop.mjs --chain=celo --apply
87150
```
88151

89-
## Current public endpoints
152+
---
90153

91-
- `GET /` — public landing page for humans and agents.
92-
- `GET /llms.txt` — concise agent-readable index.
93-
- `GET /llms-full.txt` — expanded agent-readable context.
94-
- `GET /healthz` — service health check.
95-
- `GET /api/health` — JSON API health check.
96-
- `GET /knowledge/search?q=...` — keyword search over ingested research in Postgres.
97-
- `POST /knowledge/search` — JSON keyword search.
98-
- `GET /knowledge/vector-search?q=...` — vector search over ingested research in Qdrant.
99-
- `POST /knowledge/vector-search` — JSON vector search.
100-
- `GET /knowledge/brief/:agent` — role-specific brief generated from ingested research.
101-
- `GET /api/providers/manifest` — provider-agent contribution contract.
102-
- `GET /dashboard` — wallet-gated user dashboard.
103-
- `GET /admin` — operator dashboard with research and system stats.
104-
- `GET /api/stats` — research item aggregations.
105-
- `GET /api/usage/:wallet` — wallet-scoped usage/access scaffold.
154+
## 4. Using it as an agent
106155

107-
## Structure
156+
The fastest path is the **[PerkOS Knowledge Plugin](https://github.com/PerkOS-xyz/PerkOS-Knowledge-Plugin)** (OpenClaw, Hermes, MCP, AgentSkill) — it wraps every endpoint below as native tools and sets your identity headers. For raw HTTP:
108157

109-
- `App/` — Next.js App Router app: marketing site, API routes, admin UI, internal/external knowledge endpoints.
110-
- `Contracts/` — smart contracts, payment adapters, x402 settlement notes, chain config.
111-
- `docs/` — architecture, cost analysis, product notes.
112-
- `scripts/` — ingestion and sync utilities.
158+
**Consume (ask):**
113159

114-
## Privacy boundary
160+
```bash
161+
curl -X POST https://knowledge.perkos.xyz/skill/query \
162+
-H 'content-type: application/json' \
163+
-H 'x-agent-wallet: 0xYourWallet' \
164+
-H 'x-payment-chain: base' \
165+
-d '{"query":"Base smart wallet gas sponsorship","limit":8,"tier":"public","createRequestOnMiss":true}'
166+
```
167+
168+
Returns ranked, source-cited context for **your own LLM**. `public` is free; paid tiers debit your prepaid balance and return HTTP `402` (`insufficient_credit` / `wallet_required`) if you can't pay.
169+
170+
**Top up (x402, gasless USDC):**
171+
172+
```bash
173+
curl -X POST https://knowledge.perkos.xyz/api/deposit \
174+
-H 'content-type: application/json' \
175+
-d '{"wallet":"0xYourWallet","amount":"1","network":"base"}'
176+
# → HTTP 402 with `accepts`; sign the EIP-3009 authorization and retry.
177+
# Settled via PerkOS Stack (stack.perkos.xyz). `creditTo` lets a human fund an agent's wallet.
178+
```
179+
180+
**Check balance / earnings / claim:**
181+
182+
```bash
183+
curl https://knowledge.perkos.xyz/api/credits/0xYourWallet # balance + byChain breakdown
184+
curl https://knowledge.perkos.xyz/api/claims/0xYourWallet # claimable USDC + $PERKOS per chain, with proof
185+
```
186+
187+
Claim on-chain from the **[dashboard](https://knowledge.perkos.xyz/dashboard)** (`PerkosClaimVault.claim(account, cumUsdc, cumReward, proof)`, same vault address on Base + Celo).
188+
189+
**Provide (earn):** answer open requests (`GET /knowledge/requests?status=open` → `claim` → `fulfill` → `validate`) or submit directly (`POST /api/ingest/research`). You earn credits whenever your evidenced, validated research answers a future paid query.
190+
191+
> **Pick the chain:** `POST /skill/query` reads `payChain` from body `payChain`/`chain` or header `x-payment-chain` (`base`|`celo`, default `base`). You spend that chain's balance and the provider earns there — deposit on the chain you want to transact on.
192+
193+
---
194+
195+
## 5. Endpoint reference
196+
197+
| Group | Endpoint | Notes |
198+
|---|---|---|
199+
| **Contract** | `GET /llms.txt`, `/llms-full.txt` | Agent-readable index (read at runtime) |
200+
| | `GET /skill/manifest` | Capabilities, auth headers, visibility model |
201+
| | `GET /api/x402/policy` | **Authoritative** live prices + payment mode |
202+
| **Consume** | `POST /skill/query` | Paid, ranked, source-cited context + quality metadata |
203+
| | `GET\|POST /knowledge/search` | Keyword / BM25 |
204+
| | `GET\|POST /knowledge/vector-search` | Semantic (Qdrant) |
205+
| | `GET /knowledge/brief/:agent` | Role-specific brief |
206+
| **Pay** | `POST /api/deposit` | x402 top-up (Base + Celo USDC via PerkOS Stack) |
207+
| | `GET /api/credits/:wallet` | Balance + earnings, `byChain` |
208+
| | `GET /api/claims/:wallet` | Claimable USDC + $PERKOS drop + Merkle proof, per chain |
209+
| **Provide** | `POST /api/ingest/research` | Submit sanitized + evidenced research |
210+
| | `GET /knowledge/requests?status=open` | Open requests to claim/fulfill/validate |
211+
| **Ops** | `/dashboard` · `/admin` | Wallet-gated user + operator UIs |
212+
| | `/healthz` · `/api/health` | Health checks |
213+
| | `POST /api/admin/rewards/{drop,distribute}` | Monthly drop (admin) |
214+
| | `POST /api/admin/claims/{build,mark-posted}` | Per-chain Merkle root (admin) |
115215

116-
PerkOS Knowledge is private-by-default. Public endpoints should expose only sanitized, intentional content. Internal memory, credentials, infrastructure notes, wallet secrets, raw logs, and private operational data must not be indexed into public outputs.
216+
---
217+
218+
## 6. Tokenomics & claim model
219+
220+
- **Fee waterfall** — provider **75%** / platform **20%** / $PERKOS reward **5%**, stored in a `tokenomics_config` row and editable from `/admin/billing` (no redeploy). Tiers: `public` (free) / `private` / `premium` / `enterprise` (validated-only). Prices live at `/api/x402/policy`.
221+
- **Per-chain, no double-pay** — earnings *and* balances are segregated by the chain the consumer paid on. A provider claims Base earnings on Base, Celo earnings on Celo.
222+
- **`PerkosClaimVault`** — a UUPS cumulative-Merkle distributor custodying USDC (earnings) + $PERKOS (drop). Deployed at the **same proxy `0xC609BB99C9CAc2b10cc7796b96d0a2EDf2B6f589` on both Base and Celo**. Role split: **owner** (governance) ≠ **distributor `0x3f0D…`** (treasury — posts roots, funds the vault). Off-chain half is [`App/lib/claim.ts`](App/lib/claim.ts) (`@openzeppelin/merkle-tree`, leaf byte-identical to the contract).
223+
224+
---
225+
226+
## 7. Agent roles
227+
228+
- **Consumer** — queries public or org-private context (pays per query).
229+
- **Requester** — turns missing context into an open request instead of guessing (`createRequestOnMiss`).
230+
- **Provider** — claims requests, submits sanitized + evidenced research, earns credits on consumption.
231+
- **Validator** — reviews evidence and trust state before higher-confidence reuse.
232+
233+
Quality controls on `POST /skill/query`: `qualityMode` (`standard` | `enterprise` ≥45 confidence | `validated_only`), `minConfidence`, `requireValidated`. Responses carry `validationStatus`, `confidencePercent`, `trustTier`, `qualityReasons` — disclose low/pending/untrusted context, don't treat it as final fact.
234+
235+
---
236+
237+
## 8. Structure
238+
239+
| Path | What |
240+
|---|---|
241+
| `App/` | Next.js App Router: site, API routes, admin/dashboard UI, `lib/` (credits, tokenomics, claim, payments, rewardsDrop, uniswapTrade) |
242+
| `App/scripts/monthly-drop.mjs` | Month-end $PERKOS usage-drop orchestrator |
243+
| `App/public/llms.txt` | Agent-facing contract served at `/llms.txt` |
244+
| `Contracts/` | `PerkosClaimVault` (Solidity, UUPS) + operator scripts (`claim-publish.sh`, `vault-fund.sh`) |
245+
| `docs/` | Architecture, tokenomics, rewards/buyback design, cost analysis |
246+
247+
---
248+
249+
## 9. Local development
250+
251+
```bash
252+
cd App
253+
npm ci
254+
npm run dev # Next dev server
255+
npm test # vitest run (lib unit tests)
256+
npm run build # production build
257+
```
117258

118-
## Provider agents
259+
**Deploy** is self-hosted (Caddy → Next standalone + Postgres + Qdrant on the PerkOS VPS, **not** Vercel): `rsync App/ → /opt/perkos-knowledge/app/` then `docker compose -f docker-compose.yml build app && up -d`. Secrets live in the VPS `.env` (never rsync'd).
119260

120-
Approved research agents can contribute knowledge as provider agents after admin onboarding. Providers submit to `POST /api/ingest/research` with `x-agent-id`, optional wallet/ERC-8004 identity headers, organization membership, and research scopes. Submissions default to private; `public_candidate` items are stored private with review required before publication.
261+
---
121262

122-
Agents and operators should start with `docs/agent-integration-overview.md` for the complete consumer/requester/provider/validator process and the reading order across the Knowledge server and PerkOS Tech Plugin repositories.
263+
## See also
123264

124-
See `docs/provider-agent-integration.md` for the provider onboarding and contribution contract.
265+
- [`docs/agent-integration-overview.md`](docs/agent-integration-overview.md) — full consumer/requester/provider/validator process.
266+
- [`docs/provider-agent-integration.md`](docs/provider-agent-integration.md) — provider onboarding + contribution contract.
267+
- [PerkOS Knowledge Plugin](https://github.com/PerkOS-xyz/PerkOS-Knowledge-Plugin) — drop-in tools for OpenClaw / Hermes / MCP.

0 commit comments

Comments
 (0)