@rootzero/contracts 1.11.0 → 1.13.0

package/core/Payable.sol

@@ -2,15 +2,16 @@
 pragma solidity ^0.8.33;
 
 import {Budget, Values} from "../utils/Value.sol";
+import {Cursors} from "../Cursors.sol";
+import {ReceivedEvent} from "../events/Received.sol";
+import {Actions} from "../utils/Actions.sol";
+import {NativeAsset} from "./Runtime.sol";
 import {max128} from "../utils/Utils.sol";
 
 /// @title Payable
 /// @notice Abstract mixin for entrypoints that accept native value (`msg.value`).
 /// Provides shared helpers for mutable native-value budgets.
-abstract contract Payable {
-    /// @dev Thrown when a payable entrypoint completes with unspent native value.
-    error UnusedValue(uint remaining);
-
+abstract contract Payable is NativeAsset, ReceivedEvent {
     /// @notice Open a native-value budget from the current call's `msg.value`.
     /// @return Budget initialized with the full `msg.value`.
     function openValue() internal view returns (Budget memory) {
@@ -33,21 +34,20 @@ abstract contract Payable {
         Values.use(budget, value);
     }
 
-    /// @notice Close a native-value budget and settle any drained value.
-    /// @param account Account identifier for the current invocation.
-    /// @param budget Mutable native-value budget to close.
-    function closeValue(bytes32 account, Budget memory budget) internal {
-        uint value = Values.drain(budget);
-        if (value == 0) return;
-        settleValue(account, value);
-    }
+    /// @notice Drain a native-value budget into a credit-only TRANSACTION block.
+    /// @dev Emits `Received` with `Actions.Refund` when a transaction is created.
+    /// @param budget Mutable budget whose remaining value is drained.
+    /// @param account Destination account to credit with the remaining native value.
+    /// @return transaction Encoded TRANSACTION block, or empty bytes when the budget is empty.
+    function closeValue(
+        Budget memory budget,
+        bytes32 account
+    ) internal returns (bytes memory transaction) {
+        uint amount = Values.drain(budget);
+        if (amount == 0) return "";
 
-    /// @notice Handle a drained native value amount.
-    /// @dev Override to refund or redirect unused value. The default rejects it.
-    /// @param account Account identifier for the current invocation.
-    /// @param value Drained native value amount to settle, in wei.
-    function settleValue(bytes32 account, uint value) internal virtual {
-        account;
-        revert UnusedValue(value);
+        transaction = Cursors.toTransactionBlock(bytes32(0), account, nativeAsset, amount);
+        emit Received(account, nativeAsset, amount, Actions.Refund, 0);
     }
+
 }

package/core/Pipeline.sol

@@ -1,34 +1,38 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Cursors, Cur} from "../Cursors.sol";
+import {Cursors, Cur, Readers, Reader} from "../Cursors.sol";
 import {Payable} from "./Payable.sol";
+import {Settlement} from "./Settlement.sol";
 import {Budget} from "../utils/Value.sol";
 
 using Cursors for Cur;
+using Readers for Reader;
 
 /// @title Pipeline
 /// @notice Core pipeline functionality shared by higher-level surfaces.
-abstract contract Pipeline is Payable {
+abstract contract Pipeline is Payable, Settlement {
     /// @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 bytes become the state passed to
-    /// the next step, and the final returned state must be empty.
+    /// 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.
     /// @param target Node ID to invoke or handle.
     /// @param account Account identifier for the piped context.
     /// @param state Current threaded state block stream.
     /// @param request Step request block stream.
     /// @param value Native EVM value assigned to this step.
-    /// @return Updated state block stream for the next step.
+    /// @return nextState Updated state block stream for the next step.
+    /// @return transactions Transaction block stream produced by the command.
     function dispatch(
         uint target,
         bytes32 account,
         bytes memory state,
         bytes calldata request,
         uint128 value
-    ) internal virtual returns (bytes memory);
+    ) internal virtual returns (bytes memory nextState, bytes memory transactions);
 
     /// @notice Execute a STEP block stream through the pipeline.
     /// @dev Reverts with `UnexpectedState` if the final threaded state is non-empty.
@@ -37,20 +41,19 @@ abstract contract Pipeline is Payable {
     /// @param state Initial state block stream passed to the first step.
     /// @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 {
+    function pipe(bytes32 account, bytes memory state, bytes calldata steps, Budget memory budget) internal {
         (Cur memory input, ) = Cursors.init(steps, 1);
 
         while (input.i < input.len) {
             (uint target, uint resources, bytes calldata request) = input.unpackStep();
-            state = dispatch(target, account, state, request, useValue(budget, resources));
+            Reader memory txs;
+            (state, txs.source) = dispatch(target, account, state, request, useValue(budget, resources));
+            while (txs.more()) {
+                (bytes32 from, bytes32 to, bytes32 asset, uint amount) = txs.unpackTransaction();
+                settle(from, to, asset, amount);
+            }
         }
 
         if (state.length != 0) revert UnexpectedState();
-        input.complete();
     }
 }

package/core/Settlement.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+/// @title DebitAccountHook
+/// @notice Hook for debiting externally managed account funds.
+abstract contract DebitAccountHook {
+    /// @notice Override to debit externally managed funds from `account`.
+    /// @param account Source account identifier.
+    /// @param asset Asset identifier.
+    /// @param amount Amount to debit.
+    function debitAccount(bytes32 account, bytes32 asset, uint amount) internal virtual;
+}
+
+/// @title CreditAccountHook
+/// @notice Hook for crediting externally managed account funds.
+abstract contract CreditAccountHook {
+    /// @notice Override to credit externally managed funds to `account`.
+    /// @param account Destination account identifier.
+    /// @param asset Asset identifier.
+    /// @param amount Amount to credit.
+    function creditAccount(bytes32 account, bytes32 asset, uint amount) 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.
+    /// 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 {
+        if (amount == 0) return;
+        if (from != 0) debitAccount(from, asset, amount);
+        if (to != 0) creditAccount(to, asset, amount);
+    }
+}

package/docs/Schema.md

@@ -33,7 +33,7 @@ used. A host can publish the meaning of a custom key with:
 event Schema(uint indexed host, bytes4 key, string schema, bytes32 name);
 ```
 
-For example, a host-specific payment block can use `Keys.local(1)`, the command
+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.
 
@@ -65,16 +65,19 @@ A schema body is a comma-separated list of items. Order is significant.
 
 ## Payload Layout
 
-A block payload has fixed fields first, followed by an optional child-block tail.
-Once a child block appears, no more fixed fields may follow.
+A block payload encodes schema items in declaration order. Fixed fields are
+packed inline, and zero or more child blocks are embedded directly at their
+declared positions. Because every child block carries its own header and payload
+length, fixed fields may appear before, after, or between child blocks.
 
 ```txt
 { uint target, uint resources, #bytes as payload }
 { bytes32 account, #bytes as state, #bytes as request }
+{ bytes4 key, #string as body, bytes32 name }
+{ #bytes as left, uint op, #bytes as right }
 ```
 
-The tail is embedded directly as child block bytes. There is no wrapper around a
-child-block tail.
+There is no wrapper around embedded child blocks.
 
 Raw dynamic bytes are represented with the reserved `#bytes` child block. Use an
 alias to give those bytes a presentation name:
@@ -293,19 +296,21 @@ invalid in any path segment.
 ## Reserved Blocks
 
 - `#bytes`: raw dynamic bytes, written without a body
+- `#string`: UTF-8 string bytes, written without a body
 - `#list`: generic list wrapper emitted by `many`
 
 Custom input shapes should define their own context-local block key and publish
-that key with a `Schema` event:
+that key with a `Schema` event. Endpoint contracts can use `schema(...)` for
+that publication:
 
 ```solidity
-bytes4 constant Input = Keys.local(1);
-emit Schema(host, Input, "{ bytes32 asset, uint amount }", bytes32("payment"));
+bytes4 input = schema(1, "{ bytes32 asset, uint amount }");
 ```
 
-The key can be a small literal, a selector, or any other `bytes4` value that is
-unique in the context where it is used. The alias names the block; the schema
-string describes only the payload body.
+Use different numeric keys when a host needs more than one local block key. The
+key can also be a selector or any other `bytes4` value that is unique in the
+context where it is used. The alias names the block; the schema string describes
+only the payload body.
 
 ## Standard Blocks
 
@@ -320,6 +325,7 @@ step     { uint target, uint resources, #bytes as request }
 context  { bytes32 account, #bytes as state, #bytes as request }
 recover  { uint handler, uint resources, bytes32 key, #bytes as witness }
 auth     { uint cid, uint deadline, #bytes as proof }
+schema   { bytes4 key, #string as body, bytes32 name }
 ```
 
 `Keys.sol` contains the corresponding standard runtime keys.

package/events/Introduction.sol

@@ -5,11 +5,12 @@ 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 blocknum)";
+    string private constant ABI = "event Introduction(uint indexed host, uint peer, uint blocknum)";
 
-    /// @param host Host node ID of the introducing contract.
+    /// @param host Host node ID receiving the introduction.
+    /// @param peer Host node ID of the introducing contract.
     /// @param blocknum Block number at which the host was deployed.
-    event Introduction(uint indexed host, uint blocknum);
+    event Introduction(uint indexed host, uint peer, uint blocknum);
 
     constructor() {
         emit EventAbi(ABI);

package/package.json

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

package/ports/Credit.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import { PortBase } from "./Base.sol";
-import { CreditAccountHook } from "../commands/Credit.sol";
+import { CreditAccountHook } from "../core/Settlement.sol";
 import { Cursors, Cur, Keys } from "../Cursors.sol";
 
 using Cursors for Cur;

package/ports/Debit.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import { PortBase } from "./Base.sol";
-import { DebitAccountHook } from "../commands/Debit.sol";
+import { DebitAccountHook } from "../core/Settlement.sol";
 import { Cursors, Cur, Keys } from "../Cursors.sol";
 
 using Cursors for Cur;

package/ports/Settle.sol

@@ -2,8 +2,7 @@
 pragma solidity ^0.8.33;
 
 import { PortBase } from "./Base.sol";
-import { CreditAccountHook } from "../commands/Credit.sol";
-import { DebitAccountHook } from "../commands/Debit.sol";
+import { Settlement } from "../core/Settlement.sol";
 import { Cursors, Cur, Keys } from "../Cursors.sol";
 
 using Cursors for Cur;
@@ -11,7 +10,7 @@ using Cursors for Cur;
 /// @title PortSettle
 /// @notice Port that consumes peer-supplied TRANSACTION blocks through debit and credit hooks.
 /// Each TRANSACTION block calls `debitAccount` for `from` and `creditAccount` for `to`.
-abstract contract PortSettle is PortBase, DebitAccountHook, CreditAccountHook {
+abstract contract PortSettle is PortBase, Settlement {
     bytes32 private immutable descriptor;
 
     constructor() {
@@ -26,8 +25,7 @@ abstract contract PortSettle is PortBase, DebitAccountHook, CreditAccountHook {
 
         while (input.i < input.len) {
             (bytes32 from, bytes32 to, bytes32 asset, uint amount) = input.unpackTransaction();
-            if (from != 0) debitAccount(from, asset, amount);
-            if (to != 0) creditAccount(to, asset, amount);
+            settle(from, to, asset, amount);
         }
         return "";
     }