@rootzero/contracts 1.23.0 → 1.25.0

package/CHANGELOG.md

@@ -3,6 +3,84 @@
 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.25.0
+
+### Breaking Changes
+
+- Changed `Pipeline.pipe` to accept a scalar `uint` budget and return the
+  remaining scalar budget. The standalone mutable `Budget` type remains
+  available for other funded execution flows.
+- Split the pipeline hook from its standard implementation. `PipePayablePort`
+  now inherits only `PipeHook`; hosts that want the built-in pipeline must
+  compose `Pipeline` explicitly, while custom hosts may implement the hook
+  without inheriting the standard dispatch and posting implementation.
+- Changed `Decoders.open` to wrap the complete non-empty calldata source as an
+  ungrouped cursor. Code that needs the former counted first-homogeneous-run
+  behavior must use the new `Decoders.batch` helper.
+
+### Added
+
+- Added scalar `Budgets.useValue` and `Budgets.useResourceValue` overloads, and
+  `Executions.drainBudget` for transferring an execution budget as a `uint`.
+- Added `PipeHook` to the `Core.sol` and `Endpoints.sol` package barrels.
+- Added `Blocks.expectKey` and key-only `Decoders.consume` and
+  `Executions.consume` overloads for validating blocks whose payload shape is
+  established by specialized decoding logic.
+- Added `Blocks.require1`, `require2`, `require4`, `require8`, and `require16`,
+  completing the fixed-width validation family alongside `require32`.
+
+### Changed
+
+- Specialized built-in composite block unpackers to validate their known keys
+  directly instead of constructing and evaluating generic specifications.
+- Specialized fixed-width block validation, empty-block inspection, and
+  key-only `takeBlock` paths to avoid redundant specification and calldata
+  work.
+- Pipeline execution now validates the complete STEP source and rejects a
+  trailing block with a different key instead of silently stopping after the
+  first homogeneous run.
+- Simplified internal debit-account output allocation to use the fixed-width
+  input size directly.
+
+## 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,18 +7,18 @@ 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";
 import { Admins, CommandHost, Guardians, Host, HostIntroduction, IHostIntroduction } from "./core/Host.sol";
 import { CommandCalls, FailedCall, NodeCalls, PortCalls, RawNodeCalls } from "./core/Calls.sol";
 import { EndpointBase, InputEndpointBase } from "./core/Endpoint.sol";
-import { Pipeline } from "./core/Pipeline.sol";
+import { PipeHook, 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

@@ -6,6 +6,7 @@ pragma solidity ^0.8.33;
 
 // Shared endpoint hooks
 import {Flags} from "./codec/Descriptors.sol";
+import {PipeHook} from "./core/Pipeline.sol";
 import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook} from "./core/Settlement.sol";
 
 // Commands
@@ -18,7 +19,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).
 
@@ -360,13 +366,15 @@ running the next step. This is the core of `Pipeline.pipe`:
 ```solidity
 while (cur.more()) {
     (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
+    uint128 value;
+    (budget, value) = Budgets.useResourceValue(budget, resources);
     Reader memory transactions;
     (state, transactions.source) = dispatch(
         cmd,
         account,
         state,
         input,
-        budget.useResourceValue(resources)
+        value
     );
     while (transactions.more()) {
         (bytes32 from, bytes32 to, bytes32 asset, uint amount) = transactions.unpackTransaction();
@@ -376,6 +384,9 @@ while (cur.more()) {
 if (state.length != 0) revert UnexpectedState();
 ```
 
+`Pipeline.pipe` takes the available native-value budget as a `uint` and returns
+the remaining budget after every step has executed.
+
 A transfer, for instance, is a two-step pipeline: `debitAccount` turns an
 `#amount` input into `#balance` state, and `payout` consumes that state
 toward a recipient. Because a pipeline is just blocks, it is also the unit of
