@rootzero/contracts 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -3,6 +3,102 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.20.0
+
+### Breaking Changes
+
+- `Nodes.toCommand`, `toPort`, `toQuery`, and `toGuard` now take an endpoint
+  name instead of a precomputed selector. The `Selectors` library was removed;
+  endpoint node IDs now derive their canonical selectors internally.
+- Renamed the memory-backed pipeline adapters from `InternalDebitAccount`,
+  `InternalCreditAccount`, and `InternalSettle` to `DebitAccountInternal`,
+  `CreditAccountInternal`, and `SettleInternal`.
+- Replaced `RelayPayableHook.relayTo(portal, resources, payload, funds)` with
+  `relay(portal, resources, account, state, input, funds)`. Relay commands now
+  pass their semantic context fields to the host instead of encoding a
+  `CONTEXT` payload before invoking the hook.
+- `DispatchPayablePort` now uses the dedicated
+  `DispatchPayableHook.dispatchTo(portal, resources, payload, funds)` hook
+  instead of sharing `RelayPayableHook`.
+
+### Added
+
+- Added `RelayEvent`, with account, portal, resources, correlation key, and
+  digest fields for recording outbound relay references.
+
+### Changed
+
+- Relay hooks retain state and nested relay input as calldata until an
+  implementation chooses to encode or otherwise consume the destination
+  context.
+
+### Upgrade Compatibility
+
+- Pass endpoint names directly to the `Nodes.to*` helpers and remove imports of
+  `Selectors`.
+- Update inherited internal adapter names and imports to the new postfix
+  convention.
+- Implement the structured `RelayPayableHook.relay` hook for relay commands and
+  `DispatchPayableHook.dispatchTo` for opaque dispatch payloads. Hosts that
+  support both surfaces must implement both hooks.
+
+## 1.19.0
+
+### Breaking Changes
+
+- Renamed port endpoint contracts from the `Port*` prefix convention to the
+  `*Port` postfix convention: `PortAllowAssets`, `PortAllowance`,
+  `PortCreditAccount`, `PortDebitAccount`, `PortDenyAssets`,
+  `PortDispatchPayable`, `PortPipePayable`, `PortPost`, and
+  `PortRedeemBalance` are now `AllowAssetsPort`, `AllowancePort`,
+  `CreditAccountPort`, `DebitAccountPort`, `DenyAssetsPort`,
+  `DispatchPayablePort`, `PipePayablePort`, `PostPort`, and
+  `RedeemBalancePort` respectively. Endpoint selectors are unchanged.
+- Removed `Blocks.readUint`; cast `uint(Blocks.read32(abs))` when an unchecked
+  absolute word read is required, or use the new cursor-consuming `next32`
+  helpers while decoding.
+- `Cursors.advance` and `Cursors.slice` now assume the documented packed-cursor
+  invariant `i <= len` instead of pre-validating manually constructed cursor
+  words. Invalid raw cursor words may now produce an arithmetic panic rather
+  than `Cursors.OutOfBounds`.
+
+### Added
+
+- Added `enter` and `expectAbs` to `Decoders` and `Executions` for entering a
+  parent payload, decoding its children in place, and proving exact final
+  consumption.
+- Added consuming `next1`, `next2`, `next4`, `next8`, `next16`, and `next32`
+  helpers to `Decoders` and `Executions` for compact fixed-width schema fields.
+- Added calldata-copy encoding across `Buffers`, `Blocks`, `Writers`, and
+  `Executions`. In-place helpers use `copy*`, execution helpers use
+  `outputCopy*`, and allocating block factories use the `*Copy` suffix.
+- Added allocating factories for LIST, EVM, CONTEXT, and RECOVER blocks, plus
+  memory and calldata factory pairs for dynamic leaf and composite blocks.
+
+### Changed
+
+- Block factories now allocate once and delegate to their canonical `write*`
+  or `copy*` encoder instead of assembling nested intermediate byte arrays.
+- Relay and dispatch paths preserve calldata slices until their destination
+  requires memory, avoiding unnecessary explicit calldata-to-memory casts.
+- `Settlement.settle` now implements its documented behavior by routing the
+  liability leg through the virtual `repay` primitive before crediting the
+  asset leg.
+- Documented that restricting schema `bytesN` fields to power-of-two widths is
+  under consideration; all widths from `bytes1` through `bytes32` remain valid.
+
+### Upgrade Compatibility
+
+- Update inherited port contract names and their imports to the new `*Port`
+  names. No endpoint selector or wire-format migration is required.
+- Replace `Blocks.readUint(abs)` with `uint(Blocks.read32(abs))`, or migrate
+  sequential custom decoders to `enter`, `next*`, and `expectAbs`.
+- Code that constructs packed cursors manually must establish `i <= len`
+  before calling navigation helpers. Normal cursor constructors and composition
+  helpers already preserve this invariant.
+- `Settlement` subclasses that override `repay` will now have that override
+  invoked by `settle`, matching the documented extension point.
+
 ## 1.18.0
 
 ### Added

package/Endpoints.sol

