@rootzero/contracts 0.9.4 → 0.9.5

package/Core.sol

@@ -7,14 +7,12 @@ pragma solidity ^0.8.33;
 import { AccessControl } from "./core/Access.sol";
 import { Balances } from "./core/Balances.sol";
 import { RootZeroContext } from "./core/Context.sol";
-import { Host } from "./core/Host.sol";
+import { Host, IHostIntroduction } from "./core/Host.sol";
 import { FailedCall, NodeCalls } from "./core/Calls.sol";
 import { Payable } from "./core/Payable.sol";
 import { Pipeline } from "./core/Pipeline.sol";
 import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
-import { HostDiscovery } from "./core/Host.sol";
-import { IHostDiscovery } from "./interfaces/IHostDiscovery.sol";
 
 
 

package/Events.sol

@@ -14,12 +14,11 @@ import { DebtEvent } from "./events/Debt.sol";
 import { DepositEvent } from "./events/Deposit.sol";
 import { AssetPositionEvent } from "./events/Position.sol";
 import { EventEmitter } from "./events/Emitter.sol";
-import { GovernedEvent } from "./events/Governed.sol";
-import { HostAnnouncedEvent } from "./events/Host.sol";
+import { IntroductionEvent } from "./events/Introduction.sol";
 import { ListingEvent } from "./events/Listing.sol";
 import { PeerEvent } from "./events/Peer.sol";
 import { QueryEvent } from "./events/Query.sol";
-import { PipedEvent } from "./events/Piped.sol";
+import { RootedEvent } from "./events/Rooted.sol";
 import { SwapEvent } from "./events/Swap.sol";
 import { WithdrawalEvent } from "./events/Withdraw.sol";
 

package/blocks/Cursors.sol

