@rootzero/contracts 1.24.0 → 1.26.0

package/codec/Blocks.sol

@@ -100,16 +100,38 @@ library Blocks {
         end = body + len;
     }
 
+    /// @notice Validate a known block key and return its payload bounds.
+    /// @dev DANGER: This performs an unchecked calldata read and validates only
+    /// the key. The caller must validate the known payload shape and returned end.
+    /// @param abs Absolute calldata position of the header.
+    /// @param key Expected block key.
+    /// @return body Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function expectKey(uint abs, bytes4 key) internal pure returns (uint body, uint end) {
+        uint head;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+        }
+        if (uint32(head >> 224) != uint32(key)) revert InvalidBlock();
+        uint len = uint32(head >> 192);
+        unchecked {
+            body = abs + Sizes.Header;
+            end = body + len;
+        }
+    }
+
     /// @dev Validate the key and exact payload size of a fixed-width block.
     /// @param abs Absolute calldata position of the header.
-    /// @param spec Expected block specification.
+    /// @param key Expected block key.
     /// @param size Expected payload length.
     /// @return body Absolute position of the payload.
     /// @return end Absolute position after the payload.
-    function expectFixed(uint abs, uint spec, uint size) private pure returns (uint body, uint end) {
-        if (header(abs, Specs.key(spec)) != size) revert InvalidBlock();
-        body = abs + Sizes.Header;
-        end = body + size;
+    function expectFixed(uint abs, bytes4 key, uint size) private pure returns (uint body, uint end) {
+        if (header(abs, key) != size) revert InvalidBlock();
+        unchecked {
+            body = abs + Sizes.Header;
+            end = body + size;
+        }
     }
 
     /// @notice Validate an empty block at an absolute calldata position.
@@ -139,8 +161,9 @@ library Blocks {
     /// @param key Expected block key.
     /// @return Whether the expected key occurs with a zero-length payload.
     function isEmpty(uint abs, uint end, bytes4 key) internal pure returns (bool) {
-        if (!hasAt(abs, end, key)) return false;
-        return uint32(uint(read32(abs)) >> 192) == 0;
+        if (abs > end || Sizes.Header > end - abs) return false;
+        uint head = uint(read32(abs));
+        return uint32(head >> 224) == uint32(key) && uint32(head >> 192) == 0;
     }
 
     /// @notice Find the first block with `key` at or after absolute position `abs`.
@@ -178,6 +201,31 @@ library Blocks {
         }
     }
 
+    /// @notice Count consecutive blocks with `key` using a minimal hint-only scan.
+    /// @dev DANGER: This is not validation. It stops on a different key or when the
+    /// next declared block end exceeds `limit`; malformed or trailing data does not
+    /// revert. Use only for optional allocation hints whose result is later validated
+    /// by normal decoding and execution finalization.
+    /// @param abs Absolute start position.
+    /// @param limit Absolute region boundary.
+    /// @param key Block key forming the run.
+    /// @return total Number of complete consecutive matching blocks.
+    function runCount(uint abs, uint limit, bytes4 key) internal pure returns (uint total) {
+        uint expected = uint32(key);
+        assembly ("memory-safe") {
+            for { } lt(abs, limit) { } {
+                let head := calldataload(abs)
+                if iszero(eq(shr(224, head), expected)) { break }
+
+                let next := add(add(abs, 8), and(shr(192, head), 0xffffffff))
+                if gt(next, limit) { break }
+
+                abs := next
+                total := add(total, 1)
+            }
+        }
+    }
+
     /// @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.
@@ -332,6 +380,20 @@ library Blocks {
         }
     }
 
+    /// @notice Write a CASHOUT block at `i`.
+    /// @dev DANGER: Unchecked memory write. Reserve `Sizes.Cashout` bytes first.
+    /// @param dst Destination buffer.
+    /// @param i Relative write position.
+    /// @param amount Native-asset amount to withdraw.
+    function writeCashout(bytes memory dst, uint i, uint amount) internal pure {
+        uint spec = Specs.Cashout;
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, spec)
+            mstore(add(p, 0x08), amount)
+        }
+    }
+
     // Two-word payloads
 
     /// @notice Write an AMOUNT block at `i`.
