@rootzero/contracts 1.3.0 → 1.5.0

package/utils/Nodes.sol

@@ -0,0 +1,263 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Layout} from "./Layout.sol";
+import {Ids} from "./Ids.sol";
+import {ensureAddr, isFamily, matchesBase, toLocalBase} from "./Utils.sol";
+
+/// @title Nodes
+/// @notice Encoding and decoding helpers for 256-bit node identifiers.
+///
+/// Node IDs share a common layout:
+///   - bits [255:224] — 4-byte type prefix (`Host`, `Command`, or `Peer`)
+///   - bits [223:192] — current `block.chainid` (makes IDs chain-local)
+///   - bits [191:160] — 4-byte ABI selector (commands and peers only)
+///   - bits [159:0]   — 160-bit EVM contract address
+///
+/// If the first byte is zero, the node is an opaque
+/// `0x00 || bytes31(hash)` ID. The callable target must be resolved by lookup
+/// or witness data before dispatch.
+///
+/// The helpers in this library validate and deconstruct structured node IDs.
+library Nodes {
+    /// @dev Thrown when an ID does not match the expected node type or chain.
+    error InvalidId();
+
+    /// @dev 24-bit family tag shared by all node types (Evm + Node category).
+    uint24 constant Family = (uint24(Layout.Evm) << 8) | uint24(Layout.Node);
+    /// @dev Full 4-byte type prefix for chain/domain nodes.
+    uint32 constant Chain = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Chain);
+    /// @dev Full 4-byte type prefix for host nodes.
+    uint32 constant Host = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Host);
+    /// @dev Full 4-byte type prefix for command nodes.
+    uint32 constant Command = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Command);
+    /// @dev Full 4-byte type prefix for peer nodes.
+    uint32 constant Peer = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Peer);
+    /// @dev Full 4-byte type prefix for query nodes.
+    uint32 constant Query = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Query);
+    /// @dev Full 4-byte type prefix for guard action nodes.
+    uint32 constant Guard = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Guard);
+
+    /// @notice Return true if `node` is a host node ID.
+    function isHost(uint node) internal pure returns (bool) {
+        return uint32(node >> 224) == Host;
+    }
+
+    /// @notice Return true if `node` is a command node ID.
+    function isCommand(uint node) internal pure returns (bool) {
+        return uint32(node >> 224) == Command;
+    }
+
+    /// @notice Return true if `node` is a peer node ID.
+    function isPeer(uint node) internal pure returns (bool) {
+        return uint32(node >> 224) == Peer;
+    }
+
+    /// @notice Return true if `node` is a query node ID.
+    function isQuery(uint node) internal pure returns (bool) {
+        return uint32(node >> 224) == Query;
+    }
+
+    /// @notice Return true if `node` is a guard action node ID.
+    function isGuard(uint node) internal pure returns (bool) {
+        return uint32(node >> 224) == Guard;
+    }
+
+    /// @notice Return true if `node` belongs to the EVM node family.
+    function isEvm(uint node) internal pure returns (bool) {
+        return isFamily(node, Family);
+    }
+
+    /// @notice Return true if `node` is opaque.
+    function isOpaque(uint node) internal pure returns (bool) {
+        return Ids.isOpaque(bytes32(node));
+    }
+
+    /// @notice Return true if `node` belongs to the EVM node family on the current chain.
+    function isLocal(uint node) internal view returns (bool) {
+        return isEvm(node) && uint32(node >> 192) == block.chainid;
+    }
+
+    /// @notice Assert that `value` is a host node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a host node.
+    function host(uint value) internal pure returns (uint node) {
+        if (!isHost(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is a command node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a command node.
+    function command(uint value) internal pure returns (uint node) {
+        if (!isCommand(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is a peer node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a peer node.
+    function peer(uint value) internal pure returns (uint node) {
+        if (!isPeer(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is a query node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a query node.
+    function query(uint value) internal pure returns (uint node) {
+        if (!isQuery(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is a guard action node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a guard action node.
+    function guard(uint value) internal pure returns (uint node) {
+        if (!isGuard(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` belongs to the EVM node family and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is an EVM node.
+    function evm(uint value) internal pure returns (uint node) {
+        if (!isEvm(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is an opaque node and return it unchanged.
+    /// @param value Node ID to validate.
+    /// @return node The same `value` if it is opaque.
+    function opaque(uint value) internal pure returns (uint node) {
+        if (!Ids.isOpaque(bytes32(value))) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` belongs to the EVM node family on the current chain and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is local.
+    function local(uint value) internal view returns (uint node) {
+        if (!isLocal(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `node` is a command ID and return its embedded ABI selector.
+    /// @param node Node ID to validate.
+    /// @return selector 4-byte command selector stored in bits [191:160].
+    function commandSelector(uint node) internal pure returns (bytes4 selector) {
+        return bytes4(uint32(command(node) >> 160));
+    }
+
+    /// @notice Assert that `node` is a peer ID and return its embedded ABI selector.
+    /// @param node Node ID to validate.
+    /// @return selector 4-byte peer selector stored in bits [191:160].
+    function peerSelector(uint node) internal pure returns (bytes4 selector) {
+        return bytes4(uint32(peer(node) >> 160));
+    }
+
+    /// @notice Assert that `node` is a query ID and return its embedded ABI selector.
+    /// @param node Node ID to validate.
+    /// @return selector 4-byte query selector stored in bits [191:160].
+    function querySelector(uint node) internal pure returns (bytes4 selector) {
+        return bytes4(uint32(query(node) >> 160));
+    }
+
+    /// @notice Assert that `node` is a guard action ID and return its embedded ABI selector.
+    /// @param node Node ID to validate.
+    /// @return selector 4-byte guard selector stored in bits [191:160].
+    function guardSelector(uint node) internal pure returns (bytes4 selector) {
+        return bytes4(uint32(guard(node) >> 160));
+    }
+
+    /// @notice Assert that `value` is the host node of `target` on the current chain.
+    /// @param value Value to validate.
+    /// @param target Expected host contract address.
+    /// @return node The same `value` if it matches `target`.
+    function matchHost(uint value, address target) internal view returns (uint node) {
+        if (value != toHost(target)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Build the chain node ID for the current chain.
+    /// @return node Chain node ID with zero selector and `address(0)` payload.
+    function localChain() internal view returns (uint node) {
+        return toLocalBase(Chain);
+    }
+
+    /// @notice Build a chain-local host ID for `target`.
+    /// @param target Host contract address.
+    /// @return node Host node ID on the current chain.
+    function toHost(address target) internal view returns (uint node) {
+        return toLocalBase(Host) | uint(uint160(target));
+    }
+
+    /// @notice Build a chain-local command ID for the given selector and contract.
+    /// @param selector 4-byte ABI selector of the command entry point.
+    /// @param target Command contract address.
+    /// @return node Command node ID embedding both the selector and address.
+    function toCommand(bytes4 selector, address target) internal view returns (uint node) {
+        node = toLocalBase(Command) | uint(uint160(target));
+        node |= uint(uint32(selector)) << 160;
+    }
+
+    /// @notice Build a chain-local peer ID for the given selector and contract.
+    /// @param selector 4-byte ABI selector of the peer entry point.
+    /// @param target Peer contract address.
+    /// @return node Peer node ID embedding both the selector and address.
+    function toPeer(bytes4 selector, address target) internal view returns (uint node) {
+        node = toLocalBase(Peer) | uint(uint160(target));
+        node |= uint(uint32(selector)) << 160;
+    }
+
+    /// @notice Build a chain-local query ID for the given selector and contract.
+    /// @param selector 4-byte ABI selector of the query entry point.
+    /// @param target Query contract address.
+    /// @return node Query node ID embedding both the selector and address.
+    function toQuery(bytes4 selector, address target) internal view returns (uint node) {
+        node = toLocalBase(Query) | uint(uint160(target));
+        node |= uint(uint32(selector)) << 160;
+    }
+
+    /// @notice Build a chain-local guard action ID for the given selector and contract.
+    /// @param selector 4-byte ABI selector of the guard action entry point.
+    /// @param target Guard action contract address.
+    /// @return node Guard action node ID embedding both the selector and address.
+    function toGuard(bytes4 selector, address target) internal view returns (uint node) {
+        node = toLocalBase(Guard) | uint(uint160(target));
+        node |= uint(uint32(selector)) << 160;
+    }
+
+    /// @notice Derive an opaque node ID from a keccak preimage.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return node `0x00 || bytes31(keccak256(preimage))`.
+    function toKeccak(bytes memory preimage) internal pure returns (uint node) {
+        return uint(Ids.toKeccak(preimage));
+    }
+
+    /// @notice Assert that `node` matches the opaque keccak ID for `preimage`.
+    /// @param node Opaque node ID to validate.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return The same `node` value if it matches.
+    function matchKeccak(uint node, bytes memory preimage) internal pure returns (uint) {
+        if (node != uint(Ids.toKeccak(preimage))) revert InvalidId();
+        return node;
+    }
+
+    /// @notice Extract the contract address from any local node ID.
+    /// Reverts if `node` does not belong to the local node family or carries `address(0)`.
+    /// @param node Node ID.
+    /// @return Contract address in the lower 160 bits of `node`.
+    function addr(uint node) internal view returns (address) {
+        return ensureAddr(address(uint160(local(node))));
+    }
+
+    /// @notice Extract the contract address from a local host ID.
+    /// Reverts if `node` does not match the local host base or carries `address(0)`.
+    /// @param node Host node ID.
+    /// @return Host contract address in the lower 160 bits of `node`.
+    function hostAddr(uint node) internal view returns (address) {
+        if (!matchesBase(bytes32(node), toLocalBase(Host))) revert InvalidId();
+        return ensureAddr(address(uint160(node)));
+    }
+}

package/utils/Utils.sol

@@ -8,6 +8,8 @@ uint16 constant MAX_BPS = 10_000;
 error ValueOverflow();
 /// @dev Thrown by `divisible` when `n` is not evenly divisible by `divisor`.
 error NotDivisible();
+/// @dev Thrown when an ID claims to carry an address but the embedded address is zero.
+error ZeroAddress();
 
 /// @notice Assert that `value` fits in uint8 and return it unchanged.
 function max8(uint value) pure returns (uint) {
@@ -92,6 +94,12 @@ function addrOr(address addr, address or) pure returns (address) {
     return addr == address(0) ? or : addr;
 }
 
+/// @notice Assert that `addr` is non-zero and return it unchanged.
+function ensureAddr(address addr) pure returns (address) {
+    if (addr == address(0)) revert ZeroAddress();
+    return addr;
+}
+
 /// @notice Convert a signed integer to its 32-byte two's-complement representation.
 function intToBytes32(int value) pure returns (bytes32) {
     return bytes32(uint(value));
@@ -136,20 +144,12 @@ function retryTicket(bytes32 account, bytes calldata state) pure returns (bytes3
 
 /// @notice Build the chain-local base prefix for a 256-bit ID.
 /// Embeds the current `block.chainid` so IDs are not portable across chains.
-/// @param prefix Four-byte type tag (e.g. `Ids.Host`, `Ids.Command`).
+/// @param prefix Four-byte type tag (e.g. `Nodes.Host`, `Nodes.Command`).
 /// @return Base value with the type tag in bits [255:224] and chainid in bits [223:192].
 function toLocalBase(uint32 prefix) view returns (uint) {
     return (uint(prefix) << 224) | (uint(max32(block.chainid)) << 192);
 }
 
-/// @notice Build the chain-local family prefix for a 256-bit ID.
-/// Uses a 24-bit family tag (the top 3 bytes of the type field).
-/// @param family Three-byte family tag.
-/// @return Family prefix with the family in bits [255:232] and chainid in bits [223:192].
-function toLocalFamily(uint24 family) view returns (uint) {
-    return (uint(family) << 232) | (uint(max32(block.chainid)) << 192);
-}
-
 /// @notice Build a chain-unspecified base prefix (no chainid embedded).
 /// Used for IDs that must be portable across chains (e.g. user accounts).
 /// @param prefix Four-byte type tag.
@@ -167,21 +167,6 @@ function isFamily(uint value, uint24 family) pure returns (bool) {
     return uint24(value >> 232) == family;
 }
 
-/// @notice Check whether `value` was created on the current chain.
-/// @param value ID to test.
-/// @return True if bits [223:192] of `value` equal `block.chainid`.
-function isLocalChain(uint value) view returns (bool) {
-    return uint32(value >> 192) == block.chainid;
-}
-
-/// @notice Check whether `value` belongs to the given family and was created on the current chain.
-/// @param value ID to test.
-/// @param family Expected 24-bit family tag.
-/// @return True if both the family and chainid fields match.
-function isLocalFamily(uint value, uint24 family) view returns (bool) {
-    return isFamily(value, family) && isLocalChain(value);
-}
-
 /// @notice Check whether two IDs share the same 64-bit base (type tag + chainid).
 /// Used to verify that an ID matches a locally-constructed base without comparing
 /// the lower 192-bit payload.

package/events/Chain.sol

@@ -1,19 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {EventEmitter} from "./Emitter.sol";
-
-/// @notice Emitted when a chain/domain node is announced.
-abstract contract ChainEvent is EventEmitter {
-    string private constant ABI = "event Chain(uint indexed chain, bytes32 native, uint commander, bytes32 admin)";
-
-    /// @param chain Chain node ID.
-    /// @param native Native asset ID for the chain.
-    /// @param commander Commander host node ID for the chain.
-    /// @param admin Admin account for the commander host on the chain.
-    event Chain(uint indexed chain, bytes32 native, uint commander, bytes32 admin);
-
-    constructor() {
-        emit EventAbi(ABI);
-    }
-}

package/events/Transfer.sol

@@ -1,22 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import { EventEmitter } from "./Emitter.sol";
-
-/// @notice Emitted when an asset moves from one account to another.
-abstract contract TransferEvent is EventEmitter {
-    string private constant ABI = "event Transfer(bytes32 indexed account, bytes32 to, bytes32 asset, bytes32 meta, uint amount, uint32 action, uint context)";
-
-    /// @param account Source account identifier.
-    /// @param to Destination account identifier.
-    /// @param asset Asset identifier.
-    /// @param meta Asset metadata slot.
-    /// @param amount Amount transferred.
-    /// @param action Primary operation hint from `Actions`.
-    /// @param context Reserved context value for future use.
-    event Transfer(bytes32 indexed account, bytes32 to, bytes32 asset, bytes32 meta, uint amount, uint32 action, uint context);
-
-    constructor() {
-        emit EventAbi(ABI);
-    }
-}

package/peer/BalancePull.sol

@@ -1,49 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {PeerBase} from "./Base.sol";
-import {Cursors, Cur, Schemas} from "../Cursors.sol";
-
-using Cursors for Cur;
-
-interface IPeerBalancePull {
-    function peerBalancePull(bytes calldata request) external returns (bytes memory);
-}
-
-abstract contract BalancePullHook {
-    /// @notice Override to process one incoming balance-based pull request from a peer host.
-    /// @param peer Peer host node ID for this request.
-    /// @param asset Requested asset identifier.
-    /// @param meta Requested asset metadata slot.
-    /// @param amount Requested amount in the asset's native units.
-    function balancePull(uint peer, bytes32 asset, bytes32 meta, uint amount) internal virtual;
-}
-
-/// @title PeerBalancePull
-/// @notice Peer that pulls requested balances from a peer host into this one.
-/// Each BALANCE block in the request calls `balancePull(peer, asset, meta, amount)`.
-/// Restricted to trusted peers.
-abstract contract PeerBalancePull is PeerBase, BalancePullHook, IPeerBalancePull {
-    uint internal immutable peerBalancePullId = peerId(this.peerBalancePull.selector);
-
-    constructor() {
-        emit Peer(host, peerBalancePullId, "1:0", Schemas.Balance, "", false);
-        emit Labeled(peerBalancePullId, bytes32(0), "peerBalancePull");
-    }
-
-    /// @notice Execute the balance-pull peer call.
-    /// @param request BALANCE block stream requested by the trusted peer.
-    /// @return Empty response bytes.
-    function peerBalancePull(bytes calldata request) external onlyPeer returns (bytes memory) {
-        (Cur memory input, , ) = Cursors.init(request, 1);
-        uint peer = caller();
-
-        while (input.i < input.len) {
-            (bytes32 asset, bytes32 meta, uint amount) = input.unpackBalance();
-            balancePull(peer, asset, meta, amount);
-        }
-
-        input.complete();
-        return "";
-    }
-}