@rootzero/contracts 1.23.0 → 1.25.0

package/codec/Decoders.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 "./Blocks.sol";
 import {Sizes, Specs} from "./Specs.sol";
 import {Cursors, Cur} from "../utils/Cursors.sol";
@@ -32,10 +32,18 @@ library Decoders {
         cur.state = Cursors.wrap(source[i:], 0, 0);
     }
 
-    /// @notice Open the first homogeneous run in `source`.
-    /// @param source Calldata block stream to open.
-    /// @return cur Cursor spanning the first homogeneous run.
+    /// @notice Open a non-empty calldata source as an ungrouped cursor.
+    /// @param source Calldata region to open.
+    /// @return cur Cursor spanning the complete source.
     function open(bytes calldata source) internal pure returns (Cur memory cur) {
+        if (source.length == 0) revert Blocks.EmptyRun();
+        cur.state = Cursors.wrap(source, 0, 0);
+    }
+
+    /// @notice Open the first homogeneous batch in `source`.
+    /// @param source Calldata block stream to open.
+    /// @return cur Counted cursor spanning the first homogeneous batch.
+    function batch(bytes calldata source) internal pure returns (Cur memory cur) {
         (uint abs, uint limit) = Cursors.bounds(source);
         if (abs == limit) revert Blocks.EmptyRun();
 
@@ -69,6 +77,18 @@ library Decoders {
         cur.state = cur.state.seekAbs(end);
     }
 
+    /// @notice Validate a known key and consume the next block from a cursor.
+    /// @dev Validates no payload-size constraint beyond proving the complete block
+    /// lies within the cursor's logical region.
+    /// @param cur Cursor advanced over the complete block.
+    /// @param key Expected block key.
+    /// @return abs Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function consume(Cur memory cur, bytes4 key) internal pure returns (uint abs, uint end) {
+        (abs, end) = Blocks.expectKey(cur.state.absolute(), key);
+        cur.state = cur.state.seekAbs(end);
+    }
+
     /// @notice Consume a matching empty block from a cursor when present.
     /// @param cur Cursor advanced only when the matching block is empty.
     /// @param key Expected block key.
