npm - @dev.sail.money/sailor - Versions diffs - 1.3.0-224 → 1.3.0-225 - Mend

@dev.sail.money/sailor 1.3.0-224 → 1.3.0-225

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (133) hide show

package/packages/ui/dist/assets/{walletconnect-DsIIuQfT.js → walletconnect-ByDpG-E0.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as l}from"./core-8m_0OoS0.js";import"./index-ohx1EwWJ.js";import"./events-BGQ3xBjc.js";import"./index.es-ClarUTak.js";import"./fallback-B2d-ODZG.js";const o=l`<svg fill="none" viewBox="0 0 96 67">
+import{F as l}from"./core-BMNH6XFj.js";import"./index-CPrhuDfP.js";import"./events-Cdt6abbf.js";import"./index.es-DImsg59a.js";import"./fallback-BSMYROva.js";const o=l`<svg fill="none" viewBox="0 0 96 67">
   <path
     fill="currentColor"
     d="M25.32 18.8a32.56 32.56 0 0 1 45.36 0l1.5 1.47c.63.62.63 1.61 0 2.22l-5.15 5.05c-.31.3-.82.3-1.14 0l-2.07-2.03a22.71 22.71 0 0 0-31.64 0l-2.22 2.18c-.31.3-.82.3-1.14 0l-5.15-5.05a1.55 1.55 0 0 1 0-2.22l1.65-1.62Zm56.02 10.44 4.59 4.5c.63.6.63 1.6 0 2.21l-20.7 20.26c-.62.61-1.63.61-2.26 0L48.28 41.83a.4.4 0 0 0-.56 0L33.03 56.21c-.63.61-1.64.61-2.27 0L10.07 35.95a1.55 1.55 0 0 1 0-2.22l4.59-4.5a1.63 1.63 0 0 1 2.27 0L31.6 43.63a.4.4 0 0 0 .57 0l14.69-14.38a1.63 1.63 0 0 1 2.26 0l14.69 14.38a.4.4 0 0 0 .57 0l14.68-14.38a1.63 1.63 0 0 1 2.27 0Z"

package/packages/ui/dist/assets/{warning-circle-CTMOrGt2.js → warning-circle-hrS3II0d.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as r}from"./core-8m_0OoS0.js";import"./index-ohx1EwWJ.js";import"./events-BGQ3xBjc.js";import"./index.es-ClarUTak.js";import"./fallback-B2d-ODZG.js";const a=r`<svg fill="none" viewBox="0 0 20 20">
+import{F as r}from"./core-BMNH6XFj.js";import"./index-CPrhuDfP.js";import"./events-Cdt6abbf.js";import"./index.es-DImsg59a.js";import"./fallback-BSMYROva.js";const a=r`<svg fill="none" viewBox="0 0 20 20">
   <path
     fill="currentColor"
     d="M11 6.67a1 1 0 1 0-2 0v2.66a1 1 0 0 0 2 0V6.67ZM10 14.5a1.25 1.25 0 1 0 0-2.5 1.25 1.25 0 0 0 0 2.5Z"

package/packages/ui/dist/assets/{x-BmL9CVvs.js → x-BPMn3x5J.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as l}from"./core-8m_0OoS0.js";import"./index-ohx1EwWJ.js";import"./events-BGQ3xBjc.js";import"./index.es-ClarUTak.js";import"./fallback-B2d-ODZG.js";const a=l`<svg fill="none" viewBox="0 0 41 40">
+import{F as l}from"./core-BMNH6XFj.js";import"./index-CPrhuDfP.js";import"./events-Cdt6abbf.js";import"./index.es-DImsg59a.js";import"./fallback-BSMYROva.js";const a=l`<svg fill="none" viewBox="0 0 41 40">
   <g clip-path="url(#a)">
     <path fill="#000" d="M.8 0h40v40H.8z" />
     <path

package/packages/ui/dist/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#040b16" />
     <title>Sail - Unlocking Personalized Money</title>
-    <script type="module" crossorigin src="/assets/index-ohx1EwWJ.js"></script>
+    <script type="module" crossorigin src="/assets/index-CPrhuDfP.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CKoOBsKn.css">
   </head>
   <body>

package/templates/default/.agents/skills/sail-mandates/references/approvals.md CHANGED Viewed

@@ -25,12 +25,12 @@ This needs no batch support and works on every kernel.
 Approve + action run as one `dispatchBatch` — atomic, single transaction. A batch dispatch consults **exactly one batch-aware `IBatchPermission`**, never a pair of `IPermission`s:
