npm - @dev.sail.money/sailor - Versions diffs - 0.0.2-23 → 0.0.2-24 - Mend

@dev.sail.money/sailor 0.0.2-23 → 0.0.2-24

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 (113) hide show

package/packages/ui/dist/assets/{walletconnect-BuShZt17.js → walletconnect-CjirfANF.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as l}from"./core-B0JxSbAV.js";import"./index-yQSvDbVa.js";import"./events-DC84dMPF.js";import"./index.es-BiIWW5o1.js";import"./fallback-BOfZ_bwu.js";const o=l`<svg fill="none" viewBox="0 0 96 67">
+import{F as l}from"./core-BlknpGLl.js";import"./index-CL1Pp-W8.js";import"./events-BPX61gpp.js";import"./index.es-5g6Py2iz.js";import"./fallback-DTghxJb4.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-DMs8QNCr.js → warning-circle-CqS0eXEs.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as r}from"./core-B0JxSbAV.js";import"./index-yQSvDbVa.js";import"./events-DC84dMPF.js";import"./index.es-BiIWW5o1.js";import"./fallback-BOfZ_bwu.js";const a=r`<svg fill="none" viewBox="0 0 20 20">
+import{F as r}from"./core-BlknpGLl.js";import"./index-CL1Pp-W8.js";import"./events-BPX61gpp.js";import"./index.es-5g6Py2iz.js";import"./fallback-DTghxJb4.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-DzP75KD1.js → x-DQeWAjll.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as l}from"./core-B0JxSbAV.js";import"./index-yQSvDbVa.js";import"./events-DC84dMPF.js";import"./index.es-BiIWW5o1.js";import"./fallback-BOfZ_bwu.js";const a=l`<svg fill="none" viewBox="0 0 41 40">
+import{F as l}from"./core-BlknpGLl.js";import"./index-CL1Pp-W8.js";import"./events-BPX61gpp.js";import"./index.es-5g6Py2iz.js";import"./fallback-DTghxJb4.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-yQSvDbVa.js"></script>
+    <script type="module" crossorigin src="/assets/index-CL1Pp-W8.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DCnJ64lX.css">
   </head>
   <body>

package/templates/custom-mandate/README.md CHANGED Viewed

@@ -78,8 +78,39 @@ Both attach paths open the browser signing station so the owner authorizes the r
 > contract address you provide. A bug can block all agent activity or authorize transactions you did
 > not intend. Review carefully before attaching.**
+## Extracting calldata parameters safely
+When you need to bound a specific call argument (amount cap, recipient check, slippage floor),
+use `SailCalldata` instead of manual `abi.decode`. The two common bugs it prevents:
+1. **Forgetting the length check** — decoding before checking `txData.length` can revert or
+   silently return wrong values. `SailCalldata.hasParams(txData, N)` is the one-line guard.
+2. **Wrong slot index** — off-by-one decodes the wrong parameter. Named helpers make the
+   intent explicit: `asAddress(txData, 0)`, `asUint256(txData, 1)`, `asAddress(txData, 2)`.
+```solidity
+import {SailCalldata} from "./SailCalldata.sol";
+function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+    if (ctx.target != POOL)        return false;
+    if (ctx.selector != SEL_SUPPLY) return false;
+    // supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)
+    if (!SailCalldata.hasParams(txData, 4)) return false;
+    address asset      = SailCalldata.asAddress(txData, 0);
+    uint256 amount     = SailCalldata.asUint256(txData, 1);
+    address onBehalfOf = SailCalldata.asAddress(txData, 2);
+    // ...
+}
+```
+Available helpers: `asAddress`, `asUint256`, `asInt256`, `asBytes32`, `asBool`,
+`asUint128`, `asUint64`, `asUint32`, `asUint24`, `asUint16`, `asBytes4`.
+Only covers static (fixed-size) types. For `bytes`, `string`, or dynamic arrays,
+use `abi.decode(txData[4:], ...)` after the `hasParams` guard.
 ## Structure
 - `foundry.toml` — Foundry config with `@sail/` remapping to `.sail/contracts/`
 - `.sail/contracts/interfaces/IPermission.sol` — interface copy (matches SailProtocol)
 - `mandates/BoundedCallPermission.sol` — general primitive: allowlisted targets, optional selector filter, max ETH value
