@dev.sail.money/sailor 0.0.2-20 → 0.0.2-21

package/examples/permissions/BoundedApproveAndCallBatch.sol

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : Sail batch dispatch (IBatchPermission) — protocol-agnostic
+// Version  : Single-tenant, constructor-configured (mirrors the multi-tenant
+//            SharedApproveAndCallBatchPermission shape from SailProtocol)
+// Chain    : Any EVM with a SELECTIVE kernel (Base, Arbitrum, Unichain, Base Sepolia)
+//
+// WHAT THIS TEACHES — the atomic approve → call → reset pattern.
+//   A bare ERC-20 approve is dangerous: it leaves a standing allowance an attacker can drain.
+//   The safe shape is to approve, consume the allowance in the SAME transaction, then reset it
+//   to zero — all-or-nothing. No single-call IPermission can enforce "the reset must be the
+//   final call", because per-call evaluation never sees the other calls. A batch permission
+//   sees the WHOLE sequence at once, so it can.
+//
+//   Gated via the kernel's dispatchBatch (NOT dispatch). This contract's single-call evaluate()
+//   deliberately returns false — it is batch-only. The manager names this permission in the
+//   batch signature; only it is consulted (selective model).
+//
+// ENFORCES ON-CHAIN (kernel calls evaluateBatch() via staticcall; false/revert ⇒ batch blocked):
+//   The batch MUST be exactly these 3 calls, in this order, each with value == 0:
+//     calls[0] = approve(spender,amount)  selector 0x095ea7b3  on an allowlisted token
+//                • token (calls[0].target) must be in ALLOWED_TOKENS (cap > 0)
+//                • spender must be in ALLOWED_SPENDERS
+//                • 0 < amount ≤ maxApprovalAmount[token]
+//     calls[1] = <consuming call>         on an allowlisted (target, selector)
+//                • target must be in ALLOWED_CONSUMING_TARGETS
+//                • selector must be in ALLOWED_CONSUMING_SELECTORS
+//                • if REQUIRE_AMOUNT_MATCH: c1.data[4:36] (the first ABI-encoded argument of the
+//                  consuming call) must equal the approve amount. Only enable this flag if the
+//                  consuming function's FIRST parameter is the amount — if the amount appears in a
+//                  later position the check reads the wrong slot and is silently bypassed.
+//     calls[2] = approve(spender,0)       selector 0x095ea7b3  — mandatory reset
+//                • same token and same spender as calls[0]
+//                • amount must be exactly 0
+//   Any deviation (wrong length, wrong token/spender/target/selector, over-cap, non-zero reset,
+//   reordering, non-zero value, malformed calldata) ⇒ false or revert.
+//
+// ⚠ FUND DESTINATION NOT BOUNDED: unlike every single-call permission in this repo, this contract
+//   makes NO assertion that the consuming call routes funds to ctx.account. The recipient, receiver,
+//   or beneficiary inside calls[1] is unchecked. An agent bug that names an external address in the
+//   consuming call's arguments will not be blocked here. To close this gap, either:
+//     a) use a consuming target/selector that structurally routes output to msg.sender (the SMA), or
+//     b) pair this contract with a protocol-specific single-call permission that bounds the recipient.
+//
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
+//   • The full calldata of the consuming call beyond its leading uint256 (recipients, paths, etc.)
+//     — bound those with a protocol-specific permission if the consuming call needs tighter limits.
+//
+// VERIFY BEFORE USE:
+//   • approve selector 0x095ea7b3 is the ERC-20 standard. ALLOWED_CONSUMING_SELECTORS must match
+//     the real selector(s) of the protocol call you intend to bracket.
+//   • Per-token caps are in each token's base units (decimals differ — USDC 6, WETH 18).
+//   • Requires a SELECTIVE kernel (dispatchBatch exists). Conjunctive kernels have no batch path.
+//   • `sailor mandate simulate` probes single evaluate() only; it cannot probe evaluateBatch().
+//     Verify this contract by calling evaluateBatch(calls, ctx) directly (eth_call) with PASS/FAIL
+//     batches before authorizing on-chain.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context}                 from "@sail/interfaces/IPermission.sol";
+import {IBatchPermission, Call, BatchContext} from "@sail/interfaces/IBatchPermission.sol";
+
+contract BoundedApproveAndCallBatch is IPermission, IBatchPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedApproveAndCallBatch");
+
+    bytes4  private constant SEL_APPROVE       = 0x095ea7b3; // approve(address,uint256)
+    uint256 private constant APPROVE_CALLDATA_LEN = 68;       // 4 + 32 (spender) + 32 (amount)
+    uint256 private constant CONSUMING_MIN_LEN    = 36;       // 4 + 32 (leading uint256 arg)
+
+    mapping(address => uint256) public maxApprovalAmount;   // token  => cap (0 = not allowed)
+    mapping(address => bool)    public isSpender;           // spender allowlist
+    mapping(address => bool)    public isConsumingTarget;   // consuming-call target allowlist
+    mapping(bytes4  => bool)    public isConsumingSelector; // consuming-call selector allowlist
+    bool public immutable REQUIRE_AMOUNT_MATCH;
+
+    /// @param tokens              Allowlisted ERC-20 tokens that may be approved
+    /// @param maxApprovalAmounts  Per-token approve cap, index-parallel with `tokens` (each > 0)
+    /// @param spenders            Allowlisted spenders that may receive the allowance
+    /// @param consumingTargets    Allowlisted targets for the middle (consuming) call
+    /// @param consumingSelectors  Allowlisted selectors for the middle (consuming) call
+    /// @param requireAmountMatch  If true, the consuming call's leading uint256 must equal the approve amount
+    constructor(
+        address[] memory tokens,
+        uint256[] memory maxApprovalAmounts,
+        address[] memory spenders,
+        address[] memory consumingTargets,
+        bytes4[]  memory consumingSelectors,
+        bool requireAmountMatch
+    ) {
+        require(tokens.length == maxApprovalAmounts.length, "tokens/amounts length mismatch");
+        require(tokens.length > 0 && spenders.length > 0, "empty token/spender allowlist");
+        require(consumingTargets.length > 0 && consumingSelectors.length > 0, "empty consuming allowlist");
+
+        for (uint256 i = 0; i < tokens.length; i++) {
+            require(tokens[i] != address(0) && maxApprovalAmounts[i] > 0, "bad token/cap");
+            maxApprovalAmount[tokens[i]] = maxApprovalAmounts[i];
+        }
+        for (uint256 i = 0; i < spenders.length; i++) {
+            require(spenders[i] != address(0), "zero spender");
+            isSpender[spenders[i]] = true;
+        }
+        for (uint256 i = 0; i < consumingTargets.length; i++) {
+            require(consumingTargets[i] != address(0), "zero target");
+            isConsumingTarget[consumingTargets[i]] = true;
+        }
+        for (uint256 i = 0; i < consumingSelectors.length; i++) {
+            require(consumingSelectors[i] != bytes4(0), "zero selector");
+            isConsumingSelector[consumingSelectors[i]] = true;
+        }
+        REQUIRE_AMOUNT_MATCH = requireAmountMatch;
+    }
+
+    // ── IBatchPermission ─────────────────────────────────────────────────────
+
+    /// @inheritdoc IBatchPermission
+    function isBatchPermission() external pure returns (bool) { return true; }
+
+    /// @inheritdoc IBatchPermission
+    function evaluateBatch(Call[] calldata calls, BatchContext calldata ctx) external view returns (bool) {
+        ctx; // batch context unused — bounds depend only on the call sequence, not the SMA
+        if (calls.length != 3) return false;
+
+        // ── calls[0]: approve(spender, amount) on an allowlisted token ───────
+        Call calldata c0 = calls[0];
+        if (c0.value != 0)                            return false;
+        if (c0.data.length != APPROVE_CALLDATA_LEN)   return false;
+        if (bytes4(c0.data[0:4]) != SEL_APPROVE)      return false;
+
+        address token = c0.target;
+        uint256 cap   = maxApprovalAmount[token];
+        if (cap == 0) return false; // token not allowlisted
+
+        (address spender, uint256 approveAmount) = _decodeApprove(c0.data);
+        if (!isSpender[spender])      return false;
+        if (approveAmount == 0)       return false;
+        if (approveAmount > cap)      return false;
+
+        // ── calls[1]: consuming call on an allowlisted (target, selector) ────
+        Call calldata c1 = calls[1];
+        if (c1.value != 0)                          return false;
+        if (!isConsumingTarget[c1.target])          return false;
+        if (c1.data.length < CONSUMING_MIN_LEN)     return false;
+        if (!isConsumingSelector[bytes4(c1.data[0:4])]) return false;
+        if (REQUIRE_AMOUNT_MATCH) {
+            if (uint256(bytes32(c1.data[4:36])) != approveAmount) return false;
+        }
+
+        // ── calls[2]: approve(spender, 0) — mandatory reset of same token+spender ─
+        Call calldata c2 = calls[2];
+        if (c2.value != 0)                            return false;
+        if (c2.target != token)                       return false;
+        if (c2.data.length != APPROVE_CALLDATA_LEN)   return false;
+        if (bytes4(c2.data[0:4]) != SEL_APPROVE)      return false;
+
+        (address resetSpender, uint256 resetAmount) = _decodeApprove(c2.data);
+        if (resetSpender != spender) return false;
+        if (resetAmount != 0)        return false;
+
+        return true;
+    }
+
+    // ── IPermission (batch-only: single dispatch is never authorised) ────────
+
+    /// @inheritdoc IPermission
+    function evaluate(bytes calldata, Context calldata) external pure returns (bool) {
+        return false;
+    }
+
+    /// @inheritdoc IPermission
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+
+    // ── internal calldata decoding (bounds-checked by callers above) ─────────
+
+    function _decodeApprove(bytes calldata data) internal pure returns (address spender, uint256 amount) {
+        spender = address(uint160(uint256(bytes32(data[4:36]))));
+        amount  = uint256(bytes32(data[36:68]));
+    }
+}

