@rootzero/contracts 0.2.0

package/contracts/commands/Pipe.sol

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandBase, CommandContext } from "./Base.sol";
+import { Keys, Schemas, Blocks, Block } from "../Blocks.sol";
+import { Accounts } from "../utils/Accounts.sol";
+import { Values } from "../utils/Value.sol";
+
+using Blocks for Block;
+
+string constant NAME = "pipe";
+
+abstract contract Pipe is CommandBase {
+    uint internal immutable pipeId = commandId(NAME);
+
+    constructor() {
+        emit Command(host, NAME, Schemas.Step, pipeId, 0, 0);
+    }
+
+    /// @dev Override to execute a single STEP target and return the next
+    /// threaded state for the pipe.
+    function dispatchStep(
+        uint target,
+        bytes32 account,
+        bytes memory state,
+        bytes calldata request,
+        uint value
+    ) internal virtual returns (bytes memory);
+
+    function pipe(
+        bytes32 account,
+        bytes memory state,
+        bytes calldata steps,
+        Values.Budget memory budget
+    ) internal returns (bytes memory) {
+        uint i = 0;
+        while (i < steps.length) {
+            Block memory ref = Blocks.from(steps, i);
+            if (ref.key != Keys.Step) break;
+            (uint target, uint value, bytes calldata request) = ref.unpackStep();
+            uint spend = Values.use(budget, value);
+            state = dispatchStep(target, account, state, request, spend);
+            i = ref.cursor;
+        }
+
+        return done(state, 0, i);
+    }
+
+    // Any unused value will not be credited back to the account using this path.
+    function pipe(CommandContext calldata c) external payable onlyCommand(pipeId, c.target) returns (bytes memory) {
+        if (Accounts.isAdmin(c.account)) revert Accounts.InvalidAccount();
+        Values.Budget memory budget = Values.fromMsg();
+        return pipe(c.account, c.state, c.request, budget);
+    }
+}

package/contracts/commands/Provision.sol

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, Channels } from "./Base.sol";
+import { Keys, Schemas, Blocks, Block, Writers, Writer } from "../Blocks.sol";
+using Blocks for Block;
+using Writers for Writer;
+
+string constant PROVISION = "provision";
+string constant PFB = "provisionFromBalance";
+
+string constant REQUEST = string.concat(Schemas.Amount, ">", Schemas.Node);
+
+abstract contract ProvisionHook {
+    /// @dev Override this hook to send or provision funds to `host`.
+    /// Called by both `Provision` and `ProvisionFromBalance`.
+    /// Implementations should only perform the side effect and must not
+    /// encode or append output blocks.
+    function provision(bytes32 account, uint host, bytes32 asset, bytes32 meta, uint amount) internal virtual;
+}
+
+abstract contract Provision is CommandBase, ProvisionHook {
+    uint internal immutable provisionId = commandId(PROVISION);
+
+    constructor() {
+        emit Command(host, PROVISION, REQUEST, provisionId, Channels.Setup, Channels.Custodies);
+    }
+
+    function provision(
+        CommandContext calldata c
+    ) external payable onlyCommand(provisionId, c.target) returns (bytes memory) {
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocCustodiesFrom(c.request, q, Keys.Amount);
+
+        while (q < end) {
+            Block memory ref = Blocks.from(c.request, q);
+            (bytes32 asset, bytes32 meta, uint amount) = ref.unpackAmount();
+            uint toHost = ref.innerNode();
+            provision(c.account, toHost, asset, meta, amount);
+            writer.appendCustody(toHost, asset, meta, amount);
+            q = ref.cursor;
+        }
+
+        return writer.done();
+    }
+}
+
+// @dev Converts BALANCE state into CUSTODY state for a destination host.
+abstract contract ProvisionFromBalance is CommandBase, ProvisionHook {
+    uint internal immutable provisionFromBalanceId = commandId(PFB);
+
+    constructor() {
+        emit Command(host, PFB, Schemas.Node, provisionFromBalanceId, Channels.Balances, Channels.Custodies);
+    }
+
+    function provisionFromBalance(
+        CommandContext calldata c
+    ) external payable onlyCommand(provisionFromBalanceId, c.target) returns (bytes memory) {
+        uint toHost = Blocks.resolveNode(c.request, 0, c.request.length, 0);
+        uint i = 0;
+        (Writer memory writer, uint end) = Writers.allocCustodiesFrom(c.state, i, Keys.Balance);
+
+        while (i < end) {
+            Block memory ref = Blocks.from(c.state, i);
+            (bytes32 asset, bytes32 meta, uint amount) = ref.unpackBalance();
+            provision(c.account, toHost, asset, meta, amount);
+            writer.appendCustody(toHost, asset, meta, amount);
+            i = ref.cursor;
+        }
+
+        return writer.done();
+    }
+}

