HandsOnChain

円と口数の釣り合いをテストで守る

作るもの

このレッスンを終えると、注文から代金の受け取りまでの操作をどの順で行っても崩れない2つの性質を、Foundryのinvariantテストで確かめられます。
1つは、ファンドのコントラクトが持つ円が、約定の前の申込の円と受け取られていない解約の代金の和と等しいことです。
もう1つは、持分の発行済みの口数が、投資家の持つ口数と解約で預かった口数の和と等しいことです。
どちらの和も、ファンドのコントラクトが数えた合計の値ではなく、注文と代金の記録から数え直します。

背景

ファンドのコントラクトは、2種類の円を預かります。
1つは約定の前の申込の円で、もう1つは運用会社が入れたのにまだ受け取られていない解約の代金です。
口数も、投資家が持つ分のほかに、解約の注文で預かった分をコントラクトが持ちます。

操作 ファンドのコントラクトの円 口数
subscribe 申込の円を預かって増える 変わらない
redeem 変わらない 投資家の口数がコントラクトへ移る。
発行済みの口数は変わらない
cancel 申込なら、預けた円を戻して減る 解約なら、預かった口数を投資家へ戻す
settle 申込の円を運用会社と投資家へ送り出して減る 申込の口数を発行して増え、解約の口数を消して減る
fundProceeds 運用会社が入れた代金の分だけ増える 変わらない
claim 投資家へ代金を払って減る 変わらない
性質 崩れた時に起きること
ファンドの円が、約定の前の申込の円と受け取られていない代金の和と等しい 取り消した人や受渡日の投資家へ払う円が足りないか、誰の注文にも数えられない円がコントラクトに残る
発行済みの口数が、投資家の持つ口数と預かった口数の和と等しい 誰も持たない口数で純資産を割り、基準価額が本当の値からずれる

ファンドのコントラクトは、預かっている円と口数の合計をpendingYenとunclaimedYenとheldUnitsに自分で数えています。
残高をこの合計と比べるだけでは、残高と合計を同じように数え違えた時に見落とします。
たとえば申込を取り消した時に円を戻さず、pendingYenも減らさない誤りがあると、残高とpendingYenは合ったままです。
注文は取り消しになっているので、取り消した投資家の円はコントラクトに残ったまま戻りません。

そこで不変条件は、注文の状態と代金の記録から和を数え直し、残高と合計の両方と比べます。
約定の前の申込の円は、状態が約定の前の申込の注文の額を足して数えます。
受け取られていない代金は、運用会社が入れた約定日の、投資家ごとの代金を足して数えます。

取り消しで円を戻さない誤りは、合計と比べても見えない
チェーンに残る値注文の状態約定の前取り消しpendingYen100,000円ファンドの円100,000円記録から数えた申込の円100,000円0円投資家A申し込んで取り消すファンドのコントラクト誤りのあるTokenizedFund不変条件記録から数え直す112233subscribe(100,000)subscribe(100,000)100,000 HJPY100,000 HJPYcancel(木曜, 0)cancel(木曜, 0)ファンドの円は記録から数えた和と合う?

この節で、時刻で振る舞いが変わる操作が増えました。
15時の締め切りで取り消せる時と純資産を入れられる時が分かれ、約定は件数で区切って何回にも分けられ、代金は土日を除いた3営業日後から受け取れます。
決めた例を試すテストだけでは、操作の並びと時刻の組み合わせを確かめ切れません。
そこで、Foundryが操作の順と引数を作り、ハンドラが範囲を整えて呼ぶinvariantテストで2つの性質を確かめます。

Foundryが操作を選び、呼ぶたびに記録から数え直す
チェーンに残る値約定の前の申込の円0円120,000円ファンドの円0円120,000円Foundry操作と引数を選ぶFundHandler送れない操作は飛ばすファンドのコントラクトTokenizedFund2つの不変条件invariant_で始まる関数11223344subscribe(who, amount)subscribe(who, amount)subscribe(120,000)subscribe(120,000)記録から数えた和とファンドの円は合う?1円から300,000円に収める1円から300,000円に収める

