@dev.sail.money/sailor 0.0.2 → 0.1.0-local

package/examples/permissions/BoundedTransfer_ERC20_Ethereum.sol

@@ -1,73 +1,73 @@
-// SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Protocol : ERC-20
-// 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
-//
-// NOT ENFORCED (agent code — can change without a new contract):
-//   • transfer frequency / timing
-//   • choice of token within ALLOWED_TOKENS
-//   • choice of recipient within ALLOWED_RECIPIENTS
-//
-// VERIFY BEFORE USE:
-//   • Selector 0xa9059cbb = transfer(address,uint256) — universally standard.
-//   • ALLOWED_TOKENS prevents the agent from transferring tokens not in the set.
-//     If a protocol uses non-standard transfer methods (e.g. transferFrom or
-//     proprietary hooks), add separate selector entries.
-//   • MAX_AMOUNT_PER_TRANSFER is denominated in the token's base units.
-//     Different tokens have different decimals (USDC = 6, WETH = 18).
-//     Set one permission per token if amounts differ across tokens.
-// ─────────────────────────────────────────────────────────────────────────────
-
-import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
-
-contract BoundedTransfer_ERC20_Ethereum is IPermission {
-    bytes32 private constant DISCRIMINATOR = keccak256("BoundedTransfer_ERC20_Ethereum");
-
-    mapping(address => bool) public isAllowedToken;
-    mapping(address => bool) public isAllowedRecipient;
-    uint256 public immutable MAX_AMOUNT_PER_TRANSFER;
-
-    // transfer(address,uint256)
-    bytes4 private constant SEL_TRANSFER = 0xa9059cbb;
-
-    /// @param allowedTokens        ERC-20 contracts the agent may transfer from
-    /// @param allowedRecipients    Addresses the agent may send to
-    /// @param maxAmountPerTransfer Per-call amount cap (in token base units)
-    constructor(
-        address[] memory allowedTokens,
-        address[] memory allowedRecipients,
-        uint256 maxAmountPerTransfer
-    ) {
-        MAX_AMOUNT_PER_TRANSFER = maxAmountPerTransfer;
-        for (uint256 i = 0; i < allowedTokens.length; i++) {
-            isAllowedToken[allowedTokens[i]] = true;
-        }
-        for (uint256 i = 0; i < allowedRecipients.length; i++) {
-            isAllowedRecipient[allowedRecipients[i]] = true;
-        }
-    }
-
-    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
-        if (!isAllowedToken[ctx.target])      return false;
-        if (ctx.selector != SEL_TRANSFER)     return false;
-        if (txData.length < 4 + 2 * 32)      return false;
-
-        (address to, uint256 amount) = abi.decode(txData[4:], (address, uint256));
-
-        if (!isAllowedRecipient[to])                return false;
-        if (amount > MAX_AMOUNT_PER_TRANSFER)       return false;
-
-        return true;
-    }
-
-    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
-}
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : ERC-20
+// Version  : Standard ERC-20 (version-agnostic)
+// Chain    : Ethereum mainnet (works on any EVM — the most general example)
+//
+// 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
+//
+// 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
+//
+// VERIFY BEFORE USE:
+//   • Selector 0xa9059cbb = transfer(address,uint256) — universally standard.
+//   • ALLOWED_TOKENS prevents the agent from transferring tokens not in the set.
+//     If a protocol uses non-standard transfer methods (e.g. transferFrom or
+//     proprietary hooks), add separate selector entries.
+//   • MAX_AMOUNT_PER_TRANSFER is denominated in the token's base units.
+//     Different tokens have different decimals (USDC = 6, WETH = 18).
+//     Set one permission per token if amounts differ across tokens.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedTransfer_ERC20_Ethereum is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedTransfer_ERC20_Ethereum");
+
+    mapping(address => bool) public isAllowedToken;
+    mapping(address => bool) public isAllowedRecipient;
+    uint256 public immutable MAX_AMOUNT_PER_TRANSFER;
+
+    // transfer(address,uint256)
+    bytes4 private constant SEL_TRANSFER = 0xa9059cbb;
+
+    /// @param allowedTokens        ERC-20 contracts the agent may transfer from
+    /// @param allowedRecipients    Addresses the agent may send to
+    /// @param maxAmountPerTransfer Per-call amount cap (in token base units)
+    constructor(
+        address[] memory allowedTokens,
+        address[] memory allowedRecipients,
+        uint256 maxAmountPerTransfer
+    ) {
+        MAX_AMOUNT_PER_TRANSFER = maxAmountPerTransfer;
+        for (uint256 i = 0; i < allowedTokens.length; i++) {
+            isAllowedToken[allowedTokens[i]] = true;
+        }
+        for (uint256 i = 0; i < allowedRecipients.length; i++) {
+            isAllowedRecipient[allowedRecipients[i]] = true;
+        }
+    }
+
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+        if (!isAllowedToken[ctx.target])      return false;
+        if (ctx.selector != SEL_TRANSFER)     return false;
+        if (txData.length < 4 + 2 * 32)      return false;
+
+        (address to, uint256 amount) = abi.decode(txData[4:], (address, uint256));
+
+        if (!isAllowedRecipient[to])                return false;
+        if (amount > MAX_AMOUNT_PER_TRANSFER)       return false;
+
+        return true;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}

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

@@ -1,52 +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
-
-| 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 |
-| `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 |
-| `BoundedBet_Limitless_Base.sol` | Limitless Prediction | CTF Exchange | Base | UNVERIFIED ABI — see header |
-
-## 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>
-```
+# 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

@@ -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/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 '[...]'

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

@@ -1,18 +1,18 @@
-// SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
-
-struct Context {
-    address account;
-    address manager;
-    address submitter;
-    address target;
-    bytes4 selector;
-    uint256 value;
-    uint256 blockTimestamp;
-    uint256 blockNumber;
-}
-
-interface IPermission {
-    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool);
-    function discriminator() external view returns (bytes32);
-}
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+struct Context {
+    address account;
+    address manager;
+    address submitter;
+    address target;
+    bytes4 selector;
+    uint256 value;
+    uint256 blockTimestamp;
+    uint256 blockNumber;
+}
+
+interface IPermission {
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool);
+    function discriminator() external view returns (bytes32);
+}