@fastish/contracts 0.1.0

package/contracts/test/TestLiquidityHost.sol

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Host} from "../core/Host.sol";
+import {
+    AddLiquidityFromCustodiesToBalances,
+    RemoveLiquidityFromCustodyToBalances,
+    AddLiquidityFromBalancesToBalances,
+    RemoveLiquidityFromBalanceToBalances
+} from "../commands/Liquidity.sol";
+import {Data} from "../blocks/Data.sol";
+import {AssetAmount, DataPairRef, DataRef, HostAmount, Writer} from "../blocks/Schema.sol";
+import {Writers} from "../blocks/Writers.sol";
+import {toHostId} from "../utils/Ids.sol";
+
+using Data for DataRef;
+using Writers for Writer;
+
+contract TestLiquidityHost is
+    Host,
+    AddLiquidityFromCustodiesToBalances,
+    RemoveLiquidityFromCustodyToBalances,
+    AddLiquidityFromBalancesToBalances,
+    RemoveLiquidityFromBalanceToBalances
+{
+    bytes32 internal constant LP_FROM_CUSTODIES_ASSET = bytes32(uint(0xaaa1));
+    bytes32 internal constant LP_FROM_BALANCES_ASSET = bytes32(uint(0xaaa2));
+    bytes32 internal constant REDEEM_FROM_CUSTODY_ASSET = bytes32(uint(0xbbb1));
+    bytes32 internal constant REDEEM_FROM_BALANCE_ASSET = bytes32(uint(0xbbb2));
+
+    event AddCustodiesMapped(
+        bytes32 account,
+        bytes32 assetA,
+        uint amountA,
+        bytes32 assetB,
+        uint amountB,
+        bytes routeData
+    );
+    event RemoveCustodyMapped(bytes32 account, bytes32 asset, uint amount, bytes routeData);
+    event AddBalancesMapped(
+        bytes32 account,
+        bytes32 assetA,
+        uint amountA,
+        bytes32 assetB,
+        uint amountB,
+        bytes routeData
+    );
+    event RemoveBalanceMapped(bytes32 account, bytes32 asset, uint amount, bytes routeData);
+    event MinimumObserved(bytes32 asset, bytes32 meta, uint amount);
+
+    constructor(address cmdr)
+        Host(address(0), 1, "test")
+        AddLiquidityFromCustodiesToBalances("route(bytes data)", 15_000)
+        RemoveLiquidityFromCustodyToBalances("route(bytes data)", 20_000)
+        AddLiquidityFromBalancesToBalances("route(bytes data)", 15_000)
+        RemoveLiquidityFromBalanceToBalances("route(bytes data)", 20_000)
+    {
+        if (cmdr != address(0)) access(toHostId(cmdr), true);
+    }
+
+    function addLiquidityFromCustodiesToBalances(
+        bytes32 account,
+        DataPairRef memory rawCustodies,
+        DataRef memory rawRoute,
+        Writer memory out
+    ) internal override {
+        HostAmount memory a = rawCustodies.a.toCustodyValue();
+        HostAmount memory b = rawCustodies.b.toCustodyValue();
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        uint routeLen = rawRoute.bound - rawRoute.i;
+        emit AddCustodiesMapped(account, a.asset, a.amount, b.asset, b.amount, routeData);
+        emitMinimum(rawRoute);
+
+        out.appendBalance(a.asset, a.meta, a.amount + routeLen);
+        out.appendBalance(b.asset, b.meta, b.amount + routeLen + 1);
+        out.appendBalance(LP_FROM_CUSTODIES_ASSET, bytes32(routeLen), a.amount + b.amount);
+    }
+
+    function removeLiquidityFromCustodyToBalances(
+        bytes32 account,
+        HostAmount memory custody,
+        DataRef memory rawRoute,
+        Writer memory out
+    ) internal override {
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        uint routeLen = rawRoute.bound - rawRoute.i;
+        emit RemoveCustodyMapped(account, custody.asset, custody.amount, routeData);
+        emitMinimum(rawRoute);
+
+        out.appendBalance(custody.asset, custody.meta, custody.amount + routeLen);
+        out.appendBalance(REDEEM_FROM_CUSTODY_ASSET, bytes32(routeLen), custody.amount + 10);
+    }
+
+    function addLiquidityFromBalancesToBalances(
+        bytes32 account,
+        DataPairRef memory rawBalances,
+        DataRef memory rawRoute,
+        Writer memory out
+    ) internal override {
+        AssetAmount memory a = rawBalances.a.toBalanceValue();
+        AssetAmount memory b = rawBalances.b.toBalanceValue();
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        uint routeLen = rawRoute.bound - rawRoute.i;
+        emit AddBalancesMapped(account, a.asset, a.amount, b.asset, b.amount, routeData);
+        emitMinimum(rawRoute);
+
+        out.appendBalance(a.asset, a.meta, a.amount + routeLen);
+        out.appendBalance(b.asset, b.meta, b.amount + routeLen + 2);
+        out.appendBalance(LP_FROM_BALANCES_ASSET, bytes32(routeLen), a.amount + b.amount);
+    }
+
+    function removeLiquidityFromBalanceToBalances(
+        bytes32 account,
+        AssetAmount memory balance,
+        DataRef memory rawRoute,
+        Writer memory out
+    ) internal override {
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        uint routeLen = rawRoute.bound - rawRoute.i;
+        emit RemoveBalanceMapped(account, balance.asset, balance.amount, routeData);
+        emitMinimum(rawRoute);
+
+        out.appendBalance(balance.asset, balance.meta, balance.amount + routeLen);
+        out.appendBalance(REDEEM_FROM_BALANCE_ASSET, bytes32(routeLen), balance.amount + 20);
+    }
+
+    function emitMinimum(DataRef memory rawRoute) internal {
+        if (rawRoute.bound < rawRoute.end) {
+            (bytes32 asset, bytes32 meta, uint amount) = rawRoute.innerMinimum();
+            emit MinimumObserved(asset, meta, amount);
+        }
+    }
+
+    function getAddLiquidityFromCustodiesToBalancesId() external view returns (uint) {
+        return addLiquidityFromCustodiesToBalancesId;
+    }
+
+    function getRemoveLiquidityFromCustodyToBalancesId() external view returns (uint) {
+        return removeLiquidityFromCustodyToBalancesId;
+    }
+
+    function getAddLiquidityFromBalancesToBalancesId() external view returns (uint) {
+        return addLiquidityFromBalancesToBalancesId;
+    }
+
+    function getRemoveLiquidityFromBalanceToBalancesId() external view returns (uint) {
+        return removeLiquidityFromBalanceToBalancesId;
+    }
+}