実装

starter/contracts/test/TokenizedFundInvariant.t.solを新しく作ります。
ファイルの初めに、ハンドラのコントラクトを置きます。
ハンドラはFoundryが呼ぶ操作を並べたコントラクトで、引数を意味のある範囲に収めてからファンドのコントラクトを呼びます。

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import {Test, console} from "forge-std/Test.sol";

import {JpyToken} from "@handsonchain/jpy-stablecoin-contracts/contracts/JpyToken.sol";
import {TokenizedFund} from "../contracts/TokenizedFund.sol";

// 投資家2人と運用会社の操作をでたらめな順に送る係。送れない操作は飛ばす
contract FundHandler is Test {
    JpyToken internal jpy;
    TokenizedFund internal fund;
    address internal manager;
    address[2] internal investors;

    // 関数ごとに、最後まで通った回数
    mapping(bytes32 action => uint256) public calls;

    function _count(string memory action) internal {
        calls[keccak256(bytes(action))]++;
    }

    constructor(JpyToken jpy_, TokenizedFund fund_, address manager_, address[2] memory investors_) {
        jpy = jpy_;
        fund = fund_;
        manager = manager_;
        investors = investors_;
    }
行 意味
console テストの出力に値を書くconsole.logを読み込む。
最後に通った回数を出すのに使う
JpyToken 1作目の円トークンを、pnpmのワークスペースから読み込む
investors 投資家2人。
どの操作も、Foundryが入れた数を2で割った余りで1人を選ぶ
calls 操作の名前ごとに、ファンドのコントラクトを呼んで最後まで通った回数を数える
_count 名前をkeccak256で32バイトに縮めてcallsの鍵にし、回数に1を足す

ハンドラの関数は、送ると断られる操作を送らずに、何もせずに戻ります。
_countはファンドのコントラクトを呼んだ後の行に置くので、callsには断られずに通った回数だけが入ります。

次に、申込と解約と取り消しと時刻の操作を足します。

    function subscribe(uint256 who, uint256 amount) external {
        address investor = investors[who % 2];
        amount = bound(amount, 1, 300_000);
        vm.prank(investor);
        fund.subscribe(amount);
        _count("subscribe");
    }

    function redeem(uint256 who, uint256 units) external {
        address investor = investors[who % 2];
        uint256 held = fund.balanceOf(investor);
        if (held == 0) return;
        units = bound(units, 1, held);
        vm.prank(investor);
        fund.redeem(units);
        _count("redeem");
    }

    function cancel(uint256 seed) external {
        uint256 day = fund.tradeDayOf(block.timestamp);
        TokenizedFund.Order[] memory orders = fund.ordersOf(day);
        if (orders.length == 0) return;
        uint256 index = seed % orders.length;
        if (orders[index].status != TokenizedFund.Status.Pending) return;
        vm.prank(orders[index].investor);
        fund.cancel(day, index);
        _count("cancel");
    }

    function warp(uint256 hours_) external {
        vm.warp(block.timestamp + bound(hours_, 1, 30) * 1 hours);
    }
行 意味
bound(amount, 1, 300_000) 申込の額を、1円から300,000円の間に収める
if (held == 0) return 口数を持っていない投資家は、解約せずに戻る
bound(units, 1, held) 解約の口数を、1口から持っている口数の間に収める
fund.tradeDayOf(block.timestamp) 今出した注文が入る約定日を選ぶ。
その日の締め切りはまだ来ていないので、取り消しは締め切りで断られない
seed % orders.length その約定日の注文から1件を選ぶ
status != Status.Pending 取り消し済みの注文は飛ばす
vm.prank(orders[index].investor) 注文した投資家の名義で取り消す。
他人の注文の取り消しは前のレッスンのテストで確かめている
bound(hours_, 1, 30) * 1 hours 時刻を1時間から30時間の間で進める。
何度か選ばれると、15時の締め切りと土日と受渡日をまたぐ

boundは、Foundryが入れた値を決めた範囲に収める関数です。
投資家2人はsetUpで100,000,000円ずつ受け取るので、1つの並びで300,000円の申込を全て選んでも円は足ります。

続けて、純資産を入れて約定する操作を足します。

    // 次に約定する約定日に純資産を入れ、その日の注文をcount件ずつ約定する。基準価額は9,000円から11,000円の間で動かす
    function settle(uint256 navSeed, uint256 count) external {
        uint256[] memory days_ = fund.orderDays();
        uint256 cursor = fund.dayCursor();
        if (cursor >= days_.length) return;
        uint256 day = days_[cursor];
        if (block.timestamp <= fund.cutoffAt(day)) return;
        if (fund.navOf(day) == 0) {
            uint256 netAssets = fund.totalSupply() * bound(navSeed, 9_000, 11_000) / 10_000;
            vm.prank(manager);
            fund.setNav(day, netAssets);
            _count("setNav");
        }
        vm.prank(manager);
        fund.settle(day, bound(count, 1, 5));
        _count("settle");
    }
行 意味
fund.orderDays()とfund.dayCursor() 約定し終えていない最も古い約定日を選ぶ。
前のレッスンの決まりで、それより後の約定日には純資産を入れられない
cursor >= days_.length 全ての約定日を約定し終えていれば、何もせずに戻る
block.timestamp <= fund.cutoffAt(day) その約定日の15時を過ぎていなければ、何もせずに戻る
fund.navOf(day) == 0 まだ純資産を入れていない約定日なら、先に純資産を入れる
fund.totalSupply() * bound(navSeed, 9_000, 11_000) / 10_000 発行済みの口数に9,000から11,000を掛けて1万で割る。
基準価額は9,000円から11,000円の間になる
bound(count, 1, 5) 1回に約定する件数を1件から5件にする。
注文が多い日は、何回かに分けて約定する

純資産の総額を発行済みの口数から出すので、基準価額は前の日から大きく離れません。
口数が0の日はnavForが10,000円を返すので、純資産の総額は0円で足ります。

最後に、代金を入れる操作と受け取る操作を足して、ハンドラを閉じます。

    // 約定し終えて、まだ代金を入れていない最も古い約定日の代金を入れる
    function fundProceeds() external {
        uint256[] memory days_ = fund.orderDays();
        uint256 cursor = fund.dayCursor();
        for (uint256 i = 0; i < cursor; i++) {
            if (fund.proceedsFunded(days_[i])) continue;
            vm.prank(manager);
            fund.fundProceeds(days_[i]);
            _count("fundProceeds");
            return;
        }
    }

    // 受渡日を過ぎて代金の入った約定日の代金を受け取る
    function claim(uint256 who) external {
        address investor = investors[who % 2];
        uint256[] memory days_ = fund.orderDays();
        for (uint256 i = 0; i < days_.length; i++) {
            uint256 day = days_[i];
            if (!fund.proceedsFunded(day) || fund.proceedsOf(day, investor) == 0) continue;
            if (block.timestamp < fund.deliveryAt(day)) continue;
            vm.prank(investor);
            fund.claim(day);
            _count("claim");
            return;
        }
    }
}
行 意味
i < cursor dayCursorより前の約定日は、全て約定し終えている。
その中から代金を入れていない最も古い日を選ぶ
return 代金を入れるのは1回の呼び出しで1日分だけにする
!fund.proceedsFunded(day) || fund.proceedsOf(day, investor) == 0 代金の入っていない約定日と、その投資家の代金がない約定日は飛ばす
block.timestamp < fund.deliveryAt(day) 受渡日の前の約定日も飛ばす

