@oracle-agent/oracle 0.2.0 → 0.2.1

package/public/oracle-splash/mesh-graph.svg

@@ -0,0 +1,216 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1400 900" width="1400" height="900">
+  <defs>
+    <style>
+      @import url('https://fonts.googleapis.com/css2?family=Cormorant+Garamond:ital,wght@0,400;0,500;1,400;1,500&amp;family=Outfit:wght@300;400;500&amp;family=IBM+Plex+Mono:wght@400;500&amp;display=swap');
+    </style>
+    <radialGradient id="bg" cx="50%" cy="35%" r="70%">
+      <stop offset="0%" stop-color="#111925"/>
+      <stop offset="45%" stop-color="#0B1018"/>
+      <stop offset="100%" stop-color="#070b10"/>
+    </radialGradient>
+    <radialGradient id="orb1" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#7CC4FF" stop-opacity="0.18"/>
+      <stop offset="55%" stop-color="#7CC4FF" stop-opacity="0.04"/>
+      <stop offset="100%" stop-color="#7CC4FF" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="orb2" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#50D2C1" stop-opacity="0.10"/>
+      <stop offset="100%" stop-color="#50D2C1" stop-opacity="0"/>
+    </radialGradient>
+    <pattern id="grid" width="48" height="48" patternUnits="userSpaceOnUse">
+      <path d="M 48 0 L 0 0 0 48" fill="none" stroke="rgba(124,196,255,0.06)" stroke-width="1"/>
+    </pattern>
+    <linearGradient id="panelStroke" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="rgba(124,196,255,0.28)"/>
+      <stop offset="100%" stop-color="rgba(124,196,255,0.08)"/>
+    </linearGradient>
+    <linearGradient id="cardFill" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" stop-color="#152031"/>
+      <stop offset="100%" stop-color="#111925"/>
+    </linearGradient>
+    <filter id="softGlow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="8" result="b"/>
+      <feMerge>
+        <feMergeNode in="b"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+    <filter id="nodeGlow" x="-40%" y="-40%" width="180%" height="180%">
+      <feGaussianBlur stdDeviation="4" result="b"/>
+      <feMerge>
+        <feMergeNode in="b"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+    <marker id="ah-blue" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#7CC4FF"/>
+    </marker>
+    <marker id="ah-poly" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#3B82F6"/>
+    </marker>
+    <marker id="ah-hl" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#50D2C1"/>
+    </marker>
+    <marker id="ah-rh" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#d7ff4d"/>
+    </marker>
+    <marker id="ah-sol" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#9945FF"/>
+    </marker>
+    <marker id="ah-btc" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#F0B90B"/>
+    </marker>
+    <marker id="ah-mute" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto">
+      <path d="M0,0 L8,4 L0,8 Z" fill="#5B738F"/>
+    </marker>
+  </defs>
+
+  <!-- page bg -->
+  <rect width="1400" height="900" fill="url(#bg)"/>
+  <rect width="1400" height="900" fill="url(#grid)"/>
+  <ellipse cx="700" cy="420" rx="520" ry="280" fill="url(#orb1)"/>
+  <ellipse cx="980" cy="620" rx="280" ry="180" fill="url(#orb2)"/>
+
+  <!-- ========== brand top-left (oracle) ========== -->
+  <g id="brand">
+    <circle cx="52" cy="48" r="7" fill="#7CC4FF" filter="url(#softGlow)"/>
+    <circle cx="52" cy="48" r="3.2" fill="#0B1018"/>
+    <text x="70" y="54" fill="#E8F1FA" font-family="Outfit, system-ui, sans-serif" font-size="26" font-weight="400" letter-spacing="-0.3">oracle</text>
+    <text x="52" y="78" fill="#5B738F" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" letter-spacing="1.8">MULTI-PROFILE MESH  ·  POWERED BY HERMES</text>
+  </g>
+
+  <!-- right meta -->
+  <text x="1350" y="48" fill="#5B738F" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" text-anchor="end" letter-spacing="1.5">FOR USERS</text>
+  <text x="1350" y="68" fill="#9BB6D1" font-family="Outfit, system-ui, sans-serif" font-size="13" text-anchor="end">graph · customizable · add agents</text>
+
+  <!-- ========== main glass panel ========== -->
+  <rect x="48" y="110" width="1304" height="730" rx="22" fill="#111925" fill-opacity="0.72" stroke="url(#panelStroke)" stroke-width="1.2"/>
+  <!-- panel header bar -->
+  <rect x="48" y="110" width="1304" height="52" rx="22" fill="#152031" fill-opacity="0.9"/>
+  <rect x="48" y="140" width="1304" height="22" fill="#152031" fill-opacity="0.9"/>
+  <text x="72" y="142" fill="#7CC4FF" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="11" letter-spacing="1.6">FOR USERS</text>
+  <text x="700" y="142" fill="#9BB6D1" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="11" text-anchor="middle" letter-spacing="1.6">MULTI-PROFILE // CUSTOMIZABLE</text>
+  <text x="1328" y="142" fill="#5B738F" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="11" text-anchor="end" letter-spacing="1.4">POWERED BY HERMES</text>
+
+  <!-- pills -->
+  <g font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" letter-spacing="1.2">
+    <rect x="72" y="182" width="128" height="28" rx="14" fill="none" stroke="rgba(124,196,255,0.28)" stroke-width="1"/>
+    <text x="136" y="200" fill="#A7D8FF" text-anchor="middle">MULTI PROFILES</text>
+    <rect x="210" y="182" width="128" height="28" rx="14" fill="none" stroke="rgba(124,196,255,0.28)" stroke-width="1"/>
+    <text x="274" y="200" fill="#A7D8FF" text-anchor="middle">CUSTOMIZABLE</text>
+    <rect x="348" y="182" width="112" height="28" rx="14" fill="none" stroke="rgba(124,196,255,0.28)" stroke-width="1"/>
+    <text x="404" y="200" fill="#A7D8FF" text-anchor="middle">ADD AGENTS</text>
+    <rect x="470" y="182" width="118" height="28" rx="14" fill="none" stroke="rgba(124,196,255,0.28)" stroke-width="1"/>
+    <text x="529" y="200" fill="#A7D8FF" text-anchor="middle">MORE CHAINS</text>
+    <rect x="598" y="182" width="148" height="28" rx="14" fill="none" stroke="rgba(124,196,255,0.28)" stroke-width="1"/>
+    <text x="672" y="200" fill="#A7D8FF" text-anchor="middle">POWERED BY HERMES</text>
+  </g>
+
+  <!-- ========== connectors (behind nodes) ========== -->
+  <!-- input -> oracle -->
+  <line x1="700" y1="310" x2="700" y2="360" stroke="#7CC4FF" stroke-width="2.5" marker-end="url(#ah-blue)" filter="url(#nodeGlow)"/>
+  <line x1="700" y1="310" x2="700" y2="360" stroke="#7CC4FF" stroke-width="10" stroke-opacity="0.12"/>
+
+  <!-- oracle hub fan-out to profiles -->
+  <!-- poly left -->
+  <path d="M620 450 C560 450 420 450 280 520" fill="none" stroke="#3B82F6" stroke-width="2" marker-end="url(#ah-poly)"/>
+  <path d="M620 450 C560 450 420 450 280 520" fill="none" stroke="#3B82F6" stroke-width="8" stroke-opacity="0.10"/>
+  <!-- hl center-left -->
+  <path d="M660 470 C640 500 560 520 500 560" fill="none" stroke="#50D2C1" stroke-width="2" marker-end="url(#ah-hl)"/>
+  <path d="M660 470 C640 500 560 520 500 560" fill="none" stroke="#50D2C1" stroke-width="8" stroke-opacity="0.10"/>
+  <!-- rh center -->
+  <line x1="700" y1="470" x2="700" y2="560" stroke="#d7ff4d" stroke-width="2" marker-end="url(#ah-rh)"/>
+  <line x1="700" y1="470" x2="700" y2="560" stroke="#d7ff4d" stroke-width="8" stroke-opacity="0.10"/>
+  <!-- sol center-right -->
+  <path d="M740 470 C760 500 840 520 900 560" fill="none" stroke="#9945FF" stroke-width="2" marker-end="url(#ah-sol)"/>
+  <path d="M740 470 C760 500 840 520 900 560" fill="none" stroke="#9945FF" stroke-width="8" stroke-opacity="0.10"/>
+  <!-- btc right -->
+  <path d="M780 450 C860 450 1000 450 1120 520" fill="none" stroke="#F0B90B" stroke-width="2" marker-end="url(#ah-btc)"/>
+  <path d="M780 450 C860 450 1000 450 1120 520" fill="none" stroke="#F0B90B" stroke-width="8" stroke-opacity="0.10"/>
+  <!-- builder bottom -->
+  <path d="M700 470 C700 510 700 640 700 680" fill="none" stroke="#5B738F" stroke-width="1.5" stroke-dasharray="4 4" marker-end="url(#ah-mute)"/>
+
+  <!-- ========== 01 INPUT / COMMAND ========== -->
+  <g filter="url(#nodeGlow)">
+    <rect x="575" y="230" width="250" height="80" rx="14" fill="url(#cardFill)" stroke="rgba(124,196,255,0.35)" stroke-width="1.2"/>
+    <text x="700" y="258" fill="#5B738F" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" text-anchor="middle" letter-spacing="1.6">YOU</text>
+    <text x="700" y="282" fill="#E8F1FA" font-family="Outfit, system-ui, sans-serif" font-size="18" font-weight="500" text-anchor="middle">Input / Command</text>
+    <text x="700" y="300" fill="#9BB6D1" font-family="Outfit, system-ui, sans-serif" font-size="12" font-weight="300" text-anchor="middle">what you type or ask</text>
+  </g>
+
+  <!-- ========== 02 CONTROL PLANE · oracle ========== -->
+  <g filter="url(#nodeGlow)">
+    <rect x="520" y="360" width="360" height="110" rx="16" fill="url(#cardFill)" stroke="rgba(124,196,255,0.45)" stroke-width="1.4"/>
+    <rect x="520" y="360" width="360" height="110" rx="16" fill="rgba(124,196,255,0.04)"/>
+    <text x="700" y="392" fill="#7CC4FF" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" text-anchor="middle" letter-spacing="1.8">CONTROL PLANE</text>
+    <text x="700" y="424" fill="#E8F1FA" font-family="Cormorant Garamond, Georgia, serif" font-size="34" font-weight="500" font-style="italic" text-anchor="middle">oracle</text>
+    <text x="700" y="450" fill="#9BB6D1" font-family="Outfit, system-ui, sans-serif" font-size="12" font-weight="300" text-anchor="middle">route  ·  bound  ·  evolve</text>
+  </g>
+
+  <!-- ========== 03 PROFILE CARDS ========== -->
+  <!-- polymarket -->
+  <g>
+    <rect x="80" y="520" width="260" height="130" rx="16" fill="#111925" stroke="rgba(59,130,246,0.45)" stroke-width="1.2"/>
+    <rect x="80" y="520" width="260" height="130" rx="16" fill="rgba(59,130,246,0.06)"/>
+    <text x="100" y="548" fill="#3B82F6" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" letter-spacing="1.6">PROFILE</text>
+    <text x="100" y="578" fill="#A7D8FF" font-family="Outfit, system-ui, sans-serif" font-size="18" font-weight="500">polymarket agent</text>
+    <text x="100" y="600" fill="#9BB6D1" font-family="Outfit, system-ui, sans-serif" font-size="12" font-weight="300">events · arb · markets</text>
+    <rect x="100" y="618" width="100" height="20" rx="10" fill="none" stroke="rgba(59,130,246,0.35)"/>
+    <text x="150" y="632" fill="#7CC4FF" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="9" text-anchor="middle">Polymarket</text>
+  </g>
+
+  <!-- hyperliquid -->
+  <g>
+    <rect x="370" y="560" width="260" height="130" rx="16" fill="#111925" stroke="rgba(80,210,193,0.45)" stroke-width="1.2"/>
+    <rect x="370" y="560" width="260" height="130" rx="16" fill="rgba(80,210,193,0.06)"/>
+    <text x="390" y="588" fill="#50D2C1" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" letter-spacing="1.6">PROFILE</text>
+    <text x="390" y="618" fill="#A8F0E6" font-family="Outfit, system-ui, sans-serif" font-size="18" font-weight="500">hyperliquid agent</text>
+    <text x="390" y="640" fill="#9BB6D1" font-family="Outfit, system-ui, sans-serif" font-size="12" font-weight="300">perps · hip-3/4 · ta</text>
+    <rect x="390" y="658" width="170" height="20" rx="10" fill="none" stroke="rgba(80,210,193,0.35)"/>
+    <text x="475" y="672" fill="#50D2C1" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="9" text-anchor="middle">Hyperliquid · HyperEVM 999</text>
+  </g>
+
+  <!-- robinhood -->
+  <g>
+    <rect x="660" y="560" width="260" height="130" rx="16" fill="#111925" stroke="rgba(215,255,77,0.40)" stroke-width="1.2"/>
+    <rect x="660" y="560" width="260" height="130" rx="16" fill="rgba(215,255,77,0.05)"/>
+    <text x="680" y="588" fill="#d7ff4d" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" letter-spacing="1.6">PROFILE</text>
+    <text x="680" y="618" fill="#EAF7B0" font-family="Outfit, system-ui, sans-serif" font-size="18" font-weight="500">robinhood agent</text>
+    <text x="680" y="640" fill="#9BB6D1" font-family="Outfit, system-ui, sans-serif" font-size="12" font-weight="300">markets · nfts · names</text>
+    <rect x="680" y="658" width="150" height="20" rx="10" fill="none" stroke="rgba(215,255,77,0.35)"/>
+    <text x="755" y="672" fill="#d7ff4d" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="9" text-anchor="middle">Robinhood Chain 4663</text>
+  </g>
+
+  <!-- solana -->
+  <g>
+    <rect x="950" y="560" width="200" height="130" rx="16" fill="#111925" stroke="rgba(153,69,255,0.45)" stroke-width="1.2"/>
+    <rect x="950" y="560" width="200" height="130" rx="16" fill="rgba(153,69,255,0.06)"/>
+    <text x="970" y="588" fill="#9945FF" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" letter-spacing="1.6">PROFILE</text>
+    <text x="970" y="618" fill="#D4B3FF" font-family="Outfit, system-ui, sans-serif" font-size="18" font-weight="500">solana agent</text>
+    <text x="970" y="640" fill="#9BB6D1" font-family="Outfit, system-ui, sans-serif" font-size="12" font-weight="300">jup · nfts · dexs</text>
+    <rect x="970" y="658" width="70" height="20" rx="10" fill="none" stroke="rgba(153,69,255,0.35)"/>
+    <text x="1005" y="672" fill="#c4a0ff" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="9" text-anchor="middle">Solana</text>
+  </g>
+
+  <!-- bitcoin (top-right of profile row) -->
+  <g>
+    <rect x="1160" y="520" width="160" height="130" rx="16" fill="#111925" stroke="rgba(240,185,11,0.40)" stroke-width="1.2"/>
+    <rect x="1160" y="520" width="160" height="130" rx="16" fill="rgba(240,185,11,0.05)"/>
+    <text x="1180" y="548" fill="#F0B90B" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" letter-spacing="1.6">PROFILE</text>
+    <text x="1180" y="578" fill="#F8E29A" font-family="Outfit, system-ui, sans-serif" font-size="18" font-weight="500">bitcoin</text>
+    <text x="1180" y="600" fill="#9BB6D1" font-family="Outfit, system-ui, sans-serif" font-size="12" font-weight="300">ord · runes</text>
+    <rect x="1180" y="618" width="50" height="20" rx="10" fill="none" stroke="rgba(240,185,11,0.35)"/>
+    <text x="1205" y="632" fill="#F0B90B" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="9" text-anchor="middle">BTC</text>
+  </g>
+
+  <!-- protocol builder -->
+  <g>
+    <rect x="520" y="710" width="360" height="72" rx="14" fill="#111925" stroke="rgba(124,196,255,0.22)" stroke-width="1" stroke-dasharray="5 4"/>
+    <text x="700" y="738" fill="#5B738F" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" text-anchor="middle" letter-spacing="1.6">BUILDER</text>
+    <text x="700" y="762" fill="#E8F1FA" font-family="Outfit, system-ui, sans-serif" font-size="16" font-weight="400" text-anchor="middle">protocol builder  ·  gated templates  ·  user-signed deploy</text>
+  </g>
+
+  <!-- footer -->
+  <text x="72" y="870" fill="#5B738F" font-family="Outfit, system-ui, sans-serif" font-size="12" font-weight="300">oracle routes input/command across a live multi-profile desk. profiles evolve. chains get added. not one bot.</text>
+  <text x="1328" y="870" fill="#3a6f99" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" text-anchor="end">self-custody · prepare → local sign</text>
+</svg>