package/contracts/test/TestMintHost.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Host} from "../core/Host.sol";
+import {MintToBalances} from "../commands/Mint.sol";
+import {DataRef, Writer} from "../blocks/Schema.sol";
+import {Writers} from "../blocks/Writers.sol";
+import {toHostId} from "../utils/Ids.sol";
+
+using Writers for Writer;
+
+contract TestMintHost is Host, MintToBalances {
+    event MintCalled(bytes32 account, bytes routeData);
+
+    bytes32 public returnAsset;
+    bytes32 public returnMeta;
+    uint    public returnAmount;
+
+    constructor(address cmdr)
+        Host(address(0), 1, "test")
+        MintToBalances("", 10_000)
+    {
+        if (cmdr != address(0)) access(toHostId(cmdr), true);
+    }
+
+    function setReturn(bytes32 asset, bytes32 meta, uint amount) external {
+        returnAsset = asset;
+        returnMeta  = meta;
+        returnAmount = amount;
+    }
+
+    function mintToBalances(bytes32 account, DataRef memory rawRoute, Writer memory out) internal override {
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        emit MintCalled(account, routeData);
+        if (returnAmount > 0) out.appendBalance(returnAsset, returnMeta, returnAmount);
+    }
+
+    function getMintId() external view returns (uint) { return mintToBalancesId; }
+    function getAdminAccount() external view returns (bytes32) { return adminAccount; }
+}