+- `mandates/SailCalldata.sol` — safe calldata parameter extraction helpers

package/templates/custom-mandate/mandates/BoundedCallPermission.sol CHANGED Viewed

@@ -2,12 +2,18 @@
 pragma solidity 0.8.26;
 import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+// SailCalldata: safe helpers for extracting calldata parameters inside evaluate().
+// Use SailCalldata.hasParams(txData, N) + SailCalldata.asAddress/asUint256/... instead of
+// manual abi.decode when you need to bound specific call arguments (amounts, recipients, etc.).
+// See SailCalldata.sol for the full API and examples/permissions/ for protocol examples.
+import {SailCalldata} from "./SailCalldata.sol";
 /// @title BoundedCallPermission
 /// @notice General-purpose IPermission primitive. Bounds the universal properties of any call:
 ///         allowed targets, allowed selectors, and max ETH value. Protocol-agnostic.
-///         For calldata-parameter bounds (amount caps, recipient checks, slippage), write a
-///         protocol-specific permission — see examples/permissions/ for the pattern per protocol.
+///         For calldata-parameter bounds (amount caps, recipient checks, slippage), use
+///         SailCalldata (imported above) and write a protocol-specific permission —
+///         see examples/permissions/ for the pattern per protocol.
 /// @dev Deploy one instance per SMA with constructor-configured parameters.
 contract BoundedCallPermission is IPermission {
     bytes32 private constant DISCRIMINATOR = keccak256("BoundedCallPermission");

package/templates/custom-mandate/mandates/SailCalldata.sol ADDED Viewed

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+// ─────────────────────────────────────────────────────────────────────────────
+// SailCalldata — safe static-parameter extraction for IPermission.evaluate()
+//
+// PROBLEM
+//   evaluate(bytes calldata txData, Context calldata ctx) receives raw ABI-
+//   encoded calldata. Extracting parameters by hand is the most dangerous part
+//   of permission writing:
+//     • Forgetting the length check before decoding → silent wrong value or
+//       revert instead of clean `return false`.
+//     • Wrong slot index → decoding the wrong parameter (type-checks, still wrong).
+//     • Truncation bugs when casting uint256 slots to address (padding bits).
+//
+// SOLUTION
+//   This library centralises the three operations into named helpers:
+//     1. hasParams()  — explicit length guard (call once, at the top of evaluate)
+//     2. asAddress()  — extract + mask to 20 bytes
+//     3. asUint256(), asInt256(), asBytes32(), asBool(), asUint128() — typed slots
+//
+//   All helpers are view/pure and add zero gas overhead beyond the slice itself.
+//
+// USAGE (replace abi.decode pattern)
+//
+//   // Before:
+//   if (txData.length < 4 + 3 * 32) return false;
+//   (address asset, uint256 amount, address onBehalfOf) =
+//       abi.decode(txData[4:], (address, uint256, address));
+//
+//   // After:
+//   if (!SailCalldata.hasParams(txData, 3)) return false;
+//   address  asset      = SailCalldata.asAddress(txData, 0);
+//   uint256  amount     = SailCalldata.asUint256(txData, 1);
+//   address  onBehalfOf = SailCalldata.asAddress(txData, 2);
+//
+// LIMITATIONS
+//   Only covers static (fixed-size) ABI types. Dynamic types (bytes, string,
+//   arrays) use pointer indirection — decode them with abi.decode(txData[4:], ...)
+//   after the hasParams() guard, or write a dedicated extractor.
+//
+// SLOT INDEXING
+//   Slots are 0-indexed from the first constructor parameter (after the 4-byte
+//   selector). Slot 0 = bytes [4..35], slot 1 = bytes [36..67], etc.
+// ─────────────────────────────────────────────────────────────────────────────
+library SailCalldata {
+    // ── Guards ────────────────────────────────────────────────────────────────
+    /// @notice Returns true when txData is long enough to hold `params` static
+    ///         32-byte ABI slots after the 4-byte selector.
+    /// @dev    Call this once at the top of evaluate() before any slot access.
+    ///         Returns false (not revert) so evaluate() can return false cleanly.
+    function hasParams(bytes calldata txData, uint256 params) internal pure returns (bool) {
+        return txData.length >= 4 + params * 32;
+    }
+    // ── Static-type extractors ────────────────────────────────────────────────
+    // All assume hasParams() has already been checked for the relevant slot.
+    // Accessing an out-of-bounds slot will cause the calldata slice to revert —
+    // always guard with hasParams() first.
+    /// @notice Extract an address from ABI slot `i` (0-indexed after selector).
+    ///         Masks to 20 bytes, discarding the ABI zero-padding in the upper 12.
+    function asAddress(bytes calldata txData, uint256 i) internal pure returns (address) {
+        return address(uint160(uint256(bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32]))));
+    }
+    /// @notice Extract a uint256 from ABI slot `i`.
+    function asUint256(bytes calldata txData, uint256 i) internal pure returns (uint256) {
+        return uint256(bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32]));
+    }
+    /// @notice Extract an int256 from ABI slot `i`.
+    function asInt256(bytes calldata txData, uint256 i) internal pure returns (int256) {
+        return int256(uint256(bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32])));
+    }
+    /// @notice Extract a bytes32 from ABI slot `i`.
+    function asBytes32(bytes calldata txData, uint256 i) internal pure returns (bytes32) {
+        return bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32]);
+    }
+    /// @notice Extract a bool from ABI slot `i` (true when slot value is non-zero).
+    function asBool(bytes calldata txData, uint256 i) internal pure returns (bool) {
+        return asUint256(txData, i) != 0;
+    }
+    /// @notice Extract a uint128 from ABI slot `i` (lower 128 bits of the slot).
+    function asUint128(bytes calldata txData, uint256 i) internal pure returns (uint128) {
+        return uint128(asUint256(txData, i));
+    }
+    /// @notice Extract a uint64 from ABI slot `i`.
+    function asUint64(bytes calldata txData, uint256 i) internal pure returns (uint64) {
+        return uint64(asUint256(txData, i));
+    }
+    /// @notice Extract a uint32 from ABI slot `i`.
+    function asUint32(bytes calldata txData, uint256 i) internal pure returns (uint32) {
+        return uint32(asUint256(txData, i));
+    }
+    /// @notice Extract a uint24 from ABI slot `i` (e.g. Uniswap fee tier).
+    function asUint24(bytes calldata txData, uint256 i) internal pure returns (uint24) {
+        return uint24(asUint256(txData, i));
+    }
+    /// @notice Extract a uint16 from ABI slot `i` (e.g. Aave referral code).
+    function asUint16(bytes calldata txData, uint256 i) internal pure returns (uint16) {
+        return uint16(asUint256(txData, i));
+    }
+    /// @notice Extract bytes4 (a function selector) from ABI slot `i`.
+    function asBytes4(bytes calldata txData, uint256 i) internal pure returns (bytes4) {
+        return bytes4(asBytes32(txData, i));
+    }
+}

