@dev.sail.money/sailor 1.3.0-98 → 1.4.0-242

package/templates/default/.agents/skills/sail-templates/catalog.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// sail-templates / catalog.mjs
+// Tracks the shared permission templates that live in
+//   Protocol/contracts/templates/*.sol
+// These are configurable singletons (extend ConfigurablePermission): deploy once
+// per chain, then every SMA reuses that address via REGISTER + CONFIGURE (attach only
+// registers on the kernel; configure writes the per-account bounds — see SKILL.md).
+// All seven are deployed (2026-07-01, CREATE2 global salt) — same address on every chain.
+// Deployment status is read from deployed.json next to this file.
+//
+// The template LIST is auto-detected from source (so it tracks additions/removals),
+// the rich per-template detail is curated below, and deployment status is read from
+// deployed.json.
+//
+// Usage:
+//   node catalog.mjs                # human view, all detected templates
+//   node catalog.mjs --json         # machine-readable
+//   node catalog.mjs --chain 8453   # deployment status for one chain
+//   node catalog.mjs --protocol /path/to/Protocol   # override Protocol dir
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const CHAIN_NAMES = {
+  1: "Ethereum", 8453: "Base", 42161: "Arbitrum", 10: "Optimism", 130: "Unichain",
+  56: "BSC", 480: "World Chain", 999: "HyperEVM", 4326: "MegaETH",
+  84532: "Base Sepolia", 11155111: "Sepolia",
+};
+
+// Curated detail, keyed by the Solidity contract name. Config blobs are the
+// authoritative abi.encode tuples taken from each contract's `_applyConfig`.
+const META = {
+  SwapPermission: {
+    primitive: "DEX swaps (Uniswap V3 / V3-02 / V2)",
+    skill: "sail-template-swap",
+    config: "(address[] routers, address[] tokensIn, address[] tokensOut, uint256 maxAmountPerTx, uint256 maxSlippageBps, address priceOracle, uint256 maxPriceAgeSec)",
+  },
+  SwapPermissionNoOracle: {
+    primitive: "DEX swaps for tokens with NO oracle — live-pool hallucination band (NOT manipulation-resistant)",
+    skill: "sail-template-swap-no-oracle",
+    config: "(address[] routers, address[] tokensIn, address[] tokensOut, uint256 maxAmountPerTx, ReferencePool[] referencePools) — ReferencePool{address tokenIn, address tokenOut, address pool, PoolKind kind (0=V2,1=V3), uint256 toleranceBps}",
+  },
+  BorrowPermission: {
+    primitive: "Lending borrows (Aave / Morpho / Compound) with LTV check",
+    skill: "sail-template-borrow",
+    config: "(address[] protocols, address[] assets, uint256 maxAmountPerTx, uint256 maxLtvBps, address collateralOracle, address borrowOracle, uint256 maxPriceAgeSec)",
+  },
+  TransferPermission: {
+    primitive: "ERC-20 transfers to a recipient allowlist (from == account)",
+    skill: "sail-template-transfer",
+    config: "(address[] allowedRecipients, address[] allowedTokens, uint256 maxAmountPerTx)",
+  },
+  DepositPermission: {
+    primitive: "Vault / lending deposits (ERC-4626 + Aave v2/v3)",
+    skill: "sail-template-deposit",
+    config: "(address[] targets, address[] tokens, uint256 maxAmountPerTx)",
+  },
+  WithdrawPermission: {
+    primitive: "ERC-20 withdrawals to a single fixed recipient",
+    skill: "sail-template-withdraw",
+    config: "(address[] tokens, address allowedRecipient, uint256 maxAmountPerTx)",
+  },
+  ApproveAndCallBatchPermission: {
+    primitive: "Atomic approve / consuming-call / reset-to-zero batch",
+    skill: "sail-template-approve-batch",
+    config: "Config{ address[] tokens, address[] spenders, ConsumingPair[] consumingPairs /* (address target, bytes4 selector) */, uint256[] maxApprovalAmounts, bool requireAmountMatch, bool allowUnconstrainedRecipient /* default false = recipient pinned to account; true = opt out */ }",
+  },
+};
+
+function argValue(flag) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 ? process.argv[i + 1] : null;
+}
+const hasFlag = (flag) => process.argv.includes(flag);
+
+function findProtocolDir() {
+  const fromArg = argValue("--protocol");
+  if (fromArg) return resolve(fromArg);
+  if (process.env.SAIL_PROTOCOL_DIR) return resolve(process.env.SAIL_PROTOCOL_DIR);
+  for (const start of [process.cwd(), HERE]) {
+    let dir = start;
+    for (let i = 0; i < 8; i++) {
+      if (existsSync(join(dir, "Protocol", "contracts", "templates"))) return join(dir, "Protocol");
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return null;
+}
+
+// Detect concrete templates from source: `contract X is ... ConfigurablePermission ...`
+// (skips `abstract contract`, e.g. the ConfigurablePermission base itself).
+function detectTemplates(protocolDir) {
+  const dir = join(protocolDir, "contracts", "templates");
+  const out = [];
+  for (const file of readdirSync(dir).filter((f) => f.endsWith(".sol"))) {
+    const src = readFileSync(join(dir, file), "utf8");
+    const m = src.match(/^\s*contract\s+(\w+)\s+is\s+([^{]+)\{/m);
+    if (!m) continue;
+    if (!/ConfigurablePermission/.test(m[2])) continue;
+    out.push({ name: m[1], file: `contracts/templates/${file}` });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function loadDeployed() {
+  const path = join(HERE, "deployed.json");
+  if (!existsSync(path)) return { chains: {} };
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { chains: {} };
+  }
+}
+
+function statusFor(deployed, name) {
+  const rows = [];
+  for (const [chainId, map] of Object.entries(deployed.chains ?? {})) {
+    const addr = map?.[name];
+    rows.push({ chainId: Number(chainId), name: CHAIN_NAMES[chainId] ?? `chain ${chainId}`, address: addr ?? null });
+  }
+  return rows.sort((a, b) => a.chainId - b.chainId);
+}
+
+function main() {
+  const protocolDir = findProtocolDir();
+  if (!protocolDir) {
+    console.error("Could not locate Protocol/contracts/templates. Pass --protocol <path> or set SAIL_PROTOCOL_DIR.");
+    process.exit(1);
+  }
+  const templates = detectTemplates(protocolDir);
+  const deployed = loadDeployed();
+  const onlyChain = argValue("--chain");
+
+  const catalog = templates.map((t) => ({
+    ...t,
+    ...(META[t.name] ?? { primitive: "(uncurated — see source)", skill: null, config: "(see source)" }),
+    deployments: statusFor(deployed, t.name).filter((r) => !onlyChain || r.chainId === Number(onlyChain)),
+  }));
+
+  // IOracle adapters usable as `priceOracle` in SwapPermission config (deployed.json `oracles`).
+  const oracles = [];
+  for (const [chainId, byLabel] of Object.entries(deployed.oracles ?? {})) {
+    if (onlyChain && Number(chainId) !== Number(onlyChain)) continue;
+    for (const [label, o] of Object.entries(byLabel ?? {})) {
+      oracles.push({ chainId: Number(chainId), name: CHAIN_NAMES[chainId] ?? `chain ${chainId}`, label, ...o });
+    }
+  }
+
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify({ protocolDir, templates: catalog, oracles }, null, 2));
+    return;
+  }
+
+  console.log("Sail shared permission templates — source: Protocol/contracts/templates\n");
+  console.log("Model: configurable singletons. Deploy ONCE per chain, then every SMA reuses the");
+  console.log("address via register (`sailor mandate attach`) + configure (no per-SMA deploy).");
+  console.log("NOTE: `sailor mandate attach` registers ONLY — you must also configure per-account");
+  console.log("(configureDirect today); see SKILL.md / references/reuse-flow.md.\n");
+  const anyUncurated = catalog.some((t) => !META[t.name]);
+  for (const t of catalog) {
+    const flag = META[t.name] ? "" : "  ⚠️ NEW/uncurated — add to META + write a skill";
+    console.log(`━━ ${t.name}${flag} ━━`);
+    console.log(`   primitive: ${t.primitive}`);
+    console.log(`   source:    ${t.file}`);
+    if (t.skill) console.log(`   skill:     ${t.skill}`);
+    console.log(`   config:    ${t.config}`);
+    const live = t.deployments.filter((d) => d.address);
+    if (live.length) {
+      console.log("   deployed:");
+      for (const d of t.deployments) {
+        console.log(`     ${d.name} (${d.chainId}): ${d.address ?? "— not yet deployed"}`);
+      }
+    } else {
+      console.log("   deployed:  not yet on any tracked chain (record in deployed.json once deployed)");
+    }
+    console.log("");
+  }
+  if (oracles.length) {
+    console.log("━━ IOracle adapters (usable as SwapPermission `priceOracle`) ━━");
+    for (const o of oracles) {
+      const pairs = (o.pairs ?? []).map((p) => p.label ?? `${p.base}/${p.quote}`).join(", ");
+      console.log(`   ${o.label} (${o.name} ${o.chainId}): ${o.address}${o.default ? "  [default]" : ""}`);
+      console.log(`     kind: ${o.kind ?? "?"}${o.twapWindowSec ? `, twap=${o.twapWindowSec}s` : ""}, decimals: ${o.priceDecimals ?? "?"}, pairs: ${pairs || "?"}`);
+      if (o.note) console.log(`     ↳ ${o.note}`);
+    }
+    console.log("");
+  }
+  if (anyUncurated) {
+    console.log("⚠️  A source template has no curated metadata above — the source folder changed.");
+  }
+  console.log("⚠️  Shared templates are UNAUDITED EXAMPLES — not part of the trusted core.");
+  console.log("   Always `sailor mandate simulate` against your SMA before authorizing on-chain.");
+}
+
+main();

package/templates/default/.agents/skills/sail-templates/deployed.json

@@ -0,0 +1,133 @@
+{
+  "_comment": "Reuse registry for the shared permission templates in Protocol/contracts/templates. These are CONFIGURABLE SINGLETONS: deployed ONCE, then every SMA reuses that address via attach + configure (no per-SMA deploy). All seven templates bind to the current CREATE2 kernel 0x38b508756c976e876EFF05a29E731A4d348BA6ED. Deploy is CREATE2 with a global salt (gitCommit 1dc1960, deploy version create2-2026-07-01), so the kernel and every template land at the SAME address on every chain — the per-chain blocks below are identical by construction, not independent deployments. Deployed by 0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6 on 2026-07-01. Supersedes the prior EOA-governed 2026-06-09 deploy (kernel 0x02ABC18B65A328de2e749F56ba79ACF2718a6659) — those addresses are dead; do not reuse them.",
+  "_schema": "sail.skills.templates.deployed/v1",
+  "kernel": "0x38b508756c976e876EFF05a29E731A4d348BA6ED",
+  "chains": {
+    "1": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "8453": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "42161": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "10": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "130": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "56": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "480": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "999": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "4326": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "84532": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    },
+    "11155111": {
+      "ApproveAndCallBatchPermission": "0x0535A4D51333484ef583103DAB1a9449756ab732",
+      "BorrowPermission": "0x3e2666051599223cEAb10De55C89A0842857d8AF",
+      "DepositPermission": "0xBfB5e13a97b12Ee89d2F2b9B65eCf7e0E371911f",
+      "SwapPermission": "0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C",
+      "SwapPermissionNoOracle": "0x34Ba96CbEd1f46c88A5265E645DC5fe41662b519",
+      "TransferPermission": "0xda909a1CC584fb7559Ce4A828b008B473Da095e1",
+      "WithdrawPermission": "0xF5eF5dda450a130e3020d54f565E830e4a7531f8"
+    }
+  },
+  "_oraclesComment": "IOracle adapters (getPrice(base,quote)) usable as `priceOracle` in SwapPermission config. SwapPermission requires a non-zero IOracle adapter. Keyed chainId -> label. `pairs` lists the directional token pairs each adapter serves (both directions); any other pair reverts. catalog.mjs surfaces these so the swap skill can pick a default oracle. An IOracle adapter reads only its named pool/tokens — it has no kernel or template-address dependency, so it remains valid against the current CREATE2 SwapPermission singleton.",
+  "oracles": {
+    "130": {
+      "UniV3TwapOracle-USDC-WETH": {
+        "address": "0x9d84C11626d13C5DC9540fA12A3Ff7B85Ac3c1B9",
+        "kind": "uniswap-v3-twap",
+        "pool": "0x65081CB48d74A32e9CCfED75164b8c09972DBcF1",
+        "poolFeeTier": 500,
+        "twapWindowSec": 1800,
+        "priceDecimals": 18,
+        "pairs": [
+          { "base": "0x078D782b760474a361dDA0AF3839290b0EF57AD6", "quote": "0x4200000000000000000000000000000000000006", "label": "USDC/WETH" }
+        ],
+        "tokens": {
+          "USDC": "0x078D782b760474a361dDA0AF3839290b0EF57AD6",
+          "WETH": "0x4200000000000000000000000000000000000006"
+        },
+        "deployedBy": "0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6",
+        "tx": "0x3ca0d7232b623afda5e53c6d2319f4c3bbdc00a28b924c9f1d994bd3abfc2b3c",
+        "deployedAt": "2026-06-30",
+        "verified": "https://uniscan.xyz/address/0x9d84c11626d13c5dc9540fa12a3ff7b85ac3c1b9",
+        "source": "sail-templates/oracles/UniV3TwapOracle.sol",
+        "default": true,
+        "note": "Default priceOracle for the USDC<->WETH pair on Unichain. Live 30-min TWAP from the 0.05% V3 pool (cardinality 2000); updatedAt = block.timestamp, so it is always fresh against maxPriceAgeSec. Manipulation resistance scales with pool liquidity + window; reads a single pool. Use with maxPriceAgeSec >= a few minutes. Deployed before the create2-2026-07-01 migration but kernel-agnostic (reads only the named pool/tokens), so it remains a valid priceOracle for the current SwapPermission singleton (0x35cEEa0db96997Cc3CF3beB42FFa36A499342F7C)."
+      }
+    }
+  }
+}

package/templates/default/.agents/skills/sail-templates/oracles/IOracle.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+/// @title  IOracle
+/// @notice Minimal price oracle interface consumed by the oracle-gated permission templates.
+///         Vendored verbatim from Protocol/contracts/interfaces/IOracle.sol so this adapter
+///         compiles standalone; the consuming SwapPermission only cares about the ABI shape.
+interface IOracle {
+    function getPrice(address base, address quote)
+        external
+        view
+        returns (uint256 price, uint8 decimals, uint256 updatedAt);
+}

package/templates/default/.agents/skills/sail-templates/oracles/UniV3TwapOracle.sol

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+pragma solidity 0.8.26;
+
+import {IOracle} from "./IOracle.sol";
+import {TickMath} from "./libs/TickMath.sol";
+import {FullMath} from "./libs/FullMath.sol";
+
+interface IUniswapV3Pool {
+    function token0() external view returns (address);
+    function token1() external view returns (address);
+    function fee() external view returns (uint24);
+    function observe(uint32[] calldata secondsAgos)
+        external
+        view
+        returns (int56[] memory tickCumulatives, uint160[] memory secondsPerLiquidityCumulativeX128s);
+}
+
+/// @title  UniV3TwapOracle — single-pool Uniswap V3 TWAP adapter implementing IOracle
+/// @notice A read-only `IOracle` adapter for the oracle-gated launch templates (SwapPermission).
+///         It serves ONE Uniswap V3 pool and the single directional token pair it contains
+///         (both directions). The price is a time-weighted average over `twapWindow` seconds,
+///         read from `pool.observe`, so it is manipulation-resistant over that window (a one-block
+///         spot move barely shifts the average) and needs no external price provider or per-call
+///         update fee.
+///
+///         IORACLE SEMANTICS. getPrice(base, quote) returns (price, decimals, updatedAt) such that
+///         1 base base-unit = price / 10**decimals quote base-units. `decimals` is fixed at 18.
+///         `updatedAt` is the current block timestamp: a TWAP is computed live at call time, so it
+///         is always fresh against the consuming template's `maxPriceAgeSec`.
+///
+///         BOUNDARIES (honest). This is NOT a USD oracle — it reports the relative price of the two
+///         pool tokens, which is exactly what SwapPermission's band needs. Manipulation resistance
+///         is only as strong as (a) the pool's liquidity and (b) the chosen window: a long-lived,
+///         well-capitalised attacker can still drag a TWAP. It reads a SINGLE pool — if that pool is
+///         drained of liquidity the average degrades. `observe` reverts ("OLD") if the pool's
+///         observation buffer does not yet span `twapWindow`; that revert propagates and the
+///         consuming template fails closed (deny). Unsupported pairs revert `UnsupportedPair`.
+contract UniV3TwapOracle is IOracle {
+    /// @notice Quote precision returned by getPrice (price is scaled by 10**18).
+    uint8 public constant PRICE_DECIMALS = 18;
+
+    address public immutable pool;
+    address public immutable token0;
+    address public immutable token1;
+    uint32  public immutable twapWindow;
+
+    error UnsupportedPair(address base, address quote);
+    error WindowZero();
+
+    /// @param _pool       Uniswap V3 pool to read.
+    /// @param _twapWindow TWAP averaging window in seconds (must be > 0 and supported by the pool's
+    ///                    observation cardinality, else getPrice reverts).
+    constructor(address _pool, uint32 _twapWindow) {
+        if (_twapWindow == 0) revert WindowZero();
+        pool        = _pool;
+        token0      = IUniswapV3Pool(_pool).token0();
+        token1      = IUniswapV3Pool(_pool).token1();
+        twapWindow  = _twapWindow;
+    }
+
+    /// @inheritdoc IOracle
+    function getPrice(address base, address quote)
+        external
+        view
+        returns (uint256 price, uint8 decimals, uint256 updatedAt)
+    {
+        bool supported = (base == token0 && quote == token1) || (base == token1 && quote == token0);
+        if (!supported) revert UnsupportedPair(base, quote);
+
+        int24 tick = _consultMeanTick();
+        // quoteAmount for a base input of 10**PRICE_DECIMALS == price scaled to PRICE_DECIMALS.
+        price = _getQuoteAtTick(tick, uint128(10 ** uint256(PRICE_DECIMALS)), base, quote);
+        decimals = PRICE_DECIMALS;
+        updatedAt = block.timestamp;
+    }
+
+    /// @dev Time-weighted mean tick over `twapWindow`, rounded toward negative infinity (Uniswap's
+    ///      OracleLibrary convention).
+    function _consultMeanTick() internal view returns (int24) {
+        uint32[] memory secondsAgos = new uint32[](2);
+        secondsAgos[0] = twapWindow;
+        secondsAgos[1] = 0;
+
+        (int56[] memory tickCumulatives, ) = IUniswapV3Pool(pool).observe(secondsAgos);
+        int56 delta = tickCumulatives[1] - tickCumulatives[0];
+        int56 window = int56(uint56(twapWindow));
+
+        int24 meanTick = int24(delta / window);
+        if (delta < 0 && (delta % window != 0)) meanTick--;
+        return meanTick;
+    }
+
+    /// @dev Uniswap OracleLibrary.getQuoteAtTick: quote-token amount for `baseAmount` of base token
+    ///      at `tick`, honouring token ordering (no decimal normalisation — raw base units).
+    function _getQuoteAtTick(int24 tick, uint128 baseAmount, address baseToken, address quoteToken)
+        internal
+        pure
+        returns (uint256 quoteAmount)
+    {
+        uint160 sqrtRatioX96 = TickMath.getSqrtRatioAtTick(tick);
+
+        if (sqrtRatioX96 <= type(uint128).max) {
+            uint256 ratioX192 = uint256(sqrtRatioX96) * sqrtRatioX96;
+            quoteAmount = baseToken < quoteToken
+                ? FullMath.mulDiv(ratioX192, baseAmount, 1 << 192)
+                : FullMath.mulDiv(1 << 192, baseAmount, ratioX192);
+        } else {
+            uint256 ratioX128 = FullMath.mulDiv(sqrtRatioX96, sqrtRatioX96, 1 << 64);
+            quoteAmount = baseToken < quoteToken
+                ? FullMath.mulDiv(ratioX128, baseAmount, 1 << 128)
+                : FullMath.mulDiv(1 << 128, baseAmount, ratioX128);
+        }
+    }
+}

package/templates/default/.agents/skills/sail-templates/oracles/libs/FullMath.sol

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+/// @title Contains 512-bit math functions
+/// @notice Vendored from Uniswap v3-core (0.8 port). Facilitates multiplication and division that
+///         can have overflow of an intermediate value without any loss of precision.
+library FullMath {
+    /// @notice Calculates floor(a×b÷denominator) with full precision.
+    function mulDiv(uint256 a, uint256 b, uint256 denominator) internal pure returns (uint256 result) {
+        unchecked {
+            uint256 prod0;
+            uint256 prod1;
+            assembly {
+                let mm := mulmod(a, b, not(0))
+                prod0 := mul(a, b)
+                prod1 := sub(sub(mm, prod0), lt(mm, prod0))
+            }
+
+            if (prod1 == 0) {
+                require(denominator > 0);
+                assembly {
+                    result := div(prod0, denominator)
+                }
+                return result;
+            }
+
+            require(denominator > prod1);
+
+            uint256 remainder;
+            assembly {
+                remainder := mulmod(a, b, denominator)
+            }
+            assembly {
+                prod1 := sub(prod1, gt(remainder, prod0))
+                prod0 := sub(prod0, remainder)
+            }
+
+            uint256 twos = denominator & (~denominator + 1);
+            assembly {
+                denominator := div(denominator, twos)
+            }
+            assembly {
+                prod0 := div(prod0, twos)
+            }
+            assembly {
+                twos := add(div(sub(0, twos), twos), 1)
+            }
+            prod0 |= prod1 * twos;
+
+            uint256 inv = (3 * denominator) ^ 2;
+            inv *= 2 - denominator * inv;
+            inv *= 2 - denominator * inv;
+            inv *= 2 - denominator * inv;
+            inv *= 2 - denominator * inv;
+            inv *= 2 - denominator * inv;
+            inv *= 2 - denominator * inv;
+
+            result = prod0 * inv;
+            return result;
+        }
+    }
+}

package/templates/default/.agents/skills/sail-templates/oracles/libs/TickMath.sol

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+/// @title Math library for computing sqrt prices from ticks
+/// @notice Vendored from Uniswap v3-core (0.8 port). Only getSqrtRatioAtTick is needed here.
+library TickMath {
+    int24 internal constant MIN_TICK = -887272;
+    int24 internal constant MAX_TICK = 887272;
+
+    /// @notice Calculates sqrt(1.0001^tick) * 2^96
+    function getSqrtRatioAtTick(int24 tick) internal pure returns (uint160 sqrtPriceX96) {
+        unchecked {
+            uint256 absTick = tick < 0 ? uint256(-int256(tick)) : uint256(int256(tick));
+            require(absTick <= uint256(int256(MAX_TICK)), "T");
+
+            uint256 ratio = absTick & 0x1 != 0 ? 0xfffcb933bd6fad37aa2d162d1a594001 : 0x100000000000000000000000000000000;
+            if (absTick & 0x2 != 0) ratio = (ratio * 0xfff97272373d413259a46990580e213a) >> 128;
+            if (absTick & 0x4 != 0) ratio = (ratio * 0xfff2e50f5f656932ef12357cf3c7fdcc) >> 128;
+            if (absTick & 0x8 != 0) ratio = (ratio * 0xffe5caca7e10e4e61c3624eaa0941cd0) >> 128;
+            if (absTick & 0x10 != 0) ratio = (ratio * 0xffcb9843d60f6159c9db58835c926644) >> 128;
+            if (absTick & 0x20 != 0) ratio = (ratio * 0xff973b41fa98c081472e6896dfb254c0) >> 128;
+            if (absTick & 0x40 != 0) ratio = (ratio * 0xff2ea16466c96a3843ec78b326b52861) >> 128;
+            if (absTick & 0x80 != 0) ratio = (ratio * 0xfe5dee046a99a2a811c461f1969c3053) >> 128;
+            if (absTick & 0x100 != 0) ratio = (ratio * 0xfcbe86c7900a88aedcffc83b479aa3a4) >> 128;
+            if (absTick & 0x200 != 0) ratio = (ratio * 0xf987a7253ac413176f2b074cf7815e54) >> 128;
+            if (absTick & 0x400 != 0) ratio = (ratio * 0xf3392b0822b70005940c7a398e4b70f3) >> 128;
+            if (absTick & 0x800 != 0) ratio = (ratio * 0xe7159475a2c29b7443b29c7fa6e889d9) >> 128;
+            if (absTick & 0x1000 != 0) ratio = (ratio * 0xd097f3bdfd2022b8845ad8f792aa5825) >> 128;
+            if (absTick & 0x2000 != 0) ratio = (ratio * 0xa9f746462d870fdf8a65dc1f90e061e5) >> 128;
+            if (absTick & 0x4000 != 0) ratio = (ratio * 0x70d869a156d2a1b890bb3df62baf32f7) >> 128;
+            if (absTick & 0x8000 != 0) ratio = (ratio * 0x31be135f97d08fd981231505542fcfa6) >> 128;
+            if (absTick & 0x10000 != 0) ratio = (ratio * 0x9aa508b5b7a84e1c677de54f3e99bc9) >> 128;
+            if (absTick & 0x20000 != 0) ratio = (ratio * 0x5d6af8dedb81196699c329225ee604) >> 128;
+            if (absTick & 0x40000 != 0) ratio = (ratio * 0x2216e584f5fa1ea926041bedfe98) >> 128;
+            if (absTick & 0x80000 != 0) ratio = (ratio * 0x48a170391f7dc42444e8fa2) >> 128;
+
+            if (tick > 0) ratio = type(uint256).max / ratio;
+
+            // this divides by 1<<32 rounding up to go from a Q128.128 to a Q128.96.
+            // we then downcast because the result always fits within 160 bits due to our tick input constraint
+            sqrtPriceX96 = uint160((ratio >> 32) + (ratio % (1 << 32) == 0 ? 0 : 1));
+        }
+    }
+}