@rootzero/contracts 1.9.0 → 1.11.0

package/commands/Relay.sol

@@ -2,38 +2,47 @@
 pragma solidity ^0.8.33;
 
 import {CommandBase, CommandContext, Keys} from "./Base.sol";
+import {Lane} from "../core/Endpoint.sol";
 import {Payable} from "../core/Payable.sol";
-import {RoutePayableHook} from "../core/Portal.sol";
-import {Cursors, Cur, Schemas} from "../Cursors.sol";
+import {Cursors, Cur} from "../Cursors.sol";
 import {Budget} from "../utils/Value.sol";
 
 using Cursors for Cur;
 
+abstract contract RoutePayableHook {
+    /// @notice Override to route an encoded payload through `portal`.
+    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param resources Chain-specific destination resources. EVM adapters
+    /// may interpret this as packed execution gas and destination value.
+    /// @param payload Encoded payload ready for the transport layer.
+    /// @param budget Source native-value budget available for transport
+    /// fees and destination resource funding.
+    function route(uint portal, uint resources, bytes memory payload, Budget memory budget) internal virtual;
+}
+
 /// @title RelayPayable
 /// @notice Command that forwards one RELAY block to a host-defined relay hook.
 /// Reverts unless the request contains exactly one RELAY block, preventing
 /// the same state from being duplicated across multiple relays.
 /// Produces no output state.
 abstract contract RelayPayable is CommandBase, Payable, RoutePayableHook {
-    uint internal immutable relayPayableId = commandId(this.relayPayable.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Command(host, relayPayableId, "1:0:0", Schemas.Relay, Keys.Any, Keys.Empty, true);
-        emit Labeled(relayPayableId, bytes32(0), "relayPayable");
+        (, descriptor) = command("relayPayable", Keys.Any, Keys.Relay, Keys.Empty, 0, true, false);
     }
 
     /// @notice Relay one RELAY request block with the command account and current state.
-    /// @param c Command context; `c.request` must contain exactly one RELAY block.
-    /// @return output Empty output state.
-    function relayPayable(CommandContext calldata c) external payable onlyCommand returns (bytes memory output) {
-        (Cur memory request, ) = Cursors.init(c.request, 1, 1);
-        Budget memory budget = openValue();
+    /// @param c Command context; `c.input` must contain exactly one RELAY block.
+    /// @return Empty output state.
+    function relayPayable(CommandContext calldata c) external payable onlyCommand returns (bytes memory) {
+        (Cur memory input, , ) = openLane(c.input, descriptor, Lane.Input, 1);
+        (uint portal, uint resources, bytes memory context) = input.relayToContext(c.account, c.state);
 
-        (uint portal, uint resources, bytes memory context) = request.relayToContext(c.account, c.state);
+        Budget memory budget = openValue();
         route(portal, resources, context, budget);
 
         closeValue(c.account, budget);
-        request.complete();
         return "";
     }
 }

package/commands/Withdraw.sol

@@ -19,11 +19,10 @@ abstract contract WithdrawHook {
 /// Use `withdraw` for assets being sent outside the protocol (e.g. ERC-20 transfers, ETH sends).
 /// For internal balance credits, use `creditAccount` instead.
 abstract contract Withdraw is CommandBase, WithdrawHook {
-    uint internal immutable withdrawId = commandId(this.withdraw.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Command(host, withdrawId, "0:1:0", "", Keys.Balance, Keys.Empty, false);
-        emit Labeled(withdrawId, bytes32(0), "withdraw");
+        (, descriptor) = command("withdraw", Keys.Balance, Keys.Empty, Keys.Empty, 0, false, false);
     }
 
     /// @notice Withdraw each BALANCE block from the command state to the command account.
@@ -32,14 +31,12 @@ abstract contract Withdraw is CommandBase, WithdrawHook {
     function withdraw(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {
-        (Cur memory state, , ) = Cursors.init(c.state, 1);
+        (Cur memory state, ) = openState(c.state, descriptor);
 
         while (state.i < state.len) {
             (bytes32 asset, uint amount) = state.unpackBalance();
             withdraw(c.account, asset, amount);
         }
-
-        state.complete();
         return "";
     }
 }

package/commands/admin/AllowAssets.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import { AdminBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur, Schemas } from "../../Cursors.sol";
+import { Cursors, Cur } from "../../Cursors.sol";
 using Cursors for Cur;
 
 abstract contract AllowAssetsHook {
@@ -16,27 +16,24 @@ abstract contract AllowAssetsHook {
 /// @notice Admin command that permits a list of assets via a virtual hook.
 /// Each ASSET block in the request calls `allowAsset`. Only callable by the admin account.
 abstract contract AllowAssets is AdminBase, AllowAssetsHook {
-    uint internal immutable allowAssetsId = commandId(this.allowAssets.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Admin(host, allowAssetsId, "1:0:0", Schemas.Asset, Keys.Empty, Keys.Empty, false);
-        emit Labeled(allowAssetsId, bytes32(0), "allowAssets");
+        (, descriptor) = command("allowAssets", Keys.Empty, Keys.Asset, Keys.Empty, 0, false, true);
     }
 
     /// @notice Allow each ASSET block in the admin request.
-    /// @param c Admin command context; `c.request` must contain ASSET blocks.
+    /// @param c Admin command context; `c.input` must contain ASSET blocks.
     /// @return Empty output state.
     function allowAssets(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory input, ) = openInput(c.input, descriptor);
 
-        while (request.i < request.len) {
-            bytes32 asset = request.unpackAsset();
+        while (input.i < input.len) {
+            bytes32 asset = input.unpackAsset();
             allowAsset(asset);
         }
-
-        request.complete();
         return "";
     }
 }

package/commands/admin/Allowance.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {AdminBase, CommandContext, Keys} from "./Base.sol";
-import {Cursors, Cur, Schemas} from "../../Cursors.sol";
+import {Cursors, Cur} from "../../Cursors.sol";
 using Cursors for Cur;
 
 abstract contract AllowanceHook {
@@ -20,25 +20,22 @@ abstract contract AllowanceHook {
 /// @notice Admin command that applies cross-host allowance entries via a virtual hook.
 /// Each ALLOWANCE block grants or updates a host-scoped asset cap. Only callable by the admin account.
 abstract contract Allowance is AdminBase, AllowanceHook {
-    uint internal immutable allowanceId = commandId(this.allowance.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Admin(host, allowanceId, "1:0:0", Schemas.Allowance, Keys.Empty, Keys.Empty, false);
-        emit Labeled(allowanceId, bytes32(0), "allowance");
+        (, descriptor) = command("allowance", Keys.Empty, Keys.Allowance, Keys.Empty, 0, false, true);
     }
 
     /// @notice Apply each ALLOWANCE block in the admin request.
-    /// @param c Admin command context; `c.request` must contain ALLOWANCE blocks.
+    /// @param c Admin command context; `c.input` must contain ALLOWANCE blocks.
     /// @return Empty output state.
     function allowance(CommandContext calldata c) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory input, ) = openInput(c.input, descriptor);
 
-        while (request.i < request.len) {
-            (uint peer, bytes32 asset, uint amount) = request.unpackAllowance();
+        while (input.i < input.len) {
+            (uint peer, bytes32 asset, uint amount) = input.unpackAllowance();
             allowance(peer, asset, amount);
         }
-
-        request.complete();
         return "";
     }
 }

package/commands/admin/Appoint.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import { AdminBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur, Schemas } from "../../Cursors.sol";
+import { Cursors, Cur } from "../../Cursors.sol";
 using Cursors for Cur;
 
 /// @title Appoint
@@ -10,27 +10,24 @@ using Cursors for Cur;
 /// Each ACCOUNT block in the request is enabled as a guardian on the host.
 /// Only callable by the admin account.
 abstract contract Appoint is AdminBase {
-    uint internal immutable appointId = commandId(this.appoint.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Admin(host, appointId, "1:0:0", Schemas.Account, Keys.Empty, Keys.Empty, false);
-        emit Labeled(appointId, bytes32(0), "appoint");
+        (, descriptor) = command("appoint", Keys.Empty, Keys.Account, Keys.Empty, 0, false, true);
     }
 
     /// @notice Appoint each ACCOUNT block in the admin request as a guardian.
-    /// @param c Admin command context; `c.request` must contain ACCOUNT blocks.
+    /// @param c Admin command context; `c.input` must contain ACCOUNT blocks.
     /// @return Empty output state.
     function appoint(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory input, ) = openInput(c.input, descriptor);
 
-        while (request.i < request.len) {
-            bytes32 account = request.unpackAccount();
+        while (input.i < input.len) {
+            bytes32 account = input.unpackAccount();
             setGuardian(account, true);
         }
-
-        request.complete();
         return "";
     }
 }

package/commands/admin/Authorize.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import { AdminBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur, Schemas } from "../../Cursors.sol";
+import { Cursors, Cur } from "../../Cursors.sol";
 using Cursors for Cur;
 
 /// @title Authorize
@@ -10,27 +10,24 @@ using Cursors for Cur;
 /// Each NODE block in the request is authorized on the host.
 /// Only callable by the admin account.
 abstract contract Authorize is AdminBase {
-    uint internal immutable authorizeId = commandId(this.authorize.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Admin(host, authorizeId, "1:0:0", Schemas.Node, Keys.Empty, Keys.Empty, false);
-        emit Labeled(authorizeId, bytes32(0), "authorize");
+        (, descriptor) = command("authorize", Keys.Empty, Keys.Node, Keys.Empty, 0, false, true);
     }
 
     /// @notice Authorize each NODE block in the admin request.
-    /// @param c Admin command context; `c.request` must contain NODE blocks.
+    /// @param c Admin command context; `c.input` must contain NODE blocks.
     /// @return Empty output state.
     function authorize(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory input, ) = openInput(c.input, descriptor);
 
-        while (request.i < request.len) {
-            uint node = request.unpackNode();
+        while (input.i < input.len) {
+            uint node = input.unpackNode();
             setNode(node, true);
         }
-
-        request.complete();
         return "";
     }
 }

package/commands/admin/Base.sol

@@ -2,8 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {CommandBase, CommandContext, Keys} from "../Base.sol";
-import {AdminEvent} from "../../events/Admin.sol";
 
 /// @title AdminBase
 /// @notice Shared base for admin commands.
-abstract contract AdminBase is CommandBase, AdminEvent {}
+abstract contract AdminBase is CommandBase {}

package/commands/admin/DenyAssets.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import { AdminBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur, Schemas } from "../../Cursors.sol";
+import { Cursors, Cur } from "../../Cursors.sol";
 using Cursors for Cur;
 
 abstract contract DenyAssetsHook {
@@ -16,27 +16,24 @@ abstract contract DenyAssetsHook {
 /// @notice Admin command that blocks a list of assets via a virtual hook.
 /// Each ASSET block in the request calls `denyAsset`. Only callable by the admin account.
 abstract contract DenyAssets is AdminBase, DenyAssetsHook {
-    uint internal immutable denyAssetsId = commandId(this.denyAssets.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Admin(host, denyAssetsId, "1:0:0", Schemas.Asset, Keys.Empty, Keys.Empty, false);
-        emit Labeled(denyAssetsId, bytes32(0), "denyAssets");
+        (, descriptor) = command("denyAssets", Keys.Empty, Keys.Asset, Keys.Empty, 0, false, true);
     }
 
     /// @notice Deny each ASSET block in the admin request.
-    /// @param c Admin command context; `c.request` must contain ASSET blocks.
+    /// @param c Admin command context; `c.input` must contain ASSET blocks.
     /// @return Empty output state.
     function denyAssets(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory input, ) = openInput(c.input, descriptor);
 
-        while (request.i < request.len) {
-            bytes32 asset = request.unpackAsset();
+        while (input.i < input.len) {
+            bytes32 asset = input.unpackAsset();
             denyAsset(asset);
         }
-
-        request.complete();
         return "";
     }
 }

package/commands/admin/Dismiss.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import { AdminBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur, Schemas } from "../../Cursors.sol";
+import { Cursors, Cur } from "../../Cursors.sol";
 using Cursors for Cur;
 
 /// @title Dismiss
@@ -10,27 +10,24 @@ using Cursors for Cur;
 /// Each ACCOUNT block in the request is disabled as a guardian on the host.
 /// Only callable by the admin account.
 abstract contract Dismiss is AdminBase {
-    uint internal immutable dismissId = commandId(this.dismiss.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Admin(host, dismissId, "1:0:0", Schemas.Account, Keys.Empty, Keys.Empty, false);
-        emit Labeled(dismissId, bytes32(0), "dismiss");
+        (, descriptor) = command("dismiss", Keys.Empty, Keys.Account, Keys.Empty, 0, false, true);
     }
 
     /// @notice Dismiss each ACCOUNT block in the admin request from guardian status.
-    /// @param c Admin command context; `c.request` must contain ACCOUNT blocks.
+    /// @param c Admin command context; `c.input` must contain ACCOUNT blocks.
     /// @return Empty output state.
     function dismiss(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory input, ) = openInput(c.input, descriptor);
 
-        while (request.i < request.len) {
-            bytes32 account = request.unpackAccount();
+        while (input.i < input.len) {
+            bytes32 account = input.unpackAccount();
             setGuardian(account, false);
         }
-
-        request.complete();
         return "";
     }
 }

package/commands/admin/Execute.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.8.33;
 
 import {AdminBase, CommandContext, Keys} from "./Base.sol";
 import {Payable} from "../../core/Payable.sol";
-import {Cursors, Cur, Schemas} from "../../Cursors.sol";
+import {Cursors, Cur} from "../../Cursors.sol";
 import {Budget} from "../../utils/Value.sol";
 
 using Cursors for Cur;
@@ -14,26 +14,23 @@ using Cursors for Cur;
 /// Only callable by the admin account.
 /// Unspent top-level `msg.value` remains on this host.
 abstract contract ExecutePayable is AdminBase, Payable {
-    uint internal immutable executePayableId = commandId(this.executePayable.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Admin(host, executePayableId, "1:0:0", Schemas.Call, Keys.Empty, Keys.Empty, true);
-        emit Labeled(executePayableId, bytes32(0), "executePayable");
+        (, descriptor) = command("executePayable", Keys.Empty, Keys.Call, Keys.Empty, 0, true, true);
     }
 
     /// @notice Execute each CALL block in the admin request.
-    /// @param c Admin command context; `c.request` must contain CALL blocks.
+    /// @param c Admin command context; `c.input` must contain CALL blocks.
     /// @return Empty output state.
     function executePayable(CommandContext calldata c) external payable onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory input, ) = openInput(c.input, descriptor);
         Budget memory budget = openValue();
 
-        while (request.i < request.len) {
-            (uint target, uint resources, bytes calldata data) = request.unpackCall();
+        while (input.i < input.len) {
+            (uint target, uint resources, bytes calldata data) = input.unpackCall();
             rawCall(target, useValue(budget, resources), data);
         }
-
-        request.complete();
         return "";
     }
 }

package/commands/admin/Label.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {AdminBase, CommandContext, Keys} from "./Base.sol";
-import {Cursors, Cur, Schemas} from "../../Cursors.sol";
+import {Cursors, Cur} from "../../Cursors.sol";
 using Cursors for Cur;
 
 /// @title Label
@@ -10,25 +10,22 @@ using Cursors for Cur;
 /// Each LABEL block in the request emits one `Labeled` event. Only callable by
 /// the admin account.
 abstract contract Label is AdminBase {
-    uint internal immutable labelId = commandId(this.label.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Admin(host, labelId, "1:0:0", Schemas.Label, Keys.Empty, Keys.Empty, false);
-        emit Labeled(labelId, bytes32(0), "label");
+        (, descriptor) = command("label", Keys.Empty, Keys.Label, Keys.Empty, 0, false, true);
     }
 
     /// @notice Publish each LABEL block in the admin request.
-    /// @param c Admin command context; `c.request` must contain LABEL blocks.
+    /// @param c Admin command context; `c.input` must contain LABEL blocks.
     /// @return Empty output state.
     function label(CommandContext calldata c) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory input, ) = openInput(c.input, descriptor);
 
-        while (request.i < request.len) {
-            (uint id, bytes32 namespace, string memory name) = request.unpackLabel();
-            emit Labeled(id, namespace, name);
+        while (input.i < input.len) {
+            (uint node, bytes32 namespace, string memory name) = input.unpackLabel();
+            emit Labeled(node, namespace, name);
         }
-
-        request.complete();
         return "";
     }
 }

package/commands/admin/Unauthorize.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import { AdminBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur, Schemas } from "../../Cursors.sol";
+import { Cursors, Cur } from "../../Cursors.sol";
 using Cursors for Cur;
 
 /// @title Unauthorize
@@ -10,27 +10,24 @@ using Cursors for Cur;
 /// Each NODE block in the request is deauthorized on the host.
 /// Only callable by the admin account.
 abstract contract Unauthorize is AdminBase {
-    uint internal immutable unauthorizeId = commandId(this.unauthorize.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Admin(host, unauthorizeId, "1:0:0", Schemas.Node, Keys.Empty, Keys.Empty, false);
-        emit Labeled(unauthorizeId, bytes32(0), "unauthorize");
+        (, descriptor) = command("unauthorize", Keys.Empty, Keys.Node, Keys.Empty, 0, false, true);
     }
 
     /// @notice Unauthorize each NODE block in the admin request.
-    /// @param c Admin command context; `c.request` must contain NODE blocks.
+    /// @param c Admin command context; `c.input` must contain NODE blocks.
     /// @return Empty output state.
     function unauthorize(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory input, ) = openInput(c.input, descriptor);
 
-        while (request.i < request.len) {
-            uint node = request.unpackNode();
+        while (input.i < input.len) {
+            uint node = input.unpackNode();
             setNode(node, false);
         }
-
-        request.complete();
         return "";
     }
 }

package/core/Endpoint.sol

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Cursors, Cur} from "../Cursors.sol";
+import {Keys} from "../blocks/Keys.sol";
+import {EndpointEvent} from "../events/Endpoint.sol";
+import {LabeledEvent} from "../events/Labeled.sol";
+import {SchemaEvent} from "../events/Schema.sol";
+import {Runtime} from "./Runtime.sol";
+
+/// @title Lane
+/// @notice Bit offsets for endpoint descriptor lanes.
+library Lane {
+    /// @dev Descriptor shift for the state lane.
+    uint internal constant State = 184;
+    /// @dev Descriptor shift for the input lane.
+    uint internal constant Input = 112;
+    /// @dev Descriptor shift for the output lane.
+    uint internal constant Output = 40;
+}
+
+/// @title EndpointBase
+/// @notice Shared endpoint metadata helpers.
+abstract contract EndpointBase is Runtime, EndpointEvent, LabeledEvent, SchemaEvent {
+    /// @dev Pack endpoint lanes and flags into a descriptor.
+    /// A non-empty lane with group 0 defaults to group 1; a zero lane is absent.
+    /// Layout: `[state:8][group:1][input:8][group:1][output:8][group:1]`
+    /// `[flags:1][reserved:4]`. Flag bits: funded = 0, admin = 1.
+    /// @param state Packed state lane plus optional group byte.
+    /// @param input Packed input lane plus optional group byte.
+    /// @param output Packed output lane plus optional group byte.
+    /// @param funded Whether the endpoint accepts nonzero native value.
+    /// @param admin Whether the endpoint is restricted to the admin account.
+    /// @return value Packed endpoint descriptor as an integer.
+    function pack(
+        bytes9 state,
+        bytes9 input,
+        bytes9 output,
+        bool funded,
+        bool admin
+    ) private pure returns (uint value) {
+        value |= uint(uint72(state)) << Lane.State;
+        value |= uint(uint72(input)) << Lane.Input;
+        value |= uint(uint72(output)) << Lane.Output;
+        value |= uint(funded ? 1 : 0) << 32;
+        value |= uint(admin ? 1 : 0) << 33;
+    }
+
+    /// @dev Return a lane's effective group size, defaulting non-empty lanes to one.
+    /// @param descriptor Packed endpoint descriptor.
+    /// @param shift Bit offset of the lane to inspect.
+    /// @return size Effective group size, or zero when the lane is absent.
+    function laneGroup(bytes32 descriptor, uint shift) private pure returns (uint8 size) {
+        uint72 lane = uint72(uint(descriptor) >> shift);
+        if (lane == 0) return 0;
+
+        size = uint8(lane);
+        if (size == 0) size = 1;
+    }
+
+    /// @notice Return an 8-byte lane value for a generic LIST containing `item`.
+    /// @param item Block key expected inside each LIST payload.
+    /// @return Packed lane key `[Keys.List][item]`.
+    function many(bytes4 item) internal pure returns (bytes8) {
+        return bytes8(bytes.concat(Keys.List, item));
+    }
+
+    /// @notice Append an explicit group size to an 8-byte lane value.
+    /// @param value Packed lane key `[key][item]`.
+    /// @param size Explicit per-operation group size for the lane.
+    /// @return Packed lane key plus group byte.
+    function group(bytes8 value, uint8 size) internal pure returns (bytes9) {
+        return bytes9(bytes.concat(value, bytes1(size)));
+    }
+
+    /// @dev Open a descriptor lane and return its effective group and output counts.
+    /// An absent lane inherits `expected`; a present lane must match it when nonzero.
+    /// @param source Block stream to open for the requested lane.
+    /// @param descriptor Packed endpoint descriptor.
+    /// @param shift Bit offset of the lane to open.
+    /// @param expected Required group count, or zero to accept the lane's count.
+    /// @return cur Cursor scoped to the lane's first block run.
+    /// @return groups Number of lane groups in `cur`, or `expected` for an absent lane.
+    /// @return outputs Number of output blocks implied by `groups` and the descriptor output lane.
+    function openLane(
+        bytes calldata source,
+        bytes32 descriptor,
+        uint shift,
+        uint expected
+    ) internal pure returns (Cur memory cur, uint groups, uint outputs) {
+        (cur, groups) = Cursors.init(source, laneGroup(descriptor, shift));
+        if (groups == 0) groups = expected;
+        else if (expected != 0 && groups != expected) revert Cursors.BadRatio();
+        outputs = groups * laneGroup(descriptor, Lane.Output);
+    }
+
+    /// @notice Open an endpoint state stream and return the expected output block count.
+    /// @param source State block stream to open.
+    /// @param descriptor Packed endpoint descriptor.
+    /// @return state Cursor scoped to the state lane's first block run.
+    /// @return outputs Number of output blocks implied by the state group count.
+    function openState(
+        bytes calldata source,
+        bytes32 descriptor
+    ) internal pure returns (Cur memory state, uint outputs) {
+        (state, , outputs) = openLane(source, descriptor, Lane.State, 0);
+    }
+
+    /// @notice Open an endpoint input stream and return the expected output block count.
+    /// @param source Input block stream to open.
+    /// @param descriptor Packed endpoint descriptor.
+    /// @return input Cursor scoped to the input lane's first block run.
+    /// @return outputs Number of output blocks implied by the input group count.
+    function openInput(
+        bytes calldata source,
+        bytes32 descriptor
+    ) internal pure returns (Cur memory input, uint outputs) {
+        (input, , outputs) = openLane(source, descriptor, Lane.Input, 0);
+    }
+
+    /// @notice Publish a block schema and return its key for descriptor construction.
+    /// @param key Block key being defined.
+    /// @param body Schema DSL string describing the block payload body.
+    /// @param name Optional block alias used by descriptor tooling and nested schemas.
+    /// @return The same block key, for inline descriptor construction.
+    function schema(bytes4 key, string memory body, bytes32 name) internal returns (bytes4) {
+        emit Schema(host, key, body, name);
+        return key;
+    }
+
+    /// @notice Create and publish endpoint metadata with a default label.
+    /// @param id Endpoint node ID.
+    /// @param name Default human-readable endpoint label.
+    /// @param state Packed state lane plus optional group byte.
+    /// @param input Packed input lane plus optional group byte.
+    /// @param output Packed output lane plus optional group byte.
+    /// @param funded Whether the endpoint accepts nonzero native value.
+    /// @param admin Whether the endpoint is restricted to the admin account.
+    /// @return descriptor Packed endpoint lane metadata and flags.
+    function endpoint(
+        uint id,
+        string memory name,
+        bytes9 state,
+        bytes9 input,
+        bytes9 output,
+        bool funded,
+        bool admin
+    ) internal returns (bytes32 descriptor) {
+        descriptor = bytes32(pack(state, input, output, funded, admin));
+        emit Endpoint(host, id, descriptor);
+        emit Labeled(id, bytes32(0), name);
+    }
+}