@rootzero/contracts 1.26.0 → 1.27.0

package/CHANGELOG.md

@@ -8,6 +8,30 @@ sections are immutable and must continue to describe the tagged release.
 
 ## Unreleased
 
+## 1.27.0
+
+### Breaking Changes
+
+- Removed `BootstrapBudgetHook`. Bootstrap budget contributions now debit the
+  account's local native asset through the standard `DebitAccountHook`.
+- Removed the external `bootstrap` endpoint and `BootstrapInternal`. Bootstrap
+  is now a pipeline-local command implemented directly by `Bootstrap` while
+  retaining its registered command ID and descriptor metadata.
+- Replaced the codec-specific `Executions.ZeroStride` error with global
+  `UnexpectedState` and `UnexpectedInput` errors for pipeline-local lane
+  violations.
+
+### Changed
+
+- Node authorization and revocation now reject foreign-chain and opaque node
+  IDs, keeping the trusted-node set local to the host chain.
+- Asserting EVM, admin, and user account helpers now require a nonzero embedded
+  address while continuing to return the original account ID.
+- Documented that either side of a position may be absent, using a zero
+  identifier and quantity like an omitted transaction endpoint.
+- Bootstrap uses assigned step value before debiting any remaining native-asset
+  amount from the account and returns unused value as credit.
+
 ## 1.26.0
 
 ### Breaking Changes

package/Endpoints.sol

@@ -13,7 +13,7 @@ import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook} fr
 import {CommandBase} from "./commands/Base.sol";
 import {Allocate, AllocateHook} from "./commands/Allocate.sol";
 import {Burn, BurnHook} from "./commands/Burn.sol";
-import {Bootstrap, BootstrapBudgetHook, BootstrapInternal} from "./commands/Bootstrap.sol";
+import {Bootstrap} from "./commands/Bootstrap.sol";
 import {Cashout, CashoutHook, CashoutInternal} from "./commands/Cashout.sol";
 import {CreditAccount, CreditAccountInternal} from "./commands/Credit.sol";
 import {DebitAccount, DebitAccountInternal} from "./commands/Debit.sol";

package/README.md

@@ -276,6 +276,14 @@ next. Balance carries `{ asset, amount }`, debt carries `{ liability, debt }`,
 and position carries their flat combination
 `{ asset, amount, liability, debt }`.
 
+Either side of a position may be absent. An absent asset side is encoded as
+`asset = 0, amount = 0`; an absent liability side is encoded as
+`liability = 0, debt = 0`. This mirrors transaction blocks, where a zero `from`
+or `to` omits that side of the transfer. A one-sided position remains useful
+when a command must preserve position-shaped state for later composition;
+otherwise the narrower `#balance` or `#debt` block expresses the same live
+value more directly.
+
 `#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
@@ -367,8 +375,11 @@ next step, allowing one command to fund later commands. The standard
 `bootstrap` command consumes a stream of
 `#bootstrap { bytes32 asset, uint amount, uint budget }` requests and atomically
 debits each asset through the standard account hook, introduces matching
