@rootzero/contracts 1.15.0 → 1.17.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, HostAsset, 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);
     }
 
@@ -256,6 +287,31 @@ library Executions {
         (value.account, value.asset) = unpackAccountAsset(exec, lane);
     }
 
+    /// @notice Decode and consume one HOST_ASSET block from `lane`.
+    /// @param exec Execution whose decoder is advanced.
+    /// @param lane Decoder lane to consume.
+    /// @return host Decoded host identifier.
+    /// @return asset Decoded asset identifier.
+    function unpackHostAsset(
+        Execution memory exec,
+        uint8 lane
+    ) internal pure returns (uint host, bytes32 asset) {
+        uint abs;
+        (exec.decoders, abs) = exec.decoders.consume(lane, Sizes.HostAsset);
+        (host, asset) = Blocks.unpackHostAsset(abs);
+    }
+
+    /// @notice Decode one HOST_ASSET block into its structured value.
+    /// @param exec Execution whose decoder is advanced.
+    /// @param lane Decoder lane to consume.
+    /// @return value Decoded host and asset.
+    function unpackHostAssetValue(
+        Execution memory exec,
+        uint8 lane
+    ) internal pure returns (HostAsset memory value) {
+        (value.host, value.asset) = unpackHostAsset(exec, lane);
+    }
+
     /// @notice Decode and consume one AMOUNT block from `lane`.
     /// @param exec Execution whose decoder is advanced.
     /// @param lane Decoder lane to consume.
@@ -294,6 +350,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.
@@ -730,6 +804,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.
@@ -739,6 +830,15 @@ library Executions {
         Blocks.writeAccountAsset(exec.output, i, account, asset);
     }
 
+    /// @notice Append a HOST_ASSET block to execution output.
+    /// @param exec Execution receiving the block.
+    /// @param host Host identifier to encode.
+    /// @param asset Asset identifier to encode.
+    function outputHostAsset(Execution memory exec, uint host, bytes32 asset) internal pure {
+        uint i = reserve(exec, Sizes.HostAsset);
+        Blocks.writeHostAsset(exec.output, i, host, asset);
+    }
+
     /// @notice Append an ALLOCATION block to execution output.
     /// @param exec Execution receiving the block.
     /// @param host Host identifier to encode.
@@ -1010,15 +1110,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,7 +1,7 @@
 // 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 {GuardianAccess} from "../core/Access.sol";
 import {Specs} from "../codec/Specs.sol";
 import {Nodes} from "../utils/Nodes.sol";