package/contracts/test/TestPeerHost.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Host} from "../core/Host.sol";
+import {PeerPull} from "../peer/Pull.sol";
+import {PeerPush} from "../peer/Push.sol";
+import {DataRef} from "../blocks/Schema.sol";
+import {toHostId} from "../utils/Ids.sol";
+
+contract TestPeerHost is Host, PeerPull, PeerPush {
+    event PeerPullCalled(bytes routeData);
+    event PeerPushCalled(bytes routeData);
+
+    constructor(address cmdr)
+        Host(address(0), 1, "test")
+        PeerPull("")
+        PeerPush("")
+    {
+        if (cmdr != address(0)) access(toHostId(cmdr), true);
+    }
+
+    function peerPull(DataRef memory rawRoute) internal override {
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        emit PeerPullCalled(routeData);
+    }
+
+    function peerPush(DataRef memory rawRoute) internal override {
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        emit PeerPushCalled(routeData);
+    }
+
+    function getPeerPullId() external view returns (uint) { return peerPullId; }
+    function getPeerPushId() external view returns (uint) { return peerPushId; }
+}

package/contracts/test/TestReclaimHost.sol

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Host} from "../core/Host.sol";
+import {ReclaimToBalances} from "../commands/Reclaim.sol";
+import {AssetAmount, DataRef, Writer} from "../blocks/Schema.sol";
+import {Data} from "../blocks/Data.sol";
+import {Writers} from "../blocks/Writers.sol";
+import {toHostId} from "../utils/Ids.sol";
+
+using Data for DataRef;
+using Writers for Writer;
+
+contract TestReclaimHost is Host, ReclaimToBalances {
+    event ReclaimCalled(bytes32 account, bytes32 asset, bytes32 meta, uint amount, bytes routeData);
+
+    bytes32 public returnAsset;
+    bytes32 public returnMeta;
+    uint    public returnAmount;
+
+    constructor(address cmdr)
+        Host(address(0), 1, "test")
+        ReclaimToBalances("", 10_000)
+    {
+        if (cmdr != address(0)) access(toHostId(cmdr), true);
+    }
+
+    function setReturn(bytes32 asset, bytes32 meta, uint amount) external {
+        returnAsset = asset;
+        returnMeta  = meta;
+        returnAmount = amount;
+    }
+
+    function reclaimToBalances(
+        bytes32 account,
+        AssetAmount memory amount,
+        DataRef memory rawRoute,
+        Writer memory out
+    ) internal override {
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        emit ReclaimCalled(account, amount.asset, amount.meta, amount.amount, routeData);
+        if (returnAmount > 0) out.appendBalance(returnAsset, returnMeta, returnAmount);
+    }
+
+    function getReclaimBalanceId() external view returns (uint) { return reclaimToBalancesId; }
+    function getAdminAccount() external view returns (bytes32) { return adminAccount; }
+}

package/contracts/test/TestRejectEther.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+contract TestRejectEther {
+    receive() external payable {
+        revert("NO_ETH");
+    }
+}

package/contracts/test/TestRemoveHost.sol

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Host} from "../core/Host.sol";
+import {Remove} from "../commands/Remove.sol";
+import {DataRef} from "../blocks/Schema.sol";
+import {toHostId} from "../utils/Ids.sol";
+
+contract TestRemoveHost is Host, Remove {
+    event RemoveCalled(bytes32 account, bytes routeData);
+
+    constructor(address cmdr)
+        Host(address(0), 1, "test")
+        Remove("")
+    {
+        if (cmdr != address(0)) access(toHostId(cmdr), true);
+    }
+
+    function remove(bytes32 account, DataRef memory rawRoute) internal override {
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        emit RemoveCalled(account, routeData);
+    }
+
+    function getRemoveId() external view returns (uint) { return removeId; }
+    function getAdminAccount() external view returns (bytes32) { return adminAccount; }
+}