-- The permission implements `@sail/interfaces/IBatchPermission.sol` — `evaluateBatch(Call[] calls, BatchContext ctx)` validates the WHOLE sequence (ordering, the approve's spender/amount, the action, and mandatory allowance cleanup) and `isBatchPermission()` returns true. `examples/permissions/BoundedApproveAndCallBatch.sol` is the model.
+- The permission implements `@sail/interfaces/IBatchPermission.sol` — `evaluateBatch(Call[] calls, BatchContext ctx)` validates the WHOLE sequence (ordering, the approve's spender/amount, the action, and mandatory allowance cleanup) and `isBatchPermission()` returns true. **For the canonical `approve → swap/deposit/supply → reset` shape, a shared `ApproveAndCallBatchPermission` singleton is deployed** on Base, Arbitrum, Unichain, Sepolia, and Base Sepolia (resolve it with `node scripts/shared-template-addr.mjs ApproveAndCallBatchPermission`) — reuse it via `attach` + `configure` rather than authoring one. `examples/permissions/BoundedApproveAndCallBatch.sol` remains the model for a non-standard shape you must author yourself.
 - A normal `IPermission` placed in a batch is rejected by the kernel with `PermissionNotBatchAware`. You cannot assemble a batch from two narrow per-call permissions — that was the trap.
 - Batch is a **selective-kernel** feature (`dispatchBatch` / `previewBatch`); conjunctive kernels have neither. Confirm the model with `sailor doctor`; details in `docs/PERMISSION_MODEL.md`.
-- At runtime, return one `Dispatch` whose `calls` array is `[approveCall, actionCall]`; the runner detects `calls.length > 1` and routes through `dispatch.batch`.
+- At runtime, return one `Dispatch` whose `calls` array is the batch. The shared `ApproveAndCallBatchPermission` requires **exactly** `[approve(spender, amount), action, approve(spender, 0)]` — the trailing reset to zero is mandatory, and the pre-batch allowance on that `(token, spender)` pair must already be zero (so never combine it with a standing approve). The runner detects `calls.length > 1` and routes through `dispatch.batch`.
-Use Model B only when atomicity genuinely matters (e.g. the approve must not be observable between calls). Otherwise prefer Model A — less contract to author and test.
+**For autonomous recurring actions (a DCA or rebalancer the agent runs on its own), Model B is the default — not an advanced option.** Model A's separate approve dispatch needs the owner back in the loop every time the bounded allowance runs out, which a recurring agent cannot do; on the first tick after the allowance is consumed it stalls (or, in a simulation, is tempted to cheat the allowance in). Reach for Model A when the owner is genuinely in the loop per action anyway. For bounded swaps specifically, [`sail-template-swap`'s "Approve coverage"](../../sail-template-swap/SKILL.md) works through the choice with concrete addresses.
 ## Verifying each model

package/templates/default/.agents/skills/sail-swap-quote/SKILL.md ADDED Viewed

@@ -0,0 +1,76 @@
+---
+name: sail-swap-quote
+description: Fetch a live Uniswap V3 quote via QuoterV2 and compute a slippage-adjusted amountOutMinimum for a swap. Use after sail-token-resolve to show the user the current price and to produce the amountOutMinimum floor the agent must embed in every swap dispatch. Runs the bundled `scripts/quote-swap.mjs` (no dependencies, no gas).
+---
+# sail-swap-quote — live price + amountOutMinimum floor
+After [`sail-token-resolve`](../sail-token-resolve/SKILL.md) confirms a token is
+swap-ready, get the actual number: how much tokenOut the user's amountIn buys
+right now, and the `amountOutMinimum` floor that protects against slippage.
+## When to load
+- After `sail-token-resolve` returned `swapReady: true`.
+- Before presenting a mandate to the user (show them the current price).
+- To validate `amountOutMinimum` before the agent dispatches a real swap.
+- Whenever the user asks "what's the price of X?" or "how much WETH for 25 USDC?".
+## Run it
+```bash
+# From the project root. Inputs come from sail-token-resolve's output.
+node scripts/quote-swap.mjs \
+  --token-in  0x078D782b760474a361dDA0AF3839290b0EF57AD6  --decimals-in  6  \
+  --token-out 0x4200000000000000000000000000000000000006 --decimals-out 18 \
+  --amount 25000000 --fee 3000 --slippage-bps 100
+```
+- `--amount` is in **base units** of tokenIn (25 USDC = `25000000`, not `25`).
+- `--fee` is the tier from `sail-token-resolve` (deepest pool).
+- `--slippage-bps` defaults to `100` (1%). Tighten (e.g. `50`) for stable pairs,
+  loosen for volatile ones. `0` removes the floor — testing only.
+- `--chain` / `--rpc` override the project's active chain/RPC.
+Output: one JSON object on stdout; human notes on stderr.
+## What it returns
+```json
+{
+  "amountIn": "25000000", "amountOut": "15805313193992907",
+  "amountOutMinimum": "15647260062052977",   // amountOut × (10000-slip)/10000
+  "slippageBps": 100, "fee": 3000,
+  "human": { "amountIn": "25.0", "amountOut": "0.015805313193992907",
+             "amountOutMinimum": "0.015647260062052977",
+             "price": "0.015805313193992907 out per 25.0 in" }
+}
+```
+## How the floor is computed
+```
+amountOutMinimum = amountOut × (10000 − slippageBps) / 10000
+```
+At 1% slippage, `amountOut × 9900 / 10000`. The agent must embed a value **at
+least this high** in its swap calldata's `amountOutMinimum` field — the
+`SwapPermission` mandate rejects any swap whose `amountOutMinimum` is below the
+pool-implied floor (fail-closed). Re-quote close to dispatch time; a stale quote
+is the most common reason a legitimate swap gets rejected.
+## What to do with it
+1. **Show the user** the `human.price` line before they approve the mandate.
+2. **Record `amountOutMinimum`** as the floor the agent's dispatch logic must
+   respect. Hand the full quote to [`sail-template-swap`](../sail-template-swap/SKILL.md)
+   — the mandate's `maxSlippageBps` bound is the on-chain enforcement of this.
+3. **Re-quote at dispatch time** — pool state moves; a quote taken minutes ago may
+   no longer match.
+## If it fails
+| Error | Meaning |
+|---|---|
+| `QuoterV2 reverted` / `amountOut == 0` | No pool at this fee tier (despite resolve-token). Try the next tier from resolve-token's `probedTiers`, or re-run resolve-token — liquidity may have shifted. |
+| `No RPC for chain` | Run from the project root, or pass `--rpc`. |

package/templates/default/.agents/skills/sail-template-approve-batch/SKILL.md ADDED Viewed

@@ -0,0 +1,98 @@
+---
+name: sail-template-approve-batch
+description: Gate an SMA's "approve → call → reset" interactions by REUSING the shared ApproveAndCallBatchPermission singleton (Protocol/contracts/templates/ApproveAndCallBatchPermission.sol) — register + configure, no per-SMA deploy. Use when an agent must approve an ERC-20 to a protocol, make one consuming call, and reset the allowance to zero — all in one atomic batch — with token/spender/target/selector allowlists and a per-token approval cap. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires ApproveAndCallBatchPermission deployed on the target chain (recorded in sail-templates/deployed.json); run sail-templates first.
+metadata:
+  workspace: sailor-harness
+  classification: generic
+  status: draft
+  origin: Protocol/contracts/templates/ApproveAndCallBatchPermission.sol
+---
+# sail-template-approve-batch — atomic approve/call/reset via the shared singleton
+Reuse the shared **`ApproveAndCallBatchPermission`** singleton — the safest way to bracket a
+single protocol interaction that needs an allowance. Family overview + flow:
+[`sail-templates`](../sail-templates/SKILL.md).
+## What it enforces (per account, from source)
+Authorises exactly this 3-call batch:
+```
+[0] approve(spender, amount)   on an allowlisted ERC-20
+[1] consuming call             on an allowlisted (target, selector)
+[2] approve(spender, 0)        reset to zero (same atomic batch)
+```
+Invariants: `tokens`, `spenders`, and `consumingPairs` must each be non-empty with no zero
+addresses/selectors (`EmptyAllowlist` reverts at configure otherwise); `token ∈ tokens` and
+`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`; the reset-to-zero is required; if
+`requireAmountMatch`, the consuming call's leading `uint256` arg must equal the approve amount.
+Malformed calldata reverts (kernel treats revert as deny).
+> **Output recipient — `allowUnconstrainedRecipient` (opt-out, default-safe).** By DEFAULT
+> (`allowUnconstrainedRecipient = false`, i.e. omitted) the consuming call's output recipient is
+> decoded and **must equal the SMA** — the safe posture — and any selector outside the decodable
+> set below is denied (fail-closed). Set `allowUnconstrainedRecipient = true` ONLY to deliberately
+> leave the recipient unconstrained (e.g. to authorize a selector outside the decodable set); then
+> only allowlist `(target, selector)` pairs whose semantics you trust to deliver output to the SMA.
+> ⚠️ This is an **opt-out** flag, not an opt-in — do not set it `true` thinking that "requires"
+> or "pins" the recipient; that gets you the opposite (unconstrained) behavior on-chain.
+>
+> **Decodable set** (recipient AND consumed-asset both resolvable at a fixed calldata offset —
+> any other selector is denied regardless of `allowUnconstrainedRecipient`, since the consumed
+> asset can never be bound to the approved token): `swapExactTokensForTokens` (V2), V3
+> `exactInputSingle` (both the SwapRouter and SwapRouter02 layouts), Aave V2 `deposit` / Aave V3
+> `supply`, ERC-4626 `deposit` / `mint`.
+## Config blob (authoritative — `config-schemas.md`)
+```
+abi.encode(Config{
+  address[]       tokens;                       // approvable ERC-20s
+  address[]       spenders;                     // allowed allowance recipients
+  ConsumingPair[] consumingPairs;               // {address target; bytes4 selector} — pair bound together
+  uint256[]       maxApprovalAmounts;           // index-parallel with tokens; per-token cap
+  bool            requireAmountMatch;           // call[1] leading uint256 must equal approve amount
+  bool            allowUnconstrainedRecipient;  // OPT-OUT (default false = call[1] output recipient decoded, must == account)
+})
+struct ConsumingPair { address target; bytes4 selector; }
+```
+`maxApprovalAmounts.length` must equal `tokens.length` (configure reverts otherwise).
+`consumingPairs` is a **struct array** `(address target, bytes4 selector)[]` — NOT two flat
+`address[]`/`bytes4[]` arrays. A selector is authorised only on the target it is paired with.
+**ABI tuple (verified round-trip):** `(address[],address[],(address,bytes4)[],uint256[],bool,bool)`.
+Encode with cast — note `selector` is a `bytes4` (left-aligned), and both trailing bools are required:
+```bash
+cast abi-encode 'cfg((address[],address[],(address,bytes4)[],uint256[],bool,bool))' \
+  '([<token>],[<spender>],[(<target>,<selector>)],[<maxApproval>],<requireAmountMatch>,<allowUnconstrainedRecipient>)'
+```
+`allowUnconstrainedRecipient` is an **opt-out** — leave it `false` unless you deliberately want
+the consuming call's output recipient unconstrained (see the field note above).
+The leading word is the `0x20` struct offset — that is correct, not flat-param corruption. A
+generic (un-named) revert inside `_applyConfig` means the blob did not decode to this exact tuple
+(usually: flat params with no `0x20` offset, the two flat arrays instead of `ConsumingPair[]`, or a
+missing trailing bool). The named errors (`TokensAndAmountsLengthMismatch`, `EmptyAllowlist`,
+`AllowlistTooLong`) fire only after a successful decode.
+## Steps
+Register → configure → simulate → reconfigure mechanics live in
+[`sail-templates` reuse-flow](../sail-templates/references/reuse-flow.md) — follow it.
+`sailor mandate attach` registers only; `configureDirect` (owner tx) is the half that makes the
+permission live. Template-specific bits:
+- **Singleton:** `ApproveAndCallBatchPermission` — `node SKILLS/sail-templates/catalog.mjs --chain
+  <id>`.
+- **Spec to confirm:** tokens+caps, spenders, `(target, selector)` consuming pairs,
+  `requireAmountMatch`, `allowUnconstrainedRecipient`. Get each selector with `cast sig` and verify
+  it delivers output to the SMA (leave `allowUnconstrainedRecipient = false`, the default, to
+  enforce that on-chain — set `true` only to deliberately opt out).
+- **Blob — ⚠️ NOT flat params.** `abi.encode(Config{ … })` — a **single wrapped struct**, so the
+  blob starts with a `0x20` offset word. `consumingPairs` is `(address,bytes4)[]` (a struct array),
+  and both trailing bools are required — see the verified `cast abi-encode` form above. Unlike
+  transfer/withdraw/deposit/borrow/swap, wrapping is required here; a flat blob reverts at configure.
+- **Simulate (mandatory — unaudited example):** the full allowed approve/call/reset batch passes;
+  missing reset, off-list spender/target/selector, or over-cap approve is rejected.

package/templates/default/.agents/skills/sail-template-borrow/SKILL.md ADDED Viewed

@@ -0,0 +1,68 @@
+---
+name: sail-template-borrow
+description: Gate an SMA's lending borrows by REUSING the shared BorrowPermission singleton (Protocol/contracts/templates/BorrowPermission.sol) — register + configure, no per-SMA deploy. Use for a bounded borrow mandate against Aave / Morpho / Compound with a protocol + asset allowlist, per-tx cap, and an on-chain LTV check via collateral + borrow oracles. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires BorrowPermission deployed on the target chain (recorded in sail-templates/deployed.json); run sail-templates first.
+metadata:
+  workspace: sailor-harness
+  classification: generic
+  status: draft
+  origin: Protocol/contracts/templates/BorrowPermission.sol
+---
+# sail-template-borrow — bounded lending borrow via the shared singleton
+Reuse the shared **`BorrowPermission`** singleton. Family overview + flow:
+[`sail-templates`](../sail-templates/SKILL.md).
+## What it enforces (per account, from source)
+Selectors (any other ⇒ `false`): Aave `borrow(address,uint256,uint256,uint16,address)`
+(**variable-rate only** — a stable-rate borrow, `rateMode != 2`, is rejected), Morpho
+**Optimizer/Morpho-Aave** `borrow(address,uint256,address,address)` (**NOT Morpho Blue** — its
+ABI differs and simply won't match this selector, i.e. fails closed; target a Blue-specific
+permission instead), Compound `borrow(uint256)` (the call target is the **cToken**; the template
+resolves `cToken.underlying()` and keys the allowlist/cap/LTV on the underlying — a target with
+no `underlying()`, e.g. cETH, is denied). Invariants: `target ∈ protocols`; `asset ∈ assets`
+(Aave/Morpho decode the asset; Compound resolves it via `underlying()`); `amount ≤
+maxAmountPerTx`; `onBehalfOf`/`receiver == SMA`; **`_ltvCheck` passes** — the projected debt
+value (via `borrowOracle`) against collateral value (via `collateralOracle`) must stay within
+`maxLtvBps`, when oracles are configured (see ORACLE MODES below).
+> **Oracle modes:** configure **zero** oracles for amount-cap-only borrowing (no LTV ceiling is
+> applied at all, despite `maxLtvBps` being stored) or **both** — exactly one oracle reverts
+> `OracleConfigInconsistent` at configure (a single feed can't price a ratio). When both are set,
+> the check still depends on their honesty/freshness — see staleness via `maxPriceAgeSec`.
+## Config blob (authoritative — `config-schemas.md`)
+```
+abi.encode(address[] protocols, address[] assets, uint256 maxAmountPerTx,
+           uint256 maxLtvBps, address collateralOracle, address borrowOracle,
+           uint256 maxPriceAgeSec)
+```
+| Field | Notes |
+|---|---|
+| `protocols` | lending pools the agent may borrow from |
+| `assets` | borrowable ERC-20 allowlist |
+| `maxAmountPerTx` | per-borrow cap, base units |
+| `maxLtvBps` | max loan-to-value, bps (e.g. `5000` = 50%) |
+| `collateralOracle` / `borrowOracle` | price sources for the LTV check |
+| `maxPriceAgeSec` | oracle freshness bound; `> 0` when oracles are set |
+> `maxLtvBps` is a **per-transaction** projection, not a tracked lifetime LTV. For
+> portfolio-level exposure, rely on the protocol's health factor or pair with a
+> position-monitoring permission.
+## Steps
+Register → configure → simulate → reconfigure mechanics (and the encoding gotcha) live in
+[`sail-templates` reuse-flow](../sail-templates/references/reuse-flow.md) — follow it.
+`sailor mandate attach` registers only; `configureDirect` (owner tx) is the half that makes the
+permission live. Template-specific bits:
+- **Singleton:** `BorrowPermission` — `node SKILLS/sail-templates/catalog.mjs --chain <id>`.
+- **Spec to confirm:** protocols, assets, cap, max LTV, oracles.
+- **Blob:** `abi.encode(protocols[], assets[], maxAmountPerTx, maxLtvBps, collateralOracle,
+  borrowOracle, maxPriceAgeSec)` — **flat params, no wrapper**.
+- **Simulate (mandatory — unaudited example):** allowed borrow within LTV passes; over-cap,
+  over-LTV, or wrong recipient is rejected.

package/templates/default/.agents/skills/sail-template-deposit/SKILL.md ADDED Viewed

@@ -0,0 +1,61 @@
+---
+name: sail-template-deposit
+description: Gate an SMA's deposits into vaults / lending pools by REUSING the shared DepositPermission singleton (Protocol/contracts/templates/DepositPermission.sol) — register + configure, no per-SMA deploy. Use for a bounded deposit mandate into ERC-4626 vaults (deposit/mint) or Aave v2/v3 (deposit/supply) with a target + token allowlist and a per-tx cap; the resulting position always accrues to the SMA. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires DepositPermission deployed on the target chain (recorded in sail-templates/deployed.json); run sail-templates first.
+metadata:
+  workspace: sailor-harness
+  classification: generic
+  status: draft
+  origin: Protocol/contracts/templates/DepositPermission.sol
+---
+# sail-template-deposit — bounded vault/lending deposit via the shared singleton
+Reuse the shared **`DepositPermission`** singleton. Family overview + flow:
+[`sail-templates`](../sail-templates/SKILL.md). Discover yield targets first with
+`sail-defillama-yields`.
+## What it enforces (per account, from source)
+Selectors (any other ⇒ `false`):
+| Function | Venue |
+|---|---|
+| `deposit(uint256 assets, address receiver)` | ERC-4626 / simple vault |
+| `mint(uint256 shares, address receiver)` | ERC-4626 |
+| `deposit(address asset, uint256 amount, address onBehalfOf, uint16)` | Aave v2 |
+| `supply(address asset, uint256 amount, address onBehalfOf, 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 checks the `asset` arg, ERC-4626 requires the `target` (vault) itself
+∈ `tokens`; `amount`/`shares ≤ maxAmountPerTx`; `receiver`/`onBehalfOf == SMA`.
+> `mint`'s cap is in **shares**, not underlying. At a high share price the effective asset cap
+> is `maxAmountPerTx × sharePrice` — size accordingly. For ERC-4626 `deposit`/`mint` the token
+> allowlist is the last line of defence (no asset in calldata) — only allowlist vaults whose
+> accepted token you trust.
+## Config blob (authoritative — `config-schemas.md`)
+```
+abi.encode(address[] targets, address[] tokens, uint256 maxAmountPerTx)
+```
+| Field | Notes |
+|---|---|
+| `targets` | vault / lending-pool addresses |
+| `tokens` | ERC-20 allowlist (the asset for Aave; the vault itself for ERC-4626) |
+| `maxAmountPerTx` | per-deposit cap (assets, or shares for `mint`), base units |
+## Steps
+Register → configure → simulate → reconfigure mechanics (and the encoding gotcha) live in
+[`sail-templates` reuse-flow](../sail-templates/references/reuse-flow.md) — follow it.
+`sailor mandate attach` registers only; `configureDirect` (owner tx) is the half that makes the
+permission live. Template-specific bits:
+- **Singleton:** `DepositPermission` — `node SKILLS/sail-templates/catalog.mjs --chain <id>`.
+- **Spec to confirm:** targets, tokens, cap (note the share-price caveat for `mint`).
+- **Blob:** `abi.encode(targets[], tokens[], maxAmountPerTx)` — **flat params, no wrapper**.
+- **Simulate (mandatory — unaudited example):** allowed deposit within cap passes; off-list
+  target/token, over-cap, or `receiver != SMA` is rejected.

package/templates/default/.agents/skills/sail-template-swap/SKILL.md ADDED Viewed

@@ -0,0 +1,207 @@
+---
+name: sail-template-swap
+description: Gate an SMA's DEX swaps by REUSING the shared SwapPermission singleton (Protocol/contracts/templates/SwapPermission.sol) — register + configure, no per-SMA deploy. Use for a bounded swap / DCA mandate on Uniswap V3, V3-02, or V2 with router + token-in/out allowlists, a per-tx cap, and a MANDATORY oracle slippage band (priceOracle is required — for no-oracle tokens use sail-template-swap-no-oracle). For the LI.FI aggregator use sail-lifi-swap; for Pendle use sail-pendle. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires SwapPermission deployed on the target chain (recorded in sail-templates/deployed.json); run sail-templates first.
+metadata:
+  workspace: sailor-harness
+  classification: generic
+  status: draft
+  origin: Protocol/contracts/templates/SwapPermission.sol
+---
+# sail-template-swap — bounded DEX swap via the shared singleton
+Reuse the shared **`SwapPermission`** singleton instead of authoring/deploying a swap contract.
+Register its address on the SMA and `configure()` your routers, token allowlists, cap, and
+slippage. Family overview + flow: [`sail-templates`](../sail-templates/SKILL.md).
+## What it enforces (per account, from source)
+Supported selectors (any other ⇒ `false`):
+| Selector | Function | Venue |
+|---|---|---|
+| `0x414bf389` | `exactInputSingle((tokenIn,tokenOut,fee,recipient,deadline,amountIn,amountOutMinimum,sqrtPriceLimitX96))` | Uniswap V3 SwapRouter |
+| `0x04e45aaf` | `exactInputSingle((tokenIn,tokenOut,fee,recipient,amountIn,amountOutMinimum,sqrtPriceLimitX96))` | Uniswap V3 SwapRouter02 |
+| `0x38ed1739` | `swapExactTokensForTokens(amountIn,amountOutMin,path[],to,deadline)` | Uniswap V2 Router |
+Invariants: `ctx.value == 0` (native value rejected — ERC-20→ERC-20 only); `target ∈ routers`;
+**`tokenIn != tokenOut` / `path[0] != path[last]`** (self-routes denied — a round-trip burns AMM
+fees while an oracle reporting base==quote would otherwise clear the band); `tokenIn`/`path[0] ∈
+tokensIn`; `tokenOut`/`path[last] ∈ tokensOut`; `recipient`/`to == SMA` (funds can't leave the
+account); `amountIn ≤ maxAmountPerTx`; **oracle band ALWAYS enforced** (the oracle is
+mandatory — see below): `amountOutMin ≥ amountIn × price/10^dec ×
+(10_000 − maxSlippageBps)/10_000`. Dust trades whose computed floor truncates to `0` are
+**denied** (fail-closed).
+> **⛔ The oracle is MANDATORY (contract `v2`, hardened in PR #45).** `_applyConfig` reverts
+> `OracleRequired()` if `priceOracle == 0` and `MissingPriceAge()` if `maxPriceAgeSec == 0`.
+> There is **no oracle-disabled mode** on this template — for tokens with no oracle use the
+> separate [`SwapPermissionNoOracle`](../sail-template-swap-no-oracle/SKILL.md) (live-pool
+> hallucination band). `maxSlippageBps == 0` is **NOT** a bypass — it means zero tolerance
+> (exact-out-or-better), the strictest valid setting. `maxSlippageBps > 9_999` reverts
+> `SlippageBpsTooLarge`.
+> **V2 intermediate hops are NOT checked** — only `path[0]`/`path[last]`. Restrict to V3 or
+> ensure any plausible intermediate token is acceptable.
+## ⚠️ Approve coverage — the hidden precondition
+`SwapPermission` authorizes the swap **call** only. The router pulls `tokenIn` via an ERC-20
+allowance, and the `approve(router, amount)` that establishes it is a **separate transaction this
+permission does not cover** (same rule as every protocol permission — see
+[`sail-mandates/references/approvals.md`](../sail-mandates/references/approvals.md)). A swap with
+no/insufficient allowance reverts inside the router and the tick fails. **Every** bounded swap
+needs the allowance handled — decide how at mandate-build time, not when the first tick reverts.
+- **Autonomous agent (DCA / rebalancer / treasury) — default:** do NOT use `SwapPermission` alone;
+  register the shared **`ApproveAndCallBatchPermission`** singleton and dispatch each tick as one
+  atomic `[approve(router, amountIn), swap, approve(router, 0)]` batch — no lingering allowance,
+  no per-tick owner signature. See [`sail-template-approve-batch`](../sail-template-approve-batch/SKILL.md).
+- **Owner in the loop per swap:** keep `SwapPermission`; the owner pre-approves the router. The
+  agent must read `allowance(SMA, router)` and **stall (never self-approve)** when it is below
+  `amountIn` — `approve()` is an owner-side action the agent cannot take on its own.
+## Config blob (authoritative — `config-schemas.md`)
+```
+abi.encode(address[] routers, address[] tokensIn, address[] tokensOut,
+           uint256 maxAmountPerTx, uint256 maxSlippageBps,
+           address priceOracle, uint256 maxPriceAgeSec)
+```
+| Field | Notes |
+|---|---|
+| `routers` | DEX routers the agent may call |
+| `tokensIn` / `tokensOut` | sell-side / buy-side allowlists (multiple out ⇒ portfolio DCA) |
+| `maxAmountPerTx` | per-swap cap, base units (e.g. `25_000_000` = 25 USDC) |
+| `maxSlippageBps` | e.g. `100` = 1%. `0` = zero tolerance (strictest), NOT a bypass. Must be `≤ 9_999`. |
+| `priceOracle` | **REQUIRED, non-zero.** An `IOracle` adapter exposing `getPrice(tokenIn, tokenOut) → (price, dec, updatedAt)` — **not** a raw Chainlink/Pyth feed. `0` reverts `OracleRequired`. |
+| `maxPriceAgeSec` | **REQUIRED, `> 0`** (oracle staleness bound). `0` reverts `MissingPriceAge`. |
+Size the cap and slippage floor with `uniswap-v3-quote` / `sail-pyth-prices`. The SDK
+`boundedSwapTemplate` encoder matches this tuple — fine to use after a quick verify.
+### Worked example — single-leg USDC → WETH
+Concrete params for a 25-USDC-per-swap, 1%-slippage DCA leg. These are the values you hand to
+`boundedSwapTemplate.encoder.encode(...)` to produce the `configureDirect` blob (step 3b) — they
+are **not** an args-file for a CLI command. `priceOracle` must be a **real, non-zero `IOracle`
+adapter** for this pair on this chain (`0x0` reverts):
+```json
+{
+  "routers":        ["0x73855d06DE49d0fe4A9c42636Ba96c62da12FF9C"],
+  "tokensIn":       ["0x078D782b760474a361dDA0AF3839290b0EF57AD6"],
+  "tokensOut":      ["0x4200000000000000000000000000000000000006"],
+  "maxAmountPerTx": "25000000",
+  "maxSlippageBps": 100,
+  "priceOracle":    "0x9d84C11626d13C5DC9540fA12A3Ff7B85Ac3c1B9",
+  "maxPriceAgeSec": 3600
+}
+```
+> The `priceOracle` above is the **default Unichain USDC/WETH `IOracle` adapter** — a verified
+> Uniswap V3 30-min TWAP (`UniV3TwapOracle`, pool `0x65081C…DBcF1`, 0.05% tier). It serves the
+> USDC↔WETH pair both directions and reverts `UnsupportedPair` for anything else. `catalog.mjs`
+> lists it under **IOracle adapters**; on other chains/pairs you must supply your own adapter
+> (`address(0)` reverts). Because it's a live TWAP, `updatedAt` is always current — `maxPriceAgeSec`
+> just needs to be a few minutes (e.g. `3600`).
+| Field | From | Notes |
+|---|---|---|
+| `routers` | SwapRouter02 for the chain (resolve-token's chain table) | V3 router; the agent calls `exactInputSingle` on it |
+| `tokensIn` | `resolve-token` | sell-side allowlist (usually just USDC) |
+| `tokensOut` | `resolve-token` | buy-side allowlist; **multiple ⇒ portfolio DCA** |
+| `maxAmountPerTx` | user's per-swap size, **base units** (string) | `"25000000"` = 25 USDC (6 dec) |
+| `maxSlippageBps` | `quote-swap`'s recommendation | `100` = 1%. `0` = zero tolerance (strictest), not a bypass. `≤ 9_999`. |
+| `priceOracle` | an `IOracle` adapter for the chain (Pyth/Chainlink-backed) | **REQUIRED, non-zero.** Must expose `getPrice(tokenIn,tokenOut)` — not the raw feed contract. |
+| `maxPriceAgeSec` | seconds | **REQUIRED, `> 0`** — staleness bound. e.g. `3600` = 1h. |
+> **Caps are base units.** A decimals mismatch (USDC is 6, most tokens 18) silently mis-sizes
+> every bound. `resolve-token` verified decimals on-chain — use that value, never a guess.
+> For a **portfolio DCA**, list every buy-side token in `tokensOut` (one config, many legs).
+## Steps
+> **Register ≠ configure.** `sailor mandate attach` only registers the singleton on the kernel;
+> it does NOT configure it. A registered-but-unconfigured singleton denies every call. You must
+> do both — steps 3a (register) and 3b (configure). Full mechanics + the encoding gotcha:
+> [`sail-templates` reuse-flow](../sail-templates/references/reuse-flow.md).
+1. **Address:** `node SKILLS/sail-templates/catalog.mjs --chain <id>` → `SwapPermission`
+   address. It's the same address on every chain (CREATE2); see `deployed.json`.
+2. **Confirm the spec with the user** (sell/buy tokens, per-swap cap, slippage, router/fee
+   tier, recipient = SMA) — print the explainer's humanReadable + warnings. No gas before
+   approval.
+3. **a. Register** the singleton on the SMA's kernel (does NOT configure):
+   ```bash
+   sailor mandate attach --address <SWAP_PERMISSION> --sma <SMA> --label "bounded-swap"
+   ```
+   **b. Configure** the per-account bounds — this is what makes the permission live. Build a
+   JSON file with the flat template params (`routers`, `tokensIn`, `tokensOut`, `maxAmountPerTx`,
+   `maxSlippageBps`, `priceOracle`, `maxPriceAgeSec` — matches the SDK `boundedSwapTemplate`
+   encoder tuple, no wrapper), then run:
+   ```bash
+   sailor mandate configure --address <SWAP_PERMISSION> --sma <SMA> \
+     --template SwapPermission --args-file ./swap-config.json
+   ```
+   `configureDirect` requires `msg.sender == permissionSigner` (`kernel.configs(<SMA>)` — the
+   owner only when they collapse to the same address); the command pre-flights the blob with an
+   `eth_call` BEFORE any signing or gas — it **reverts** on `priceOracle == 0` (`OracleRequired`),
+   `maxPriceAgeSec == 0` (`MissingPriceAge`), or `maxSlippageBps > 9_999` (`SlippageBpsTooLarge`) —
+   then requests the `configureDirect` tx from `permissionSigner` through the signing station and
+   verifies `isConfigured(<SMA>) == true` on receipt. Pass `--simulate-only` to stop after the
+   pre-flight (no signing, no gas).
+   *(The signed `configure(account, params, deadline, sig)` path uses EIP-712 domain `("SwapPermission","2")`.)*
+4. **Simulate** — prove an allowed swap passes and a bad one (wrong recipient / over-cap /
+   disallowed token) fails:
+   ```bash
+   sailor mandate simulate --address <SWAP_PERMISSION> --sma <SMA> --calls ./swap-probe.json
+   ```
+5. **Reconfigure** later (new cap / extra output token) — re-run step 3b with a new blob; same
+   address, no re-register.
+## Agent config (off-chain, within the on-chain bounds)
+The mandate bounds what the agent MAY do; the agent's code decides what it WILL do and when. Wire
+the legs from the resolve + quote outputs:
+```typescript
+export const DCA_LEGS = [
+  {
+    tokenIn: "<USDC_ADDR>", tokenOut: "<WETH_ADDR>",
+    tokenInDecimals: 6, tokenOutDecimals: 18,
+    feeTier: 3000, amountPerSwap: 25_000_000n,   // base units, ≤ maxAmountPerTx
+    slippageBps: 100,
+  },
+] as const;
+```
+The agent must re-quote via [`sail-swap-quote`](../sail-swap-quote/SKILL.md) close to dispatch time
+and embed the floor `amountOutMinimum` in the swap calldata — the on-chain `maxSlippageBps` enforces
+it regardless. **Match the tick's dispatch shape to your approve model:** under the batch model
+(default) the agent returns one `Dispatch` whose `calls` is the 3-element
+`[approve(router, amountIn), swap, approve(router, 0)]` and must NOT pre-approve out of band (the
+batch requires a zero pre-batch allowance); under `SwapPermission` + owner pre-approve it emits a
+plain single-call swap and MUST read `allowance(SMA, router)` and **stall (not self-approve)** when
+it is below `amountIn`.
+## When NOT to use this
+- **Token has no `IOracle` adapter** → this template REQUIRES a non-zero oracle and will not
+  configure without one. Use [`sail-template-swap-no-oracle`](../sail-template-swap-no-oracle/SKILL.md)
+  (live-pool hallucination band — catches honest mistakes, NOT MEV/flash-loan attacks) or author a
+  bespoke permission. There is no oracle-off mode on `SwapPermission`.
+- **Aggregator (LI.FI) or opaque calldata** → the mandate can't inspect the route; use
+  [`sail-lifi-swap`](../sail-lifi-swap/SKILL.md) or [`sail-mandates`](../sail-mandates/SKILL.md).
+- **`SwapPermission` not deployed on your chain** → check `deployed.json` first (it's live on all
+  11 Sailor-bundled chains as of the current deploy); for anything outside that set, author your
+  own via [`sail-mandates`](../sail-mandates/SKILL.md).
+## Notes
+- The oracle is **mandatory** and the band is **always** enforced; `maxSlippageBps = 0` is the
+  strictest setting (zero tolerance), not a way to disable the check.
+- `priceOracle` must be an `IOracle` adapter (`getPrice(tokenIn,tokenOut) → (price, dec, updatedAt)`),
+  not a raw Chainlink/Pyth feed; it must return a meaningful `updatedAt` or evaluate fails closed.
+- Native value is rejected (`ctx.value != 0 ⇒ deny`) — ERC-20→ERC-20 only.
+- Unaudited example — step 4 is mandatory.
+- `recipient = SMA` is non-negotiable and enforced in the contract, not just config.