同じファイルの末尾に、テストのコントラクトを足します。

contract TokenizedFundInvariantTest is Test {
    uint256 internal constant YEN = 1e18;

    JpyToken internal jpy;
    TokenizedFund internal fund;
    FundHandler internal handler;
    address internal manager = makeAddr("manager");
    address internal alice = makeAddr("alice");
    address internal bob = makeAddr("bob");

    function setUp() public {
        // 2026-03-05 (木) の10時 (日本時間) から始める
        vm.warp(1772672400);
        jpy = new JpyToken(address(this));
        fund = new TokenizedFund(jpy, manager);
        address[4] memory allowed = [alice, bob, manager, address(fund)];
        for (uint256 i = 0; i < allowed.length; i++) jpy.setAllowed(allowed[i], true);
        jpy.issue(alice, 100_000_000 * YEN, keccak256("alice"));
        jpy.issue(bob, 100_000_000 * YEN, keccak256("bob"));
        jpy.issue(manager, 1_000_000_000 * YEN, keccak256("manager"));
        address[3] memory payers = [alice, bob, manager];
        for (uint256 i = 0; i < payers.length; i++) {
            vm.prank(payers[i]);
            jpy.approve(address(fund), type(uint256).max);
        }
        handler = new FundHandler(jpy, fund, manager, [alice, bob]);
        targetContract(address(handler));
    }
行 意味
vm.warp(1772672400) 時計を2026-03-05 (木) の日本時間の10時に合わせる。
締め切りの前から始める
new TokenizedFund(jpy, manager) テスト用に口数を渡せるFundHarnessではなく、ファンドのコントラクトそのものを置く。
口数は申込の約定でしか増えない
jpy.setAllowed(...) 投資家2人と運用会社とファンドのコントラクトを、円トークンの許可リストに載せる
jpy.approve(address(fund), ...) 投資家の申込と運用会社の代金の入金のために、ファンドのコントラクトに円を任せる
targetContract(address(handler)) Foundryが呼ぶ相手をハンドラだけに絞る

続けて、円の不変条件を足します。

    // ファンドのコントラクトが持つ円は、約定の前の申込の円と、入れたのにまだ受け取られていない解約の代金の和と等しい。
    // 和は注文と代金の記録から数え直し、ファンドが持つ合計の変数には頼らない
    function invariant_FundYenMatchesOrders() public view {
        uint256[] memory days_ = fund.orderDays();
        uint256 pending;
        uint256 unclaimed;
        for (uint256 i = 0; i < days_.length; i++) {
            TokenizedFund.Order[] memory orders = fund.ordersOf(days_[i]);
            for (uint256 j = 0; j < orders.length; j++) {
                if (orders[j].kind == TokenizedFund.Kind.Subscribe && orders[j].status == TokenizedFund.Status.Pending) {
                    pending += orders[j].amount;
                }
            }
            if (fund.proceedsFunded(days_[i])) {
                unclaimed += fund.proceedsOf(days_[i], alice) + fund.proceedsOf(days_[i], bob);
            }
        }
        assertEq(jpy.balanceOf(address(fund)), (pending + unclaimed) * YEN);
        assertEq(fund.pendingYen(), pending);
        assertEq(fund.unclaimedYen(), unclaimed);
    }
行 意味
fund.orderDays() 注文のある約定日を全て読み、日ごとに注文の記録を見る
Kind.Subscribe && Status.Pending 約定の前の申込の注文の額だけを足す。
取り消した申込と約定した申込は、もう円を預かっていない
fund.proceedsFunded(days_[i]) 運用会社が代金を入れた約定日だけ、投資家2人の受け取っていない代金を足す。
入れる前の代金は、まだファンドのコントラクトにない
assertEq(jpy.balanceOf(...), (pending + unclaimed) * YEN) ファンドのコントラクトの円が、記録から数えた和と等しい
assertEq(fund.pendingYen(), pending) コントラクトが数えた申込の円の合計も、記録から数えた額と等しい
assertEq(fund.unclaimedYen(), unclaimed) コントラクトが数えた受け取られていない代金の合計も、記録から数えた額と等しい

円は、以上であることを確かめるassertGeではなく、等しいことを確かめるassertEqで確かめます。
ハンドラは円トークンを直接ファンドへ送る操作を持たないので、ファンドの円はファンドの関数でしか動かないためです。
申込を約定した時は、口数の価値の円を運用会社へ送り、余りの円を投資家へ返します。
どちらも同じ取引の中で送り出すので、ファンドの円に残りません。

続けて、口数の不変条件を足します。

    // 持分の発行済みの口数は、投資家の持つ口数と、解約で預かった口数の和と等しい。預かった口数も注文から数え直す
    function invariant_UnitsMatchHolders() public view {
        uint256[] memory days_ = fund.orderDays();
        uint256 held;
        for (uint256 i = 0; i < days_.length; i++) {
            TokenizedFund.Order[] memory orders = fund.ordersOf(days_[i]);
            for (uint256 j = 0; j < orders.length; j++) {
                if (orders[j].kind == TokenizedFund.Kind.Redeem && orders[j].status == TokenizedFund.Status.Pending) {
                    held += orders[j].amount;
                }
            }
        }
        assertEq(fund.totalSupply(), fund.balanceOf(alice) + fund.balanceOf(bob) + held);
        assertEq(fund.balanceOf(address(fund)), held);
        assertEq(fund.heldUnits(), held);
    }
行 意味
Kind.Redeem && Status.Pending 約定の前の解約の注文の口数だけを足す。
取り消した解約の口数は投資家へ戻り、約定した解約の口数は消えている
fund.totalSupply() 発行済みの口数が、投資家2人の口数と預かった口数の和と等しい
fund.balanceOf(address(fund)) ファンドのコントラクトが持つ口数が、預かった口数と等しい
fund.heldUnits() コントラクトが数えた預かった口数の合計も、記録から数えた口数と等しい

最後に、狙った操作が通った回数を出す関数を足して、テストのコントラクトを閉じます。

    // 狙った操作が通った回数を、-vvの出力に残す
    function afterInvariant() external view {
        string[7] memory actions = ["subscribe", "redeem", "cancel", "setNav", "settle", "fundProceeds", "claim"];
        for (uint256 i = 0; i < actions.length; i++) {
            console.log(actions[i], handler.calls(keccak256(bytes(actions[i]))));
        }
    }
}

Foundryは、1つの並びを呼び終えるたびにafterInvariantを呼びます。
console.logで書いた値は、forge testに-vvを付けると出ます。
出るのは最後の並びの回数で、ハンドラのcallsから7つの操作の通った回数を読みます。

starter/contracts/foundry.tomlの末尾に、[invariant]のセクションを足します。

[invariant]
runs = 64
depth = 128
fail_on_revert = false
show_metrics = true
行 意味
runs 操作の並びを作り直す回数。
並びごとにsetUpの直後の状態から始める
depth 1つの並びでハンドラを呼ぶ回数
fail_on_revert ハンドラの呼び出しが断られても、テストを失敗にせずに続ける
show_metrics ハンドラの関数ごとに、呼んだ回数と断られた回数の表を出す

開発環境のFoundry 1.5.1の既定はruns = 256とdepth = 500で、fail_on_revertとshow_metricsは書いた値と同じです。
既定と同じ2つも、Foundryの版で既定が変わってもテストの意味が変わらないように書いておきます。
ハンドラは断られる操作を飛ばしますが、まれに断られる操作が残るので、fail_on_revert = falseにします。

解約の代金を受け取るまで進むには、1つの並びの中で次の操作がこの順に選ばれる必要があります。

順 選ばれる操作
1 subscribeで申し込む
2 warpで、申込の約定日の15時を過ぎる
3 settleで純資産を入れて約定し、口数を受け取る。
注文が5件より多ければ何度か選ばれる
4 redeemで解約する
5 warpで、解約の約定日の15時を過ぎる
6 settleで解約を約定し終える
7 fundProceedsで代金を入れる
8 warpを何度か選び、受渡日の0時を過ぎる
9 claimで受け取る