package/contracts/test/TestSwapHost.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Host} from "../core/Host.sol";
+import {SwapExactBalanceToBalance} from "../commands/Swap.sol";
+import {AssetAmount, DataRef} from "../Schema.sol";
+import {Data} from "../blocks/Data.sol";
+
+using Data for DataRef;
+
+contract TestSwapHost is Host, SwapExactBalanceToBalance {
+    event SwapMapped(bytes32 account, bytes32 asset, bytes32 meta, uint amount, bytes routeData);
+    event SwapMinimum(bytes32 asset, bytes32 meta, uint amount);
+
+    constructor(address fastish)
+        Host(fastish, 1, "test")
+        SwapExactBalanceToBalance("route(bytes data)")
+    {}
+
+    function swapExactBalanceToBalance(
+        bytes32 account,
+        AssetAmount memory balance,
+        DataRef memory rawRoute
+    ) internal override returns (AssetAmount memory out) {
+        bytes calldata routeData = msg.data[rawRoute.i:rawRoute.bound];
+        emit SwapMapped(account, balance.asset, balance.meta, balance.amount, routeData);
+        if (rawRoute.bound < rawRoute.end) {
+            (bytes32 minAsset, bytes32 minMeta, uint minAmount) = rawRoute.innerMinimum();
+            emit SwapMinimum(minAsset, minMeta, minAmount);
+        }
+        return AssetAmount({
+            asset: balance.asset,
+            meta: bytes32(rawRoute.bound - rawRoute.i),
+            amount: balance.amount + (rawRoute.bound - rawRoute.i)
+        });
+    }
+
+    function getSwapExactInAsset32Id() external view returns (uint) {
+        return swapExactBalanceToBalanceId;
+    }
+
+    function getAdminAccount() external view returns (bytes32) {
+        return adminAccount;
+    }
+}

package/contracts/test/TestUtils.sol

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {addrOr, toAdminAccount, toUserAccount, accountEvmAddr, isAdminAccount, ensureEvmAccount} from "../utils/Accounts.sol";
+import {
+    toValueAsset,
+    toErc20Asset,
+    toErc721Asset,
+    isAsset32,
+    resolveAmount,
+    ensureAmount,
+    ensureAssetRef,
+    localErc20Addr,
+    localErc721Issuer
+} from "../utils/Assets.sol";
+import {toHostId, toCommandId, toCommandSelector, isHost, isCommand, localNodeAddr, localHostAddr, ensureHost, ensureCommand} from "../utils/Ids.sol";
+import {applyBps, beforeBps, isFamily, isLocal, isLocalFamily, matchesBase, toLocalBase, toUnspecifiedBase, max8, max16, max32, max64, max128, max160} from "../utils/Utils.sol";
+import {msgValue, useValue, ValueBudget} from "../utils/Value.sol";
+import {bytes32ToString} from "../utils/Strings.sol";
+
+contract TestUtils {
+    function testAddrOr(address addr, address or_) external pure returns (address) {
+        return addrOr(addr, or_);
+    }
+
+    function testToAdminAccount(address addr) external view returns (bytes32) {
+        return toAdminAccount(addr);
+    }
+
+    function testToUserAccount(address addr) external pure returns (bytes32) {
+        return toUserAccount(addr);
+    }
+
+    function testAccountEvmAddr(bytes32 account) external pure returns (address) {
+        return accountEvmAddr(account);
+    }
+
+    function testIsAdminAccount(bytes32 account) external pure returns (bool) {
+        return isAdminAccount(account);
+    }
+
+    function testToValueAsset() external view returns (bytes32) {
+        return toValueAsset();
+    }
+
+    function testToErc20Asset(address addr) external view returns (bytes32) {
+        return toErc20Asset(addr);
+    }
+
+    function testToErc721Asset(address addr) external view returns (bytes32) {
+        return toErc721Asset(addr);
+    }
+
+    function testIsAsset32(bytes32 asset) external pure returns (bool) {
+        return isAsset32(asset);
+    }
+
+    function testResolveAmount(uint available, uint min, uint max) external pure returns (uint) {
+        return resolveAmount(available, min, max);
+    }
+
+    function testEnsureAmount(uint amount) external pure returns (uint) {
+        return ensureAmount(amount);
+    }
+
+    function testEnsureAmountRange(uint amount, uint min, uint max) external pure returns (uint) {
+        return ensureAmount(amount, min, max);
+    }
+
+    function testEnsureAssetRef(bytes32 asset, bytes32 meta) external pure returns (bytes32) {
+        return ensureAssetRef(asset, meta);
+    }
+
+    function testLocalErc20Addr(bytes32 asset) external view returns (address) {
+        return localErc20Addr(asset);
+    }
+
+    function testLocalErc721Issuer(bytes32 asset) external view returns (address) {
+        return localErc721Issuer(asset);
+    }
+
+    function testToHostId(address addr) external view returns (uint) {
+        return toHostId(addr);
+    }
+
+    function testToCommandId(bytes32 name, address addr) external view returns (uint) {
+        return toCommandId(toCommandSelector(name), addr);
+    }
+
+    function testToCommandSelector(bytes32 name) external pure returns (bytes4) {
+        return toCommandSelector(name);
+    }
+
+    function testIsHost(uint id) external pure returns (bool) {
+        return isHost(id);
+    }
+
+    function testIsCommand(uint id) external pure returns (bool) {
+        return isCommand(id);
+    }
+
+    function testLocalNodeAddr(uint node) external view returns (address) {
+        return localNodeAddr(node);
+    }
+
+    function testLocalHostAddr(uint host) external view returns (address) {
+        return localHostAddr(host);
+    }
+
+    function testEnsureHost(uint id, address addr) external view returns (uint) {
+        return ensureHost(id, addr);
+    }
+
+    function testEnsureCommand(uint id) external pure returns (uint) {
+        return ensureCommand(id);
+    }
+
+    function testApplyBps(uint amount, uint16 bps) external pure returns (uint) {
+        return applyBps(amount, bps);
+    }
+
+    function testBeforeBps(uint amount, uint16 bps) external pure returns (uint) {
+        return beforeBps(amount, bps);
+    }
+
+    function testIsFamily(uint value, uint24 family) external pure returns (bool) {
+        return isFamily(value, family);
+    }
+
+    function testIsLocal(uint value) external view returns (bool) {
+        return isLocal(value);
+    }
+
+    function testMatchesBase(bytes32 value, uint base) external pure returns (bool) {
+        return matchesBase(value, base);
+    }
+
+    function testToLocalBase(uint32 prefix) external view returns (uint) {
+        return toLocalBase(prefix);
+    }
+
+    function testMsgValue() external payable returns (uint) {
+        ValueBudget memory budget = msgValue();
+        return budget.remaining;
+    }
+
+    function testUseValue(uint amount, uint remaining) external pure returns (uint spent, uint remainingAfter) {
+        ValueBudget memory budget = ValueBudget({remaining: remaining});
+        spent = useValue(amount, budget);
+        remainingAfter = budget.remaining;
+    }
+
+    function testBytes32ToString(bytes32 value) external pure returns (string memory) {
+        return bytes32ToString(value);
+    }
+
+    function testMax8(uint value) external pure returns (uint) {
+        return max8(value);
+    }
+
+    function testMax16(uint value) external pure returns (uint) {
+        return max16(value);
+    }
+
+    function testMax32(uint value) external pure returns (uint) {
+        return max32(value);
+    }
+
+    function testMax64(uint value) external pure returns (uint) {
+        return max64(value);
+    }
+
+    function testMax128(uint value) external pure returns (uint) {
+        return max128(value);
+    }
+
+    function testMax160(uint value) external pure returns (uint) {
+        return max160(value);
+    }
+}

