@rootzero/contracts 1.22.0 → 1.24.0

package/codec/Blocks.sol

@@ -382,6 +382,22 @@ library Blocks {
         }
     }
 
+    /// @notice Write a DEBT block at `i`.
+    /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B64` bytes first.
+    /// @param dst Destination buffer.
+    /// @param i Relative write position.
+    /// @param liability Liability identifier to encode.
+    /// @param debt Debt quantity to encode.
+    function writeDebt(bytes memory dst, uint i, bytes32 liability, uint debt) internal pure {
+        uint spec = Specs.Debt;
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, spec)
+            mstore(add(p, 0x08), liability)
+            mstore(add(p, 0x28), debt)
+        }
+    }
+
     /// @notice Write a HOST_ASSET block at `i`.
     /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B64` bytes first.
     /// @param dst Destination buffer.
@@ -1014,14 +1030,44 @@ library Blocks {
 
     // Raw reads
 
+    /// @notice Read one byte from an absolute calldata position.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @return value Decoded one-byte value.
+    function read1(uint abs) internal pure returns (bytes1 value) {
+        return bytes1(read32(abs));
+    }
+
+    /// @notice Read two bytes from an absolute calldata position.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @return value Decoded two-byte value.
+    function read2(uint abs) internal pure returns (bytes2 value) {
+        return bytes2(read32(abs));
+    }
+
     /// @notice Read four bytes from an absolute calldata position.
     /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
     /// @param abs Absolute calldata position.
     /// @return value Decoded four-byte value.
     function read4(uint abs) internal pure returns (bytes4 value) {
-        assembly ("memory-safe") {
-            value := calldataload(abs)
-        }
+        return bytes4(read32(abs));
+    }
+
+    /// @notice Read eight bytes from an absolute calldata position.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @return value Decoded eight-byte value.
+    function read8(uint abs) internal pure returns (bytes8 value) {
+        return bytes8(read32(abs));
+    }
+
+    /// @notice Read sixteen bytes from an absolute calldata position.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @return value Decoded sixteen-byte value.
+    function read16(uint abs) internal pure returns (bytes16 value) {
+        return bytes16(read32(abs));
     }
 
     /// @notice Read one word from an absolute calldata position.
@@ -1322,6 +1368,22 @@ library Blocks {
         }
     }
 
+    /// @notice Decode a low-level fixed-width DEBT block at `abs`.
+    /// @param abs Absolute block position.
+    /// @return liability Decoded liability identifier.
+    /// @return debt Decoded debt quantity.
+    function unpackDebt(uint abs) internal pure returns (bytes32 liability, uint debt) {
+        uint head;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+        }
+        if (head >> 192 != Specs.Debt >> 192) revert InvalidBlock();
+        assembly ("memory-safe") {
+            liability := calldataload(add(abs, 0x08))
+            debt := calldataload(add(abs, 0x28))
+        }
+    }
+
     /// @notice Decode a low-level fixed-width ACCOUNT_ASSET block at `abs`.
     /// @param abs Absolute block position.
     /// @return account Decoded account identifier.