@@ -384,12 +395,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
@@ -476,11 +487,11 @@ names, access sets, balances — from logs alone, with no artifact files.
 Import from the package entry points rather than deep paths:
 
 - `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
-  `Settlement`, `Pipeline`, `Portal`, validator
+  `Settlement`, `PipeHook`, `Pipeline`, `Portal`, validator
 - `@rootzero/contracts/Commands.sol` — `CommandBase`, `Execution`, `Flags`,
   codec helpers, and shared value types for authoring custom commands
 - `@rootzero/contracts/Endpoints.sol` — command, admin, port, guard, and query
-  mixins, their hooks, and `Flags`
+  mixins, their hooks (including `PipeHook`), and `Flags`
 - `@rootzero/contracts/Codec.sol` — `Blocks`, calldata `Cur`/`Cursors`, memory
   `Reader`/`Readers`, `Writers`, `Schemas`, `Descriptors`, `Flags`, `Keys`, and
   `Specs`

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

@@ -100,16 +100,33 @@ library Blocks {
         end = body + len;
     }
 
+    /// @notice Validate a known block key and return its payload bounds.
+    /// @dev DANGER: This performs an unchecked calldata read and validates only
+    /// the key. The caller must validate the known payload shape and returned end.
+    /// @param abs Absolute calldata position of the header.
+    /// @param key Expected block key.
+    /// @return body Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function expectKey(uint abs, bytes4 key) internal pure returns (uint body, uint end) {
+        uint len = header(abs, key);
+        unchecked {
+            body = abs + Sizes.Header;
+            end = body + len;
+        }
+    }
+
     /// @dev Validate the key and exact payload size of a fixed-width block.
     /// @param abs Absolute calldata position of the header.
-    /// @param spec Expected block specification.
+    /// @param key Expected block key.
     /// @param size Expected payload length.
     /// @return body Absolute position of the payload.
     /// @return end Absolute position after the payload.
-    function expectFixed(uint abs, uint spec, uint size) private pure returns (uint body, uint end) {
-        if (header(abs, Specs.key(spec)) != size) revert InvalidBlock();
-        body = abs + Sizes.Header;
-        end = body + size;
+    function expectFixed(uint abs, bytes4 key, uint size) private pure returns (uint body, uint end) {
+        if (header(abs, key) != size) revert InvalidBlock();
+        unchecked {
+            body = abs + Sizes.Header;
+            end = body + size;
+        }
     }
 
     /// @notice Validate an empty block at an absolute calldata position.
@@ -139,8 +156,9 @@ library Blocks {
     /// @param key Expected block key.
     /// @return Whether the expected key occurs with a zero-length payload.
     function isEmpty(uint abs, uint end, bytes4 key) internal pure returns (bool) {
-        if (!hasAt(abs, end, key)) return false;
-        return uint32(uint(read32(abs)) >> 192) == 0;
+        if (abs > end || Sizes.Header > end - abs) return false;
+        uint head = uint(read32(abs));
+        return uint32(head >> 224) == uint32(key) && uint32(head >> 192) == 0;
     }
 
     /// @notice Find the first block with `key` at or after absolute position `abs`.
@@ -382,6 +400,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 +1048,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.
@@ -1034,6 +1098,46 @@ library Blocks {
         }
     }
 
+    /// @notice Require the byte at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected byte.
+    function require1(uint abs, bytes1 expected) internal pure {
+        if (read1(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the two bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected two-byte value.
+    function require2(uint abs, bytes2 expected) internal pure {
+        if (read2(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the four bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected four-byte value.
+    function require4(uint abs, bytes4 expected) internal pure {
+        if (read4(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the eight bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected eight-byte value.
+    function require8(uint abs, bytes8 expected) internal pure {
+        if (read8(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the sixteen bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected sixteen-byte value.
+    function require16(uint abs, bytes16 expected) internal pure {
+        if (read16(abs) != expected) revert UnexpectedValue();
+    }
+
     /// @notice Require the word at an absolute calldata position to match `expected`.
     /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
     /// @param abs Absolute calldata position.
@@ -1060,7 +1164,7 @@ library Blocks {
     /// @return a First payload word.
     /// @return end Absolute position after the block.
     function unpack32(uint abs, uint spec) internal pure returns (bytes32 a, uint end) {
-        (abs, end) = expectFixed(abs, spec, 32);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 32);
         a = read32(abs);
     }
 
@@ -1071,7 +1175,7 @@ library Blocks {
     /// @return b Second payload word.
     /// @return end Absolute position after the block.
     function unpack64(uint abs, uint spec) internal pure returns (bytes32 a, bytes32 b, uint end) {
-        (abs, end) = expectFixed(abs, spec, 64);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 64);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1089,7 +1193,7 @@ library Blocks {
         uint abs,
         uint spec
     ) internal pure returns (bytes32 a, bytes32 b, bytes32 c, uint end) {
-        (abs, end) = expectFixed(abs, spec, 96);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 96);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1109,7 +1213,7 @@ library Blocks {
         uint abs,
         uint spec
     ) internal pure returns (bytes32 a, bytes32 b, bytes32 c, bytes32 d, uint end) {
-        (abs, end) = expectFixed(abs, spec, 128);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 128);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1131,7 +1235,7 @@ library Blocks {
         uint abs,
         uint spec
     ) internal pure returns (bytes32 a, bytes32 b, bytes32 c, bytes32 d, bytes32 e, uint end) {
-        (abs, end) = expectFixed(abs, spec, 160);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 160);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1322,6 +1426,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.
@@ -1591,7 +1711,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint entity, bytes calldata stream, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Annotation);
+        (abs, limit) = expectKey(abs, Keys.Annotation);
         assembly ("memory-safe") {
             entity := calldataload(abs)
         }
@@ -1609,7 +1729,7 @@ library Blocks {
         uint abs
     ) internal pure returns (bytes32 account, bytes calldata state, bytes calldata input, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Context);
+        (abs, limit) = expectKey(abs, Keys.Context);
         assembly ("memory-safe") {
             account := calldataload(abs)
         }
@@ -1630,7 +1750,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint cmd, uint resources, bytes calldata input, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Step);
+        (abs, limit) = expectKey(abs, Keys.Step);
         assembly ("memory-safe") {
             cmd := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1649,7 +1769,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint target, uint resources, bytes calldata payload, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Call);
+        (abs, limit) = expectKey(abs, Keys.Call);
         assembly ("memory-safe") {
             target := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1668,7 +1788,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint portal, uint resources, bytes calldata input, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Relay);
+        (abs, limit) = expectKey(abs, Keys.Relay);
         assembly ("memory-safe") {
             portal := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1687,7 +1807,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint portal, uint resources, bytes calldata payload, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Dispatch);
+        (abs, limit) = expectKey(abs, Keys.Dispatch);
         assembly ("memory-safe") {
             portal := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1703,7 +1823,7 @@ library Blocks {
     /// @return end Absolute position after the block.
     function unpackLabel(uint abs) internal pure returns (bytes32 namespace, string memory name, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Label);
+        (abs, limit) = expectKey(abs, Keys.Label);
         assembly ("memory-safe") {
             namespace := calldataload(abs)
         }
@@ -1721,7 +1841,7 @@ library Blocks {
     /// @return end Absolute position after the block.
     function unpackSchema(uint abs) internal pure returns (uint spec, string memory body, bytes32 name, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Schema);
+        (abs, limit) = expectKey(abs, Keys.Schema);
         assembly ("memory-safe") {
             spec := calldataload(abs)
         }
@@ -1748,7 +1868,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint handler, uint resources, bytes32 key, bytes calldata witness, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Recover);
+        (abs, limit) = expectKey(abs, Keys.Recover);
         assembly ("memory-safe") {
             handler := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1919,6 +2039,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.