package/scripts/protocol-template-gate.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { listProtocolTemplates, runProtocolTemplateGate } from "../src/protocol-templates/gate.mjs";
+
+const id = process.argv[2];
+if (!id || id === "list") {
+  console.log(JSON.stringify(listProtocolTemplates(), null, 2));
+  process.exit(0);
+}
+try {
+  const r = runProtocolTemplateGate(id, { allowSkipStatic: process.env.REQUIRE_SLITHER !== "1" });
+  console.log(JSON.stringify(r, null, 2));
+} catch (e) {
+  console.error(String(e.message || e));
+  process.exit(1);
+}

package/skills/oracle-protocol-builder/SKILL.md

@@ -1,38 +1,59 @@
 ---
 name: oracle-protocol-builder
-description: Use when the user wants Oracle to act as a builder: scaffold contracts/apps, prepare unsigned deploys, and create launch runbooks.
+description: Use when the user wants Oracle to scaffold/deploy protocol templates. Gated Foundry templates; prepare-only deploy; not a firm audit.
 ---
 
 # Protocol builder
 
-Oracle can be a builder, not only a trader/analyzer. The boundary stays the same:
-it writes and prepares; the user signs and deploys.
+Oracle scaffolds and **prepares unsigned deploys**. The user signs. Custody boundary unchanged.
 