package/examples/permissions/BoundedBet_Limitless_Base.sol

@@ -21,14 +21,15 @@ pragma solidity 0.8.26;
 //   Deploying this contract with an unverified ABI may silently PASS or FAIL
 //   all dispatches depending on whether the selector matches.
 //
-// ENFORCED ON-CHAIN (assuming verified ABI — see warning above):
-//   buy(bytes32 conditionId, uint256 amount, uint256 outcomeIndex)
-//   • target must be LIMITLESS_EXCHANGE
-//   • conditionId must be in ALLOWED_CONDITIONS
-//   • amount ≤ MAX_STAKE
-//   • outcomeIndex must be in ALLOWED_OUTCOMES
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked)
+//                    — ASSUMING the unverified ABI above is correct:
+//   buy(bytes32 conditionId,uint256 amount,uint256 outcomeIndex)  selector = keccak256(sig)[0:4]
+//     • target must be LIMITLESS_EXCHANGE
+//     • conditionId must be in ALLOWED_CONDITIONS
+//     • amount ≤ MAX_STAKE
+//     • outcomeIndex must be in ALLOWED_OUTCOMES
 //
-// NOT ENFORCED:
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
 //   • Market price / odds (on-chain prediction market prices fluctuate)
 //   • Timing / frequency of bets
 //

