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

package/examples/permissions/BoundedSwap_UniswapV4_Unichain.sol

@@ -10,8 +10,8 @@ pragma solidity 0.8.26;
 // Target   : Universal Router  0xef740bf23acae26f6492b10de645d6b98dc8eaf3
 //            (verify on Uniscan before use)
 //
-// ENFORCED ON-CHAIN (via kernel evaluate() on every dispatch):
-//   execute(bytes,bytes[]) or execute(bytes,bytes[],uint256):
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked):
+//   execute(bytes,bytes[],uint256) selector 0x3593564c  /  execute(bytes,bytes[]) selector 0x24856bc3
 //     • target must be UNIVERSAL_ROUTER
 //     • first command byte (masking the allow-failure MSB) must be V4_SWAP (0x10)
 //     • exactly one command (single-swap path — disallow multi-hop command strings)
@@ -19,9 +19,13 @@ pragma solidity 0.8.26;
 //     • tokenIn (from poolKey, derived by zeroForOne) must be FIXED_CURRENCY_IN
 //     • tokenOut must be in ALLOWED_CURRENCIES_OUT
 //     • amountIn ≤ MAX_AMOUNT_IN
-//     • amountOutMinimum ≥ amountIn × MIN_BPS / 10 000
+//     • amountOutMinimum ≥ amountIn × MIN_BPS / 10 000  (slippage floor — see caveat below)
 //
-// NOT ENFORCED — documented limitations:
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
+//   • real (cross-denomination) slippage — see MIN_BPS caveat in evaluate()
+//   • swap frequency / cadence
+//
+// DOCUMENTED LIMITATIONS (on-chain, but intentionally not constrained):
 //   • hookData is not inspected (hooks can alter swap behavior on-chain; if the
 //     pool uses a hook that significantly changes execution, this permission cannot
 //     constrain it. Deploy against pools with address(0) hooks or audited hooks only.)
@@ -93,12 +97,10 @@ contract BoundedSwap_UniswapV4_Unichain is IPermission {
         MAX_AMOUNT_IN     = maxAmountIn;
         MIN_BPS           = minBps;
         for (uint256 i = 0; i < allowedCurrenciesOut.length; i++) {
-            isAllowedCurrenciesOut[allowedCurrenciesOut[i]] = true;
+            isAllowedCurrencyOut[allowedCurrenciesOut[i]] = true;
         }
     }
 
-    mapping(address => bool) private isAllowedCurrenciesOut;
-
     function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
         if (ctx.target != UNIVERSAL_ROUTER) return false;
         if (ctx.selector != SEL_EXECUTE_DEADLINE && ctx.selector != SEL_EXECUTE) return false;
@@ -133,8 +135,12 @@ contract BoundedSwap_UniswapV4_Unichain is IPermission {
         address tokenOut = p.zeroForOne ? p.poolKey.currency1 : p.poolKey.currency0;
 
         if (tokenIn != FIXED_CURRENCY_IN)            return false;
-        if (!isAllowedCurrenciesOut[tokenOut])       return false;
+        if (!isAllowedCurrencyOut[tokenOut])         return false;
         if (p.amountIn > MAX_AMOUNT_IN)              return false;
+        // Slippage floor: amountOutMinimum ≥ amountIn × MIN_BPS / 10 000.
+        // WARNING: compares tokenOut against tokenIn base units. For same-price/same-decimal
+        // pairs this maps to a slippage %. For cross-price pairs it is trivially satisfied —
+        // real slippage is enforced by the agent off-chain, not by this contract.
         if (p.amountOutMinimum < (uint256(p.amountIn) * MIN_BPS) / 10_000) return false;
 
         return true;

package/examples/permissions/BoundedTransfer_ERC20_Ethereum.sol

@@ -6,13 +6,13 @@ pragma solidity 0.8.26;
 // Version  : Standard ERC-20 (version-agnostic)
 // Chain    : Ethereum mainnet (works on any EVM — the most general example)
 //
-// ENFORCED ON-CHAIN (via kernel evaluate() on every dispatch):
-//   transfer(address to, uint256 amount)
-//   • target must be in ALLOWED_TOKENS
-//   • recipient (to) must be in ALLOWED_RECIPIENTS
-//   • amount ≤ MAX_AMOUNT_PER_TRANSFER
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked):
+//   transfer(address to,uint256 amount)  selector 0xa9059cbb
+//     • target must be in ALLOWED_TOKENS
+//     • recipient (to) must be in ALLOWED_RECIPIENTS
+//     • amount ≤ MAX_AMOUNT_PER_TRANSFER
 //
