@rootzero/contracts 1.14.0 → 1.16.0

package/core/Host.sol

@@ -1,15 +1,17 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AccessControl} from "./Access.sol";
+import {AccessDenied, CallerAccess, CommanderAccess} from "./Access.sol";
+import {Runtime} from "./Runtime.sol";
+import {Annotate} from "../commands/admin/Annotate.sol";
 import {Appoint} from "../commands/admin/Appoint.sol";
 import {Authorize} from "../commands/admin/Authorize.sol";
 import {Dismiss} from "../commands/admin/Dismiss.sol";
 import {Unauthorize} from "../commands/admin/Unauthorize.sol";
 import {ExecutePayable} from "../commands/admin/Execute.sol";
-import {Label} from "../commands/admin/Label.sol";
 import {Revoke} from "../guards/Revoke.sol";
 import {IntroductionEvent} from "../events/Introduction.sol";
+import {Accounts} from "../utils/Accounts.sol";
 import {Nodes} from "../utils/Nodes.sol";
 
 /// @title IHostIntroduction
@@ -21,6 +23,55 @@ interface IHostIntroduction {
     function introduce(uint peer, uint blocknum) external;
 }
 
+/// @title HostIntroduction
+/// @notice Shared deployment-time introduction behavior for rootzero hosts.
+/// Calls a deployed commander during construction without adding an inbound
+/// introduction endpoint to the inheriting host.
+abstract contract HostIntroduction is Runtime {
+    /// @param cmdr Commander address to introduce this host to when it is a deployed contract.
+    /// @dev Deployment reverts if a contract commander does not accept `introduce(uint,uint)`.
+    constructor(address cmdr) {
+        if (cmdr == address(0) || cmdr == address(this) || cmdr.code.length == 0) return;
+        introduceTo(Nodes.toHost(cmdr));
+    }
+
+    /// @notice Introduce this host to the contract address embedded in a local EVM node ID.
+    /// @dev Accepts host and endpoint IDs such as commands, ports, queries, and guards.
+    /// Reverts when `node` is not local or embeds the zero address.
+    /// @param node Local EVM node ID whose underlying contract receives the introduction.
+    function introduceTo(uint node) internal {
+        IHostIntroduction(Nodes.addr(node)).introduce(host, block.number);
+    }
+}
+
+/// @title CommandHost
+/// @notice Minimal host base for commander-only command execution.
+/// Does not include admin commands, peer authorization, guardians, inbound
+/// introductions, generic execution, or a native-token receive function.
+/// Commands using trusted `NodeCalls` must separately compose a `TrustAccess` policy.
+abstract contract CommandHost is CommanderAccess, CallerAccess, HostIntroduction {
+    /// @dev Thrown when a commander-only host is deployed without an external commander.
+    error InvalidCommander();
+
+    /// @param cmdr Nonzero address allowed to invoke hosted commands.
+    constructor(address cmdr) CommanderAccess(cmdr) HostIntroduction(cmdr) {
+        if (cmdr == address(0)) revert InvalidCommander();
+    }
+
+    function enforceCaller(address caller) internal view virtual override returns (address) {
+        return enforceCommander(caller);
+    }
+
+}
+
+/// @title Admins
+/// @notice Optional bundle of the default host administration commands.
+abstract contract Admins is Annotate, ExecutePayable, Authorize, Unauthorize {}
+
+/// @title Guardians
+/// @notice Optional bundle for guardian management and the default revoke guard.
+abstract contract Guardians is Appoint, Dismiss, Revoke {}
+
 /// @title Host
 /// @notice Abstract base contract for rootzero host implementations.
 /// Inherits admin command support (authorize, unauthorize, label, executePayable),
