@rootzero/contracts 1.14.0 → 1.16.0

package/execution/Execution.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, Tx} from "../core/Types.sol";
+import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, Position, Tx} from "../core/Types.sol";
 import {Blocks} from "../codec/Blocks.sol";
 import {Buffers} from "../codec/Buffers.sol";
 import {Sizes, Specs} from "../codec/Specs.sol";
@@ -9,6 +9,7 @@ import {Descriptors} from "../codec/Descriptors.sol";
 import {Cursors, Cur} from "../utils/Cursors.sol";
 import {Lanes} from "../utils/Lanes.sol";
 import {Budget} from "./Budget.sol";
+import {max16} from "../utils/Utils.sol";
 
 /// @notice Mutable state shared across one endpoint execution.
 /// @dev `decoders` contains tagged input and state cursor lanes. Cursor operations
@@ -28,6 +29,10 @@ library Executions {
 
     /// @dev Thrown when an execution attempts to spend more value than remains in its budget.
     error InsufficientValue();
+    /// @dev Decoder block counts do not form compatible descriptor groups.
+    error BadRatio();
+    /// @dev A descriptor-empty lane received a non-empty block source.
+    error ZeroStride();
 
     // -------------------------------------------------------------------------
     // Opening
@@ -37,15 +42,39 @@ library Executions {
     /// @param source Calldata source for the decoder lane.
     /// @param descriptor Packed endpoint descriptor.
     /// @param lane Input or state lane identifier.
-    /// @return cur Tagged packed decoder cursor, or zero for an absent lane.
+    /// @return cur Tagged packed decoder cursor carrying its raw block count, or zero for an absent lane.
     function openDecoder(bytes calldata source, uint descriptor, uint8 lane) private pure returns (uint cur) {
         uint stride = Descriptors.stride(descriptor, lane);
         (uint abs, uint limit) = Cursors.bounds(source);
         if (stride == 0 && abs == limit) return 0;
+        if (stride == 0) revert ZeroStride();
 
-        bytes4 key = bytes4(source);
-        (uint groups, uint end) = Blocks.scope(abs, limit, key, stride);
-        cur = Cursors.create(abs, end - abs, groups, 0, lane);
+        bytes4 key = Descriptors.key(descriptor, lane);
+        (uint count, uint end) = Blocks.runExact(abs, limit, key);
+        if (count == 0) revert Blocks.EmptyRun();
+        cur = Cursors.create(abs, end - abs, count, 0, lane);
+    }
+
+    /// @dev Convert one decoder lane's raw block count into descriptor groups.
+    function groupCount(uint decoders, uint descriptor, uint8 lane) private pure returns (uint groups) {
+        uint stride = Descriptors.stride(descriptor, lane);
+        if (stride == 0) return 0;
+
+        uint count = decoders.select(lane).count();
+        if (count % stride != 0) revert BadRatio();
+        groups = count / stride;
+    }
+
+    /// @dev Reconcile decoder lane groups once at endpoint execution opening.
+    function reconcile(uint decoders, uint descriptor, uint expected) private pure returns (uint groups) {
+        uint input = groupCount(decoders, descriptor, Lanes.Input);
+        uint state = groupCount(decoders, descriptor, Lanes.State);
+        if (input != 0 && state != 0 && input != state) revert BadRatio();
+
+        groups = input != 0 ? input : state;
+        if (groups != 0 && expected != 0 && groups != expected) revert BadRatio();
+        if (groups == 0) groups = expected;
+        max16(groups);
     }
 
     /// @dev Initialize one tagged writer cursor from a descriptor lane.
@@ -58,7 +87,9 @@ library Executions {
         (uint capacity, bool growable) = Descriptors.allocation(descriptor, lane, batches);
         if (capacity == 0) return 0;
 
-        cur = Buffers.cursor(capacity + padding, batches, growable, lane);
+        uint count = batches * Descriptors.stride(descriptor, lane);
+        if (padding != 0) count += padding / Sizes.Transaction;
+        cur = Buffers.cursor(capacity + padding, count, growable, lane);
     }
 
     /// @dev Open and pair the input and state decoder cursors.
@@ -91,7 +122,7 @@ library Executions {
     function open(uint decoders, uint descriptor, uint batches) private view returns (Execution memory exec) {
         exec.budget = msg.value;
         exec.decoders = decoders;
-        batches = Cursors.reconcile(decoders, batches);
+        batches = reconcile(decoders, descriptor, batches);
         exec.writers = writerCursors(descriptor, batches);
     }
 
@@ -166,6 +197,14 @@ library Executions {
         exec.decoders = cur.seekAbs(end);
     }
 
+    /// @notice Require the active execution decoder to be at absolute position `abs`.
+    /// @dev The most recent lane-aware decoder operation determines the active lane.
+    /// @param exec Execution whose active decoder position is validated.
+    /// @param abs Expected absolute position.
+    function expectAbs(Execution memory exec, uint abs) internal pure {
+        exec.decoders.expectAbs(abs);
+    }
+
     /// @notice Consume a LIST block and return a cursor scoped to its payload.
     /// @param exec Execution whose decoder is advanced.
     /// @param lane Decoder lane containing the LIST block.
@@ -286,6 +325,24 @@ library Executions {
         (value.asset, value.amount) = unpackBalance(exec, lane);
     }
 
+    /// @notice Decode and consume one POSITION block from `lane`.
+    function unpackPosition(
+        Execution memory exec,
+        uint8 lane
+    ) internal pure returns (bytes32 asset, uint amount, bytes32 liability, uint debt) {
+        uint abs;
+        (exec.decoders, abs) = exec.decoders.consume(lane, Sizes.Position);
+        (asset, amount, liability, debt) = Blocks.unpackPosition(abs);
+    }
+
+    /// @notice Decode one POSITION block into its structured value.
+    function unpackPositionValue(
+        Execution memory exec,
+        uint8 lane
+    ) internal pure returns (Position memory value) {
+        (value.asset, value.amount, value.liability, value.debt) = unpackPosition(exec, lane);
+    }
+
     /// @notice Decode one BALANCE block and associate it with `host`.
     /// @param exec Execution whose decoder is advanced.
     /// @param lane Decoder lane to consume.
@@ -520,6 +577,21 @@ library Executions {
         exec.decoders = cur.seekAbs(end);
     }
 
+    /// @notice Decode and consume one ANNOTATION block from `lane`.
+    /// @param exec Execution whose decoder is advanced.
+    /// @param lane Decoder lane to consume.
+    /// @return entity Decoded entity identifier.
+    /// @return data Decoded annotation block stream.
+    function unpackAnnotation(
+        Execution memory exec,
+        uint8 lane
+    ) internal pure returns (uint entity, bytes calldata data) {
+        uint cur = exec.decoders.select(lane);
+        uint end;
+        (entity, data, end) = Blocks.unpackAnnotation(cur.absolute());
+        exec.decoders = cur.seekAbs(end);
+    }
+
     /// @notice Decode and consume one CONTEXT block from `lane`.
     /// @param exec Execution whose decoder is advanced.
     /// @param lane Decoder lane to consume.
@@ -573,17 +645,16 @@ library Executions {
     /// @notice Decode and consume one LABEL block from `lane`.
     /// @param exec Execution whose decoder is advanced.
     /// @param lane Decoder lane to consume.
-    /// @return id Decoded node identifier.
     /// @return namespace Decoded label namespace.
     /// @return name Decoded label text.
     function unpackLabel(
         Execution memory exec,
         uint8 lane
-    ) internal pure returns (uint id, bytes32 namespace, string memory name) {
+    ) internal pure returns (bytes32 namespace, string memory name) {
         uint cur = exec.decoders.select(lane);
         uint abs = cur.absolute();
         uint end;
-        (id, namespace, name, end) = Blocks.unpackLabel(abs);
+        (namespace, name, end) = Blocks.unpackLabel(abs);
         exec.decoders = cur.seekAbs(end);
     }
 
@@ -708,6 +779,23 @@ library Executions {
         outputBalance(exec, value.asset, value.amount);
     }
 
+    /// @notice Append a POSITION block to execution output.
+    function outputPosition(
+        Execution memory exec,
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal pure {
+        uint i = reserve(exec, Sizes.Position);
+        Blocks.writePosition(exec.output, i, asset, amount, liability, debt);
+    }
+
+    /// @notice Append a structured POSITION value to execution output.
+    function outputPosition(Execution memory exec, Position memory value) internal pure {
+        outputPosition(exec, value.asset, value.amount, value.liability, value.debt);
+    }
+
     /// @notice Append an ACCOUNT_ASSET block to execution output.
     /// @param exec Execution receiving the block.
     /// @param account Account identifier to encode.
@@ -956,13 +1044,12 @@ library Executions {
 
     /// @notice Append a LABEL block to execution output.
     /// @param exec Execution receiving the block.
-    /// @param id Node identifier to encode.
     /// @param namespace Label namespace to encode.
     /// @param name Label text to encode.
-    function outputLabel(Execution memory exec, uint id, bytes32 namespace, string memory name) internal pure {
-        uint size = Sizes.B64 + Sizes.Header + bytes(name).length;
+    function outputLabel(Execution memory exec, bytes32 namespace, string memory name) internal pure {
+        uint size = Sizes.B32 + Sizes.Header + bytes(name).length;
         uint i = reserve(exec, size);
-        Blocks.writeLabel(exec.output, i, id, namespace, name);
+        Blocks.writeLabel(exec.output, i, namespace, name);
     }
 
     /// @notice Append a SCHEMA block to execution output.
@@ -989,15 +1076,23 @@ library Executions {
         exec.budget = 0;
     }
 
+    /// @notice Deduct an exact native value from the execution budget.
+    /// @param exec Mutable execution whose budget is charged.
+    /// @param value Native value to consume in wei.
+    /// @return The consumed native value.
+    function useValue(Execution memory exec, uint value) internal pure returns (uint) {
+        if (value > exec.budget) revert InsufficientValue();
+        exec.budget -= value;
+        return value;
+    }
+
     /// @notice Deduct the EVM value lane of `resources` from the execution budget.
     /// @dev EVM resources use the low 128 bits as native value/endowment.
     /// @param exec Mutable execution whose budget is charged.
     /// @param resources Packed resources whose value lane should be spent.
     /// @return value Native value to forward in wei.
-    function useValue(Execution memory exec, uint resources) internal pure returns (uint128 value) {
-        value = uint128(resources);
-        if (value > exec.budget) revert InsufficientValue();
-        exec.budget -= value;
+    function useResourceValue(Execution memory exec, uint resources) internal pure returns (uint128) {
+        return uint128(useValue(exec, uint128(resources)));
     }
 
     /// @notice Append a deferred transaction to the transaction writer lane.

package/guards/Base.sol

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AccessControl} from "../core/Access.sol";
-import {EndpointBase} from "../core/Endpoint.sol";
+import {InputEndpointBase} from "../core/Endpoint.sol";
+import {GuardianAccess} from "../core/Access.sol";
 import {Specs} from "../codec/Specs.sol";
 import {Nodes} from "../utils/Nodes.sol";
 import {Selectors} from "../utils/Selectors.sol";
@@ -10,10 +10,10 @@ import {Selectors} from "../utils/Selectors.sol";
 /// @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, EndpointBase {
+abstract contract GuardBase is GuardianAccess, InputEndpointBase {
     /// @dev Restrict execution to active guardian addresses.
     modifier onlyGuardian() {
-        if (!isGuardian(msg.sender)) revert AccessDenied();
+        enforceGuardian(msg.sender);
         _;
     }
 

package/package.json

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

package/ports/Base.sol

@@ -2,8 +2,9 @@
 pragma solidity ^0.8.33;
 
 import { NodeCalls } from "../core/Calls.sol";
+import { NodeAccess } from "../core/Access.sol";
 import { Specs } from "../codec/Specs.sol";
-import { EndpointBase } from "../core/Endpoint.sol";
+import { InputEndpointBase } from "../core/Endpoint.sol";
 import { Nodes } from "../utils/Nodes.sol";
 import { Selectors } from "../utils/Selectors.sol";
 import { Descriptors } from "../codec/Descriptors.sol";
@@ -12,14 +13,11 @@ import { Descriptors } from "../codec/Descriptors.sol";
 /// @notice Abstract base for peer-facing rootzero ports.
 /// Ports handle inter-host operations between cooperating hosts.
 /// Access is restricted to trusted peer callers via `onlyPeer`.
-abstract contract PortBase is NodeCalls, EndpointBase {
-    /// @dev Thrown when the commander attempts to call a port entrypoint directly.
-    error CommanderNotAllowed();
+abstract contract PortBase is NodeCalls, NodeAccess, InputEndpointBase {
 
     /// @dev Restrict execution to trusted callers, excluding the commander.
     modifier onlyPeer() {
-        if (msg.sender == commander) revert CommanderNotAllowed();
-        enforceCaller(msg.sender);
+        enforcePeer(msg.sender);
         _;
     }
 
@@ -44,7 +42,21 @@ abstract contract PortBase is NodeCalls, EndpointBase {
         uint output,
         bool funded
     ) internal returns (uint id, uint descriptor) {
+        descriptor = Descriptors.create(Specs.Empty, input, output, 0, funded ? Descriptors.Funded : 0);
+        return port(name, descriptor);
+    }
+
+    /// @notice Publish an already constructed port descriptor and default label.
+    /// @param name Port entrypoint name and default label. It must exactly
+    /// match the Solidity port function name used by the canonical ABI.
+    /// @param descriptor Packed port endpoint descriptor.
+    /// @return id Port node ID.
+    /// @return published Published endpoint descriptor.
+    function port(
+        string memory name,
+        uint descriptor
+    ) internal returns (uint id, uint published) {
         id = Nodes.toPort(Selectors.port(name), address(this));
-        descriptor = endpoint(id, name, Specs.Empty, input, output, 0, funded ? Descriptors.Funded : 0);
+        published = endpoint(id, name, descriptor);
     }
 }

package/ports/Dispatch.sol

@@ -2,23 +2,23 @@
 pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
-import {RoutePayableHook} from "../commands/Relay.sol";
+import {RelayPayableHook} from "../commands/Relay.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
 using Executions for Execution;
 
 /// @title PortDispatchPayable
-/// @notice Port endpoint that forwards DISPATCH blocks to a host-defined route hook.
-abstract contract PortDispatchPayable is PortBase, RoutePayableHook {
+/// @notice Port endpoint that forwards DISPATCH blocks to a host-defined relay hook.
+abstract contract PortDispatchPayable is PortBase, RelayPayableHook {
     uint private immutable descriptor;
 
     constructor() {
         (, descriptor) = port("portDispatchPayable", Specs.Dispatch, Specs.Empty, true);
     }
 
-    /// @notice Forward peer-supplied dispatches to the host-defined route hook.
-    /// @dev Route hooks receive the shared top-level source value
+    /// @notice Forward peer-supplied dispatches to the host-defined relay hook.
+    /// @dev Relay hooks receive the shared top-level source value
     ///      budget. Any `msg.value` not spent by the hook remains on this host.
     /// @param data DISPATCH block stream supplied by the trusted peer.
     /// @return Empty response bytes.
@@ -27,7 +27,7 @@ abstract contract PortDispatchPayable is PortBase, RoutePayableHook {
 
         while (exec.more()) {
             (uint portal, uint resources, bytes calldata payload) = exec.unpackDispatch(Lanes.Input);
-            route(portal, resources, bytes(payload), exec);
+            relayTo(portal, resources, bytes(payload), exec);
         }
         
         return "";

package/ports/{Settle.sol → Post.sol}

@@ -2,33 +2,37 @@
 pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
-import {Settlement} from "../core/Settlement.sol";
+import {PostHook} from "../core/Settlement.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
+import {Action} from "../annotations/Action.sol";
+import {Actions} from "../utils/Actions.sol";
 
 using Executions for Execution;
 
-/// @title PortSettle
-/// @notice Port that consumes peer-supplied TRANSACTION blocks through debit and credit hooks.
+/// @title PortPost
+/// @notice Port that posts peer-supplied TRANSACTION blocks through debit and credit hooks.
 /// Each TRANSACTION block calls `debitAccount` for `from` and `creditAccount` for `to`.
-abstract contract PortSettle is PortBase, Settlement {
+abstract contract PortPost is PortBase, PostHook, Action {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portSettle", Specs.Transaction, Specs.Empty, false);
+        uint id;
+        (id, descriptor) = port("portPost", Specs.Transaction, Specs.Empty, false);
+        action(id, Actions.Post);
     }
 
-    /// @notice Execute the port-settle call.
+    /// @notice Post peer-supplied transactions.
     /// @param data TRANSACTION block stream supplied by the trusted peer.
     /// @return Empty response bytes.
-    function portSettle(bytes calldata data) external onlyPeer returns (bytes memory) {
+    function portPost(bytes calldata data) external onlyPeer returns (bytes memory) {
         Execution memory exec = openInput(data, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 from, bytes32 to, bytes32 asset, uint amount) = exec.unpackTransaction(Lanes.Input);
-            settle(from, to, asset, amount);
+            post(from, to, asset, amount);
         }
-        
+
         return "";
     }
 }

package/queries/Base.sol

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { EndpointBase } from "../core/Endpoint.sol";
+import { InputEndpointBase } from "../core/Endpoint.sol";
+import { Descriptors } from "../codec/Descriptors.sol";
 import { Specs } from "../codec/Specs.sol";
 import { Nodes } from "../utils/Nodes.sol";
 import { Selectors } from "../utils/Selectors.sol";
@@ -10,7 +11,7 @@ import { Selectors } from "../utils/Selectors.sol";
 /// @notice Abstract base for rootzero query contracts.
 /// Queries are view-only entry points that consume a block-stream input and
 /// return a block-stream response.
-abstract contract QueryBase is EndpointBase {
+abstract contract QueryBase is InputEndpointBase {
 
     /// @notice Publish query metadata and a default label.
     /// @param name Query entrypoint name and default label. It must exactly
@@ -24,7 +25,21 @@ abstract contract QueryBase is EndpointBase {
         uint input,
         uint output
     ) internal returns (uint id, uint descriptor) {
+        descriptor = Descriptors.create(Specs.Empty, input, output, 0, 0);
+        return query(name, descriptor);
+    }
+
+    /// @notice Publish an already constructed query descriptor and default label.
+    /// @param name Query entrypoint name and default label. It must exactly
+    /// match the Solidity query function name used by the canonical ABI.
+    /// @param descriptor Packed query endpoint descriptor.
+    /// @return id Query node ID.
+    /// @return published Published endpoint descriptor.
+    function query(
+        string memory name,
+        uint descriptor
+    ) internal returns (uint id, uint published) {
         id = Nodes.toQuery(Selectors.query(name), address(this));
-        descriptor = endpoint(id, name, Specs.Empty, input, output, 0, 0);
+        published = endpoint(id, name, descriptor);
     }
 }

package/utils/Accounts.sol

@@ -10,7 +10,6 @@ import {ensureAddr, isFamily, toLocalBase, toUnspecifiedBase} from "./Utils.sol"
 ///
 /// Account IDs embed a 4-byte type tag in bits [255:224]:
 ///   - `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]
 ///
 /// If the first byte is zero, the account is an opaque
@@ -26,8 +25,6 @@ library Accounts {
     uint24 constant Family = (uint24(Layout.Evm) << 8) | uint24(Layout.Account);
     /// @dev Full 4-byte type prefix for admin accounts (chain-local EVM address).
     uint32 constant Admin = (uint32(Layout.Evm) << 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.Evm) << 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.Evm) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.User);
 
@@ -53,11 +50,6 @@ 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;
@@ -87,14 +79,6 @@ library Accounts {
         return value;
     }
 
-    /// @notice Assert that `value` is a guardian account and return it unchanged.
-    /// @param value Account identifier to validate.
-    /// @return account The same `value` if it is a guardian account.
-    function guardian(bytes32 value) internal pure returns (bytes32 account) {
-        if (!isGuardian(value)) revert InvalidAccount();
-        return value;
-    }
-
     /// @notice Assert that `value` is a user account and return it unchanged.
     /// @param value Account identifier to validate.
     /// @return account The same `value` if it is a user account.
@@ -110,13 +94,6 @@ library Accounts {
         return bytes32(toLocalBase(Admin) | (uint(uint160(account)) << 32));
     }
 
-    /// @notice Encode an EVM address as a chain-local guardian account ID.
-    /// @param account EVM address to embed.
-    /// @return Guardian account ID bound to the current chain.
-    function toGuardian(address account) internal view returns (bytes32) {
-        return bytes32(toLocalBase(Guardian) | (uint(uint160(account)) << 32));
-    }
-
     /// @notice Encode an EVM address as a chain-agnostic user account ID.
     /// @param account EVM address to embed.
     /// @return User account ID without a chain binding.

package/utils/Actions.sol

@@ -17,4 +17,5 @@ library Actions {
     uint32 constant Repay = 11;
     uint32 constant Liquidate = 12;
     uint32 constant Refund = 13;
+    uint32 constant Post = 14;
 }