@rootzero/contracts 1.18.0 → 1.19.0

package/codec/Writers.sol

@@ -22,6 +22,7 @@ struct Writer {
 /// then lazily allocates and writes binary-encoded blocks sequentially.
 /// Physical allocation is rounded up to whole 32-byte words for scratch space,
 /// while the writer cursor length tracks logical capacity. Call `finish` to trim the buffer.
+/// `append*` helpers consume memory inputs; `copy*` helpers consume calldata inputs.
 library Writers {
     // -------------------------------------------------------------------------
     // Initialization helpers
@@ -497,6 +498,107 @@ library Writers {
         Blocks.writeSchema(writer.dst, i, spec, body, name);
     }
 
+    // -------------------------------------------------------------------------
+    // Calldata copy helpers
+    // -------------------------------------------------------------------------
+
+    /// @notice Append arbitrary calldata bytes to the writer.
+    /// @param writer Destination writer; `i` is advanced by `data.length`.
+    /// @param data Calldata bytes to append.
+    function copy(Writer memory writer, bytes calldata data) internal pure {
+        uint i = reserve(writer, data.length, data.length);
+        Buffers.copy(writer.dst, i, data);
+    }
+
+    /// @notice Append a custom block by copying its payload from calldata.
+    function copyBlock(Writer memory writer, uint spec, bytes calldata data) internal pure {
+        Specs.validate(spec, data.length);
+        uint size = Sizes.Header + data.length;
+        uint i = reserve(writer, size);
+        Blocks.copy(writer.dst, i, Specs.key(spec), data);
+    }
+
+    /// @notice Append a LIST block by copying its payload from calldata.
+    function copyList(Writer memory writer, bytes calldata value) internal pure {
+        uint size = Sizes.Header + value.length;
+        uint i = reserve(writer, size);
+        Blocks.copyList(writer.dst, i, value);
+    }
+
+    /// @notice Append an EVM block by copying its payload from calldata.
+    function copyEvm(Writer memory writer, bytes calldata value) internal pure {
+        uint size = Sizes.Header + value.length;
+        uint i = reserve(writer, size);
+        Blocks.copyEvm(writer.dst, i, value);
+    }
+
+    /// @notice Append a BYTES block by copying its payload from calldata.
+    function copyBytes(Writer memory writer, bytes calldata value) internal pure {
+        uint size = Sizes.Header + value.length;
+        uint i = reserve(writer, size);
+        Blocks.copyBytes(writer.dst, i, value);
+    }
+
+    /// @notice Append a STRING block by copying its payload from calldata.
+    function copyString(Writer memory writer, string calldata value) internal pure {
+        uint size = Sizes.Header + bytes(value).length;
+        uint i = reserve(writer, size);
+        Blocks.copyString(writer.dst, i, value);
+    }
+
+    /// @notice Append a STEP block by copying its nested input from calldata.
+    function copyStep(Writer memory writer, uint cmd, uint resources, bytes calldata input) internal pure {
+        uint size = Sizes.B64 + Sizes.Header + input.length;
+        uint i = reserve(writer, size);
+        Blocks.copyStep(writer.dst, i, cmd, resources, input);
+    }
+
+    /// @notice Append a CALL block by copying its nested payload from calldata.
+    function copyCall(Writer memory writer, uint target, uint resources, bytes calldata payload) internal pure {
+        uint size = Sizes.B64 + Sizes.Header + payload.length;
+        uint i = reserve(writer, size);
+        Blocks.copyCall(writer.dst, i, target, resources, payload);
+    }
+
+    /// @notice Append a RELAY block by copying its nested input from calldata.
+    function copyRelay(Writer memory writer, uint portal, uint resources, bytes calldata input) internal pure {
+        uint size = Sizes.B64 + Sizes.Header + input.length;
+        uint i = reserve(writer, size);
+        Blocks.copyRelay(writer.dst, i, portal, resources, input);
+    }
+
+    /// @notice Append a DISPATCH block by copying its nested payload from calldata.
+    function copyDispatch(Writer memory writer, uint portal, uint resources, bytes calldata payload) internal pure {
+        uint size = Sizes.B64 + Sizes.Header + payload.length;
+        uint i = reserve(writer, size);
+        Blocks.copyDispatch(writer.dst, i, portal, resources, payload);
+    }
+
+    /// @notice Append a CONTEXT block by copying its nested streams from calldata.
+    function copyContext(
+        Writer memory writer,
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
+    ) internal pure {
+        uint size = Sizes.B32 + 2 * Sizes.Header + state.length + input.length;
+        uint i = reserve(writer, size);
+        Blocks.copyContext(writer.dst, i, account, state, input);
+    }
+
+    /// @notice Append a RECOVER block by copying its nested witness from calldata.
+    function copyRecover(
+        Writer memory writer,
+        uint handler,
+        uint resources,
+        bytes32 recoverykey,
+        bytes calldata witness
+    ) internal pure {
+        uint size = Sizes.B96 + Sizes.Header + witness.length;
+        uint i = reserve(writer, size);
+        Blocks.copyRecover(writer.dst, i, handler, resources, recoverykey, witness);
+    }
+
     // -------------------------------------------------------------------------
     // Finalisation
     // -------------------------------------------------------------------------

package/commands/Relay.sol

@@ -34,7 +34,7 @@ abstract contract RelayPayable is CommandBase, RelayPayableHook {
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
         Execution memory exec = openCommand(state, input, descriptor, 1);
         (uint portal, uint resources, bytes calldata payload) = exec.unpackRelay(Lanes.Input);
-        bytes memory context = Blocks.context(account, bytes(state), bytes(payload));
+        bytes memory context = Blocks.contextCopy(account, state, payload);
 
         relayTo(portal, resources, context, exec);
 
@@ -66,7 +66,7 @@ abstract contract RelayBalancePayable is CommandBase, RelayPayableHook {
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
         Execution memory exec = openCommand(state, input, descriptor, 1);
         (uint portal, uint resources, bytes calldata payload) = exec.unpackRelay(Lanes.Input);
-        bytes memory context = Blocks.context(account, bytes(state), bytes(payload));
+        bytes memory context = Blocks.contextCopy(account, state, payload);
 
         relayTo(portal, resources, context, exec);
 

package/core/Settlement.sol

@@ -69,7 +69,7 @@ abstract contract Settlement is PostHook, SettleHook, RepayHook, DebitAccountHoo
         bytes32 liability,
         uint debt
     ) internal virtual override {
+        repay(account, liability, debt);
         if (amount != 0) creditAccount(account, asset, amount);
-        if (debt != 0) debitAccount(account, liability, debt);
     }
 }

package/docs/Schema.md

@@ -301,6 +301,11 @@ bytes1 through bytes32
 `uint` means `uint256`; `int` means `int256`. Other integer widths, unsized
 `bytes`, `string`, and array syntax are not part of the core schema DSL.
 
+Restricting fixed bytes to the power-of-two widths `bytes1`, `bytes2`,
+`bytes4`, `bytes8`, `bytes16`, and `bytes32` is under consideration, but has
+not been decided. Until that decision is made, the schema DSL continues to
+allow every `bytesN` width from 1 through 32.
+
 Integers are encoded big-endian. Signed integers use two's-complement encoding
 for their declared width. `bool` is one byte: `0x00` for false and `0x01` for
 true. `bytesN` values are encoded as exactly `N` bytes with no padding.

package/execution/Execution.sol

@@ -24,6 +24,8 @@ struct Execution {
 
 /// @title Executions
 /// @notice Opening, decoding, output, transaction, and value helpers for executions.
+/// @dev `output*` helpers consume memory inputs; `outputCopy*` helpers copy
+/// calldata inputs directly to the output lane.
 library Executions {
     using Cursors for uint;
 
@@ -197,6 +199,21 @@ library Executions {
         exec.decoders = cur.seekAbs(end);
     }
 
+    /// @notice Validate and enter the payload of the next block in an execution decoder lane.
+    /// @dev The selected lane remains in its existing frame so callers can decode
+    /// child blocks in place. Callers should prove complete payload consumption
+    /// with `exec.expectAbs(end)` after decoding the children from the same lane.
+    /// @param exec Execution whose selected decoder cursor advances over the block header.
+    /// @param lane Execution decoder lane to select.
+    /// @param spec Expected parent block specification.
+    /// @return abs Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function enter(Execution memory exec, uint8 lane, uint spec) internal pure returns (uint abs, uint end) {
+        uint cur = exec.decoders.select(lane);
+        (abs, end) = Blocks.expect(cur.absolute(), spec);
+        exec.decoders = cur.seekAbs(abs);
+    }
+
     /// @notice Require the active execution decoder to be at absolute position `abs`.
     /// @dev The most recent lane-aware decoder operation determines the active lane.
     /// @param exec Execution whose active decoder position is validated.
@@ -218,6 +235,46 @@ library Executions {
     // Fixed-width block decoding
     // -------------------------------------------------------------------------
 
+    /// @dev Return the next raw calldata word from `lane` and advance by `size` bytes.
+    function next(Execution memory exec, uint8 lane, uint size) private pure returns (bytes32 value) {
+        uint abs;
+        (exec.decoders, abs) = exec.decoders.consume(lane, size);
+        value = Blocks.read32(abs);
+    }
+
+    /// @notice Return the next raw byte from a decoder lane and advance it by one byte.
+    function next1(Execution memory exec, uint8 lane) internal pure returns (bytes1 value) {
+        value = bytes1(next(exec, lane, 1));
+    }
+
+    /// @notice Return the next two raw bytes from a decoder lane and advance it by two bytes.
+    function next2(Execution memory exec, uint8 lane) internal pure returns (bytes2 value) {
+        value = bytes2(next(exec, lane, 2));
+    }
+
+    /// @notice Return the next four raw bytes from a decoder lane and advance it by four bytes.
+    function next4(Execution memory exec, uint8 lane) internal pure returns (bytes4 value) {
+        value = bytes4(next(exec, lane, 4));
+    }
+
+    /// @notice Return the next eight raw bytes from a decoder lane and advance it by eight bytes.
+    function next8(Execution memory exec, uint8 lane) internal pure returns (bytes8 value) {
+        value = bytes8(next(exec, lane, 8));
+    }
+
+    /// @notice Return the next sixteen raw bytes from a decoder lane and advance it by sixteen bytes.
+    function next16(Execution memory exec, uint8 lane) internal pure returns (bytes16 value) {
+        value = bytes16(next(exec, lane, 16));
+    }
+
+    /// @notice Return the next raw calldata word from a decoder lane and advance it.
+    /// @param exec Execution whose selected decoder cursor advances by one word.
+    /// @param lane Execution decoder lane to select.
+    /// @return value Raw word at the selected lane's previous position.
+    function next32(Execution memory exec, uint8 lane) internal pure returns (bytes32 value) {
+        value = next(exec, lane, Sizes.Word);
+    }
+
     /// @notice Decode one fixed 32-byte payload from `lane`.
     /// @param exec Execution whose decoder is advanced.
     /// @param lane Decoder lane to consume.
@@ -1097,6 +1154,99 @@ library Executions {
         Blocks.writeSchema(exec.output, i, spec, body, name);
     }
 
+    // -------------------------------------------------------------------------
+    // Calldata output copy helpers
+    // -------------------------------------------------------------------------
+
+    /// @notice Append a custom block to execution output by copying its payload from calldata.
+    function outputCopyBlock(Execution memory exec, uint spec, bytes calldata data) internal pure {
+        Specs.validate(spec, data.length);
+        uint size = Sizes.Header + data.length;
+        uint i = reserve(exec, size);
+        Blocks.copy(exec.output, i, Specs.key(spec), data);
+    }
+
+    /// @notice Append a LIST block to execution output by copying its payload from calldata.
+    function outputCopyList(Execution memory exec, bytes calldata value) internal pure {
+        uint size = Sizes.Header + value.length;
+        uint i = reserve(exec, size);
+        Blocks.copyList(exec.output, i, value);
+    }
+
+    /// @notice Append an EVM block to execution output by copying its payload from calldata.
+    function outputCopyEvm(Execution memory exec, bytes calldata value) internal pure {
+        uint size = Sizes.Header + value.length;
+        uint i = reserve(exec, size);
+        Blocks.copyEvm(exec.output, i, value);
+    }
+
+    /// @notice Append a BYTES block to execution output by copying its payload from calldata.
+    function outputCopyBytes(Execution memory exec, bytes calldata value) internal pure {
+        uint size = Sizes.Header + value.length;
+        uint i = reserve(exec, size);
+        Blocks.copyBytes(exec.output, i, value);
+    }
+
+    /// @notice Append a STRING block to execution output by copying its payload from calldata.
+    function outputCopyString(Execution memory exec, string calldata value) internal pure {
+        uint size = Sizes.Header + bytes(value).length;
+        uint i = reserve(exec, size);
+        Blocks.copyString(exec.output, i, value);
+    }
+
+    /// @notice Append a STEP block to execution output by copying its nested input from calldata.
+    function outputCopyStep(Execution memory exec, uint cmd, uint resources, bytes calldata input) internal pure {
+        uint size = Sizes.B64 + Sizes.Header + input.length;
+        uint i = reserve(exec, size);
+        Blocks.copyStep(exec.output, i, cmd, resources, input);
+    }
+
+    /// @notice Append a CALL block to execution output by copying its nested payload from calldata.
+    function outputCopyCall(Execution memory exec, uint target, uint resources, bytes calldata payload) internal pure {
+        uint size = Sizes.B64 + Sizes.Header + payload.length;
+        uint i = reserve(exec, size);
+        Blocks.copyCall(exec.output, i, target, resources, payload);
+    }
+
+    /// @notice Append a RELAY block to execution output by copying its nested input from calldata.
+    function outputCopyRelay(Execution memory exec, uint portal, uint resources, bytes calldata input) internal pure {
+        uint size = Sizes.B64 + Sizes.Header + input.length;
+        uint i = reserve(exec, size);
+        Blocks.copyRelay(exec.output, i, portal, resources, input);
+    }
+
+    /// @notice Append a DISPATCH block to execution output by copying its nested payload from calldata.
+    function outputCopyDispatch(Execution memory exec, uint portal, uint resources, bytes calldata payload) internal pure {
+        uint size = Sizes.B64 + Sizes.Header + payload.length;
+        uint i = reserve(exec, size);
+        Blocks.copyDispatch(exec.output, i, portal, resources, payload);
+    }
+
+    /// @notice Append a CONTEXT block to execution output by copying its nested streams from calldata.
+    function outputCopyContext(
+        Execution memory exec,
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
+    ) internal pure {
+        uint size = Sizes.B32 + 2 * Sizes.Header + state.length + input.length;
+        uint i = reserve(exec, size);
+        Blocks.copyContext(exec.output, i, account, state, input);
+    }
+
+    /// @notice Append a RECOVER block to execution output by copying its nested witness from calldata.
+    function outputCopyRecover(
+        Execution memory exec,
+        uint handler,
+        uint resources,
+        bytes32 recoverykey,
+        bytes calldata witness
+    ) internal pure {
+        uint size = Sizes.B96 + Sizes.Header + witness.length;
+        uint i = reserve(exec, size);
+        Blocks.copyRecover(exec.output, i, handler, resources, recoverykey, witness);
+    }
+
     // -------------------------------------------------------------------------
     // Value and transaction writing
     // -------------------------------------------------------------------------

package/package.json

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

package/ports/AllowAssets.sol

@@ -8,10 +8,10 @@ import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
 using Executions for Execution;
 
-/// @title PortAllowAssets
+/// @title AllowAssetsPort
 /// @notice Port that permits a list of assets on behalf of a peer host.
 /// Each ASSET block in the input calls `allowAsset`. Restricted to trusted peers.
-abstract contract PortAllowAssets is PortBase, AllowAssetsHook {
+abstract contract AllowAssetsPort is PortBase, AllowAssetsHook {
     uint private immutable descriptor;
 
     constructor() {

package/ports/Allowance.sol

@@ -8,11 +8,11 @@ import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
 using Executions for Execution;
 
-/// @title PortAllowance
+/// @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 PortAllowance is PortBase, AllowanceHook {
+abstract contract AllowancePort is PortBase, AllowanceHook {
     uint private immutable descriptor;
 
     constructor() {

package/ports/Credit.sol

@@ -8,10 +8,10 @@ import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
 using Executions for Execution;
 
-/// @title PortCreditAccount
+/// @title CreditAccountPort
 /// @notice Port that lets a trusted peer credit supplied accounts directly.
 /// Each ACCOUNT_AMOUNT block calls `creditAccount` for its account.
-abstract contract PortCreditAccount is PortBase, CreditAccountHook {
+abstract contract CreditAccountPort is PortBase, CreditAccountHook {
     uint private immutable descriptor;
 
     constructor() {

package/ports/Debit.sol

@@ -8,10 +8,10 @@ import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
 using Executions for Execution;
 
-/// @title PortDebitAccount
+/// @title DebitAccountPort
 /// @notice Port that lets a trusted peer debit supplied accounts directly.
 /// Each ACCOUNT_AMOUNT block calls `debitAccount` for its account.
-abstract contract PortDebitAccount is PortBase, DebitAccountHook {
+abstract contract DebitAccountPort is PortBase, DebitAccountHook {
     uint private immutable descriptor;
 
     constructor() {

package/ports/DenyAssets.sol

@@ -8,10 +8,10 @@ import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
 using Executions for Execution;
 
-/// @title PortDenyAssets
+/// @title DenyAssetsPort
 /// @notice Port that blocks a list of assets on behalf of a peer host.
 /// Each ASSET block in the input calls `denyAsset`. Restricted to trusted peers.
-abstract contract PortDenyAssets is PortBase, DenyAssetsHook {
+abstract contract DenyAssetsPort is PortBase, DenyAssetsHook {
     uint private immutable descriptor;
 
     constructor() {

package/ports/Dispatch.sol

@@ -8,9 +8,9 @@ import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
 using Executions for Execution;
 
-/// @title PortDispatchPayable
+/// @title DispatchPayablePort
 /// @notice Port endpoint that forwards DISPATCH blocks to a host-defined relay hook.
-abstract contract PortDispatchPayable is PortBase, RelayPayableHook {
+abstract contract DispatchPayablePort is PortBase, RelayPayableHook {
     uint private immutable descriptor;
 
     constructor() {
@@ -27,7 +27,7 @@ abstract contract PortDispatchPayable is PortBase, RelayPayableHook {
 
         while (exec.more()) {
             (uint portal, uint resources, bytes calldata payload) = exec.unpackDispatch(Lanes.Input);
-            relayTo(portal, resources, bytes(payload), exec);
+            relayTo(portal, resources, payload, exec);
         }
         
         return "";

package/ports/Pipe.sol

@@ -9,10 +9,10 @@ import {Budget} from "../execution/Budget.sol";
 
 using Executions for Execution;
 
-/// @title PortPipePayable
+/// @title PipePayablePort
 /// @notice Port that consumes CONTEXT blocks and executes each input as a step stream.
 /// Each context's input bytes are passed to the shared pipeline.
-abstract contract PortPipePayable is PortBase, Pipeline {
+abstract contract PipePayablePort is PortBase, Pipeline {
     uint private immutable descriptor;
 
     constructor() {

package/ports/Post.sol

@@ -10,10 +10,10 @@ import {Actions} from "../utils/Actions.sol";
 
 using Executions for Execution;
 
-/// @title PortPost
+/// @title PostPort
 /// @notice Port that posts peer-supplied TRANSACTION blocks through debit and credit hooks.
 /// Each TRANSACTION block calls `debitAccount` for `from` and `creditAccount` for `to`.
-abstract contract PortPost is PortBase, PostHook, Action {
+abstract contract PostPort is PortBase, PostHook, Action {
     uint private immutable descriptor;
 
     constructor() {

package/ports/Redeem.sol

@@ -16,11 +16,11 @@ abstract contract RedeemBalanceHook {
     function redeemBalance(uint peer, bytes32 asset, uint amount) internal virtual;
 }
 
-/// @title PortRedeemBalance
+/// @title RedeemBalancePort
 /// @notice Port that redeems balance state from a peer host into local assets.
 /// Each BALANCE block in the input calls `redeemBalance(peer, asset, amount)`.
 /// Restricted to trusted peers.
-abstract contract PortRedeemBalance is PortBase, RedeemBalanceHook {
+abstract contract RedeemBalancePort is PortBase, RedeemBalanceHook {
     uint private immutable descriptor;
 
     constructor() {

package/utils/Cursors.sol

@@ -36,6 +36,11 @@ struct Cur {
 /// to marks. A zero mark identifies the empty cursor at position zero; `before`
 /// therefore treats it as already reached.
 ///
+/// Cursor navigation assumes packed cursor inputs satisfy `i <= len`.
+/// Constructors and composition helpers establish this invariant, and navigation
+/// helpers preserve it. Manually constructing or modifying packed cursor words
+/// may cause arithmetic panics instead of cursor-specific errors.
+///
 /// The zero word represents an absent cursor.
 library Cursors {
     /// @dev A cursor position exceeds its logical length.
@@ -214,11 +219,12 @@ library Cursors {
     }
 
     /// @notice Advance the current position of the lower cursor.
+    /// @dev Assumes `cur` satisfies the cursor invariant `i <= len`.
     /// @param cur Packed cursor or cursor pair.
     /// @param amount Number of bytes to advance.
     /// @return updated Cursor advanced by `amount`.
     function advance(uint cur, uint amount) internal pure returns (uint updated) {
-        uint i = uint32(validate(cur));
+        uint i = uint32(cur);
         uint len = uint32(cur >> 64);
         if (amount > len - i) revert OutOfBounds();
         updated = cur + amount;
@@ -236,14 +242,15 @@ library Cursors {
 
     /// @notice Create a child cursor over `[start, end)` within the lower cursor.
     /// @dev The child starts at position zero, has no recorded count, and uses the
-    /// supplied tag. Any higher cursor is omitted.
+    /// supplied tag. Any higher cursor is omitted. Assumes `cur` satisfies the
+    /// cursor invariant `i <= len`.
     /// @param cur Parent cursor or cursor pair.
     /// @param start Child start relative to the parent base.
     /// @param end Child exclusive end relative to the parent base.
     /// @param tag Child identity tag.
     /// @return child Packed child cursor.
     function slice(uint cur, uint start, uint end, uint8 tag) internal pure returns (uint child) {
-        (, uint offset, uint len) = decode(validate(cur));
+        (, uint offset, uint len) = decode(cur);
         if (start > end || end > len) revert OutOfBounds();
         child = create(offset + start, end - start, 0, 0, tag);
     }