@@ -416,6 +478,24 @@ library Blocks {
 
     // Three-word payloads
 
+    /// @notice Write a BOOTSTRAP block at `i`.
+    /// @dev DANGER: Unchecked memory write. Reserve `Sizes.Bootstrap` bytes first.
+    /// @param dst Destination buffer.
+    /// @param i Relative write position.
+    /// @param asset Asset identifier to bootstrap.
+    /// @param amount Balance amount to source.
+    /// @param budget Native-value budget to source.
+    function writeBootstrap(bytes memory dst, uint i, bytes32 asset, uint amount, uint budget) internal pure {
+        uint spec = Specs.Bootstrap;
+        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), budget)
+        }
+    }
+
     /// @notice Write an ALLOCATION block at `i`.
     /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B96` bytes first.
     /// @param dst Destination buffer.
@@ -679,19 +759,19 @@ library Blocks {
     /// @param dst Destination buffer.
     /// @param i Relative write position.
     /// @param cmd Command identifier.
-    /// @param resources Packed resources.
+    /// @param value Native value assigned to the step.
     /// @param input Command input.
-    function writeStep(bytes memory dst, uint i, uint cmd, uint resources, bytes memory input) internal pure {
-        uint len = 64 + Sizes.Header + input.length;
+    function writeStep(bytes memory dst, uint i, uint cmd, uint128 value, bytes memory input) internal pure {
+        uint len = 48 + Sizes.Header + input.length;
         uint key = uint32(Keys.Step);
         uint byteskey = uint32(Keys.Bytes);
         assembly ("memory-safe") {
             let p := add(add(dst, 0x20), i)
             mstore(p, or(shl(224, key), shl(192, len)))
             mstore(add(p, 0x08), cmd)
-            mstore(add(p, 0x28), resources)
+            mstore(add(p, 0x28), shl(128, value))
 
-            let q := add(p, 0x48)
+            let q := add(p, 0x38)
             let inputlen := mload(input)
             mstore(q, or(shl(224, byteskey), shl(192, inputlen)))
             mcopy(add(q, 0x08), add(input, 0x20), inputlen)
@@ -951,8 +1031,21 @@ library Blocks {
     }
 
     /// @notice Encode a STEP block at `i`, copying its nested input from calldata.
-    function copyStep(bytes memory dst, uint i, uint cmd, uint resources, bytes calldata input) internal pure {
-        copyComposite(dst, i, Keys.Step, cmd, resources, input);
+    function copyStep(bytes memory dst, uint i, uint cmd, uint128 value, bytes calldata input) internal pure {
+        uint len = max32(48 + Sizes.Header + input.length);
+        uint key = uint32(Keys.Step);
+        uint byteskey = uint32(Keys.Bytes);
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, or(shl(224, key), shl(192, len)))
+            mstore(add(p, 0x08), cmd)
+            mstore(add(p, 0x28), shl(128, value))
+
+            let q := add(p, 0x38)
+            let inputlen := input.length
+            mstore(q, or(shl(224, byteskey), shl(192, inputlen)))
+            calldatacopy(add(q, 0x08), input.offset, inputlen)
+        }
     }
 
     /// @notice Encode a CALL block at `i`, copying its nested payload from calldata.
@@ -1080,6 +1173,46 @@ library Blocks {
         }
     }
 
+    /// @notice Require the byte at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected byte.
+    function require1(uint abs, bytes1 expected) internal pure {
+        if (read1(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the two bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected two-byte value.
+    function require2(uint abs, bytes2 expected) internal pure {
+        if (read2(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the four bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected four-byte value.
+    function require4(uint abs, bytes4 expected) internal pure {
+        if (read4(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the eight bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected eight-byte value.
+    function require8(uint abs, bytes8 expected) internal pure {
+        if (read8(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the sixteen bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected sixteen-byte value.
+    function require16(uint abs, bytes16 expected) internal pure {
+        if (read16(abs) != expected) revert UnexpectedValue();
+    }
+
     /// @notice Require the word at an absolute calldata position to match `expected`.
     /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
     /// @param abs Absolute calldata position.
@@ -1106,7 +1239,7 @@ library Blocks {
     /// @return a First payload word.
     /// @return end Absolute position after the block.
     function unpack32(uint abs, uint spec) internal pure returns (bytes32 a, uint end) {
-        (abs, end) = expectFixed(abs, spec, 32);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 32);
         a = read32(abs);
     }
 
@@ -1117,7 +1250,7 @@ library Blocks {
     /// @return b Second payload word.
     /// @return end Absolute position after the block.
     function unpack64(uint abs, uint spec) internal pure returns (bytes32 a, bytes32 b, uint end) {
-        (abs, end) = expectFixed(abs, spec, 64);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 64);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1135,7 +1268,7 @@ library Blocks {
         uint abs,
         uint spec
     ) internal pure returns (bytes32 a, bytes32 b, bytes32 c, uint end) {
-        (abs, end) = expectFixed(abs, spec, 96);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 96);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1155,7 +1288,7 @@ library Blocks {
         uint abs,
         uint spec
     ) internal pure returns (bytes32 a, bytes32 b, bytes32 c, bytes32 d, uint end) {
-        (abs, end) = expectFixed(abs, spec, 128);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 128);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1177,7 +1310,7 @@ library Blocks {
         uint abs,
         uint spec
     ) internal pure returns (bytes32 a, bytes32 b, bytes32 c, bytes32 d, bytes32 e, uint end) {
-        (abs, end) = expectFixed(abs, spec, 160);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 160);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1284,11 +1417,9 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.Account >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             account := calldataload(add(abs, 0x08))
         }
+        if (head >> 192 != Specs.Account >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width ASSET block at `abs`.
@@ -1298,11 +1429,9 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.Asset >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             asset := calldataload(add(abs, 0x08))
         }
+        if (head >> 192 != Specs.Asset >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width NODE block at `abs`.
@@ -1312,11 +1441,9 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.Node >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             node := calldataload(add(abs, 0x08))
         }
+        if (head >> 192 != Specs.Node >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width STATUS block at `abs`.
@@ -1326,11 +1453,21 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
+            code := calldataload(add(abs, 0x08))
         }
         if (head >> 192 != Specs.Status >> 192) revert InvalidBlock();
+    }
+
+    /// @notice Decode a low-level fixed-width CASHOUT block at `abs`.
+    /// @param abs Absolute block position.
+    /// @return amount Native-asset amount to withdraw.
+    function unpackCashout(uint abs) internal pure returns (uint amount) {
+        uint head;
         assembly ("memory-safe") {
-            code := calldataload(add(abs, 0x08))
+            head := calldataload(abs)
+            amount := calldataload(add(abs, 0x08))
         }
+        if (head >> 192 != Specs.Cashout >> 192) revert InvalidBlock();
     }
 
     // Two-word payloads
@@ -1343,12 +1480,10 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.Amount >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             asset := calldataload(add(abs, 0x08))
             amount := calldataload(add(abs, 0x28))
         }
+        if (head >> 192 != Specs.Amount >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width BALANCE block at `abs`.
@@ -1359,13 +1494,10 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.Balance >> 192) revert InvalidBlock();
-
-        assembly ("memory-safe") {
             asset := calldataload(add(abs, 0x08))
             amount := calldataload(add(abs, 0x28))
         }
+        if (head >> 192 != Specs.Balance >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width DEBT block at `abs`.
@@ -1376,12 +1508,10 @@ library Blocks {
         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))
         }
+        if (head >> 192 != Specs.Debt >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width ACCOUNT_ASSET block at `abs`.
@@ -1392,16 +1522,30 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.AccountAsset >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             account := calldataload(add(abs, 0x08))
             asset := calldataload(add(abs, 0x28))
         }
+        if (head >> 192 != Specs.AccountAsset >> 192) revert InvalidBlock();
     }
 
     // Three-word payloads
 
+    /// @notice Decode a low-level fixed-width BOOTSTRAP block at `abs`.
+    /// @param abs Absolute block position.
+    /// @return asset Decoded asset identifier.
+    /// @return amount Decoded balance amount.
+    /// @return budget Decoded native-value budget contribution.
+    function unpackBootstrap(uint abs) internal pure returns (bytes32 asset, uint amount, uint budget) {
+        uint head;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+            asset := calldataload(add(abs, 0x08))
+            amount := calldataload(add(abs, 0x28))
+            budget := calldataload(add(abs, 0x48))
+        }
+        if (head >> 192 != Specs.Bootstrap >> 192) revert InvalidBlock();
+    }
+
     /// @notice Decode a low-level fixed-width ALLOCATION block at `abs`.
     /// @param abs Absolute block position.
     /// @return host Decoded host identifier.
@@ -1411,13 +1555,11 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.Allocation >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             host := calldataload(add(abs, 0x08))
             asset := calldataload(add(abs, 0x28))
             amount := calldataload(add(abs, 0x48))
         }
+        if (head >> 192 != Specs.Allocation >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width ALLOWANCE block at `abs`.
@@ -1429,13 +1571,11 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.Allowance >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             host := calldataload(add(abs, 0x08))
             asset := calldataload(add(abs, 0x28))
             amount := calldataload(add(abs, 0x48))
         }
+        if (head >> 192 != Specs.Allowance >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width CUSTODY block at `abs`.
@@ -1447,13 +1587,11 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.Custody >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             host := calldataload(add(abs, 0x08))
             asset := calldataload(add(abs, 0x28))
             amount := calldataload(add(abs, 0x48))
         }
+        if (head >> 192 != Specs.Custody >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width ACCOUNT_AMOUNT block at `abs`.
@@ -1465,13 +1603,11 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.AccountAmount >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             account := calldataload(add(abs, 0x08))
             asset := calldataload(add(abs, 0x28))
             amount := calldataload(add(abs, 0x48))
         }
+        if (head >> 192 != Specs.AccountAmount >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width HOST_AMOUNT block at `abs`.
@@ -1483,13 +1619,11 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.HostAmount >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             host := calldataload(add(abs, 0x08))
             asset := calldataload(add(abs, 0x28))
             amount := calldataload(add(abs, 0x48))
         }
+        if (head >> 192 != Specs.HostAmount >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width HOST_ACCOUNT_ASSET block at `abs`.
@@ -1501,13 +1635,11 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.HostAccountAsset >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             host := calldataload(add(abs, 0x08))
             account := calldataload(add(abs, 0x28))
             asset := calldataload(add(abs, 0x48))
         }
+        if (head >> 192 != Specs.HostAccountAsset >> 192) revert InvalidBlock();
     }
 
     // Four-word payloads
@@ -1524,14 +1656,12 @@ library Blocks {
         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))
         }
+        if (head >> 192 != Specs.Position >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width HOST_ASSET block at `abs`.
@@ -1542,12 +1672,10 @@ library Blocks {
         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))
         }
+        if (head >> 192 != Specs.HostAsset >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width TRANSACTION block at `abs`.
@@ -1560,14 +1688,12 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.Transaction >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             from := calldataload(add(abs, 0x08))
             to := calldataload(add(abs, 0x28))
             asset := calldataload(add(abs, 0x48))
             amount := calldataload(add(abs, 0x68))
         }
+        if (head >> 192 != Specs.Transaction >> 192) revert InvalidBlock();
     }
 
     /// @notice Decode a low-level fixed-width HOST_ACCOUNT_AMOUNT block at `abs`.
@@ -1582,14 +1708,12 @@ library Blocks {
         uint head;
         assembly ("memory-safe") {
             head := calldataload(abs)
-        }
-        if (head >> 192 != Specs.HostAccountAmount >> 192) revert InvalidBlock();
-        assembly ("memory-safe") {
             host := calldataload(add(abs, 0x08))
             account := calldataload(add(abs, 0x28))
             asset := calldataload(add(abs, 0x48))
             amount := calldataload(add(abs, 0x68))
         }
+        if (head >> 192 != Specs.HostAccountAmount >> 192) revert InvalidBlock();
     }
 
     // Dynamic leaf blocks
@@ -1599,7 +1723,16 @@ library Blocks {
     /// @return value Decoded list payload.
     /// @return end Absolute position after the block.
     function unpackList(uint abs) internal pure returns (bytes calldata value, uint end) {
-        return unpackRaw(abs, Keys.List);
+        uint head;
+        uint len;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+            len := and(shr(192, head), 0xffffffff)
+            value.offset := add(abs, 0x08)
+            value.length := len
+        }
+        if (uint32(head >> 224) != uint32(Keys.List)) revert InvalidBlock();
+        end = abs + Sizes.Header + len;
     }
 
     /// @notice Decode one EVM payload and its absolute end position.
@@ -1607,7 +1740,16 @@ library Blocks {
     /// @return value Decoded EVM payload.
     /// @return end Absolute position after the block.
     function unpackEvm(uint abs) internal pure returns (bytes calldata value, uint end) {
-        return unpackRaw(abs, Keys.Evm);
+        uint head;
+        uint len;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+            len := and(shr(192, head), 0xffffffff)
+            value.offset := add(abs, 0x08)
+            value.length := len
+        }
+        if (uint32(head >> 224) != uint32(Keys.Evm)) revert InvalidBlock();
+        end = abs + Sizes.Header + len;
     }
 
     /// @notice Decode one BYTES payload and its absolute end position.
@@ -1615,7 +1757,16 @@ library Blocks {
     /// @return value Decoded byte payload.
     /// @return end Absolute position after the block.
     function unpackBytes(uint abs) internal pure returns (bytes calldata value, uint end) {
-        return unpackRaw(abs, Keys.Bytes);
+        uint head;
+        uint len;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+            len := and(shr(192, head), 0xffffffff)
+            value.offset := add(abs, 0x08)
+            value.length := len
+        }
+        if (uint32(head >> 224) != uint32(Keys.Bytes)) revert InvalidBlock();
+        end = abs + Sizes.Header + len;
     }
 
     /// @notice Decode one STRING payload and its absolute end position.
@@ -1623,20 +1774,15 @@ library Blocks {
     /// @return value Decoded string bytes.
     /// @return end Absolute position after the block.
     function unpackString(uint abs) internal pure returns (bytes calldata value, uint end) {
-        return unpackRaw(abs, Keys.String);
-    }
-
-    /// @dev Decode a dynamic leaf block after validating its key.
-    /// @param abs Absolute block position.
-    /// @param expected Expected block key.
-    /// @return value Decoded payload.
-    /// @return end Absolute position after the block.
-    function unpackRaw(uint abs, bytes4 expected) private pure returns (bytes calldata value, uint end) {
-        uint len = header(abs, expected);
+        uint head;
+        uint len;
         assembly ("memory-safe") {
+            head := calldataload(abs)
+            len := and(shr(192, head), 0xffffffff)
             value.offset := add(abs, 0x08)
             value.length := len
         }
+        if (uint32(head >> 224) != uint32(Keys.String)) revert InvalidBlock();
         end = abs + Sizes.Header + len;
     }
 
@@ -1653,7 +1799,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint entity, bytes calldata stream, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Annotation);
+        (abs, limit) = expectKey(abs, Keys.Annotation);
         assembly ("memory-safe") {
             entity := calldataload(abs)
         }
@@ -1671,7 +1817,7 @@ library Blocks {
         uint abs
     ) internal pure returns (bytes32 account, bytes calldata state, bytes calldata input, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Context);
+        (abs, limit) = expectKey(abs, Keys.Context);
         assembly ("memory-safe") {
             account := calldataload(abs)
         }
@@ -1685,19 +1831,19 @@ library Blocks {
     /// @notice Decode one STEP block and its nested input.
     /// @param abs Absolute block position.
     /// @return cmd Decoded command identifier.
-    /// @return resources Decoded packed resources.
+    /// @return value Decoded native value.
     /// @return input Decoded command input.
     /// @return end Absolute position after the block.
     function unpackStep(
         uint abs
-    ) internal pure returns (uint cmd, uint resources, bytes calldata input, uint end) {
+    ) internal pure returns (uint cmd, uint128 value, bytes calldata input, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Step);
+        (abs, limit) = expectKey(abs, Keys.Step);
         assembly ("memory-safe") {
             cmd := calldataload(abs)
-            resources := calldataload(add(abs, 0x20))
+            value := shr(128, calldataload(add(abs, 0x20)))
         }
-        (input, end) = unpackBytes(abs + 64);
+        (input, end) = unpackBytes(abs + 48);
         if (end != limit) revert InvalidBlock();
     }
 
@@ -1711,7 +1857,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint target, uint resources, bytes calldata payload, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Call);
+        (abs, limit) = expectKey(abs, Keys.Call);
         assembly ("memory-safe") {
             target := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1730,7 +1876,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint portal, uint resources, bytes calldata input, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Relay);
+        (abs, limit) = expectKey(abs, Keys.Relay);
         assembly ("memory-safe") {
             portal := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1749,7 +1895,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint portal, uint resources, bytes calldata payload, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Dispatch);
+        (abs, limit) = expectKey(abs, Keys.Dispatch);
         assembly ("memory-safe") {
             portal := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1765,7 +1911,7 @@ library Blocks {
     /// @return end Absolute position after the block.
     function unpackLabel(uint abs) internal pure returns (bytes32 namespace, string memory name, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Label);
+        (abs, limit) = expectKey(abs, Keys.Label);
         assembly ("memory-safe") {
             namespace := calldataload(abs)
         }
@@ -1783,7 +1929,7 @@ library Blocks {
     /// @return end Absolute position after the block.
     function unpackSchema(uint abs) internal pure returns (uint spec, string memory body, bytes32 name, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Schema);
+        (abs, limit) = expectKey(abs, Keys.Schema);
         assembly ("memory-safe") {
             spec := calldataload(abs)
         }
@@ -1810,7 +1956,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint handler, uint resources, bytes32 key, bytes calldata witness, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Recover);
+        (abs, limit) = expectKey(abs, Keys.Recover);
         assembly ("memory-safe") {
             handler := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1963,6 +2109,24 @@ library Blocks {
 
     // Fixed-width factories
 
+    /// @notice Encode a BOOTSTRAP block.
+    /// @param asset Asset identifier.
+    /// @param amount Balance amount to source.
+    /// @param budget Native-value budget to source.
+    /// @return value Encoded BOOTSTRAP block bytes.
+    function createBootstrap(bytes32 asset, uint amount, uint budget) internal pure returns (bytes memory value) {
+        value = allocate(Sizes.Bootstrap);
+        writeBootstrap(value, 0, asset, amount, budget);
+    }
+
+    /// @notice Encode a CASHOUT block.
+    /// @param amount Native-asset amount to withdraw.
+    /// @return value Encoded CASHOUT block bytes.
+    function createCashout(uint amount) internal pure returns (bytes memory value) {
+        value = allocate(Sizes.Cashout);
+        writeCashout(value, 0, amount);
+    }
+
     /// @notice Encode an AMOUNT block.
     /// @param asset Asset identifier.
     /// @param amount Token amount.
@@ -2036,20 +2200,20 @@ library Blocks {
 
     /// @notice Encode a STEP block.
     /// @param cmd Command identifier.
-    /// @param resources Packed resources assigned to the step.
+    /// @param value Native value assigned to the step.
     /// @param input Raw nested input payload.
-    /// @return value Encoded STEP block bytes.
-    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);
+    /// @return encoded Encoded STEP block bytes.
+    function createStep(uint cmd, uint128 value, bytes memory input) internal pure returns (bytes memory encoded) {
+        uint len = max32(Sizes.Step + input.length);
+        encoded = allocate(len);
+        writeStep(encoded, 0, cmd, value, input);
     }
 
     /// @notice Encode a STEP block by copying its nested input from calldata.
-    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);
+    function createStepCopy(uint cmd, uint128 value, bytes calldata input) internal pure returns (bytes memory encoded) {
+        uint len = max32(Sizes.Step + input.length);
+        encoded = allocate(len);
+        copyStep(encoded, 0, cmd, value, input);
     }
 
     /// @notice Encode a CALL block.
@@ -2158,3 +2322,85 @@ library Blocks {
         copyRecover(value, 0, handler, resources, recoverykey, witness);
     }
 }
+
+/// @title Memory
+/// @notice Fixed-stride decoding for homogeneous block streams held in memory.
+/// @dev The unpackers are intentionally unchecked beyond their exact header
+/// comparison. Callers must obtain bounds with `bounds`, advance by the matching
+/// complete encoded block size, and stop at the returned end position.
+library Memory {
+    uint64 private constant BalanceHeader = (uint64(uint32(Keys.Balance)) << 32) | 64;
+    uint64 private constant DebtHeader = (uint64(uint32(Keys.Debt)) << 32) | 64;
+    uint64 private constant PositionHeader = (uint64(uint32(Keys.Position)) << 32) | 128;
+    uint64 private constant TransactionHeader = (uint64(uint32(Keys.Transaction)) << 32) | 128;
+
+    /// @notice Return absolute bounds for a fixed-stride memory block stream.
+    /// @dev DANGER: Empty streams are valid and `size` must be nonzero. The size
+    /// must include the complete block header and payload.
+    /// @param source Memory block stream.
+    /// @param size Complete encoded size of each block.
+    /// @return abs Absolute memory position of the first block header.
+    /// @return end Absolute memory position immediately after the source.
+    function bounds(bytes memory source, uint size) internal pure returns (uint abs, uint end) {
+        uint len = source.length;
+        uint remainder;
+        assembly ("memory-safe") {
+            remainder := mod(len, size)
+            abs := add(source, 0x20)
+            end := add(abs, len)
+        }
+        if (remainder != 0) revert Blocks.InvalidBlock();
+    }
+
+    /// @notice Decode a BALANCE block at an in-bounds absolute memory position.
+    function unpackBalance(uint abs) internal pure returns (bytes32 asset, uint amount) {
+        uint64 actual;
+        assembly ("memory-safe") {
+            actual := shr(192, mload(abs))
+            asset := mload(add(abs, 0x08))
+            amount := mload(add(abs, 0x28))
+        }
+        if (actual != BalanceHeader) revert Blocks.InvalidBlock();
+    }
+
+    /// @notice Decode a DEBT block at an in-bounds absolute memory position.
+    function unpackDebt(uint abs) internal pure returns (bytes32 liability, uint debt) {
+        uint64 actual;
+        assembly ("memory-safe") {
+            actual := shr(192, mload(abs))
+            liability := mload(add(abs, 0x08))
+            debt := mload(add(abs, 0x28))
+        }
+        if (actual != DebtHeader) revert Blocks.InvalidBlock();
+    }
+
+    /// @notice Decode a POSITION block at an in-bounds absolute memory position.
+    function unpackPosition(
+        uint abs
+    ) internal pure returns (bytes32 asset, uint amount, bytes32 liability, uint debt) {
+        uint64 actual;
+        assembly ("memory-safe") {
+            actual := shr(192, mload(abs))
+            asset := mload(add(abs, 0x08))
+            amount := mload(add(abs, 0x28))
+            liability := mload(add(abs, 0x48))
+            debt := mload(add(abs, 0x68))
+        }
+        if (actual != PositionHeader) revert Blocks.InvalidBlock();
+    }
+
+    /// @notice Decode a TRANSACTION block at an in-bounds absolute memory position.
+    function unpackTransaction(
+        uint abs
+    ) internal pure returns (bytes32 from, bytes32 to, bytes32 asset, uint amount) {
+        uint64 actual;
+        assembly ("memory-safe") {
+            actual := shr(192, mload(abs))
+            from := mload(add(abs, 0x08))
+            to := mload(add(abs, 0x28))
+            asset := mload(add(abs, 0x48))
+            amount := mload(add(abs, 0x68))
+        }
+        if (actual != TransactionHeader) revert Blocks.InvalidBlock();
+    }
+}