@dev.sail.money/sailor 0.1.0-local → 1.0.0-38

package/examples/permissions/BoundedVault_ERC4626_Base.sol

@@ -1,97 +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; }
-}
+// 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

@@ -1,79 +1,79 @@
-# Permission Examples
-
-These are example permission contracts for common DeFi protocols, maintained by Sailor.
-
-**They are not part of Sail Protocol. They are not audited by Sail. They are not a supported
-or exhaustive set.** The protocol accepts any contract implementing IPermission — these examples
-teach the bounding pattern for specific protocols so you (and your AI agent) can adapt them or
-write your own.
-
-## Permissions are only as strong as the protocol is on-chain
-
-A permission is evaluated by the kernel on every dispatch — but it can only see what happens
-on-chain. For venues with off-chain order matching (e.g. Polymarket, Hyperliquid), a permission
-can constrain deposits, withdrawals, and sub-accounts, but NOT the orders your agent signs
-off-chain. Prefer fully on-chain venues — Uniswap, Aave, GMX, Synthetix, Limitless — where every
-action passes through the kernel and your bounds actually hold.
-
-## Permissions are protocol- and version-specific
-
-Calldata differs by protocol and by version. A Uniswap V3 swap is a different decode than a
-Uniswap V4 swap. Use the example closest to YOUR exact protocol+version+chain, verify the decode
-against the protocol's real ABI, and confirm what it enforces before deploying.
-
-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 |
-| `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 | 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
-
-Each file is self-contained and explains in its header exactly what is and is not enforced.
-Read the header before deploying.
-
-To compile:
-```bash
-forge build
-```
-
-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.
+# Permission Examples
+
+These are example permission contracts for common DeFi protocols, maintained by Sailor.
+
+**They are not part of Sail Protocol. They are not audited by Sail. They are not a supported
+or exhaustive set.** The protocol accepts any contract implementing IPermission — these examples
+teach the bounding pattern for specific protocols so you (and your AI agent) can adapt them or
+write your own.
+
+## Permissions are only as strong as the protocol is on-chain
+
+A permission is evaluated by the kernel on every dispatch — but it can only see what happens
+on-chain. For venues with off-chain order matching (e.g. Polymarket, Hyperliquid), a permission
+can constrain deposits, withdrawals, and sub-accounts, but NOT the orders your agent signs
+off-chain. Prefer fully on-chain venues — Uniswap, Aave, GMX, Synthetix, Limitless — where every
+action passes through the kernel and your bounds actually hold.
+
+## Permissions are protocol- and version-specific
+
+Calldata differs by protocol and by version. A Uniswap V3 swap is a different decode than a
+Uniswap V4 swap. Use the example closest to YOUR exact protocol+version+chain, verify the decode
+against the protocol's real ABI, and confirm what it enforces before deploying.
+
+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 |
+| `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 | 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
+
+Each file is self-contained and explains in its header exactly what is and is not enforced.
+Read the header before deploying.
+
+To compile:
+```bash
+forge build
+```
+
+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

@@ -1,118 +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));
-    }
-}
+// 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/foundry.toml

@@ -1,10 +1,10 @@
-[profile.default]
-src = "."
-out = "out"
-libs = ["lib"]
-remappings = ["@sail/interfaces/=interfaces/"]
-solc = "0.8.26"
-optimizer = true
-optimizer_runs = 200
-# Examples compile with: forge build (from this directory)
-# Deploy within a Sailor project using: sailor mandate deploy --contract <Name> --args '[...]'
+[profile.default]
+src = "."
+out = "out"
+libs = ["lib"]
+remappings = ["@sail/interfaces/=interfaces/"]
+solc = "0.8.26"
+optimizer = true
+optimizer_runs = 200
+# Examples compile with: forge build (from this directory)
+# Deploy within a Sailor project using: sailor mandate deploy --contract <Name> --args '[...]'