-## Builder modes
+## Security gate (v1)
 
-- scaffold contracts and tests
-- scaffold mint/gacha/claim pages
-- build DEX/pool/router integrations
-- write deploy and verify scripts
-- produce unsigned deploy or admin transactions
-- create launch runbooks and monitoring dashboards
-- audit authority, upgradeability, fees, and emergency controls
+Before any template deploy prepare:
 
-## Required order
+1. `forge test` must pass on the template
+2. Slither runs when installed (optional skip if missing; set `REQUIRE_SLITHER=1` to hard-require)
+3. JS `runProtocolTemplateGate` / `prepareTemplateDeploy` refuse otherwise
 
-1. Authority model: owner, admin, upgrader, pauser, treasury, withdrawer.
-2. Threat model: what can go wrong and who can rug or halt.
-3. Tests: caps, payments, roles, upgrades, withdrawals, randomness, routing.
-4. Simulation: deploy, initialize, and first user action.
-5. Prepare: unsigned artifact only, bound to chain and destination.
-6. Receipt: deployed address, source verification, event logs, and state readback.
+```js
+// list
+data.call("protocol-templates", "list")
+// gate
+data.call("protocol-templates", "gate", { templateId: "safe-erc20" })
+// unsigned deploy prepare (stamped)
+data.call("protocol-templates", "prepareDeploy", {
+  templateId: "safe-erc20",
+  chainId: 8453,
+  args: [name, symbol, supply, initialHolder, initialOwner],
+})
+```
 
