@dev.sail.money/sailor 1.3.0-95 → 1.4.0-242

package/templates/default/scripts/shared-template-addr.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// shared-template-addr.mjs — resolve a deployed shared-template singleton
+// address for the active chain. Reads the vendored registry next to the skill
+// (deployed.json) and the chain from .sail/.env.local or .sail/config.json.
+//
+//   node scripts/shared-template-addr.mjs SwapPermission
+//   node scripts/shared-template-addr.mjs TransferPermission --chain base
+//   node scripts/shared-template-addr.mjs --list
+//
+// Prints the checksummed address (or "not deployed" with a non-zero exit).
+// Pure JS, no dependencies.
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+
+// Mirrors the chain map in quote-swap.mjs / resolve-token.mjs so --chain accepts
+// the same names those scripts do, not just a numeric id.
+const CHAIN_NAME_TO_ID = {
+  ethereum: 1,
+  unichain: 130,
+  base: 8453,
+  arbitrum: 42161,
+};
+
+function resolveChainArg(raw) {
+  if (raw === undefined) return null;
+  if (/^\d+$/.test(raw)) return Number(raw);
+  const id = CHAIN_NAME_TO_ID[raw.toLowerCase()];
+  if (id === undefined) {
+    process.stderr.write(
+      `Unknown --chain "${raw}". Known names: ${Object.keys(CHAIN_NAME_TO_ID).join(", ")} (or pass a numeric chain id).\n`,
+    );
+    process.exit(1);
+  }
+  return id;
+}
+
+function readJson(p) {
+  return existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : null;
+}
+
+function readChain() {
+  // .sail/.env.local CHAIN_ID, then .sail/config.json chainId
+  const envPath = resolvePath(process.cwd(), ".sail", ".env.local");
+  if (existsSync(envPath)) {
+    for (const line of readFileSync(envPath, "utf8").split("\n")) {
+      const m = line.match(/^\s*CHAIN_ID\s*=\s*(\d+)/);
+      if (m) return Number(m[1]);
+    }
+  }
+  const cfg = readJson(resolvePath(process.cwd(), ".sail", "config.json"));
+  return cfg?.chainId ?? null;
+}
+
+const REGISTRY = JSON.parse(
+  readFileSync(
+    resolvePath(
+      resolvePath(new URL(".", import.meta.url).pathname),
+      "..",
+      ".agents",
+      "skills",
+      "sail-templates",
+      "deployed.json",
+    ),
+    "utf8",
+  ),
+);
+
+const args = process.argv.slice(2);
+const list = args.includes("--list");
+const name = args.find((a) => !a.startsWith("--"));
+const chainFlagIdx = args.indexOf("--chain");
+const chainOverride = chainFlagIdx !== -1 ? resolveChainArg(args[chainFlagIdx + 1]) : null;
+const chainId = chainOverride ?? readChain();
+
+if (list) {
+  process.stdout.write(
+    "Deployed shared templates by chain (from .agents/skills/sail-templates/deployed.json):\n",
+  );
+  for (const [cid, templates] of Object.entries(REGISTRY.chains)) {
+    const names = Object.keys(templates);
+    process.stdout.write(`  chain ${cid}: ${names.length ? names.join(", ") : "(none)"}\n`);
+  }
+  process.exit(0);
+}
+
+if (!name) {
+  process.stderr.write(
+    `Usage: shared-template-addr.mjs <TemplateName> [--chain <id|${Object.keys(CHAIN_NAME_TO_ID).join("|")}>] [--list]\n`,
+  );
+  process.exit(1);
+}
+if (!chainId) {
+  process.stderr.write(
+    "Could not resolve chain. Pass --chain <id> or set CHAIN_ID in .sail/.env.local.\n",
+  );
+  process.exit(1);
+}
+
+const chainTemplates = REGISTRY.chains[String(chainId)] ?? {};
+const addr = chainTemplates[name];
+if (!addr) {
+  process.stderr.write(
+    `"${name}" is not deployed on chain ${chainId}.\n` +
+      `Deployed here: ${Object.keys(chainTemplates).join(", ") || "(none)"}.\n` +
+      `SwapPermissionNoOracle is source-only (not deployed on any chain) — use SwapPermission or author a bespoke permission.\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(addr + "\n");

package/templates/default/test/BoundedCallPermission.t.sol

@@ -39,7 +39,8 @@ contract BoundedCallPermissionTest {
             selector: selector,
             value: value,
             blockTimestamp: block.timestamp,
-            blockNumber: block.number
+            blockNumber: block.number,
+            configEpoch: 0 // BoundedCallPermission takes no post-deploy config; value unused
         });
     }
 

package/docs/PERMISSION_MODEL.md

@@ -1,93 +0,0 @@
-# Sail permission model: conjunctive vs selective
-
-The deployed SailKernel ships in **two incompatible dispatch models**. Which one a
-chain runs changes how dispatches are signed *and* how permissions must be written.
-Get this wrong and every dispatch reverts with an opaque selector. This is the single
-most important thing to understand before operating an SMA.
-
-## TL;DR
-
-| | **Conjunctive** (older) | **Selective** (newer) |
-|---|---|---|
-| Chains today (bundled kernels) | None — all bundled kernels moved to selective | Base (8453), Base Sepolia (84532), Arbitrum (42161), Unichain (130) |
-| `dispatch(...)` | `(account, target, value, data, sig, deadline)` — **no `permission`** | `(account, permission, target, value, data, sig, deadline)` |
-| Which permissions are checked | **ALL** registered permissions; **all must return true** | only the **one** permission named in the call |
-| EIP-712 `Dispatch` struct | no `permission` field | includes `permission` |
-| Batch (`dispatchBatch`/`previewBatch`) | **not available** | available |
-| **Permission design rule** | **MUST pass through calls outside its domain** | may return false freely |
-
-Don't guess from a version string — **detect it on-chain** (see below).
-
-## The conjunctive pass-through rule (the big footgun)
-
-On a conjunctive kernel the kernel calls `evaluate(txData, ctx)` on **every**
-registered permission and ANDs the results. A single `false` blocks the whole
-dispatch (`PermissionDenied`).
-
-So a permission that only cares about, say, approvals **must still return `true` for
-every call it doesn't govern**:
-
-```solidity
-function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
-    // Pass through calls outside this permission's domain (conjunctive model).
-    if (ctx.selector != APPROVE) return true;   // <-- without this line, this
-                                                 //     permission bricks swaps,
-                                                 //     transfers, everything.
-    // ...domain-specific checks for approve...
-}
-```
-
-A permission that returns `false` (or reverts, or runs out of gas — both treated as
-`false`) on unrelated calls **bricks the entire account**: no dispatch of any kind
-can pass. We hit exactly this during bring-up with permissions that "blocked each
-other." The fix was to redeploy every permission with pass-through semantics.
-
-Corollary: on a conjunctive kernel you **cannot** have two permissions that each
-enforce a different token's approve — each would reject the other's token. To support
-approving both DAI and USDC you need **one** approve permission that allows both (see
-`examples/lifi-permissions/`), not two narrow ones.
-
-Selective kernels don't have this problem: each dispatch names one permission and
-only that one is consulted.
-
-## Detect the model on-chain
-
-The SDK reads each kernel's public `DISPATCH_TYPEHASH` constant and matches it
-against the canonical hashes for each model. Never assume.
-
-```ts
-const caps = await client.capabilities();
-// caps.dispatchModel: "conjunctive" | "selective"
-// caps.dispatchTypehash, caps.source ("onchain-typehash" | "static-hint")
-```
-
-Verified typehashes:
-
-- conjunctive `DISPATCH_TYPEHASH` = `0x7510c80e…`
-  `Dispatch(address account,address target,uint256 value,bytes32 dataHash,uint256 nonce,uint256 deadline)`
-- selective `DISPATCH_TYPEHASH` =
-  `Dispatch(address account,address permission,address target,uint256 value,bytes32 dataHash,uint256 nonce,uint256 deadline)`
-
-`client.dispatch.single(...)` already signs the correct struct and uses the correct
-ABI for the detected model — you don't sign by hand. `client.dispatch.batch` /
-`preview` throw a clear error on conjunctive kernels (no `dispatchBatch`).
-
-## Roles (unchanged across models)
-
-| Role | Authority |
-|------|-----------|
-| **Owner** | Holds the Safe; custody anchor. |
-| **Permission Signer** | Authorizes which `IPermission` contracts apply (EIP-712 `RegisterPermissions` / `RevokePermissions`). Signed in the browser signing station — the agent never holds this key. |
-| **Manager** | Executes dispatches within the registered permissions (ECDSA / ERC-1271). The agent's hot key. |
-
-## Preflight before spending gas
-
-Run `sailor doctor` (read-only, no gas, no keys):
-
-- detects the dispatch model,
-- lists registered permissions,
-- on a conjunctive kernel, **probes each permission for pass-through** and flags any
-  that would brick dispatch.
-
-See [AGENTS.md](../AGENTS.md) for the operational decision tree and the
-revert failure-mode catalog.

package/examples/README.md

@@ -1,24 +0,0 @@
-# examples/
-
-Reference material for building Sail permission contracts. Nothing here is part of
-Sail Protocol and nothing here is audited.
-
-## What's in here
-
-### `permissions/`
-
-Protocol-specific permission examples (Uniswap, Aave, GMX, Vault, Pendle, and others).
-These are copied into your project by `sailor init` so you have local starting points to
-adapt. They are not a supported or exhaustive library — review them before using.
-
-### `custom-mandate/`
-
-A standalone Foundry workspace scaffold for authoring your own `IPermission` contract as a
-separate project. Fork it, rename it, and build from `BoundedCallPermission.sol`.
-
-### `lifi-permissions/`
-
-Reference-only source for the deployed LiFi EIP-1167 clone implementations
-(`LifiBoundedApprovePermissionCloneable`, `LifiDiamondSwapPermissionCloneable`).
-These document live deployed contracts — do not adapt them directly for new projects.
-See the `README.md` inside for deployment addresses and the conjunctive-kernel caveat.

package/examples/lifi-permissions/LifiBoundedApprovePermissionCloneable.sol

@@ -1,84 +0,0 @@
-// SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
-
-import {IPermission, Context} from "../../.sail/contracts/interfaces/IPermission.sol";
-import {CloneInitializable} from "../../.sail/contracts/templates/base/CloneInitializable.sol";
-
-/// @title  LifiBoundedApprovePermissionCloneable
-/// @notice EIP-1167 clone-template approval permission with PER-TOKEN caps. The
-///         logic contract is deployed once and registered in the SDK's
-///         standaloneTemplates; each account clones it via
-///         PermissionFactory.deployAndAttach and configures via initialize().
-///
-///         The manager may ONLY approve the LiFi Diamond, and only on tokens that
-///         have a configured cap, up to that token's cap. Passes through any
-///         non-approve call (conjunctive model).
-///
-///         Caps are PER TOKEN (not one global cap) because token value and decimals
-///         differ — e.g. 1 DAI = 1e18 base units vs 1 USDC = 1e6. A single cap can't
-///         bound both sensibly.
-contract LifiBoundedApprovePermissionCloneable is IPermission, CloneInitializable {
-    bytes4 private constant APPROVE = 0x095ea7b3;
-    address public constant LIFI_DIAMOND = 0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE;
-
-    // Per-token approve cap, in the token's base units. 0 = token not allowed.
-    // A mapping occupies its own slot pointer and does not pack with the
-    // CloneInitializable `_initialized` bool at slot 0.
-    mapping(address token => uint256 cap) public maxApprovePerToken;
-    address public permissionSigner;
-
-    error NotPermissionSigner();
-    error ZeroAddress();
-    error LengthMismatch();
-
-    modifier onlyPermissionSigner() {
-        if (msg.sender != permissionSigner) revert NotPermissionSigner();
-        _;
-    }
-
-    /// @dev Lock the logic contract; only clones (fresh storage) can be initialized.
-    constructor() {
-        _disableInitializers();
-    }
-
-    /// @notice One-time per-clone configuration.
-    /// @param tokens            Tokens the manager may approve to the LiFi Diamond.
-    /// @param caps              Per-token cap (token base units); index-aligned with `tokens`.
-    /// @param _permissionSigner Owner wallet; sole authority for post-init updates.
-    function initialize(
-        address[] memory tokens,
-        uint256[] memory caps,
-        address _permissionSigner
-    ) external initializer {
-        if (_permissionSigner == address(0)) revert ZeroAddress();
-        if (tokens.length != caps.length) revert LengthMismatch();
-        permissionSigner = _permissionSigner;
-        for (uint256 i; i < tokens.length; i++) {
-            maxApprovePerToken[tokens[i]] = caps[i];
-        }
-    }
-
-    /// @notice Set (cap > 0) or clear (cap == 0) a token's per-tx approve cap.
-    function setTokenCap(address token, uint256 cap) external onlyPermissionSigner {
-        maxApprovePerToken[token] = cap;
-    }
-
-    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
-        // Pass through calls outside this permission's domain (conjunctive model).
-        if (ctx.selector != APPROVE) return true;
-        if (ctx.target == address(0)) return false; // token is ctx.target
-        if (txData.length < 68) return false;
-
-        (address spender, uint256 amount) = abi.decode(txData[4:], (address, uint256));
-        if (spender != LIFI_DIAMOND) return false;
-
-        uint256 cap = maxApprovePerToken[ctx.target];
-        if (cap == 0) return false; // token not allowed
-        if (amount > cap) return false; // over the per-token cap
-        return true;
-    }
-
-    function discriminator() external pure returns (bytes32) {
-        return keccak256("LifiBoundedApprovePermissionCloneable.v1");
-    }
-}

package/examples/lifi-permissions/LifiDiamondSwapPermissionCloneable.sol

@@ -1,97 +0,0 @@
-// SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
-
-import {IPermission, Context} from "../../.sail/contracts/interfaces/IPermission.sol";
-import {CloneInitializable} from "../../.sail/contracts/templates/base/CloneInitializable.sol";
-
-/// @title  LifiDiamondSwapPermissionCloneable
-/// @notice EIP-1167 clone-template version of LifiDiamondSwapPermission. The logic
-///         contract is deployed once and registered in the SDK's standaloneTemplates;
-///         each account gets its own clone via PermissionFactory.deployAndAttach,
-///         configured through initialize() (NOT the constructor).
-///
-///         Restricts manager-initiated swaps to the official LiFi Diamond on Base:
-///          - target must be the LiFi Diamond,
-///          - selector must be allowlisted,
-///          - receiver embedded in the calldata must equal ctx.account (the SMA),
-///          - the minAmount field must not exceed the configured cap.
-///         Passes through any call whose target is not the diamond (conjunctive model).
-///
-///         Calldata layout (validated against live Base quotes):
-///          selector(4) + word0(32) + word1(32) + word2(32) + receiver(32) + minAmount(32)
-///          → receiver at offset 100, minAmount at offset 132.
-contract LifiDiamondSwapPermissionCloneable is IPermission, CloneInitializable {
-    // Official LiFi Diamond on Base Mainnet.
-    address public constant LIFI_DIAMOND = 0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE;
-
-    // Storage starts after CloneInitializable's `_initialized` bool (slot 0). A
-    // mapping occupies its own slot pointer and does not pack with the bool.
-    mapping(bytes4 selector => bool) public isAllowedSelector;
-    uint256 public maxMinAmountPerTx;
-    address public permissionSigner;
-
-    error NotPermissionSigner();
-    error ZeroAddress();
-
-    modifier onlyPermissionSigner() {
-        if (msg.sender != permissionSigner) revert NotPermissionSigner();
-        _;
-    }
-
-    /// @dev Lock the logic contract; only clones (fresh storage) can be initialized.
-    constructor() {
-        _disableInitializers();
-    }
-
-    /// @notice One-time per-clone configuration.
-    /// @param allowedSelectors   LiFi Diamond selectors to allowlist on init.
-    /// @param _maxMinAmountPerTx Cap on the minAmount field (type(uint256).max = uncapped).
-    /// @param _permissionSigner  Owner wallet; sole authority for post-init updates.
-    function initialize(
-        bytes4[] memory allowedSelectors,
-        uint256 _maxMinAmountPerTx,
-        address _permissionSigner
-    ) external initializer {
-        if (_permissionSigner == address(0)) revert ZeroAddress();
-        maxMinAmountPerTx = _maxMinAmountPerTx;
-        permissionSigner = _permissionSigner;
-        for (uint256 i; i < allowedSelectors.length; i++) {
-            isAllowedSelector[allowedSelectors[i]] = true;
-        }
-    }
-
-    function setMaxMinAmountPerTx(uint256 newMax) external onlyPermissionSigner {
-        maxMinAmountPerTx = newMax;
-    }
-
-    /// @notice Add a LiFi selector. Only after verifying its calldata places
-    ///         `receiver` at offset 100 and `minAmount` at offset 132.
-    function addSelector(bytes4 selector) external onlyPermissionSigner {
-        isAllowedSelector[selector] = true;
-    }
-
-    function removeSelector(bytes4 selector) external onlyPermissionSigner {
-        isAllowedSelector[selector] = false;
-    }
-
-    uint256 private constant RECEIVER_OFFSET = 100;
-    uint256 private constant MIN_DATA_LEN = 164;
-
-    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
-        // Pass through calls outside this permission's domain (conjunctive model).
-        if (ctx.target != LIFI_DIAMOND) return true;
-        if (!isAllowedSelector[ctx.selector]) return false;
-        if (txData.length < MIN_DATA_LEN) return false;
-
-        address receiver = abi.decode(txData[RECEIVER_OFFSET:RECEIVER_OFFSET + 32], (address));
-        uint256 minAmount = abi.decode(txData[RECEIVER_OFFSET + 32:RECEIVER_OFFSET + 64], (uint256));
-
-        if (receiver != ctx.account) return false;
-        if (minAmount > maxMinAmountPerTx) return false;
-        return true;
-    }
-
-    function discriminator() external pure returns (bytes32) {
-        return keccak256("LifiDiamondSwapPermissionCloneable.v1");
-    }
-}

package/examples/lifi-permissions/README.md

@@ -1,53 +0,0 @@
-# LiFi clone-permission templates
-
-Canonical source (for reference) of the EIP-1167 **clone** permission templates
-used for LiFi-based swaps/DCA. The logic contracts are deployed once per chain and
-registered in the SDK deployment registry
-(`packages/sdk/src/deployments.ts` → `standaloneTemplates` / `cloneTemplates`).
-Each account gets its own clone via `PermissionFactory.deployAndAttach`, configured
-through `initialize()` (never the constructor).
-
-These follow the `CloneInitializable` pattern: the constructor calls
-`_disableInitializers()` to permanently lock the logic contract, and a one-time
-`initialize()` (guarded by the `initializer` modifier) configures each clone.
-
-> The `import` paths reference `../../.sail/contracts/{interfaces,templates/base}`
-> from the Foundry project they were built in
-> (`tests/base-mainnet-agent-01/`). This folder is **reference source** — sailor has
-> no Foundry build. Build/deploy happens in that project via
-> `scripts/deploy-clone-templates.ts`.
-
-> **Note:** The kernels bundled in `@sail.money/sailor/sdk` (Base, Base Sepolia, Arbitrum, Unichain) now all run the **selective** dispatch model — verified on-chain against each kernel's `DISPATCH_TYPEHASH`. These templates were written for the older conjunctive model and include pass-through logic (`return true` for calls outside their domain) that is not required on selective kernels. Review before deploying against a selective kernel; the pass-through logic is harmless but unnecessary.
-
-## Contracts
-
-### LifiDiamondSwapPermissionCloneable → `boundedLiFi`
-Restricts manager swaps to the official LiFi Diamond:
-target == diamond, selector allowlisted, embedded receiver == `ctx.account`,
-`minAmount <= maxMinAmountPerTx`. Passes through any call whose target is not the
-diamond (conjunctive-kernel rule).
-
-`initialize(bytes4[] allowedSelectors, uint256 maxMinAmountPerTx, address permissionSigner)`
-
-### LifiBoundedApprovePermissionCloneable → `boundedApprove`
-Approve only the LiFi Diamond, only on tokens with a configured cap, up to that
-cap. **Per-token caps** (`mapping(token => cap)`) because token value/decimals
-differ (1 DAI = 1e18 vs 1 USDC = 1e6). Passes through non-approve calls.
-
-`initialize(address[] tokens, uint256[] caps, address permissionSigner)`
-
-## Deployed logic addresses
-
-| Template | Chain | Address |
-|---|---|---|
-| boundedLiFi | Base mainnet (8453) | `0xF1abcF774250fD1A8147B56DA07Bf9021064650A` |
-| boundedApprove | Base mainnet (8453) | `0x9c0b86daf9e75d759a5D165aD7366e52b3353fD8` |
-
-Both verified `initialized() == true` (logic locked) post-deploy.
-
-## Conjunctive-kernel note
-
-Both Base kernels use the **conjunctive** dispatch model: every registered
-permission is evaluated and ALL must return true. So a permission MUST pass through
-calls outside its own domain (return `true`), or it bricks unrelated dispatches.
-Both templates above do this.