-// NOT ENFORCED (agent code — can change without a new contract):
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
 //   • transfer frequency / timing
 //   • choice of token within ALLOWED_TOKENS
 //   • choice of recipient within ALLOWED_RECIPIENTS

package/examples/permissions/BoundedVault_ERC4626_Base.sol

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : ERC-4626 (tokenized vault standard)
+// Version  : Standard EIP-4626 interface (version-agnostic)
+// Chain    : Base mainnet (8453) — reference vault below; works on any EVM
+// Target   : Reference vault — Moonwell Flagship USDC (MetaMorpho, ERC-4626)
+//            0xc1256Ae5FF1cf2719D4937adb3bbCCab2E00A2Ca  (verified ERC-4626 on Base: asset()=USDC)
+//            Written against the STANDARD interface, so it generalizes to any 4626 vault.
+//
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked):
+//   deposit(uint256 assets,address receiver)                  selector 0x6e553f65
+//     • target (the vault) must be in ALLOWED_VAULTS
+//     • assets ≤ MAX_DEPOSIT_ASSETS
+//     • receiver must equal ctx.account (the SMA — shares cannot be minted to another address)
+//   withdraw(uint256 assets,address receiver,address owner)   selector 0xb460af94
+//   redeem(uint256 shares,address receiver,address owner)     selector 0xba087652
+//     • target (the vault) must be in ALLOWED_VAULTS
+//     • receiver must equal ctx.account (assets cannot be sent elsewhere)
+//     • owner    must equal ctx.account (cannot burn shares the SMA merely has allowance over)
+//
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
+//   • Which vault within ALLOWED_VAULTS to use, and deposit/withdraw timing/cadence
+//   • Withdraw/redeem amount (only the receiver/owner are bound, not the size — the SMA can
+//     always withdraw its own position in full; add a cap here if your strategy needs one)
+//   • Underlying ASSET: enforced TRANSITIVELY via ALLOWED_VAULTS, not from calldata. A 4626
+//     vault's asset() is fixed at deploy; the deposit/withdraw calldata carries NO asset field,
+//     so the asset cannot be read from it. Allowlist only vaults whose asset() you have verified.
+//
+// VERIFY BEFORE USE:
+//   • Selectors are the EIP-4626 standard (verified via `cast sig`): deposit 0x6e553f65,
+//     withdraw 0xb460af94, redeem 0xba087652. (mint(uint256,address)=0x94bf804d is NOT gated
+//     here — add it if your agent mints shares by exact share count.)
+//   • Confirm each allowlisted vault actually implements ERC-4626 and its asset() is what you
+//     expect (e.g. on the reference vault, asset() == USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).
+//   • A deposit also needs a prior ERC-20 approve of the vault — gate that with a separate
+//     approve permission (see BoundedApproveAndCallBatch.sol for the atomic approve→call→reset pattern).
+//   • MAX_DEPOSIT_ASSETS is in the asset's base units (USDC = 6 decimals).
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedVault_ERC4626_Base is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedVault_ERC4626_Base");
+
+    mapping(address => bool) public isAllowedVault;
+    uint256 public immutable MAX_DEPOSIT_ASSETS;
+
+    // EIP-4626 standard selectors
+    bytes4 private constant SEL_DEPOSIT  = 0x6e553f65; // deposit(uint256,address)
+    bytes4 private constant SEL_WITHDRAW = 0xb460af94; // withdraw(uint256,address,address)
+    bytes4 private constant SEL_REDEEM   = 0xba087652; // redeem(uint256,address,address)
+
+    /// @param allowedVaults     ERC-4626 vaults the agent may deposit into / withdraw from
+    /// @param maxDepositAssets  Per-deposit cap in the asset's base units (must be > 0)
+    constructor(address[] memory allowedVaults, uint256 maxDepositAssets) {
+        require(allowedVaults.length > 0, "empty vault allowlist");
+        require(maxDepositAssets > 0,     "zero deposit cap");
+        MAX_DEPOSIT_ASSETS = maxDepositAssets;
+        for (uint256 i = 0; i < allowedVaults.length; i++) {
+            require(allowedVaults[i] != address(0), "zero vault address");
+            isAllowedVault[allowedVaults[i]] = true;
+        }
+    }
+
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+        if (!isAllowedVault[ctx.target]) return false;
+        if (txData.length < 4)           return false;
+
+        // deposit(uint256 assets, address receiver)
+        if (ctx.selector == SEL_DEPOSIT) {
+            if (txData.length < 4 + 2 * 32) return false;
+            (uint256 assets, address receiver) = abi.decode(txData[4:], (uint256, address));
+            if (assets > MAX_DEPOSIT_ASSETS) return false;
+            if (receiver != ctx.account)     return false; // shares must accrue to the SMA
+            return true;
+        }
+
+        // withdraw(uint256 assets, address receiver, address owner)
+        // redeem(uint256 shares,  address receiver, address owner)
+        // Identical parameter layout: (uint256, address, address).
+        // Amount (assets/shares) is NOT bounded — the SMA can always exit its full position.
+        // Add a maxWithdrawAssets constructor param and check here if your strategy needs a cap.
+        if (ctx.selector == SEL_WITHDRAW || ctx.selector == SEL_REDEEM) {
+            if (txData.length < 4 + 3 * 32) return false;
+            (, address receiver, address owner) = abi.decode(txData[4:], (uint256, address, address));
+            if (receiver != ctx.account) return false; // assets must return to the SMA
+            if (owner    != ctx.account) return false; // only the SMA's own shares may be burned
+            return true;
+        }
+
+        return false;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}