-`#balance` state, and sources summed trusted credit through its dedicated budget
-hook. This is the core of
+`#balance` state, and debits each nonzero budget contribution from the account's
+native asset through the same hook. Its pipeline-local implementation uses assigned step value first when
+bootstrapping the native asset, debits any remainder from the account, and
+returns unused assigned value as credit. Bootstrap is registered with command
+metadata but is only executable through local pipeline dispatch. This is the core of
 `Pipeline.pipe`:
 
 ```solidity
@@ -400,17 +411,18 @@ command batching. A step's `uint128 value` is drawn directly from the shared
 native-value budget. Transport envelopes retain separate chain-specific
 `resources` fields for adapters that also need gas or runtime parameters.
 
-Hosts that implement a pipeline locally can inherit `BootstrapInternal`,
+Hosts that implement a pipeline locally can inherit `Bootstrap`,
 `CashoutInternal`, `DebitAccountInternal`, `CreditAccountInternal`,
 `SettleInternal`, and
-`RepayInternal` to advertise the canonical command endpoints while routing
+`RepayInternal` to register canonical command metadata while routing
 their local command IDs through `executeBootstrap`, `executeCashout`,
 `executeDebitAccount`, `executeCreditAccount`, `executeSettle`, and
 `executeRepay`. The bootstrap, cashout, and debit adapters decode fixed-stride
 calldata input directly; the other three
 decode memory-backed pipeline state. All avoid an external self-call. Pass the
-step value into each adapter; all six reject nonzero value because the commands
-are non-funded.
+step value into each adapter. Bootstrap is pipeline-local rather than an
+externally callable command and may consume value for native-asset balance;
+the other five reject nonzero value because those 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

package/codec/Schema.sol

@@ -60,6 +60,8 @@ pragma solidity ^0.8.33;
 // - while a balance, debt, or custody is in-flight as pipeline state, it is not simultaneously persisted
 //   in another ledger/store by this protocol
 // - debt carries only a live liability side; position pairs live balance and debt sides
+// - either position side may be absent by setting both its identifier and quantity to zero,
+//   analogous to omitting a transaction side with a zero `from` or `to`
 // - debt and position state are transient and do not themselves 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

package/commands/Bootstrap.sol

@@ -1,33 +1,20 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Execution, Executions, CommandBase, Specs} from "./Base.sol";
+import {CommandBase, Specs} from "./Base.sol";
 import {Blocks} from "../codec/Blocks.sol";
 import {Sizes} from "../codec/Specs.sol";
 import {Cursors} from "../utils/Cursors.sol";
 import {DebitAccountHook} from "../core/Settlement.sol";
-
-using Executions for Execution;
-
-/// @notice Hook implemented by hosts that source bootstrap pipeline budget.
-abstract contract BootstrapBudgetHook {
-    /// @notice Source native-value budget for `account` during bootstrap.
-    /// Called once per BOOTSTRAP input block.
-    /// @dev Implementations must revert unless the contribution can be made available.
-    /// A zero amount is valid and may return immediately without changing state.
-    /// @param account Account funding the pipeline.
-    /// @param amount Native value added to the pipeline budget.
-    function bootstrapBudget(bytes32 account, uint amount) internal virtual;
-}
+import {UnexpectedState} from "../utils/Errors.sol";
 
 /// @title Bootstrap
-/// @notice Command that atomically starts a pipeline with BALANCE state and native-value budget.
-abstract contract Bootstrap is CommandBase, DebitAccountHook, BootstrapBudgetHook {
-    uint private immutable descriptor;
+/// @notice Pipeline-local command that atomically starts with BALANCE state and native-value budget.
+abstract contract Bootstrap is CommandBase, DebitAccountHook {
     uint private immutable id;
 
     constructor() {
-        (id, descriptor) = command("bootstrap", Specs.Empty, Specs.Bootstrap, Specs.Balance, 0);
+        (id,) = command("bootstrap", Specs.Empty, Specs.Bootstrap, Specs.Balance, 0);
     }
 
     /// @notice Return the registered BOOTSTRAP command ID.
@@ -35,57 +22,56 @@ abstract contract Bootstrap is CommandBase, DebitAccountHook, BootstrapBudgetHoo
         return id;
     }
 
-    /// @notice Source initial balances and budget contributions for a pipeline.
-    /// @param context Command context carrying a BOOTSTRAP input stream.
-    /// @return output One BALANCE block per BOOTSTRAP input.
-    /// @return credit Sum of trusted native value contributed by every input.
+    /// @dev Bootstrap one local balance, using assigned value before debiting
+    /// any remaining native-asset amount from the account.
     function bootstrap(
-        bytes calldata context
-    ) external onlyCommand returns (bytes memory output, uint credit) {
-        Execution memory exec = openCommand(context, descriptor);
-
-        while (exec.more()) {
-            (bytes32 asset, uint amount, uint budget) = exec.unpackBootstrap();
-            debitAccount(exec.account, asset, amount);
-            bootstrapBudget(exec.account, budget);
-            exec.outputBalance(asset, amount);
-            credit += budget;
+        bytes32 account,
+        bytes32 asset,
+        uint amount,
+        uint budget,
+        uint value
+    ) private returns (uint) {
+        if (asset == nativeAsset) {
+            uint funded = amount < value ? amount : value;
+            unchecked {
+                amount -= funded;
+                value -= funded;
+            }
+            amount += budget;
+        } else {
+            if (amount != 0) debitAccount(account, asset, amount);
+            amount = budget;
         }
 
-        return exec.close(credit);
+        if (amount != 0) debitAccount(account, nativeAsset, amount);
+        return value + budget;
     }
-}
 
-/// @title BootstrapInternal
-/// @notice Extends bootstrap with optimized local pipeline dispatch.
-abstract contract BootstrapInternal is Bootstrap {
     /// @notice Execute bootstrap directly against a calldata BOOTSTRAP stream.
     /// @param account Account funding the pipeline.
     /// @param state Empty pipeline state required by the command schema.
     /// @param input BOOTSTRAP block stream.
-    /// @param value Native value assigned to this command; must be zero.
+    /// @param value Native value available to fund native-asset balances.
     /// @return output One BALANCE block per BOOTSTRAP input.
-    /// @return credit Sum of the sourced budget contributions.
+    /// @return credit Sourced budget contributions plus unused assigned value.
     function executeBootstrap(
         bytes32 account,
         bytes memory state,
         bytes calldata input,
         uint128 value
     ) internal returns (bytes memory output, uint credit) {
-        if (value != 0) revert ValueNotAllowed();
-        if (state.length != 0) revert Executions.ZeroStride();
+        if (state.length != 0) revert UnexpectedState();
         if (input.length % Sizes.Bootstrap != 0) revert Blocks.InvalidBlock();
 
         (uint abs, uint end) = Cursors.bounds(input);
         output = new bytes(input.length / Sizes.Bootstrap * Sizes.Balance);
+        credit = value;
         uint i;
 
         while (abs < end) {
             (bytes32 asset, uint amount, uint budget) = Blocks.unpackBootstrap(abs);
-            debitAccount(account, asset, amount);
-            bootstrapBudget(account, budget);
+            credit = bootstrap(account, asset, amount, budget, credit);
             Blocks.writeBalance(output, i, asset, amount);
-            credit += budget;
             unchecked {
                 abs += Sizes.Bootstrap;
                 i += Sizes.Balance;

package/commands/Cashout.sol

@@ -7,6 +7,7 @@ import {Sizes} from "../codec/Specs.sol";
 import {Cursors} from "../utils/Cursors.sol";
 import {Action} from "../annotations/Action.sol";
 import {Actions} from "../utils/Actions.sol";
+import {UnexpectedState} from "../utils/Errors.sol";
 
 using Executions for Execution;
 
@@ -70,7 +71,7 @@ abstract contract CashoutInternal is Cashout {
         uint128 value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
-        if (state.length != 0) revert Executions.ZeroStride();
+        if (state.length != 0) revert UnexpectedState();
         if (input.length % Sizes.Cashout != 0) revert Blocks.InvalidBlock();
 
         (uint abs, uint end) = Cursors.bounds(input);

package/commands/Credit.sol

@@ -5,6 +5,7 @@ import {Execution, Executions, CommandBase, Specs} from "./Base.sol";
 import {CreditAccountHook} from "../core/Settlement.sol";
 import {Blocks, Memory} from "../codec/Blocks.sol";
 import {Sizes} from "../codec/Specs.sol";
+import {UnexpectedInput} from "../utils/Errors.sol";
 
 using Executions for Execution;
 
@@ -61,7 +62,7 @@ abstract contract CreditAccountInternal is CreditAccount {
         uint128 value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
-        if (input.length != 0) revert Executions.ZeroStride();
+        if (input.length != 0) revert UnexpectedInput();
         if (state.length == 0) revert Blocks.EmptyRun();
 
         (uint abs, uint end) = Memory.bounds(state, Sizes.Balance);

package/commands/Debit.sol

@@ -6,6 +6,7 @@ import {DebitAccountHook} from "../core/Settlement.sol";
 import {Blocks} from "../codec/Blocks.sol";
 import {Sizes} from "../codec/Specs.sol";
 import {Cursors} from "../utils/Cursors.sol";
+import {UnexpectedState} from "../utils/Errors.sol";
 
 using Executions for Execution;
 
@@ -64,7 +65,7 @@ abstract contract DebitAccountInternal is DebitAccount {
         uint128 value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
-        if (state.length != 0) revert Executions.ZeroStride();
+        if (state.length != 0) revert UnexpectedState();
         if (input.length == 0) revert Blocks.EmptyRun();
         if (input.length % Sizes.Amount != 0) revert Blocks.InvalidBlock();
 

package/commands/Repay.sol

@@ -7,6 +7,7 @@ import {Action} from "../annotations/Action.sol";
 import {Actions} from "../utils/Actions.sol";
 import {Blocks, Memory} from "../codec/Blocks.sol";
 import {Sizes} from "../codec/Specs.sol";
+import {UnexpectedInput} from "../utils/Errors.sol";
 
 using Executions for Execution;
 
@@ -164,7 +165,7 @@ abstract contract RepayInternal is Repay {
         uint128 value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
-        if (input.length != 0) revert Executions.ZeroStride();
+        if (input.length != 0) revert UnexpectedInput();
         if (state.length == 0) revert Blocks.EmptyRun();
 
         (uint abs, uint end) = Memory.bounds(state, Sizes.Debt);

package/commands/Settle.sol

@@ -7,6 +7,7 @@ import {Action} from "../annotations/Action.sol";
 import {Actions} from "../utils/Actions.sol";
 import {Blocks, Memory} from "../codec/Blocks.sol";
 import {Sizes} from "../codec/Specs.sol";
+import {UnexpectedInput} from "../utils/Errors.sol";
 
 using Executions for Execution;
 
@@ -111,7 +112,7 @@ abstract contract SettleInternal is Settle {
         uint128 value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
-        if (input.length != 0) revert Executions.ZeroStride();
+        if (input.length != 0) revert UnexpectedInput();
         if (state.length == 0) revert Blocks.EmptyRun();
 
         (uint abs, uint end) = Memory.bounds(state, Sizes.Position);

package/core/Access.sol

@@ -89,6 +89,7 @@ abstract contract NodeAccess is AdminAccess, TrustAccess, NodeEvent {
     /// @param node Node ID to update.
     /// @param active True to authorize the node, false to revoke it.
     function setNode(uint node, bool active) internal {
+        node = Nodes.local(node);
         nodes[node] = active;
         emit Node(host, node, active);
     }

package/core/Pipeline.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.8.33;
 
 import {Blocks} from "../codec/Blocks.sol";
 import {Cursors} from "../utils/Cursors.sol";
-import {InsufficientValue, OutOfBounds} from "../utils/Errors.sol";
+import {InsufficientValue, OutOfBounds, UnexpectedState} from "../utils/Errors.sol";
 
 /// @notice Hook implemented by hosts that execute encoded step streams.
 abstract contract PipeHook {
@@ -19,9 +19,6 @@ abstract contract PipeHook {
 /// @title Pipeline
 /// @notice Core pipeline functionality shared by higher-level surfaces.
 abstract contract Pipeline is PipeHook {
-    /// @dev Thrown when the pipeline finishes with non-empty threaded state.
-    error UnexpectedState();
-
     /// @notice Override to dispatch one piped step.
     /// Called once per STEP block. The returned state becomes the state passed to
     /// the next step, and the final returned state must be empty. Returned

package/core/Settlement.sol

@@ -61,7 +61,8 @@ abstract contract Settlement is PostHook, SettleHook, RepayHook, DebitAccountHoo
     }
 
     /// @notice Settle one position by crediting its asset and debiting its liability.
-    /// Skips either operation when its corresponding amount is zero.
+    /// Skips either operation when its corresponding amount is zero, including
+    /// position sides encoded as absent with a zero identifier and quantity.
     function settle(
         bytes32 account,
         bytes32 asset,

package/core/Types.sol

@@ -76,6 +76,7 @@ struct Debt {
 }
 
 /// @notice Asset and liability pair threaded as live pipeline state.
+/// Either side may be absent by setting both its identifier and quantity to zero.
 struct Position {
     /// @dev Identifier for the asset side.
     bytes32 asset;

package/execution/Execution.sol

@@ -28,9 +28,6 @@ struct Execution {
 library Executions {
     using Cursors for uint;
 
-    /// @dev Command-defined lane policy rejected data in an expected-empty lane.
-    error ZeroStride();
-
     // -------------------------------------------------------------------------
     // Opening
     // -------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",

package/utils/Accounts.sol

@@ -34,6 +34,7 @@ library Accounts {
     }
 
     /// @notice Return true if `account` belongs to the EVM account family.
+    /// @dev Classification only; does not require a nonzero embedded address.
     function isEvm(bytes32 account) internal pure returns (bool) {
         return isFamily(uint(account), Family);
     }
@@ -44,20 +45,24 @@ library Accounts {
     }
 
     /// @notice Return true if `account` is an admin account.
+    /// @dev Classification only; does not require a nonzero embedded address.
     function isAdmin(bytes32 account) internal pure returns (bool) {
         return prefix(account) == Admin;
     }
 
     /// @notice Return true if `account` is a user account.
+    /// @dev Classification only; does not require a nonzero embedded address.
     function isUser(bytes32 account) internal pure returns (bool) {
         return prefix(account) == User;
     }
 
-    /// @notice Assert that `value` belongs to the EVM account family and return it unchanged.
+    /// @notice Assert that `value` belongs to the EVM account family, contains
+    /// a nonzero embedded address, and return it unchanged.
     /// @param value Account identifier to validate.
     /// @return account The same `value` if it is an EVM account.
     function evm(bytes32 value) internal pure returns (bytes32 account) {
-        if (!isEvm(value)) revert InvalidAccount();
+        if (!isFamily(uint(value), Family)) revert InvalidAccount();
+        ensureAddr(address(uint160(uint(value) >> 32)));
         return value;
     }
 
@@ -69,19 +74,23 @@ library Accounts {
         return value;
     }
 
-    /// @notice Assert that `value` is an admin account and return it unchanged.
+    /// @notice Assert that `value` is an admin account, contains a nonzero
+    /// embedded address, and return it unchanged.
     /// @param value Account identifier to validate.
     /// @return account The same `value` if it is an admin account.
     function admin(bytes32 value) internal pure returns (bytes32 account) {
-        if (!isAdmin(value)) revert InvalidAccount();
+        if (uint32(uint(value) >> 224) != Admin) revert InvalidAccount();
+        ensureAddr(address(uint160(uint(value) >> 32)));
         return value;
     }
 
-    /// @notice Assert that `value` is a user account and return it unchanged.
+    /// @notice Assert that `value` is a user account, contains a nonzero
+    /// embedded address, and return it unchanged.
     /// @param value Account identifier to validate.
     /// @return account The same `value` if it is a user account.
     function user(bytes32 value) internal pure returns (bytes32 account) {
-        if (!isUser(value)) revert InvalidAccount();
+        if (uint32(uint(value) >> 224) != User) revert InvalidAccount();
+        ensureAddr(address(uint160(uint(value) >> 32)));
         return value;
     }
 
@@ -120,6 +129,6 @@ library Accounts {
     /// @param account EVM-family account ID.
     /// @return Embedded address (bits [191:32] of the ID).
     function addr(bytes32 account) internal pure returns (address) {
-        return ensureAddr(address(uint160(uint(evm(account)) >> 32)));
+        return address(uint160(uint(evm(account)) >> 32));
     }
 }

package/utils/Errors.sol

@@ -7,6 +7,12 @@ error InsufficientValue();
 /// @dev Thrown when a decoder or execution is finalized with unread data.
 error UnconsumedData();
 
+/// @dev Thrown when an operation requires empty state but receives state data.
+error UnexpectedState();
+
+/// @dev Thrown when an operation requires empty input but receives input data.
+error UnexpectedInput();
+
 /// @dev Thrown when an ID does not match the expected convention or type.
 error InvalidId();