@@ -28,30 +79,21 @@ interface IHostIntroduction {
 /// optionally introduces itself to a commander host at deployment.
 /// Accepts native ETH payments via the `receive` function.
 abstract contract Host is
-    Authorize,
-    Unauthorize,
-    Revoke,
-    Appoint,
-    Dismiss,
-    Label,
-    ExecutePayable,
+    Admins,
+    Guardians,
+    HostIntroduction,
     IntroductionEvent,
     IHostIntroduction
 {
-    /// @param cmdr Commander address; passed to `AccessControl`.
+    /// @param cmdr Commander address; used by the composed access capabilities.
     ///        If `cmdr` is a deployed contract, the host calls `introduce`
     ///        on it during construction.
-    constructor(address cmdr) AccessControl(cmdr) {
-        if (cmdr == address(0) || cmdr == address(this) || cmdr.code.length == 0) return;
-        introduceTo(Nodes.toHost(cmdr));
-    }
+    constructor(address cmdr) CommanderAccess(cmdr) HostIntroduction(cmdr) {}
 
-    /// @notice Introduce this host to the contract address embedded in a local EVM node ID.
-    /// @dev Accepts host and endpoint IDs such as commands, ports, queries, and guards.
-    /// Reverts when `node` is not local or embeds the zero address.
-    /// @param node Local EVM node ID whose underlying contract receives the introduction.
-    function introduceTo(uint node) internal {
-        IHostIntroduction(Nodes.addr(node)).introduce(host, block.number);
+    /// @notice Assert that `caller` may invoke commands on a peer-aware host.
+    function enforceCaller(address caller) internal view virtual override returns (address) {
+        if (caller == address(0) || !isTrustedCaller(caller)) revert AccessDenied();
+        return caller;
     }
 
     /// @notice Record a host introduction claim.
@@ -59,7 +101,7 @@ abstract contract Host is
     /// @param peer Host node ID being introduced.
     /// @param blocknum Block number at which the host was deployed.
     function introduce(uint peer, uint blocknum) external {
-        emit Introduction(host, Nodes.matchHost(peer, msg.sender), blocknum);
+        emit Introduction(host, Nodes.matchHost(peer, msg.sender), Accounts.toUser(tx.origin), blocknum);
     }
 
     /// @notice Accept native ETH transfers (e.g. from command value flows).

package/core/Pipeline.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {Decoders, Cur, Readers, Reader} from "../Codec.sol";
-import {Settlement} from "./Settlement.sol";
+import {PostHook} from "./Settlement.sol";
 import {Budget, Budgets} from "../execution/Budget.sol";
 
 using Decoders for Cur;
@@ -11,14 +11,14 @@ using Budgets for Budget;
 
 /// @title Pipeline
 /// @notice Core pipeline functionality shared by higher-level surfaces.
-abstract contract Pipeline is Settlement {
+abstract contract Pipeline is PostHook {
     /// @dev Thrown when the pipeline finishes with non-empty threaded state.
     error UnexpectedState();
 
     /// @notice Override to dispatch one piped step.
     /// Called once per STEP block. The returned state becomes the state passed to
     /// the next step, and the final returned state must be empty. Returned
-    /// transactions are decoded and passed individually to `settle` before the next step runs.
+    /// transactions are decoded and passed individually to `post` before the next step runs.
     /// @param cmd Command node ID to invoke or handle.
     /// @param account Account identifier for the piped context.
     /// @param state Current threaded state block stream.
@@ -42,16 +42,16 @@ abstract contract Pipeline is Settlement {
     /// @param steps STEP block stream to execute.
     /// @param budget Mutable native-value budget shared across all steps.
     function pipe(bytes32 account, bytes memory state, bytes calldata steps, Budget memory budget) internal {
-        Cur memory cur = Decoders.open(steps, 1);
+        Cur memory cur = Decoders.open(steps);
 
         while (cur.more()) {
             (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
             Reader memory txs;
-            (state, txs.source) = dispatch(cmd, account, state, input, budget.use(resources));
+            (state, txs.source) = dispatch(cmd, account, state, input, budget.useResourceValue(resources));
 
             while (txs.more()) {
                 (bytes32 from, bytes32 to, bytes32 asset, uint amount) = txs.unpackTransaction();
-                settle(from, to, asset, amount);
+                post(from, to, asset, amount);
             }
         }
 

package/core/Settlement.sol

@@ -21,19 +21,48 @@ abstract contract CreditAccountHook {
     function creditAccount(bytes32 account, bytes32 asset, uint amount) internal virtual;
 }
 
+/// @title PostHook
+/// @notice Hook for posting one transaction between accounts.
+abstract contract PostHook {
+    /// @notice Override to post one transaction.
+    function post(bytes32 from, bytes32 to, bytes32 asset, uint amount) internal virtual;
+}
+
+/// @title SettleHook
+/// @notice Hook for settling one asset-liability position.
+abstract contract SettleHook {
+    /// @notice Override to settle one position for `account`.
+    function settle(
+        bytes32 account,
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal virtual;
+}
+
 /// @title Settlement
-/// @notice Settles decoded transactions through debit and credit account hooks.
-abstract contract Settlement is DebitAccountHook, CreditAccountHook {
-    /// @notice Settle one transaction by debiting its source and crediting its destination.
+/// @notice Default account-hook implementation for transaction posting and position settlement.
+abstract contract Settlement is PostHook, SettleHook, DebitAccountHook, CreditAccountHook {
+    /// @notice Post one transaction by debiting its source and crediting its destination.
     /// Returns without calling either hook when `amount` is zero and skips either
     /// operation when the corresponding account is zero.
-    /// @param from Source account identifier.
-    /// @param to Destination account identifier.
-    /// @param asset Asset identifier.
-    /// @param amount Token amount.
-    function settle(bytes32 from, bytes32 to, bytes32 asset, uint amount) internal {
+    function post(bytes32 from, bytes32 to, bytes32 asset, uint amount) internal virtual override {
         if (amount == 0) return;
         if (from != 0) debitAccount(from, asset, amount);
         if (to != 0) creditAccount(to, asset, amount);
     }
+
+    /// @notice Settle one position by crediting its asset and debiting its liability.
+    /// Skips either operation when its corresponding amount is zero.
+    function settle(
+        bytes32 account,
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal virtual override {
+        if (amount != 0) creditAccount(account, asset, amount);
+        if (debt != 0) debitAccount(account, liability, debt);
+    }
 }

package/core/Types.sol

@@ -59,7 +59,19 @@ struct HostAccountAmount {
     uint amount;
 }
 
-/// @notice Transfer payload used by transaction blocks and peer settlement.
+/// @notice Asset and liability pair threaded as live pipeline state.
+struct Position {
+    /// @dev Identifier for the asset side.
+    bytes32 asset;
+    /// @dev Quantity on the asset side.
+    uint amount;
+    /// @dev Identifier for the liability side.
+    bytes32 liability;
+    /// @dev Quantity owed on the liability side.
+    uint debt;
+}
+
+/// @notice Transfer payload used by transaction blocks and peer posting.
 struct Tx {
     /// @dev Sender account identifier.
     bytes32 from;

package/docs/Schema.md

@@ -27,12 +27,23 @@ For example, the standard `amount` alias uses the key derived from `#amount`
 and the schema body `{ bytes32 asset, uint amount }`. Custom block keys do not
 have to be keccak-derived. They
 are opaque `bytes4` tags and only need to be unique in the context where they are
-used. A host can publish the meaning of a custom key with:
+used. A host can publish the meaning of a custom key as an annotation:
 
 ```solidity
-event Schema(uint indexed host, uint spec, string body, bytes32 name);
+event Annotation(uint indexed entity, bytes data);
+#schema { uint spec, #string as body, bytes32 name }
 ```
 
+Annotation merge behavior is defined by the annotation block type rather than
+by the `Annotation` event. A `#schema` annotation is identified by its entity
+and the block key encoded in `spec`: distinct keys accumulate, while the latest
+trusted claim for the same key replaces the earlier one. Other annotation types
+may define additive, historical, or explicitly revocable behavior instead.
+
+The standard `#action { uint action }` annotation assigns one primary semantic
+action to an entity. The latest trusted value replaces the previous value, and
+`Actions.None` clears the classification.
+
 For example, a host-specific payment block can use a small literal, the command
 selector, or any other chosen `bytes4` value as long as that key is not
 overloaded in the relevant host/schema context.
@@ -150,12 +161,62 @@ with no payload, use a zero-payload block such as `#unit`.
 
 Endpoint descriptors currently use a narrower convention than the full block
 grammar: each state, input, or output lane is a single run of blocks, without
-additional global items. Future protocol surfaces may use the more flexible
-top-level structure.
+additional global items. Endpoint decoder opening requires that run to consume
+the complete supplied lane; a trailing block with another key is invalid.
+Lower-level cursor scanning may still intentionally open only a prefix run.
+Those lower layers retain only the raw block count; descriptor strides are
+applied and lane groups reconciled once when an endpoint execution opens.
+Future protocol surfaces may use the more flexible top-level structure.
+
+For commands, complete-lane validation is also a state-safety rule. State is a
+linear value owned by the current pipeline step, not optional context that a
+command may disregard. Every command must account for the complete supplied
+state by consuming it, transforming and returning it, forwarding it intact, or
+reverting. A command whose descriptor declares an empty state lane must reject
+non-empty state. A command that accepts state must validate the complete stream
+against its declared schema; accepting only a prefix and silently dropping the
+remainder is invalid.
+
+## Live Pipeline State
+
+`#balance`, `#custody`, and `#position` are live state carried between command
+steps for the active account. A position atomically pairs an asset side with a
+liability side:
+
+```txt
+position { bytes32 asset, uint amount, bytes32 liability, uint debt }
+```
+
+The pair is deliberately general. The asset side represents value acquired or
+controlled, and the liability side represents value owed or required. Commands
+may preserve or replace either side and return a new position. The terminal
+`settle` command consumes the pair. Position state is transient protocol state;
+rewriting it does not by itself create, discharge, or replace an obligation
+persisted by a host or external protocol. The responsible command hook must
+perform or verify those effects. A command must not ignore a supplied position:
+it must explicitly consume, transform, forward, or reject it, so neither its
+asset nor its debt can disappear accidentally.
+
+This representation supports ordinary forward transformations as well as
+backward composition. For example, an exact-output route can carry its desired
+asset while successive hops replace the upstream liability:
+
+```txt
+position(C, 100, C, 100)
+→ position(C, 100, B, 50)
+→ position(C, 100, A, 25)
+→ settle
+```
+
+“Backward” describes how requirements are composed from the desired result
+toward the source. Pipeline execution is not reversed: STEP blocks always run
+forward in their encoded order. Exact-output routing is only an example;
+borrowing, refinancing, collateral transformation, callback obligations,
+cross-host claims, fees, and netting can use the same position state.
 
 ## Field Aliases
 
-Block aliases are published in `Schema` events. Field aliases are presentation
+Block aliases are published in `#schema` annotations. Field aliases are presentation
 metadata for tooling. They do not change payload layout or runtime keys.
 
 ```txt
@@ -306,8 +367,8 @@ invalid in any path segment.
 - `#list`: generic list wrapper emitted by `many`
 
 Custom input shapes should define their own context-local block spec and publish
-it with a `Schema` event. Endpoint contracts can use `schema(...)` to construct
-and publish that spec:
+it with a `#schema` annotation. Endpoint contracts can use `schema(...)` to
+construct and publish that spec:
 
 ```solidity
 uint input = schema(1, 64, 64, 64, "{ bytes32 asset, uint amount }", bytes32(0));

package/events/Annotation.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {EventEmitter} from "./Emitter.sol";
+
+/// @notice Emitted to attach encoded annotation blocks to an entity.
+/// @dev `data` is a protocol block stream. A single block is the conventional
+/// case, but related annotations may be emitted together. Annotations are claims
+/// by the emitting contract, and each block key defines its annotation type.
+/// Consumers process events in log order and blocks in stream order, then apply
+/// the identity and merge rules defined by each annotation type. The event does
+/// not impose a universal replacement policy: a type may replace, accumulate,
+/// preserve history, or define its own revocation convention.
+abstract contract AnnotationEvent is EventEmitter {
+    string private constant ABI = "event Annotation(uint indexed entity, bytes data)";
+
+    /// @param entity Entity being annotated.
+    /// @param data Encoded annotation block stream, conventionally containing one block.
+    event Annotation(uint indexed entity, bytes data);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/events/Guardian.sol

@@ -3,12 +3,12 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-/// @notice Emitted when a guardian account status changes on a host.
+/// @notice Emitted when a user account's guardian role changes on a host.
 abstract contract GuardianEvent is EventEmitter {
     string private constant ABI = "event Guardian(uint indexed host, bytes32 account, bool active)";
 
     /// @param host Host node ID where the guardian change occurred.
-    /// @param account Guardian account ID.
+    /// @param account User account ID assigned or removed as a guardian.
     /// @param active True if the guardian is enabled, false if revoked.
     event Guardian(uint indexed host, bytes32 account, bool active);
 

package/events/Introduction.sol

@@ -5,12 +5,13 @@ import { EventEmitter } from "./Emitter.sol";
 
 /// @notice Emitted when a host introduces itself to another host.
 abstract contract IntroductionEvent is EventEmitter {
-    string private constant ABI = "event Introduction(uint indexed host, uint peer, uint blocknum)";
+    string private constant ABI = "event Introduction(uint indexed host, uint peer, bytes32 origin, uint blocknum)";
 
     /// @param host Host node ID receiving the introduction.
     /// @param peer Host node ID of the introducing contract.
+    /// @param origin Transaction-origin address encoded as a chain-agnostic user account.
     /// @param blocknum Block number at which the host was deployed.
-    event Introduction(uint indexed host, uint peer, uint blocknum);
+    event Introduction(uint indexed host, uint peer, bytes32 origin, uint blocknum);
 
     constructor() {
         emit EventAbi(ABI);

package/execution/Budget.sol

@@ -19,15 +19,23 @@ library Budgets {
         budget.remaining = msg.value;
     }
 
+    /// @notice Deduct an exact native value from `budget`.
+    /// @param budget Mutable budget to debit.
+    /// @param value Native value to consume in wei.
+    /// @return The consumed native value.
+    function useValue(Budget memory budget, uint value) internal pure returns (uint) {
+        if (value > budget.remaining) revert InsufficientValue();
+        budget.remaining -= value;
+        return value;
+    }
+
     /// @notice Deduct the EVM value lane of `resources` from `budget`.
     /// @dev EVM resources use the low 128 bits as native value/endowment.
     /// @param budget Mutable budget to debit.
     /// @param resources Packed resources whose low 128 bits contain native value.
     /// @return value Native value to forward in wei.
-    function use(Budget memory budget, uint resources) internal pure returns (uint128 value) {
-        value = uint128(resources);
-        if (value > budget.remaining) revert InsufficientValue();
-        budget.remaining -= value;
+    function useResourceValue(Budget memory budget, uint resources) internal pure returns (uint128) {
+        return uint128(useValue(budget, uint128(resources)));
     }
 
     /// @notice Remove and return all remaining value from `budget`.