@dev.sail.money/sailor 0.0.2-12

package/examples/permissions/BoundedBorrow_AaveV3_Arbitrum.sol

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : Aave V3
+// Version  : Pool (proxy) — fully on-chain, oracle-based liquidation
+// Chain    : Arbitrum mainnet
+// Target   : Aave V3 Pool  0x794a61358D6845594F94dc1DB02A252b5b4814aD
+//
+// ENFORCED ON-CHAIN (via kernel evaluate() on every dispatch):
+//   borrow(address asset, uint256 amount, uint256 interestRateMode,
+//          uint16 referralCode, address onBehalfOf)
+//   • target must be AAVE_POOL
+//   • asset must be in ALLOWED_ASSETS
+//   • amount ≤ MAX_BORROW_AMOUNT
+//   • onBehalfOf must equal ctx.account (the SMA — agent cannot borrow on behalf of others)
+//   • interestRateMode must be in ALLOWED_RATE_MODES
+//     (1 = stable [deprecated in V3.1], 2 = variable; restrict to [2] for V3.1+)
+//
+// NOT ENFORCED (agent code — can change without a new contract):
+//   • Health factor management — the kernel cannot check post-borrow health factor
+//   • referralCode (informational only, does not affect fund safety)
+//   • Repayment timing — agent decides when to repay
+//   • Collateral composition — managed by prior deposit permissions
+//
+// VERIFY BEFORE USE:
+//   • Confirm Aave V3 Pool address on Arbitrum (0x794a... — verify on Arbiscan).
+//   • Selector 0xa415bcad = borrow(address,uint256,uint256,uint16,address).
+//     Compute: keccak256("borrow(address,uint256,uint256,uint16,address)")[0:4]
+//     and confirm it matches before deploying.
+//   • Aave V3.1 deprecated stable-rate borrowing (interestRateMode=1).
+//     If using V3.1+, set allowedRateModes = [2] (variable only).
+//   • MAX_BORROW_AMOUNT is in the asset's base units (e.g. 6 decimals for USDC).
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedBorrow_AaveV3_Arbitrum is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedBorrow_AaveV3_Arbitrum");
+
+    address public immutable AAVE_POOL;
+    mapping(address => bool) public isAllowedAsset;
+    uint256 public immutable MAX_BORROW_AMOUNT;
+    mapping(uint256 => bool) public isAllowedRateMode;
+
+    // borrow(address,uint256,uint256,uint16,address)
+    // VERIFY: keccak256("borrow(address,uint256,uint256,uint16,address)")[0:4] == 0xa415bcad
+    bytes4 private constant SEL_BORROW = 0xa415bcad;
+
+    /// @param aavePool         Aave V3 Pool proxy address
+    /// @param allowedAssets    Assets the agent may borrow
+    /// @param maxBorrowAmount  Per-call borrow cap in asset base units
+    /// @param allowedRateModes Interest rate modes allowed (2 = variable; use [2] for V3.1+)
+    constructor(
+        address aavePool,
+        address[] memory allowedAssets,
+        uint256 maxBorrowAmount,
+        uint256[] memory allowedRateModes
+    ) {
+        AAVE_POOL        = aavePool;
+        MAX_BORROW_AMOUNT = maxBorrowAmount;
+        for (uint256 i = 0; i < allowedAssets.length; i++) {
+            isAllowedAsset[allowedAssets[i]] = true;
+        }
+        for (uint256 i = 0; i < allowedRateModes.length; i++) {
+            isAllowedRateMode[allowedRateModes[i]] = true;
+        }
+    }
+
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+        if (ctx.target != AAVE_POOL)      return false;
+        if (ctx.selector != SEL_BORROW)   return false;
+        // borrow(address asset, uint256 amount, uint256 interestRateMode, uint16 referralCode, address onBehalfOf)
+        // = 5 ABI-encoded 32-byte slots after the 4-byte selector
+        if (txData.length < 4 + 5 * 32)  return false;
+
+        (
+            address asset,
+            uint256 amount,
+            uint256 interestRateMode,
+            /* uint16 referralCode — not bounded */,
+            address onBehalfOf
+        ) = abi.decode(txData[4:], (address, uint256, uint256, uint16, address));
+
+        if (!isAllowedAsset[asset])           return false;
+        if (amount > MAX_BORROW_AMOUNT)       return false;
+        if (onBehalfOf != ctx.account)        return false;  // agent borrows only for the SMA
+        if (!isAllowedRateMode[interestRateMode]) return false;
+
+        return true;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}

package/examples/permissions/BoundedPerp_GMXv2_Arbitrum.sol

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : GMX V2 (gmx-synthetics)
+// Version  : ExchangeRouter / OrderHandler — fully on-chain oracle execution
+//            NOT Hyperliquid (off-chain order book — permissions cannot bound orders)
+// Chain    : Arbitrum mainnet
+// Target   : ExchangeRouter  0x7c68c7866a64fa2160f78eeae12217ffbf871fa8
+//            (verify on Arbiscan — GMX may redeploy; check their official docs)
+//
+// ENFORCED ON-CHAIN (via kernel evaluate() on every dispatch):
+//   createOrder(CreateOrderParams params)  selector 0x414577b7
+//   • target must be EXCHANGE_ROUTER
+//   • market must be in ALLOWED_MARKETS
+//   • initialCollateralDeltaAmount ≤ MAX_COLLATERAL_AMOUNT
+//   • sizeDeltaUsd ≤ MAX_SIZE_DELTA_USD
+//   • isLong must be in ALLOWED_DIRECTIONS (true=long, false=short, or both)
+//
+// NOT ENFORCED — documented limitations:
+//   • Leverage ratio: sizeDeltaUsd vs collateralDeltaAmount are bounded separately
+//     but their ratio (effective leverage) is not directly enforced here because
+//     it depends on collateral price. Add a price-oracle leverage check if needed.
+//   • acceptablePrice / triggerPrice: not bounded — agent controls entry price.
+//     Add bounds if the strategy requires a price range check.
+//   • decreasePositionSwapType, shouldUnwrapNativeToken, autoCancel: not bounded.
+//   • swapPath (inside CreateOrderParamAddresses): not bounded — any intermediate
+//     tokens in the swap path are allowed. Restrict if needed.
+//   • receiver address: not bounded — set to ctx.account in your agent.
+//
+// STRUCT LAYOUT NOTE:
+//   This contract defines CreateOrderParams inline. It must match EXACTLY the
+//   struct layout in the deployed ExchangeRouter's IBaseOrderUtils. If GMX
+//   updates the struct (e.g. adds a field), this permission will misparse calldata
+//   and return false (fail closed — safe but non-functional).
+//   VERIFY against BaseOrderUtils.sol at:
+//   https://github.com/gmx-io/gmx-synthetics/blob/main/contracts/order/BaseOrderUtils.sol
+//
+// VERIFY BEFORE USE:
+//   • Confirm ExchangeRouter address on Arbitrum (0x7c68... — verify on Arbiscan).
+//   • Selector 0x414577b7 = createOrder(IBaseOrderUtils.CreateOrderParams).
+//     Verify against the deployed contract's ABI tab on Arbiscan.
+//   • sizeDeltaUsd is in USD with 30 decimals (GMX V2 standard). E.g. $1000 = 1e33.
+//   • initialCollateralDeltaAmount is in collateral token base units.
+//   • Test with real calldata samples from GMX V2 on Arbitrum testnet before mainnet.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedPerp_GMXv2_Arbitrum is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedPerp_GMXv2_Arbitrum");
+
+    address public immutable EXCHANGE_ROUTER;
+    mapping(address => bool) public isAllowedMarket;
+    uint256 public immutable MAX_COLLATERAL_AMOUNT;
+    /// @dev sizeDeltaUsd uses GMX V2's 30-decimal USD representation. 1 USD = 1e30.
+    uint256 public immutable MAX_SIZE_DELTA_USD;
+    bool public immutable ALLOW_LONG;
+    bool public immutable ALLOW_SHORT;
+
+    // createOrder(IBaseOrderUtils.CreateOrderParams)
+    // VERIFY: keccak256("createOrder(...)")[0:4] == 0x414577b7 on deployed ExchangeRouter
+    bytes4 private constant SEL_CREATE_ORDER = 0x414577b7;
+
+    // ── Inline struct definitions — MUST match IBaseOrderUtils.CreateOrderParams ──
+    // Verify against:
+    // https://github.com/gmx-io/gmx-synthetics/blob/main/contracts/order/BaseOrderUtils.sol
+
+    struct CreateOrderParamAddresses {
+        address receiver;
+        address callbackContract;
+        address uiFeeReceiver;
+        address market;
+        address initialCollateralToken;
+        address[] swapPath;         // dynamic — makes this struct dynamic
+    }
+
+    struct CreateOrderParamNumbers {
+        uint256 sizeDeltaUsd;
+        uint256 initialCollateralDeltaAmount;
+        uint256 triggerPrice;
+        uint256 acceptablePrice;
+        uint256 executionFee;
+        uint256 callbackGasLimit;
+        uint256 minOutputAmount;
+        uint256 validFromTime;
+    }
+
+    struct CreateOrderParams {
+        CreateOrderParamAddresses addresses;
+        CreateOrderParamNumbers   numbers;
+        uint8   orderType;
+        uint8   decreasePositionSwapType;
+        bool    isLong;
+        bool    shouldUnwrapNativeToken;
+        bool    autoCancel;
+        bytes32 referralCode;
+    }
+
+    /// @param exchangeRouter       GMX V2 ExchangeRouter address
+    /// @param allowedMarkets       GMX V2 market addresses the agent may trade
+    /// @param maxCollateralAmount  Per-order collateral cap in collateral token base units
+    /// @param maxSizeDeltaUsd      Per-order position size cap in GMX USD (30 decimals)
+    /// @param allowLong            Whether long orders are permitted
+    /// @param allowShort           Whether short orders are permitted
+    constructor(
+        address exchangeRouter,
+        address[] memory allowedMarkets,
+        uint256 maxCollateralAmount,
+        uint256 maxSizeDeltaUsd,
+        bool allowLong,
+        bool allowShort
+    ) {
+        EXCHANGE_ROUTER      = exchangeRouter;
+        MAX_COLLATERAL_AMOUNT = maxCollateralAmount;
+        MAX_SIZE_DELTA_USD   = maxSizeDeltaUsd;
+        ALLOW_LONG           = allowLong;
+        ALLOW_SHORT          = allowShort;
+        for (uint256 i = 0; i < allowedMarkets.length; i++) {
+            isAllowedMarket[allowedMarkets[i]] = true;
+        }
+    }
+
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+        if (ctx.target != EXCHANGE_ROUTER)      return false;
+        if (ctx.selector != SEL_CREATE_ORDER)   return false;
+        if (txData.length < 4)                  return false;
+
+        // abi.decode handles the nested dynamic struct (address[] swapPath) correctly.
+        // A malformed calldata or struct layout mismatch causes a revert → false (fail closed).
+        CreateOrderParams memory p = abi.decode(txData[4:], (CreateOrderParams));
+
+        if (!isAllowedMarket[p.addresses.market])                 return false;
+        if (p.numbers.initialCollateralDeltaAmount > MAX_COLLATERAL_AMOUNT) return false;
+        if (p.numbers.sizeDeltaUsd > MAX_SIZE_DELTA_USD)          return false;
+        if (p.isLong  && !ALLOW_LONG)                             return false;
+        if (!p.isLong && !ALLOW_SHORT)                            return false;
+
+        return true;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}

