@rootzero/contracts 1.22.0 → 1.24.0

package/commands/admin/Annotate.sol

@@ -16,21 +16,19 @@ abstract contract Annotate is AdminBase {
     }
 
     /// @notice Publish each ANNOTATION block in the admin input.
-    /// @param input ANNOTATION block stream.
+    /// @param context Admin command context carrying the ANNOTATION input 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);
+        bytes calldata context
+    ) external returns (bytes memory, bytes memory) {
+        Execution memory exec = openAdminCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (uint entity, bytes calldata data) = exec.unpackAnnotation(Lanes.Input);
             emit Annotation(entity, data);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/admin/Appoint.sol

@@ -17,21 +17,19 @@ abstract contract Appoint is GuardianAccess, AdminBase {
     }
 
     /// @notice Appoint each user ACCOUNT block in the admin input as a guardian.
-    /// @param input ACCOUNT block stream.
+    /// @param context Admin command context carrying the ACCOUNT input stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function appoint(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
-    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        bytes calldata context
+    ) external returns (bytes memory, bytes memory) {
+        Execution memory exec = openAdminCommand(context, descriptor, 0);
 
         while (exec.more()) {
             bytes32 guardian = exec.unpackAccount(Lanes.Input);
             setGuardian(guardian, true);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/admin/Authorize.sol

@@ -22,21 +22,19 @@ abstract contract Authorize is AdminBase {
     }
 
     /// @notice Authorize each NODE block in the admin input.
-    /// @param input NODE block stream.
+    /// @param context Admin command context carrying the NODE input stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function authorize(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
-    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        bytes calldata context
+    ) external returns (bytes memory, bytes memory) {
+        Execution memory exec = openAdminCommand(context, descriptor, 0);
 
         while (exec.more()) {
             uint node = exec.unpackNode(Lanes.Input);
             setNode(node, true);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/admin/Base.sol

@@ -7,9 +7,18 @@ import {NodeAccess} from "../../core/Access.sol";
 /// @title AdminBase
 /// @notice Shared base for admin commands.
 abstract contract AdminBase is NodeAccess, CommandBase {
-    /// @dev Restrict execution to the commander using the host's admin account.
-    modifier onlyAdmin(bytes32 account) {
+    /// @notice Decode, authorize, and open one admin command context.
+    function openAdminCommand(
+        bytes calldata context,
+        uint descriptor,
+        uint batches
+    ) internal view returns (Execution memory exec) {
+        bytes32 account;
+        bytes calldata state;
+        bytes calldata input;
+        (account, state, input) = unpackCommandContext(context);
         enforceAdmin(account, msg.sender);
-        _;
+        exec = Executions.open(state, input, descriptor, batches);
+        exec.account = account;
     }
 }

package/commands/admin/DenyAssets.sol

@@ -23,21 +23,19 @@ abstract contract DenyAssets is AdminBase, DenyAssetsHook {
     }
 
     /// @notice Deny each ASSET block in the admin input.
-    /// @param input ASSET block stream.
+    /// @param context Admin command context carrying the ASSET input stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function denyAssets(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
-    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        bytes calldata context
+    ) external returns (bytes memory, bytes memory) {
+        Execution memory exec = openAdminCommand(context, descriptor, 0);
 
         while (exec.more()) {
             bytes32 asset = exec.unpackAsset(Lanes.Input);
             denyAsset(asset);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/admin/Dismiss.sol

@@ -17,21 +17,19 @@ abstract contract Dismiss is GuardianAccess, AdminBase {
     }
 
     /// @notice Dismiss each user ACCOUNT block in the admin input from guardian status.
-    /// @param input ACCOUNT block stream.
+    /// @param context Admin command context carrying the ACCOUNT input stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function dismiss(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
-    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        bytes calldata context
+    ) external returns (bytes memory, bytes memory) {
+        Execution memory exec = openAdminCommand(context, descriptor, 0);
 
         while (exec.more()) {
             bytes32 guardian = exec.unpackAccount(Lanes.Input);
             setGuardian(guardian, false);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/admin/Execute.sol

@@ -19,21 +19,19 @@ abstract contract ExecutePayable is RawNodeCalls, AdminBase {
     }
 
     /// @notice Execute each CALL block in the admin input.
-    /// @param input CALL block stream.
+    /// @param context Admin command context carrying the CALL input stream.
     /// @return Empty output state.
     /// @return Remaining native value as a refund transaction stream.
     function executePayable(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
-    ) external payable onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        bytes calldata context
+    ) external payable returns (bytes memory, bytes memory) {
+        Execution memory exec = openAdminCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (uint target, uint resources, bytes calldata data) = exec.unpackCall(Lanes.Input);
             rawCall(target, exec.useResourceValue(resources), data);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/admin/Unauthorize.sol

@@ -22,21 +22,19 @@ abstract contract Unauthorize is AdminBase {
     }
 
     /// @notice Unauthorize each NODE block in the admin input.
-    /// @param input NODE block stream.
+    /// @param context Admin command context carrying the NODE input stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function unauthorize(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
-    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        bytes calldata context
+    ) external returns (bytes memory, bytes memory) {
+        Execution memory exec = openAdminCommand(context, descriptor, 0);
 
         while (exec.more()) {
             uint node = exec.unpackNode(Lanes.Input);
             setNode(node, false);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/core/Access.sol

@@ -12,6 +12,14 @@ import {addrOr} from "../utils/Utils.sol";
 error AccessDenied();
 error CommanderNotAllowed();
 
+/// @notice Assert that `msg.sender` equals `expected` and return it.
+/// @param expected Address required to be the current message sender.
+/// @return The validated sender address.
+function enforceSender(address expected) view returns (address) {
+    if (msg.sender != expected) revert AccessDenied();
+    return expected;
+}
+
 /// @title CallerAccess
 /// @notice Authorization capability required by command entrypoints.
 abstract contract CallerAccess is Runtime {

package/core/Calls.sol

@@ -3,6 +3,9 @@ pragma solidity ^0.8.33;
 
 import {TrustAccess} from "./Access.sol";
 import {Nodes} from "../utils/Nodes.sol";
+import {Keys} from "../codec/Keys.sol";
+import {Sizes} from "../codec/Specs.sol";
+import {max32} from "../utils/Utils.sol";
 
 /// @dev Emitted when a trusted inter-node call fails.
 /// @param addr Contract address that was called.
@@ -81,6 +84,50 @@ abstract contract NodeCalls is RawNodeCalls, TrustAccess {
 /// @title CommandCalls
 /// @notice Trusted command-call helpers for contracts that route command nodes.
 abstract contract CommandCalls is NodeCalls {
+    /// @dev Build `command(bytes)` calldata and its nested CONTEXT block in one allocation.
+    /// Threaded state is copied from memory and step input directly from calldata.
+    function encodeCommandCall(
+        bytes4 selector,
+        bytes32 account,
+        bytes memory state,
+        bytes calldata input
+    ) internal pure returns (bytes memory data) {
+        uint contextLen = max32(Sizes.B32 + 2 * Sizes.Header + state.length + input.length);
+        uint paddedContextLen = (contextLen + 31) & ~uint(31);
+        uint dataLen = 4 + 64 + paddedContextLen;
+
+        // Reserve one scratch word because the final eight-byte block header is
+        // written with mstore. Exclude that word from the returned calldata.
+        data = new bytes(dataLen + 32);
+
+        uint contextKey = uint32(Keys.Context);
+        uint bytesKey = uint32(Keys.Bytes);
+        assembly ("memory-safe") {
+            mstore(data, dataLen)
+            let out := add(data, 0x20)
+
+            // ABI envelope for command(bytes).
+            mstore(out, selector)
+            mstore(add(out, 0x04), 0x20)
+            mstore(add(out, 0x24), contextLen)
+
+            // CONTEXT(account, BYTES(state), BYTES(input)).
+            let context := add(out, 0x44)
+            mstore(context, or(shl(224, contextKey), shl(192, sub(contextLen, 8))))
+            mstore(add(context, 0x08), account)
+
+            let stateBlock := add(context, 0x28)
+            let stateLen := mload(state)
+            mstore(stateBlock, or(shl(224, bytesKey), shl(192, stateLen)))
+            mcopy(add(stateBlock, 0x08), add(state, 0x20), stateLen)
+
+            let inputBlock := add(add(stateBlock, 0x08), stateLen)
+            let inputLen := input.length
+            mstore(inputBlock, or(shl(224, bytesKey), shl(192, inputLen)))
+            calldatacopy(add(inputBlock, 0x08), input.offset, inputLen)
+        }
+    }
+
     /// @notice Encode and call a trusted command node.
     /// @param command Command node ID embedding the target selector.
     /// @param value Native value to forward in wei.
@@ -97,7 +144,7 @@ abstract contract CommandCalls is NodeCalls {
         bytes calldata input
     ) internal returns (bytes memory nextState, bytes memory transactions) {
         bytes4 selector = Nodes.commandSelector(command);
-        bytes memory data = abi.encodeWithSelector(selector, account, state, input);
+        bytes memory data = encodeCommandCall(selector, account, state, input);
         return abi.decode(trustedCall(command, value, data), (bytes, bytes));
     }
 }
@@ -110,7 +157,18 @@ abstract contract PortCalls is NodeCalls {
     /// @param value Native value to forward in wei.
     /// @param input Port input block stream.
     /// @return success True if the low-level port call succeeded.
-    function tryCallPort(uint port, uint128 value, bytes calldata input) internal returns (bool success) {
+    function tryCallPort(uint port, uint128 value, bytes memory input) internal returns (bool success) {
+        bytes4 selector = Nodes.portSelector(port);
+        bytes memory data = abi.encodeWithSelector(selector, input);
+        return tryTrustedCall(port, value, data);
+    }
+
+    /// @notice Try to encode and call a trusted port node by copying input from calldata.
+    /// @param port Port node ID embedding the target selector.
+    /// @param value Native value to forward in wei.
+    /// @param input Port input block stream.
+    /// @return success True if the low-level port call succeeded.
+    function tryCallPortCopy(uint port, uint128 value, bytes calldata input) internal returns (bool success) {
         bytes4 selector = Nodes.portSelector(port);
         bytes memory data = abi.encodeWithSelector(selector, input);
         return tryTrustedCall(port, value, data);
@@ -121,7 +179,18 @@ abstract contract PortCalls is NodeCalls {
     /// @param value Native value to forward in wei.
     /// @param input Port input block stream.
     /// @return Decoded port output block stream.
-    function callPort(uint port, uint128 value, bytes calldata input) internal returns (bytes memory) {
+    function callPort(uint port, uint128 value, bytes memory input) internal returns (bytes memory) {
+        bytes4 selector = Nodes.portSelector(port);
+        bytes memory data = abi.encodeWithSelector(selector, input);
+        return abi.decode(trustedCall(port, value, data), (bytes));
+    }
+
+    /// @notice Encode and call a trusted port node by copying input from calldata.
+    /// @param port Port node ID embedding the target selector.
+    /// @param value Native value to forward in wei.
+    /// @param input Port input block stream.
+    /// @return Decoded port output block stream.
+    function callPortCopy(uint port, uint128 value, bytes calldata input) internal returns (bytes memory) {
         bytes4 selector = Nodes.portSelector(port);
         bytes memory data = abi.encodeWithSelector(selector, input);
         return abi.decode(trustedCall(port, value, data), (bytes));

package/core/Portal.sol

@@ -21,7 +21,7 @@ abstract contract Portal is PortCalls, NodeAccess, UnresolvedEvent, ResolvedEven
     /// @param value Native EVM value assigned to the forwarding attempt.
     /// @return miss Message digest recorded for recovery when forwarding fails; zero on success.
     function forward(uint port, bytes32 key, bytes calldata message, uint128 value) internal returns (bytes32 miss) {
-        if (tryCallPort(port, value, message)) return bytes32(0);
+        if (tryCallPortCopy(port, value, message)) return bytes32(0);
 
         miss = keccak256(message);
         unresolved[key] = miss;
@@ -37,6 +37,6 @@ abstract contract Portal is PortCalls, NodeAccess, UnresolvedEvent, ResolvedEven
         if (unresolved[key] != keccak256(witness)) revert BadWitness();
 
         delete unresolved[key];
-        callPort(port, value, witness);
+        callPortCopy(port, value, witness);
     }
 }

package/core/Types.sol

@@ -67,6 +67,14 @@ struct HostAccountAmount {
     uint amount;
 }
 
+/// @notice Liability and debt pair threaded as live pipeline state.
+struct Debt {
+    /// @dev Identifier for the liability side.
+    bytes32 liability;
+    /// @dev Quantity owed on the liability side.
+    uint debt;
+}
+
 /// @notice Asset and liability pair threaded as live pipeline state.
 struct Position {
     /// @dev Identifier for the asset side.

package/events/Positioned.sol

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {EventEmitter} from "./Emitter.sol";
+
+/// @notice Emitted when an action produces an account position.
+abstract contract PositionedEvent is EventEmitter {
+    string private constant ABI =
+        "event Positioned(bytes32 indexed account, bytes32 asset, uint amount, bytes32 liability, uint debt, uint32 action)";
+
+    /// @param account Account associated with the position.
+    /// @param asset Identifier for the asset side.
+    /// @param amount Quantity on the asset side.
+    /// @param liability Identifier for the liability side.
+    /// @param debt Quantity owed on the liability side.
+    /// @param action Primary operation hint from `Actions` that produced the position.
+    event Positioned(bytes32 indexed account, bytes32 asset, uint amount, bytes32 liability, uint debt, uint32 action);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/execution/Execution.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, Position, Tx} from "../core/Types.sol";
+import {AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, Debt, Position, Tx} from "../core/Types.sol";
 import {Blocks} from "../codec/Blocks.sol";
 import {Buffers} from "../codec/Buffers.sol";
 import {Sizes, Specs} from "../codec/Specs.sol";
@@ -15,6 +15,7 @@ import {max16} from "../utils/Utils.sol";
 /// @dev `decoders` contains tagged input and state cursor lanes. Cursor operations
 /// select one logical lane by swapping it into the lower 128 bits.
 struct Execution {
+    bytes32 account;
     uint budget;
     uint decoders;
     uint writers;
@@ -195,6 +196,33 @@ library Executions {
         return exec.decoders.select(lane).absolute();
     }
 
+    /// @dev Return the complete validated calldata source for a decoder lane.
+    /// @dev Does not consume or depend on the lane's current position. A lane
+    /// absent because its descriptor is EMPTY returns an empty calldata slice.
+    /// @param exec Execution whose input or state source is requested.
+    /// @param lane Input or state decoder lane.
+    /// @return data Complete calldata region represented by the lane.
+    function raw(Execution memory exec, uint8 lane) private pure returns (bytes calldata data) {
+        if (!exec.decoders.contains(lane)) return msg.data[0:0];
+
+        uint cur = exec.decoders.select(lane);
+        (, uint offset, uint len) = cur.decode();
+        if (len > msg.data.length || offset > msg.data.length - len) revert Blocks.MalformedBlocks();
+        return msg.data[offset:offset + len];
+    }
+
+    /// @notice Return the complete validated command state without consuming it.
+    /// @dev Remains the complete original state after the state cursor advances.
+    function rawState(Execution memory exec) internal pure returns (bytes calldata) {
+        return raw(exec, Lanes.State);
+    }
+
+    /// @notice Return the complete validated endpoint input without consuming it.
+    /// @dev Remains the complete original input after the input cursor advances.
+    function rawInput(Execution memory exec) internal pure returns (bytes calldata) {
+        return raw(exec, Lanes.Input);
+    }
+
     /// @notice Return whether the next block on `lane` has `key` and an empty payload.
     /// @param exec Execution whose decoder is inspected without advancing.
     /// @param lane Decoder lane to inspect.
@@ -218,6 +246,20 @@ library Executions {
         exec.decoders = cur.seekAbs(end);
     }
 
+    /// @notice Validate and consume one block from a decoder lane, returning its complete encoding.
+    /// @param exec Execution whose selected decoder cursor is advanced past the block.
+    /// @param lane Execution decoder lane to select.
+    /// @param key Expected block key.
+    /// @return data Calldata view of the complete block, including its header.
+    function takeBlock(
+        Execution memory exec,
+        uint8 lane,
+        bytes4 key
+    ) internal pure returns (bytes calldata data) {
+        (uint abs, uint end) = consume(exec, lane, Specs.create(key, 0, 0, 0));
+        data = msg.data[abs - Sizes.Header:end];
+    }
+
     /// @notice Consume a matching empty block from an execution decoder lane when present.
     /// @param exec Execution whose selected decoder advances only for a matching empty block.
     /// @param lane Decoder lane to consume.
@@ -486,6 +528,18 @@ library Executions {
         (value.asset, value.amount) = unpackBalance(exec, lane);
     }
 
+    /// @notice Decode and consume one DEBT block from `lane`.
+    function unpackDebt(Execution memory exec, uint8 lane) internal pure returns (bytes32 liability, uint debt) {
+        uint abs;
+        (exec.decoders, abs) = exec.decoders.consume(lane, Sizes.Debt);
+        (liability, debt) = Blocks.unpackDebt(abs);
+    }
+
+    /// @notice Decode one DEBT block into its structured value.
+    function unpackDebtValue(Execution memory exec, uint8 lane) internal pure returns (Debt memory value) {
+        (value.liability, value.debt) = unpackDebt(exec, lane);
+    }
+
     /// @notice Decode and consume one POSITION block from `lane`.
     function unpackPosition(
         Execution memory exec,
@@ -948,6 +1002,17 @@ library Executions {
         outputBalance(exec, value.asset, value.amount);
     }
 
+    /// @notice Append a DEBT block to execution output.
+    function outputDebt(Execution memory exec, bytes32 liability, uint debt) internal pure {
+        uint i = reserve(exec, Sizes.Debt);
+        Blocks.writeDebt(exec.output, i, liability, debt);
+    }
+
+    /// @notice Append a structured DEBT value to execution output.
+    function outputDebt(Execution memory exec, Debt memory value) internal pure {
+        outputDebt(exec, value.liability, value.debt);
+    }
+
     /// @notice Append a POSITION block to execution output.
     function outputPosition(
         Execution memory exec,

package/package.json

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

package/ports/Allowance.sol

@@ -2,35 +2,45 @@
 pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
-import {AllowanceHook} from "../commands/admin/Allowance.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
 using Executions for Execution;
 
-/// @title AllowancePort
-/// @notice Port that lets a trusted peer host input or refresh its own allowance.
-/// Each AMOUNT block in the input is scoped to the peer host and passed to the
-/// shared allowance hook as a host-scoped allowance. Restricted to trusted peers.
-abstract contract AllowancePort is PortBase, AllowanceHook {
+/// @notice Hook implemented by hosts that handle allowance requests from peers.
+abstract contract RequestAllowanceHook {
+    /// @notice Override to handle one allowance request from a peer host.
+    /// @dev The implementation is responsible for validating the request and
+    /// deciding what allowance, if any, to grant.
+    /// @param peer Peer host node ID requesting the allowance.
+    /// @param asset Asset identifier supplied by the peer.
+    /// @param amount Allowance amount requested in the asset's native units.
+    function requestAllowance(uint peer, bytes32 asset, uint amount) internal virtual;
+}
+
+/// @title RequestAllowancePort
+/// @notice Port that lets trusted peers request their own asset allowances.
+/// Each AMOUNT block is scoped to the caller and passed unchanged to
+/// `requestAllowance(peer, asset, amount)`.
+abstract contract RequestAllowancePort is PortBase, RequestAllowanceHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portAllowance", Specs.Amount, Specs.Empty, 0);
+        (, descriptor) = port("portRequestAllowance", Specs.Amount, Specs.Empty, 0);
     }
 
-    /// @notice Execute the allowance port call.
-    /// @param data AMOUNT block stream requested by the trusted peer.
+    /// @notice Request asset allowances for the calling peer.
+    /// @param data AMOUNT block stream supplied by the trusted peer.
     /// @return Empty response bytes.
-    function portAllowance(bytes calldata data) external onlyPeer returns (bytes memory) {
+    function portRequestAllowance(bytes calldata data) external onlyPeer returns (bytes memory) {
         Execution memory exec = openInput(data, descriptor, 0);
         uint peer = caller();
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
-            allowance(peer, asset, amount);
+            requestAllowance(peer, asset, amount);
         }
-        
+
         return "";
     }
 }