package/contracts/test/TestValidator.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Validator} from "../core/Validator.sol";
+
+contract TestValidator is Validator {
+    function testVerify(bytes32 hash, uint192 nonce, bytes calldata proof) external returns (address) {
+        return verify(hash, nonce, proof);
+    }
+}

package/contracts/utils/Accounts.sol

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {ACCOUNT, ADMIN, EVM32, USER} from "./Layout.sol";
+import {isFamily, toLocalBase, toUnspecifiedBase} from "./Utils.sol";
+
+error InvalidAccount();
+
+uint24 constant ACCOUNT_FAMILY = (uint24(EVM32) << 8) | uint24(ACCOUNT);
+uint32 constant ADMIN_PREFIX = (uint32(EVM32) << 16) | (uint32(ACCOUNT) << 8) | uint32(ADMIN);
+uint32 constant USER_PREFIX = (uint32(EVM32) << 16) | (uint32(ACCOUNT) << 8) | uint32(USER);
+
+function addrOr(address addr, address or) pure returns (address) {
+    return addr == address(0) ? or : addr;
+}
+
+function accountPrefix(bytes32 account) pure returns (uint32) {
+    return uint32(uint(account) >> 224);
+}
+
+function isAdminAccount(bytes32 account) pure returns (bool) {
+    return accountPrefix(account) == ADMIN_PREFIX;
+}
+
+function toAdminAccount(address addr) view returns (bytes32) {
+    return bytes32(toLocalBase(ADMIN_PREFIX) | (uint(uint160(addr)) << 32));
+}
+
+function toUserAccount(address addr) pure returns (bytes32) {
+    return bytes32(toUnspecifiedBase(USER_PREFIX) | (uint(uint160(addr)) << 32));
+}
+
+function ensureEvmAccount(bytes32 account) pure {
+    if (!isFamily(uint(account), ACCOUNT_FAMILY)) {
+        revert InvalidAccount();
+    }
+}
+
+function accountEvmAddr(bytes32 account) pure returns (address) {
+    ensureEvmAccount(account);
+    return address(uint160(uint(account) >> 32));
+}