package/templates/default/AGENTS.md CHANGED Viewed

@@ -56,11 +56,41 @@ I'll write the permission contracts that bound your agent, prove in plain Englis
 Permission contracts live in `mandates/`. The user authors, reviews, and owns them. For examples by protocol and chain, see `examples/permissions/`.
+**Prerequisite — Foundry:** `forge build` requires the Foundry toolchain. If `forge` is not found, install it:
+```bash
+curl -L https://foundry.paradigm.xyz | bash   # then restart shell
+foundryup
+```
+**Approve coverage — mandatory:** ERC-20 `approve()` calls are NOT covered by supply or deposit permission contracts. If your strategy approves a token before supplying, you MUST deploy a separate bounded-approve permission that covers that specific `(token, spender, maxAmount)` combination, and authorize it alongside the supply permission. An agent that calls `approve()` without a matching permission will be rejected by the kernel.
+**Batching:** if a strategy tick needs to approve before supplying, build both calls into a single dispatch array — `[approveCall, supplyCall]` — not two separate ticks. Splitting them wastes a tick and the approval sits exposed until the next run.
 ```bash
 forge build
 sailor mandate deploy --contract <Name> --sma <SMA>   # deploy only — do NOT --attach yet
 ```
+**Constructor args:** quoting rules differ by shell.
+Bash / Git Bash:
+```bash
+sailor mandate deploy --contract <Name> --args '["0xToken","1000000"]' --sma <SMA>
+```
+PowerShell — use escaped inner quotes inside single quotes:
+```powershell
+sailor mandate deploy --contract <Name> --args '[\"0xToken\",\"1000000\"]' --sma <SMA>
+```
+Any shell — `--args-file` avoids quoting entirely:
+```json
+["0xToken", "1000000"]
+```
+```bash
+sailor mandate deploy --contract <Name> --args-file args.json --sma <SMA>
+```
 Before AUTHORIZING (attaching) the permission, BACK the plain-English claims with an actual on-chain probe. `evaluate()` lives on the deployed contract, so deploy first, then — before the irreversible authorization — generate sample calls from the user's stated strategy (ones the permission MUST accept and ones it MUST reject) and run them through `sailor mandate simulate`. This is an off-chain `eth_call` (no gas, no signing) that reports what the permission's `evaluate()` returns for each call, and flags any target with no contract code (a wrong or wrong-chain address):
 ```bash
@@ -90,13 +120,30 @@ sailor run --once    # single tick — confirm it works before automating
 For GitHub Actions:
 1. Run `sailor keys export-ci` — copies your encrypted agent wallet to `ci-keystore.json` in the project root and adds it to `.gitignore` as an allowed file. The keystore is geth v3 encrypted; the raw private key is never exposed.
-2. Commit and push `ci-keystore.json`:
+2. Commit the required files. CI needs these non-secret files to be in the repo:
    ```bash