package/contracts/commands/Reclaim.sol

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, Channels } from "./Base.sol";
+import { AssetAmount, Schemas, Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+string constant NAME = "reclaimToBalances";
+
+using Blocks for Block;
+using Writers for Writer;
+
+abstract contract ReclaimToBalances is CommandBase {
+    uint internal immutable reclaimToBalancesId = commandId(NAME);
+    uint private immutable outScale;
+
+    constructor(string memory maybeRoute, uint scaledRatio) {
+        outScale = scaledRatio;
+        string memory schema = Schemas.route1(maybeRoute, Schemas.Amount);
+        emit Command(host, NAME, schema, reclaimToBalancesId, Channels.Setup, Channels.Balances);
+    }
+
+    /// @dev Override to reclaim balances described by `rawRoute`.
+    /// `amount` is extracted from the route and implementations may append one
+    /// or more BALANCE blocks to `out`.
+    function reclaimToBalances(
+        bytes32 account,
+        AssetAmount memory amount,
+        Block memory rawRoute,
+        Writer memory out
+    ) internal virtual;
+
+    function reclaimToBalances(
+        CommandContext calldata c
+    ) external payable onlyCommand(reclaimToBalancesId, c.target) returns (bytes memory) {
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocScaledBalancesFrom(c.request, q, Keys.Route, outScale);
+
+        while (q < end) {
+            Block memory route;
+            route = Blocks.routeFrom(c.request, q);
+            q = route.cursor;
+            AssetAmount memory value = route.innerAmountValue();
+            reclaimToBalances(c.account, value, route, writer);
+        }
+
+        return writer.finish();
+    }
+}

package/contracts/commands/Redeem.sol

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, Channels } from "./Base.sol";
+import { AssetAmount, HostAmount, Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+string constant RDBTB = "redeemFromBalanceToBalances";
+string constant RDCTB = "redeemFromCustodyToBalances";
+
+using Blocks for Block;
+using Writers for Writer;
+
+abstract contract RedeemFromBalanceToBalances is CommandBase {
+    uint internal immutable redeemFromBalanceToBalancesId = commandId(RDBTB);
+    uint private immutable outScale;
+    bool private immutable useRoute;
+
+    constructor(string memory maybeRoute, uint scaledRatio) {
+        outScale = scaledRatio;
+        useRoute = bytes(maybeRoute).length > 0;
+        emit Command(host, RDBTB, maybeRoute, redeemFromBalanceToBalancesId, Channels.Balances, Channels.Balances);
+    }
+
+    /// @dev Override to redeem a balance position into balances.
+    /// `rawRoute` is zero-initialized and should be ignored when
+    /// `maybeRoute` is empty. Implementations may append one or more BALANCE
+    /// blocks to `out`.
+    function redeemFromBalanceToBalances(
+        bytes32 account,
+        AssetAmount memory balance,
+        Block memory rawRoute,
+        Writer memory out
+    ) internal virtual;
+
+    function redeemFromBalanceToBalances(
+        CommandContext calldata c
+    ) external payable onlyCommand(redeemFromBalanceToBalancesId, c.target) returns (bytes memory) {
+        uint i = 0;
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocScaledBalancesFrom(c.state, i, Keys.Balance, outScale);
+
+        while (i < end) {
+            Block memory route;
+            if (useRoute) {
+                route = Blocks.routeFrom(c.request, q);
+                q = route.cursor;
+            }
+            Block memory ref = Blocks.from(c.state, i);
+            AssetAmount memory balance = ref.toBalanceValue();
+            redeemFromBalanceToBalances(c.account, balance, route, writer);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}
+
+abstract contract RedeemFromCustodyToBalances is CommandBase {
+    uint internal immutable redeemFromCustodyToBalancesId = commandId(RDCTB);
+    uint private immutable outScale;
+    bool private immutable useRoute;
+
+    constructor(string memory maybeRoute, uint scaledRatio) {
+        outScale = scaledRatio;
+        useRoute = bytes(maybeRoute).length > 0;
+        emit Command(host, RDCTB, maybeRoute, redeemFromCustodyToBalancesId, Channels.Custodies, Channels.Balances);
+    }
+
+    /// @dev Override to redeem a custody position into balances.
+    /// `rawRoute` is zero-initialized and should be ignored when
+    /// `maybeRoute` is empty. Implementations may append one or more BALANCE
+    /// blocks to `out`.
+    function redeemFromCustodyToBalances(
+        bytes32 account,
+        HostAmount memory custody,
+        Block memory rawRoute,
+        Writer memory out
+    ) internal virtual;
+
+    function redeemFromCustodyToBalances(
+        CommandContext calldata c
+    ) external payable onlyCommand(redeemFromCustodyToBalancesId, c.target) returns (bytes memory) {
+        uint i = 0;
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocScaledBalancesFrom(c.state, i, Keys.Custody, outScale);
+
+        while (i < end) {
+            Block memory route;
+            if (useRoute) {
+                route = Blocks.routeFrom(c.request, q);
+                q = route.cursor;
+            }
+            Block memory ref = Blocks.from(c.state, i);
+            HostAmount memory custody = ref.toCustodyValue();
+            redeemFromCustodyToBalances(c.account, custody, route, writer);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}

package/contracts/commands/Remove.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandBase, CommandContext, Channels } from "./Base.sol";
+import { Blocks, Block, Keys } from "../Blocks.sol";
+using Blocks for Block;
+
+string constant NAME = "remove";
+
+abstract contract Remove is CommandBase {
+    uint internal immutable removeId = commandId(NAME);
+
+    constructor(string memory route) {
+        emit Command(host, NAME, route, removeId, Channels.Setup, Channels.Setup);
+    }
+
+    /// @dev Override to remove or dismantle an object described by `rawRoute`.
+    /// Called once per ROUTE block in the request.
+    function remove(bytes32 account, Block memory rawRoute) internal virtual;
+
+    function remove(CommandContext calldata c) external payable onlyCommand(removeId, c.target) returns (bytes memory) {
+        uint q = 0;
+        while (q < c.request.length) {
+            Block memory ref = Blocks.from(c.request, q);
+            if (ref.key != Keys.Route) break;
+            remove(c.account, ref);
+            q = ref.cursor;
+        }
+
+        return done(0, q);
+    }
+}

package/contracts/commands/Repay.sol

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, Channels } from "./Base.sol";
+import { AssetAmount, HostAmount, Schemas, Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+string constant RFBTB = "repayFromBalanceToBalances";
+string constant RFCTB = "repayFromCustodyToBalances";
+
+using Blocks for Block;
+using Writers for Writer;
+
+abstract contract RepayFromBalanceToBalances is CommandBase {
+    uint internal immutable repayFromBalanceToBalancesId = commandId(RFBTB);
+    uint private immutable outScale;
+    bool private immutable useRoute;
+
+    constructor(string memory maybeRoute, uint scaledRatio) {
+        outScale = scaledRatio;
+        useRoute = bytes(maybeRoute).length > 0;
+        emit Command(host, RFBTB, maybeRoute, repayFromBalanceToBalancesId, Channels.Balances, Channels.Balances);
+    }
+
+    /// @dev Override to repay debt using a balance amount.
+    /// `rawRoute` is zero-initialized and should be ignored when
+    /// `maybeRoute` is empty. Implementations may append returned balances to
+    /// `out`.
+    function repayFromBalanceToBalances(
+        bytes32 account,
+        AssetAmount memory balance,
+        Block memory rawRoute,
+        Writer memory out
+    ) internal virtual;
+
+    function repayFromBalanceToBalances(
+        CommandContext calldata c
+    ) external payable onlyCommand(repayFromBalanceToBalancesId, c.target) returns (bytes memory) {
+        uint i = 0;
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocScaledBalancesFrom(c.state, i, Keys.Balance, outScale);
+
+        while (i < end) {
+            Block memory route;
+            if (useRoute) {
+                route = Blocks.routeFrom(c.request, q);
+                q = route.cursor;
+            }
+            Block memory ref = Blocks.from(c.state, i);
+            AssetAmount memory balance = ref.toBalanceValue();
+            repayFromBalanceToBalances(c.account, balance, route, writer);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}
+
+abstract contract RepayFromCustodyToBalances is CommandBase {
+    uint internal immutable repayFromCustodyToBalancesId = commandId(RFCTB);
+    uint private immutable outScale;
+    bool private immutable useRoute;
+
+    constructor(string memory maybeRoute, uint scaledRatio) {
+        outScale = scaledRatio;
+        useRoute = bytes(maybeRoute).length > 0;
+        emit Command(host, RFCTB, maybeRoute, repayFromCustodyToBalancesId, Channels.Custodies, Channels.Balances);
+    }
+
+    /// @dev Override to repay debt using a custody amount.
+    /// `rawRoute` is zero-initialized and should be ignored when
+    /// `maybeRoute` is empty. Implementations may append returned balances to
+    /// `out`.
+    function repayFromCustodyToBalances(
+        bytes32 account,
+        HostAmount memory custody,
+        Block memory rawRoute,
+        Writer memory out
+    ) internal virtual;
+
+    function repayFromCustodyToBalances(
+        CommandContext calldata c
+    ) external payable onlyCommand(repayFromCustodyToBalancesId, c.target) returns (bytes memory) {
+        uint i = 0;
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocScaledBalancesFrom(c.state, i, Keys.Custody, outScale);
+
+        while (i < end) {
+            Block memory route;
+            if (useRoute) {
+                route = Blocks.routeFrom(c.request, q);
+                q = route.cursor;
+            }
+            Block memory ref = Blocks.from(c.state, i);
+            HostAmount memory custody = ref.toCustodyValue();
+            repayFromCustodyToBalances(c.account, custody, route, writer);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}

package/contracts/commands/Settle.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, Channels } from "./Base.sol";
+import { Tx, Keys, Blocks, Block } from "../Blocks.sol";
+using Blocks for Block;
+
+string constant NAME = "settle";
+
+abstract contract Settle is CommandBase {
+    uint internal immutable settleId = commandId(NAME);
+
+    constructor() {
+        emit Command(host, NAME, "", settleId, Channels.Transactions, Channels.Setup);
+    }
+
+    /// @dev Override to settle a single transaction block.
+    /// Called once per TX block in state.
+    function settle(Tx memory value) internal virtual;
+
+    function settle(CommandContext calldata c) external payable onlyCommand(settleId, c.target) returns (bytes memory) {
+        uint i = 0;
+        while (i < c.state.length) {
+            Block memory ref = Blocks.from(c.state, i);
+            if (ref.key != Keys.Transaction) break;
+            Tx memory value = ref.toTxValue();
+            settle(value);
+            i = ref.cursor;
+        }
+        return done(0, i);
+    }
+}

package/contracts/commands/Stake.sol

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, Channels } from "./Base.sol";
+import { AssetAmount, HostAmount, Blocks, Block, Writers, Writer, Keys } from "../Blocks.sol";
+
+string constant SBTB = "stakeBalanceToBalances";
+string constant SCTB = "stakeCustodyToBalances";
+string constant SCTP = "stakeCustodyToPosition";
+
+using Blocks for Block;
+using Writers for Writer;
+
+abstract contract StakeBalanceToBalances is CommandBase {
+    uint internal immutable stakeBalanceToBalancesId = commandId(SBTB);
+    uint private immutable outScale;
+
+    constructor(string memory route, uint scaledRatio) {
+        outScale = scaledRatio;
+        emit Command(host, SBTB, route, stakeBalanceToBalancesId, Channels.Balances, Channels.Balances);
+    }
+
+    /// @dev Override to stake a balance position and append resulting balances
+    /// to `out`.
+    function stakeBalanceToBalances(
+        bytes32 account,
+        AssetAmount memory balance,
+        Block memory rawRoute,
+        Writer memory out
+    ) internal virtual;
+
+    function stakeBalanceToBalances(
+        CommandContext calldata c
+    ) external payable onlyCommand(stakeBalanceToBalancesId, c.target) returns (bytes memory) {
+        uint i = 0;
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocScaledBalancesFrom(c.state, i, Keys.Balance, outScale);
+
+        while (i < end) {
+            Block memory route;
+            route = Blocks.routeFrom(c.request, q);
+            q = route.cursor;
+            Block memory ref = Blocks.from(c.state, i);
+            AssetAmount memory balance = ref.toBalanceValue();
+            stakeBalanceToBalances(c.account, balance, route, writer);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}
+
+abstract contract StakeCustodyToBalances is CommandBase {
+    uint internal immutable stakeCustodyToBalancesId = commandId(SCTB);
+    uint private immutable outScale;
+
+    constructor(string memory route, uint scaledRatio) {
+        outScale = scaledRatio;
+        emit Command(host, SCTB, route, stakeCustodyToBalancesId, Channels.Custodies, Channels.Balances);
+    }
+
+    /// @dev Override to stake a custody position and append resulting balances
+    /// to `out`.
+    function stakeCustodyToBalances(
+        bytes32 account,
+        HostAmount memory custody,
+        Block memory rawRoute,
+        Writer memory out
+    ) internal virtual;
+
+    function stakeCustodyToBalances(
+        CommandContext calldata c
+    ) external payable onlyCommand(stakeCustodyToBalancesId, c.target) returns (bytes memory) {
+        uint i = 0;
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocScaledBalancesFrom(c.state, i, Keys.Custody, outScale);
+
+        while (i < end) {
+            Block memory route;
+            route = Blocks.routeFrom(c.request, q);
+            q = route.cursor;
+            Block memory ref = Blocks.from(c.state, i);
+            HostAmount memory custody = ref.toCustodyValue();
+            stakeCustodyToBalances(c.account, custody, route, writer);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}
+
+abstract contract StakeCustodyToPosition is CommandBase {
+    uint internal immutable stakeCustodyToPositionId = commandId(SCTP);
+
+    constructor(string memory route) {
+        emit Command(host, SCTP, route, stakeCustodyToPositionId, Channels.Custodies, Channels.Setup);
+    }
+
+    /// @dev Override to stake a custody position into a non-balance setup
+    /// target described by `rawRoute`.
+    function stakeCustodyToPosition(bytes32 account, HostAmount memory custody, Block memory rawRoute) internal virtual;
+
+    function stakeCustodyToPosition(
+        CommandContext calldata c
+    ) external payable onlyCommand(stakeCustodyToPositionId, c.target) returns (bytes memory) {
+        uint i = 0;
+        uint q = 0;
+        while (i < c.state.length) {
+            Block memory ref = Blocks.from(c.state, i);
+            if (ref.key != Keys.Custody) break;
+            HostAmount memory custody = ref.toCustodyValue();
+            Block memory route;
+            route = Blocks.routeFrom(c.request, q);
+            q = route.cursor;
+            stakeCustodyToPosition(c.account, custody, route);
+            i = ref.cursor;
+        }
+
+        return done(0, i);
+    }
+}

package/contracts/commands/Supply.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandBase, CommandContext, Channels } from "./Base.sol";
+import { Blocks, Block, HostAmount, Keys } from "../Blocks.sol";
+string constant NAME = "supply";
+
+using Blocks for Block;
+
+abstract contract Supply is CommandBase {
+    uint internal immutable supplyId = commandId(NAME);
+
+    constructor() {
+        emit Command(host, NAME, "", supplyId, Channels.Custodies, Channels.Setup);
+    }
+
+    /// @dev Override to consume or supply a single custody position.
+    /// Called once per CUSTODY block in state.
+    function supply(bytes32 account, HostAmount memory value) internal virtual;
+
+    function supply(CommandContext calldata c) external payable onlyCommand(supplyId, c.target) returns (bytes memory) {
+        uint i = 0;
+        while (i < c.state.length) {
+            Block memory ref = Blocks.from(c.state, i);
+            if (ref.key != Keys.Custody) break;
+            HostAmount memory value = ref.toCustodyValue();
+            supply(c.account, value);
+            i = ref.cursor;
+        }
+
+        return done(0, i);
+    }
+}

package/contracts/commands/Swap.sol

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, Channels } from "./Base.sol";
+import { AssetAmount, HostAmount, Keys, Schemas, Blocks, Block, Writers, Writer } from "../Blocks.sol";
+using Blocks for Block;
+using Writers for Writer;
+
+string constant SEBTB = "swapExactBalanceToBalance";
+string constant SECTB = "swapExactCustodyToBalance";
+
+abstract contract SwapExactBalanceToBalance is CommandBase {
+    uint internal immutable swapExactBalanceToBalanceId = commandId(SEBTB);
+
+    constructor(string memory maybeRoute) {
+        string memory schema = Schemas.route1(maybeRoute, Schemas.Minimum);
+        emit Command(host, SEBTB, schema, swapExactBalanceToBalanceId, Channels.Balances, Channels.Balances);
+    }
+
+    /// @dev Override to swap an exact balance input into a balance output.
+    /// Implementations extract the requested minimum from
+    /// `rawRoute.innerMinimum()`.
+    function swapExactBalanceToBalance(
+        bytes32 account,
+        AssetAmount memory balance,
+        Block memory rawRoute
+    ) internal virtual returns (AssetAmount memory out);
+
+    function swapExactBalanceToBalance(
+        CommandContext calldata c
+    ) external payable onlyCommand(swapExactBalanceToBalanceId, c.target) returns (bytes memory) {
+        uint i = 0;
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocBalancesFrom(c.state, i, Keys.Balance);
+
+        while (i < end) {
+            Block memory route;
+            route = Blocks.routeFrom(c.request, q);
+            q = route.cursor;
+            Block memory ref = Blocks.from(c.state, i);
+            AssetAmount memory balance = ref.toBalanceValue();
+            AssetAmount memory out = swapExactBalanceToBalance(c.account, balance, route);
+            writer.appendNonZeroBalance(out);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}
+
+abstract contract SwapExactCustodyToBalance is CommandBase {
+    uint internal immutable swapExactCustodyToBalanceId = commandId(SECTB);
+
+    constructor(string memory maybeRoute) {
+        string memory schema = Schemas.route1(maybeRoute, Schemas.Minimum);
+        emit Command(host, SECTB, schema, swapExactCustodyToBalanceId, Channels.Custodies, Channels.Balances);
+    }
+
+    /// @dev Override to swap an exact custody input into a balance output.
+    /// Implementations extract the requested minimum from
+    /// `rawRoute.innerMinimum()`.
+    function swapExactCustodyToBalance(
+        bytes32 account,
+        HostAmount memory custody,
+        Block memory rawRoute
+    ) internal virtual returns (AssetAmount memory out);
+
+    function swapExactCustodyToBalance(
+        CommandContext calldata c
+    ) external payable onlyCommand(swapExactCustodyToBalanceId, c.target) returns (bytes memory) {
+        uint i = 0;
+        uint q = 0;
+        (Writer memory writer, uint end) = Writers.allocBalancesFrom(c.state, i, Keys.Custody);
+
+        while (i < end) {
+            Block memory route;
+            route = Blocks.routeFrom(c.request, q);
+            q = route.cursor;
+            Block memory ref = Blocks.from(c.state, i);
+            HostAmount memory custody = ref.toCustodyValue();
+            AssetAmount memory out = swapExactCustodyToBalance(c.account, custody, route);
+            writer.appendNonZeroBalance(out);
+            i = ref.cursor;
+        }
+
+        return writer.finish();
+    }
+}