package/examples/permissions/README.md

@@ -27,14 +27,25 @@ You own what you deploy.
 
 ## Examples
 
+Each header has two blocks: **ENFORCES ON-CHAIN** (bounds the kernel checks in `evaluate()` on
+every dispatch — these actually hold) and **AGENT-ENFORCED / NOT BOUNDED HERE** (left to your
+off-chain agent code — these do *not* hold on-chain). Read both before deploying.
+
 | File | Protocol | Version | Chain | Status |
 |---|---|---|---|---|
 | `BoundedSwap_UniswapV3_Base.sol` | Uniswap Swap | V3 SwapRouter02 | Base | Full decode |
 | `BoundedSwap_UniswapV4_Unichain.sol` | Uniswap Swap | V4 Universal Router | Unichain | Partial decode — see header |
-| `BoundedBorrow_AaveV3_Arbitrum.sol` | Aave Borrow | V3 Pool | Arbitrum | Full decode — verify selector |
+| `BoundedBorrow_AaveV3_Arbitrum.sol` | Aave Borrow | V3 Pool | Arbitrum | Full decode |
+| `BoundedSupply_AaveV3_Arbitrum.sol` | Aave Supply | V3 Pool | Arbitrum | Full decode |
+| `BoundedVault_ERC4626_Base.sol` | ERC-4626 Vault deposit/withdraw | EIP-4626 standard | Base (any EVM) | Full decode |
+| `BoundedStake_Venice_Base.sol` | Venice (VVV) staking | sVVV staking | Base | Full decode |
 | `BoundedTransfer_ERC20_Ethereum.sol` | ERC-20 Transfer | — | Ethereum (any EVM) | Full decode |
-| `BoundedPerp_GMXv2_Arbitrum.sol` | GMX Perpetuals | V2 ExchangeRouter | Arbitrum | Partial decode — see header |
+| `BoundedPerp_GMXv2_Arbitrum.sol` | GMX Perpetuals | V2 ExchangeRouter | Arbitrum | Reference pattern — verify selector/struct/router against live GMX ABI (see header) |
 | `BoundedBet_Limitless_Base.sol` | Limitless Prediction | CTF Exchange | Base | UNVERIFIED ABI — see header |
+| `BoundedApproveAndCallBatch.sol` | Atomic approve→call→reset | Sail `IBatchPermission` | Any selective kernel | Full decode — batch-only (see note below) |
+
+The `interfaces/` directory holds `IPermission.sol` (single-call permissions) and
+`IBatchPermission.sol` (batch permissions — see the batch example).
 
 ## Using these examples
 
@@ -50,3 +61,19 @@ To deploy within a Sailor project (copy the .sol file to `mandates/` first):
 ```bash
 sailor mandate deploy --contract <Name> --args '[...]' --attach --sma <SMA>
 ```
