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

package/examples/permissions/BoundedBorrow_AaveV3_Arbitrum.sol

@@ -1,94 +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; }
-}
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : Aave V3
+// Version  : Pool (proxy) — fully on-chain, oracle-based liquidation
+// Chain    : Arbitrum mainnet (42161)
+// Target   : Aave V3 Pool  0x794a61358D6845594F94dc1DB02A252b5b4814aD  (verified on Arbiscan)
+//
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked):
+//   borrow(address asset,uint256 amount,uint256 interestRateMode,uint16 referralCode,address onBehalfOf)
+//   selector 0xa415bcad
+//     • 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+)
+//
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this 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/supply 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

@@ -1,143 +1,154 @@
-// 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; }
-}
+// 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 (42161)
+//
+// ⚠ REFERENCE PATTERN — VERIFY SELECTOR, STRUCT, AND ROUTER AGAINST THE LIVE GMX ABI ⚠
+//   GMX runs MULTIPLE versioned ExchangeRouter deployments on Arbitrum (e.g.
+//   0x7c68c7866a64fa2160f78eeae12217ffbf871fa8, 0x602b805EedddBbD9ddff44A7dcBD46cb07849685,
+//   and others) and HAS EVOLVED the CreateOrderParams struct over time (it added
+//   `cancellationReceiver` to the addresses tuple and a trailing `dataList` bytes32[]).
+//   The struct + selector below are taken from the CURRENT canonical source
+//   (gmx-io/gmx-synthetics, contracts/order/IBaseOrderUtils.sol, main branch) and are
+//   mutually consistent — but the specific router YOU target may run an OLDER struct
+//   with a DIFFERENT selector. Selector mismatch ⇒ evaluate() returns false for every
+//   legitimate order (fail-closed: safe, but the permission silently does nothing useful).
+//   Before deploying you MUST:
+//     1. Pick the exact ExchangeRouter your agent will call and read its verified ABI.
+//     2. Confirm its createOrder selector == SEL_CREATE_ORDER below (recompute with
+//        `cast sig "createOrder(<exact tuple>)"`); if not, update SEL_CREATE_ORDER and
+//        the inline struct to match that router's version.
+//     3. Set EXCHANGE_ROUTER (constructor arg) to that same router address.
+//
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked):
+//   createOrder(IBaseOrderUtils.CreateOrderParams)  selector 0x212234c3 (current canonical struct)
+//     • target must be EXCHANGE_ROUTER
+//     • market must be in ALLOWED_MARKETS
+//     • initialCollateralDeltaAmount ≤ MAX_COLLATERAL_AMOUNT
+//     • sizeDeltaUsd ≤ MAX_SIZE_DELTA_USD
+//     • isLong must be allowed (ALLOW_LONG / ALLOW_SHORT)
+//
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
+//   • Leverage ratio: sizeDeltaUsd vs collateralDeltaAmount are bounded separately
+//     but their ratio (effective leverage) is not enforced — it depends on collateral price.
+//   • acceptablePrice / triggerPrice: not bounded — agent controls entry price.
+//   • decreasePositionSwapType, shouldUnwrapNativeToken, autoCancel: not bounded.
+//   • swapPath (inside the addresses tuple): not bounded — any intermediate tokens allowed.
+//   • receiver / cancellationReceiver: not bounded — set to ctx.account in your agent.
+//
+// VERIFY BEFORE USE:
+//   • SEL_CREATE_ORDER = 0x212234c3 was computed (via `cast sig`) from the CURRENT canonical
+//     tuple. Older routers differ — see the loud banner above. ALWAYS reconfirm.
+//   • 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 your chosen GMX router before mainnet.
+//   • Source: https://github.com/gmx-io/gmx-synthetics/blob/main/contracts/order/IBaseOrderUtils.sol
+// ─────────────────────────────────────────────────────────────────────────────
+
+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)
+    // Computed via `cast sig` (split across lines for readability — paste as one string in the shell):
+    //   "createOrder((address,address,address,address,address,address,address[]),"
+    //               "(uint256,uint256,uint256,uint256,uint256,uint256,uint256,uint256),"
+    //               "uint8,uint8,bool,bool,bool,bytes32,bytes32[])"
+    //   == 0x212234c3
+    // ⚠ Older GMX routers use an earlier struct (no cancellationReceiver / no dataList) and a
+    //   DIFFERENT selector. Reconfirm against your chosen router's ABI — see header banner.
+    bytes4 private constant SEL_CREATE_ORDER = 0x212234c3;
+
+    // ── Inline struct definitions — match the CURRENT canonical IBaseOrderUtils.CreateOrderParams ──
+    // Source: https://github.com/gmx-io/gmx-synthetics/blob/main/contracts/order/IBaseOrderUtils.sol
+
+    struct CreateOrderParamsAddresses {
+        address receiver;
+        address cancellationReceiver;  // added in a later GMX version — present in current struct
+        address callbackContract;
+        address uiFeeReceiver;
+        address market;
+        address initialCollateralToken;
+        address[] swapPath;            // dynamic — makes this struct dynamic
+    }
+
+    struct CreateOrderParamsNumbers {
+        uint256 sizeDeltaUsd;
+        uint256 initialCollateralDeltaAmount;
+        uint256 triggerPrice;
+        uint256 acceptablePrice;
+        uint256 executionFee;
+        uint256 callbackGasLimit;
+        uint256 minOutputAmount;
+        uint256 validFromTime;
+    }
+
+    struct CreateOrderParams {
+        CreateOrderParamsAddresses addresses;
+        CreateOrderParamsNumbers   numbers;
+        uint8   orderType;
+        uint8   decreasePositionSwapType;
+        bool    isLong;
+        bool    shouldUnwrapNativeToken;
+        bool    autoCancel;
+        bytes32 referralCode;
+        bytes32[] dataList;            // added in a later GMX version — present in current struct
+    }
+
+    /// @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/BoundedStake_Venice_Base.sol

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : Venice (VVV) staking
+// Version  : sVVV staking contract (proxy) — fully on-chain
+// Chain    : Base mainnet (8453)
+// Target   : Staking proxy  0x321b7ff75154472B18EDb199033fF4D116F340Ff  ("Staked Venice Token")
+//            (impl 0xe37a7920dbc11253ac6d031c29f592f71b348dca — proxy is the stable target)
+//            Staked asset: VVV  0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf
+//
+// ⚠ SELECTOR NOTE — the function is stake(address,uint256), NOT stake(uint256).
+//   Verified against the live contract (bytecode + 4byte registry): the staking entrypoint is
+//   stake(address recipient, uint256 amount) = 0xadc9772e. The single-arg stake(uint256)
+//   = 0xa694fc3a is ABSENT. Gating the wrong selector silently rejects every real stake
+//   (fail-closed but non-functional). ALWAYS confirm the selector against the contract you target.
+//
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked):
+//   stake(address recipient,uint256 amount)  selector 0xadc9772e
+//     • target must be STAKING_CONTRACT
+//     • amount ≤ MAX_STAKE_AMOUNT
+//     • recipient must equal ctx.account (the SMA — the staked position cannot be assigned
+//       to another address; verified empirically: this arg is the position beneficiary)
+//   claim()  selector 0x4e71d92d
+//     • target must be STAKING_CONTRACT
+//     • takes NO recipient argument — rewards always accrue to the caller (the SMA when the
+//       kernel dispatches), so "claim-rewards-to-SMA-only" holds structurally
+//
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
+//   • Stake timing / cadence and how often rewards are claimed
+//   • Unstaking: this permission does NOT allow initiateUnstake(uint256) (0xae5ac921) — add it
+//     with its own bounds if the agent should manage exits; left out to keep this single-purpose.
+//   • Staked ASSET: enforced TRANSITIVELY via STAKING_CONTRACT (the contract accepts one fixed
+//     token, VVV). The stake calldata carries no token field, so the asset is pinned by the target.
+//
+// VERIFY BEFORE USE:
+//   • Confirm STAKING_CONTRACT and that its stake selector is 0xadc9772e on the contract you target.
+//   • Confirm the stake address arg is the position recipient (not, e.g., a token address) on your
+//     contract — on Venice it is the recipient (verified by staking to a third party on a fork).
+//   • MAX_STAKE_AMOUNT is in VVV base units (18 decimals).
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedStake_Venice_Base is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedStake_Venice_Base");
+
+    address public immutable STAKING_CONTRACT;
+    uint256 public immutable MAX_STAKE_AMOUNT;
+
+    // Verified against the live Venice staking contract (bytecode + 4byte registry):
+    bytes4 private constant SEL_STAKE = 0xadc9772e; // stake(address recipient,uint256 amount)
+    bytes4 private constant SEL_CLAIM = 0x4e71d92d; // claim()
+
+    /// @param stakingContract  Venice staking contract (the proxy address)
+    /// @param maxStakeAmount   Per-stake cap in VVV base units (18 decimals; must be > 0)
+    constructor(address stakingContract, uint256 maxStakeAmount) {
+        require(stakingContract != address(0), "zero staking contract");
+        require(maxStakeAmount > 0,            "zero stake cap");
+        STAKING_CONTRACT = stakingContract;
+        MAX_STAKE_AMOUNT = maxStakeAmount;
+    }
+
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+        if (ctx.target != STAKING_CONTRACT) return false;
+
+        // stake(address recipient, uint256 amount)
+        if (ctx.selector == SEL_STAKE) {
+            if (txData.length < 4 + 2 * 32) return false;
+            (address recipient, uint256 amount) = abi.decode(txData[4:], (address, uint256));
+            if (amount > MAX_STAKE_AMOUNT) return false;
+            if (recipient != ctx.account)  return false; // stake only to the SMA's own position
+            return true;
+        }
+
+        // claim() — no args; rewards go to the caller (the SMA). No recipient to bound.
+        if (ctx.selector == SEL_CLAIM) {
+            return true;
+        }
+
+        return false;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}