@dev.sail.money/sailor 0.0.2 → 1.0.0-38

package/templates/default/examples/dca/agent.ts

@@ -0,0 +1,174 @@
+// Reference example — not the user's strategy. Consult for patterns; author the user's own in src/.
+// Shows: a complete DCA tick loop — USDC→WETH via Uniswap V3 on Base mainnet.
+// To adapt: replace token addresses, protocol ABIs, and swap logic with your target strategy.
+
+import type { Agent, AgentContext, Call, Dispatch } from "@sail.money/sailor/sdk";
+import { encodeFunctionData, type PublicClient } from "viem";
+import {
+  ALLOWED_TOKENS,
+  MIN_USDC_TO_SWAP,
+  QUOTER_V2,
+  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;
+
+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 ────────────────────────────────────────────────────────────
+
+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. Slippage tolerance: ${SLIPPAGE_BPS / 100}%.`,
+
+  async tick(ctx: AgentContext): Promise<Dispatch[]> {
+    const { safe } = ctx;
+    ctx.log(`tick — block ${ctx.blockNumber}, sma ${safe}`);
+
+    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 — submitting approve`);
+      return [intent({
+        target: usdc,
+        value: 0n,
+        data: encodeFunctionData({ abi: ERC20_ABI, functionName: "approve", args: [SWAP_ROUTER, 2n ** 256n - 1n] }),
+      })];
+    }
+
+    // Step 3: Quote via QuoterV2 — fail closed on any error
+    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`);
+      return [];
+    }
+    if (expectedOut === 0n) {
+      ctx.log("QuoterV2 returned 0 — skipping");
+      return [];
+    }
+
+    // Step 4: Encode swap with slippage protection
+    const minOut = (expectedOut * BigInt(10_000 - SLIPPAGE_BPS)) / 10_000n;
+    ctx.log(`quote: ${expectedOut} wei WETH, minOut (${SLIPPAGE_BPS / 100}% slippage): ${minOut}`);
+    return [intent({
+      target: SWAP_ROUTER,
+      value: 0n,
+      data: encodeFunctionData({
+        abi: SWAP_ROUTER_ABI,
+        functionName: "exactInputSingle",
+        args: [{ tokenIn: usdc, tokenOut: weth, fee: SWAP_FEE_TIER, recipient: safe, amountIn: SWAP_AMOUNT_USDC, amountOutMinimum: minOut, sqrtPriceLimitX96: 0n }],
+      }),
+    })];
+  },
+};

package/templates/{dca-rebalancer/src → default/examples/dca}/mandate.ts

@@ -1,4 +1,7 @@
-import type { Address } from "@sail/sdk";
+// Reference example — not the user's strategy. Consult for patterns; author the user's own in src/.
+// Shows: token addresses, swap parameters, and contract addresses for a USDC→WETH DCA on Base mainnet.
+
+import type { Address } from "@sail.money/sailor/sdk";
 
 // ── Token addresses (Base mainnet) ────────────────────────────────────────────
 
@@ -14,38 +17,18 @@ export const ALLOWED_TOKENS: Address[] = [
 
 // ── Swap parameters ───────────────────────────────────────────────────────────
 
-/**
- * Amount of USDC to spend per swap (in USDC base units, 6 decimals).
- * Default: 5 USDC. Adjust before deploying to production.
- */
+/** Amount of USDC to spend per swap (in USDC base units, 6 decimals). Default: 5 USDC. */
 export const SWAP_AMOUNT_USDC = 5_000_000n; // 5 USDC
 
-/**
- * Minimum USDC balance the SMA must hold before a swap is attempted.
- * Must be ≥ SWAP_AMOUNT_USDC. Adds a safety margin so a single swap
- * doesn't drain the account to zero.
- */
+/** Minimum USDC balance the SMA must hold before a swap is attempted. */
 export const MIN_USDC_TO_SWAP = 6_000_000n; // 6 USDC
 
-/**
- * Slippage tolerance in basis points (100 = 1%).
- * amountOutMinimum = quote × (1 − SLIPPAGE_BPS / 10 000).
- * If no quote is available, the agent skips the swap entirely (fail closed).
- *
- * Tighten for large trades or illiquid pairs; loosen if valid swaps are
- * frequently denied by price impact. Default 1% is conservative for
- * USDC/WETH on Base.
- */
+/** Slippage tolerance in basis points (100 = 1%). */
 export const SLIPPAGE_BPS = 100; // 1%
 
-/**
- * Uniswap V3 pool fee tier for the USDC/WETH pool on Base.
- * 500 = 0.05% — the most liquid USDC/WETH pool on Base mainnet.
- */
+/** Uniswap V3 pool fee tier for the USDC/WETH pool on Base (500 = 0.05%). */
 export const SWAP_FEE_TIER = 500;
 
-// ── Rebalancing ───────────────────────────────────────────────────────────────
-
 /** Rebalance when allocation drift exceeds this fraction (0.05 = 5%). */
 export const REBALANCE_THRESHOLD = 0.05;
 
@@ -57,11 +40,6 @@ export const SWAP_ROUTER: Address = "0x2626664c2603336E57B271c5C0b26F421741e481"
 /**
  * Uniswap V3 QuoterV2 on Base.
  * Called off-chain (via eth_call) to obtain the expected output amount
- * before computing amountOutMinimum. If this call fails, the agent skips
- * the swap — it never submits with amountOutMinimum = 0.
- *
- * Note: amountOutMinimum is set by the agent from the QuoterV2 result.
- * For defense-in-depth, add an on-chain minimum check in your permission
- * contract so the kernel also validates the minimum out requirement.
+ * before computing amountOutMinimum.
  */
 export const QUOTER_V2: Address = "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a";

package/templates/{dca-rebalancer → default}/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "dca-rebalancer",
+  "name": "sail-agent",
   "version": "0.1.0",
-  "description": "Dollar-cost-average rebalancer — starter Sail Protocol agent",
+  "description": "Sail Protocol agent starter",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit"

package/templates/default/src/agent.ts

@@ -0,0 +1,37 @@
+/**
+ * Your agent — implement your strategy here.
+ *
+ * The runner calls tick() on every interval. Return an array of Dispatch intents;
+ * the runner submits each one through the kernel against a matching registered permission.
+ * Return [] to skip this tick (no gas spent).
+ *
+ * The runner resolves which permission authorizes each call automatically — you
+ * express what you want to do; you do not name permissions per call.
+ *
+ * For a worked end-to-end example (DCA / Uniswap V3 / Base):
+ *   see examples/dca/agent.ts and examples/dca/mandate.ts
+ */
+
+import type { Agent, AgentContext, Dispatch } from "@sail.money/sailor/sdk";
+
+export const agent: Agent = {
+  name: "my-agent",
+  description: "Describe your strategy here.",
+
+  async tick(ctx: AgentContext): Promise<Dispatch[]> {
+    ctx.log(`tick — block ${ctx.blockNumber}, sma ${ctx.safe}`);
+
+    // TODO: implement your strategy.
+    // Read on-chain state, decide what to do, return intent dispatches.
+    // ctx.read.balance(tokenAddress) — read token balance of the SMA
+    // ctx.data._publicClient — viem PublicClient for arbitrary on-chain reads
+    // ctx.log(msg) — append a message to the activity log
+    //
+    // Example (from examples/dca/agent.ts):
+    //   const balance = await ctx.read.balance(USDC_ADDRESS);
+    //   if (balance < MIN_AMOUNT) return [];
+    //   return [{ txHash: "0x", calls: [{ target: ROUTER, value: 0n, data: swapCalldata }], success: false, gasUsed: 0n }];
+
+    return [];
+  },
+};

package/templates/default/src/config.ts

@@ -0,0 +1,24 @@
+/** Reads RPC_URL and CHAIN_ID from environment (set via .sail/.env.local or GitHub Secrets). */
+export function getEnvConfig(): { rpcUrl: string; chainId: number } {
+  const rpcUrl = process.env["RPC_URL"];
+  if (!rpcUrl) {
+    throw new Error(
+      "RPC_URL is not set.\n" +
+        "Add RPC_URL to .sail/.env.local or set it as an environment variable.",
+    );
+  }
+
+  if (!process.env["CHAIN_ID"]) {
+    throw new Error(
+      "CHAIN_ID is not set.\n" +
+        "Open this folder in your AI coding assistant and say 'start' — Stage 1 will ask\n" +
+        "which chain you want and set CHAIN_ID in .sail/.env.local.",
+    );
+  }
+  const chainId = Number(process.env["CHAIN_ID"]);
+  if (Number.isNaN(chainId)) {
+    throw new Error(`Invalid CHAIN_ID: ${process.env["CHAIN_ID"]}`);
+  }
+
+  return { rpcUrl, chainId };
+}

package/templates/default/src/mandate.ts

@@ -0,0 +1,22 @@
+/**
+ * Strategy parameters and contract addresses for your agent.
+ *
+ * Put your token addresses, protocol contracts, amounts, and other
+ * constants here. Import them into agent.ts.
+ *
+ * For a worked example (DCA / USDC→WETH / Uniswap V3 / Base):
+ *   see examples/dca/mandate.ts
+ *
+ * For protocol-specific permission examples (Uniswap, Aave, GMX, …):
+ *   see examples/permissions/
+ */
+
+// TODO: replace with your strategy's parameters.
+// Example structure:
+//
+// import type { Address } from "@sail/sdk";
+//
+// export const INPUT_TOKEN: Address = "0x...";   // token you're spending
+// export const OUTPUT_TOKEN: Address = "0x...";  // token you're acquiring
+// export const MAX_AMOUNT_PER_TICK = 0n;         // in input token base units
+// export const PROTOCOL_CONTRACT: Address = "0x..."; // target contract

package/templates/default/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@sail.money/sailor/sdk": ["../../packages/sdk/src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}

package/templates/lifi-permissions/README.md

@@ -17,7 +17,7 @@ These follow the `CloneInitializable` pattern: the constructor calls
 > no Foundry build. Build/deploy happens in that project via
 > `scripts/deploy-clone-templates.ts`.
 
-> **Note:** The kernels bundled in `@sail/sdk` (Base, Base Sepolia, Arbitrum, Unichain) now all run the **selective** dispatch model — verified on-chain against each kernel's `DISPATCH_TYPEHASH`. These templates were written for the older conjunctive model and include pass-through logic (`return true` for calls outside their domain) that is not required on selective kernels. Review before deploying against a selective kernel; the pass-through logic is harmless but unnecessary.
+> **Note:** The kernels bundled in `@sail.money/sailor/sdk` (Base, Base Sepolia, Arbitrum, Unichain) now all run the **selective** dispatch model — verified on-chain against each kernel's `DISPATCH_TYPEHASH`. These templates were written for the older conjunctive model and include pass-through logic (`return true` for calls outside their domain) that is not required on selective kernels. Review before deploying against a selective kernel; the pass-through logic is harmless but unnecessary.
 
 ## Contracts
 

package/packages/ui/dist/assets/cursor-DV7rOqbJ.js

@@ -1,3 +0,0 @@
-import{F as o}from"./core-Ckx_cyuH.js";import"./index-Q2Yai4Fe.js";import"./events-CiKP71cK.js";import"./index.es-C78cE5SI.js";import"./fallback-Ofl6uSnB.js";const l=o` <svg fill="none" viewBox="0 0 13 4">
-  <path fill="currentColor" d="M.5 0h12L8.9 3.13a3.76 3.76 0 0 1-4.8 0L.5 0Z" />
-</svg>`;export{l as cursorSvg};