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

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));
+        }
+    }
+}

package/templates/default/.agents/skills/sail-templates/references/config-schemas.md

@@ -0,0 +1,139 @@
+# Config schemas & enforced invariants — authoritative (from source)
+
+Each shared template stores per-account config under `mapping(address => …)` and decodes a
+`configure(...)` blob in `_applyConfig`. The tuples below are taken **directly from
+`Protocol/contracts/templates/*.sol`** and are the source of truth — encode with
+`abi.encode(...)` in that exact order. (The `@sail/sdk/templates` builders track a
+previously-deployed set; verify a builder's params match the tuple here before using it.)
+
+All caps/amounts are in the relevant token's **base units**. Every template runs under the
+kernel's `staticcall` + gas cap + fail-closed semantics: a revert ⇒ deny.
+
+---
+
+## SwapPermission
+```
+abi.encode(address[] routers, address[] tokensIn, address[] tokensOut,
+           uint256 maxAmountPerTx, uint256 maxSlippageBps,
+           address priceOracle, uint256 maxPriceAgeSec)
+```
+Selectors: `0x414bf389` (V3 `exactInputSingle` w/ deadline), `0x04e45aaf` (V3-02 no deadline),
+`0x38ed1739` (V2 `swapExactTokensForTokens`). Invariants: `value == 0` (native value rejected);
+`target ∈ routers`; **`tokenIn != tokenOut` / `path[0] != path[last]`** (self-routes denied — a
+round-trip would burn AMM fees while an oracle reporting base==quote clears the band);
+`tokenIn`/`path[0] ∈ tokensIn`; `tokenOut`/`path[last] ∈ tokensOut`;
+`recipient`/`to == account`; `amountIn ≤ maxAmountPerTx`; **oracle slippage band ALWAYS enforced**.
+The oracle is **mandatory** (contract `v2`): `_applyConfig` reverts `OracleRequired` if
+`priceOracle == 0`, `MissingPriceAge` if `maxPriceAgeSec == 0`, and `SlippageBpsTooLarge` if
+`maxSlippageBps > 9_999`. `maxSlippageBps == 0` ⇒ zero tolerance (strictest), NOT a bypass.
+`priceOracle` is an `IOracle` adapter (`getPrice(base,quote) → (price, dec, updatedAt)`), not a raw
+feed; dust trades whose floor truncates to 0 are denied. V2 intermediate hops are NOT checked.
+(For no-oracle tokens use `SwapPermissionNoOracle`.)
+
+## SwapPermissionNoOracle
+```
+abi.encode(address[] routers, address[] tokensIn, address[] tokensOut,
+           uint256 maxAmountPerTx, ReferencePool[] referencePools)
+
+struct ReferencePool { address tokenIn; address tokenOut; address pool;
+                       PoolKind kind /* 0=V2, 1=V3 */; uint256 toleranceBps; }
+```
+Same selectors and structural checks as `SwapPermission` (`0x414bf389`, `0x04e45aaf`,
+`0x38ed1739`): `target ∈ routers`; `tokenIn`/`path[0] ∈ tokensIn`; `tokenOut`/`path[last] ∈
+tokensOut`; `recipient`/`to == account`; `amountIn ≤ maxAmountPerTx`. **Differs** from
+`SwapPermission` in the price judgement: instead of an oracle band it enforces a **pool-referenced
+hallucination band** — `amountOutMin` must be ≥ the output implied by the live spot price of the
+operator-named `referencePool` for that directional pair, minus `toleranceBps`, and `amountOutMin
+> 0`. Config-time invariants (`_applyConfig` reverts ⇒ configure fails): `toleranceBps ≤ 5_000`
+(50% max); `pool != 0`; pool's `token0()`/`token1()` must match the pair (orientation precomputed);
+**strict coverage** — every non-self directional `(tokenIn, tokenOut)` combination MUST have a
+reference pool or configure reverts `MissingReferencePool`. Fail-closed at evaluate if the pool is
+missing/unreadable/illiquid or the floor truncates to zero.
+
+> ⚠️ **NOT manipulation-resistant.** The reference is a single pool's LIVE spot price, movable
+> within the same transaction (flash-loan / sandwich). This band only catches an *honest* mistake
+> (a confused agent quoting a wildly wrong price); it is NOT slippage protection. For
+> manipulation-resistant protection use the oracle-gated `SwapPermission`. Cap is per-tx, not
+> cumulative.
+
+## BorrowPermission
+```
+abi.encode(address[] protocols, address[] assets, uint256 maxAmountPerTx,
+           uint256 maxLtvBps, address collateralOracle, address borrowOracle,
+           uint256 maxPriceAgeSec)
+```
+Selectors: Aave `borrow(address,uint256,uint256,uint16,address)` (variable-rate only —
+`rateMode != 2` denies; stable-rate debt is rejected), Morpho **Optimizer/Morpho-Aave**
+`borrow(address,uint256,address,address)` (NOT Morpho Blue — its ABI differs and simply won't
+match, i.e. fails closed), Compound `borrow(uint256)` (target is the cToken; the underlying is
+resolved via `cToken.underlying()` and both the allowlist and LTV are underlying-denominated —
+targets with no `underlying()`, e.g. cETH, are denied). Invariants: `protocols`/`assets` must be
+non-empty with no zero addresses (`EmptyAllowlist`/`ZeroAddress` revert otherwise);
+`target ∈ protocols`; `asset ∈ assets`; `amount ≤ maxAmountPerTx`; `onBehalfOf`/`receiver ==
+account`. **Oracle modes:** zero oracles ⇒ amount-cap-only (no LTV ceiling applied at all, despite
+`maxLtvBps` being stored); both oracles set ⇒ `_ltvCheck` enforces the LTV bound. Exactly one
+oracle set reverts `OracleConfigInconsistent` at configure — it's an all-or-nothing pair.
+
+## TransferPermission
+```
+abi.encode(address[] allowedRecipients, address[] allowedTokens, uint256 maxAmountPerTx)
+```
+Selectors: `0xa9059cbb` `transfer`, `0x23b872dd` `transferFrom`. Invariants: `value == 0`;
+`allowedRecipients`/`allowedTokens` must be non-empty with no zero addresses
+(`EmptyAllowlist`/`ZeroAddress` revert at configure otherwise); `target (token) ∈ allowedTokens`;
+`to ∈ allowedRecipients`; `amount ≤ maxAmountPerTx`;
+**`transferFrom` requires `from == account`** (stricter than the old TransferTarget).
+Max 50 entries per allowlist.
+
+## DepositPermission
+```
+abi.encode(address[] targets, address[] tokens, uint256 maxAmountPerTx)
+```
+Selectors: `deposit(uint256,address)` (ERC-4626), `mint(uint256,address)`,
+`deposit(address,uint256,address,uint16)` (Aave v2), `supply(address,uint256,address,uint16)`
+(Aave v3). Invariants: `value == 0`; `targets`/`tokens` must be non-empty with no zero addresses
+(`EmptyAllowlist`/`ZeroAddress` revert at configure otherwise); `target ∈ targets`; token
+allowlist enforced (Aave: the `asset` arg; ERC-4626: `target` itself must be in `tokens`);
+`amount`/`shares ≤ maxAmountPerTx`; `receiver`/`onBehalfOf == account`. `mint` cap is in
+**shares** — account for share price.
+
+## WithdrawPermission
+```
+abi.encode(address[] tokens, address allowedRecipient, uint256 maxAmountPerTx)
+```
+Selectors: `0xa9059cbb` `transfer`, `0x23b872dd` `transferFrom`. Invariants: `value == 0`;
+`tokens` must be non-empty and `allowedRecipient` non-zero, with no zero-address tokens
+(`EmptyAllowlist`/`ZeroAddress` revert at configure otherwise); `target (token) ∈ tokens`;
+`to == allowedRecipient` (single address per config); `amount ≤ maxAmountPerTx`;
+**`transferFrom` requires `from == account`**. To change the recipient, `reconfigure` with a new
+blob.
+
+## ApproveAndCallBatchPermission
+```
+abi.encode(Config{
+  address[]       tokens; address[] spenders; ConsumingPair[] consumingPairs;
+  uint256[]       maxApprovalAmounts; bool requireAmountMatch; bool allowUnconstrainedRecipient;
+})
+struct ConsumingPair { address target; bytes4 selector; }
+```
+ABI tuple: `(address[],address[],(address,bytes4)[],uint256[],bool,bool)`. `consumingPairs` is a
+**struct array**, not two flat arrays — each `(target, selector)` is bound together, so a selector
+is authorised only on its paired target. Authorises exactly the 3-call batch:
+`approve(spender, amount)` → consuming call → `approve(spender, 0)`. Invariants: `tokens`,
+`spenders`, and `consumingPairs` must each be non-empty and contain no zero addresses/selectors
+(`EmptyAllowlist` reverts otherwise); token ∈ `tokens` with `amount ≤ maxApprovalAmount[token]`;
+`spender ∈ spenders`; `(target, selector)` ∈ `consumingPairs`; the pre-batch allowance on
+`(token, spender)` must be zero; the consuming call must target the approved `spender` and pull the
+approved `token`; allowance reset to zero in the same batch; if `requireAmountMatch`, the consuming
+call's leading `uint256` arg must equal the approve amount. `maxApprovalAmounts` is index-parallel
+with `tokens` (length mismatch reverts).
+
+> ⚠️ **Field name/polarity — `allowUnconstrainedRecipient`, NOT `requireRecipientIsAccount`.**
+> The field is an **opt-out**, default-safe: `false` (the default, i.e. an omitted/zero-value
+> bool) means the consuming call's output recipient is decoded and **must equal the account** —
+> the safe posture. `true` is a deliberate opt-out that leaves the recipient **unconstrained**.
+> Setting the bool `true` thinking it "requires/pins the recipient" gets the **opposite**
+> behaviour on-chain. Either way, the recipient (and the consumed asset) can only be decoded for
+> selectors in the fixed-offset set below — any other selector is denied under the default pin:
+> `swapExactTokensForTokens`, V3 `exactInputSingle` (both SwapRouter layouts), Aave V2/V3
+> `deposit`/`supply`, ERC-4626 `deposit`/`mint`.

package/templates/default/.agents/skills/sail-templates/references/reuse-flow.md

@@ -0,0 +1,139 @@
+# Reuse-first flow — register + configure a shared template
+
+The whole point of a **shared** template: the logic is already deployed, so you skip the
+deploy entirely. You give one SMA its own private config inside the singleton's
+`mapping(address => …)` and register it on the kernel.
+
+> **Two steps, not one (today).** The on-chain **intended** design is a single signed call —
+> `MandateFactory.attach(account, template, params, configureDeadline, configureSig, kernelSig)`
+> — that registers the template on the kernel AND writes its per-account config together.
+> **The shipped `sailor` CLI does not implement that combined call yet.** `sailor mandate
+> attach` performs **only the kernel registration** (`RegisterPermission` / the batch
+> `registerPermissions`); it never calls `configure`/`configureDirect`, carries no `--params`,
+> and builds no `Configure` EIP-712 signature. The SDK's `client.mandate.attach(...)` is a
+> `notImplemented()` stub.
+>
+> A registered-but-unconfigured singleton has `isConfigured == false`, so the kernel's
+> `evaluate()` **denies every call** — a registered-but-dead permission. You MUST configure
+> separately, with `sailor mandate configure` (step 4 below). The flow below describes what
+> actually works now.
+
+## On-chain mechanics (`MandateFactory` + `ConfigurablePermission`)
+
+These are the **on-chain** entry points — the contract truth for what the combined/intended
+flow does. The shipped CLI uses a subset of them today (registration only); the configure
+half is driven directly for now.
+
+Registration (kernel side — what `sailor mandate attach` does today):
+
+| Function | Use |
+|---|---|
+| kernel `registerPermission(account, permission, deadline, sig)` | Register one template address on an SMA |
+| kernel `registerPermissions(account, permissions[], deadline, sig)` | Register several in one signature (the `--address a,b,c` batch path) |
+| kernel `revokePermissions(account, permissions[], deadline, sig)` | Remove (`sailor mandate revoke`) |
+
+Configuration (singleton side — the half the CLI does NOT do today):
+
+| Function | Use |
+|---|---|
+| `configure(account, params, deadline, sig)` | Set per-account config, gated by an EIP-712 `Configure(account, paramsHash, nonce, deadline, epoch)` signature from the account's `permissionSigner` (ECDSA or ERC-1271). |
+| `configureDirect(account, params)` | Set per-account config, gated by `msg.sender == permissionSigner`. The working path when the owner IS the permissionSigner — a plain owner tx, no signature. |
+| `reconfigure(...)` | Intended batch re-config path (`MandateFactory.reconfigure`); functionally `configure` again with a new blob. |
+
+The intended combined call (`MandateFactory.attach`) and its batch/replace/detach siblings are
+defined on the factory contract; they are the target state for a future one-step CLI command,
+not something the current CLI drives.
+
+The kernel evaluates a registered permission via `staticcall` with a per-permission gas cap;
+a revert or over-gas is treated as `false` (fail-closed), never a kernel revert.
+
+## The steps (as they work today)
+
+### 1. Discover the address
+```bash
+node SKILLS/sail-templates/catalog.mjs --chain <id>
+```
+The address comes from [`deployed.json`](../deployed.json). **If the template isn't deployed on
+your chain yet** (e.g. `SwapPermissionNoOracle` is not deployed anywhere), that's the
+prerequisite: deploy the singleton once (Protocol team / `DeploySharedTemplates`) and record
+its address there. A template address is only meaningful paired with that chain's kernel.
+
+### 2. Build the config blob
+Encode the config tuple **exactly as the contract's `_applyConfig` decodes it** — the
+authoritative tuples are in [config-schemas.md](config-schemas.md). Use `abi.encode(...)` in
+that order, or the typed builder under `@sail/sdk/templates` **only after** verifying its param
+tuple equals the source tuple (the SDK builders track a previously-deployed set and may differ
+from these source contracts):
+```ts
+import { boundedSwapTemplate } from "@sail/sdk/templates"; // verify params vs config-schemas.md first
+
+const params = { routers, tokensIn, tokensOut, maxAmountPerTx, maxSlippageBps,
+                 priceOracle, maxPriceAgeSec };
+const blob = boundedSwapTemplate.encoder.encode(params);
+
+// Always surface the human-readable summary + warnings to the user first:
+const explanation = boundedSwapTemplate.explainer.explain(params);
+```
+
+> ⚠️ **Encoding gotcha (fails closed).** Templates do NOT all encode the same way.
+> `TransferPermission` / `WithdrawPermission` / `DepositPermission` decode **flat top-level
+> params** (`abi.encode(address[], address[], uint256)`). `ApproveAndCallBatchPermission`
+> decodes a **single wrapped struct** (`abi.encode(Config{…})`) — its blob starts with a `0x20`
+> tuple-offset word. Wrapping a flat-params blob (or vice-versa) reverts at configure. **Always
+> round-trip-decode the blob and `cast call`-simulate `configureDirect` before sending.**
+
+### 3. Register the singleton on the kernel (does NOT configure)
+```bash
+sailor mandate attach --address <SHARED_ADDRESS> --sma <SMA> --label "<primitive>"
+```
+This builds and submits the kernel `RegisterPermission` (or `registerPermissions` for a
+comma-separated `--address` list). It does NOT call `configure`. After this step the address is
+in `getPermissions(<SMA>)` but `isConfigured(<SMA>) == false`, so every dispatch is still
+denied. Proceed to step 4.
+
+### 4. Configure the per-account bounds (the half that makes it live)
+When the owner IS the SMA's `permissionSigner` (the default Sailor onboarding), drive
+`configureDirect(account, <config blob>)` as a plain owner transaction — `msg.sender ==
+permissionSigner` holds and no EIP-712 signature is needed — via the shipped command:
+```bash
+sailor mandate configure --address <SHARED_ADDRESS> --sma <SMA> \
+  --template <TemplateName> --args-file ./config.json
+# or with a pre-encoded blob:
+sailor mandate configure --address <SHARED_ADDRESS> --sma <SMA> --params <0x-blob>
+```
+It does, in order:
+1. **Pre-flight (no gas):** an `eth_call` simulation of `configureDirect` from `permissionSigner`. A revert here means the config is invalid before any gas is spent — fix the blob (see the encoding gotcha) and retry. Pass `--simulate-only` to stop here.
+2. **Send it:** pushes the `configureDirect` call to the owner wallet as an `arbitrary-tx` request through the signing station; the owner approves in the browser and the owner wallet sends the transaction.
+3. **Verify:** reads `isConfigured(<SMA>)` on the singleton and errors if it isn't `true`.
+
+If the owner is **not** the `permissionSigner` (e.g. a separate mandate-signer / multisig), use
+`configure(account, params, deadline, sig)` instead: construct the EIP-712 `Configure` digest
+(bound to the kernel's current `registrationEpoch`), have the `permissionSigner` sign it, and
+submit. `sailor mandate configure` does not build this signature for you — that path is still
+manual.
+
+### 5. Verify off-chain (no gas)
+Prove it accepts what you want and rejects what you don't, before trusting it:
+```bash
+sailor mandate simulate --address <SHARED_ADDRESS> --sma <SMA> \
+  --target <router> --calldata <hex> --expect pass
+# or a batch file:
+sailor mandate simulate --address <SHARED_ADDRESS> --sma <SMA> --calls ./probe.json
+```
+
+### 6. Reconfigure when bounds change
+New cap or allowlist? Re-encode the blob and repeat step 4 (`sailor mandate configure --force`,
+or the manual `configure` signature path) — the address stays registered, no re-attach. (On-chain
+`MandateFactory.reconfigure` is the intended batch path for this.)
+
+## Gotchas
+
+- **Unconfigured = deny.** A freshly-registered shared template with no `configure()` has
+  `isConfigured == false` and denies everything. Register AND configure — don't stop at
+  `sailor mandate attach`.
+- **`sailor mandate attach` is register-only.** It does not configure. This is the single most
+  common trap; see steps 3 and 4.
+- **Caps are in base units** of the relevant token (e.g. `25_000_000` = 25 USDC).
+- **permissionSigner is the trust anchor** for config. In production use a multisig / timelock
+  — whoever holds it can widen allowlists and caps on every account they signed for.
+- The shared singletons are **unaudited examples**. Simulate (Step 5) is not optional.