@rootzero/contracts 1.14.0 → 1.16.0

package/commands/Withdraw.sol

@@ -2,6 +2,8 @@
 pragma solidity ^0.8.33;
 
 import {Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
+import {Action} from "../annotations/Action.sol";
+import {Actions} from "../utils/Actions.sol";
 using Executions for Execution;
 
 /// @notice Hook implemented by hosts that withdraw account balances.
@@ -18,11 +20,13 @@ abstract contract WithdrawHook {
 /// @notice Command that delivers BALANCE state blocks to an external destination.
 /// 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 {
+abstract contract Withdraw is CommandBase, WithdrawHook, Action {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("withdraw", Specs.Balance, Specs.Empty, Specs.Empty, 0, false, false);
+        uint id;
+        (id, descriptor) = command("withdraw", Specs.Balance, Specs.Empty, Specs.Empty, 0, false, false);
+        action(id, Actions.Withdraw);
     }
 
     /// @notice Withdraw each BALANCE block from the command state to the command account.
@@ -32,9 +36,9 @@ abstract contract Withdraw is CommandBase, WithdrawHook {
     function withdraw(
         bytes32 account,
         bytes calldata state,
-        bytes calldata
+        bytes calldata input
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openState(state, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackBalance(Lanes.State);

package/commands/admin/AllowAssets.sol

@@ -28,10 +28,10 @@ abstract contract AllowAssets is AdminBase, AllowAssetsHook {
     /// @return Empty transaction stream.
     function allowAssets(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             bytes32 asset = exec.unpackAsset(Lanes.Input);

package/commands/admin/Allowance.sol

@@ -32,10 +32,10 @@ abstract contract Allowance is AdminBase, AllowanceHook {
     /// @return Empty transaction stream.
     function allowance(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             (uint peer, bytes32 asset, uint amount) = exec.unpackAllowance(Lanes.Input);

package/commands/admin/Annotate.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {AdminBase, Execution, Executions, Lanes, Specs} from "./Base.sol";
+using Executions for Execution;
+
+/// @title Annotate
+/// @notice Admin command that attaches encoded annotation block streams to entities.
+/// Each ANNOTATION block in the input emits one `Annotation` event. Only callable
+/// by the admin account.
+abstract contract Annotate is AdminBase {
+    uint private immutable descriptor;
+
+    constructor() {
+        (, descriptor) = command("annotate", Specs.Empty, Specs.Annotation, Specs.Empty, 0, false, true);
+    }
+
+    /// @notice Publish each ANNOTATION block in the admin input.
+    /// @param input ANNOTATION block stream.
+    /// @return Empty output state.
+    /// @return Empty transaction stream.
+    function annotate(
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
+    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
+        Execution memory exec = openCommand(state, input, descriptor, 0);
+
+        while (exec.more()) {
+            (uint entity, bytes calldata data) = exec.unpackAnnotation(Lanes.Input);
+            emit Annotation(entity, data);
+        }
+
+        return close(exec, account);
+    }
+}

package/commands/admin/Appoint.sol

@@ -2,29 +2,30 @@
 pragma solidity ^0.8.33;
 
 import { AdminBase, Execution, Executions, Lanes, Specs } from "./Base.sol";
+import { GuardianAccess } from "../../core/Access.sol";
 using Executions for Execution;
 
 /// @title Appoint
 /// @notice Admin command that grants guardian status to a list of account IDs.
-/// Each ACCOUNT block in the input is enabled as a guardian on the host.
+/// Each USER ACCOUNT block in the input is assigned the guardian role on the host.
 /// Only callable by the admin account.
-abstract contract Appoint is AdminBase {
+abstract contract Appoint is GuardianAccess, AdminBase {
     uint private immutable descriptor;
 
     constructor() {
         (, descriptor) = command("appoint", Specs.Empty, Specs.Account, Specs.Empty, 0, false, true);
     }
 
-    /// @notice Appoint each ACCOUNT block in the admin input as a guardian.
+    /// @notice Appoint each user ACCOUNT block in the admin input as a guardian.
     /// @param input ACCOUNT block stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function appoint(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             bytes32 guardian = exec.unpackAccount(Lanes.Input);

package/commands/admin/Authorize.sol

@@ -27,10 +27,10 @@ abstract contract Authorize is AdminBase {
     /// @return Empty transaction stream.
     function authorize(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             uint node = exec.unpackNode(Lanes.Input);

package/commands/admin/Base.sol

@@ -2,7 +2,14 @@
 pragma solidity ^0.8.33;
 
 import {CommandBase, Execution, Executions, Lanes, Specs} from "../Base.sol";
+import {NodeAccess} from "../../core/Access.sol";
 
 /// @title AdminBase
 /// @notice Shared base for admin commands.
-abstract contract AdminBase is CommandBase {}
+abstract contract AdminBase is NodeAccess, CommandBase {
+    /// @dev Restrict execution to the commander using the host's admin account.
+    modifier onlyAdmin(bytes32 account) {
+        enforceAdmin(account, msg.sender);
+        _;
+    }
+}

package/commands/admin/DenyAssets.sol

@@ -28,10 +28,10 @@ abstract contract DenyAssets is AdminBase, DenyAssetsHook {
     /// @return Empty transaction stream.
     function denyAssets(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             bytes32 asset = exec.unpackAsset(Lanes.Input);

package/commands/admin/Dismiss.sol

@@ -2,29 +2,30 @@
 pragma solidity ^0.8.33;
 
 import { AdminBase, Execution, Executions, Lanes, Specs } from "./Base.sol";
+import { GuardianAccess } from "../../core/Access.sol";
 using Executions for Execution;
 
 /// @title Dismiss
 /// @notice Admin command that revokes guardian status from a list of account IDs.
-/// Each ACCOUNT block in the input is disabled as a guardian on the host.
+/// Each USER ACCOUNT block in the input loses the guardian role on the host.
 /// Only callable by the admin account.
-abstract contract Dismiss is AdminBase {
+abstract contract Dismiss is GuardianAccess, AdminBase {
     uint private immutable descriptor;
 
     constructor() {
         (, descriptor) = command("dismiss", Specs.Empty, Specs.Account, Specs.Empty, 0, false, true);
     }
 
-    /// @notice Dismiss each ACCOUNT block in the admin input from guardian status.
+    /// @notice Dismiss each user ACCOUNT block in the admin input from guardian status.
     /// @param input ACCOUNT block stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function dismiss(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             bytes32 guardian = exec.unpackAccount(Lanes.Input);

package/commands/admin/Execute.sol

@@ -2,6 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {AdminBase, Execution, Executions, Lanes, Specs} from "./Base.sol";
+import {RawNodeCalls} from "../../core/Calls.sol";
 
 using Executions for Execution;
 
@@ -10,7 +11,7 @@ using Executions for Execution;
 /// Each CALL block specifies a target node ID, packed resources, and raw calldata payload.
 /// Only callable by the admin account.
 /// Unspent top-level `msg.value` is returned as a refund transaction.
-abstract contract ExecutePayable is AdminBase {
+abstract contract ExecutePayable is RawNodeCalls, AdminBase {
     uint private immutable descriptor;
 
     constructor() {
@@ -23,14 +24,14 @@ abstract contract ExecutePayable is AdminBase {
     /// @return Remaining native value as a refund transaction stream.
     function executePayable(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external payable onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             (uint target, uint resources, bytes calldata data) = exec.unpackCall(Lanes.Input);
-            rawCall(target, exec.useValue(resources), data);
+            rawCall(target, exec.useResourceValue(resources), data);
         }
 
         return close(exec, account);

package/commands/admin/Unauthorize.sol

@@ -27,10 +27,10 @@ abstract contract Unauthorize is AdminBase {
     /// @return Empty transaction stream.
     function unauthorize(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             uint node = exec.unpackNode(Lanes.Input);

package/core/Access.sol

@@ -8,34 +8,75 @@ import {Accounts} from "../utils/Accounts.sol";
 import {Nodes} from "../utils/Nodes.sol";
 import {addrOr} from "../utils/Utils.sol";
 
-/// @title AccessControl
-/// @notice Host access control layer.
-/// Tracks an immutable trusted commander, the host's own node ID, and a
-/// mapping of externally trusted node IDs. Inbound trust is host-based:
-/// trusted hosts, the commander, and this contract itself may interact
-/// with the host through the guarded command and peer entrypoints.
-abstract contract AccessControl is Runtime, NodeEvent, GuardianEvent {
-    /// @dev Trusted commander address. All calls from this address are implicitly trusted.
-    /// Defaults to `address(this)` when no external commander is provided.
-    address internal immutable commander;
-    /// @dev Admin account ID derived from the commander address at construction time.
-    bytes32 internal immutable admin;
+/// @dev Thrown when a caller, account, or node lacks required access.
+error AccessDenied();
+error CommanderNotAllowed();
 
-    /// @dev Mapping from guardian account ID to guardian status.
-    mapping(bytes32 account => bool) internal guardians;
+/// @title CallerAccess
+/// @notice Authorization capability required by command entrypoints.
+abstract contract CallerAccess is Runtime {
+    /// @notice Assert that `caller` may invoke a command and return it.
+    function enforceCaller(address caller) internal view virtual returns (address);
+}
 
-    /// @dev Mapping from node ID to trust status.
-    mapping(uint node => bool) internal nodes;
+/// @title TrustAccess
+/// @notice Authorization capability required by trusted outbound node calls.
+abstract contract TrustAccess {
+    /// @notice Assert that `node` is trusted and return it.
+    function ensureTrusted(uint node) internal view virtual returns (uint);
+}
 
-    /// @dev Thrown when a caller, account, or node lacks required access.
-    error AccessDenied();
+/// @title CommanderAccess
+/// @notice Minimal commander-based access control shared by host access policies.
+abstract contract CommanderAccess is Runtime {
+    /// @dev Trusted commander address.
+    /// Defaults to `address(this)` when no external commander is provided.
+    address internal immutable commander;
 
     /// @param cmdr Commander address, or zero to make this contract self-managed.
     constructor(address cmdr) {
         commander = addrOr(cmdr, address(this));
+    }
+
+    /// @notice Assert that `caller` is the commander and return it.
+    /// @param caller Address to validate.
+    /// @return The same `caller` value if it is the commander.
+    function enforceCommander(address caller) internal view returns (address) {
+        if (caller == address(0) || caller != commander) {
+            revert AccessDenied();
+        }
+        return caller;
+    }
+
+}
+
+/// @title AdminAccess
+/// @notice Commander access with the admin account derived from the commander.
+abstract contract AdminAccess is CommanderAccess {
+    /// @dev Admin account ID derived from the commander address at construction time.
+    bytes32 internal immutable admin;
+
+    constructor() {
         admin = Accounts.toAdmin(commander);
     }
 
+    /// @notice Assert that `account` is the admin account and `caller` is the commander.
+    function enforceAdmin(bytes32 account, address caller) internal view returns (bytes32) {
+        if (account != admin) revert AccessDenied();
+        enforceCommander(caller);
+        return account;
+    }
+}
+
+/// @title NodeAccess
+/// @notice Admin access extended with externally trusted node IDs.
+/// Inbound trust is host-based:
+/// trusted hosts, the commander, and this contract itself may interact
+/// with the host through the guarded command and peer entrypoints.
+abstract contract NodeAccess is AdminAccess, TrustAccess, NodeEvent {
+    /// @dev Mapping from node ID to trust status.
+    mapping(uint node => bool) internal nodes;
+
     /// @notice Set authorization status for a node.
     /// @param node Node ID to update.
     /// @param active True to authorize the node, false to revoke it.
@@ -44,58 +85,59 @@ abstract contract AccessControl is Runtime, NodeEvent, GuardianEvent {
         emit Node(host, node, active);
     }
 
-    /// @notice Set guardian status for an account.
-    /// @param account Guardian account ID to update.
-    /// @param active True to enable the guardian, false to revoke it.
-    function setGuardian(bytes32 account, bool active) internal {
-        Accounts.guardian(account);
-        guardians[account] = active;
-        emit Guardian(host, account, active);
-    }
-
-    /// @notice Return true if `addr` is an active guardian.
-    /// @param addr EVM address to check as a guardian account.
-    function isGuardian(address addr) internal view returns (bool) {
-        return guardians[Accounts.toGuardian(addr)];
-    }
-
     /// @notice Return true if `caller` is an implicitly trusted address.
     /// Trusted callers: the commander, this contract itself, or any address
     /// whose host ID has been explicitly authorized.
     /// @param caller Address to check.
-    function isTrusted(address caller) internal view returns (bool) {
+    function isTrustedCaller(address caller) internal view returns (bool) {
         return caller == commander || caller == address(this) || nodes[Nodes.toHost(caller)];
     }
 
     /// @notice Assert that `node` is in the trusted set and return it.
     /// @param node Node ID to validate.
     /// @return The same `node` value if trusted.
-    function ensureTrusted(uint node) internal view returns (uint) {
+    function ensureTrusted(uint node) internal view override returns (uint) {
         if (node == 0 || !nodes[node]) {
             revert AccessDenied();
         }
         return node;
     }
 
-    /// @notice Assert that `caller` is trusted and return it.
-    /// Used by command and peer modifiers to gate execution to authorized senders.
-    /// @param caller Address to validate.
-    /// @return The same `caller` value if trusted.
-    function enforceCaller(address caller) internal view returns (address) {
-        if (caller == address(0) || !isTrusted(caller)) {
+    /// @notice Assert that `caller` is a trusted peer other than the commander.
+    function enforcePeer(address caller) internal view returns (address) {
+        if (caller == commander) revert CommanderNotAllowed();
+        if (caller == address(0) || !isTrustedCaller(caller)) {
             revert AccessDenied();
         }
         return caller;
     }
 
-    /// @notice Assert that `caller` is the commander and return it.
-    /// Used by admin modifiers to keep governance authority separate from peer trust.
-    /// @param caller Address to validate.
-    /// @return The same `caller` value if it is the commander.
-    function enforceCommander(address caller) internal view returns (address) {
-        if (caller == address(0) || caller != commander) {
-            revert AccessDenied();
-        }
+}
+
+/// @title GuardianAccess
+/// @notice Node access extended with guardian identity and authorization.
+abstract contract GuardianAccess is NodeAccess, GuardianEvent {
+    /// @dev Mapping from user account ID to guardian status.
+    mapping(bytes32 account => bool) internal guardians;
+
+    /// @notice Set guardian status for an account.
+    /// @param account User account ID whose guardian role is updated.
+    /// @param active True to enable the guardian, false to revoke it.
+    function setGuardian(bytes32 account, bool active) internal {
+        account = Accounts.user(account);
+        guardians[account] = active;
+        emit Guardian(host, account, active);
+    }
+
+    /// @notice Return true if `addr` is an active guardian.
+    /// @param addr EVM address to check for the guardian role.
+    function isGuardian(address addr) internal view returns (bool) {
+        return guardians[Accounts.toUser(addr)];
+    }
+
+    /// @notice Assert that `caller` is an active guardian and return it.
+    function enforceGuardian(address caller) internal view returns (address) {
+        if (caller == address(0) || !isGuardian(caller)) revert AccessDenied();
         return caller;
     }
 }

package/core/Calls.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AccessControl} from "./Access.sol";
+import {TrustAccess} from "./Access.sol";
 import {Nodes} from "../utils/Nodes.sol";
 
 /// @dev Emitted when a trusted inter-node call fails.
@@ -10,9 +10,9 @@ import {Nodes} from "../utils/Nodes.sol";
 /// @param err Revert data returned by the failed call.
 error FailedCall(address addr, bytes4 selector, bytes err);
 
-/// @title NodeCalls
-/// @notice Shared low-level inter-node call helpers for contracts that can talk to other nodes.
-abstract contract NodeCalls is AccessControl {
+/// @title RawNodeCalls
+/// @notice Low-level inter-node call helpers without target authorization.
+abstract contract RawNodeCalls {
     /// @notice Try a raw low-level call to another node and return whether it succeeded.
     /// @param node Node ID of the callee.
     /// @param value Native value to forward in wei.
@@ -23,15 +23,6 @@ abstract contract NodeCalls is AccessControl {
         (success, ) = payable(addr).call{value: value}(data);
     }
 
-    /// @notice Try a trusted low-level call to another node and return whether it succeeded.
-    /// @param node Node ID of the callee.
-    /// @param value Native value to forward in wei.
-    /// @param data Encoded calldata to send.
-    /// @return success True if the low-level call succeeded.
-    function tryTrustedCall(uint node, uint128 value, bytes memory data) internal returns (bool success) {
-        return tryRawCall(ensureTrusted(node), value, data);
-    }
-
     /// @notice Make a raw low-level call to another node and revert when it fails.
     /// @param node Node ID of the callee.
     /// @param value Native value to forward in wei.
@@ -44,15 +35,6 @@ abstract contract NodeCalls is AccessControl {
         if (!success) revert FailedCall(addr, bytes4(data), out);
     }
 
-    /// @notice Make a trusted low-level call to another node and revert when it fails.
-    /// @param node Node ID of the callee.
-    /// @param value Native value to forward in wei.
-    /// @param data Encoded calldata to send.
-    /// @return out Return data from the successful call.
-    function trustedCall(uint node, uint128 value, bytes memory data) internal returns (bytes memory out) {
-        return rawCall(ensureTrusted(node), value, data);
-    }
-
     /// @notice Make a raw low-level read-only query to another node and revert when it fails.
     /// @param node Node ID of the callee.
     /// @param data Encoded calldata to send.
@@ -64,6 +46,29 @@ abstract contract NodeCalls is AccessControl {
         if (!success) revert FailedCall(addr, bytes4(data), out);
     }
 
+}
+
+/// @title NodeCalls
+/// @notice Trusted low-level inter-node calls backed by a host-provided node policy.
+abstract contract NodeCalls is RawNodeCalls, TrustAccess {
+    /// @notice Try a trusted low-level call to another node and return whether it succeeded.
+    /// @param node Node ID of the callee.
+    /// @param value Native value to forward in wei.
+    /// @param data Encoded calldata to send.
+    /// @return success True if the low-level call succeeded.
+    function tryTrustedCall(uint node, uint128 value, bytes memory data) internal returns (bool success) {
+        return tryRawCall(ensureTrusted(node), value, data);
+    }
+
+    /// @notice Make a trusted low-level call to another node and revert when it fails.
+    /// @param node Node ID of the callee.
+    /// @param value Native value to forward in wei.
+    /// @param data Encoded calldata to send.
+    /// @return out Return data from the successful call.
+    function trustedCall(uint node, uint128 value, bytes memory data) internal returns (bytes memory out) {
+        return rawCall(ensureTrusted(node), value, data);
+    }
+
     /// @notice Make a trusted low-level read-only query to another node and revert when it fails.
     /// @param node Node ID of the callee.
     /// @param data Encoded calldata to send.

package/core/Endpoint.sol

@@ -1,57 +1,15 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Specs} from "../codec/Specs.sol";
 import {Execution, Executions} from "../execution/Execution.sol";
 import {EndpointEvent} from "../events/Endpoint.sol";
-import {LabeledEvent} from "../events/Labeled.sol";
-import {SchemaEvent} from "../events/Schema.sol";
+import {Label} from "../annotations/Label.sol";
+import {Schema} from "../annotations/Schema.sol";
 import {Descriptors} from "../codec/Descriptors.sol";
-import {Runtime} from "./Runtime.sol";
 
 /// @title EndpointBase
 /// @notice Shared endpoint metadata helpers.
-abstract contract EndpointBase is Runtime, EndpointEvent, LabeledEvent, SchemaEvent {
-    /// @notice Open an endpoint input stream with an expected batch count.
-    /// @param source Input block stream to open.
-    /// @param descriptor Packed endpoint descriptor.
-    /// @param batches Required batch count, or zero to accept the input count.
-    /// @return exec Execution with its output buffer metadata initialized for the input batch count.
-    function openInput(
-        bytes calldata source,
-        uint descriptor,
-        uint batches
-    ) internal view returns (Execution memory exec) {
-        return Executions.openInput(source, descriptor, batches);
-    }
-
-    /// @notice Finalize an execution output and return its encoded block stream.
-    /// @param exec Completed endpoint execution.
-    /// @return Encoded output block stream.
-    function close(Execution memory exec) internal pure returns (bytes memory) {
-        return Executions.finish(exec);
-    }
-
-    /// @notice Construct and publish a context-local block specification.
-    /// @param key Context-local key value.
-    /// @param min Minimum accepted payload length.
-    /// @param max Maximum accepted payload length; zero means unbounded.
-    /// @param hint Initial per-block payload capacity.
-    /// @param body Schema DSL string describing the block payload body.
-    /// @param name Schema alias name, or zero for unnamed schemas.
-    /// @return spec The context-local block specification.
-    function schema(
-        uint32 key,
-        uint32 min,
-        uint32 max,
-        uint32 hint,
-        string memory body,
-        bytes32 name
-    ) internal returns (uint spec) {
-        spec = Specs.create(bytes4(key), min, max, hint);
-        emit Schema(host, spec, body, name);
-    }
-
+abstract contract EndpointBase is EndpointEvent, Label, Schema {
     /// @notice Create and publish endpoint metadata with a default label.
     /// @param id Endpoint node ID.
     /// @param name Default human-readable endpoint label.
@@ -71,7 +29,39 @@ abstract contract EndpointBase is Runtime, EndpointEvent, LabeledEvent, SchemaEv
         uint8 flags
     ) internal returns (uint descriptor) {
         descriptor = Descriptors.create(state, input, output, transactions, flags);
+        return endpoint(id, name, descriptor);
+    }
+
+    /// @notice Publish already constructed endpoint metadata with a default label.
+    /// @param id Endpoint node ID.
+    /// @param name Default human-readable endpoint label.
+    /// @param descriptor Packed endpoint lane metadata and flags.
+    /// @return The published endpoint descriptor.
+    function endpoint(uint id, string memory name, uint descriptor) internal returns (uint) {
         emit Endpoint(host, id, descriptor);
-        emit Labeled(id, bytes32(0), name);
+        label(id, bytes32(0), name);
+        return descriptor;
+    }
+
+    /// @notice Finalize an execution output and return its encoded block stream.
+    /// @param exec Completed endpoint execution.
+    /// @return Encoded output block stream.
+    function close(Execution memory exec) internal pure returns (bytes memory) {
+        return Executions.finish(exec);
+    }
+}
+
+/// @title InputEndpointBase
+/// @notice Shared input opening for endpoint families that have only an input lane.
+/// Commands intentionally do not inherit this base because they must open state
+/// and input together through `openCommand`.
+abstract contract InputEndpointBase is EndpointBase {
+    /// @notice Open an endpoint input stream with an expected batch count.
+    function openInput(
+        bytes calldata input,
+        uint descriptor,
+        uint batches
+    ) internal view returns (Execution memory exec) {
+        return Executions.openInput(input, descriptor, batches);
     }
 }