package/examples/permissions/BoundedBorrow_AaveV3_Arbitrum.sol

@@ -4,24 +4,24 @@ 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
+// Chain    : Arbitrum mainnet (42161)
+// Target   : Aave V3 Pool  0x794a61358D6845594F94dc1DB02A252b5b4814aD  (verified on Arbiscan)
 //
-// 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+)
+// 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+)
 //
-// NOT ENFORCED (agent code — can change without a new contract):
+// 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 permissions
+//   • Collateral composition — managed by prior deposit/supply permissions
 //
 // VERIFY BEFORE USE:
 //   • Confirm Aave V3 Pool address on Arbitrum (0x794a... — verify on Arbiscan).

package/examples/permissions/BoundedPerp_GMXv2_Arbitrum.sol

@@ -5,44 +5,48 @@ 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)
+// Chain    : Arbitrum mainnet (42161)
 //
-// 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)
+// ⚠ 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.
 //
-// NOT ENFORCED — documented limitations:
+// 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 directly enforced here because
-//     it depends on collateral price. Add a price-oracle leverage check if needed.
+//     but their ratio (effective leverage) is not enforced — it depends on collateral price.
 //   • 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
+//   • 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:
-//   • Confirm ExchangeRouter address on Arbitrum (0x7c68... — verify on Arbiscan).
-//   • Selector 0x414577b7 = createOrder(IBaseOrderUtils.CreateOrderParams).
-//     Verify against the deployed contract's ABI tab on Arbiscan.
+//   • 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 GMX V2 on Arbitrum testnet before mainnet.
+//   • 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";
@@ -59,23 +63,29 @@ contract BoundedPerp_GMXv2_Arbitrum is IPermission {
     bool public immutable ALLOW_SHORT;
 
     // createOrder(IBaseOrderUtils.CreateOrderParams)
-    // VERIFY: keccak256("createOrder(...)")[0:4] == 0x414577b7 on deployed ExchangeRouter
-    bytes4 private constant SEL_CREATE_ORDER = 0x414577b7;
+    // 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 — MUST match IBaseOrderUtils.CreateOrderParams ──
-    // Verify against:
-    // https://github.com/gmx-io/gmx-synthetics/blob/main/contracts/order/BaseOrderUtils.sol
+    // ── Inline struct definitions — match the CURRENT canonical IBaseOrderUtils.CreateOrderParams ──
+    // Source: https://github.com/gmx-io/gmx-synthetics/blob/main/contracts/order/IBaseOrderUtils.sol
 
-    struct CreateOrderParamAddresses {
+    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
+        address[] swapPath;            // dynamic — makes this struct dynamic
     }
 
-    struct CreateOrderParamNumbers {
+    struct CreateOrderParamsNumbers {
         uint256 sizeDeltaUsd;
         uint256 initialCollateralDeltaAmount;
         uint256 triggerPrice;
@@ -87,14 +97,15 @@ contract BoundedPerp_GMXv2_Arbitrum is IPermission {
     }
 
     struct CreateOrderParams {
-        CreateOrderParamAddresses addresses;
-        CreateOrderParamNumbers   numbers;
+        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

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; }
+}

package/examples/permissions/BoundedSupply_AaveV3_Arbitrum.sol

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : Aave V3
+// Version  : Pool (proxy) — fully on-chain, oracle-based accounting
+// Chain    : Arbitrum mainnet (42161)
+// Target   : Aave V3 Pool  0x794a61358D6845594F94dc1DB02A252b5b4814aD  (verified on Arbiscan;
+//            same Pool as BoundedBorrow_AaveV3_Arbitrum — supply 0x617ba037 confirmed present
+//            in the live implementation 0xf05fd3cc...)
+//
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked):
+//   supply(address asset,uint256 amount,address onBehalfOf,uint16 referralCode)  selector 0x617ba037
+//     • target must be AAVE_POOL
+//     • asset must be in ALLOWED_ASSETS
+//     • amount ≤ MAX_SUPPLY_AMOUNT
+//     • onBehalfOf must equal ctx.account (the SMA — collateral is credited to the SMA, not
+//       to another account)
+//
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
+//   • referralCode (informational only, does not affect fund safety)
+//   • Supply timing / cadence and choice of asset within ALLOWED_ASSETS
+//   • Withdrawal: not gated here (add a withdraw(asset,amount,to) permission with to==SMA if needed)
+//   • A supply also needs a prior ERC-20 approve of the Pool — gate that separately
+//     (see BoundedApproveAndCallBatch.sol for the atomic approve→call→reset pattern).
+//
+// VERIFY BEFORE USE:
+//   • Selector 0x617ba037 = supply(address,uint256,address,uint16) — verified via `cast sig`
+//     and confirmed present in the deployed Pool implementation on Arbitrum.
+//   • This is the canonical Aave V3 Pool.supply. (V3.x also exposes supplyWithPermit — not
+//     gated here; add it if your agent supplies via EIP-2612 permits.)
+//   • MAX_SUPPLY_AMOUNT is in the asset's base units (e.g. USDC = 6 decimals).
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedSupply_AaveV3_Arbitrum is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedSupply_AaveV3_Arbitrum");
+
+    address public immutable AAVE_POOL;
+    mapping(address => bool) public isAllowedAsset;
+    uint256 public immutable MAX_SUPPLY_AMOUNT;
+
+    // supply(address,uint256,address,uint16) — verified 0x617ba037
+    bytes4 private constant SEL_SUPPLY = 0x617ba037;
+
+    /// @param aavePool         Aave V3 Pool proxy address
+    /// @param allowedAssets    Assets the agent may supply (must be non-empty)
+    /// @param maxSupplyAmount  Per-call supply cap in asset base units (must be > 0)
+    constructor(address aavePool, address[] memory allowedAssets, uint256 maxSupplyAmount) {
+        require(aavePool != address(0),      "zero pool address");
+        require(allowedAssets.length > 0,    "empty asset allowlist");
+        require(maxSupplyAmount > 0,         "zero supply cap");
+        AAVE_POOL        = aavePool;
+        MAX_SUPPLY_AMOUNT = maxSupplyAmount;
+        for (uint256 i = 0; i < allowedAssets.length; i++) {
+            require(allowedAssets[i] != address(0), "zero asset address");
+            isAllowedAsset[allowedAssets[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_SUPPLY) return false;
+        // supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)
+        // = 4 ABI-encoded 32-byte slots after the 4-byte selector
+        if (txData.length < 4 + 4 * 32) return false;
+
+        (
+            address asset,
+            uint256 amount,
+            address onBehalfOf,
+            /* uint16 referralCode — not bounded */
+        ) = abi.decode(txData[4:], (address, uint256, address, uint16));
+
+        if (!isAllowedAsset[asset])       return false;
+        if (amount > MAX_SUPPLY_AMOUNT)   return false;
+        if (onBehalfOf != ctx.account)    return false; // collateral credited only to the SMA
+
+        return true;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}

package/examples/permissions/BoundedSwap_UniswapV3_Base.sol

@@ -4,29 +4,31 @@ pragma solidity 0.8.26;
 // ─────────────────────────────────────────────────────────────────────────────
 // Protocol : Uniswap V3
 // Version  : SwapRouter02 (NOT the older SwapRouter — different selectors)
-// Chain    : Base mainnet
-// Target   : SwapRouter02  0x2626664c2603336E57B271c5C0b26F421741e481
+// Chain    : Base mainnet (8453)
+// Target   : SwapRouter02  0x2626664c2603336E57B271c5C0b26F421741e481  (verified on Basescan)
 //
-// ENFORCED ON-CHAIN (via kernel evaluate() on every dispatch):
-//   exactInputSingle path (selector 0x04e45aaf):
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked):
+//   exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))  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):
+//     • amountOutMinimum ≥ amountIn × MIN_BPS / 10 000  (slippage floor — see caveat below)
+//   approve(address,uint256)  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):
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
 //   • fee tier, sqrtPriceLimitX96, recipient address
 //   • swap frequency / cadence
+//   • real (cross-denomination) slippage — see MIN_BPS caveat in evaluate()
 //
 // VERIFY BEFORE USE:
-//   • Confirm SwapRouter02 address on your chain (Base default shown above).
+//   • Confirm SwapRouter02 address on your chain (Base default shown above; verified on Basescan).
 //   • Selector 0x04e45aaf = exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))
-//     on SwapRouter02. The older SwapRouter uses a different selector (0x414577b7).
+//     on SwapRouter02 (verified via `cast sig`). The OLDER SwapRouter's exactInputSingle (the
+//     deadline variant) is 0x414bf389 — a different selector; do not confuse the two.
 //   • Confirm that amountOutMinimum slippage floor fits your price-impact expectations for the
 //     chosen pool. Large amountIn values may trigger price impact beyond MIN_BPS.
 // ─────────────────────────────────────────────────────────────────────────────