@@ -268,7 +288,7 @@ library Decoders {
     /// @return out Cursor spanning the complete encoded block.
     function takeBlock(Cur memory cur, bytes4 key) internal pure returns (Cur memory out) {
         uint abs = cur.state.absolute();
-        (, uint end) = consume(cur, Specs.create(key, 0, 0, 0));
+        (, uint end) = consume(cur, key);
         out.state = Cursors.create(abs, end - abs, 0, 0, 0);
     }
 
@@ -427,6 +447,16 @@ library Decoders {
         (asset, amount) = Blocks.unpackBalance(abs);
     }
 
+    /// @notice Decode and consume one DEBT block.
+    /// @param cur Cursor advanced past the block.
+    /// @return liability Decoded liability identifier.
+    /// @return debt Decoded debt quantity.
+    function unpackDebt(Cur memory cur) internal pure returns (bytes32 liability, uint debt) {
+        uint abs;
+        (cur.state, abs) = cur.state.consume(Sizes.Debt);
+        (liability, debt) = Blocks.unpackDebt(abs);
+    }
+
     /// @notice Decode one BALANCE block and associate it with `host`.
     /// @param cur Cursor advanced past the block.
     /// @param host Host identifier associated with the balance.
@@ -614,6 +644,13 @@ library Decoders {
         (value.asset, value.amount) = unpackBalance(cur);
     }
 
+    /// @notice Decode one DEBT block into its structured value.
+    /// @param cur Cursor advanced past the block.
+    /// @return value Structured liability and debt.
+    function unpackDebtValue(Cur memory cur) internal pure returns (Debt memory value) {
+        (value.liability, value.debt) = unpackDebt(cur);
+    }
+
     /// @notice Decode and consume one HOST_ACCOUNT_ASSET block.
     /// @param cur Cursor advanced past the block.
     /// @return host Decoded host identifier.

package/codec/Descriptors.sol

@@ -6,6 +6,7 @@ import {Lanes} from "../utils/Lanes.sol";
 
 /// @title Flags
 /// @notice Packed endpoint behavior flags.
+/// @dev Bits 6 and 7 are reserved for endpoint-defined custom flags.
 library Flags {
     /// @dev Endpoint accepts nonzero native value.
     uint8 internal constant Funded = 1 << 0;
@@ -27,7 +28,8 @@ library Descriptors {
     /// `[output key:4][min:4][max:4][hint:3][stride:1]`
     /// `[reserved:4]`
     /// `[transactions:1]`
-    /// `[flags:1]`. Flag bits: funded = 0, admin = 1.
+    /// `[flags:1]`. Flag bits: funded = 0, admin = 1; bits 6 and 7 are
+    /// reserved for endpoint-defined custom flags.
     /// @param state State lane specification.
     /// @param input Direct input lane specification.
     /// @param output Output writer specification.

package/codec/Keys.sol

@@ -13,6 +13,8 @@ library Keys {
     bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, uint amount)
     bytes4 constant Balance = bytes4(keccak256("#balance"));
+    /// @dev Liability-only debt state - (bytes32 liability, uint debt)
+    bytes4 constant Debt = bytes4(keccak256("#debt"));
     /// @dev Host-scoped input amount - (uint host, bytes32 asset, uint amount)
     bytes4 constant Allocation = bytes4(keccak256("#allocation"));
     /// @dev Host-scoped allowance cap - (uint host, bytes32 asset, uint amount)

package/codec/Readers.sol

@@ -133,6 +133,18 @@ library Readers {
         }
     }
 
+    /// @notice Consume a DEBT block and return its fields.
+    /// @param cur Reader; advanced past the block.
+    /// @return liability Liability identifier.
+    /// @return debt Debt quantity.
+    function unpackDebt(Reader memory cur) internal pure returns (bytes32 liability, uint debt) {
+        uint abs = consume(cur, Keys.Debt, 64, 64);
+        assembly ("memory-safe") {
+            liability := mload(abs)
+            debt := mload(add(abs, 0x20))
+        }
+    }
+
     /// @notice Consume a HOST_ASSET block and return its fields.
     /// @param cur Reader; advanced past the block.
     /// @return host Host identifier.

package/codec/Schema.sol

@@ -53,12 +53,12 @@ pragma solidity ^0.8.33;
 // - command input and state streams are each a single run of blocks under the
 //   current protocol convention; the block format may support other shapes in
 //   future protocol surfaces
-// - `balance(...)`, `custody(...)`, and `position(...)` are live, linear state in the active command pipeline
+// - `balance(...)`, `debt(...)`, `custody(...)`, and `position(...)` are live, linear state in the active command pipeline
 // - pipeline state belongs to the active account while the pipeline is executing
-// - while a balance or custody is in-flight as pipeline state, it is not simultaneously persisted
+// - while a balance, debt, or custody is in-flight as pipeline state, it is not simultaneously persisted
 //   in another ledger/store by this protocol
-// - a position pairs live asset and liability sides; commands may transform either side
-// - position state is transient and does not itself create or erase an externally persisted obligation
+// - debt carries only a live liability side; position pairs live balance and debt sides
+// - debt and position state are transient and do not themselves create or erase an externally persisted obligation
 // - positions support backward composition, but pipeline steps always execute in encoded order
 // - commands must preserve, transform, settle, or intentionally consume pipeline state
 // - input blocks such as `amount(...)`, `allocation(...)`, and `allowance(...)`
@@ -89,6 +89,7 @@ library Schemas {
 
     string constant Amount = "bytes32 asset, uint amount";
     string constant Balance = "bytes32 asset, uint amount";
+    string constant Debt = "bytes32 liability, uint debt";
     string constant AccountAsset = "bytes32 account, bytes32 asset";
     string constant HostAsset = "uint host, bytes32 asset";
 

package/codec/Specs.sol

@@ -27,6 +27,8 @@ library Sizes {
     uint constant Amount = B64;
     /// @dev BALANCE block: 8 header + 32 asset + 32 amount = 72 bytes
     uint constant Balance = B64;
+    /// @dev DEBT block: 8 header + 32 liability + 32 debt = 72 bytes
+    uint constant Debt = B64;
     /// @dev HOST_ASSET block: 8 header + 32 host + 32 asset = 72 bytes
     uint constant HostAsset = B64;
     /// @dev ALLOCATION/CUSTODY block: 8 header + 32 host + 32 asset + 32 amount = 104 bytes
@@ -63,6 +65,7 @@ library Specs {
     uint constant Empty = uint(bytes32(Keys.Empty));
     uint constant Amount = uint(bytes32(Keys.Amount)) | Exact64;
     uint constant Balance = uint(bytes32(Keys.Balance)) | Exact64;
+    uint constant Debt = uint(bytes32(Keys.Debt)) | Exact64;
     uint constant Allocation = uint(bytes32(Keys.Allocation)) | Exact96;
     uint constant Allowance = uint(bytes32(Keys.Allowance)) | Exact96;
     uint constant Custody = uint(bytes32(Keys.Custody)) | Exact96;

package/codec/Writers.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AssetAmount, AccountAmount, HostAmount, Position, Tx} from "../core/Types.sol";
+import {AssetAmount, AccountAmount, HostAmount, Debt, Position, Tx} from "../core/Types.sol";
 import {Blocks} from "./Blocks.sol";
 import {Buffers} from "./Buffers.sol";
 import {Sizes, Specs} from "./Specs.sol";
@@ -204,6 +204,17 @@ library Writers {
         appendBalance(writer, value.asset, value.amount);
     }
 
+    /// @notice Append a DEBT block.
+    function appendDebt(Writer memory writer, bytes32 liability, uint debt) internal pure {
+        uint i = reserve(writer, Sizes.Debt);
+        Blocks.writeDebt(writer.dst, i, liability, debt);
+    }
+
+    /// @notice Append a structured DEBT value.
+    function appendDebt(Writer memory writer, Debt memory value) internal pure {
+        appendDebt(writer, value.liability, value.debt);
+    }
+
     /// @notice Append an ACCOUNT_ASSET block.
     /// @param writer Destination writer.
     /// @param account Account identifier to encode.

package/commands/Base.sol

@@ -99,10 +99,7 @@ abstract contract CommandBase is CallerAccess, EndpointBase, ReceivedEvent {
         uint descriptor,
         uint batches
     ) internal view returns (Execution memory exec) {
-        bytes32 account;
-        bytes calldata state;
-        bytes calldata input;
-        (account, state, input) = unpackCommandContext(context);
+        (bytes32 account, bytes calldata state, bytes calldata input) = unpackCommandContext(context);
         exec = Executions.open(state, input, descriptor, batches);
         exec.account = account;
     }

package/commands/Debit.sol

@@ -67,11 +67,8 @@ abstract contract DebitAccountInternal is DebitAccount {
     ) internal returns (bytes memory, bytes memory) {
         if (value != 0) revert ValueNotAllowed();
         if (state.length != 0) revert Executions.ZeroStride();
-        if (input.length == 0) revert Blocks.EmptyRun();
-
-        Cur memory cur = Decoders.wrap(input);
-        uint count = input.length / Sizes.Amount;
-        bytes memory output = new bytes(count * Sizes.Balance);
+        Cur memory cur = Decoders.open(input);
+        bytes memory output = new bytes(input.length);
         uint i;
 
         while (cur.more()) {

package/commands/Repay.sol

@@ -5,10 +5,13 @@ import {Execution, Executions, CommandBase, Flags, Lanes, Specs} from "./Base.so
 import {RepayHook} from "../core/Settlement.sol";
 import {Action} from "../annotations/Action.sol";
 import {Actions} from "../utils/Actions.sol";
+import {Blocks} from "../codec/Blocks.sol";
+import {Reader, Readers} from "../codec/Readers.sol";
 
 using Executions for Execution;
+using Readers for Reader;
 
-/// @notice Hook implemented by hosts that repay position liabilities using native value.
+/// @notice Hook implemented by hosts that repay liabilities using native value.
 abstract contract RepayPayableHook {
     /// @notice Override to repay one liability for `account` with a shared value budget.
     /// @param account Account whose liability is being repaid.
@@ -19,21 +22,84 @@ abstract contract RepayPayableHook {
 }
 
 /// @title Repay
-/// @notice Command that repays POSITION liabilities and returns their assets as BALANCE state.
+/// @notice Command that consumes DEBT state by repaying each liability.
 abstract contract Repay is CommandBase, RepayHook, Action {
     uint private immutable descriptor;
+    uint private immutable id;
+
+    constructor() {
+        (id, descriptor) = command("repay", Specs.Debt, Specs.Empty, Specs.Empty, 0, 0);
+        action(id, Actions.Repay);
+    }
+
+    /// @notice Return the registered REPAY command ID.
+    function repayId() internal view returns (uint) {
+        return id;
+    }
+
+    /// @notice Repay each liability in the DEBT state stream.
+    /// @param context Command context carrying the DEBT state stream.
+    /// @return Empty output state.
+    /// @return Empty transaction stream.
+    function repay(
+        bytes calldata context
+    ) external onlyCommand returns (bytes memory, bytes memory) {
+        Execution memory exec = openCommand(context, descriptor, 0);
+
+        while (exec.more()) {
+            (bytes32 liability, uint debt) = exec.unpackDebt(Lanes.State);
+            repay(exec.account, liability, debt);
+        }
+
+        return closeCommand(exec);
+    }
+}
+
+/// @title RepayPayable
+/// @notice Funded command that consumes DEBT state by repaying each liability.
+abstract contract RepayPayable is CommandBase, RepayPayableHook, Action {
+    uint private immutable descriptor;
 
     constructor() {
         uint id;
-        (id, descriptor) = command("repay", Specs.Position, Specs.Empty, Specs.Balance, 0, 0);
-        action(id, Actions.Settle);
+        (id, descriptor) = command("repayPayable", Specs.Debt, Specs.Empty, Specs.Empty, 0, Flags.Funded);
+        action(id, Actions.Repay);
+    }
+
+    /// @notice Repay each liability in the DEBT state stream.
+    /// @param context Command context carrying the DEBT state stream.
+    /// @return Empty output state.
+    /// @return Remaining native value as a refund transaction stream.
+    function repayPayable(
+        bytes calldata context
+    ) external payable onlyCommand returns (bytes memory, bytes memory) {
+        Execution memory exec = openCommand(context, descriptor, 0);
+
+        while (exec.more()) {
+            (bytes32 liability, uint debt) = exec.unpackDebt(Lanes.State);
+            repay(exec.account, liability, debt, exec);
+        }
+
+        return closeCommand(exec);
+    }
+}
+
+/// @title RepayPosition
+/// @notice Command that repays POSITION liabilities and returns their assets as BALANCE state.
+abstract contract RepayPosition is CommandBase, RepayHook, Action {
+    uint private immutable descriptor;
+
+    constructor() {
+        uint id;
+        (id, descriptor) = command("repayPosition", Specs.Position, Specs.Empty, Specs.Balance, 0, 0);
+        action(id, Actions.Repay);
     }
 
     /// @notice Repay each POSITION liability and return its asset as BALANCE state.
     /// @param context Command context carrying the POSITION state stream.
     /// @return BALANCE output state containing each released asset side.
     /// @return Empty transaction stream.
-    function repay(
+    function repayPosition(
         bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
         Execution memory exec = openCommand(context, descriptor, 0);
@@ -48,22 +114,24 @@ abstract contract Repay is CommandBase, RepayHook, Action {
     }
 }
 
-/// @title RepayPayable
+/// @title RepayPositionPayable
 /// @notice Funded command that repays POSITION liabilities and returns their assets as BALANCE state.
-abstract contract RepayPayable is CommandBase, RepayPayableHook, Action {
+abstract contract RepayPositionPayable is CommandBase, RepayPayableHook, Action {
     uint private immutable descriptor;
 
     constructor() {
         uint id;
-        (id, descriptor) = command("repayPayable", Specs.Position, Specs.Empty, Specs.Balance, 0, Flags.Funded);
-        action(id, Actions.Settle);
+        (id, descriptor) = command(
+            "repayPositionPayable", Specs.Position, Specs.Empty, Specs.Balance, 0, Flags.Funded
+        );
+        action(id, Actions.Repay);
     }
 
     /// @notice Repay each POSITION liability and return its asset as BALANCE state.
     /// @param context Command context carrying the POSITION state stream.
     /// @return BALANCE output state containing each released asset side.
     /// @return Remaining native value as a refund transaction stream.
-    function repayPayable(
+    function repayPositionPayable(
         bytes calldata context
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
         Execution memory exec = openCommand(context, descriptor, 0);
@@ -77,3 +145,35 @@ abstract contract RepayPayable is CommandBase, RepayPayableHook, Action {
         return closeCommand(exec);
     }
 }
+
+/// @title RepayInternal
+/// @notice Extends the advertised repay command with memory-state pipeline dispatch.
+/// @dev This adapter is not a separate command. It uses the command ID and repayment hook
+/// inherited from `Repay` while accepting the state location used by `Pipeline`.
+abstract contract RepayInternal is Repay {
+    /// @notice Execute the inherited repay command from an internal pipeline.
+    /// @param account Account whose liabilities are repaid.
+    /// @param state DEBT block stream held in pipeline memory.
+    /// @param input Empty input required by the command schema.
+    /// @param value Native value assigned to the command; must be zero.
+    /// @return output Empty output state.
+    /// @return transactions Empty transaction stream.
+    function executeRepay(
+        bytes32 account,
+        bytes memory state,
+        bytes calldata input,
+        uint128 value
+    ) internal returns (bytes memory, bytes memory) {
+        if (value != 0) revert ValueNotAllowed();
+        if (input.length != 0) revert Executions.ZeroStride();
+        if (state.length == 0) revert Blocks.EmptyRun();
+
+        Reader memory reader = Readers.open(state);
+        while (reader.more()) {
+            (bytes32 liability, uint debt) = reader.unpackDebt();
+            repay(account, liability, debt);
+        }
+
+        return ("", "");
+    }
+}

package/commands/admin/Base.sol

@@ -13,10 +13,7 @@ abstract contract AdminBase is NodeAccess, CommandBase {
         uint descriptor,
         uint batches
     ) internal view returns (Execution memory exec) {
-        bytes32 account;
-        bytes calldata state;
-        bytes calldata input;
-        (account, state, input) = unpackCommandContext(context);
+        (bytes32 account, bytes calldata state, bytes calldata input) = unpackCommandContext(context);
         enforceAdmin(account, msg.sender);
         exec = Executions.open(state, input, descriptor, batches);
         exec.account = account;

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/Pipeline.sol

@@ -3,15 +3,25 @@ pragma solidity ^0.8.33;
 
 import {Decoders, Cur, Readers, Reader} from "../Codec.sol";
 import {PostHook} from "./Settlement.sol";
-import {Budget, Budgets} from "../execution/Budget.sol";
+import {Budgets} from "../execution/Budget.sol";
 
 using Decoders for Cur;
 using Readers for Reader;
-using Budgets for Budget;
+
+/// @notice Hook implemented by hosts that execute encoded step streams.
+abstract contract PipeHook {
+    /// @notice Execute a step stream and return its remaining native-value budget.
+    function pipe(
+        bytes32 account,
+        bytes memory state,
+        bytes calldata steps,
+        uint budget
+    ) internal virtual returns (uint remaining);
+}
 
 /// @title Pipeline
 /// @notice Core pipeline functionality shared by higher-level surfaces.
-abstract contract Pipeline is PostHook {
+abstract contract Pipeline is PipeHook, PostHook {
     /// @dev Thrown when the pipeline finishes with non-empty threaded state.
     error UnexpectedState();
 
@@ -36,18 +46,26 @@ abstract contract Pipeline is PostHook {
 
     /// @notice Execute a STEP block stream through the pipeline.
     /// @dev Reverts with `UnexpectedState` if the final threaded state is non-empty.
-    /// Callers remain responsible for settling any unspent value in `budget`.
+    /// Callers remain responsible for settling the returned unspent value.
     /// @param account Account identifier used for each dispatched step.
     /// @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 {
+    /// @param budget Native-value budget shared across all steps.
+    /// @return remaining Native value remaining after every step executes.
+    function pipe(
+        bytes32 account,
+        bytes memory state,
+        bytes calldata steps,
+        uint budget
+    ) internal virtual override returns (uint remaining) {
         Cur memory cur = Decoders.open(steps);
 
         while (cur.more()) {
             (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
+            uint128 value;
+            (budget, value) = Budgets.useResourceValue(budget, resources);
             Reader memory txs;
-            (state, txs.source) = dispatch(cmd, account, state, input, budget.useResourceValue(resources));
+            (state, txs.source) = dispatch(cmd, account, state, input, value);
 
             while (txs.more()) {
                 (bytes32 from, bytes32 to, bytes32 asset, uint amount) = txs.unpackTransaction();
@@ -56,5 +74,6 @@ abstract contract Pipeline is PostHook {
         }
 
         if (state.length != 0) revert UnexpectedState();
+        return budget;
     }
 }

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/execution/Budget.sol

@@ -29,6 +29,15 @@ library Budgets {
         return value;
     }
 
+    /// @notice Deduct an exact native value from a scalar budget.
+    /// @param budget Remaining native value in wei.
+    /// @param value Native value to consume in wei.
+    /// @return remaining Native value remaining after the deduction.
+    function useValue(uint budget, uint value) internal pure returns (uint remaining) {
+        if (value > budget) revert InsufficientValue();
+        remaining = budget - 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.
@@ -38,6 +47,19 @@ library Budgets {
         return uint128(useValue(budget, uint128(resources)));
     }
 
+    /// @notice Deduct the EVM value lane of `resources` from a scalar budget.
+    /// @param budget Remaining native value in wei.
+    /// @param resources Packed resources whose low 128 bits contain native value.
+    /// @return remaining Native value remaining after the deduction.
+    /// @return value Native value consumed from the budget.
+    function useResourceValue(
+        uint budget,
+        uint resources
+    ) internal pure returns (uint remaining, uint128 value) {
+        value = uint128(resources);
+        remaining = useValue(budget, value);
+    }
+
     /// @notice Remove and return all remaining value from `budget`.
     /// @param budget Mutable budget to drain.
     /// @return value Native value removed from the budget.

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";
@@ -246,6 +246,20 @@ library Executions {
         exec.decoders = cur.seekAbs(end);
     }
 
+    /// @notice Validate a known key and consume the next block from an execution decoder lane.
+    /// @dev Validates no payload-size constraint beyond proving the complete block
+    /// lies within the selected lane's logical region.
+    /// @param exec Execution whose selected decoder cursor is advanced over the complete block.
+    /// @param lane Execution decoder lane to select.
+    /// @param key Expected block key.
+    /// @return abs Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function consume(Execution memory exec, uint8 lane, bytes4 key) internal pure returns (uint abs, uint end) {
+        uint cur = exec.decoders.select(lane);
+        (abs, end) = Blocks.expectKey(cur.absolute(), key);
+        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.
@@ -256,7 +270,7 @@ library Executions {
         uint8 lane,
         bytes4 key
     ) internal pure returns (bytes calldata data) {
-        (uint abs, uint end) = consume(exec, lane, Specs.create(key, 0, 0, 0));
+        (uint abs, uint end) = consume(exec, lane, key);
         data = msg.data[abs - Sizes.Header:end];
     }
 
@@ -528,6 +542,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,
@@ -990,6 +1016,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,
@@ -1380,13 +1417,20 @@ library Executions {
     // Value and transaction writing
     // -------------------------------------------------------------------------
 
+    /// @notice Remove and return the remaining execution value budget.
+    /// @param exec Execution whose budget is drained.
+    /// @return budget Native value removed from the execution.
+    function drainBudget(Execution memory exec) internal pure returns (uint budget) {
+        budget = exec.budget;
+        exec.budget = 0;
+    }
+
     /// @notice Transfer the remaining value budget out of an execution.
     /// @dev Clears `exec.budget` so the returned budget becomes its sole owner.
     /// @param exec Execution whose budget is detached.
     /// @return budget Detached budget containing the remaining value.
     function takeBudget(Execution memory exec) internal pure returns (Budget memory budget) {
-        budget.remaining = exec.budget;
-        exec.budget = 0;
+        budget.remaining = drainBudget(exec);
     }
 
     /// @notice Deduct an exact native value from the execution budget.

package/package.json

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