@rootzero/contracts 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+Add all changes made after a release to `Unreleased`. Published version
+sections are immutable and must continue to describe the tagged release.
+
+## Unreleased
+
+## 1.24.0
+
+### Breaking Changes
+
+- Renamed the existing `Position`-consuming `repay` and `repayPayable`
+  commands to `repayPosition` and `repayPositionPayable`. Their state
+  transition remains `Position` to `Balance`; the new commands using the old
+  names consume `Debt` and return empty state. Command selectors and node IDs
+  for position repayment therefore change.
+
+### Added
+
+- Added the standalone `Debt { liability, debt }` pipeline state, its standard
+  block key and schema, and codec support across blocks, readers, writers,
+  decoders, and execution helpers.
+- Added `repay` and `repayPayable` commands that consume `Debt` state and return
+  empty state.
+- Added `RepayInternal` for dispatching the non-funded `repay` command directly
+  against memory-backed pipeline state.
+- Added unchecked `Blocks.read1`, `read2`, `read8`, and `read16` absolute
+  calldata helpers, completing the power-of-two family alongside `read4` and
+  `read32`.
+- Added the standalone `ensureContract` utility and shared `InvalidContract`
+  error for uniformly requiring addresses with deployed bytecode.
+- Added the free `enforceSender` access helper for requiring an exact
+  `msg.sender` with the shared `AccessDenied` error.
+- Documented descriptor flag bits 6 and 7 as endpoint-defined custom flags;
+  bits 2 through 5 remain reserved for future protocol flags.
+
+### Changed
+
+- Repayment commands now publish the canonical `Actions.Repay` annotation
+  instead of `Actions.Settle`.
+
 ## 1.23.0
 
 ### Breaking Changes

package/Codec.sol

@@ -4,7 +4,7 @@ pragma solidity ^0.8.33;
 // Aggregator: re-exports the complete block encoding and decoding surface.
 // Import this file for low-level codec extensions and direct stream processing.
 
