@rootzero/contracts 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -3,6 +3,64 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.16.0
+
+### Breaking Changes
+
+- Removed the unused generic `Position` event and `PositionEvent` base contract.
+- Renamed transaction handling from settlement to posting: the transaction
+  helper is now `post(...)`, and `portSettle(bytes)` is now `portPost(bytes)`.
+  The port selector and node ID change, and its action is now `Actions.Post`
+  (`14`) instead of `Actions.Settle` (`3`). The `Settlement` convenience base
+  implements both the transaction `PostHook` and position `SettleHook`.
+- Removed `openInput` from `EndpointBase`. Port, query, and guard bases expose
+  `openInput` through the input-only `InputEndpointBase`, while custom commands
+  must pass both state and input through `openCommand`.
+- Removed the wildcard `Specs.Any` state type. The stateful relay is now
+  `relayBalancePayable` and accepts `BALANCE` state blocks; `relayPayable`
+  explicitly accepts empty state.
+- Renamed the numeric `Position` fields from `assets` and `liabilities` to
+  `amount` and `debt`.
+- Renamed `Budget.use` to `useResourceValue` and split execution spending into
+  exact `useValue` and packed-resource `useResourceValue` helpers.
+- Renamed `RoutePayableHook.route` to `RelayPayableHook.relayTo`. Recovery hooks
+  are now `RecoverPayableHook` implementations that receive the complete
+  resource word and mutable execution budget.
+
+### Added
+
+- Added the hostless `#position` state block for threading asset-liability pairs
+  between pipeline commands.
+- Added the `settle` command, the position `SettleHook`, and the transaction
+  `PostHook`. The `Settlement` convenience base provides default implementations
+  of both through the debit and credit account hooks.
+- Added `relayBalancePayable` for relaying required `BALANCE` state while
+  `relayPayable` now explicitly relays with empty state.
+- Added memory-backed `InternalDebitAccount`, `InternalCreditAccount`, and
+  `InternalSettle` adapters for hosts that execute canonical commands directly
+  from their pipeline dispatcher.
+
+### Changed
+
+- Documented the command state-safety invariant: every command must handle the
+  complete supplied state stream or revert, and commands with empty state lanes
+  must reject non-empty state.
+- Endpoint decoder opening now requires the complete supplied lane to be one
+  homogeneous run of the descriptor's declared key; trailing block types are
+  rejected instead of silently left outside the decoder cursor.
+- Block runs and cursors now retain raw block counts only. Descriptor stride
+  conversion and state/input group reconciliation happen once in execution
+  opening rather than in `Blocks` or `Cursors`.
+- Pipeline transaction streams are posted before the next step, and position
+  state is settled separately through the scalar asset, amount, liability, and
+  debt hook.
+
+### Upgrade Compatibility
+
+- Command and port selectors, block schemas, and hook signatures changed in
+  this release. Deploy fresh hosts and update pipeline builders and peer
+  integrations together.
+
 ## 1.15.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, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
+import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
 import { Keys } from "./codec/Keys.sol";
 import { Sizes, Specs } from "./codec/Specs.sol";
 import { Descriptors } from "./codec/Descriptors.sol";

package/Commands.sol

@@ -11,4 +11,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, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx} from "./core/Types.sol";
+import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx} from "./core/Types.sol";

package/Core.sol

@@ -16,9 +16,9 @@ import { CommandCalls, FailedCall, NodeCalls, PortCalls, RawNodeCalls } from "./
 import { EndpointBase } from "./core/Endpoint.sol";
 import { Pipeline } from "./core/Pipeline.sol";
 import { Budget, Budgets } from "./execution/Budget.sol";
-import { CreditAccountHook, DebitAccountHook, Settlement } from "./core/Settlement.sol";
+import { CreditAccountHook, DebitAccountHook, PostHook, SettleHook, Settlement } from "./core/Settlement.sol";
 import { Portal } from "./core/Portal.sol";
-import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
+import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
 
 

package/Endpoints.sol

@@ -5,7 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file to inherit from the full rootzero callable host surface without managing individual paths.
 
 // Shared endpoint hooks
-import { CreditAccountHook, DebitAccountHook } from "./core/Settlement.sol";
+import { CreditAccountHook, DebitAccountHook, PostHook, SettleHook } from "./core/Settlement.sol";
 
 // Commands
 import { Allocate, AllocateHook } from "./commands/Allocate.sol";
@@ -15,8 +15,9 @@ import { DebitAccount } from "./commands/Debit.sol";
 import { Deposit, DepositHook, DepositPayable, DepositPayableHook } from "./commands/Deposit.sol";
 import { Payout, PayoutHook } from "./commands/Payout.sol";
 import { Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook } from "./commands/Provision.sol";
-import { RecoverHook, RecoverPayable } from "./commands/Recover.sol";
-import { RelayPayable, RoutePayableHook } from "./commands/Relay.sol";
+import { RecoverPayable, RecoverPayableHook } from "./commands/Recover.sol";
+import { RelayPayable, RelayBalancePayable, RelayPayableHook } from "./commands/Relay.sol";
+import { Settle } from "./commands/Settle.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands
@@ -41,7 +42,7 @@ import { PortDebitAccount } from "./ports/Debit.sol";
 import { PortDenyAssets } from "./ports/DenyAssets.sol";
 import { PortPipePayable } from "./ports/Pipe.sol";
 import { PortDispatchPayable } from "./ports/Dispatch.sol";
-import { PortSettle } from "./ports/Settle.sol";
+import { PortPost } from "./ports/Post.sol";
 
 // Guard endpoints
 import { GuardBase } from "./guards/Base.sol";

package/Events.sol

@@ -11,7 +11,6 @@ import { BalanceEvent } from "./events/Balance.sol";
 import { CommanderEvent } from "./events/Commander.sol";
 import { DispatchEvent } from "./events/Dispatch.sol";
 import { EndpointEvent } from "./events/Endpoint.sol";
-import { PositionEvent } from "./events/Position.sol";
 import { ReceivedEvent } from "./events/Received.sol";
 import { RecoveredEvent } from "./events/Recovered.sol";
 import { EventEmitter } from "./events/Emitter.sol";

package/README.md

