@rootzero/contracts 1.22.0 → 1.24.0

package/CHANGELOG.md

@@ -3,6 +3,113 @@
 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
+
+- Changed every command entrypoint from
+  `(bytes32 account, bytes state, bytes input)` to one `bytes context` argument
+  containing exactly one encoded `CONTEXT` block. Canonical command selectors
+  now use `(bytes)`, so every command node ID changes. Existing command callers,
+  cached IDs, and deployed host graphs are not compatible with this release.
+- Added the acting account to `Execution`. `CommandBase.openCommand` and
+  `AdminBase.openAdminCommand` now accept the encoded context and return only
+  the initialized execution, and command implementations close with
+  `closeCommand(exec)` instead of `close(exec, account)`.
+- Removed the separate state argument from `RelayPayableHook.relay`. Relay
+  implementations can obtain the complete validated state with
+  `exec.rawState()` while the explicit account and nested relay input arguments
+  remain unchanged.
+- Consolidated `AllowAssetsPort` and `DenyAssetsPort` into
+  `ports/Assets.sol`; update direct source imports to the new path.
+- Renamed the peer `AllowancePort` and `portAllowance` selector to
+  `RequestAllowancePort` and `portRequestAllowance`. The peer port now uses a
+  distinct `RequestAllowanceHook.requestAllowance` hook; the admin `Allowance`
+  command and its authoritative `AllowanceHook.allowance` hook are unchanged.
+- Removed the `Commander` event declaration. Commander addresses and chain
+  context are off-chain configuration; host, native-asset, and admin IDs are
+  deterministic from that information.
+- Prefixed every typed `Blocks` factory with `create`, including calldata-copy
+  variants; for example, use `createBalance`, `createStepCopy`, `createBytes`,
+  and `createString` instead of `balance`, `stepCopy`, `data`, and `text`.
+- Changed the `max8`, `max16`, `max24`, `max32`, `max40`, `max64`, `max96`,
+  `max128`, and `max160` bounds helpers to return their corresponding narrowed
+  integer types instead of `uint`.
+
+### Added
+
+- Added `PositionedEvent`, which publishes asset and liability sides together
+  with the semantic action that produced the observed position.
+- Added `RequestAssetPort`, which passes trusted peers' batched asset and amount
+  requests to a host hook for validation and fulfillment.
+- Added `Executions.takeBlock`, which validates and consumes a block from a
+  selected decoder lane and returns its complete calldata encoding.
+- Added `Executions.rawState` and `Executions.rawInput` for retrieving complete
+  validated calldata lanes independently of current cursor progress.
+- Added `Blocks.createAmount` for constructing canonical `AMOUNT` blocks.
+
+### Changed
+
+- Command pipeline hops now construct `command(bytes)` calldata and the nested
+  `CONTEXT` block directly in one allocation, copying memory state and calldata
+  input into the final call buffer.
+- Added memory `callPort`/`tryCallPort` helpers and calldata-copy
+  `callPortCopy`/`tryCallPortCopy` counterparts, matching the block factory
+  naming convention. Portal forwarding and recovery use the copy variants.
+
+### Upgrade Compatibility
+
+- Rebuild command IDs from the new `(bytes)` selectors, redeploy command hosts,
+  and update pipeline builders and other callers to pass one encoded `CONTEXT`
+  block. Do not mix 1.22 command IDs or callers with 1.23 deployments.
+- Update custom commands to read the acting account from `exec.account`, use
+  `openCommand(context, descriptor, batches)`, and return
+  `closeCommand(exec)`.
+- Update relay hook implementations to remove the state parameter and use
+  `exec.rawState()` when the forwarded state is required.
+- Update direct port imports, renamed request-allowance endpoints and hooks,
+  typed `Blocks` factory calls, and any assignments that relied on `max*`
+  returning `uint`.
+
 ## 1.22.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";
@@ -37,12 +44,11 @@ import {Unauthorize} from "./commands/admin/Unauthorize.sol";
 
 // Port endpoints
 import {PortBase} from "./ports/Base.sol";
-import {AllowAssetsPort} from "./ports/AllowAssets.sol";
-import {AllowancePort} from "./ports/Allowance.sol";
+import {AllowAssetsPort, DenyAssetsPort, RequestAssetPort, RequestAssetHook} from "./ports/Assets.sol";
+import {RequestAllowancePort, RequestAllowanceHook} from "./ports/Allowance.sol";
 import {RedeemBalancePort, RedeemBalanceHook} from "./ports/Redeem.sol";
 import {CreditAccountPort} from "./ports/Credit.sol";
 import {DebitAccountPort} from "./ports/Debit.sol";
