@agenticprimitives/contracts 1.0.0-alpha.26 → 1.0.0-alpha.27

package/src/custody/CustodyPolicy.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.28;
 
-import {IAgentAccount, AgentAccountRecoveryArgs, AgentAccountRecoveryPasskeyAdd} from "../IAgentAccount.sol";
+import {IAgentAccount, AgentAccountRecoveryArgs, AgentAccountRecoveryPasskeyAdd, AgentAccountRotateCredentialArgs} from "../IAgentAccount.sol";
 import {SignatureSlotRecovery} from "../libraries/SignatureSlotRecovery.sol";
 
 /// @dev R6.6 — minimal interface for the `account → factory → governance.isPaused()`
@@ -80,7 +80,8 @@ contract CustodyPolicy {
         ChangeValueCeiling,           // 12 — T4
         SetRecoveryApprovals,      // 13 — T4
         RecoverAccount,            // 14 — T6
-        ChangeApprovalsRequired    // 15 — T4 (per-tier custody quorum threshold)
+        ChangeApprovalsRequired,   // 15 — T4 (per-tier custody quorum threshold)
+        RotateCredential           // 16 — T4 (spec 410 §1.2: add + retire + re-approve standing wires, atomically)
     }
 
     struct ScheduledChange {
@@ -296,6 +297,9 @@ contract CustodyPolicy {
     event T3CeilingChanged(address indexed account, uint256 oldCeiling, uint256 newCeiling);
     event RecoveryThresholdChanged(address indexed account, uint8 oldValue, uint8 newValue);
     event OwnersRotated(address indexed account, uint256 newOwnerCount);
+    /// @dev Spec 410 §1.2 — a planned rotation applied: one credential in, one out, `reapproved` wires
+    ///      re-approved under the new custody epoch in the same transaction.
+    event CredentialRotated(address indexed account, uint256 reapproved);
     /// @notice Audit C-10: per-rotation count of custodians removed.
     event CustodiansRemovedDuringRotation(address indexed account, uint256 removedCount);
     /// @notice Audit C-11: CustodyPolicy was uninstalled; the account
@@ -343,6 +347,8 @@ contract CustodyPolicy {
     error UnconfiguredTier(uint8 tier);
     error RecoveryRequiresGuardians();
     error EmptyOwnerSet();
+    /// @dev Spec 410 §1.2 — `RotateCredential` needs exactly one credential added and exactly one retired.
+    error RotationNeedsOneAddAndOneRemove();
     error CustodyActionNotYetImplemented(uint8 action);
     error CannotDowngradeWithTrustees();
     error TimelockRequiredForTier(uint8 tier);
@@ -858,6 +864,9 @@ contract CustodyPolicy {
         } else if (action == CustodyAction.RecoverAccount) {
             AgentAccountRecoveryArgs memory r = abi.decode(args, (AgentAccountRecoveryArgs));
             _applyRecoverAccount(account, r);
+        } else if (action == CustodyAction.RotateCredential) {
+            AgentAccountRotateCredentialArgs memory r = abi.decode(args, (AgentAccountRotateCredentialArgs));
+            _applyRotateCredential(account, r);
         } else if (action == CustodyAction.ApplySystemUpdate) {
             (address newImpl) = abi.decode(args, (address));
             _execute(account, abi.encodeWithSignature("upgradeToAndCall(address,bytes)", newImpl, ""));
@@ -977,6 +986,9 @@ contract CustodyPolicy {
                 removed++;
             }
         }
+        // Spec 410 §1.2: a bulk custodian rotation carries no re-approval list; like recovery it voids every
+        // approval so nothing planted for a future epoch survives it. Re-approve through `RotateCredential`.
+        _revokeAllApprovedDigests(account);
         emit OwnersRotated(account, added);
         // Note: OwnersRotated only carries `added` for ABI compat. A
         // future revision should add a `removed` field; that's a
@@ -1070,9 +1082,47 @@ contract CustodyPolicy {
             removedPasskeys++;
         }
 
+        // Spec 410 §1.2 (THESIS-1a): recovery re-approves nothing and voids every approval the account
+        // ever made — including one planted for a future epoch. The person re-issues from a reviewed list.
+        _revokeAllApprovedDigests(account);
         emit AccountRecovered(account, addedOwners, removedOwners, addedPasskeys, removedPasskeys);
     }
 
+    /// @dev Spec 410 §1.2 — the planned rotation: add → retire → re-approve, one transaction. The account
+    ///      derives each key under the post-retirement epoch (`approveDigest`); this module never computes
+    ///      a key. Exactly one credential in and one out, so the account is never credential-less and the
+    ///      action cannot be bent into a bulk custody change at the rotation tier.
+    function _applyRotateCredential(address account, AgentAccountRotateCredentialArgs memory r) internal {
+        bool addsOwner = r.addOwner != address(0);
+        bool addsPasskey = r.addPasskey.x != 0 || r.addPasskey.y != 0 || r.addPasskey.credentialIdDigest != bytes32(0);
+        bool removesOwner = r.removeOwner != address(0);
+        bool removesPasskey = r.removePasskeyCredentialIdDigest != bytes32(0);
+        if (addsOwner == addsPasskey || removesOwner == removesPasskey) revert RotationNeedsOneAddAndOneRemove();
+
+        if (addsOwner) {
+            _execute(account, abi.encodeCall(IAgentAccount.addCustodian, (r.addOwner)));
+        } else {
+            _execute(account, abi.encodeWithSignature(
+                "addPasskey(bytes32,uint256,uint256,bytes32)",
+                r.addPasskey.credentialIdDigest, r.addPasskey.x, r.addPasskey.y, r.addPasskey.rpIdHash
+            ));
+        }
+        if (removesOwner) {
+            _execute(account, abi.encodeCall(IAgentAccount.removeCustodian, (r.removeOwner)));
+        } else {
+            _execute(account, abi.encodeWithSignature("removePasskey(bytes32)", r.removePasskeyCredentialIdDigest));
+        }
+        for (uint256 i; i < r.reapprove.length; i++) {
+            _execute(account, abi.encodeWithSignature("approveDigest(bytes32)", r.reapprove[i]));
+        }
+        emit CredentialRotated(account, r.reapprove.length);
+    }
+
+    /// @dev Spec 410 §1.2 — `AgentAccount.revokeAllApprovedDigests()` as the account (module context).
+    function _revokeAllApprovedDigests(address account) internal {
+        _execute(account, abi.encodeWithSignature("revokeAllApprovedDigests()"));
+    }
+
     /// @dev Spec § 5.1 default-threshold matrix.
     function _defaultApprovals(uint8 nCustodians, uint8 tier) internal pure returns (uint8) {
         if (nCustodians == 0) return 0;

package/src/custody/TreasurySpendPolicy.sol

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title TreasurySpendPolicy — an aggregate ceiling AT THE RESOURCE (spec 410 §7, THESIS-6)
+ * @notice Every caveat enforcer bounds ONE delegation: `ValueEnforcer` a call's value, `PaymentEnforcer` a
+ *         mandate's budget under (delegator, delegationHash). None of them can see the treasury's other
+ *         delegates, so two delegates each under their own ceiling can jointly exceed the principal's
+ *         budget. This module is the ceiling that belongs to the TREASURY: an ERC-7579 HOOK the account
+ *         installs, consulted on every `execute` / `executeBatch` — a custodian's own userOp and a delegated
+ *         redemption alike, because the account runs its hooks on both — that adds the value each call moves
+ *         to the current window and refuses the one that would pass the ceiling.
+ *
+ *         WHAT IT COUNTS. Native value (`value` on the call) when `asset == address(0)`; otherwise ERC-20
+ *         `transfer(to, amount)` and `transferFrom(from, to, amount)` calldata aimed at `asset`. Anything else
+ *         moves no value of this asset and is not counted. A batch is one call: its inner calls are summed.
+ *
+ *         WINDOWS are fixed-length epochs from `windowStart` — never sliding — so the check is O(1) and the
+ *         refusal is reproducible off chain from the receipt and the block time.
+ *
+ *         WHO SETS IT. The budget is the install data: `installModule(4, this, abi.encode(asset, ceiling,
+ *         windowSeconds))`, which on a custody-governed treasury is a governance selector under its quorum;
+ *         changing it is an uninstall + reinstall under the same gate. There is no setter a single key could
+ *         reach. Per-delegation ceilings are untouched: the tighter of the two refuses.
+ *
+ *         WHAT IT IS NOT: a policy of who may spend (that is the mandate), a rate limit on calls, or anything
+ *         a planner consults — the harness may READ `budget()` to say "this would exceed the treasury's
+ *         shared budget" before a signature (honesty); the hook is the authority.
+ */
+contract TreasurySpendPolicy {
+    struct Budget {
+        address asset;        // address(0) = native value
+        uint256 ceiling;      // per window, in the asset's base units
+        uint64 windowSeconds; // fixed epochs from windowStart
+        uint64 windowStart;
+        uint64 windowIndex;   // the epoch `spent` belongs to
+        uint256 spent;
+        bool installed;
+    }
+
+    /// account => budget
+    mapping(address => Budget) private _budgets;
+
+    event BudgetInstalled(address indexed account, address indexed asset, uint256 ceiling, uint64 windowSeconds, uint64 windowStart);
+    event BudgetUninstalled(address indexed account);
+    event Spent(address indexed account, uint64 indexed windowIndex, uint256 amount, uint256 spentInWindow);
+
+    error BudgetExceeded(uint256 ceiling, uint256 spentInWindow, uint256 amount);
+    error NotInstalledOn(address account);
+    error AlreadyInstalledOn(address account);
+    error BadBudget();
+
+    bytes4 private constant TRANSFER = bytes4(keccak256("transfer(address,uint256)"));
+    bytes4 private constant TRANSFER_FROM = bytes4(keccak256("transferFrom(address,address,uint256)"));
+
+    // ─── ERC-7579 module surface ───────────────────────────────────────
+
+    function isModuleType(uint256 moduleTypeId) external pure returns (bool) { return moduleTypeId == 4; }
+    function moduleId() external pure returns (string memory) { return "agenticprimitives-treasury-spend-policy-1"; }
+
+    /// @notice Called by the account from `installModule` (governance-gated there): the budget is the install data.
+    function onInstall(bytes calldata initData) external {
+        Budget storage b = _budgets[msg.sender];
+        if (b.installed) revert AlreadyInstalledOn(msg.sender);
+        (address asset, uint256 ceiling, uint64 windowSeconds) = abi.decode(initData, (address, uint256, uint64));
+        if (windowSeconds == 0) revert BadBudget();
+        b.asset = asset;
+        b.ceiling = ceiling;
+        b.windowSeconds = windowSeconds;
+        b.windowStart = uint64(block.timestamp);
+        b.windowIndex = 0;
+        b.spent = 0;
+        b.installed = true;
+        emit BudgetInstalled(msg.sender, asset, ceiling, windowSeconds, b.windowStart);
+    }
+
+    function onUninstall(bytes calldata) external {
+        if (!_budgets[msg.sender].installed) revert NotInstalledOn(msg.sender);
+        delete _budgets[msg.sender];
+        emit BudgetUninstalled(msg.sender);
+    }
+
+    // ─── The hook ──────────────────────────────────────────────────────
+
+    /// @notice `preCheck` from the account: `msgData` is `abi.encode(target, value, data)` for `execute` and
+    ///         `abi.encode(Call[])` for `executeBatch`. Sums the value this call moves in the budget's asset and
+    ///         refuses when the window's total would pass the ceiling.
+    function preCheck(address, uint256, bytes calldata msgData) external returns (bytes memory) {
+        Budget storage b = _budgets[msg.sender];
+        if (!b.installed) return hex"";
+        uint256 amount = _valueMoved(b.asset, msgData);
+        if (amount == 0) return hex"";
+        uint64 idx = uint64((block.timestamp - b.windowStart) / b.windowSeconds);
+        if (idx != b.windowIndex) { b.windowIndex = idx; b.spent = 0; }
+        uint256 next = b.spent + amount;
+        if (next > b.ceiling) revert BudgetExceeded(b.ceiling, b.spent, amount);
+        b.spent = next;
+        emit Spent(msg.sender, idx, amount, next);
+        return hex"";
+    }
+
+    function postCheck(bytes calldata) external {}
+
+    // ─── Reads (the harness's honesty, never its authority) ────────────
+
+    function budget(address account) external view returns (address asset, uint256 ceiling, uint64 windowSeconds, uint64 windowStart, uint64 windowIndex, uint256 spent, bool installed) {
+        Budget storage b = _budgets[account];
+        return (b.asset, b.ceiling, b.windowSeconds, b.windowStart, b.windowIndex, b.spent, b.installed);
+    }
+
+    /// @notice What the account has spent in the CURRENT window (0 once the window rolled), and the ceiling.
+    function remaining(address account) external view returns (uint256 left, uint256 ceiling) {
+        Budget storage b = _budgets[account];
+        if (!b.installed) return (type(uint256).max, 0);
+        uint64 idx = uint64((block.timestamp - b.windowStart) / b.windowSeconds);
+        uint256 spent = idx == b.windowIndex ? b.spent : 0;
+        return (b.ceiling > spent ? b.ceiling - spent : 0, b.ceiling);
+    }
+
+    // ─── Internals ─────────────────────────────────────────────────────
+
+    /// @dev Both encodings the account uses, told apart by the first word: `abi.encode(Call[])` opens with the
+    ///      array's offset (exactly 0x20), `abi.encode(target, value, data)` with the target address — and no
+    ///      contract lives at address 0x20. The decode runs through an external self-call so a malformed payload
+    ///      is caught rather than reverting the account's call (abi.decode cannot be tried in place).
+    function _valueMoved(address asset, bytes calldata msgData) internal view returns (uint256 total) {
+        if (msgData.length < 32) return 0;
+        uint256 first = uint256(bytes32(msgData[0:32]));
+        if (first == 0x20) {
+            try this.decodeBatch(msgData) returns (Call[] memory calls) {
+                for (uint256 i = 0; i < calls.length; i++) total += _amountOf(asset, calls[i].target, calls[i].value, calls[i].data);
+                return total;
+            } catch { return 0; }
+        }
+        try this.decodeSingle(msgData) returns (address target, uint256 value, bytes memory data) {
+            return _amountOf(asset, target, value, data);
+        } catch { return 0; }
+    }
+
+    struct Call { address target; uint256 value; bytes data; }
+
+    function decodeSingle(bytes calldata msgData) external pure returns (address, uint256, bytes memory) {
+        return abi.decode(msgData, (address, uint256, bytes));
+    }
+    function decodeBatch(bytes calldata msgData) external pure returns (Call[] memory) {
+        return abi.decode(msgData, (Call[]));
+    }
+
+    function _amountOf(address asset, address target, uint256 value, bytes memory data) internal pure returns (uint256) {
+        if (asset == address(0)) return value;
+        if (target != asset || data.length < 4) return 0;
+        bytes4 sel;
+        assembly { sel := mload(add(data, 32)) }
+        if (sel == TRANSFER && data.length >= 68) {
+            uint256 amount;
+            assembly { amount := mload(add(data, 68)) }
+            return amount;
+        }
+        if (sel == TRANSFER_FROM && data.length >= 100) {
+            uint256 amount;
+            assembly { amount := mload(add(data, 100)) }
+            return amount;
+        }
+        return 0;
+    }
+}

package/src/enforcers/PayloadClassesEnforcer.sol

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "../agency/ICaveatEnforcer.sol";
+
+/**
+ * @title PayloadClassesEnforcer — the INFORMATION-FLOW caveat (spec 410 §7)
+ * @notice Where a read precedes a write in one plan — read a member's record, then send a message — the
+ *         mandate names, as ontology classes, what the write MAY CARRY: `apvault:ContactEmail`, never
+ *         `apvault:GivingHistory`. terms = abi.encode(string[] classIris).
+ *
+ *         THE CHAIN CANNOT READ A PAYLOAD, and this enforcer does not pretend to: its hooks are pure no-ops.
+ *         What it does is pin the terms INTO THE SIGNED DELEGATION — the caveat is part of the EIP-712 hash
+ *         the person approved — so the off-chain per-step verifier (`delegation.evaluateCaveats`, strict)
+ *         judges the write's declared payload classes (the tool contract's `carries`, per argument) against
+ *         exactly what was signed, and nobody can widen the list without a new signature. An enforcer that
+ *         judged nothing and pinned nothing would be a comment; this one pins.
+ *
+ *         What it is NOT: authority over the read (the read has its own mandate and scope), a content
+ *         filter, or a substitute for the vault's per-record scope — those are enforced where the data is.
+ */
+contract PayloadClassesEnforcer is ICaveatEnforcer {
+    function beforeHook(bytes calldata, bytes calldata, bytes32, address, address, address, uint256, bytes calldata) external pure override {}
+    function afterHook(bytes calldata, bytes calldata, bytes32, address, address, address, uint256, bytes calldata) external pure override {}
+
+    /// @notice The classes a wire's terms name — for a reader with the wire and no SDK.
+    function classesOf(bytes calldata terms) external pure returns (string[] memory) {
+        return abi.decode(terms, (string[]));
+    }
+}

package/src/registry/EstateProjectionRegistry.sol

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title EstateProjectionRegistry — an estate's authority, projected onto PUBLIC GROUND (spec 410 §4)
+ * @notice One registry, many estates. An estate's grants and relationships are enforced on its own chain and
+ *         held in its principals' vaults; a verifier elsewhere can read neither. What the estate anchors here
+ *         is two Merkle roots over BLINDED commitments — the live-grant root (every grant currently live) and
+ *         the membership root (every countersigned relationship credential) — plus the hash of its signed
+ *         charter (spec 410 §9), under a monotonic sequence. A presentation against these roots tells a
+ *         verifier in another estate that a grant is live or an agent is a member in that estate as of that
+ *         sequence, and nothing else (the estate-projection SDK package).
+ *
+ *         WHO MAY WRITE. An estate REGISTERS once: its id — keccak256("eip155:<chainId>:<governance>"), the
+ *         one fact public ground learns about it — bound to the SIGNER its governance controls here (an EOA
+ *         or an account on this chain). First registration wins; the signer rotates only by the current
+ *         signer. `setRoots` is the signer's, with a sequence strictly above the last: a replayed or reordered
+ *         projection is refused. No admin, no pause, no upgrade: public ground has no operator either.
+ *
+ *         WHAT THIS IS NOT: authority. A root proves what the estate vouches for at a moment; whether the
+ *         receiving estate lets an agent ACT is its own mandate, per step (ADR-0056 / ADR-0057).
+ */
+contract EstateProjectionRegistry {
+    struct Roots {
+        bytes32 liveGrantRoot;
+        bytes32 membershipRoot;
+        bytes32 charterHash;
+        uint64 sequence;
+        uint64 anchoredAt;
+    }
+
+    mapping(bytes32 estateId => address signer) public signerOf;
+    mapping(bytes32 estateId => Roots) private _roots;
+
+    event EstateRegistered(bytes32 indexed estateId, address indexed signer);
+    event EstateSignerRotated(bytes32 indexed estateId, address indexed from, address indexed to);
+    event RootsAnchored(bytes32 indexed estateId, uint64 indexed sequence, bytes32 liveGrantRoot, bytes32 membershipRoot, bytes32 charterHash);
+
+    error AlreadyRegistered(bytes32 estateId);
+    error NotRegistered(bytes32 estateId);
+    error NotTheSigner(bytes32 estateId, address caller);
+    error SequenceNotAbove(uint64 last, uint64 given);
+    error ZeroAddress();
+
+    /// @notice Bind an estate id to the signer its governance controls on this chain. First come, once.
+    function register(bytes32 estateId, address signer) external {
+        if (signer == address(0)) revert ZeroAddress();
+        if (signerOf[estateId] != address(0)) revert AlreadyRegistered(estateId);
+        signerOf[estateId] = signer;
+        emit EstateRegistered(estateId, signer);
+    }
+
+    function rotateSigner(bytes32 estateId, address to) external {
+        if (to == address(0)) revert ZeroAddress();
+        address cur = signerOf[estateId];
+        if (cur == address(0)) revert NotRegistered(estateId);
+        if (msg.sender != cur) revert NotTheSigner(estateId, msg.sender);
+        signerOf[estateId] = to;
+        emit EstateSignerRotated(estateId, cur, to);
+    }
+
+    /// @notice Anchor the estate's roots under `sequence` (strictly above the last). Refreshed on every revocation
+    ///         and membership change; a verifier's freshness policy reads `anchoredAt`.
+    function setRoots(bytes32 estateId, bytes32 liveGrantRoot, bytes32 membershipRoot, bytes32 charterHash, uint64 sequence) external {
+        address cur = signerOf[estateId];
+        if (cur == address(0)) revert NotRegistered(estateId);
+        if (msg.sender != cur) revert NotTheSigner(estateId, msg.sender);
+        Roots storage r = _roots[estateId];
+        if (sequence <= r.sequence) revert SequenceNotAbove(r.sequence, sequence);
+        r.liveGrantRoot = liveGrantRoot;
+        r.membershipRoot = membershipRoot;
+        r.charterHash = charterHash;
+        r.sequence = sequence;
+        r.anchoredAt = uint64(block.timestamp);
+        emit RootsAnchored(estateId, sequence, liveGrantRoot, membershipRoot, charterHash);
+    }
+
+    /// @notice The one read a verifier makes: the roots as anchored, with the sequence and when.
+    function roots(bytes32 estateId) external view returns (bytes32 liveGrantRoot, bytes32 membershipRoot, bytes32 charterHash, uint64 sequence, uint64 anchoredAt) {
+        Roots storage r = _roots[estateId];
+        return (r.liveGrantRoot, r.membershipRoot, r.charterHash, r.sequence, r.anchoredAt);
+    }
+
+    /// @notice keccak256("eip155:<chainId>:<governance>") — the same derivation the SDK's `estateIdOf` uses.
+    function estateIdOf(uint256 chainId, address governance) external pure returns (bytes32) {
+        return keccak256(abi.encodePacked("eip155:", _utoa(chainId), ":", _lowerHex(governance)));
+    }
+
+    function _utoa(uint256 v) private pure returns (string memory) {
+        if (v == 0) return "0";
+        uint256 j = v; uint256 len;
+        while (j != 0) { len++; j /= 10; }
+        bytes memory b = new bytes(len);
+        while (v != 0) { len -= 1; b[len] = bytes1(uint8(48 + v % 10)); v /= 10; }
+        return string(b);
+    }
+    function _lowerHex(address a) private pure returns (string memory) {
+        bytes memory alphabet = "0123456789abcdef";
+        bytes memory s = new bytes(42);
+        s[0] = "0"; s[1] = "x";
+        uint160 v = uint160(a);
+        for (uint256 i = 0; i < 20; i++) {
+            uint8 bt = uint8(v >> (8 * (19 - i)));
+            s[2 + i * 2] = alphabet[bt >> 4];
+            s[3 + i * 2] = alphabet[bt & 0x0f];
+        }
+        return string(s);
+    }
+}