@dev.sail.money/sailor 0.0.2-12 → 0.0.2-13

package/templates/dca-rebalancer/AGENT_PLAYBOOK.md

@@ -1,110 +0,0 @@
-# Sail agent playbook
-
-Operational guide for an agent (or operator) running a Sail Protocol SMA via the
-Sailor SDK/CLI. Read [docs/PERMISSION_MODEL.md](docs/PERMISSION_MODEL.md) first — the
-conjunctive vs selective distinction underpins everything below.
-
-Golden rule: **always ask the user before any action that costs gas or moves funds.**
-
-## Step 0 — detect capabilities (always first)
-
-Before signing or dispatching anything, learn what kernel you're on:
-
-```ts
-const caps = await client.capabilities();   // reads DISPATCH_TYPEHASH on-chain
-```
-
-or, from the CLI, run the full preflight:
-
-```bash
-sailor doctor            # kernel model + permission health, read-only, no gas
-sailor doctor --json     # machine-readable
-```
-
-`sailor doctor` detects the dispatch model, lists registered permissions, and — on a
-conjunctive kernel — flags any permission that does **not** pass through unrelated
-calls (which would brick every dispatch). Fix those before doing anything else.
-
-## Decision tree
-
-```
-Want to act on the SMA?
-│
-├─ Is the Sail module enabled + account registered?      → no:  finish onboarding (sailor onboard)
-│
-├─ sailor doctor green?                                   → no:  revoke/replace bricking permissions first
-│
-├─ Need a NEW kind of action the permissions don't allow? → yes: register a permission (owner signs)
-│     • Conjunctive: the permission MUST pass through other calls. Prefer ONE
-│       permission per domain that allows everything you need (e.g. a single
-│       approve permission whitelisting all tokens you'll approve).
-│     • Use a clone template when one exists (no Solidity):
-│       getSailDeployment(chainId).cloneTemplates  → deployAndAttach
-│
-├─ One-off swap?                                          → client.strategy.swap({from,to,amount,slippage})
-│
-└─ Recurring/automated (DCA, rebalance)?                  → loop strategy.swap on a schedule;
-                                                            approve a larger batch once so most
-                                                            iterations are a single swap dispatch.
-```
-
-### Approvals
-
-- An ERC-20 `approve` is itself a dispatch and must pass the registered permissions.
-  On a conjunctive kernel that means an **approve permission that allows the token +
-  spender + amount**, AND every other permission passing the approve through.
-- The bounded-approve template uses **per-token caps** (token value/decimals differ:
-  1 DAI = 1e18 vs 1 USDC = 1e6). One global cap can't bound both.
-- `client.strategy.swap` only approves when the current router allowance is below the
-  trade size, so steady-state swaps are a single dispatch. Pass `approveAmount` larger
-  than `amount` to batch a bigger approval for DCA.
-
-### Swap mandates (LiFi)
-
-- The swap permission restricts: target = LiFi diamond, selector allowlisted, embedded
-  receiver == the account, `minAmount` ≤ cap. Verify the route's selector is
-  allowlisted (Base routes commonly use `0x5fd9ae2e`); add others via the permission
-  signer if needed.
-- Default slippage is 3% — LiFi's own 0.5% reverts (`CumulativeSlippageTooHigh`) on
-  small trades.
-
-### Automated jobs
-
-- Sequential dispatches: `client.dispatch.single` auto-tracks the manager nonce per
-  `(kernel, account)` and waits for the prior bump to propagate before signing the
-  next — no manual nonce handling, even on a load-balanced RPC.
-- Use a dedicated RPC endpoint (not a public replica) to minimize read-after-write lag.
-- Pin post-tx reads to the receipt's block; a lagging node can otherwise make a
-  confirmed action look failed.
-
-## Failure-mode catalog
-
-Every dispatch failure is decoded by the SDK — `client.dispatch.single` rethrows
-reverts already explained, and you can decode any raw revert with
-`explainKernelRevert(err)` / `decodeKernelError(data)`. Common ones:
-
-| Error (selector) | What it means | Fix |
-|---|---|---|
-| `InvalidManagerSignature` (`0xeb6942f1`) | The signed EIP-712 Dispatch didn't recover to the registered manager. | Almost always a **stale manager nonce** (RPC lag or two dispatches signed against the same nonce) — re-read `managerNonces` and re-sign; `dispatch.single` now handles this. Or the **wrong Dispatch struct** for this kernel — use `capabilities()`. |
-| `PermissionDenied(permission)` | A registered permission's `evaluate()` returned false / reverted / ran out of gas. | On a **conjunctive** kernel, a permission that doesn't pass through unrelated calls bricks everything — run `sailor doctor` and revoke/replace it. Otherwise the call genuinely violates that permission's bounds. |
-| `NoPermissionsRegistered(account)` | Account has zero permissions; kernel denies by default. | Register at least one permission (owner signs). |
-| `PermissionNotRegistered(permission)` | Named permission isn't registered. | Register it; or on a conjunctive kernel drop the permission arg (the SDK does). |
-| `SessionInactive(account)` | Manager session is revoked. | `session.activate` before dispatching. |
-| `DeadlineExpired(deadline,current)` | Signature deadline is in the past. | Sign with a deadline comfortably ahead of `block.timestamp`. |
-| `SafeExecutionFailed()` | Permission passed, but the target call itself reverted. | Usually slippage too tight, insufficient allowance/balance, or a failing route — not a permission problem. |
-| `ModuleNotEnabled()` | Sail module not enabled on the Safe. | Complete onboarding (enable the module) first. |
-| `ProtocolPaused()` | Governance paused the protocol. | Wait for unpause. |
-| `NotManager(caller,expected)` | Submitter isn't the registered manager. | Submit from the manager key. |
-| `TooManyPermissions(account,limit)` | Per-account permission cap reached. | Revoke an unused permission first. |
-
-When in doubt, the SDK hint string (in `error.kernelError.hint`) names the likely
-cause and fix.
-
-## Quick reference (SDK)
-
-- `client.capabilities()` — detect dispatch model.
-- `client.dispatch.single(safe, permission, call, manager, opts?)` — nonce-safe single dispatch (`opts`: `nonce`, `awaitNonce`, `gas`, `deadline`).
-- `client.strategy.swap(safe, {from,to,amount,slippage,swapPermission?,approveAmount?}, manager)` — approve-when-low + LiFi swap.
-- `explainKernelRevert(err)` / `decodeKernelError(data)` — human-readable revert.
-- `getSailDeployment(chainId).cloneTemplates` — wizard-ready clone templates + their `initialize()` params.
-- CLI: `sailor capabilities` (feasibility map), `sailor doctor` (preflight: model, permissions, RPC + gas), `sailor onboard`, `sailor mandate …`, `sailor station start`.