@@ -149,7 +149,7 @@ const input = concat([
 ```
 
 Everything downstream keeps this shape: commands loop over input blocks,
-settlement loops over transactions, pipelines loop over steps. Batching is
+posting loops over transactions, pipelines loop over steps. Batching is
 never a special case.
 
 ## IDs, Accounts, Assets, and Nodes
@@ -248,30 +248,51 @@ struct CommandContext {
 
 Every command returns two block streams: `state`, which is threaded into the
 next pipeline step, and `transactions`, which contains `#transaction` blocks
-for the pipeline host to settle outside the state lane. Either stream may be
+for the pipeline host to post outside the state lane. Either stream may be
 empty.
 
-The input carries instructions; the state carries live value. While a
-sequence of commands executes, `#balance` and `#custody` blocks in the state
-are the funds being moved — produced by one command, consumed by the next.
+State is linear, not optional ambient context. A command is responsible for
+the entire state stream it receives: it must validate and consume it, transform
+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 standard `Deposit` mixin shows the canonical shape — open the input,
-loop the batch, call the hook, write the output run:
+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
+`{ 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,
+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
+recorded by an external system.
+
+The standard `Deposit` mixin shows the canonical shape: open and validate both
+command lanes, loop the batch, call the hook, and write the output run:
 
 ```solidity
 function deposit(
-    CommandContext calldata c
+    bytes32 account,
+    bytes calldata state,
+    bytes calldata input
 ) external onlyCommand returns (bytes memory, bytes memory) {
-    (Cur memory input, uint outputs) = openInput(c.input, descriptor);
-    Writer memory output = Writers.allocBalances(outputs);
+    Execution memory exec = openCommand(state, input, descriptor, 0);
 
-    while (input.i < input.len) {
-        (bytes32 asset, uint amount) = input.unpackAmount();
-        deposit(c.account, asset, amount); // host policy hook
-        output.appendBalance(asset, amount);
+    while (exec.more()) {
+        (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
+        deposit(account, asset, amount); // host policy hook
+        exec.outputBalance(asset, amount);
     }
 
-    return (end(output), "");
+    return close(exec, account);
 }
 ```
 
@@ -292,7 +313,13 @@ abstract contract MyCommand is CommandBase {
         bytes calldata state,
         bytes calldata input
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        // parse input, loop, return the output state run and any transactions
+        Execution memory exec = openCommand(state, input, descriptor, 0);
+        while (exec.more()) {
+            (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
+            // Apply command-specific behavior for this group.
+            exec.outputBalance(asset, amount);
+        }
+        return close(exec, account);
     }
 }
 ```
@@ -301,8 +328,10 @@ The standard commands cover the common ledger movements: `deposit` and
 `depositPayable` (external funds in), `withdraw` and `burn` (funds out),
 `debitAccount` and `creditAccount` (internal movements), `payout` (deliver
 state to other accounts), `allocate` (turn balance state into custody),
-`provision` (provision custody from an external allocation), and `relayPayable`
-(hand a pipeline to another portal).
+`provision` (provision custody from an external allocation), `settle` (consume
+asset-liability position state), `relayPayable` (relay a pipeline without
+state), and `relayBalancePayable` (relay balance state and a pipeline to another
+portal).
 
 ## Pipelines
 
@@ -316,7 +345,7 @@ step { uint cmd, uint resources, #bytes as input }
 Each step names a command, the resources it may spend, and its input.
 The returned state threads into the next command and the final state must be
 empty. Returned transactions do not enter the state lane; the pipeline passes
-each decoded transaction to the shared settlement implementation before
+each decoded transaction to the shared posting implementation before
 running the next step. This is the core of `Pipeline.pipe`:
 
 ```solidity
@@ -328,11 +357,11 @@ while (cur.more()) {
         account,
         state,
         input,
-        budget.use(resources)
+        budget.useResourceValue(resources)
     );
     while (transactions.more()) {
         (bytes32 from, bytes32 to, bytes32 asset, uint amount) = transactions.unpackTransaction();
-        settle(from, to, asset, amount);
+        post(from, to, asset, amount);
     }
 }
 if (state.length != 0) revert UnexpectedState();
@@ -345,6 +374,31 @@ command batching — and `resources` is a chain-specific word interpreted by the
 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 `InternalDebitAccount`,
+`InternalCreditAccount`, and `InternalSettle` 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. The host
+dispatcher must reject nonzero step value before invoking them because all three
+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
+represents the value currently required upstream. Each hop consumes one
+position, fulfills or transforms its current requirement, and returns the next
+position:
+
+```txt
+position(C, 100, C, 100)
+→ position(C, 100, B, 50)
+→ position(C, 100, A, 25)
+→ settle
+```
+
+This is backward composition, not backward execution: `#step` blocks still
+execute forward in their encoded order. Exact-output routing is only one use;
+other commands may transform the asset side, the liability side, or both.
+
 ## Queries
 
 Queries are the read endpoints: view functions that take a block-stream input
@@ -365,15 +419,15 @@ the descriptor's lanes through the published block schemas.
 Ports are the host-to-host surfaces, callable only by trusted peer hosts. The two
 central ones are batches all the way down:
 
-- `portSettle` consumes `transaction { bytes32 from, bytes32 to, bytes32 asset,
+- `portPost` consumes `transaction { bytes32 from, bytes32 to, bytes32 asset,
   uint amount }` blocks, debiting `from` and crediting `to` per
-  block — how two hosts record settlement between their ledgers.
+  block — how two hosts post transactions between their ledgers.
 - `portPipePayable` consumes `context` blocks, each carrying an account, an
   initial state, and a run of steps — a complete pipeline delivered by another
   host, executed locally against the port call's shared value budget.
 
-This is also the cross-portal mechanism. `relayPayable` (or `portDispatchPayable`)
-wraps a pipe and addresses it to a portal, commonly the destination host ID;
+This is also the cross-portal mechanism. `relayPayable`, `relayBalancePayable`,
+or `portDispatchPayable` wraps a pipe and addresses it to a portal, commonly the destination host ID;
 a bridge adapter moves the **raw
 bytes**; the destination host parses them with the same cursor rules and runs
 the same pipeline loop. Nothing in the payload is EVM-specific — step commands
@@ -386,9 +440,9 @@ bytes and produce the same output bytes for every endpoint.
 
 Admin commands use the regular command shape but are gated to the host's admin
 account: trust management (`authorize`, `unauthorize`), guardian management
-(`appoint`, `dismiss`), metadata (`label`, `publishSchema`), asset gating (`allowAssets`,
-`denyAssets`, `allowance`), lifecycle (`init`, `destroy`), and raw calls
-(`executePayable`). Guards go the other way: direct actions guardians can take
+(`appoint`, `dismiss`), metadata (`annotate`), optional asset gating
+(`allowAssets`, `denyAssets`, `allowance`), and raw calls (`executePayable`).
+Guards go the other way: direct actions guardians can take
 without any command context — the default is `revoke`, which lets a guardian
 drop a trusted node immediately.
 

package/codec/Blocks.sol

@@ -35,10 +35,6 @@ library Blocks {
     error UnexpectedValue();
     /// @dev A scoped block run contained no blocks.
     error EmptyRun();
-    /// @dev A block run was scoped with a zero stride.
-    error ZeroStride();
-    /// @dev A block count is not divisible by its declared stride.
-    error BadRatio();
 
     // -------------------------------------------------------------------------
     // Calldata inspection and navigation
@@ -147,25 +143,16 @@ library Blocks {
         }
     }
 
-    /// @notice Scope a consecutive block run into equal-sized groups.
+    /// @notice Count a run that must consume the complete region.
+    /// @dev Reverts when any well-formed trailing block has a different key.
     /// @param abs Absolute start position.
     /// @param limit Absolute region boundary.
-    /// @param key Block key forming the run.
-    /// @param stride Number of blocks per group.
-    /// @return groups Number of complete groups in the run.
-    /// @return end Absolute position immediately after the run.
-    function scope(
-        uint abs,
-        uint limit,
-        bytes4 key,
-        uint stride
-    ) internal pure returns (uint groups, uint end) {
-        if (stride == 0) revert ZeroStride();
-        uint count;
-        (count, end) = run(abs, limit, key);
-        if (count == 0) revert EmptyRun();
-        if (count % stride != 0) revert BadRatio();
-        groups = count / stride;
+    /// @param key Required block key for the complete region.
+    /// @return total Number of matching blocks.
+    /// @return end Absolute position equal to `limit`.
+    function runExact(uint abs, uint limit, bytes4 key) internal pure returns (uint total, uint end) {
+        (total, end) = run(abs, limit, key);
+        if (end != limit) revert InvalidBlock();
     }
 
     // Generic block writes
@@ -460,6 +447,33 @@ library Blocks {
 
     // Four-word payloads
 
+    /// @notice Write a POSITION block at `i`.
+    /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B128` bytes first.
+    /// @param dst Destination buffer.
+    /// @param i Relative write position.
+    /// @param asset Identifier for the asset side.
+    /// @param amount Quantity on the asset side.
+    /// @param liability Identifier for the liability side.
+    /// @param debt Quantity owed on the liability side.
+    function writePosition(
+        bytes memory dst,
+        uint i,
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal pure {
+        uint spec = Specs.Position;
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, spec)
+            mstore(add(p, 0x08), asset)
+            mstore(add(p, 0x28), amount)
+            mstore(add(p, 0x48), liability)
+            mstore(add(p, 0x68), debt)
+        }
+    }
+
     /// @notice Write a TRANSACTION block at `i`.
     /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B128` bytes first.
     /// @param dst Destination buffer.
@@ -1249,6 +1263,28 @@ library Blocks {
 
     // Four-word payloads
 
+    /// @notice Decode a low-level fixed-width POSITION block at `abs`.
+    /// @param abs Absolute block position.
+    /// @return asset Decoded asset-side identifier.
+    /// @return amount Decoded asset-side quantity.
+    /// @return liability Decoded liability-side identifier.
+    /// @return debt Decoded liability-side debt.
+    function unpackPosition(
+        uint abs
+    ) internal pure returns (bytes32 asset, uint amount, bytes32 liability, uint debt) {
+        uint head;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+        }
+        if (head >> 192 != Specs.Position >> 192) revert InvalidBlock();
+        assembly ("memory-safe") {
+            asset := calldataload(add(abs, 0x08))
+            amount := calldataload(add(abs, 0x28))
+            liability := calldataload(add(abs, 0x48))
+            debt := calldataload(add(abs, 0x68))
+        }
+    }
+
     /// @notice Decode a low-level fixed-width TRANSACTION block at `abs`.
     /// @param abs Absolute block position.
     /// @return from Decoded debit account.
@@ -1577,6 +1613,28 @@ library Blocks {
         return bytes.concat(Keys.Balance, bytes4(uint32(64)), asset, bytes32(amount));
     }
 
+    /// @notice Encode a POSITION block.
+    /// @param asset Identifier for the asset side.
+    /// @param amount Quantity on the asset side.
+    /// @param liability Identifier for the liability side.
+    /// @param debt Quantity owed on the liability side.
+    /// @return Encoded POSITION block bytes.
+    function position(
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal pure returns (bytes memory) {
+        return bytes.concat(
+            Keys.Position,
+            bytes4(uint32(128)),
+            asset,
+            bytes32(amount),
+            liability,
+            bytes32(debt)
+        );
+    }
+
     /// @notice Encode a CUSTODY block.
     /// @param host Host node ID holding the custody.
     /// @param asset Asset identifier.

package/codec/Buffers.sol

@@ -18,12 +18,12 @@ library Buffers {
 
     /// @notice Create a packed buffer cursor at write position zero.
     /// @param len Initial logical byte capacity.
-    /// @param groups Number of logical groups represented by the buffer.
+    /// @param count Number of logical items represented by the buffer.
     /// @param growable Whether writes may expand the logical capacity.
     /// @param tag Cursor identity tag.
     /// @return cur Packed buffer cursor.
-    function cursor(uint len, uint groups, bool growable, uint8 tag) internal pure returns (uint cur) {
-        cur = Cursors.create(0, len, groups, growable ? Growable : 0, tag);
+    function cursor(uint len, uint count, bool growable, uint8 tag) internal pure returns (uint cur) {
+        cur = Cursors.create(0, len, count, growable ? Growable : 0, tag);
     }
 
     /// @notice Reserve relative write space and return the updated packed buffer cursor.

package/codec/Decoders.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, Tx} from "../core/Types.sol";
+import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, 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,20 +32,17 @@ library Decoders {
         cur.state = Cursors.wrap(source[i:], 0, 0);
     }
 
-    /// @notice Open the first homogeneous run in `source` using `stride`.
+    /// @notice Open the first homogeneous run in `source`.
     /// @param source Calldata block stream to open.
-    /// @param stride Number of blocks per group, or zero for an ungrouped stream.
     /// @return cur Cursor spanning the first homogeneous run.
-    function open(
-        bytes calldata source,
-        uint stride
-    ) internal pure returns (Cur memory cur) {
+    function open(bytes calldata source) internal pure returns (Cur memory cur) {
         (uint abs, uint limit) = Cursors.bounds(source);
-        if (stride == 0 && abs == limit) return cur;
+        if (abs == limit) revert Blocks.EmptyRun();
 
         bytes4 key = bytes4(source);
-        (uint groups, uint end) = Blocks.scope(abs, limit, key, stride);
-        cur.state = Cursors.create(abs, end - abs, groups, 0, 0);
+        (uint count, uint end) = Blocks.run(abs, limit, key);
+        if (count == 0) revert Blocks.EmptyRun();
+        cur.state = Cursors.create(abs, end - abs, count, 0, 0);
     }
 
     /// @notice Return whether `cur` has unread bytes.
@@ -163,6 +160,16 @@ library Decoders {
         return Blocks.find(offset + i, offset + end, key) - offset;
     }
 
+    /// @notice Count consecutive blocks with `key` from the current cursor position.
+    /// @dev Does not advance the cursor.
+    /// @param cur Cursor to inspect.
+    /// @param key Block key forming the run.
+    /// @return count Number of consecutive matching blocks.
+    function run(Cur memory cur, bytes4 key) internal pure returns (uint count) {
+        (uint i, uint offset, uint len) = cur.state.decode();
+        (count, ) = Blocks.run(offset + i, offset + len, key);
+    }
+
     /// @notice Consume one LIST block and return a cursor over its items.
     /// @param cur Cursor advanced past the list.
     /// @return items Cursor spanning the list payload.
@@ -532,6 +539,20 @@ library Decoders {
         (value.host, value.asset, value.amount) = unpackCustody(cur);
     }
 
+    /// @notice Decode and consume one POSITION block.
+    function unpackPosition(
+        Cur memory cur
+    ) internal pure returns (bytes32 asset, uint amount, bytes32 liability, uint debt) {
+        uint abs;
+        (cur.state, abs) = cur.state.consume(Sizes.Position);
+        (asset, amount, liability, debt) = Blocks.unpackPosition(abs);
+    }
+
+    /// @notice Decode one POSITION block into its structured value.
+    function unpackPositionValue(Cur memory cur) internal pure returns (Position memory value) {
+        (value.asset, value.amount, value.liability, value.debt) = unpackPosition(cur);
+    }
+
     /// @notice Decode one TRANSACTION block into its structured value.
     /// @param cur Cursor advanced past the block.
     /// @return value Structured transaction.

package/codec/Descriptors.sol

@@ -37,7 +37,6 @@ library Descriptors {
         state = Specs.normalize(state, true);
         input = Specs.normalize(input, false);
         output = Specs.normalize(output, true);
-
         descriptor = pack(state, input, output, transactions, flags);
     }
 

package/codec/Keys.sol

@@ -9,8 +9,6 @@ pragma solidity ^0.8.33;
 library Keys {
     /// @dev Empty / unset key.
     bytes4 constant Empty = bytes4(0);
-    /// @dev Wildcard key used in discovery when any block stream is accepted.
-    bytes4 constant Any = 0xffffffff;
     /// @dev Input amount - (bytes32 asset, uint amount)
     bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, uint amount)
@@ -21,6 +19,8 @@ library Keys {
     bytes4 constant Allowance = bytes4(keccak256("#allowance"));
     /// @dev Cross-host custody state - (uint host, bytes32 asset, uint amount)
     bytes4 constant Custody = bytes4(keccak256("#custody"));
+    /// @dev Asset-liability position state - (bytes32 asset, uint amount, bytes32 liability, uint debt)
+    bytes4 constant Position = bytes4(keccak256("#position"));
     /// @dev List wrapper; payload is an embedded repeated block stream
     bytes4 constant List = bytes4(keccak256("#list"));
     /// @dev EVM-encoded payload field; layout follows standard ABI tuple encoding

package/codec/Readers.sol

@@ -94,6 +94,19 @@ library Readers {
         }
     }
 
+    /// @notice Consume a POSITION block and return its fields.
+    function unpackPosition(
+        Reader memory cur
+    ) internal pure returns (bytes32 asset, uint amount, bytes32 liability, uint debt) {
+        uint abs = consume(cur, Keys.Position, 128, 128);
+        assembly ("memory-safe") {
+            asset := mload(abs)
+            amount := mload(add(abs, 0x20))
+            liability := mload(add(abs, 0x40))
+            debt := mload(add(abs, 0x60))
+        }
+    }
+
     /// @notice Consume a TRANSACTION block and return its fields.
     /// @param cur Reader; advanced past the block.
     /// @return from Source account identifier.

package/codec/Schema.sol

@@ -43,10 +43,13 @@ 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(...)` and `custody(...)` are live, linear state in the active command pipeline
+// - `balance(...)`, `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
 //   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
+// - 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(...)`
 //   express intent, constraints, or references
@@ -90,6 +93,7 @@ library Schemas {
 
     // Four-word payloads
 
+    string constant Position = "{ bytes32 asset, uint amount, bytes32 liability, uint debt }";
     string constant Transaction = "{ bytes32 from, bytes32 to, bytes32 asset, uint amount }";
     string constant HostAccountAmount = "{ uint host, bytes32 account, bytes32 asset, uint amount }";