-## Refusal line
+CLI: `npm run protocol:gate -- safe-erc20`
+
+## Shipped template: `safe-erc20`
+
+- Fixed supply, mint once in constructor (no hidden mint)
+- Ownable2Step + pause
+- No tax / blacklist / max-tx / upgrade proxy
+- Foundry tests included
+
+## Honesty
 
-Refuse hidden drains, honeypots, wash-trading systems, undisclosed tax switches,
-fake TVL, or any contract whose main purpose is deceiving buyers.
+**Reviewed templates + automated tests ≠ paid Solidity audit.**
 
-## Output standard
+Docs and prepare envelopes always set `firmAudit: false` and carry the disclaimer.
+Mainnet TVL → independent firm audit.
+
+## Required order (custom work)
+
+1. Authority model  
+2. Threat model  
+3. Tests (Foundry)  
+4. Static analysis when available  
+5. Gate green  
+6. Prepare unsigned only  
+7. User signs + verify source  
+
+## Refusal line
 
-Lead with the authority model and irreversible choices. Then the file plan or
-artifact. End with the exact tests/simulations run and what remains unverified.
+Refuse hidden drains, honeypots, wash-trading systems, undisclosed tax switches, fake TVL, or any contract whose main purpose is deceiving buyers.

package/src/data/catalog.mjs