-import { AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
+import { AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Debt, Position, Tx } from "./core/Types.sol";
 import { Keys } from "./codec/Keys.sol";
 import { Sizes, Specs } from "./codec/Specs.sol";
 import { Descriptors, Flags } from "./codec/Descriptors.sol";

package/Commands.sol

@@ -12,4 +12,4 @@ import {Blocks} from "./codec/Blocks.sol";
 import {Sizes, Specs} from "./codec/Specs.sol";
 import {Decoders} from "./codec/Decoders.sol";
 import {Cursors, Cur} from "./utils/Cursors.sol";
-import {AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx} from "./core/Types.sol";
+import {AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Debt, Position, Tx} from "./core/Types.sol";

package/Core.sol

@@ -7,7 +7,7 @@ pragma solidity ^0.8.33;
 import { Action } from "./annotations/Action.sol";
 import { Label } from "./annotations/Label.sol";
 import { Schema } from "./annotations/Schema.sol";
-import { AccessDenied, AdminAccess, CallerAccess, CommanderAccess, CommanderNotAllowed, GuardianAccess, NodeAccess, TrustAccess } from "./core/Access.sol";
+import { AccessDenied, AdminAccess, CallerAccess, CommanderAccess, CommanderNotAllowed, enforceSender, GuardianAccess, NodeAccess, TrustAccess } from "./core/Access.sol";
 import { Balances, InsufficientFunds } from "./core/Balances.sol";
 import { Escrows, InsufficientEscrow } from "./core/Escrows.sol";
 import { NativeAsset, Runtime } from "./core/Runtime.sol";
@@ -18,7 +18,7 @@ import { Pipeline } from "./core/Pipeline.sol";
 import { Budget, Budgets } from "./execution/Budget.sol";
 import { CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook, Settlement } from "./core/Settlement.sol";
 import { Portal } from "./core/Portal.sol";
-import { AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
+import { AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Debt, Position, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
 
 

package/Endpoints.sol

@@ -18,7 +18,14 @@ import {Deposit, DepositHook, DepositPayable, DepositPayableHook} from "./comman
 import {Payout, PayoutHook} from "./commands/Payout.sol";
 import {Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook} from "./commands/Provision.sol";
 import {RecoverPayable, RecoverPayableHook} from "./commands/Recover.sol";
-import {Repay, RepayPayable, RepayPayableHook} from "./commands/Repay.sol";
+import {
+    Repay,
+    RepayInternal,
+    RepayPayable,
+    RepayPayableHook,
+    RepayPosition,
+    RepayPositionPayable
+} from "./commands/Repay.sol";
 import {RelayPayable, RelayBalancePayable, RelayPayableHook} from "./commands/Relay.sol";
 import {Settle, SettlePayable, SettlePayableHook, SettleInternal} from "./commands/Settle.sol";
 import {Withdraw, WithdrawHook} from "./commands/Withdraw.sol";

package/README.md

@@ -265,22 +265,24 @@ and return it, forward it intact, or revert. A command must never succeed while
 silently ignoring or dropping supplied state. Commands that declare
 `Specs.Empty` state therefore reject any non-empty state, while commands that
 accept state validate the complete stream against their declared state schema.
-This is especially important for `#position`, because dropping a position could
-silently discard both live value and an outstanding debt requirement.
-
-The input carries instructions; the state carries live value. While a
-sequence of commands executes, `#balance`, `#custody`, and `#position` blocks
-in the state are the value being moved — produced by one command, consumed by
-the next. A position carries an asset-liability pair as
+This is especially important for `#debt` and `#position`, because dropping
+either could silently discard an outstanding debt requirement.
+
+The input carries instructions; the state carries live value. While a sequence
+of commands executes, `#balance`, `#debt`, `#custody`, and `#position` blocks in
+the state are the value being moved — produced by one command, consumed by the
+next. Balance carries `{ asset, amount }`, debt carries `{ liability, debt }`,
+and position carries their flat combination
 `{ asset, amount, liability, debt }`.
 
-`#position` is general live state rather than a lending-specific debt record.
-It pairs value acquired or controlled with value owed or required. A command
-may preserve or replace either side and return the resulting position for the
-next step; `settle` terminally consumes the pair. This supports swaps,
+`#debt` and `#position` are general live state rather than persisted
+lending-specific debt records. Debt carries value owed or required; position
+pairs that liability with value acquired or controlled. A command may preserve
+or replace either side and return the resulting state for the next step;
+`settle` terminally consumes a position pair. This supports swaps,
 borrowing, refinancing, collateral changes, callback obligations, cross-host
-claims, fees, netting, and other multi-step operations. A position is a
-transient representation and does not itself create or erase an obligation
+claims, fees, netting, and other multi-step operations. Debt and position are
+transient representations and do not themselves create or erase an obligation
 recorded by an external system.
 
 The standard `Deposit` mixin shows the canonical shape: open and validate both
@@ -330,7 +332,9 @@ abstract contract MyCommand is CommandBase {
 
 The final argument is a packed flags byte. Pass `0` for an ordinary endpoint,
 or compose values such as `Flags.Funded`, `Flags.Admin`, and
-`Flags.AdminFunded` from the command or endpoint package entry point.
+`Flags.AdminFunded` from the command or endpoint package entry point. Bits 6
+and 7 are reserved for endpoint-defined custom flags. Bits 2 through 5 remain
+reserved for future protocol flags.
 
 The standard commands cover the common ledger movements: `deposit` and
 `depositPayable` (external funds in), `settlePayable` (funded settlement),
@@ -338,7 +342,9 @@ The standard commands cover the common ledger movements: `deposit` and
 `debitAccount` and `creditAccount` (internal movements), `payout` (deliver
 state to other accounts), `allocate` (turn balance state into custody),
 `provision` (provision custody from an external allocation), `settle` (consume
-asset-liability position state), `relayPayable` (relay a pipeline without
+asset-liability position state), `repay` and `repayPayable` (consume standalone
+debt state), `repayPosition` and `repayPositionPayable` (repay a position's debt
+and return its asset as balance state), `relayPayable` (relay a pipeline without
 state), and `relayBalancePayable` (relay balance state and a pipeline to another
 portal).
 
@@ -384,12 +390,12 @@ portal adapter (on EVM, the low 128 bits are native value in wei, drawn from a
 shared budget), so the same pipeline bytes are meaningful to every port.
 
 Hosts that implement a pipeline locally can inherit `DebitAccountInternal`,
-`CreditAccountInternal`, and `SettleInternal` to advertise the canonical command
-endpoints while routing their local command IDs through `executeDebitAccount`,
-`executeCreditAccount`, and `executeSettle`. These adapters consume the
-memory-backed pipeline state directly and avoid an external self-call. Pass the
-step value into each adapter; all three reject nonzero value because the
-commands are non-funded.
+`CreditAccountInternal`, `SettleInternal`, and `RepayInternal` to advertise the
+canonical command endpoints while routing their local command IDs through
+`executeDebitAccount`, `executeCreditAccount`, `executeSettle`, and
+`executeRepay`. These adapters consume the memory-backed pipeline state directly
+and avoid an external self-call. Pass the step value into each adapter; all four
+reject nonzero value because the commands are non-funded.
 
 Positions also support backward-composed pipelines. In an exact-output route,
 the asset side can represent the desired result while the liability side

package/Utils.sol

@@ -12,7 +12,7 @@ import { ECDSA } from "./utils/ECDSA.sol";
 import { Ids } from "./utils/Ids.sol";
 import { Nodes } from "./utils/Nodes.sol";
 import { Layout } from "./utils/Layout.sol";
-import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, clear8, clear16, clear32, clear64, divisible, ensureAddr, hash32, intToBytes32, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, replace8, replace16, replace32, replace64, retryTicket, toLocalBase, toUnspecifiedBase, ValueOverflow, ZeroAddress } from "./utils/Utils.sol";
+import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, clear8, clear16, clear32, clear64, divisible, ensureAddr, ensureContract, hash32, intToBytes32, InvalidContract, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, replace8, replace16, replace32, replace64, retryTicket, toLocalBase, toUnspecifiedBase, ValueOverflow, ZeroAddress } from "./utils/Utils.sol";
 
 
 

package/annotations/Schema.sol

@@ -18,13 +18,7 @@ abstract contract Schema is Runtime, AnnotationEvent {
     /// @param hint Initial per-block payload capacity.
     /// @param body Schema DSL string describing the block payload body.
     /// @return spec The context-local block specification.
-    function schema(
-        uint32 key,
-        uint32 min,
-        uint32 max,
-        uint32 hint,
-        string memory body
-    ) internal returns (uint spec) {
+    function schema(uint32 key, uint32 min, uint32 max, uint32 hint, string memory body) internal returns (uint spec) {
         return schema(key, min, max, hint, body, bytes32(0));
     }
 

package/codec/Blocks.sol

@@ -382,6 +382,22 @@ library Blocks {
         }
     }
 
+    /// @notice Write a DEBT block at `i`.
+    /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B64` bytes first.
+    /// @param dst Destination buffer.
+    /// @param i Relative write position.
+    /// @param liability Liability identifier to encode.
+    /// @param debt Debt quantity to encode.
+    function writeDebt(bytes memory dst, uint i, bytes32 liability, uint debt) internal pure {
+        uint spec = Specs.Debt;
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, spec)
+            mstore(add(p, 0x08), liability)
+            mstore(add(p, 0x28), debt)
+        }
+    }
+
     /// @notice Write a HOST_ASSET block at `i`.
     /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B64` bytes first.
     /// @param dst Destination buffer.
@@ -1014,14 +1030,44 @@ library Blocks {
 
     // Raw reads
 
+    /// @notice Read one byte from an absolute calldata position.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @return value Decoded one-byte value.
+    function read1(uint abs) internal pure returns (bytes1 value) {
+        return bytes1(read32(abs));
+    }
+
+    /// @notice Read two bytes from an absolute calldata position.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @return value Decoded two-byte value.
+    function read2(uint abs) internal pure returns (bytes2 value) {
+        return bytes2(read32(abs));
+    }
+
     /// @notice Read four bytes from an absolute calldata position.
     /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
     /// @param abs Absolute calldata position.
     /// @return value Decoded four-byte value.
     function read4(uint abs) internal pure returns (bytes4 value) {
-        assembly ("memory-safe") {
-            value := calldataload(abs)
-        }
+        return bytes4(read32(abs));
+    }
+
+    /// @notice Read eight bytes from an absolute calldata position.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @return value Decoded eight-byte value.
+    function read8(uint abs) internal pure returns (bytes8 value) {
+        return bytes8(read32(abs));
+    }
+
+    /// @notice Read sixteen bytes from an absolute calldata position.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @return value Decoded sixteen-byte value.
+    function read16(uint abs) internal pure returns (bytes16 value) {
+        return bytes16(read32(abs));
     }
 
     /// @notice Read one word from an absolute calldata position.
@@ -1322,6 +1368,22 @@ library Blocks {
         }
     }
 
+    /// @notice Decode a low-level fixed-width DEBT block at `abs`.
+    /// @param abs Absolute block position.
+    /// @return liability Decoded liability identifier.
+    /// @return debt Decoded debt quantity.
+    function unpackDebt(uint abs) internal pure returns (bytes32 liability, uint debt) {
+        uint head;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+        }
+        if (head >> 192 != Specs.Debt >> 192) revert InvalidBlock();
+        assembly ("memory-safe") {
+            liability := calldataload(add(abs, 0x08))
+            debt := calldataload(add(abs, 0x28))
+        }
+    }
+
     /// @notice Decode a low-level fixed-width ACCOUNT_ASSET block at `abs`.
     /// @param abs Absolute block position.
     /// @return account Decoded account identifier.
@@ -1919,6 +1981,15 @@ library Blocks {
         writeBalance(value, 0, asset, amount);
     }
 
+    /// @notice Encode a DEBT block.
+    /// @param liability Liability identifier.
+    /// @param debt Debt quantity.
+    /// @return value Encoded DEBT block bytes.
+    function createDebt(bytes32 liability, uint debt) internal pure returns (bytes memory value) {
+        value = allocate(Sizes.Debt);
+        writeDebt(value, 0, liability, debt);
+    }
+
     /// @notice Encode a CUSTODY block.
     /// @param host Host node ID holding the custody.
     /// @param asset Asset identifier.

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";
@@ -427,6 +427,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 +624,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/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/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/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/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";
@@ -528,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,
@@ -990,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.23.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/utils/Utils.sol

@@ -10,6 +10,8 @@ error ValueOverflow();
 error NotDivisible();
 /// @dev Thrown when an ID claims to carry an address but the embedded address is zero.
 error ZeroAddress();
+/// @dev Thrown when an address does not contain deployed bytecode.
+error InvalidContract();
 
 /// @notice Assert that `value` fits in uint8 and return it as uint8.
 function max8(uint value) pure returns (uint8) {
@@ -146,6 +148,14 @@ function ensureAddr(address addr) pure returns (address) {
     return addr;
 }
 
+/// @notice Assert that `target` contains deployed bytecode and return it unchanged.
+/// @dev Rejects EOAs, zero and future deployment addresses, contracts currently
+/// under construction, and precompiles whose code length is zero.
+function ensureContract(address target) view returns (address) {
+    if (target.code.length == 0) revert InvalidContract();
+    return target;
+}
+
 /// @notice Convert a signed integer to its 32-byte two's-complement representation.
 function intToBytes32(int value) pure returns (bytes32) {
     return bytes32(uint(value));