warpは1回で30時間までしか進まないので、受渡日まで進むには何度も選ばれる必要があります。
ハンドラの関数は7つあり、Foundryはどれかを毎回選び直します。
試しにdepthを32にして実行すると、64回の並びのどれでもclaimは1回も通りませんでした。
128回呼ぶと、64回の並びのうち6割ほどで受け取りまで進みました。

確かめる

starter/contractsのディレクトリで、円の不変条件のテストを-vvを付けて実行します。

forge test --mt invariant_FundYenMatchesOrders -vv

次のように、64回の並びで8,192回呼んだ後も性質が保たれたことが出ます。
[PASS]の行の下にはハンドラの関数ごとの表が出て、Logs:の下にはafterInvariantが出した回数が出ます。

[PASS] invariant_FundYenMatchesOrders() (runs: 64, calls: 8192, reverts: 0)

╭-------------+--------------+-------+---------+----------╮
| Contract    | Selector     | Calls | Reverts | Discards |
+=========================================================+
| FundHandler | cancel       | 1185  | 0       | 0        |
|-------------+--------------+-------+---------+----------|
| FundHandler | claim        | 1173  | 0       | 0        |
|-------------+--------------+-------+---------+----------|
| FundHandler | fundProceeds | 1119  | 0       | 0        |
|-------------+--------------+-------+---------+----------|
| FundHandler | redeem       | 1189  | 0       | 0        |
|-------------+--------------+-------+---------+----------|
| FundHandler | settle       | 1170  | 0       | 0        |
|-------------+--------------+-------+---------+----------|
| FundHandler | subscribe    | 1179  | 0       | 0        |
|-------------+--------------+-------+---------+----------|
| FundHandler | warp         | 1177  | 0       | 0        |
╰-------------+--------------+-------+---------+----------╯