@@ -1776,7 +1838,7 @@ library Blocks {
     /// @notice Encode an empty block.
     /// @param key Block type key.
     /// @return value Encoded empty block header.
-    function empty(bytes4 key) internal pure returns (bytes memory value) {
+    function createEmpty(bytes4 key) internal pure returns (bytes memory value) {
         value = allocate(Sizes.Header);
         writeEmpty(value, 0, key);
     }
@@ -1801,28 +1863,28 @@ library Blocks {
     // Dynamic leaf factories
 
     /// @notice Encode a LIST block.
-    function list(bytes memory value) internal pure returns (bytes memory blockdata) {
+    function createList(bytes memory value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         writeList(blockdata, 0, value);
     }
 
     /// @notice Encode a LIST block by copying its payload from calldata.
-    function listCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
+    function createListCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         copyList(blockdata, 0, value);
     }
 
     /// @notice Encode an EVM block.
-    function evm(bytes memory value) internal pure returns (bytes memory blockdata) {
+    function createEvm(bytes memory value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         writeEvm(blockdata, 0, value);
     }
 
     /// @notice Encode an EVM block by copying its payload from calldata.
-    function evmCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
+    function createEvmCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         copyEvm(blockdata, 0, value);
@@ -1831,14 +1893,14 @@ library Blocks {
     /// @notice Encode a BYTES block with a raw payload.
     /// @param value Raw payload bytes.
     /// @return blockdata Encoded BYTES block bytes.
-    function data(bytes memory value) internal pure returns (bytes memory blockdata) {
+    function createBytes(bytes memory value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         writeBytes(blockdata, 0, value);
     }
 
     /// @notice Encode a BYTES block by copying its payload from calldata.
-    function dataCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
+    function createBytesCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         copyBytes(blockdata, 0, value);
@@ -1847,14 +1909,14 @@ library Blocks {
     /// @notice Encode a STRING block with a UTF-8 payload.
     /// @param value String payload.
     /// @return blockdata Encoded STRING block bytes.
-    function text(string memory value) internal pure returns (bytes memory blockdata) {
+    function createString(string memory value) internal pure returns (bytes memory blockdata) {
         uint len = max32(bytes(value).length);
         blockdata = allocate(Sizes.Header + len);
         writeString(blockdata, 0, value);
     }
 
     /// @notice Encode a STRING block by copying its payload from calldata.
-    function textCopy(string calldata value) internal pure returns (bytes memory blockdata) {
+    function createStringCopy(string calldata value) internal pure returns (bytes memory blockdata) {
         uint len = max32(bytes(value).length);
         blockdata = allocate(Sizes.Header + len);
         copyString(blockdata, 0, value);
@@ -1866,7 +1928,7 @@ library Blocks {
     /// @param namespace Label namespace.
     /// @param name Label text.
     /// @return value Encoded LABEL block bytes.
-    function label(bytes32 namespace, string memory name) internal pure returns (bytes memory value) {
+    function createLabel(bytes32 namespace, string memory name) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B32 + bytes(name).length);
         value = allocate(Sizes.Header + len);
         writeLabel(value, 0, namespace, name);
@@ -1875,7 +1937,7 @@ library Blocks {
     /// @notice Encode an ACTION annotation block.
     /// @param actionid Canonical semantic action identifier.
     /// @return value Encoded ACTION block bytes.
-    function action(uint actionid) internal pure returns (bytes memory value) {
+    function createAction(uint actionid) internal pure returns (bytes memory value) {
         value = allocate(Sizes.B32);
         write32(value, 0, Keys.Action, bytes32(actionid));
     }
@@ -1884,8 +1946,8 @@ library Blocks {
     /// @param spec Block specification.
     /// @param body Schema body.
     /// @return value Encoded SCHEMA block bytes.
-    function schema(uint spec, string memory body) internal pure returns (bytes memory value) {
-        return schema(spec, body, bytes32(0));
+    function createSchema(uint spec, string memory body) internal pure returns (bytes memory value) {
+        return createSchema(spec, body, bytes32(0));
     }
 
     /// @notice Encode a named SCHEMA block.
@@ -1893,7 +1955,7 @@ library Blocks {
     /// @param body Schema body.
     /// @param name Schema name.
     /// @return value Encoded SCHEMA block bytes.
-    function schema(uint spec, string memory body, bytes32 name) internal pure returns (bytes memory value) {
+    function createSchema(uint spec, string memory body, bytes32 name) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + bytes(body).length);
         value = allocate(Sizes.Header + len);
         writeSchema(value, 0, spec, body, name);
@@ -1901,21 +1963,39 @@ library Blocks {
 
     // Fixed-width factories
 
+    /// @notice Encode an AMOUNT block.
+    /// @param asset Asset identifier.
+    /// @param amount Token amount.
+    /// @return value Encoded AMOUNT block bytes.
+    function createAmount(bytes32 asset, uint amount) internal pure returns (bytes memory value) {
+        value = allocate(Sizes.Amount);
+        writeAmount(value, 0, asset, amount);
+    }
+
     /// @notice Encode a BALANCE block.
     /// @param asset Asset identifier.
     /// @param amount Token amount.
     /// @return value Encoded BALANCE block bytes.
-    function balance(bytes32 asset, uint amount) internal pure returns (bytes memory value) {
+    function createBalance(bytes32 asset, uint amount) internal pure returns (bytes memory value) {
         value = allocate(Sizes.Balance);
         writeBalance(value, 0, asset, amount);
     }
 
+    /// @notice Encode a DEBT block.
+    /// @param liability Liability identifier.
+    /// @param debt Debt quantity.
+    /// @return value Encoded DEBT block bytes.
+    function createDebt(bytes32 liability, uint debt) internal pure returns (bytes memory value) {
+        value = allocate(Sizes.Debt);
+        writeDebt(value, 0, liability, debt);
+    }
+
     /// @notice Encode a CUSTODY block.
     /// @param host Host node ID holding the custody.
     /// @param asset Asset identifier.
     /// @param amount Token amount.
     /// @return value Encoded CUSTODY block bytes.
-    function custody(uint host, bytes32 asset, uint amount) internal pure returns (bytes memory value) {
+    function createCustody(uint host, bytes32 asset, uint amount) internal pure returns (bytes memory value) {
         value = allocate(Sizes.B96);
         writeCustody(value, 0, host, asset, amount);
     }
@@ -1926,7 +2006,7 @@ library Blocks {
     /// @param liability Identifier for the liability side.
     /// @param debt Quantity owed on the liability side.
     /// @return value Encoded POSITION block bytes.
-    function position(
+    function createPosition(
         bytes32 asset,
         uint amount,
         bytes32 liability,
@@ -1942,7 +2022,7 @@ library Blocks {
     /// @param asset Asset identifier.
     /// @param amount Transfer amount.
     /// @return value Encoded TRANSACTION block bytes.
-    function transaction(
+    function createTransaction(
         bytes32 from,
         bytes32 to,
         bytes32 asset,
@@ -1959,14 +2039,14 @@ library Blocks {
     /// @param resources Packed resources assigned to the step.
     /// @param input Raw nested input payload.
     /// @return value Encoded STEP block bytes.
-    function step(uint cmd, uint resources, bytes memory input) internal pure returns (bytes memory value) {
+    function createStep(uint cmd, uint resources, bytes memory input) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + input.length);
         value = allocate(len);
         writeStep(value, 0, cmd, resources, input);
     }
 
     /// @notice Encode a STEP block by copying its nested input from calldata.
-    function stepCopy(uint cmd, uint resources, bytes calldata input) internal pure returns (bytes memory value) {
+    function createStepCopy(uint cmd, uint resources, bytes calldata input) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + input.length);
         value = allocate(len);
         copyStep(value, 0, cmd, resources, input);
@@ -1977,14 +2057,14 @@ library Blocks {
     /// @param resources Packed resources assigned to the call.
     /// @param payload Raw calldata payload for the target.
     /// @return value Encoded CALL block bytes.
-    function call(uint target, uint resources, bytes memory payload) internal pure returns (bytes memory value) {
+    function createCall(uint target, uint resources, bytes memory payload) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + payload.length);
         value = allocate(len);
         writeCall(value, 0, target, resources, payload);
     }
 
     /// @notice Encode a CALL block by copying its nested payload from calldata.
-    function callCopy(uint target, uint resources, bytes calldata payload) internal pure returns (bytes memory value) {
+    function createCallCopy(uint target, uint resources, bytes calldata payload) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + payload.length);
         value = allocate(len);
         copyCall(value, 0, target, resources, payload);
@@ -1996,14 +2076,14 @@ library Blocks {
     /// @param resources Chain-specific resources for the destination context.
     /// @param input Nested input block stream.
     /// @return value Encoded RELAY block bytes.
-    function relay(uint portal, uint resources, bytes memory input) internal pure returns (bytes memory value) {
+    function createRelay(uint portal, uint resources, bytes memory input) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + input.length);
         value = allocate(len);
         writeRelay(value, 0, portal, resources, input);
     }
 
     /// @notice Encode a RELAY block by copying its nested input from calldata.
-    function relayCopy(uint portal, uint resources, bytes calldata input) internal pure returns (bytes memory value) {
+    function createRelayCopy(uint portal, uint resources, bytes calldata input) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + input.length);
         value = allocate(len);
         copyRelay(value, 0, portal, resources, input);
@@ -2015,14 +2095,14 @@ library Blocks {
     /// @param resources Chain-specific resources for the destination dispatch.
     /// @param payload Encoded payload.
     /// @return value Encoded DISPATCH block bytes.
-    function dispatch(uint portal, uint resources, bytes memory payload) internal pure returns (bytes memory value) {
+    function createDispatch(uint portal, uint resources, bytes memory payload) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + payload.length);
         value = allocate(len);
         writeDispatch(value, 0, portal, resources, payload);
     }
 
     /// @notice Encode a DISPATCH block by copying its nested payload from calldata.
-    function dispatchCopy(
+    function createDispatchCopy(
         uint portal,
         uint resources,
         bytes calldata payload
@@ -2033,7 +2113,7 @@ library Blocks {
     }
 
     /// @notice Encode a CONTEXT block.
-    function context(
+    function createContext(
         bytes32 account,
         bytes memory state,
         bytes memory input
@@ -2044,7 +2124,7 @@ library Blocks {
     }
 
     /// @notice Encode a CONTEXT block by copying its nested streams from calldata.
-    function contextCopy(
+    function createContextCopy(
         bytes32 account,
         bytes calldata state,
         bytes calldata input
@@ -2055,7 +2135,7 @@ library Blocks {
     }
 
     /// @notice Encode a RECOVER block.
-    function recover(
+    function createRecover(
         uint handler,
         uint resources,
         bytes32 recoverykey,
@@ -2067,7 +2147,7 @@ library Blocks {
     }
 
     /// @notice Encode a RECOVER block by copying its nested witness from calldata.
-    function recoverCopy(
+    function createRecoverCopy(
         uint handler,
         uint resources,
         bytes32 recoverykey,

package/codec/Decoders.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, Position, Tx} from "../core/Types.sol";
+import {AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, Debt, Position, Tx} from "../core/Types.sol";
 import {Blocks} from "./Blocks.sol";
 import {Sizes, Specs} from "./Specs.sol";
 import {Cursors, Cur} from "../utils/Cursors.sol";
@@ -427,6 +427,16 @@ library Decoders {
         (asset, amount) = Blocks.unpackBalance(abs);
     }
 
+    /// @notice Decode and consume one DEBT block.
+    /// @param cur Cursor advanced past the block.
+    /// @return liability Decoded liability identifier.
+    /// @return debt Decoded debt quantity.
+    function unpackDebt(Cur memory cur) internal pure returns (bytes32 liability, uint debt) {
+        uint abs;
+        (cur.state, abs) = cur.state.consume(Sizes.Debt);
+        (liability, debt) = Blocks.unpackDebt(abs);
+    }
+
     /// @notice Decode one BALANCE block and associate it with `host`.
     /// @param cur Cursor advanced past the block.
     /// @param host Host identifier associated with the balance.
@@ -614,6 +624,13 @@ library Decoders {
         (value.asset, value.amount) = unpackBalance(cur);
     }
 
+    /// @notice Decode one DEBT block into its structured value.
+    /// @param cur Cursor advanced past the block.
+    /// @return value Structured liability and debt.
+    function unpackDebtValue(Cur memory cur) internal pure returns (Debt memory value) {
+        (value.liability, value.debt) = unpackDebt(cur);
+    }
+
     /// @notice Decode and consume one HOST_ACCOUNT_ASSET block.
     /// @param cur Cursor advanced past the block.
     /// @return host Decoded host identifier.

package/codec/Descriptors.sol

@@ -6,6 +6,7 @@ import {Lanes} from "../utils/Lanes.sol";
 
 /// @title Flags
 /// @notice Packed endpoint behavior flags.
+/// @dev Bits 6 and 7 are reserved for endpoint-defined custom flags.
 library Flags {
     /// @dev Endpoint accepts nonzero native value.
     uint8 internal constant Funded = 1 << 0;
@@ -27,7 +28,8 @@ library Descriptors {
     /// `[output key:4][min:4][max:4][hint:3][stride:1]`
     /// `[reserved:4]`
     /// `[transactions:1]`
-    /// `[flags:1]`. Flag bits: funded = 0, admin = 1.
+    /// `[flags:1]`. Flag bits: funded = 0, admin = 1; bits 6 and 7 are
+    /// reserved for endpoint-defined custom flags.
     /// @param state State lane specification.
     /// @param input Direct input lane specification.
     /// @param output Output writer specification.

package/codec/Keys.sol

@@ -13,6 +13,8 @@ library Keys {
     bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, uint amount)
     bytes4 constant Balance = bytes4(keccak256("#balance"));
+    /// @dev Liability-only debt state - (bytes32 liability, uint debt)
+    bytes4 constant Debt = bytes4(keccak256("#debt"));
     /// @dev Host-scoped input amount - (uint host, bytes32 asset, uint amount)
     bytes4 constant Allocation = bytes4(keccak256("#allocation"));
     /// @dev Host-scoped allowance cap - (uint host, bytes32 asset, uint amount)

package/codec/Readers.sol

@@ -133,6 +133,18 @@ library Readers {
         }
     }
 
+    /// @notice Consume a DEBT block and return its fields.
+    /// @param cur Reader; advanced past the block.
+    /// @return liability Liability identifier.
+    /// @return debt Debt quantity.
+    function unpackDebt(Reader memory cur) internal pure returns (bytes32 liability, uint debt) {
+        uint abs = consume(cur, Keys.Debt, 64, 64);
+        assembly ("memory-safe") {
+            liability := mload(abs)
+            debt := mload(add(abs, 0x20))
+        }
+    }
+
     /// @notice Consume a HOST_ASSET block and return its fields.
     /// @param cur Reader; advanced past the block.
     /// @return host Host identifier.

package/codec/Schema.sol

@@ -53,12 +53,12 @@ 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(...)`, `custody(...)`, and `position(...)` are live, linear state in the active command pipeline
+// - `balance(...)`, `debt(...)`, `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
+// - while a balance, debt, 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
+// - debt carries only a live liability side; position pairs live balance and debt sides
+// - 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
 // - input blocks such as `amount(...)`, `allocation(...)`, and `allowance(...)`
@@ -89,6 +89,7 @@ library Schemas {
 
     string constant Amount = "bytes32 asset, uint amount";
     string constant Balance = "bytes32 asset, uint amount";
+    string constant Debt = "bytes32 liability, uint debt";
     string constant AccountAsset = "bytes32 account, bytes32 asset";
     string constant HostAsset = "uint host, bytes32 asset";
 

package/codec/Specs.sol

@@ -27,6 +27,8 @@ library Sizes {
     uint constant Amount = B64;
     /// @dev BALANCE block: 8 header + 32 asset + 32 amount = 72 bytes
     uint constant Balance = B64;
+    /// @dev DEBT block: 8 header + 32 liability + 32 debt = 72 bytes
+    uint constant Debt = B64;
     /// @dev HOST_ASSET block: 8 header + 32 host + 32 asset = 72 bytes
     uint constant HostAsset = B64;
     /// @dev ALLOCATION/CUSTODY block: 8 header + 32 host + 32 asset + 32 amount = 104 bytes
@@ -63,6 +65,7 @@ library Specs {
     uint constant Empty = uint(bytes32(Keys.Empty));
     uint constant Amount = uint(bytes32(Keys.Amount)) | Exact64;
     uint constant Balance = uint(bytes32(Keys.Balance)) | Exact64;
+    uint constant Debt = uint(bytes32(Keys.Debt)) | Exact64;
     uint constant Allocation = uint(bytes32(Keys.Allocation)) | Exact96;
     uint constant Allowance = uint(bytes32(Keys.Allowance)) | Exact96;
     uint constant Custody = uint(bytes32(Keys.Custody)) | Exact96;

package/codec/Writers.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AssetAmount, AccountAmount, HostAmount, Position, Tx} from "../core/Types.sol";
+import {AssetAmount, AccountAmount, HostAmount, Debt, Position, Tx} from "../core/Types.sol";
 import {Blocks} from "./Blocks.sol";
 import {Buffers} from "./Buffers.sol";
 import {Sizes, Specs} from "./Specs.sol";
@@ -204,6 +204,17 @@ library Writers {
         appendBalance(writer, value.asset, value.amount);
     }
 
+    /// @notice Append a DEBT block.
+    function appendDebt(Writer memory writer, bytes32 liability, uint debt) internal pure {
+        uint i = reserve(writer, Sizes.Debt);
+        Blocks.writeDebt(writer.dst, i, liability, debt);
+    }
+
+    /// @notice Append a structured DEBT value.
+    function appendDebt(Writer memory writer, Debt memory value) internal pure {
+        appendDebt(writer, value.liability, value.debt);
+    }
+
     /// @notice Append an ACCOUNT_ASSET block.
     /// @param writer Destination writer.
     /// @param account Account identifier to encode.

package/commands/Allocate.sol

@@ -28,23 +28,20 @@ abstract contract Allocate is CommandBase, AllocateHook {
     }
 
     /// @notice Allocate BALANCE state blocks to matching NODE input blocks.
-    /// @param state BALANCE block stream.
-    /// @param input Matching NODE block stream.
+    /// @param context Command context carrying BALANCE state and matching NODE input.
     /// @return CUSTODY block stream matching the allocated balances.
     /// @return Empty transaction stream.
     function allocate(
-        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()) {
             HostAmount memory custody = exec.unpackBalanceForHost(Lanes.State, exec.unpackNode(Lanes.Input));
-            allocate(account, custody);
+            allocate(exec.account, custody);
             exec.outputCustody(custody);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/Base.sol

@@ -70,40 +70,56 @@ abstract contract CommandBase is CallerAccess, EndpointBase, ReceivedEvent {
         published = endpoint(id, name, descriptor);
     }
 
-    /// @notice Open and validate both command lanes, including lanes declared EMPTY.
+    /// @notice Decode the command ABI argument as exactly one complete CONTEXT block.
+    /// @dev Rejects empty input, trailing bytes, and additional context blocks.
+    function unpackCommandContext(
+        bytes calldata context
+    ) internal pure returns (bytes32 account, bytes calldata state, bytes calldata input) {
+        uint abs;
+        assembly ("memory-safe") {
+            abs := context.offset
+        }
+
+        uint end;
+        (account, state, input, end) = Blocks.unpackContext(abs);
+        if (end != abs + context.length) revert Blocks.InvalidBlock();
+    }
+
+    /// @notice Decode one command context and validate both lanes, including lanes declared EMPTY.
     /// Batches are derived from the input and state lanes. A non-empty stream for
     /// a lane whose descriptor has zero stride reverts instead of being ignored.
     /// Commands must account for the complete validated state by consuming it,
     /// transforming and returning it, forwarding it intact, or reverting.
-    /// @param state Current command state block stream.
-    /// @param input Command input block stream.
+    /// @param context Exactly one CONTEXT block carrying the account, state, and input.
     /// @param descriptor Packed command endpoint descriptor.
     /// @param batches Required batch count, or zero to reconcile the lane counts.
     /// @return exec Execution with its output buffer metadata initialized for the reconciled batch count.
     function openCommand(
-        bytes calldata state,
-        bytes calldata input,
+        bytes calldata context,
         uint descriptor,
         uint batches
     ) internal view returns (Execution memory exec) {
-        return Executions.open(state, input, descriptor, batches);
+        bytes32 account;
+        bytes calldata state;
+        bytes calldata input;
+        (account, state, input) = unpackCommandContext(context);
+        exec = Executions.open(state, input, descriptor, batches);
+        exec.account = account;
     }
 
-    /// @notice Close a command execution and refund unspent value to `account`.
+    /// @notice Close a command execution and refund unspent value to its account.
     /// @param exec Command execution to close.
-    /// @param account Account that should receive any unspent value.
     /// @return output Final encoded output block stream.
     /// @return transactions Final encoded transaction block stream.
-    function close(
-        Execution memory exec,
-        bytes32 account
+    function closeCommand(
+        Execution memory exec
     ) internal returns (bytes memory output, bytes memory transactions) {
         if (exec.budget == 0 && Cursors.initial(exec.writers)) return ("", "");
 
         output = close(exec);
-        uint amount = exec.refundValue(account, nativeAsset);
+        uint amount = exec.refundValue(exec.account, nativeAsset);
         if (amount != 0) {
-            emit Received(account, nativeAsset, amount, Actions.Refund, 0);
+            emit Received(exec.account, nativeAsset, amount, Actions.Refund, 0);
         }
 
         transactions = exec.finishTransactions();

package/commands/Burn.sol

@@ -30,22 +30,20 @@ abstract contract Burn is CommandBase, BurnHook, Action {
     }
 
     /// @notice Burn each BALANCE block from the command state.
-    /// @param state BALANCE block stream.
+    /// @param context Command context carrying the BALANCE state stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function burn(
-        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.unpackBalance(Lanes.State);
-            burn(account, asset, amount);
+            burn(exec.account, asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }