superfluid-org · kasparkallas · Mar 24, 2026 · Mar 23, 2026 · Mar 24, 2026 · Mar 24, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -12,7 +12,7 @@
       "name": "superfluid",
       "source": "./",
       "description": "Superfluid Protocol & ecosystem knowledge base — references, tools, and integration guides for real-time finance on EVM chains",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "author": {
         "name": "Kaspar Kallas",
         "email": "superfluid@kasparkallas.com"

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "superfluid",
   "description": "Superfluid Protocol & ecosystem knowledge base — references, tools, and integration guides for real-time finance on EVM chains",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": {
     "name": "Kaspar Kallas",
     "email": "superfluid@kasparkallas.com"

diff --git a/.vault/Home.md b/.vault/Home.md
@@ -16,6 +16,12 @@ Project vault for the Superfluid Protocol Claude Code skill (`superfluid-org/ski
 
 ## Resolved Tickets
 
+- [[T047-add-brand-design-guide]] -- Add brand design guide (color palette, typography, visual identity)
+- [[T046-smart-contract-patterns-evals]] -- Add eval cases for smart contract patterns guide
+- [[T045-smart-contract-patterns-guide]] -- Add smart contract patterns guide, GDA gotchas, skill corrections
+- [[T044-torex-deep-research]] -- Add TOREX deep research and eval cases
+- [[T043-deep-research-eval-cases]] -- Add eval cases for semantic money and GDA scalability deep researches
+- [[T042-semantic-money-gda-deep-researches]] -- Add Semantic Money yellowpaper and GDA scalability deep researches
 - [[T041-selector-sidecars]] -- Add selector sidecar files, refine guides and eval cases
 - [[T040-update-sdk-0.2.0-yield-backend]] -- Update to @sfpro/sdk 0.2.0 with yield backend and SUP contracts
 - [[T039-add-ecosystem-deep-researches]] -- Add 5 ecosystem deep researches (Planet IX, Nerite, SuperBoring, Giveth, Streme)
@@ -64,14 +70,16 @@ Project vault for the Superfluid Protocol Claude Code skill (`superfluid-org/ski
 - [[rich-abi-yaml-alignment]] -- Alignment with ABI JSON, NatSpec, and ethers.js
 - [[deep-research-guide]] -- Deep-research authoring guide and prompt template
 - [[The-Complete-Guide-to-Building-Skill-for-Claude.pdf]] -- Anthropic's official skill-building guide (PDF)
+- [[semantic-money-yellowpaper1.pdf]] -- Semantic Money yellowpaper (formal payment primitives)
+- [[torex-paper.pdf]] -- TOREX research paper (streaming DEX mechanics)
 
 ## Quick Reference
 
 - **Skill entry**: `skills/superfluid/SKILL.md`
 - **Contracts**: `skills/superfluid/references/contracts/` (22 Rich ABI YAMLs + 24 selector sidecars + format spec)
 - **Subgraphs**: `skills/superfluid/references/subgraphs/` (query-patterns, 6 `.graphql` schemas, 5 usage guides)
-- **Guides**: `skills/superfluid/references/guides/` (architecture, super-apps, macro-forwarders, sdks, scripts, api-services, sup-and-dao, flowing-balances)
-- **Deep researches**: `skills/superfluid/references/deep-researches/` (9 ecosystem deep-dives)
+- **Guides**: `skills/superfluid/references/guides/` (architecture, super-apps, smart-contract-patterns, macro-forwarders, sdks, scripts, api-services, sup-and-dao, flowing-balances, brand-design)
+- **Deep researches**: `skills/superfluid/references/deep-researches/` (12 ecosystem deep-dives)
 - **Scripts**: `skills/superfluid/scripts/` (`metadata.mjs`, `tokenlist.mjs`, `balance.mjs`, `abi.mjs`, `selectors.mjs`)
 - **Evals**: `evals/` (script tests + skill evals)
 - **Landing page**: `landing-page/index.html` (Vercel-deployed static page)

diff --git a/.vault/resources/semantic-money-yellowpaper1.pdf b/.vault/resources/semantic-money-yellowpaper1.pdf
diff --git a/.vault/resources/torex-paper.pdf b/.vault/resources/torex-paper.pdf
diff --git a/.vault/tickets/T042-semantic-money-gda-deep-researches.md b/.vault/tickets/T042-semantic-money-gda-deep-researches.md
@@ -0,0 +1,22 @@
+---
+status: done
+priority: normal
+tags: [skill, enhancement]
+created: 2026-03-24
+resolved: 2026-03-24
+---
+
+# T042 — Add Semantic Money and GDA scalability deep researches
+
+## Problem
+
+The skill documents *what* CFA and GDA do but not *why* they work mathematically. Developers asking about the formal specification, BasicParticle, settle-on-write, or GDA's O(1) scalability get no structured guidance. The Semantic Money yellowpaper and Haskell formal spec are not referenced.
+
+## Resolution
+
+1. Created `references/deep-researches/semantic-money-yellowpaper.md` (~505 lines) — covers payment system model, conservation of value, BasicParticle, index abstraction, agreement framework, FRP connection, real-time balance formula, buffer-based solvency, key Haskell modules, links to yellowpaper PDF and spec source
+2. Created `references/deep-researches/gda-scalability.md` (~395 lines) — covers the O(N) CFA problem, PDPoolIndex/PDPoolMember data structures, operation walkthroughs (distributeFlow, distribute, updateMemberUnits, connectPool, claimAll), rounding model with align2, universal index composition, settle-on-write, connected vs disconnected members, scalability summary, practical builder advice
+3. Added keywords (`semantic money, yellowpaper, whitepaper`) to SKILL.md frontmatter
+4. Added both files to ecosystem deep-dives and new "Formal specification and protocol theory" use-case map section
+5. Added cross-reference from GDA use-case section and GDA rounding gotcha to gda-scalability.md
+6. Added "Formal Foundations" section to architecture.md linking to yellowpaper deep research
diff --git a/.vault/tickets/T043-deep-research-eval-cases.md b/.vault/tickets/T043-deep-research-eval-cases.md
@@ -0,0 +1,20 @@
+---
+status: done
+priority: normal
+tags: [skill, enhancement]
+created: 2026-03-24
+resolved: 2026-03-24
+---
+
+# T043 — Add deep-research eval cases
+
+## Problem
+
+The two new deep researches (semantic-money-yellowpaper, gda-scalability) have no eval coverage to verify the skill correctly routes to and extracts information from them.
+
+## Resolution
+
+1. Added 2 correctness eval cases to `evals/cases/skill/correctness.cases.json`:
+   - `correct-basic-particle-rtb-formula` — tests BasicParticle formula and settle-on-write knowledge (targets yellowpaper research)
+   - `correct-gda-o1-scalability` — tests O(1) distribution via PDPoolIndex knowledge (targets GDA scalability research)
+2. Both cases scored 100% on initial run (sonnet gen + sonnet judge)
diff --git a/.vault/tickets/T044-torex-deep-research.md b/.vault/tickets/T044-torex-deep-research.md
@@ -0,0 +1,47 @@
+---
+status: done
+priority: medium
+tags: [skill, deep-research, enhancement]
+created: 2026-03-24
+resolved: 2026-03-24
+---
+
+# T044: Add TOREX deep research and eval cases
+
+Add a dedicated deep research covering the TOREX (TWAP Oracle Exchange) protocol mechanics, distinct from the existing `superboring.md` which covers the product layer.
+
+## Scope
+
+- New `torex.md` deep research (311 lines) covering:
+  - Core architecture (two event loops: money flow events + LMEs)
+  - TWAP Observer pattern (ITwapObserver, UniswapV3PoolTwapHoppableObserver)
+  - Liquidity Moving Event flow (7-step callback sequence)
+  - Discount model (shifted reciprocal f(v,t) = v * F/(F+t), τ/ε parameterization)
+  - Back adjustments (back charge for new streamers, back refund for departing)
+  - Controller hooks (ITorexController, fee safety, permission controls)
+  - MEV properties (trader protection via TWAP, mover exposure)
+  - Twin TOREX (Rich/Poor netting, shortfall-only swaps)
+  - Liquidity mover implementations (basic SwapRouter02 → advanced TwinTorexLM with 1inch/UniV3/V4/Balancer)
+  - Deployment addresses and key repos
+- New `torex.cases.json` with 3 eval cases (discount model, back adjustments, Twin TOREX) — 100% pass rate
+- Cross-references between `torex.md` and `superboring.md`
+- SKILL.md pointer under "Ecosystem deep-dives"
+
+## Sources
+
+- TOREX whitepaper (https://app.superboring.xyz/torexpaper, 8 pages)
+- averageX contracts repo (`/refs/averageX/`)
+- `superfluid-finance/torex-basic-liquidity-mover` (basic Uniswap V3 mover)
+- `superfluid-finance/liquidity-mover` (Twin TOREX + multi-DEX mover)
+
+## Resolution
+
+All files created and verified. Eval cases pass at 100%. Deep research count: 12 (was 11).
+
+### Files created
+- `skills/superfluid/references/deep-researches/torex.md`
+- `evals/cases/skill/torex.cases.json`
+
+### Files modified
+- `skills/superfluid/SKILL.md` — added TOREX pointer
+- `skills/superfluid/references/deep-researches/superboring.md` — added cross-reference to torex.md
diff --git a/.vault/tickets/T045-smart-contract-patterns-guide.md b/.vault/tickets/T045-smart-contract-patterns-guide.md
@@ -0,0 +1,31 @@
+---
+status: done
+priority: high
+tags: [guides, contracts, skill]
+created: 2026-03-24
+resolved: 2026-03-24
+---
+
+# T045 — Add smart contract patterns guide
+
+## Goal
+
+Create a practical patterns & gotchas guide for smart contract developers, distilled from 8 production repos and reference implementations. Make the AI better at generating correct Superfluid contracts.
+
+## Resolution
+
+Created `references/guides/smart-contract-patterns.md` (440 lines) with 6 sections:
+- **A. GDA Pool Patterns** — unit scaling, buffer funding (GDA has no app credit), defensive unit ops, pool config, per-member isolation
+- **B. Super App Callback Patterns** — flow splitting anatomy, context chaining, receiver validation, safe external calls, stream redirection
+- **C. Custom SuperToken Deployment** — Pure, Wrapper, SETH (pre-deployed), Bridged/xERC20, storage layout, atomic deployment
+- **D. Proxy & Factory Patterns** — Beacon, Create2, Clones, UUPS
+- **E. Automation / Public Operator Pattern** — ACL via CFAv1Forwarder + ERC-20 allowance, createFlowFrom/deleteFlowFrom, time-gated execution, delay compensation
+- **F. Stream-Based Access Control** — passive state query vs Super App, multiple payment tiers
+
+Also updated:
+- `SKILL.md` — added GDA buffer gotcha to Common Gotchas + routing entry under Building Super Apps
+- `GDAv1Forwarder.abi.yaml` — added GDA no-app-credit note on `distributeFlow`
+- `SuperfluidPool.abi.yaml` — corrected `decreaseMemberUnits` note (uint128 underflow, not rounding)
+- `super-apps.md` — added "App Credit Is CFA-Only" subsection
+
+Key correction during development: investigation of SuperfluidPool.sol revealed that `decreaseMemberUnits` does NOT fail due to "GDA rounding." Units are stored as plain uint128 — no rounding in store/retrieve. Banger's try/catch is defensive against their own accounting errors, not a protocol issue.
diff --git a/.vault/tickets/T046-smart-contract-patterns-evals.md b/.vault/tickets/T046-smart-contract-patterns-evals.md
@@ -0,0 +1,34 @@
+---
+status: done
+priority: high
+tags: [evals, contracts, skill]
+created: 2026-03-24
+resolved: 2026-03-24
+---
+
+# T046 — Add eval cases for smart contract patterns
+
+## Goal
+
+Write eval cases to verify the skill correctly teaches smart contract patterns, gotchas, and production knowledge from the new patterns guide.
+
+## Resolution
+
+Created `evals/cases/skill/smart-contract-patterns.cases.json` with 7 eval cases:
+
+| Case | Category | Tests |
+|------|----------|-------|
+| `gotcha-gda-no-app-credit` | gotchas | GDA has no app credit for CFA→GDA splitting |
+| `gotcha-gda-unit-scaling` | gotchas | flowRate/totalUnits truncation to zero |
+| `correct-automation-public-operator` | correctness | ACL + ERC-20 allowance dual permission pattern |
+| `correct-passive-vs-superapp` | correctness | Passive state query vs Super App |
+| `correct-custom-supertoken-types` | correctness | Pure / Wrapper / SETH / Bridged types |
+| `codegen-cfa-gda-splitter` | code-gen | CFA→GDA splitter with buffer funding |
+| `routing-smart-contract-patterns` | routing | Routes to patterns guide content |
+
+Iterative refinement over 3 eval runs:
+- Round 1: Identified incorrect rounding premise, overly strict criteria, prompt ambiguities
+- Round 2: Deleted invalid rounding case, fixed SETH/variant ambiguity, reframed automation as general pattern
+- Round 3: Fixed automation prompt to motivate ERC-20 approve, added getCFAFlowRate/getCFANetFlowRate to golden facts
+
+Final results: 5/7 pass at 100%. The `codegen-cfa-gda-splitter` case (30-60%) is a legitimate failure — the model's training overrides the skill's GDA no-app-credit documentation. This is the hardest test and correctly identifies a real knowledge gap.
diff --git a/.vault/tickets/T047-add-brand-design-guide.md b/.vault/tickets/T047-add-brand-design-guide.md
@@ -0,0 +1,15 @@
+---
+status: done
+priority: low
+tags: [skill, enhancement]
+created: 2026-03-24
+resolved: 2026-03-24
+---
+
+# T047 — Add brand design guide
+
+Add a brand/design reference guide with the Superfluid team's color palette, typography, and design characteristics so the AI can produce UIs in the Superfluid team's style when asked.
+
+## Resolution
+
+Created `references/guides/brand-design.md` with the full color palette (gray, brand green, error, warning, secondary pink/violet/blue), typography (GT Walsheim Pro + Open Sans alternative), design characteristics, external resource links, and app references. Added routing entry in SKILL.md under "Superfluid team brand & design." Scoped to Superfluid team products — not imposed on all UI work.
diff --git a/.vault/vision/roadmap.md b/.vault/vision/roadmap.md
@@ -1,5 +1,5 @@
 ---
-updated: 2026-03-23
+updated: 2026-03-24
 ---
 
 # Roadmap
@@ -17,7 +17,7 @@ The skill exists to solve these problems by giving AI direct, structured knowled
 
 ## Current Focus
 
-v1.0.0 released — comprehensive protocol skill with 22 contract references, 9 deep researches, flowing balances guide, evaluation suite, landing page, and plugin packaging.
+v1.1.0 released — formal specification deep researches, GDA scalability analysis, TOREX deep research, smart contract patterns guide. Next focus is tool selection guidance and task-oriented guides.
 
 ## Planned
 
@@ -30,6 +30,7 @@ v1.0.0 released — comprehensive protocol skill with 22 contract references, 9
 
 ## Completed
 
+- **v1.1.0** -- Semantic Money formal specification deep research: yellowpaper foundations, BasicParticle formula, index abstraction, agreement framework, FRP connection, Haskell spec walkthrough (T042). GDA scalability deep research: O(1) distribution via PDPoolIndex, operation walkthroughs, rounding model with align2, connected vs disconnected members, practical builder advice (T042). 2 new correctness eval cases for deep research routing (T043). TOREX deep research: streaming DEX mechanics, discount model, back adjustments, Twin TOREX, liquidity mover implementations, 3 eval cases (T044). Smart contract patterns guide: GDA pool patterns, Super App callbacks, custom SuperTokens, proxy/factory, automation/operator, stream access control — distilled from 8 production repos; GDA no-app-credit and decreaseMemberUnits corrections in ABI YAMLs; 7 eval cases (T045, T046). Cross-references, SKILL.md routing, Formal Foundations section in architecture.md. Brand design guide with color palette, typography, and visual identity for Superfluid team products (T047).
 - **v1.0.0** -- Flowing balances guide with framework-agnostic real-time balance display (T038). 5 ecosystem deep researches: Planet IX, Nerite, SuperBoring, Giveth, Streme (T039). ERC-8004 Agent Pool deep-research (T036). History, GoodDollar, Flow State deep researches and prompt guide (T035). Clear Signing preview, x402, Campaigns, social links (T034). Landing page with FAQ, OG tags, install instructions (T033). Release workflow and skill trigger keywords (T031). Plugin packaging with plugin.json (T037). Skill eval runner and evaluation test suite (T026, T024). SUP Token / Reserve System ABIs (T020). Per-subgraph usage guides (T018). Super Apps guide (T017). Version bump and .gitattributes export-ignore (T032, T030). Gotcha migration to notes fields (T029).
 - **v0.4.0** -- Subgraph query support: 4 GraphQL entity schemas (protocol-v1, vesting-scheduler, flow-scheduler, auto-wrap) and query-patterns guide in `references/subgraphs/` (T016). MacroForwarder guide with composable batch operations and EIP-712 signed macro example (T015). Renamed `.rich-abi.yaml` → `.abi.yaml` across all 17 reference files (T014). Added Graphinator sentinel and Token Prices API to ecosystem. Replaced marketplace install docs with skills.sh tutorial.
 - **v0.3.1** -- Code generation best practices: SDK address exports table, strengthened anti-hallucination ABI/address guidance, Whois endpoint clarification with GOTCHA (T013). Fix GDA celo-mainnet address typo (89355 → 89555).