Logs:
  subscribe 14
  redeem 13
  cancel 10
  setNav 5
  settle 11
  fundProceeds 5
  claim 1

Suite result: ok. 1 passed; 0 failed; 0 skipped

Foundryは実行するたびに違う並びを作るので、表とLogs:の数は毎回変わります。

表のCallsは、64回の並びでハンドラの関数を呼んだ回数の合計です。
ハンドラが何もせずに戻った回も数えるので、claimの1,173回のほとんどは、受け取れる代金がなく戻った回です。
何もせずに戻った回は断られた回に数えないので、Revertsは0になります。
表だけを見ると、受け取りまで進んだのかが分かりません。

Logs:の数は、最後の並びの128回の呼び出しで、ファンドの関数まで通った回数です。
上の出力ではclaimが1回とfundProceedsが5回通り、代金を受け取った後の状態でも円の性質を確かめられています。
claimが0の時は、その並びでは受け取りまで進んでいません。
何度か実行して、claimが1以上になる並びがあることを確かめます。

実行によっては、settleのRevertsが0でない数になります。
発行済みの口数が1口だけの日に、ハンドラの出す純資産の総額が1円未満に切り捨てられて0円になり、setNavがZeroNavで断るためです。
ファンドのコントラクトの誤りではないので、fail_on_revert = falseで続けます。

性質が崩れた時の表示も見ておきます。
TokenizedFund.solのcancelで、申込を取り消した時のpendingYen -= order.amount;とjpy.transfer(msg.sender, order.amount * YEN);の2行を消して実行します。

[FAIL: assertion failed: 224653000000000000000000 != 224648000000000000000000]
	[Sequence] (original: 7, shrunk: 2)

左がファンドのコントラクトの円で、右が記録から数えた和です。
差の5円が、取り消したのに戻らなかった申込の円です。
Foundryは崩れた並びを短く縮めてから出し、この時は5円のsubscribeとその注文のcancelの2回に縮まりました。

試しに、残高をpendingYenとunclaimedYenの和とだけ比べる不変条件を足して同じ誤りで実行すると、[PASS]で通ってしまいます。
円を戻さない誤りとpendingYenを減らさない誤りが重なると、残高とコントラクトの合計は合ったままだからです。
注文の記録から数え直すと、取り消しになった注文の円がコントラクトに残っていることが分かります。
試したら行を戻しておきます。

forge testで全てのテストを実行すると、口数の不変条件と合わせて26個のテストが全て通ります。
次のレッスンで、運用会社のページから純資産を入れて約定し、代金を入れる画面を作ります。