@rootzero/contracts 0.2.0

package/contracts/blocks/Keys.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+library Keys {
+    bytes4 constant Amount = bytes4(keccak256("amount(bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Balance = bytes4(keccak256("balance(bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Custody = bytes4(keccak256("custody(uint host, bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Minimum = bytes4(keccak256("minimum(bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Maximum = bytes4(keccak256("maximum(bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Route = bytes4(keccak256("route(bytes data)"));
+    bytes4 constant Quantity = bytes4(keccak256("quantity(uint amount)"));
+    bytes4 constant Rate = bytes4(keccak256("rate(uint value)"));
+    bytes4 constant Party = bytes4(keccak256("party(bytes32 account)"));
+    bytes4 constant Recipient = bytes4(keccak256("recipient(bytes32 account)"));
+    bytes4 constant Transaction = bytes4(keccak256("tx(bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Step = bytes4(keccak256("step(uint target, uint value, bytes request)"));
+    bytes4 constant Auth = bytes4(keccak256("auth(uint cid, uint deadline, bytes proof)"));
+    bytes4 constant Asset = bytes4(keccak256("asset(bytes32 asset, bytes32 meta)"));
+    bytes4 constant Node = bytes4(keccak256("node(uint id)"));
+    bytes4 constant Listing = bytes4(keccak256("listing(uint host, bytes32 asset, bytes32 meta)"));
+    bytes4 constant Funding = bytes4(keccak256("funding(uint host, uint amount)"));
+    bytes4 constant Allocation = bytes4(keccak256("allocation(uint host, bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Bounty = bytes4(keccak256("bounty(uint amount, bytes32 relayer)"));
+}

package/contracts/blocks/Mem.sol

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { HostAmount, Tx, Keys } from "./Schema.sol";
+import { Blocks } from "./Blocks.sol";
+
+struct MemRef {
+    bytes4 key;
+    uint i;
+    uint bound;
+    uint end;
+}
+
+library Mem {
+    function from(bytes memory source, uint i) internal pure returns (MemRef memory ref) {
+        uint eod = source.length;
+        if (i == eod) return MemRef(bytes4(0), 0, 0, i);
+        if (i > eod) revert Blocks.MalformedBlocks();
+
+        unchecked {
+            ref.i = i + 12;
+        }
+        if (ref.i > eod) revert Blocks.MalformedBlocks();
+
+        bytes32 w;
+        assembly ("memory-safe") {
+            w := mload(add(add(source, 0x20), i))
+        }
+
+        ref.key = bytes4(w);
+        ref.bound = ref.i + uint32(bytes4(w << 32));
+        ref.end = ref.i + uint32(bytes4(w << 64));
+
+        if (ref.bound > ref.end || ref.end > eod) revert Blocks.MalformedBlocks();
+    }
+
+    function slice(bytes memory source, uint start, uint end) internal pure returns (bytes memory out) {
+        if (end < start || end > source.length) revert Blocks.MalformedBlocks();
+        uint len = end - start;
+        out = new bytes(len);
+        if (len == 0) return out;
+
+        assembly ("memory-safe") {
+            mcopy(add(out, 0x20), add(add(source, 0x20), start), len)
+        }
+    }
+
+    function count(bytes memory source, uint i, bytes4 key) internal pure returns (uint count_, uint next) {
+        next = i;
+        while (next < source.length) {
+            MemRef memory ref = from(source, next);
+            if (ref.key != key) break;
+            unchecked {
+                ++count_;
+            }
+            next = ref.end;
+        }
+    }
+
+    function find(bytes memory source, uint i, uint limit, bytes4 key) internal pure returns (MemRef memory ref) {
+        if (limit > source.length) revert Blocks.MalformedBlocks();
+        while (i < limit) {
+            ref = from(source, i);
+            if (ref.end > limit) revert Blocks.MalformedBlocks();
+            if (ref.key == key) return ref;
+            i = ref.end;
+        }
+
+        return MemRef(bytes4(0), limit, limit, limit);
+    }
+
+    function ensure(MemRef memory ref, bytes4 key) internal pure {
+        if (key == 0 || key != ref.key) revert Blocks.InvalidBlock();
+    }
+
+    function ensure(MemRef memory ref, bytes4 key, uint len) internal pure {
+        if (key == 0 || key != ref.key || len != (ref.bound - ref.i)) revert Blocks.InvalidBlock();
+    }
+
+    function ensure(MemRef memory ref, bytes4 key, uint min, uint max) internal pure {
+        uint len = ref.bound - ref.i;
+        if (key == 0 || key != ref.key || len < min || (max != 0 && len > max)) revert Blocks.InvalidBlock();
+    }
+
+    function unpackBalance(
+        MemRef memory ref,
+        bytes memory source
+    ) internal pure returns (bytes32 asset, bytes32 meta, uint amount) {
+        ensure(ref, Keys.Balance, 96);
+        uint i = ref.i;
+
+        assembly ("memory-safe") {
+            let p := add(add(source, 0x20), i)
+            asset := mload(p)
+            meta := mload(add(p, 0x20))
+            amount := mload(add(p, 0x40))
+        }
+    }
+
+    function toCustodyValue(
+        MemRef memory ref,
+        bytes memory source
+    ) internal pure returns (HostAmount memory value) {
+        ensure(ref, Keys.Custody, 128);
+        uint i = ref.i;
+
+        assembly ("memory-safe") {
+            let p := add(add(source, 0x20), i)
+            mstore(value, mload(p))
+            mstore(add(value, 0x20), mload(add(p, 0x20)))
+            mstore(add(value, 0x40), mload(add(p, 0x40)))
+            mstore(add(value, 0x60), mload(add(p, 0x60)))
+        }
+    }
+
+    function toTxValue(MemRef memory ref, bytes memory source) internal pure returns (Tx memory value) {
+        ensure(ref, Keys.Transaction, 160);
+        uint i = ref.i;
+
+        assembly ("memory-safe") {
+            let p := add(add(source, 0x20), i)
+            mstore(value, mload(p))
+            mstore(add(value, 0x20), mload(add(p, 0x20)))
+            mstore(add(value, 0x40), mload(add(p, 0x40)))
+            mstore(add(value, 0x60), mload(add(p, 0x60)))
+            mstore(add(value, 0x80), mload(add(p, 0x80)))
+        }
+    }
+}

package/contracts/blocks/Schema.sol

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { Keys } from "./Keys.sol";
+
+library Schemas {
+    string constant Amount = "amount(bytes32 asset, bytes32 meta, uint amount)";
+    string constant Balance = "balance(bytes32 asset, bytes32 meta, uint amount)";
+    string constant Custody = "custody(uint host, bytes32 asset, bytes32 meta, uint amount)";
+    string constant Minimum = "minimum(bytes32 asset, bytes32 meta, uint amount)";
+    string constant Maximum = "maximum(bytes32 asset, bytes32 meta, uint amount)";
+    string constant Route = "route(bytes data)";
+    string constant RouteEmpty = "route()";
+    string constant Quantity = "quantity(uint amount)";
+    string constant Rate = "rate(uint value)";
+    string constant Party = "party(bytes32 account)";
+    string constant Recipient = "recipient(bytes32 account)";
+    string constant Transaction = "tx(bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)";
+    string constant Step = "step(uint target, uint value, bytes request)";
+    string constant Auth = "auth(uint cid, uint deadline, bytes proof)";
+    string constant Asset = "asset(bytes32 asset, bytes32 meta)";
+    string constant Node = "node(uint id)";
+    string constant Listing = "listing(uint host, bytes32 asset, bytes32 meta)";
+    string constant Funding = "funding(uint host, uint amount)";
+    string constant Allocation = "allocation(uint host, bytes32 asset, bytes32 meta, uint amount)";
+    string constant Bounty = "bounty(uint amount, bytes32 relayer)";
+
+    function route1(string memory maybeRoute, string memory a) internal pure returns (string memory) {
+        return string.concat(bytes(maybeRoute).length == 0 ? RouteEmpty : maybeRoute, ">", a);
+    }
+
+    function route2(string memory maybeRoute, string memory a, string memory b) internal pure returns (string memory) {
+        return string.concat(bytes(maybeRoute).length == 0 ? RouteEmpty : maybeRoute, ">", a, ">", b);
+    }
+}
+
+// Block stream:
+// - encoding is [bytes4 key][bytes4 selfLen][bytes4 totalLen][self payload][child blocks...]
+// - `selfLen` covers only the block payload
+// - `totalLen` covers payload plus child blocks
+// - payload layout is block-specific
+//
+// Extensible payloads:
+// - self payload may be [head][dynamic tail]
+// - head layout is implied by the block key
+// - one dynamic field may consume the rest of self payload without its own length prefix
+// - child blocks, if any, are encoded as a normal nested block stream
+//
+// Schema DSL:
+// - `;` separates top-level sibling blocks
+// - `>` attaches child blocks to the preceding parent
+// - repeated `>` adds more children to the same parent, not to the previous child
+// - `->` separates request and response shapes, appears at most once, and is omitted when no output is modeled
+// - top-level blocks of the same type should be grouped together
+// - primary / driving blocks should appear before auxiliary blocks
+// - `route(<fields...>)` is a reserved extensible schema form whose key is always `Keys.Route`
+// - canonical blocks are `amount(...)` for request amounts, `balance(...)` for state balances,
+//   `minimum(...)` for result floors, `maximum(...)` for spend ceilings, and `quantity(...)`
+//   for plain scalar amounts
+// - `auth(uint cid, uint deadline, bytes proof)` is a proof-separator child and must be emitted last
+//
+// Signed blocks:
+// - a signed top-level block ends with one trailing AUTH child
+// - only the final AUTH is treated specially; earlier AUTH blocks remain ordinary signed child bytes
+// - the signed slice runs from the parent block start through the AUTH head, excluding only AUTH proof bytes
+// - `cid` binds the signature to one command; `deadline` acts as expiry and nonce
+// - current helpers assume proof layout `[bytes20 signer][bytes65 sig]`
+
+uint constant AUTH_PROOF_LEN = 85;
+uint constant AUTH_TOTAL_LEN = 161;
+
+struct AssetAmount {
+    bytes32 asset;
+    bytes32 meta;
+    uint amount;
+}
+
+struct HostAmount {
+    uint host;
+    bytes32 asset;
+    bytes32 meta;
+    uint amount;
+}
+
+struct UserAmount {
+    bytes32 account;
+    bytes32 asset;
+    bytes32 meta;
+    uint amount;
+}
+
+struct HostAsset {
+    uint host;
+    bytes32 asset;
+    bytes32 meta;
+}
+
+struct Tx {
+    bytes32 from;
+    bytes32 to;
+    bytes32 asset;
+    bytes32 meta;
+    uint amount;
+}
+

package/contracts/blocks/Writers.sol

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { Blocks } from "./Blocks.sol";
+import { AssetAmount, HostAmount, Tx, Keys } from "./Schema.sol";
+
+struct Writer {
+    uint i;
+    uint end;
+    bytes dst;
+}
+
+uint constant ALLOC_SCALE = 10_000;
+uint constant BALANCE_BLOCK_LEN = 108;
+uint constant BOUNTY_BLOCK_LEN = 76;
+uint constant CUSTODY_BLOCK_LEN = 140;
+uint constant TX_BLOCK_LEN = 172;
+
+library Writers {
+    error WriterOverflow();
+    error IncompleteWriter();
+    error EmptyRequest();
+
+    // Encodes a 12-byte block header (4-byte key + 4-byte selfLen + 4-byte totalLen) into a uint so assembly can
+    // write the full header in one mstore while the payload starts at offset + 12.
+    function toBlockHeader(bytes4 key, uint selfLen, uint totalLen) internal pure returns (uint) {
+        if (selfLen > type(uint32).max || totalLen > type(uint32).max || selfLen > totalLen) revert Blocks.MalformedBlocks();
+        return (uint(uint32(key)) << 224) | (uint(uint32(selfLen)) << 192) | (uint(uint32(totalLen)) << 160);
+    }
+
+    function alloc(uint len) internal pure returns (Writer memory writer) {
+        writer = Writer({i: 0, end: len, dst: new bytes(len)});
+    }
+
+    function append(Writer memory writer, bytes memory data) internal pure {
+        uint next = writer.i + data.length;
+        if (next > writer.dst.length) revert WriterOverflow();
+        assembly ("memory-safe") {
+            mcopy(add(add(mload(add(writer, 0x40)), 0x20), mload(writer)), add(data, 0x20), mload(data))
+        }
+        writer.i = next;
+    }
+
+    function allocBalancesFrom(
+        bytes calldata blocks,
+        uint i,
+        bytes4 source
+    ) internal pure returns (Writer memory writer, uint next) {
+        return allocFromScaledCount(blocks, i, source, ALLOC_SCALE, BALANCE_BLOCK_LEN);
+    }
+
+    function allocPairedBalancesFrom(
+        bytes calldata blocks,
+        uint i,
+        bytes4 source
+    ) internal pure returns (Writer memory writer, uint next) {
+        return allocFromScaledCount(blocks, i, source, ALLOC_SCALE * 2, BALANCE_BLOCK_LEN);
+    }
+
+    function allocScaledBalancesFrom(
+        bytes calldata blocks,
+        uint i,
+        bytes4 source,
+        uint scaledRatio
+    ) internal pure returns (Writer memory writer, uint next) {
+        return allocFromScaledCount(blocks, i, source, scaledRatio, BALANCE_BLOCK_LEN);
+    }
+
+    function allocTxsFrom(
+        bytes calldata blocks,
+        uint i,
+        bytes4 source
+    ) internal pure returns (Writer memory writer, uint next) {
+        return allocFromScaledCount(blocks, i, source, ALLOC_SCALE, TX_BLOCK_LEN);
+    }
+
+    function allocCustodiesFrom(
+        bytes calldata blocks,
+        uint i,
+        bytes4 source
+    ) internal pure returns (Writer memory writer, uint next) {
+        return allocFromScaledCount(blocks, i, source, ALLOC_SCALE, CUSTODY_BLOCK_LEN);
+    }
+
+    function allocScaledCustodiesFrom(
+        bytes calldata blocks,
+        uint i,
+        bytes4 source,
+        uint scaledRatio
+    ) internal pure returns (Writer memory writer, uint next) {
+        return allocFromScaledCount(blocks, i, source, scaledRatio, CUSTODY_BLOCK_LEN);
+    }
+
+    function allocFromScaledCount(
+        bytes calldata blocks,
+        uint i,
+        bytes4 source,
+        uint scaledRatio,
+        uint blockLen
+    ) internal pure returns (Writer memory writer, uint next) {
+        uint count;
+        (count, next) = Blocks.count(blocks, i, source);
+        if (count == 0) revert EmptyRequest();
+        uint scaledCount = count * scaledRatio;
+        if (scaledCount % ALLOC_SCALE != 0) revert Blocks.MalformedBlocks();
+        uint len = (scaledCount / ALLOC_SCALE) * blockLen;
+        writer = Writer({i: 0, end: len, dst: new bytes(len)});
+    }
+
+    function writeBalanceBlock(bytes memory dst, uint i, AssetAmount memory value) internal pure returns (uint next) {
+        next = i + BALANCE_BLOCK_LEN;
+        if (next > dst.length) revert WriterOverflow();
+        uint header = toBlockHeader(Keys.Balance, 96, 96);
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, header)
+            mstore(add(p, 0x0c), mload(value))
+            mstore(add(p, 0x2c), mload(add(value, 0x20)))
+            mstore(add(p, 0x4c), mload(add(value, 0x40)))
+        }
+    }
+
+    function appendBalance(Writer memory writer, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        appendBalance(writer, AssetAmount(asset, meta, amount));
+    }
+
+    function appendBalance(Writer memory writer, AssetAmount memory value) internal pure {
+        writer.i = writeBalanceBlock(writer.dst, writer.i, value);
+    }
+
+    function appendNonZeroBalance(Writer memory writer, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        if (amount > 0) appendBalance(writer, asset, meta, amount);
+    }
+
+    function appendNonZeroBalance(Writer memory writer, AssetAmount memory value) internal pure {
+        if (value.amount > 0) appendBalance(writer, value);
+    }
+
+    function writeBountyBlock(bytes memory dst, uint i, uint amount, bytes32 relayer) internal pure returns (uint next) {
+        next = i + BOUNTY_BLOCK_LEN;
+        if (next > dst.length) revert WriterOverflow();
+        uint header = toBlockHeader(Keys.Bounty, 64, 64);
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, header)
+            mstore(add(p, 0x0c), amount)
+            mstore(add(p, 0x2c), relayer)
+        }
+    }
+
+    function appendBounty(Writer memory writer, uint amount, bytes32 relayer) internal pure {
+        writer.i = writeBountyBlock(writer.dst, writer.i, amount, relayer);
+    }
+
+    function writeCustodyBlock(bytes memory dst, uint i, HostAmount memory value) internal pure returns (uint next) {
+        next = i + CUSTODY_BLOCK_LEN;
+        if (next > dst.length) revert WriterOverflow();
+        uint header = toBlockHeader(Keys.Custody, 128, 128);
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, header)
+            mstore(add(p, 0x0c), mload(value))
+            mstore(add(p, 0x2c), mload(add(value, 0x20)))
+            mstore(add(p, 0x4c), mload(add(value, 0x40)))
+            mstore(add(p, 0x6c), mload(add(value, 0x60)))
+        }
+    }
+
+    function appendCustody(Writer memory writer, uint host, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        appendCustody(writer, HostAmount(host, asset, meta, amount));
+    }
+
+    function appendCustody(Writer memory writer, HostAmount memory value) internal pure {
+        writer.i = writeCustodyBlock(writer.dst, writer.i, value);
+    }
+
+    function writeTxBlock(bytes memory dst, uint i, Tx memory value) internal pure returns (uint next) {
+        next = i + TX_BLOCK_LEN;
+        if (next > dst.length) revert WriterOverflow();
+        uint header = toBlockHeader(Keys.Transaction, 160, 160);
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, header)
+            mstore(add(p, 0x0c), mload(value))
+            mstore(add(p, 0x2c), mload(add(value, 0x20)))
+            mstore(add(p, 0x4c), mload(add(value, 0x40)))
+            mstore(add(p, 0x6c), mload(add(value, 0x60)))
+            mstore(add(p, 0x8c), mload(add(value, 0x80)))
+        }
+    }
+
+    function appendTx(Writer memory writer, Tx memory value) internal pure {
+        writer.i = writeTxBlock(writer.dst, writer.i, value);
+    }
+
+    function done(Writer memory writer) internal pure returns (bytes memory) {
+        if (writer.i != writer.dst.length) revert IncompleteWriter();
+        return writer.dst;
+    }
+
+    function finish(Writer memory writer) internal pure returns (bytes memory out) {
+        if (writer.i == 0) revert EmptyRequest();
+        if (writer.i > writer.dst.length) revert IncompleteWriter();
+        out = writer.dst;
+        assembly ("memory-safe") {
+            mstore(out, mload(writer))
+        }
+    }
+}

package/contracts/combinators/AmountToBalance.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { AssetAmount, Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+using Blocks for Block;
+using Writers for Writer;
+
+abstract contract AmountToBalance {
+    function amountToBalance(bytes32 account, AssetAmount memory amount) internal virtual returns (AssetAmount memory);
+
+    function amountsToBalances(bytes calldata blocks, uint i, bytes32 account) internal returns (bytes memory) {
+        (Writer memory writer, uint end) = Writers.allocBalancesFrom(blocks, i, Keys.Amount);
+
+        while (i < end) {
+            Block memory ref = Blocks.from(blocks, i);
+            AssetAmount memory amount = ref.toAmountValue();
+            AssetAmount memory out = amountToBalance(account, amount);
+            writer.appendNonZeroBalance(out);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}

package/contracts/combinators/AmountToCustody.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { HostAmount, Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+using Blocks for Block;
+using Writers for Writer;
+
+abstract contract AmountToCustody {
+    function amountToCustody(
+        uint host,
+        bytes32 account,
+        bytes32 asset,
+        bytes32 meta,
+        uint amount
+    ) internal virtual returns (HostAmount memory);
+
+    function amountsToCustodies(
+        bytes calldata blocks,
+        uint i,
+        uint host,
+        bytes32 account
+    ) internal returns (bytes memory) {
+        (Writer memory writer, uint end) = Writers.allocCustodiesFrom(blocks, i, Keys.Amount);
+
+        while (i < end) {
+            Block memory ref = Blocks.from(blocks, i);
+            (bytes32 asset, bytes32 meta, uint amount) = ref.unpackAmount();
+            HostAmount memory out = amountToCustody(host, account, asset, meta, amount);
+            if (out.amount > 0) writer.appendCustody(out);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}

package/contracts/combinators/CustodyToBalance.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { AssetAmount, HostAmount, Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+using Blocks for Block;
+using Writers for Writer;
+
+abstract contract CustodyToBalance {
+    function custodyToBalance(bytes32 account, HostAmount memory custody) internal virtual returns (AssetAmount memory);
+
+    function custodiesToBalances(bytes calldata blocks, uint i, bytes32 account) internal returns (bytes memory) {
+        (Writer memory writer, uint end) = Writers.allocBalancesFrom(blocks, i, Keys.Custody);
+
+        while (i < end) {
+            Block memory ref = Blocks.from(blocks, i);
+            HostAmount memory custody = ref.toCustodyValue();
+            AssetAmount memory out = custodyToBalance(account, custody);
+            writer.appendNonZeroBalance(out);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}

package/contracts/combinators/EachRoute.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { Blocks, Block, Keys } from "../Blocks.sol";
+
+abstract contract EachRoute {
+    function eachRoute(Block memory rawRoute) internal virtual;
+
+    function forEachRoute(bytes calldata blocks, uint i) internal returns (uint) {
+        while (i < blocks.length) {
+            Block memory ref = Blocks.from(blocks, i);
+            if (ref.key != Keys.Route) return i;
+            eachRoute(ref);
+            i = ref.cursor;
+        }
+        return i;
+    }
+}

package/contracts/combinators/MapBalance.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { AssetAmount, Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+using Blocks for Block;
+using Writers for Writer;
+
+abstract contract MapBalance {
+    function mapBalance(bytes32 account, AssetAmount memory balance) internal virtual returns (AssetAmount memory out);
+
+    function mapBalances(bytes calldata state, uint i, bytes32 account) internal returns (bytes memory) {
+        (Writer memory writer, uint end) = Writers.allocBalancesFrom(state, i, Keys.Balance);
+
+        while (i < end) {
+            Block memory ref = Blocks.from(state, i);
+            AssetAmount memory balance = ref.toBalanceValue();
+            AssetAmount memory out = mapBalance(account, balance);
+            writer.appendNonZeroBalance(out);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}

package/contracts/combinators/MapCustody.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { HostAmount, Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+using Blocks for Block;
+using Writers for Writer;
+
+abstract contract MapCustody {
+    function mapCustody(bytes32 account, HostAmount memory custody) internal virtual returns (HostAmount memory out);
+
+    function mapCustodies(bytes calldata state, uint i, bytes32 account) internal returns (bytes memory) {
+        (Writer memory writer, uint end) = Writers.allocCustodiesFrom(state, i, Keys.Custody);
+
+        while (i < end) {
+            Block memory ref = Blocks.from(state, i);
+            HostAmount memory custody = ref.toCustodyValue();
+            HostAmount memory out = mapCustody(account, custody);
+            if (out.amount > 0) writer.appendCustody(out);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}

package/contracts/combinators/RouteToBalance.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+using Writers for Writer;
+
+abstract contract RouteToBalance {
+    function routeToBalance(
+        bytes32 account,
+        Block memory rawRoute
+    ) internal virtual returns (bytes32 asset, bytes32 meta, uint amount);
+
+    function routesToBalances(bytes calldata blocks, uint i, bytes32 account) internal returns (bytes memory) {
+        (Writer memory writer, uint end) = Writers.allocBalancesFrom(blocks, i, Keys.Route);
+
+        while (i < end) {
+            Block memory route;
+            route = Blocks.routeFrom(blocks, i);
+            i = route.cursor;
+            (bytes32 asset, bytes32 meta, uint amount) = routeToBalance(account, route);
+            if (amount > 0) writer.appendBalance(asset, meta, amount);
+        }
+
+        return writer.finish();
+    }
+}