@@ -59,6 +59,15 @@ registerProvider({
   description: "Hyperliquid public /info",
 });
 
+registerProvider({
+  id: "protocol-templates",
+  venue: "protocol-builder",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "list", "gate", "prepareDeploy"],
+  description: "Gated Safe* Solidity templates: forge test required before unsigned deploy prepare. NOT a firm audit.",
+});
+
 registerProvider({
   id: "poly-public",
   venue: "poly",

package/src/data/desk-data.mjs

@@ -29,6 +29,8 @@ import * as hlstake from "./providers/hl-staking.mjs";
 import * as hlmarkets from "./providers/hl-markets.mjs";
 import * as hloutcome from "./providers/hl-outcome.mjs";
 import * as polyclob from "./providers/poly-clob.mjs";
+import * as protoTpl from "../protocol-templates/prepare-deploy.mjs";
+import { listProtocolTemplates, runProtocolTemplateGate } from "../protocol-templates/gate.mjs";
 import * as hlperps from "./providers/hl-perps.mjs";
 import * as gecko from "./providers/geckoterminal.mjs";
 import * as curve from "./providers/curve.mjs";
@@ -218,6 +220,12 @@ const OPS = {
     prepareOrder: (o, a = {}) => hloutcome.hlPrepareOutcomeOrder(a, o),
     prepareCancel: (o, a = {}) => hloutcome.hlPrepareOutcomeCancel(a, o),
   },
+  "protocol-templates": {
+    health: () => ({ ok: true, templates: listProtocolTemplates().map((t) => t.id), firmAudit: false }),
+    list: () => listProtocolTemplates(),
+    gate: (o, a = {}) => runProtocolTemplateGate(a.templateId || a.id, o),
+    prepareDeploy: (o, a = {}) => protoTpl.prepareTemplateDeploy(a, o),
+  },
   "poly-clob": {
     prepareOrder: (o, a = {}) => {
       // prepare is sync; wrap for dataCall

package/src/protocol-templates/gate.mjs

@@ -0,0 +1,179 @@
+// Protocol template security gate.
+// Refuse prepare-deploy unless Foundry tests are green.
+// Static analysis (slither) is required when available; otherwise documented skip.
+// This is NOT a substitute for a paid Solidity firm audit.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+
+const HERE = fileURLToPath(new URL(".", import.meta.url));
+const PKG_ROOT = resolve(HERE, "../..");
+const TEMPLATES_ROOT = join(PKG_ROOT, "protocols", "templates");
+
+export const TEMPLATE_AUDIT_DISCLAIMER =
+  "Template + Foundry tests + optional static analysis. NOT a paid security-firm audit. Do not put mainnet TVL on forks without an independent Solidity audit.";
+
+export function listProtocolTemplates() {
+  if (!existsSync(TEMPLATES_ROOT)) return [];
+  return readdirSync(TEMPLATES_ROOT)
+    .filter((name) => statSync(join(TEMPLATES_ROOT, name)).isDirectory())
+    .map((id) => {
+      const dir = join(TEMPLATES_ROOT, id);
+      const security = join(dir, "SECURITY.md");
+      return {
+        id,
+        path: dir,
+        securityNotice: existsSync(security) ? readFileSync(security, "utf8").slice(0, 500) : null,
+        disclaimer: TEMPLATE_AUDIT_DISCLAIMER,
+      };
+    });
+}
+
+function forgeBin() {
+  if (process.env.FORGE_BIN) return process.env.FORGE_BIN;
+  const home = process.env.HOME || "";
+  const candidates = ["forge", join(home, ".foundry/bin/forge")];
+  for (const c of candidates) {
+    const r = spawnSync(c, ["--version"], { encoding: "utf8" });
+    if (r.status === 0) return c;
+  }
+  return null;
+}
+
+function slitherBin() {
+  if (process.env.SLITHER_BIN) return process.env.SLITHER_BIN;
+  const r = spawnSync("slither", ["--version"], { encoding: "utf8" });
+  return r.status === 0 ? "slither" : null;
+}
+
+function run(cmd, args, cwd) {
+  const r = spawnSync(cmd, args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, PATH: `${process.env.HOME || ""}/.foundry/bin:${process.env.PATH || ""}` },
+    timeout: 120_000,
+  });
+  return {
+    ok: r.status === 0,
+    status: r.status,
+    stdout: r.stdout || "",
+    stderr: r.stderr || "",
+  };
+}
+
+function hashTree(dir) {
+  const h = createHash("sha256");
+  function walk(p) {
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      if (["lib", "out", "cache", ".git"].includes(p.split("/").pop())) return;
+      for (const name of readdirSync(p).sort()) walk(join(p, name));
+    } else if (st.isFile() && (p.endsWith(".sol") || p.endsWith(".toml") || p.endsWith(".md"))) {
+      h.update(p);
+      h.update(readFileSync(p));
+    }
+  }
+  walk(dir);
+  return h.digest("hex");
+}
+
+/**
+ * Run security gate on a template id.
+ * @param {string} templateId e.g. "safe-erc20"
+ * @param {{ allowSkipStatic?: boolean }} opts
+ */
+export function runProtocolTemplateGate(templateId, opts = {}) {
+  const allowSkipStatic = opts.allowSkipStatic !== false; // default allow skip if no slither
+  const dir = join(TEMPLATES_ROOT, templateId);
+  if (!existsSync(dir)) {
+    throw new Error(`protocol-templates: unknown template "${templateId}"`);
+  }
+
+  const forge = forgeBin();
+  if (!forge) {
+    throw new Error(
+      "protocol-templates: forge not found. Install Foundry (https://getfoundry.sh) then: cd protocols/templates/" +
+        templateId +
+        " && forge install && forge test"
+    );
+  }
+
+  // ensure libs (not vendored in git)
+  if (!existsSync(join(dir, "lib", "forge-std"))) {
+    const a = run(forge, ["install", "foundry-rs/forge-std", "--no-git"], dir);
+    if (!a.ok) throw new Error(`protocol-templates: forge install forge-std failed\n${a.stderr}`);
+  }
+  if (!existsSync(join(dir, "lib", "openzeppelin-contracts"))) {
+    const b = run(forge, ["install", "OpenZeppelin/openzeppelin-contracts@v5.0.2", "--no-git"], dir);
+    if (!b.ok) throw new Error(`protocol-templates: forge install openzeppelin failed\n${b.stderr}`);
+  }
+
+  const tests = run(forge, ["test", "-q"], dir);
+  if (!tests.ok) {
+    throw new Error(
+      `protocol-templates: forge test FAILED for ${templateId}\n${tests.stdout}\n${tests.stderr}`.slice(0, 2000)
+    );
+  }
+
+  let staticAnalysis = { tool: null, ok: true, skipped: true, reason: "slither not installed" };
+  const slither = slitherBin();
+  if (slither) {
+    const s = run(slither, [".", "--filter-paths", "lib", "--exclude-dependencies"], dir);
+    staticAnalysis = {
+      tool: "slither",
+      ok: s.ok,
+      skipped: false,
+      stdout: (s.stdout || "").slice(0, 1500),
+      stderr: (s.stderr || "").slice(0, 500),
+    };
+    if (!s.ok && !opts.allowStaticFail) {
+      throw new Error(`protocol-templates: slither FAILED for ${templateId}\n${s.stdout}\n${s.stderr}`.slice(0, 2000));
+    }
+  } else if (!allowSkipStatic) {
+    throw new Error("protocol-templates: slither required (allowSkipStatic=false) but not installed");
+  }
+
+  const sourceHash = hashTree(dir);
+  return {
+    ok: true,
+    templateId,
+    path: dir,
+    forgeTests: { ok: true, tool: "forge", summary: "forge test passed" },
+    staticAnalysis,
+    sourceHash,
+    disclaimer: TEMPLATE_AUDIT_DISCLAIMER,
+    firmAudit: false,
+  };
+}
+
+/**
+ * Build artifact after gate. Returns bytecode for unsigned deploy prepare.
+ */
+export function buildProtocolTemplate(templateId, opts = {}) {
+  const gate = runProtocolTemplateGate(templateId, opts);
+  const forge = forgeBin();
+  const dir = gate.path;
+  const build = run(forge, ["build", "-q"], dir);
+  if (!build.ok) {
+    throw new Error(`protocol-templates: forge build failed\n${build.stderr}`.slice(0, 1500));
+  }
+  // default contract name heuristic
+  const contractName = opts.contractName || (templateId === "safe-erc20" ? "SafeERC20" : null);
+  if (!contractName) throw new Error("protocol-templates: contractName required");
+  const artifactPath = join(dir, "out", `${contractName}.sol`, `${contractName}.json`);
+  if (!existsSync(artifactPath)) {
+    throw new Error(`protocol-templates: artifact missing at ${artifactPath}`);
+  }
+  const artifact = JSON.parse(readFileSync(artifactPath, "utf8"));
+  return {
+    gate,
+    contractName,
+    abi: artifact.abi,
+    bytecode: artifact.bytecode?.object || artifact.bytecode,
+    deployedBytecode: artifact.deployedBytecode?.object || artifact.deployedBytecode,
+    artifactPath,
+  };
+}

package/src/protocol-templates/prepare-deploy.mjs

@@ -0,0 +1,81 @@
+// Prepare unsigned deploy for a gated protocol template.
+// Never signs. Never broadcasts. Requires green forge tests first.
+
+import { ContractFactory, isAddress } from "ethers";
+import { stampPrepared } from "../prepare-envelope.mjs";
+import { buildProtocolTemplate, listProtocolTemplates, TEMPLATE_AUDIT_DISCLAIMER } from "./gate.mjs";
+
+export { listProtocolTemplates, TEMPLATE_AUDIT_DISCLAIMER };
+
+/**
+ * @param {object} args
+ * @param {string} args.templateId - e.g. safe-erc20
+ * @param {number} args.chainId
+ * @param {string[]} [args.constructorArgs] - ABI-encoded via ethers from values
+ * @param {any[]} [args.args] - constructor JS values (preferred)
+ * @param {string} [args.contractName]
+ */
+export async function prepareTemplateDeploy(args = {}, opts = {}) {
+  const templateId = String(args.templateId || "").trim();
+  if (!templateId) throw new Error("prepareTemplateDeploy: templateId required");
+  const chainId = Number(args.chainId);
+  if (!Number.isInteger(chainId) || chainId <= 0) {
+    throw new Error("prepareTemplateDeploy: chainId required");
+  }
+
+  const built = buildProtocolTemplate(templateId, {
+    contractName: args.contractName,
+    allowSkipStatic: opts.allowSkipStatic !== false,
+    allowStaticFail: opts.allowStaticFail === true,
+  });
+
+  if (!built.bytecode || built.bytecode === "0x") {
+    throw new Error("prepareTemplateDeploy: empty bytecode");
+  }
+
+  const bc = built.bytecode.startsWith("0x") ? built.bytecode : `0x${built.bytecode}`;
+  const ctorArgs = args.args ?? args.constructorArgs ?? [];
+  const factory = new ContractFactory(built.abi, bc);
+  const deployTx = await factory.getDeployTransaction(...(Array.isArray(ctorArgs) ? ctorArgs : []));
+  const data = deployTx.data;
+
+  // validate SafeERC20 constructor shape if applicable
+  if (templateId === "safe-erc20" && Array.isArray(ctorArgs)) {
+    const [name, symbol, supply, holder, owner] = ctorArgs;
+    if (!name || !symbol) throw new Error("safe-erc20: name/symbol required");
+    if (supply == null || BigInt(supply) <= 0n) throw new Error("safe-erc20: supply must be > 0");
+    if (!isAddress(String(holder))) throw new Error("safe-erc20: initialHolder must be address");
+    if (!isAddress(String(owner))) throw new Error("safe-erc20: initialOwner must be address");
+  }
+
+  return stampPrepared(
+    {
+      provider: "protocol-templates",
+      kind: "template-deploy",
+      templateId,
+      contractName: built.contractName,
+      chainId,
+      transaction: {
+        chainId,
+        to: null, // creation
+        data,
+        value: "0x0",
+      },
+      abi: built.abi,
+      bytecodeHash: built.gate.sourceHash,
+      gate: {
+        forgeTests: built.gate.forgeTests,
+        staticAnalysis: {
+          tool: built.gate.staticAnalysis.tool,
+          ok: built.gate.staticAnalysis.ok,
+          skipped: built.gate.staticAnalysis.skipped,
+        },
+        firmAudit: false,
+        disclaimer: TEMPLATE_AUDIT_DISCLAIMER,
+      },
+      requiresUserSignature: true,
+      note: "Unsigned deploy. User wallet signs. Template tests passed; not a firm audit.",
+    },
+    { provider: "protocol-templates", kind: "template-deploy" }
+  );
+}