-   git add ci-keystore.json && git commit -m "chore: add CI keystore" && git push
+   npm install                  # generate package-lock.json if it doesn't exist
+   git add ci-keystore.json package-lock.json .sail/account.json .sail/config.json .sail/mandate.json
+   git commit -m "chore: add CI keystore and sail state" && git push
    ```
+   `package-lock.json` is required by `npm ci` (used in the workflow). `.sail/account.json`, `.sail/config.json`, and `.sail/mandate.json` contain only public addresses and flags — no secrets. The `.gitignore` already has `!` exceptions for all of these.
 3. Add two secrets in GitHub (Settings → Secrets → Actions):
    - `SAIL_PASSPHRASE` — the passphrase that encrypts your agent wallet
    - `RPC_URL` — your RPC endpoint
+4. Install the `gh` CLI — required to manage the workflow from the terminal (trigger runs, check logs, add secrets without opening the browser):
+   - macOS: `brew install gh`
+   - Windows: `winget install --id GitHub.cli` or `scoop install gh`
+   - Linux: see https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+   Then authenticate with the `workflow` scope:
+   ```bash
+   gh auth login --scopes workflow
+   ```
+   The `workflow` scope is required — without it, `gh` cannot trigger or inspect Actions runs. Verify with:
+   ```bash
+   gh auth status          # confirm workflow scope is listed
+   gh workflow run agent-tick.yml   # manual trigger
+   gh run list --workflow agent-tick.yml   # check run history
+   ```
 The scaffolded workflow at `.github/workflows/agent-tick.yml` picks up `ci-keystore.json`, unlocks it with `SAIL_PASSPHRASE`, and runs on the configured schedule. No private key ever appears in the workflow or in secrets.
@@ -120,3 +167,5 @@ Use `buildDispatchSignature` from `@sail.money/sdk` — it reads the on-chain `D
 - Do not hardcode the dispatch model — detect it on-chain
 - Do not present example permissions as audited or as a supported menu
 - Do not commit `SAIL_PASSPHRASE` or private keys
+- Do not write a supply or deposit permission without also deploying a bounded-approve permission for each token the agent will approve — approve calls have no mandate coverage otherwise
+- Do not pass `--args` inline JSON from PowerShell — use `--args-file` instead

package/packages/ui/dist/assets/cursor-D3cYdnOt.js DELETED Viewed

@@ -1,3 +0,0 @@
-import{F as o}from"./core-B0JxSbAV.js";import"./index-yQSvDbVa.js";import"./events-DC84dMPF.js";import"./index.es-BiIWW5o1.js";import"./fallback-BOfZ_bwu.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};