@@ -10,7 +10,7 @@ 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 GuardianAccess, EndpointBase {
+abstract contract GuardBase is GuardianAccess, InputEndpointBase {
     /// @dev Restrict execution to active guardian addresses.
     modifier onlyGuardian() {
         enforceGuardian(msg.sender);

package/guards/Revoke.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
+import {AllowanceHook} from "../commands/admin/Allowance.sol";
 import {GuardBase} from "./Base.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
@@ -25,6 +26,26 @@ abstract contract Revoke is GuardBase {
             uint node = exec.unpackNode(Lanes.Input);
             setNode(node, false);
         }
+    }
+}
+
+/// @title RevokeAllowance
+/// @notice Guardian action that revokes host-scoped asset allowances.
+/// @dev Opt-in guard. Hosts expose it by inheriting this contract and implementing AllowanceHook.
+abstract contract RevokeAllowance is GuardBase, AllowanceHook {
+    uint private immutable descriptor;
 
+    constructor() {
+        (, descriptor) = guard("revokeAllowance", Specs.HostAsset);
+    }
+
+    /// @notice Revoke every HOST_ASSET allowance in `input` as the active guardian.
+    function revokeAllowance(bytes calldata input) external onlyGuardian {
+        Execution memory exec = openInput(input, descriptor, 0);
+
+        while (exec.more()) {
+            (uint peer, bytes32 asset) = exec.unpackHostAsset(Lanes.Input);
+            allowance(peer, asset, 0);
+        }
     }
 }

package/package.json

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

package/ports/Base.sol

@@ -4,7 +4,7 @@ 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";
@@ -13,7 +13,7 @@ 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, NodeAccess, EndpointBase {
+abstract contract PortBase is NodeCalls, NodeAccess, InputEndpointBase {
 
     /// @dev Restrict execution to trusted callers, excluding the commander.
     modifier onlyPeer() {

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,7 +2,7 @@
 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";
@@ -10,29 +10,29 @@ 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, Action {
+abstract contract PortPost is PortBase, PostHook, Action {
     uint private immutable descriptor;
 
     constructor() {
         uint id;
-        (id, descriptor) = port("portSettle", Specs.Transaction, Specs.Empty, false);
-        action(id, Actions.Settle);
+        (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,7 @@
 // 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";
@@ -11,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

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;
 }

package/utils/Cursors.sol

@@ -12,12 +12,12 @@ struct Cur {
 }
 
 /// @title Cursors
-/// @notice Packed cursor state and navigation for grouped byte regions.
+/// @notice Packed cursor state and navigation for byte regions.
 /// @dev Each 128-bit cursor uses the following layout:
 /// bits   0-31    i
 /// bits  32-63    offset
 /// bits  64-95    len
-/// bits  96-111   groups
+/// bits  96-111   count (opaque consumer metadata)
 /// bits 112-119   flags (consumer-defined)
 /// bits 120-127   tag
 ///
@@ -28,7 +28,7 @@ struct Cur {
 /// cursor into that position while preserving the pair.
 ///
 /// A mark is a standalone cursor value used as an immutable positional
-/// reference. It retains the cursor's offset, length, groups, flags, and tag,
+/// reference. It retains the cursor's offset, length, count, flags, and tag,
 /// but may carry a different `i`. A mark has no intrinsic boundary or movement
 /// semantics; callers may later use its position for comparison, validation,
 /// seeking, or another operation. Because it has the ordinary single-cursor
@@ -41,9 +41,6 @@ library Cursors {
     /// @dev A cursor position exceeds its logical length.
     error OutOfBounds();
 
-    /// @dev Two optional group counts are both set but do not match.
-    error BadRatio();
-
     /// @dev A cursor is not positioned at the expected offset.
     error UnexpectedPosition();
 
@@ -58,14 +55,14 @@ library Cursors {
     /// @notice Create a cursor positioned at its beginning.
     /// @param offset Absolute source or buffer offset.
     /// @param len Logical byte length.
-    /// @param groups Logical group count.
+    /// @param items Opaque item count associated with the region.
     /// @param flags Consumer-defined flags.
     /// @param tag Cursor identity tag.
     /// @return cur Packed cursor.
-    function create(uint offset, uint len, uint groups, uint8 flags, uint8 tag) internal pure returns (uint cur) {
+    function create(uint offset, uint len, uint items, uint8 flags, uint8 tag) internal pure returns (uint cur) {
         cur |= max32(offset) << 32;
         cur |= max32(len) << 64;
-        cur |= max16(groups) << 96;
+        cur |= max16(items) << 96;
         cur |= uint(flags) << 112;
         cur |= uint(tag) << 120;
     }
@@ -113,7 +110,7 @@ library Cursors {
     /// @notice Return the active cursor without its position.
     /// @dev Ignores the upper cursor when `cur` is a pair.
     /// @param cur Packed cursor or cursor pair.
-    /// @return The lower cursor's offset, length, groups, flags, and tag.
+    /// @return The lower cursor's offset, length, count, flags, and tag.
     function frame(uint cur) internal pure returns (uint) {
         return clear32(uint128(cur), 0);
     }
@@ -128,15 +125,20 @@ library Cursors {
 
     /// @notice Decode the consumer metadata and identity tag from the lower cursor.
     /// @param cur Packed cursor or cursor pair.
-    /// @return groups Logical group count.
+    /// @return items Opaque item count.
     /// @return flags Consumer-defined flags.
     /// @return tag Cursor identity tag.
-    function meta(uint cur) internal pure returns (uint groups, uint8 flags, uint8 tag) {
-        groups = uint16(cur >> 96);
+    function meta(uint cur) internal pure returns (uint items, uint8 flags, uint8 tag) {
+        items = uint16(cur >> 96);
         flags = uint8(cur >> 112);
         tag = uint8(cur >> 120);
     }
 
+    /// @notice Return the opaque item count attached to the active cursor.
+    function count(uint cur) internal pure returns (uint) {
+        return uint16(cur >> 96);
+    }
+
     /// @notice Return whether both packed cursors remain at their initial positions.
     /// @param cur Packed cursor or cursor pair.
     /// @return Whether both lane positions are zero.
@@ -233,7 +235,7 @@ library Cursors {
     }
 
     /// @notice Create a child cursor over `[start, end)` within the lower cursor.
-    /// @dev The child starts at position zero, has no groups, and uses the
+    /// @dev The child starts at position zero, has no recorded count, and uses the
     /// supplied tag. Any higher cursor is omitted.
     /// @param cur Parent cursor or cursor pair.
     /// @param start Child start relative to the parent base.
@@ -248,22 +250,6 @@ library Cursors {
 
     // Pairing and selection
 
-    /// @notice Reconcile both packed cursor lanes with an expected group count.
-    /// @dev Zero lanes and lanes with zero groups do not constrain the result.
-    /// @param cur Packed cursor or cursor pair.
-    /// @param expected Expected group count; zero accepts the encoded count.
-    /// @return groups Reconciled effective group count.
-    function reconcile(uint cur, uint expected) internal pure returns (uint groups) {
-        uint low = uint16(cur >> 96);
-        uint high = uint16(cur >> 224);
-        if (low != 0 && high != 0 && low != high) revert BadRatio();
-
-        groups = low != 0 ? low : high;
-        if (groups != 0 && expected != 0 && groups != expected) revert BadRatio();
-        if (groups == 0) groups = expected;
-        max16(groups);
-    }
-
     /// @notice Combine two cursors into one packed word.
     /// @dev Zero represents absence and acts as the identity value.
     /// @param low Cursor placed in the lower lane.

package/events/Position.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 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 PositionEvent is EventEmitter {
-    string private constant ABI = "event Position(bytes32 indexed account, bytes32 asset, uint value, uint32 action, uint context, uint queryId)";
-
-    /// @param account Account identifier that owns or is associated with the position.
-    /// @param asset Asset identifier for the asset class.
-    /// @param value Context-specific position value; 0 indicates a closed position.
-    /// @param action Primary operation hint from `Actions`.
-    /// @param context Reserved context value for future use.
-    /// @param queryId Query ID associated with the position lookup or reporting context.
-    event Position(bytes32 indexed account, bytes32 asset, uint value, uint32 action, uint context, uint queryId);
-
-    constructor() {
-        emit EventAbi(ABI);
-    }
-}