@rootzero/contracts 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -3,6 +3,96 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.17.0
+
+### Breaking Changes
+
+- `executeDebitAccount`, `executeCreditAccount`, and `executeSettle` now require
+  the pipeline step's `uint128 value` argument and reject nonzero value inside
+  the internal adapter.
+- `AllowanceHook` implementations must treat an amount of zero as revocation.
+
+### Added
+
+- Added the `HostAsset` structural block and complete codec support for
+  host-scoped asset references.
+- Added the opt-in `RevokeAllowance` guardian endpoint, which accepts
+  `HostAsset` entries and revokes each allowance through `AllowanceHook`.
+- Added the funded `settlePayable` command and `SettlePayableHook` for settlement
+  implementations that require access to the command's native-value budget.
+
+### Changed
+
+- Completed the endpoint barrel with `CommandBase` and exported the new command,
+  guard, hook, internal adapter, and structural type surfaces from their
+  corresponding package barrels.
+
+### Upgrade Compatibility
+
+- Pipeline hosts using the internal debit, credit, or settle adapters must pass
+  each step's assigned value into the adapter. Existing non-funded steps should
+  continue to pass zero.
+
+## 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.
+- Completed the public barrel exports for internal command adapters,
+  input-only endpoint bases, access errors, and low-level utility helpers.
+
+### 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, HostAsset, 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, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, 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 { AdminAccess, CallerAccess, CommanderAccess, GuardianAccess, NodeAccess, TrustAccess } from "./core/Access.sol";
+import { AccessDenied, AdminAccess, CallerAccess, CommanderAccess, CommanderNotAllowed, 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 } from "./core/Endpoint.sol";
+import { EndpointBase, InputEndpointBase } 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, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
 
 

package/Endpoints.sol

@@ -5,18 +5,20 @@ 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 { CommandBase } from "./commands/Base.sol";
 import { Allocate, AllocateHook } from "./commands/Allocate.sol";
 import { Burn, BurnHook } from "./commands/Burn.sol";
-import { CreditAccount } from "./commands/Credit.sol";
-import { DebitAccount } from "./commands/Debit.sol";
+import { CreditAccount, InternalCreditAccount } from "./commands/Credit.sol";
+import { DebitAccount, InternalDebitAccount } 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 { InternalSettle, Settle, SettlePayable, SettlePayableHook } from "./commands/Settle.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands
@@ -41,11 +43,11 @@ 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";
-import { Revoke } from "./guards/Revoke.sol";
+import { Revoke, RevokeAllowance } from "./guards/Revoke.sol";
 
 // Query endpoints
 import { QueryBase } from "./queries/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
@@ -219,7 +219,10 @@ pipeline.
 
 The built-in surface is also available as two independent feature bundles:
 `Admins` provides annotate, authorize, unauthorize, and executePayable;
-`Guardians` provides appoint, dismiss, and revoke. The full `Host` composes
+`Guardians` provides appoint, dismiss, and node revocation. Hosts that implement
+the allowance hook can additionally inherit the opt-in `RevokeAllowance` guard,
+which accepts `hostAsset { uint host, bytes32 asset }` entries and always applies
+a zero allowance. The full `Host` composes
 both, while smaller hosts can inherit either bundle separately.
 
 Trust is explicit and minimal. Each host has an immutable **commander**
@@ -248,30 +251,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,17 +316,26 @@ 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);
     }
 }
 ```
 
 The standard commands cover the common ledger movements: `deposit` and
-`depositPayable` (external funds in), `withdraw` and `burn` (funds out),
+`depositPayable` (external funds in), `settlePayable` (funded settlement),
+`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 +349,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 +361,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 +378,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. Pass the
+step value into each adapter; all three 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
+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 +423,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 +444,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/Utils.sol

@@ -13,7 +13,7 @@ import { Ids } from "./utils/Ids.sol";
 import { Nodes } from "./utils/Nodes.sol";
 import { Selectors } from "./utils/Selectors.sol";
 import { Layout } from "./utils/Layout.sol";
-import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, divisible, hash32, intToBytes32, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, retryTicket, toLocalBase, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.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";
 
 
 

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
@@ -348,6 +335,22 @@ library Blocks {
         }
     }
 
+    /// @notice Write a HOST_ASSET block at `i`.
+    /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B64` bytes first.
+    /// @param dst Destination buffer.
+    /// @param i Relative write position.
+    /// @param host Host identifier to encode.
+    /// @param asset Asset identifier to encode.
+    function writeHostAsset(bytes memory dst, uint i, uint host, bytes32 asset) internal pure {
+        uint spec = Specs.HostAsset;
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, spec)
+            mstore(add(p, 0x08), host)
+            mstore(add(p, 0x28), asset)
+        }
+    }
+
     // Three-word payloads
 
     /// @notice Write an ALLOCATION block at `i`.
@@ -460,6 +463,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 +1279,44 @@ 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 HOST_ASSET block at `abs`.
+    /// @param abs Absolute block position.
+    /// @return host Decoded host identifier.
+    /// @return asset Decoded asset identifier.
+    function unpackHostAsset(uint abs) internal pure returns (uint host, bytes32 asset) {
+        uint head;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+        }
+        if (head >> 192 != Specs.HostAsset >> 192) revert InvalidBlock();
+        assembly ("memory-safe") {
+            host := calldataload(add(abs, 0x08))
+            asset := calldataload(add(abs, 0x28))
+        }
+    }
+
     /// @notice Decode a low-level fixed-width TRANSACTION block at `abs`.
     /// @param abs Absolute block position.
     /// @return from Decoded debit account.
@@ -1577,6 +1645,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.