+
+## Verify before you authorize
+
+Prove a permission accepts the calls you want and rejects the ones you don't — before paying
+registration gas — with `sailor mandate simulate` (off-chain `eth_call`, no gas, signs nothing):
+```bash
+sailor mandate simulate --address <permission> --calls calls.json
+```
+Every example here was checked this way (valid calls PASS, out-of-bounds calls FAIL).
+
+**Batch permissions are different.** `BoundedApproveAndCallBatch.sol` implements `IBatchPermission`
+and is gated by the kernel's `dispatchBatch`, not single `dispatch` — its single-call `evaluate()`
+deliberately returns `false`. `sailor mandate simulate` only probes single `evaluate()`, so it
+**cannot** verify a batch permission. Until simulate gains a batch mode, verify a batch permission
+by calling its `evaluateBatch(calls, ctx)` view directly (e.g. `cast call`) with the call sequences
+you expect to pass and fail — same fail-closed `eth_call` semantics, the correct entrypoint.

package/examples/permissions/SailCalldata.sol

@@ -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/examples/permissions/interfaces/IBatchPermission.sol

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// Mirrors SailProtocol contracts/interfaces/IBatchPermission.sol. A batch-aware
+// permission gates `dispatchBatch` — an ordered array of subcalls executed as one
+// atomic transaction. Exactly ONE batch permission is consulted per batch dispatch
+// (selective model), and it owns validation of every subcall AND the cross-call
+// invariants (ordering, matching amounts, mandatory cleanup) that no per-call
+// IPermission can express.
+
+/// @notice A single subcall in a batch dispatch.
+/// @dev The kernel executes each Call as safe.execTransactionFromModule(target, value, data, 0)
+///      — operation is always CALL, never DELEGATECALL.
+struct Call {
+    address target; // MUST NOT equal the kernel (enforced by the kernel)
+    uint256 value;  // native ETH forwarded (wei)
+    bytes   data;   // calldata for the subcall
+}
+
+/// @notice Execution context passed to evaluateBatch on each batch dispatch (read-only snapshot).
+struct BatchContext {
+    address account;        // the Safe (SMA) whose assets are moved
+    address manager;        // the delegated signer who authorised the batch
+    address submitter;      // msg.sender of the dispatch (may differ from manager via a relayer)
+    address permission;     // this batch permission contract
+    bytes32 batchHash;      // keccak256(abi.encode(calls)) — stable id for the exact sequence
+    uint256 blockTimestamp; // block.timestamp at dispatch
+    uint256 blockNumber;    // block.number at dispatch
+}
+
+interface IBatchPermission {
+    /// @notice Validate an entire batch of subcalls. Called via staticcall under a gas cap;
+    ///         a revert / OOG / malformed return is treated as `false` (fail-closed).
+    function evaluateBatch(Call[] calldata calls, BatchContext calldata ctx) external view returns (bool);
+
+    /// @notice Marker the kernel uses (try/catch) to detect batch-aware permissions. MUST return true.
+    function isBatchPermission() external pure returns (bool);
+}

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@dev.sail.money/sailor",
-  "version": "0.0.2",
+  "version": "1.0.0-38",
   "description": "Operator toolkit for Sail Protocol",
   "bin": {
     "sailor": "packages/cli/dist/index.cjs"
   },
+  "exports": {
+    "./sdk": {
+      "import": "./packages/sdk/dist/index.js",
+      "types": "./packages/sdk/dist/index.d.ts"
+    }
+  },
   "files": [
     "packages/cli/dist",
     "packages/sdk/dist",
@@ -17,23 +23,22 @@
     "README.md",
     "AGENTS.md"
   ],
-  "devDependencies": {
-    "@biomejs/biome": "^1.9.0",
-    "typescript": "^5.5.0"
-  },
-  "dependencies": {
-    "tsx": "^4.22.4"
-  },
   "scripts": {
-    "build": "pnpm --filter @sail/sdk build && pnpm --filter @sail/chains build && pnpm --filter sailor build && pnpm --filter sailor-ui build",
+    "build": "pnpm --filter @sail/sdk build && pnpm --filter sailor build && pnpm --filter sailor-ui build",
     "test": "pnpm --filter sailor-ui test",
     "test:ui": "pnpm --filter sailor-ui test:ui",
     "link:cli": "pnpm link --global",
-    "postinstall": "node scripts/postinstall.js",
-    "typecheck": "pnpm --filter @sail/sdk build && pnpm --filter @sail/chains build && pnpm -r typecheck",
+    "typecheck": "pnpm --filter @sail/sdk build && pnpm -r typecheck",
     "docs:check": "node scripts/check-docs.mjs",
     "init:check": "node scripts/check-init.mjs",
     "eval": "node evals/run.mjs",
     "lint": "biome check ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "typescript": "^5.5.0"
+  },
+  "dependencies": {
+    "tsx": "^4.22.4"
   }
-}
+}