package/templates/dca-rebalancer/README.md

@@ -1,16 +0,0 @@
-# DCA Rebalancer — Sail Protocol Agent
-
-This folder is your Sail agent. It DCA-rebalances a token basket on a schedule.
-
-Open this folder in **Claude Code**, **Cursor**, or **Codex** (or any LLM-powered IDE) and say:
-
-> start
-
-Your AI coding assistant will walk you through every step — from network and wallet setup to your
-first on-chain tick. See `AGENTS.md` for the details; no manual config needed.
-
-## Project layout
-
-- `.sail/config.json` is the local project manifest.
-- `.sail/keys/` stores the encrypted agent wallet and mandate signer keys when local signing is used.
-- `.sail/state/` is for persistent agent state, audit logs, and tx history.

package/templates/dca-rebalancer/src/agent.ts

@@ -1,253 +0,0 @@
-/**
- * DCA-rebalancer agent — Base mainnet, selective SailKernel.
- *
- * Strategy: on each tick, if the SMA holds enough USDC, swap a fixed amount
- * into WETH via Uniswap V3 SwapRouter02.
- *
- * Slippage protection: QuoterV2 is called off-chain before each swap.
- *   amountOutMinimum = expectedOut × (1 − SLIPPAGE_BPS / 10 000)
- * If QuoterV2 is unavailable or returns 0, the agent skips the tick entirely
- * (fail closed — never submits with amountOutMinimum = 0).
- *
- * Selective kernel: the runner supports dispatchBatch, but this agent returns at
- * most ONE dispatch per tick for simplicity:
- *   - An approve, if the router allowance is insufficient.
- *   - A swap, if allowance is sufficient and a valid quote is available.
- * Next tick handles the other step.
- *
- * The agent does NOT call dispatch.single() itself — it returns intent objects
- * ({calls, txHash:'0x', ...}) and the runner submits them.
- *
- * PERMISSION ROUTING (default — probe path):
- * This template returns plain Dispatch objects with no `permission` field. The
- * runner automatically probes each registered permission via off-chain evaluate()
- * and routes each call to the first permission that accepts it. This is the
- * recommended default: zero agent-side knowledge of permission addresses required.
- *
- * OPTIONAL OVERRIDE (skip probe for a known permission):
- * If the agent knows exactly which permission governs a call, it can set the
- * optional `permission` field on the returned Dispatch to skip the probe:
- *
- *   import type { Address } from "viem";
- *   const MY_SWAP_PERMISSION = "0x..." as Address;
- *   return [{ ...dispatch, permission: MY_SWAP_PERMISSION }];
- *
- * This is an optimisation only — the probe path is equally correct.
- */
-
-import type { Agent, AgentContext, Call, Dispatch } from "@sail/sdk";
-import { encodeFunctionData, type PublicClient } from "viem";
-import {
-  ALLOWED_TOKENS,
-  MIN_USDC_TO_SWAP,
-  QUOTER_V2,
-  REBALANCE_THRESHOLD,
-  SLIPPAGE_BPS,
-  SWAP_AMOUNT_USDC,
-  SWAP_FEE_TIER,
-  SWAP_ROUTER,
-} from "./mandate.js";
-
-// ── ABI fragments ─────────────────────────────────────────────────────────────
-
-const ERC20_ABI = [
-  {
-    name: "allowance",
-    type: "function",
-    stateMutability: "view",
-    inputs: [
-      { name: "owner", type: "address" },
-      { name: "spender", type: "address" },
-    ],
-    outputs: [{ type: "uint256" }],
-  },
-  {
-    name: "approve",
-    type: "function",
-    stateMutability: "nonpayable",
-    inputs: [
-      { name: "spender", type: "address" },
-      { name: "amount", type: "uint256" },
-    ],
-    outputs: [{ type: "bool" }],
-  },
-] as const;
-
-// Uniswap V3 QuoterV2 — quoteExactInputSingle (struct-params variant).
-// Called via eth_call (publicClient.simulateContract) since the function
-// is marked nonpayable but is safe to simulate as a read.
-const QUOTER_V2_ABI = [
-  {
-    name: "quoteExactInputSingle",
-    type: "function",
-    stateMutability: "nonpayable",
-    inputs: [
-      {
-        name: "params",
-        type: "tuple",
-        components: [
-          { name: "tokenIn", type: "address" },
-          { name: "tokenOut", type: "address" },
-          { name: "amountIn", type: "uint256" },
-          { name: "fee", type: "uint24" },
-          { name: "sqrtPriceLimitX96", type: "uint160" },
-        ],
-      },
-    ],
-    outputs: [
-      { name: "amountOut", type: "uint256" },
-      { name: "sqrtPriceX96After", type: "uint160" },
-      { name: "initializedTicksCrossed", type: "uint32" },
-      { name: "gasEstimate", type: "uint256" },
-    ],
-  },
-] as const;
-
-const SWAP_ROUTER_ABI = [
-  {
-    name: "exactInputSingle",
-    type: "function",
-    stateMutability: "payable",
-    inputs: [
-      {
-        name: "params",
-        type: "tuple",
-        components: [
-          { name: "tokenIn", type: "address" },
-          { name: "tokenOut", type: "address" },
-          { name: "fee", type: "uint24" },
-          { name: "recipient", type: "address" },
-          { name: "amountIn", type: "uint256" },
-          { name: "amountOutMinimum", type: "uint256" },
-          { name: "sqrtPriceLimitX96", type: "uint160" },
-        ],
-      },
-    ],
-    outputs: [{ name: "amountOut", type: "uint256" }],
-  },
-] as const;
-
-// ── Intent builder ────────────────────────────────────────────────────────────
-
-/** Wrap a single EVM call as a Dispatch intent (no txHash yet — runner submits). */
-function intent(call: Call): Dispatch {
-  return { txHash: "0x", calls: [call], success: false, gasUsed: 0n };
-}
-
-// ── Agent ─────────────────────────────────────────────────────────────────────
-
-export const agent: Agent = {
-  name: "dca-rebalancer",
-  description:
-    `DCA into WETH with USDC on Base via Uniswap V3. ` +
-    `Rebalances when allocation drift exceeds ${REBALANCE_THRESHOLD * 100}%. ` +
-    `Slippage tolerance: ${SLIPPAGE_BPS / 100}%.`,
-
-  async tick(ctx: AgentContext): Promise<Dispatch[]> {
-    const { safe } = ctx;
-
-    ctx.log(`tick — block ${ctx.blockNumber}, sma ${safe}`);
-
-    // publicClient is injected by the runner via ctx.data._publicClient
-    // so the agent can make arbitrary on-chain reads (allowance, QuoterV2).
-    const pc = ctx.data._publicClient as PublicClient | undefined;
-    if (!pc) {
-      ctx.log("no publicClient in ctx.data — skipping tick");
-      return [];
-    }
-
-    const usdc = ALLOWED_TOKENS[0]!;
-    const weth = ALLOWED_TOKENS[1]!;
-
-    // ── Step 1: Check USDC balance ────────────────────────────────────────────
-    const usdcBalance = await ctx.read.balance(usdc);
-    ctx.log(`USDC balance: ${usdcBalance} (min to swap: ${MIN_USDC_TO_SWAP})`);
-
-    if (usdcBalance < MIN_USDC_TO_SWAP) {
-      ctx.log("USDC balance below minimum — skipping tick");
-      return [];
-    }
-
-    // ── Step 2: Check allowance — approve first if needed ─────────────────────
-    const allowance = await pc.readContract({
-      address: usdc,
-      abi: ERC20_ABI,
-      functionName: "allowance",
-      args: [safe, SWAP_ROUTER],
-    });
-
-    if (allowance < SWAP_AMOUNT_USDC) {
-      ctx.log(`allowance (${allowance}) < swap amount (${SWAP_AMOUNT_USDC}) — submitting approve`);
-      // Approve max uint256 once so subsequent ticks skip this step.
-      const approveCall: Call = {
-        target: usdc,
-        value: 0n,
-        data: encodeFunctionData({
-          abi: ERC20_ABI,
-          functionName: "approve",
-          args: [SWAP_ROUTER, 2n ** 256n - 1n],
-        }),
-      };
-      return [intent(approveCall)];
-    }
-
-    // ── Step 3: Quote via QuoterV2 — fail closed ──────────────────────────────
-    let expectedOut: bigint;
-    try {
-      const result = await pc.simulateContract({
-        address: QUOTER_V2,
-        abi: QUOTER_V2_ABI,
-        functionName: "quoteExactInputSingle",
-        args: [
-          {
-            tokenIn: usdc,
-            tokenOut: weth,
-            amountIn: SWAP_AMOUNT_USDC,
-            fee: SWAP_FEE_TIER,
-            sqrtPriceLimitX96: 0n,
-          },
-        ],
-      });
-      expectedOut = (result.result as [bigint, bigint, number, bigint])[0];
-    } catch (e) {
-      ctx.log(`QuoterV2 unavailable: ${(e as Error).message.slice(0, 100)} — skipping tick (fail closed)`);
-      return [];
-    }
-
-    if (expectedOut === 0n) {
-      ctx.log("QuoterV2 returned 0 expected output — skipping tick (fail closed)");
-      return [];
-    }
-
-    // ── Step 4: Compute amountOutMinimum with slippage ────────────────────────
-    const minOut = (expectedOut * BigInt(10_000 - SLIPPAGE_BPS)) / 10_000n;
-    ctx.log(
-      `quote: ${expectedOut} wei WETH, minOut (${SLIPPAGE_BPS / 100}% slippage): ${minOut}`,
-    );
-
-    // ── Step 5: Encode swap call ──────────────────────────────────────────────
-    const swapCall: Call = {
-      // Uniswap V3 SwapRouter02 on Base
-      target: SWAP_ROUTER,
-      value: 0n,
-      data: encodeFunctionData({
-        abi: SWAP_ROUTER_ABI,
-        functionName: "exactInputSingle",
-        args: [
-          {
-            tokenIn: usdc,
-            tokenOut: weth,
-            fee: SWAP_FEE_TIER,
-            recipient: safe,      // output stays in the SMA
-            amountIn: SWAP_AMOUNT_USDC,
-            amountOutMinimum: minOut, // slippage-protected — never 0
-            sqrtPriceLimitX96: 0n,
-          },
-        ],
-      }),
-    };
-
-    ctx.log(`submitting swap: ${SWAP_AMOUNT_USDC} USDC → WETH, minOut=${minOut}`);
-    return [intent(swapCall)];
-  },
-};