package/examples/permissions/BoundedSwap_UniswapV3_Base.sol

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : Uniswap V3
+// Version  : SwapRouter02 (NOT the older SwapRouter — different selectors)
+// Chain    : Base mainnet
+// Target   : SwapRouter02  0x2626664c2603336E57B271c5C0b26F421741e481
+//
+// ENFORCED ON-CHAIN (via kernel evaluate() on every dispatch):
+//   exactInputSingle path (selector 0x04e45aaf):
+//     • target must be SWAP_ROUTER
+//     • tokenIn  must equal FIXED_TOKEN_IN
+//     • tokenOut must be in ALLOWED_TOKENS_OUT
+//     • amountIn ≤ MAX_AMOUNT_IN
+//     • amountOutMinimum ≥ amountIn × MIN_BPS / 10 000  (slippage floor)
+//   approve path (selector 0x095ea7b3):
+//     • target must be FIXED_TOKEN_IN (the ERC-20 being approved)
+//     • spender must be SWAP_ROUTER
+//     • amount  ≤ MAX_AMOUNT_IN
+//
+// NOT ENFORCED (agent code — can change without a new contract):
+//   • fee tier, sqrtPriceLimitX96, recipient address
+//   • swap frequency / cadence
+//
+// VERIFY BEFORE USE:
+//   • Confirm SwapRouter02 address on your chain (Base default shown above).
+//   • Selector 0x04e45aaf = exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))
+//     on SwapRouter02. The older SwapRouter uses a different selector (0x414577b7).
+//   • Confirm that amountOutMinimum slippage floor fits your price-impact expectations for the
+//     chosen pool. Large amountIn values may trigger price impact beyond MIN_BPS.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedSwap_UniswapV3_Base is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedSwap_UniswapV3_Base");
+
+    address public immutable SWAP_ROUTER;
+    address public immutable FIXED_TOKEN_IN;
+    mapping(address => bool) public isAllowedTokenOut;
+    uint256 public immutable MAX_AMOUNT_IN;
+    /// @dev Slippage floor in basis points. 9 900 = allow at most 1% slippage.
+    uint256 public immutable MIN_BPS;
+
+    bytes4 private constant SEL_EXACT_INPUT_SINGLE = 0x04e45aaf;
+    bytes4 private constant SEL_APPROVE            = 0x095ea7b3;
+
+    struct ExactInputSingleParams {
+        address tokenIn;
+        address tokenOut;
+        uint24  fee;
+        address recipient;
+        uint256 amountIn;
+        uint256 amountOutMinimum;
+        uint160 sqrtPriceLimitX96;
+    }
+
+    /// @param swapRouter      SwapRouter02 address (0x2626... on Base)
+    /// @param fixedTokenIn    The one token the agent is allowed to sell
+    /// @param allowedTokensOut  Tokens the agent may receive
+    /// @param maxAmountIn     Per-call spend cap in fixedTokenIn base units
+    /// @param minBps          Minimum amountOutMinimum as fraction of amountIn ×10 000
+    ///                        e.g. 9900 → require amountOutMinimum ≥ 99% of amountIn
+    ///                        (denominated in fixedTokenIn units, not USD — set per your pair)
+    constructor(
+        address swapRouter,
+        address fixedTokenIn,
+        address[] memory allowedTokensOut,
+        uint256 maxAmountIn,
+        uint256 minBps
+    ) {
+        require(minBps <= 10_000, "minBps > 10000");
+        SWAP_ROUTER    = swapRouter;
+        FIXED_TOKEN_IN = fixedTokenIn;
+        MAX_AMOUNT_IN  = maxAmountIn;
+        MIN_BPS        = minBps;
+        for (uint256 i = 0; i < allowedTokensOut.length; i++) {
+            isAllowedTokenOut[allowedTokensOut[i]] = true;
+        }
+    }
+
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+        if (txData.length < 4) return false;
+
+        // exactInputSingle: agent swaps FIXED_TOKEN_IN for an allowed output token
+        if (ctx.target == SWAP_ROUTER && ctx.selector == SEL_EXACT_INPUT_SINGLE) {
+            if (txData.length < 4 + 7 * 32) return false;
+            ExactInputSingleParams memory p = abi.decode(txData[4:], (ExactInputSingleParams));
+            if (p.tokenIn != FIXED_TOKEN_IN)         return false;
+            if (!isAllowedTokenOut[p.tokenOut])      return false;
+            if (p.amountIn > MAX_AMOUNT_IN)          return false;
+            // Slippage floor: require amountOutMinimum ≥ amountIn * MIN_BPS / 10 000.
+            // This is not a USD check — it's a ratio check in tokenIn units.
+            // For a USDC→WETH swap, set MIN_BPS conservatively (e.g. 9 900 for 1% slippage).
+            if (p.amountOutMinimum < (p.amountIn * MIN_BPS) / 10_000) return false;
+            return true;
+        }
+
+        // approve: agent approves the router to spend FIXED_TOKEN_IN
+        if (ctx.target == FIXED_TOKEN_IN && ctx.selector == SEL_APPROVE) {
+            if (txData.length < 4 + 2 * 32) return false;
+            (address spender, uint256 amount) = abi.decode(txData[4:], (address, uint256));
+            if (spender != SWAP_ROUTER)  return false;
+            if (amount > MAX_AMOUNT_IN)  return false;
+            return true;
+        }
+
+        return false;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}

