HandsOnChain

供給量と残高の和をテストで守る

作るもの

このレッスンを終えると、発行と送金と償還と凍結をどの順で行っても供給量が持ち主の残高の和と等しいことを、Foundryのfuzzテストとinvariantテストで確かめられます。
ここまでのtest_で始まるテストは、決めた入力に対して決めた結果になるかを確かめるものでした。
このレッスンのテストは、Foundryが作るたくさんの入力と操作の並びを使って、崩れてはいけない性質を確かめます。

背景

銀行の帳簿では、全ての預金の残高を足した額が帳簿の合計と必ず一致します。
一致しない時は、どこかで記帳を誤ったことになります。
円トークンでも、供給量 (totalSupply) と全ての持ち主の残高の和が一致することが、発行体が持つ円と円トークンの額が合っていることの前提になります。

この種の「どんな場合でも成り立つ性質」は、思い付いた例を試すだけでは確かめ切れません。
Foundryには、入力を自動で作って確かめるテストが2種類あります。

テスト 名前の付け方 Foundryがすること
fuzzテスト testFuzz_で始める 引数にいろいろな値を入れて、同じテストを何度も実行する
invariantテスト invariant_で始める 決めた関数をいろいろな順番と引数で呼び、呼ぶたびに性質を確かめる

実装

まず、送金しても供給量と2人の残高の和が変わらないことをfuzzテストで確かめます。

    function testFuzz_TransferKeepsSupply(uint256 issued, uint256 sent) public {
        issued = bound(issued, 1, 1e30);
        sent = bound(sent, 0, issued);
        _issue(alice, issued);

        vm.prank(alice);
        token.transfer(bob, sent);

        assertEq(token.balanceOf(alice) + token.balanceOf(bob), issued);
        assertEq(token.totalSupply(), issued);
    }

boundは、Foundryが入れた値を意味のある範囲に収める関数です。
送る額を発行した額以下に収めないと、ほとんどの回が残高不足で拒まれます。

次に、invariantテストで操作を呼び出すハンドラのコントラクトを、同じファイルの末尾に足します。
Foundryはこのハンドラの関数を、いろいろな順番と引数で呼びます。

/// @dev invariant のテストで、発行と送金と償還と凍結を順不同に呼ぶハンドラ
contract JpyTokenHandler is Test {
    JpyToken internal token;
    address internal issuer;
    address[] internal holders;

    constructor(JpyToken token_, address issuer_, address[] memory holders_) {
        token = token_;
        issuer = issuer_;
        holders = holders_;
    }

    function _holder(uint256 seed) internal view returns (address) {
        return holders[seed % holders.length];
    }

    function issue(uint256 seed, uint256 amount) external {
        amount = bound(amount, 1, 1e27);
        vm.prank(issuer);
        token.issue(_holder(seed), amount, bytes32(seed));
    }

    function transfer(uint256 fromSeed, uint256 toSeed, uint256 amount) external {
        address from = _holder(fromSeed);
        amount = bound(amount, 0, token.balanceOf(from));
        vm.prank(from);
        token.transfer(_holder(toSeed), amount);
    }

    function redeem(uint256 seed, uint256 amount) external {
        address holder = _holder(seed);
        amount = bound(amount, 0, token.balanceOf(holder));
        vm.prank(holder);
        token.redeem(amount);
    }

    function setFrozen(uint256 seed, bool frozen) external {
        vm.prank(issuer);
        token.setFrozen(_holder(seed), frozen);
    }

    function holderCount() external view returns (uint256) {
        return holders.length;
    }

    function holderAt(uint256 index) external view returns (address) {
        return holders[index];
    }
}

最後に、ハンドラを使ってinvariantテストを書きます。

contract JpyTokenInvariantTest is Test {
    JpyToken internal token;
    JpyTokenHandler internal handler;

    function setUp() public {
        address issuer = makeAddr("issuer");
        address[] memory holders = new address[](3);
        holders[0] = makeAddr("alice");
        holders[1] = makeAddr("bob");
        holders[2] = makeAddr("carol");

        token = new JpyToken(issuer);
        vm.startPrank(issuer);
        for (uint256 i = 0; i < holders.length; i++) {
            token.setAllowed(holders[i], true);
        }
        vm.stopPrank();

        handler = new JpyTokenHandler(token, issuer, holders);
        targetContract(address(handler));
    }

    /// @dev どの順で発行と送金と償還と凍結を呼んでも、供給量は持ち主の残高の和と等しい
    function invariant_SupplyEqualsBalances() public view {
        uint256 sum;
        for (uint256 i = 0; i < handler.holderCount(); i++) {
            sum += token.balanceOf(handler.holderAt(i));
        }
        assertEq(token.totalSupply(), sum);
    }
}
行 意味
targetContract(address(handler)) Foundryが呼ぶ相手をハンドラのコントラクトだけに絞る
invariant_SupplyEqualsBalances ハンドラの関数を呼ぶたびに、Foundryがこの関数で性質を確かめる

凍結したアカウントの送金は拒まれるため、ハンドラの呼び出しの一部は失敗します。
失敗しても性質の確認は続けたいので、foundry.tomlの[invariant]のセクションにfail_on_revert = falseを書きます。

[invariant]
runs = 64
depth = 32
fail_on_revert = false

runsは操作の並びを作り直す回数で、depthは1つの並びでハンドラを呼ぶ回数です。

確かめる

forge test

次のように、invariantテストが2,048回の呼び出しの後も性質を保ったことが表示されます。

[PASS] invariant_SupplyEqualsBalances() (runs: 64, calls: 2048, reverts: 528)

revertsの数は、凍結や残高不足で拒まれた呼び出しの数です。
性質が崩れた時の表示を見るには、invariant_SupplyEqualsBalancesのassertEqの右辺をsum + 1に変えて実行します。
Foundryはテストを失敗させ、性質が崩れるまでの呼び出しの並びを表示します。

この時点で、15個のテストが全て通ります。
次のレッスンで、本人確認と凍結と一時停止をブラウザから行えるようにします。