-import {DenyAssetsPort} from "./ports/DenyAssets.sol";
 import {PipePayablePort} from "./ports/Pipe.sol";
 import {DispatchPayablePort, DispatchPayableHook} from "./ports/Dispatch.sol";
 import {PostPort} from "./ports/Post.sol";

package/Events.sol

@@ -8,7 +8,6 @@ import { AnnotationEvent } from "./events/Annotation.sol";
 import { AssetEvent, AssetStatusEvent } from "./events/Asset.sol";
 import { Actions } from "./utils/Actions.sol";
 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 { ReceivedEvent } from "./events/Received.sol";
@@ -19,6 +18,7 @@ import { GuardianEvent } from "./events/Guardian.sol";
 import { IntroductionEvent } from "./events/Introduction.sol";
 import { LockedEvent } from "./events/Locked.sol";
 import { NodeEvent } from "./events/Node.sol";
+import { PositionedEvent } from "./events/Positioned.sol";
 import { RootedEvent } from "./events/Rooted.sol";
 import { RouteEvent } from "./events/Route.sol";
 import { SpentEvent } from "./events/Spent.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
@@ -288,19 +290,17 @@ command lanes, loop the batch, call the hook, and write the output run:
 
 ```solidity
 function deposit(
-    bytes32 account,
-    bytes calldata state,
-    bytes calldata input
+    bytes calldata context
 ) external onlyCommand returns (bytes memory, bytes memory) {
-    Execution memory exec = openCommand(state, input, descriptor, 0);
+    Execution memory exec = openCommand(context, descriptor, 0);
 
     while (exec.more()) {
         (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
-        deposit(account, asset, amount); // host policy hook
+        deposit(exec.account, asset, amount); // host policy hook
         exec.outputBalance(asset, amount);
     }
 
-    return close(exec, account);
+    return closeCommand(exec);
 }
 ```
 
@@ -317,24 +317,24 @@ abstract contract MyCommand is CommandBase {
     }
 
     function myCommand(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, 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);
+        return closeCommand(exec);
     }
 }
 ```
 
 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),
@@ -342,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).
 
@@ -388,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
@@ -435,6 +437,12 @@ central ones are batches all the way down:
 - `portPost` consumes `transaction { bytes32 from, bytes32 to, bytes32 asset,
   uint amount }` blocks, debiting `from` and crediting `to` per
   block — how two hosts post transactions between their ledgers.
+- `portRequestAsset` consumes `amount { bytes32 asset, uint amount }` blocks and
+  passes the authenticated peer, asset, and amount to a host hook. The hook
+  validates asset support and applies the host's request and transfer policy.
+- `portRequestAllowance` consumes the same amount blocks and lets the
+  authenticated peer request an asset allowance. The hook decides what
+  allowance, if any, to grant.
 - `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.

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

@@ -12,6 +12,6 @@ abstract contract Action is AnnotationEvent {
     /// @param entity Entity receiving the action annotation.
     /// @param value Canonical action identifier, such as a value from `Actions`.
     function action(uint entity, uint value) internal virtual {
-        emit Annotation(entity, Blocks.action(value));
+        emit Annotation(entity, Blocks.createAction(value));
     }
 }

package/annotations/Label.sol

@@ -14,6 +14,6 @@ abstract contract Label is AnnotationEvent {
     /// @param namespace Label namespace.
     /// @param name Human-readable name within the namespace.
     function label(uint entity, bytes32 namespace, string memory name) internal virtual {
-        emit Annotation(entity, Blocks.label(namespace, name));
+        emit Annotation(entity, Blocks.createLabel(namespace, name));
     }
 }

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));
     }
 
@@ -80,7 +74,7 @@ abstract contract Schema is Runtime, AnnotationEvent {
     /// @param name Schema alias name, or zero for unnamed schemas.
     /// @return The published block specification.
     function schema(uint spec, string memory body, bytes32 name) internal returns (uint) {
-        emit Annotation(host, Blocks.schema(spec, body, name));
+        emit Annotation(host, Blocks.createSchema(spec, body, name));
         return spec;
     }
 }