package/examples/permissions/BoundedSwap_UniswapV4_Unichain.sol

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : Uniswap V4
+// Version  : Universal Router + PoolManager (V4 singleton)
+//            NOTE: V4 is NOT the same as V3. Calldata encoding is completely
+//            different — do NOT adapt a V3 permission for V4.
+// Chain    : Unichain mainnet
+// 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):
+//     • 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)
+//     • V4 action inside must be SWAP_EXACT_IN_SINGLE (0x00)
+//     • 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
+//
+// NOT ENFORCED — documented limitations:
+//   • 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.)
+//   • fee tier and tickSpacing within the PoolKey are not constrained here
+//     (add pool-key checks if you want to restrict to a specific pool)
+//   • The ALL_CURRENCY_PAIR constant (FIXED_CURRENCY_IN, allowedCurrenciesOut) does
+//     not constrain which pool is used when multiple pools share the same currency pair
+//
+// VERIFY BEFORE USE:
+//   • Confirm Universal Router address on Unichain (shown above; verify on Uniscan).
+//   • V4_SWAP command byte = 0x10, SWAP_EXACT_IN_SINGLE action = 0x00 — verify
+//     against deployed UniversalRouter and V4Router on Unichain if contract is updated.
+//   • PoolKey struct layout (currency0, currency1, fee, tickSpacing, hooks) must
+//     match the deployed PoolManager on Unichain. If layout changes, update struct.
+//   • hookData is not bounded. Only use with unhookyed pools or audited, bounded hooks.
+//   • Calldata revert = false (kernel treats revert as denial) — malformed inputs
+//     are safely rejected, but verify with actual calldata samples before deployment.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedSwap_UniswapV4_Unichain is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedSwap_UniswapV4_Unichain");
+
+    address public immutable UNIVERSAL_ROUTER;
+    address public immutable FIXED_CURRENCY_IN;
+    mapping(address => bool) public isAllowedCurrencyOut;
+    uint256 public immutable MAX_AMOUNT_IN;
+    uint256 public immutable MIN_BPS;
+
+    // execute(bytes,bytes[],uint256) — with deadline
+    bytes4 private constant SEL_EXECUTE_DEADLINE = 0x3593564c;
+    // execute(bytes,bytes[])          — without deadline
+    bytes4 private constant SEL_EXECUTE           = 0x24856bc3;
+    // Universal Router command byte for V4_SWAP
+    uint8 private constant CMD_V4_SWAP = 0x10;
+    // Bit mask to strip the "allow failure" MSB from a command byte
+    uint8 private constant CMD_MASK = 0x3f;
+    // V4Router action: SWAP_EXACT_IN_SINGLE
+    uint8 private constant ACT_SWAP_EXACT_IN_SINGLE = 0x00;
+
+    // PoolKey layout must match the deployed V4 PoolManager on Unichain
+    struct PoolKey {
+        address currency0;  // Currency — address type in V4
+        address currency1;
+        uint24  fee;
+        int24   tickSpacing;
+        address hooks;      // IHooks — address(0) for unhookyed pools
+    }
+
+    struct ExactInputSingleParams {
+        PoolKey poolKey;
+        bool    zeroForOne;
+        uint128 amountIn;
+        uint128 amountOutMinimum;
+        bytes   hookData;   // not inspected — see limitations header
+    }
+
+    constructor(
+        address universalRouter,
+        address fixedCurrencyIn,
+        address[] memory allowedCurrenciesOut,
+        uint256 maxAmountIn,
+        uint256 minBps
+    ) {
+        require(minBps <= 10_000, "minBps > 10000");
+        UNIVERSAL_ROUTER  = universalRouter;
+        FIXED_CURRENCY_IN = fixedCurrencyIn;
+        MAX_AMOUNT_IN     = maxAmountIn;
+        MIN_BPS           = minBps;
+        for (uint256 i = 0; i < allowedCurrenciesOut.length; i++) {
+            isAllowedCurrenciesOut[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;
+        if (txData.length < 4) return false;
+
+        // Decode the execute call. Both overloads start with (bytes commands, bytes[] inputs).
+        // abi.decode ignores trailing fields, so decoding as (bytes, bytes[]) works for both.
+        (bytes memory commands, bytes[] memory inputs) = abi.decode(txData[4:], (bytes, bytes[]));
+
+        // Enforce: exactly one command, and it must be V4_SWAP
+        if (commands.length != 1)                              return false;
+        if ((uint8(commands[0]) & CMD_MASK) != CMD_V4_SWAP)   return false;
+        if (inputs.length != 1)                                return false;
+
+        // Decode the V4 router call (actions + per-action params)
+        (bytes memory v4Actions, bytes[] memory v4Params) =
+            abi.decode(inputs[0], (bytes, bytes[]));
+
+        // Enforce: exactly one V4 action, and it must be SWAP_EXACT_IN_SINGLE
+        if (v4Actions.length != 1)                                                    return false;
+        if (uint8(v4Actions[0]) != ACT_SWAP_EXACT_IN_SINGLE)                         return false;
+        if (v4Params.length != 1)                                                     return false;
+
+        // Decode ExactInputSingleParams from the action param.
+        // hookData is a dynamic bytes field — revert here means false (fail closed).
+        ExactInputSingleParams memory p = abi.decode(v4Params[0], (ExactInputSingleParams));
+
+        // Derive tokenIn and tokenOut from the PoolKey and zeroForOne flag.
+        // In V4, currency0 < currency1 (sorted by address). zeroForOne = true means
+        // trading currency0 for currency1.
+        address tokenIn  = p.zeroForOne ? p.poolKey.currency0 : p.poolKey.currency1;
+        address tokenOut = p.zeroForOne ? p.poolKey.currency1 : p.poolKey.currency0;
+
+        if (tokenIn != FIXED_CURRENCY_IN)            return false;
+        if (!isAllowedCurrenciesOut[tokenOut])       return false;
+        if (p.amountIn > MAX_AMOUNT_IN)              return false;
+        if (p.amountOutMinimum < (uint256(p.amountIn) * MIN_BPS) / 10_000) return false;
+
+        return true;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}

package/examples/permissions/BoundedTransfer_ERC20_Ethereum.sol

@@ -0,0 +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; }
+}

package/examples/permissions/README.md

@@ -0,0 +1,52 @@
+# 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>
+```

package/examples/permissions/foundry.toml

@@ -0,0 +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 '[...]'

package/examples/permissions/interfaces/IPermission.sol

@@ -0,0 +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);
+}