@@ -524,17 +524,28 @@ library Cursors {
 
     /// @notice Encode a CONTEXT block.
     /// @param account Command account identifier.
-    /// @param value Native value budget assigned to the context.
     /// @param state Embedded state block stream.
     /// @param request Embedded request block stream.
     /// @return Encoded CONTEXT block bytes.
-    function toContextBlock(
-        bytes32 account,
+    function toContextBlock(bytes32 account, bytes memory state, bytes memory request) internal pure returns (bytes memory) {
+        return createBlock(Keys.Context, bytes.concat(account, toBytesBlock(state), toBytesBlock(request)));
+    }
+
+    /// @notice Encode a RELAY block.
+    /// @param target Command target identifier.
+    /// @param value Native value assigned to the relay.
+    /// @param account Command account identifier.
+    /// @param state Embedded state block stream.
+    /// @param request Embedded request block stream.
+    /// @return Encoded RELAY block bytes.
+    function toRelayBlock(
+        uint target,
         uint value,
+        bytes32 account,
         bytes memory state,
         bytes memory request
     ) internal pure returns (bytes memory) {
-        return createBlock(Keys.Context, bytes.concat(account, bytes32(value), toBytesBlock(state), toBytesBlock(request)));
+        return createBlock(Keys.Relay, bytes.concat(bytes32(target), bytes32(value), toContextBlock(account, state, request)));
     }
 
     // -------------------------------------------------------------------------
@@ -1091,20 +1102,33 @@ library Cursors {
     /// The `state` and `request` slices are the raw payloads of the required BYTES children.
     /// @param cur Cursor; advanced past the block.
     /// @return account Command account identifier.
-    /// @return value Native value budget assigned to the context.
     /// @return state Embedded state block stream.
     /// @return request Embedded request block stream.
-    function unpackContext(
-        Cur memory cur
-    ) internal pure returns (bytes32 account, uint value, bytes calldata state, bytes calldata request) {
-        uint end = cur.enter(Keys.Context, 64 + 2 * Sizes.Header, 0);
+    function unpackContext(Cur memory cur) internal pure returns (bytes32 account, bytes calldata state, bytes calldata request) {
+        uint end = cur.enter(Keys.Context, 32 + 2 * Sizes.Header, 0);
         account = cur.read32();
-        value = uint(cur.read32());
         state = cur.unpackBytes();
         request = cur.unpackBytes();
         cur.exit(end);
     }
 
+    /// @notice Consume a RELAY block and return its target, value, and context fields.
+    /// @param cur Cursor; advanced past the block.
+    /// @return target Destination command/node ID.
+    /// @return value Native value assigned to the relay.
+    /// @return account Command account identifier.
+    /// @return state Embedded state block stream.
+    /// @return request Embedded request block stream.
+    function unpackRelay(
+        Cur memory cur
+    ) internal pure returns (uint target, uint value, bytes32 account, bytes calldata state, bytes calldata request) {
+        uint end = cur.enter(Keys.Relay, 64 + Sizes.Header + 32 + 2 * Sizes.Header, 0);
+        target = uint(cur.read32());
+        value = uint(cur.read32());
+        (account, state, request) = cur.unpackContext();
+        cur.exit(end);
+    }
+
     // Type-specific validators
 
     /// @notice Validate an AUTH block at position `i` and extract deadline and proof.

package/blocks/Keys.sol

@@ -43,6 +43,8 @@ library Keys {
     bytes4 constant Call = bytes4(keccak256("#call"));
     /// @dev Command context transport - (bytes32 account, #bytes as state, #bytes as request)
     bytes4 constant Context = bytes4(keccak256("#context"));
+    /// @dev Pipeline relay - (uint target, uint value, #context)
+    bytes4 constant Relay = bytes4(keccak256("#relay"));
     /// @dev Authentication proof - (uint cid, uint deadline, #bytes as proof); must appear last in its segment
     bytes4 constant Auth = bytes4(keccak256("#auth"));
     /// @dev Asset descriptor without amount - (bytes32 asset, bytes32 meta)

package/blocks/Schema.sol

@@ -59,9 +59,10 @@ library Schemas {
     string constant Allocation = "#allocation { uint host, bytes32 asset, bytes32 meta, uint amount }";
     string constant Allowance = "#allowance { uint host, bytes32 asset, bytes32 meta, uint amount }";
     string constant Transaction = "#transaction { bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount }";
+    string constant Context = "#context { bytes32 account, #bytes as state, #bytes as request }";
+    string constant Relay = "#relay { uint target, uint value, #context { bytes32 account, #bytes as state, #bytes as request } }";
     string constant Call = "#call { uint target, uint value, #bytes as payload }";
     string constant Step = "#step { uint target, uint value, #bytes as request }";
-    string constant Context = "#context { bytes32 account, uint value, #bytes as state, #bytes as request }";
     string constant Bounty = "#bounty { uint amount, bytes32 relayer }";
     string constant Fee = "#fee { uint amount }";
     string constant Auth = "#auth { uint cid, uint deadline, #bytes as proof }";
@@ -81,7 +82,8 @@ library Forms {
     string constant AccountAmount = "#accountAmount { bytes32 account, bytes32 asset, bytes32 meta, uint amount }";
     string constant HostAmount = "#hostAmount { uint host, bytes32 asset, bytes32 meta, uint amount }";
     string constant HostAccountAsset = "#hostAccountAsset { uint host, bytes32 account, bytes32 asset, bytes32 meta }";
-    string constant HostAccountAmount = "#hostAccountAmount { uint host, bytes32 account, bytes32 asset, bytes32 meta, uint amount }";
+    string constant HostAccountAmount =
+        "#hostAccountAmount { uint host, bytes32 account, bytes32 asset, bytes32 meta, uint amount }";
 }
 
 /// @title Sizes

package/blocks/Writers.sol

@@ -27,6 +27,7 @@ library Hints {
     uint constant Step = 256;
     uint constant Call = 256;
     uint constant Context = 512;
+    uint constant Relay = 640;
 }
 
 /// @title Writers
@@ -223,6 +224,14 @@ library Writers {
         return allocFromHint(count, Hints.Context);
     }
 
+    /// @notice Allocate a writer for `count` RELAY blocks using a per-block capacity hint.
+    /// @dev The backing buffer expands automatically if encoded relays exceed the initial hint.
+    /// @param count Number of relay blocks to allocate space for.
+    /// @return writer Allocated growable writer.
+    function allocRelays(uint count) internal pure returns (Writer memory writer) {
+        return allocFromHint(count, Hints.Relay);
+    }
+
     // -------------------------------------------------------------------------
     // Fixed-width write helpers
     // -------------------------------------------------------------------------
@@ -871,20 +880,42 @@ library Writers {
         appendBlock64Bytes(writer, Keys.Call, bytes32(target), bytes32(value), data);
     }
 
-    /// @notice Append a CONTEXT block with a value budget and nested state/request BYTES payloads.
+    /// @notice Append a CONTEXT block with nested state/request BYTES payloads.
     /// @param writer Destination writer; `i` is advanced by the encoded CONTEXT block length.
     /// @param account Command account identifier.
-    /// @param value Native value budget assigned to the context.
     /// @param state Raw nested state payload.
     /// @param request Raw nested request payload.
-    function appendContext(
+    function appendContext(Writer memory writer, bytes32 account, bytes memory state, bytes memory request) internal pure {
+        appendBlock32BytesBytes(writer, Keys.Context, account, state, request);
+    }
+
+    /// @notice Append a RELAY block with a nested CONTEXT block.
+    /// @param writer Destination writer; `i` is advanced by the encoded RELAY block length.
+    /// @param target Command target identifier.
+    /// @param value Native value assigned to the relay.
+    /// @param account Command account identifier.
+    /// @param state Raw nested state payload.
+    /// @param request Raw nested request payload.
+    function appendRelay(
         Writer memory writer,
-        bytes32 account,
+        uint target,
         uint value,
+        bytes32 account,
         bytes memory state,
         bytes memory request
     ) internal pure {
-        appendBlock64BytesBytes(writer, Keys.Context, account, bytes32(value), state, request);
+        uint i = writer.i;
+        uint len = 96 + 3 * Sizes.Header + state.length + request.length;
+        uint next = i + Sizes.Header + len;
+        i = reserve(writer, next, next);
+
+        uint p = writeHeader(writer.dst, i, Keys.Relay, uint32(max32(len)));
+        assembly ("memory-safe") {
+            mstore(add(p, 0x08), target)
+            mstore(add(p, 0x28), value)
+        }
+
+        writeBlock32BytesBytes(writer.dst, i + Sizes.Header + 64, Keys.Context, account, state, request);
     }
 
     /// @notice Append a STATUS form block.

package/core/Calls.sol

@@ -72,13 +72,13 @@ abstract contract NodeCalls is AccessControl {
     }
 
     /// @notice Encode and call a trusted command node.
-    /// @param ctx Command execution context.
-    /// @param cid Command node ID embedding the target selector.
+    /// @param id Command node ID embedding the target selector.
     /// @param value Native value to forward in wei.
+    /// @param ctx Command execution context.
     /// @return Decoded command output block stream.
-    function callCommand(CommandContext memory ctx, uint cid, uint value) internal returns (bytes memory) {
-        bytes4 selector = Ids.commandSelector(cid);
+    function callCommand(uint id, uint value, CommandContext memory ctx) internal returns (bytes memory) {
+        bytes4 selector = Ids.commandSelector(id);
         bytes memory data = abi.encodeWithSelector(selector, ctx);
-        return abi.decode(callTo(cid, value, data), (bytes));
+        return abi.decode(callTo(id, value, data), (bytes));
     }
 }

package/core/Host.sol

@@ -5,38 +5,43 @@ import {AccessControl} from "./Access.sol";
 import {Authorize} from "../commands/admin/Authorize.sol";
 import {Unauthorize} from "../commands/admin/Unauthorize.sol";
 import {ExecutePayable} from "../commands/admin/Execute.sol";
-import {HostAnnouncedEvent} from "../events/Host.sol";
-import {IHostDiscovery} from "../interfaces/IHostDiscovery.sol";
-import {Ids} from "../utils/Ids.sol";
+import {IntroductionEvent} from "../events/Introduction.sol";
 
-/// @notice Mixin that allows a contract to act as a host discovery registry.
-/// Hosts call `announceHost` on a discovery contract to register themselves.
-abstract contract HostDiscovery is HostAnnouncedEvent, IHostDiscovery {
-    /// @notice Announce this host to the discovery registry.
-    /// Validates that `id` matches `msg.sender` before emitting.
-    /// @param id Host node ID (must equal `Ids.toHost(msg.sender)`).
-    /// @param blocknum Block number at which the host was deployed.
-    /// @param version Protocol version the host implements.
-    /// @param namespace Human-readable namespace string for the host.
-    function announceHost(uint id, uint blocknum, uint16 version, string calldata namespace) external {
-        emit HostAnnounced(Ids.matchHost(id, msg.sender), blocknum, version, namespace);
-    }
+/// @title IHostIntroduction
+/// @notice Interface implemented by hosts that accept introductions from other hosts.
+interface IHostIntroduction {
+    /// @notice Record a host introduction claim.
+    /// @param peer Host node ID being introduced.
+    /// @param blocknum Block number at which the introduction was made.
+    /// @param version Protocol version the host is running.
+    /// @param namespace Human-readable namespace or label for the host.
+    function introduce(uint peer, uint blocknum, uint16 version, string calldata namespace) external;
 }
 
 /// @title Host
 /// @notice Abstract base contract for rootzero host implementations.
 /// Inherits admin command support (authorize, unauthorize, executePayable) and
-/// optionally announces itself to a discovery contract at deployment.
+/// optionally introduces itself to a commander host at deployment.
 /// Accepts native ETH payments via the `receive` function.
-abstract contract Host is Authorize, Unauthorize, ExecutePayable {
+abstract contract Host is Authorize, Unauthorize, ExecutePayable, IntroductionEvent, IHostIntroduction {
     /// @param cmdr Commander address; passed to `AccessControl`.
-    ///        If `cmdr` is a deployed contract, the host calls `announceHost`
-    ///        on it during construction to register with the discovery registry.
+    ///        If `cmdr` is a deployed contract, the host calls `introduce`
+    ///        on it during construction.
     /// @param version Protocol version number to publish in the announcement.
     /// @param namespace Human-readable namespace string for the host.
     constructor(address cmdr, uint16 version, string memory namespace) AccessControl(cmdr) {
         if (cmdr == address(0) || cmdr == address(this) || cmdr.code.length == 0) return;
-        IHostDiscovery(cmdr).announceHost(host, block.number, version, namespace);
+        IHostIntroduction(cmdr).introduce(host, block.number, version, namespace);
+    }
+
+    /// @notice Record a host introduction claim.
+    /// @dev This event is informational only; it does not authorize or trust the introduced host.
+    /// @param peer Host node ID being introduced.
+    /// @param blocknum Block number at which the host was deployed.
+    /// @param version Protocol version the host implements.
+    /// @param namespace Human-readable namespace string for the host.
+    function introduce(uint peer, uint blocknum, uint16 version, string calldata namespace) external {
+        emit Introduction(peer, blocknum, version, namespace);
     }
 
     /// @notice Accept native ETH transfers (e.g. from command value flows).

package/docs/Schema.md

@@ -57,7 +57,8 @@ Once a child block appears, no more fixed fields may follow.
 
 ```txt
 #call { uint target, uint value, #bytes as payload }
-#context { bytes32 account, uint value, #bytes as state, #bytes as request }
+#context { bytes32 account, #bytes as state, #bytes as request }
+#relay { uint target, uint value, #context { bytes32 account, #bytes as state, #bytes as request } }
 ```
 
 The tail is embedded directly as child block bytes. There is no wrapper around a
@@ -187,7 +188,8 @@ Common protocol schemas live in `contracts/blocks/Schema.sol`:
 #payout { bytes32 account, bytes32 asset, bytes32 meta, uint amount }
 #call { uint target, uint value, #bytes as payload }
 #step { uint target, uint value, #bytes as request }
-#context { bytes32 account, uint value, #bytes as state, #bytes as request }
+#context { bytes32 account, #bytes as state, #bytes as request }
+#relay { uint target, uint value, #context { bytes32 account, #bytes as state, #bytes as request } }
 #auth { uint cid, uint deadline, #bytes as proof }
 ```
 

package/events/Introduction.sol

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { EventEmitter } from "./Emitter.sol";
+
+string constant ABI = "event Introduction(uint indexed host, uint blocknum, uint16 version, string namespace)";
+
+/// @notice Emitted when a host introduces itself to another host.
+abstract contract IntroductionEvent is EventEmitter {
+    /// @param host Host node ID of the introducing contract.
+    /// @param blocknum Block number at which the host was deployed.
+    /// @param version Protocol version the host implements.
+    /// @param namespace Human-readable namespace string for the host.
+    event Introduction(uint indexed host, uint blocknum, uint16 version, string namespace);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}
+
+
+

package/events/{Piped.sol → Rooted.sol}

@@ -3,14 +3,14 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-string constant ABI = "event Piped(bytes32 indexed account, uint deadline, uint value)";
+string constant ABI = "event Rooted(bytes32 indexed account, uint deadline, uint value)";
 
 /// @notice Emitted for root-level protocol actions (e.g. governance or protocol-wide operations).
-abstract contract PipedEvent is EventEmitter {
+abstract contract RootedEvent is EventEmitter {
     /// @param account Account identifier associated with the action.
     /// @param deadline Expiry timestamp of the action.
     /// @param value Native value associated with the action.
-    event Piped(bytes32 indexed account, uint deadline, uint value);
+    event Rooted(bytes32 indexed account, uint deadline, uint value);
 
     constructor() {
         emit EventAbi(ABI);

package/package.json

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

package/peer/Pipe.sol

@@ -9,26 +9,26 @@ import {Budget} from "../utils/Value.sol";
 using Cursors for Cur;
 
 /// @title PeerPipePayable
-/// @notice Peer that consumes CONTEXT blocks and executes each context request as a STEP stream.
-/// Each CONTEXT block carries an account, state, and request; the request is passed to the
-/// shared pipeline as the step stream.
+/// @notice Peer that consumes RELAY blocks and executes each context request as a STEP stream.
+/// Each RELAY block carries a value budget plus a CONTEXT block; the relay target is ignored
+/// and the nested context request is passed to the shared pipeline as the step stream.
 abstract contract PeerPipePayable is PeerBase, Pipeline {
     string private constant NAME = "peerPipePayable";
     uint internal immutable peerPipePayableId = peerId(NAME);
 
     constructor() {
-        emit Peer(host, peerPipePayableId, NAME, "1:0", Schemas.Context, "", true);
+        emit Peer(host, peerPipePayableId, NAME, "1:0", Schemas.Relay, "", true);
     }
 
-    /// @notice Execute peer-supplied contexts through the shared payable pipe.
-    /// @dev Each context receives its own explicit value sub-budget. Any top-level
-    ///      `msg.value` not assigned to a context remains on this host.
+    /// @notice Execute peer-supplied relays through the shared payable pipe.
+    /// @dev Each relay receives its own explicit value sub-budget. Any top-level
+    ///      `msg.value` not assigned to a relay remains on this host.
     function peerPipePayable(bytes calldata request) external payable onlyPeer returns (bytes memory) {
         (Cur memory input, ) = cursor(request, 1);
         Budget memory budget = valueBudget();
 
         while (input.i < input.bound) {
-            (bytes32 account, uint value, bytes calldata state, bytes calldata steps) = input.unpackContext();
+            (, uint value, bytes32 account, bytes calldata state, bytes calldata steps) = input.unpackRelay();
             pipe(account, state, steps, allocateValue(budget, value));
         }
 

package/events/Governed.sol

@@ -1,21 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import { EventEmitter } from "./Emitter.sol";
-
-string constant ABI = "event Governed(uint indexed host, uint deadline, uint value)";
-
-/// @notice Emitted when a governance action is recorded on a host.
-abstract contract GovernedEvent is EventEmitter {
-    /// @param host Host node ID where the governance action occurred.
-    /// @param deadline Expiry timestamp of the governance action.
-    /// @param value Native value associated with the action.
-    event Governed(uint indexed host, uint deadline, uint value);
-
-    constructor() {
-        emit EventAbi(ABI);
-    }
-}
-
-
-

package/events/Host.sol

@@ -1,22 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import { EventEmitter } from "./Emitter.sol";
-
-string constant ABI = "event HostAnnounced(uint indexed host, uint blocknum, uint16 version, string namespace)";
-
-/// @notice Emitted by the discovery contract when a host registers itself.
-abstract contract HostAnnouncedEvent is EventEmitter {
-    /// @param host Host node ID of the registering contract.
-    /// @param blocknum Block number at which the host was deployed.
-    /// @param version Protocol version the host implements.
-    /// @param namespace Human-readable namespace string for the host.
-    event HostAnnounced(uint indexed host, uint blocknum, uint16 version, string namespace);
-
-    constructor() {
-        emit EventAbi(ABI);
-    }
-}
-
-
-

package/interfaces/IHostDiscovery.sol

@@ -1,16 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-/// @title IHostDiscovery
-/// @notice Interface implemented by a discovery registry that hosts announce themselves to.
-interface IHostDiscovery {
-    /// @notice Register or refresh a host entry in the discovery registry.
-    /// @param id Host node ID.
-    /// @param blocknum Block number at which the announcement was made.
-    /// @param version Protocol version the host is running.
-    /// @param namespace Human-readable namespace or label for the host.
-    function announceHost(uint id, uint blocknum, uint16 version, string calldata namespace) external;
-}
-
-
-