@@ -5,57 +5,52 @@ 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, PostHook, RepayHook, SettleHook } from "./core/Settlement.sol";
+import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, 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, 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 { RecoverPayable, RecoverPayableHook } from "./commands/Recover.sol";
-import { Repay, RepayPayable, RepayPayableHook } from "./commands/Repay.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";
+import {CommandBase} from "./commands/Base.sol";
+import {Allocate, AllocateHook} from "./commands/Allocate.sol";
+import {Burn, BurnHook} from "./commands/Burn.sol";
+import {CreditAccount, CreditAccountInternal} from "./commands/Credit.sol";
+import {DebitAccount, DebitAccountInternal} 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 {RecoverPayable, RecoverPayableHook} from "./commands/Recover.sol";
+import {Repay, RepayPayable, RepayPayableHook} 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";
 
 // Admin commands
-import { AdminBase } from "./commands/admin/Base.sol";
-import { AllowAssets, AllowAssetsHook } from "./commands/admin/AllowAssets.sol";
-import { Allowance, AllowanceHook } from "./commands/admin/Allowance.sol";
-import { Annotate } from "./commands/admin/Annotate.sol";
-import { Appoint } from "./commands/admin/Appoint.sol";
-import { Authorize } from "./commands/admin/Authorize.sol";
-import { DenyAssets, DenyAssetsHook } from "./commands/admin/DenyAssets.sol";
-import { Dismiss } from "./commands/admin/Dismiss.sol";
-import { ExecutePayable } from "./commands/admin/Execute.sol";
-import { Unauthorize } from "./commands/admin/Unauthorize.sol";
+import {AdminBase} from "./commands/admin/Base.sol";
+import {AllowAssets, AllowAssetsHook} from "./commands/admin/AllowAssets.sol";
+import {Allowance, AllowanceHook} from "./commands/admin/Allowance.sol";
+import {Annotate} from "./commands/admin/Annotate.sol";
+import {Appoint} from "./commands/admin/Appoint.sol";
+import {Authorize} from "./commands/admin/Authorize.sol";
+import {DenyAssets, DenyAssetsHook} from "./commands/admin/DenyAssets.sol";
+import {Dismiss} from "./commands/admin/Dismiss.sol";
+import {ExecutePayable} from "./commands/admin/Execute.sol";
+import {Unauthorize} from "./commands/admin/Unauthorize.sol";
 
 // Port endpoints
-import { PortBase } from "./ports/Base.sol";
-import { PortAllowAssets } from "./ports/AllowAssets.sol";
-import { PortAllowance } from "./ports/Allowance.sol";
-import { PortRedeemBalance, RedeemBalanceHook } from "./ports/Redeem.sol";
-import { PortCreditAccount } from "./ports/Credit.sol";
-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 { PortPost } from "./ports/Post.sol";
+import {PortBase} from "./ports/Base.sol";
+import {AllowAssetsPort} from "./ports/AllowAssets.sol";
+import {AllowancePort} 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";
 
 // Guard endpoints
-import { GuardBase } from "./guards/Base.sol";
-import { Revoke, RevokeAllowance, RevokeAsset } from "./guards/Revoke.sol";
+import {GuardBase} from "./guards/Base.sol";
+import {Revoke, RevokeAllowance, RevokeAsset} from "./guards/Revoke.sol";
 
 // Query endpoints
-import { QueryBase } from "./queries/Base.sol";
-import { AssetStatus, AssetStatusHook } from "./queries/Assets.sol";
-import { GetBalances, GetBalancesHook } from "./queries/Balances.sol";
+import {QueryBase} from "./queries/Base.sol";
+import {AssetStatus, AssetStatusHook} from "./queries/Assets.sol";
+import {GetBalances, GetBalancesHook} from "./queries/Balances.sol";

package/Events.sol

@@ -13,6 +13,7 @@ import { DispatchEvent } from "./events/Dispatch.sol";
 import { EndpointEvent } from "./events/Endpoint.sol";
 import { ReceivedEvent } from "./events/Received.sol";
 import { RecoveredEvent } from "./events/Recovered.sol";
+import { RelayEvent } from "./events/Relay.sol";
 import { EventEmitter } from "./events/Emitter.sol";
 import { GuardianEvent } from "./events/Guardian.sol";
 import { IntroductionEvent } from "./events/Introduction.sol";

package/README.md

@@ -378,8 +378,8 @@ 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
+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

package/Utils.sol

@@ -11,7 +11,6 @@ import { Amounts, Assets } from "./utils/Assets.sol";
 import { ECDSA } from "./utils/ECDSA.sol";
 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, 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/annotations/Label.sol

@@ -13,11 +13,7 @@ abstract contract Label is AnnotationEvent {
     /// @param entity Entity receiving the label annotation.
     /// @param namespace Label namespace.
     /// @param name Human-readable name within the namespace.
-    function label(
-        uint entity,
-        bytes32 namespace,
-        string memory name
-    ) internal virtual {
+    function label(uint entity, bytes32 namespace, string memory name) internal virtual {
         emit Annotation(entity, Blocks.label(namespace, name));
     }
 }