package/contracts/utils/Assets.sol

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {ASSET, ERC20, ERC721, EVM32, VALUE} from "./Layout.sol";
+import {matchesBase, toLocalBase} from "./Utils.sol";
+
+uint32 constant VALUE_PREFIX = (uint32(EVM32) << 16) | (uint32(ASSET) << 8) | uint32(VALUE);
+uint32 constant ERC20_PREFIX = (uint32(EVM32) << 16) | (uint32(ASSET) << 8) | uint32(ERC20);
+uint32 constant ERC721_PREFIX = (uint32(EVM32) << 16) | (uint32(ASSET) << 8) | uint32(ERC721);
+
+error ZeroAmount();
+error InvalidAsset();
+error BadAmount(uint amount);
+
+function isAsset32(bytes32 asset) pure returns (bool) {
+    return bytes1(asset) == 0x20;
+}
+
+function toValueAsset() view returns (bytes32) {
+    return bytes32(toLocalBase(VALUE_PREFIX));
+}
+
+function toErc20Asset(address addr) view returns (bytes32) {
+    return bytes32(toLocalBase(ERC20_PREFIX) | (uint(uint160(addr)) << 32));
+}
+
+function toErc721Asset(address issuer) view returns (bytes32) {
+    return bytes32(toLocalBase(ERC721_PREFIX) | (uint(uint160(issuer)) << 32));
+}
+
+function resolveAmount(uint available, uint min, uint max) pure returns (uint) {
+    uint amount = available > max ? max : available;
+    if (amount < min) {
+        revert BadAmount(amount);
+    }
+    return amount;
+}
+
+function ensureAmount(uint amount) pure returns (uint) {
+    if (amount == 0) {
+        revert ZeroAmount();
+    }
+    return amount;
+}
+
+function ensureAmount(uint amount, uint min, uint max) pure returns (uint) {
+    if (amount < min || amount > max) {
+        revert BadAmount(amount);
+    }
+    return amount;
+}
+
+function ensureAssetRef(bytes32 asset, bytes32 meta) pure returns (bytes32) {
+    if (asset == 0 || (bytes1(asset) == 0x20 && meta != 0)) revert InvalidAsset();
+    return bytes1(asset) == 0x20 ? asset : keccak256(bytes.concat(asset, meta));
+}
+
+function ensureBalanceRef(bytes32 asset, bytes32 meta, uint amount) pure returns (bytes32 ref) {
+    ensureAmount(amount);
+    return ensureAssetRef(asset, meta);
+}
+
+function localErc20Addr(bytes32 asset) view returns (address) {
+    if (!matchesBase(asset, toLocalBase(ERC20_PREFIX))) revert InvalidAsset();
+    return address(uint160(uint(asset) >> 32));
+}
+
+function localErc721Issuer(bytes32 asset) view returns (address) {
+    if (!matchesBase(asset, toLocalBase(ERC721_PREFIX))) revert InvalidAsset();
+    return address(uint160(uint(asset) >> 32));
+}

package/contracts/utils/Channels.sol

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+uint8 constant SETUP = 0x0001;
+uint8 constant PIPE = 0x0002;
+uint8 constant BALANCES = 0x0003;
+uint8 constant TRANSACTIONS = 0x0004;
+uint8 constant CUSTODIES = 0x0005;
+uint8 constant CLAIMS = 0x0006;