@rootzero/contracts 0.9.5 → 0.9.7

package/events/Balance.sol

@@ -3,10 +3,10 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-string constant ABI = "event Balance(bytes32 indexed account, bytes32 asset, bytes32 meta, uint balance, int change, uint access)";
-
 /// @notice Emitted when an account balance changes.
 abstract contract BalanceEvent is EventEmitter {
+    string private constant ABI = "event Balance(bytes32 indexed account, bytes32 asset, bytes32 meta, uint balance, int change, uint access)";
+
     /// @param account Account identifier whose balance changed.
     /// @param asset Asset identifier.
     /// @param meta Asset metadata slot.

package/events/Collateral.sol

@@ -3,11 +3,11 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-string constant ABI = "event Collateral(bytes32 indexed account, bytes32 asset, bytes32 meta, uint amount, uint access)";
-
 /// @notice Emitted when an account's collateral position changes.
 /// Off-chain indexers should query the access command to retrieve the precise collateral details.
 abstract contract CollateralEvent is EventEmitter {
+    string private constant ABI = "event Collateral(bytes32 indexed account, bytes32 asset, bytes32 meta, uint amount, uint access)";
+
     /// @param account Account identifier that holds the collateral.
     /// @param asset Asset identifier of the collateral.
     /// @param meta Asset metadata slot.

package/events/Command.sol

@@ -3,11 +3,11 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-string constant ABI =
-    "event Command(uint indexed host, uint id, string name, bytes32 shape, string request, bytes4 state, bytes4 output, bool acceptsValue)";
-
 /// @notice Emitted once per command during host deployment to publish its request schema and state keys.
 abstract contract CommandEvent is EventEmitter {
+    string private constant ABI =
+        "event Command(uint indexed host, uint id, string name, bytes32 shape, string request, bytes4 state, bytes4 output, bool acceptsValue)";
+
     /// @param host Host node ID that owns this command.
     /// @param id Command node ID.
     /// @param name Human-readable command name.

package/events/Contexts.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+/// @notice Standard context codes for generic asset activity events.
+library Contexts {
+    uint constant Deposit = 1;
+    uint constant Withdraw = 2;
+    uint constant Fee = 3;
+    uint constant Mint = 4;
+    uint constant Burn = 5;
+    uint constant Swap = 6;
+}

package/events/Debt.sol

@@ -3,11 +3,11 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-string constant ABI = "event Debt(bytes32 indexed account, bytes32 asset, bytes32 meta, uint amount, uint mode, uint access)";
-
 /// @notice Emitted when an account's debt position changes.
 /// Off-chain indexers should query the access command to retrieve precise debt details.
 abstract contract DebtEvent is EventEmitter {
+    string private constant ABI = "event Debt(bytes32 indexed account, bytes32 asset, bytes32 meta, uint amount, uint mode, uint access)";
+
     /// @param account Account identifier that holds the debt.
     /// @param asset Asset identifier of the debt.
     /// @param meta Asset metadata slot.

package/events/Guard.sol

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {EventEmitter} from "./Emitter.sol";
+
+/// @notice Emitted once per guard action during host deployment to publish its request schema.
+abstract contract GuardEvent is EventEmitter {
+    string private constant ABI = "event Guard(uint indexed host, uint id, string name, string request)";
+
+    /// @param host Host node ID that owns this guard action.
+    /// @param id Guard action node ID.
+    /// @param name Human-readable guard action name.
+    /// @param request Schema DSL string describing the guard action request shape.
+    event Guard(uint indexed host, uint id, string name, string request);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/events/Guardian.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { EventEmitter } from "./Emitter.sol";
+
+/// @notice Emitted when a guardian account status changes on a host.
+abstract contract GuardianEvent is EventEmitter {
+    string private constant ABI = "event Guardian(uint indexed host, bytes32 account, bool active)";
+
+    /// @param host Host node ID where the guardian change occurred.
+    /// @param account Guardian account ID.
+    /// @param active True if the guardian is enabled, false if revoked.
+    event Guardian(uint indexed host, bytes32 account, bool active);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/events/Introduction.sol

@@ -3,10 +3,10 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-string constant ABI = "event Introduction(uint indexed host, uint blocknum, uint16 version, string namespace)";
-
 /// @notice Emitted when a host introduces itself to another host.
 abstract contract IntroductionEvent is EventEmitter {
+    string private constant ABI = "event Introduction(uint indexed host, uint blocknum, uint16 version, string namespace)";
+
     /// @param host Host node ID of the introducing contract.
     /// @param blocknum Block number at which the host was deployed.
     /// @param version Protocol version the host implements.

package/events/Node.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { EventEmitter } from "./Emitter.sol";
+
+/// @notice Emitted when a node's authorization status changes on a host.
+abstract contract NodeEvent is EventEmitter {
+    string private constant ABI = "event Node(uint indexed host, uint node, bool active)";
+
+    /// @param host Host node ID where the authorization change occurred.
+    /// @param node Node ID that was authorized or revoked.
+    /// @param active True if the node is authorized, false if revoked.
+    event Node(uint indexed host, uint node, bool active);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/events/Peer.sol

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { EventEmitter } from "./Emitter.sol";
-
-string constant ABI =
-    "event Peer(uint indexed host, uint id, string name, bytes32 shape, string request, string response, bool acceptsValue)";
+import {EventEmitter} from "./Emitter.sol";
 
 /// @notice Emitted once per peer during host deployment to publish its request and response schemas.
 abstract contract PeerEvent is EventEmitter {
+    string private constant ABI =
+        "event Peer(uint indexed host, uint id, string name, bytes32 shape, string request, string response, bool acceptsValue)";
+
     /// @param host Host node ID that owns this peer.
     /// @param id Peer node ID.
     /// @param name Human-readable peer name.
@@ -15,12 +15,17 @@ abstract contract PeerEvent is EventEmitter {
     /// @param request Schema DSL string describing the peer request shape.
     /// @param response Schema DSL string describing the peer response shape.
     /// @param acceptsValue Whether the peer entrypoint accepts nonzero `msg.value`.
-    event Peer(uint indexed host, uint id, string name, bytes32 shape, string request, string response, bool acceptsValue);
+    event Peer(
+        uint indexed host,
+        uint id,
+        string name,
+        bytes32 shape,
+        string request,
+        string response,
+        bool acceptsValue
+    );
 
     constructor() {
         emit EventAbi(ABI);
     }
 }
-
-
-

package/events/Position.sol

@@ -3,17 +3,17 @@ pragma solidity ^0.8.33;
 
 import {EventEmitter} from "./Emitter.sol";
 
-string constant ABI = "event AssetPosition(bytes32 indexed account, bytes32 asset, bytes32 meta, uint value, uint queryId)";
-
 /// @notice Emitted when the reported value of an asset-backed position changes or is observed.
 /// A value of 0 should be interpreted as a closed position.
-abstract contract AssetPositionEvent is EventEmitter {
+abstract contract PositionEvent is EventEmitter {
+    string private constant ABI = "event Position(bytes32 indexed account, bytes32 asset, bytes32 meta, uint value, uint queryId)";
+
     /// @param account Account identifier that owns or is associated with the position.
     /// @param asset Asset identifier for the asset class.
     /// @param meta Asset metadata slot carrying the position context.
     /// @param value Context-specific position value; 0 indicates a closed position.
     /// @param queryId Query ID associated with the position lookup or reporting context.
-    event AssetPosition(bytes32 indexed account, bytes32 asset, bytes32 meta, uint value, uint queryId);
+    event Position(bytes32 indexed account, bytes32 asset, bytes32 meta, uint value, uint queryId);
 
     constructor() {
         emit EventAbi(ABI);

package/events/Query.sol

@@ -3,10 +3,10 @@ pragma solidity ^0.8.33;
 
 import {EventEmitter} from "./Emitter.sol";
 
-string constant ABI = "event Query(uint indexed host, uint id, string name, bytes32 shape, string request, string response)";
-
 /// @notice Emitted once per query during host deployment to publish its request and response schemas.
 abstract contract QueryEvent is EventEmitter {
+    string private constant ABI = "event Query(uint indexed host, uint id, string name, bytes32 shape, string request, string response)";
+
     /// @param host Host node ID that owns this query.
     /// @param id Query node ID.
     /// @param name Human-readable query name.

package/events/Received.sol

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { EventEmitter } from "./Emitter.sol";
+
+/// @notice Emitted when an account receives an asset in a protocol operation.
+abstract contract ReceivedEvent is EventEmitter {
+    string private constant ABI = "event Received(bytes32 indexed account, bytes32 asset, bytes32 meta, uint amount, uint context)";
+
+    /// @param account Account identifier that received the asset.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
+    /// @param amount Amount received.
+    /// @param context Operation context identifier associated with this receipt.
+    event Received(bytes32 indexed account, bytes32 asset, bytes32 meta, uint amount, uint context);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/events/Rooted.sol

@@ -3,10 +3,10 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-string constant ABI = "event Rooted(bytes32 indexed account, uint deadline, uint value)";
-
 /// @notice Emitted for root-level protocol actions (e.g. governance or protocol-wide operations).
 abstract contract RootedEvent is EventEmitter {
+    string private constant ABI = "event Rooted(bytes32 indexed account, uint deadline, uint value)";
+
     /// @param account Account identifier associated with the action.
     /// @param deadline Expiry timestamp of the action.
     /// @param value Native value associated with the action.

package/events/Spent.sol

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { EventEmitter } from "./Emitter.sol";
+
+/// @notice Emitted when an account spends an asset in a protocol operation.
+abstract contract SpentEvent is EventEmitter {
+    string private constant ABI = "event Spent(bytes32 indexed account, bytes32 asset, bytes32 meta, uint amount, uint context)";
+
+    /// @param account Account identifier that spent the asset.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
+    /// @param amount Amount spent.
+    /// @param context Operation context identifier associated with this spend.
+    event Spent(bytes32 indexed account, bytes32 asset, bytes32 meta, uint amount, uint context);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/guards/Base.sol

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {AccessControl} from "../core/Access.sol";
+import {GuardEvent} from "../events/Guard.sol";
+import {Ids, Selectors} from "../utils/Ids.sol";
+
+/// @notice ABI-encode a guard action call from a target guard ID and request block stream.
+/// @dev Derives the function selector from `target` via `Ids.guardSelector(target)`.
+/// Reverts if `target` is not a valid guard ID.
+/// @param target Destination guard action node ID embedding the target selector.
+/// @param request Input block stream for the guard invocation.
+/// @return ABI-encoded calldata for the guard action entry point.
+function encodeGuardCall(uint target, bytes calldata request) pure returns (bytes memory) {
+    bytes4 selector = Ids.guardSelector(target);
+    return abi.encodeWithSelector(selector, request);
+}
+
+/// @title GuardBase
+/// @notice Abstract base for guardian-only direct host actions.
+/// Guard actions are non-payable direct calls with no command context, state, or response.
+abstract contract GuardBase is AccessControl, GuardEvent {
+    /// @dev Restrict execution to active guardian addresses.
+    modifier onlyGuardian() {
+        if (!isGuardian(msg.sender)) revert AccessDenied();
+        _;
+    }
+
+    /// @notice Derive the deterministic node ID for a named guard action on this contract.
+    /// @param name Guard action function name (without argument list).
+    /// @return Guard action node ID.
+    function guardId(string memory name) internal view returns (uint) {
+        return Ids.toGuard(Selectors.guard(name), address(this));
+    }
+}

package/guards/Revoke.sol

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {GuardBase} from "./Base.sol";
+import {Cursors, Cur, Schemas} from "../Cursors.sol";
+using Cursors for Cur;
+
+/// @title Revoke
+/// @notice Guardian action that quickly revokes authorization from a list of node IDs.
+/// Each NODE block in the request is deauthorized on the host.
+/// Only callable by active guardian addresses.
+abstract contract Revoke is GuardBase {
+    string private constant NAME = "revoke";
+
+    uint internal immutable revokeId = guardId(NAME);
+
+    constructor() {
+        emit Guard(host, revokeId, NAME, Schemas.Node);
+    }
+
+    function revoke(bytes calldata request) external onlyGuardian {
+        (Cur memory input, ) = cursor(request, 1);
+
+        while (input.i < input.bound) {
+            uint node = input.unpackNode();
+            setNode(node, false);
+        }
+
+        input.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",

package/peer/Pipe.sol

@@ -9,26 +9,26 @@ import {Budget} from "../utils/Value.sol";
 using Cursors for Cur;
 
 /// @title PeerPipePayable
-/// @notice Peer that consumes RELAY blocks and executes each context request as a STEP stream.
-/// Each RELAY block carries a value budget plus a CONTEXT block; the relay target is ignored
-/// and the nested context request is passed to the shared pipeline as the step stream.
+/// @notice Peer that consumes PIPE blocks and executes each context request as a STEP stream.
+/// Each PIPE block carries a value budget plus a CONTEXT block; the nested
+/// context request is passed to the shared pipeline as the step stream.
 abstract contract PeerPipePayable is PeerBase, Pipeline {
     string private constant NAME = "peerPipePayable";
     uint internal immutable peerPipePayableId = peerId(NAME);
 
     constructor() {
-        emit Peer(host, peerPipePayableId, NAME, "1:0", Schemas.Relay, "", true);
+        emit Peer(host, peerPipePayableId, NAME, "1:0", Schemas.Pipe, "", true);
     }
 
-    /// @notice Execute peer-supplied relays through the shared payable pipe.
-    /// @dev Each relay receives its own explicit value sub-budget. Any top-level
-    ///      `msg.value` not assigned to a relay remains on this host.
+    /// @notice Execute peer-supplied pipes through the shared payable pipe.
+    /// @dev Each pipe receives its own explicit value sub-budget. Any top-level
+    ///      `msg.value` not assigned to a pipe remains on this host.
     function peerPipePayable(bytes calldata request) external payable onlyPeer returns (bytes memory) {
         (Cur memory input, ) = cursor(request, 1);
         Budget memory budget = valueBudget();
 
         while (input.i < input.bound) {
-            (, uint value, bytes32 account, bytes calldata state, bytes calldata steps) = input.unpackRelay();
+            (uint value, bytes32 account, bytes calldata state, bytes calldata steps) = input.unpackPipe();
             pipe(account, state, steps, allocateValue(budget, value));
         }
 

package/queries/Assets.sol

@@ -8,38 +8,38 @@ import {QueryBase} from "./Base.sol";
 using Cursors for Cur;
 using Writers for Writer;
 
-abstract contract IsAllowedAssetHook {
-    /// @notice Resolve whether one asset tuple is allowed.
-    /// Concrete implementations define the allowlist policy.
+abstract contract AssetStatusHook {
+    /// @notice Resolve support status for one asset tuple.
+    /// Concrete implementations define the support policy and optional context codes.
     /// @param asset Requested asset identifier.
     /// @param meta Requested asset metadata slot.
-    /// @return allowed Whether the asset tuple is allowed.
-    function isAllowedAsset(bytes32 asset, bytes32 meta) internal view virtual returns (bool allowed);
+    /// @return status Asset support status. Zero means unsupported; nonzero means supported.
+    function assetStatus(bytes32 asset, bytes32 meta) internal view virtual returns (uint status);
 }
 
-/// @title IsAllowedAsset
-/// @notice Rootzero query that checks whether one or more `(asset, meta)` tuples are allowed.
+/// @title AssetStatus
+/// @notice Rootzero query that checks support status for one or more `(asset, meta)` tuples.
 /// The request is a run of `ASSET` blocks.
 /// The response returns one `STATUS` form block per query entry, preserving request order.
-abstract contract IsAllowedAsset is QueryBase, IsAllowedAssetHook {
-    string private constant NAME = "isAllowedAsset";
-    uint public immutable isAllowedAssetId = queryId(NAME);
+abstract contract AssetStatus is QueryBase, AssetStatusHook {
+    string private constant NAME = "assetStatus";
+    uint public immutable assetStatusId = queryId(NAME);
 
     constructor() {
-        emit Query(host, isAllowedAssetId, NAME, "1:1", Schemas.Asset, Forms.Status);
+        emit Query(host, assetStatusId, NAME, "1:1", Schemas.Asset, Forms.Status);
     }
 
-    /// @notice Resolve allowlist status for a run of requested `(asset, meta)` tuples.
+    /// @notice Resolve asset support status for a run of requested `(asset, meta)` tuples.
     /// @param request Block-stream request consisting of `#asset { bytes32 asset, bytes32 meta }` blocks.
-    /// @return Block-stream response containing one `#status { bool ok }` per asset block.
-    function isAllowedAsset(bytes calldata request) external view returns (bytes memory) {
+    /// @return Block-stream response containing one `#status { uint code }` per asset block.
+    function assetStatus(bytes calldata request) external view returns (bytes memory) {
         (Cur memory query, uint groups) = cursor(request, 1);
         Writer memory response = Writers.allocStatuses(groups);
 
         while (query.i < query.bound) {
             (bytes32 asset, bytes32 meta) = query.unpackAsset();
-            bool allowed = isAllowedAsset(asset, meta);
-            response.appendStatus(allowed);
+            uint status = assetStatus(asset, meta);
+            response.appendStatus(status);
         }
 
         query.close();

package/utils/Accounts.sol

@@ -8,8 +8,9 @@ import {isFamily, toLocalBase, toUnspecifiedBase} from "./Utils.sol";
 /// @notice Encoding and decoding helpers for 256-bit account identifiers.
 ///
 /// Account IDs embed a 4-byte type tag in bits [255:224]:
-///   - `Admin` — chain-local EVM address in bits [191:32]
-///   - `User`  — chain-agnostic EVM address in bits [191:32]
+///   - `Admin`    — chain-local EVM address in bits [191:32]
+///   - `Guardian` — chain-local EVM address in bits [191:32]
+///   - `User`     — chain-agnostic EVM address in bits [191:32]
 library Accounts {
     /// @dev Thrown when an account ID does not belong to the EVM family.
     error InvalidAccount();
@@ -18,6 +19,8 @@ library Accounts {
     uint24 constant Family = (uint24(Layout.Evm32) << 8) | uint24(Layout.Account);
     /// @dev Full 4-byte type prefix for admin accounts (chain-local EVM address).
     uint32 constant Admin = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.Admin);
+    /// @dev Full 4-byte type prefix for guardian accounts (chain-local EVM address).
+    uint32 constant Guardian = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.Guardian);
     /// @dev Full 4-byte type prefix for user accounts (chain-agnostic EVM address).
     uint32 constant User = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.User);
     /// @dev Full 4-byte type prefix for keccak accounts (opaque 28-byte hash).
@@ -40,6 +43,11 @@ library Accounts {
         return prefix(account) == Admin;
     }
 
+    /// @notice Return true if `account` is a guardian account.
+    function isGuardian(bytes32 account) internal pure returns (bool) {
+        return prefix(account) == Guardian;
+    }
+
     /// @notice Return true if `account` is a user account.
     function isUser(bytes32 account) internal pure returns (bool) {
         return prefix(account) == User;
@@ -49,6 +57,38 @@ library Accounts {
         return prefix(account) == Keccak;
     }
 
+    /// @notice Assert that `input` is an admin account and return it unchanged.
+    /// @param input Account identifier to validate.
+    /// @return account The same `input` if it is an admin account.
+    function admin(bytes32 input) internal pure returns (bytes32 account) {
+        if (!isAdmin(input)) revert InvalidAccount();
+        return input;
+    }
+
+    /// @notice Assert that `input` is a guardian account and return it unchanged.
+    /// @param input Account identifier to validate.
+    /// @return account The same `input` if it is a guardian account.
+    function guardian(bytes32 input) internal pure returns (bytes32 account) {
+        if (!isGuardian(input)) revert InvalidAccount();
+        return input;
+    }
+
+    /// @notice Assert that `input` is a user account and return it unchanged.
+    /// @param input Account identifier to validate.
+    /// @return account The same `input` if it is a user account.
+    function user(bytes32 input) internal pure returns (bytes32 account) {
+        if (!isUser(input)) revert InvalidAccount();
+        return input;
+    }
+
+    /// @notice Assert that `input` is a keccak account and return it unchanged.
+    /// @param input Account identifier to validate.
+    /// @return account The same `input` if it is a keccak account.
+    function keccak(bytes32 input) internal pure returns (bytes32 account) {
+        if (!isKeccak(input)) revert InvalidAccount();
+        return input;
+    }
+
     /// @notice Encode an EVM address as a chain-local admin account ID.
     /// @param addr EVM address to embed.
     /// @return Admin account ID bound to the current chain.
@@ -56,6 +96,13 @@ library Accounts {
         return bytes32(toLocalBase(Admin) | (uint(uint160(addr)) << 32));
     }
 
+    /// @notice Encode an EVM address as a chain-local guardian account ID.
+    /// @param addr EVM address to embed.
+    /// @return Guardian account ID bound to the current chain.
+    function toGuardian(address addr) internal view returns (bytes32) {
+        return bytes32(toLocalBase(Guardian) | (uint(uint160(addr)) << 32));
+    }
+
     /// @notice Encode an EVM address as a chain-agnostic user account ID.
     /// @param addr EVM address to embed.
     /// @return User account ID without a chain binding.

package/utils/Assets.sol

@@ -17,6 +17,8 @@ import {matchesBase, toLocalBase} from "./Utils.sol";
 library Assets {
     /// @dev Thrown when an asset ID does not match the expected type or chain.
     error InvalidAsset();
+    /// @dev Thrown when an asset is not authorized for the requested operation.
+    error UnauthorizedAsset();
 
     /// @dev Full 4-byte type prefix for the native value asset.
     uint32 constant Value = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Value);