HandsOnChain

社債と円の釣り合いをテストで守る

作るもの

このレッスンを終えると、申込から償還と不履行までの操作をどの順で行っても崩れない2つの性質を、Foundryのinvariantテストで確かめられます。
1つは、社債トークンの総数が投資家の残高の和と等しいことです。
もう1つは、決済のコントラクトが持つ円が、払うと約束した額を下回らないことです。
Foundryは操作の順と引数を作り変えながら時刻を進め、操作を呼ぶたびにこの2つを確かめます。

背景

社債の帳簿では、投資家ごとに記録した口数を足すと、発行してまだ償還していない口数と必ず一致します。
一致しない時は、どこかで発行か償還の記録を誤ったことになります。

決済のコントラクトは、投資家から預かった申込の円と、発行体から入れてもらった利金と償還の円を持っています。
持っている円が払うと約束した額より少なくなると、最後に受け取りに来た投資家へ払えません。

この節までに、時刻で振る舞いが変わる操作が増えました。
同じ関数でも、締め切りや記録日や満期の前か後かで、通る時と拒まれる時があります。
決めた例を試すテストだけでは、操作の並びと時刻の組み合わせを確かめ切れません。
そこで、Foundryが操作の順と引数を作り、ハンドラが時刻を進めながら呼ぶinvariantテストで2つの性質を確かめます。

性質 崩れた時に起きること
社債の総数が3人の残高の和と等しい 発行かburnを数え違えている。
利金の総額は記録日の総数から出すため、払う額もずれる
決済のコントラクトの円が払う約束の額を下回らない 後から受け取りに来た投資家へ、申込の返金か利金か額面を払えない

実装

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

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

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

import {JpyToken} from "@handsonchain/jpy-stablecoin-contracts/contracts/JpyToken.sol";
import {BondToken} from "../contracts/BondToken.sol";
import {BondSettlement} from "../contracts/BondSettlement.sol";
import {DigitalBondBase} from "./DigitalBond.t.sol";

// fuzzが選んだ順で、申込、締め、利金の入金と受け取り、売買、償還、不履行を呼ぶ。
// 時刻は呼ぶたびに少しずつ進め、記録日と利払い日と満期をまたがせる
contract BondHandler is Test {
    JpyToken internal jpy;
    BondToken internal bond;
    BondSettlement internal settlement;
    address internal issuer;
    address[3] internal investors;
    uint256 internal constant YEN = 1e18;
    uint256 public time;

    constructor(JpyToken jpy_, BondToken bond_, BondSettlement settlement_, address issuer_, address[3] memory investors_) {
        jpy = jpy_;
        bond = bond_;
        settlement = settlement_;
        issuer = issuer_;
        investors = investors_;
        time = block.timestamp;
    }

    // 呼ぶたびに前の呼び出しで進めた時刻へ戻してから操作する
    modifier at() {
        vm.warp(time);
        _;
    }

    function pass(uint256 seconds_) external at {
        time += bound(seconds_, 1 days, 180 days);
    }
行 意味
investors 本人確認を済ませた3人の投資家。
どの操作も、Foundryが入れた数を3で割った余りで1人を選ぶ
time ハンドラが進めた時刻。
呼び出しをまたいで時刻を引き継ぐ
modifier at() どの操作も、初めにvm.warp(time)でtimeの時刻へ戻してから行う
pass 時刻を1日から180日の間で進める。
Foundryがこの関数を何度か選ぶと、記録日や満期をまたぐ

boundは、Foundryが入れた値を決めた範囲に収める関数です。
次に、募集の操作を足します。

    function subscribe(uint256 who, uint256 units) external at {
        address investor = investors[who % 3];
        units = bound(units, 1, 30);
        vm.startPrank(investor);
        jpy.approve(address(settlement), units * bond.faceValue() * YEN);
        settlement.subscribe(units);
        vm.stopPrank();
    }

    function close() external at {
        settlement.close();
    }

    // 締め切りの前なら残りの口数を投資家に申し込ませ、締め切りの後に締めて社債を発行する。
    // 発行した後の利払いと売買と償還を、fuzzが多く通れるようにする
    function issueAll(uint256 who) external at {
        if (settlement.closed() || block.timestamp > settlement.deadline()) return;
        uint256 left = settlement.issueAmount() - settlement.totalSubscribed();
        if (left > 0) {
            vm.startPrank(investors[who % 3]);
            jpy.approve(address(settlement), left * bond.faceValue() * YEN);
            settlement.subscribe(left);
            vm.stopPrank();
        }
        time = settlement.deadline() + 1;
        vm.warp(time);
        settlement.close();
    }

subscribeをばらばらの口数で呼ぶだけでは、申込の和がちょうど30口になることはまれです。
ほとんどの並びが募集不成立で終わり、その後の利払いと売買と償還を通りません。
issueAllは、締め切りの前なら残りの口数を1人の投資家に申し込ませ、締め切りの1秒後へ進めて締めます。
これで、社債を発行した後まで進む並びが増えます。

利払いの操作を足します。

    // 半分の回は足りない分をちょうど入れ、残りの回は1円から20,000円の間で入れる
    function fundCoupon(uint256 n, uint256 amount) external at {
        n = n % 2;
        uint256 gap = settlement.couponDue(n) - _min(settlement.couponFunded(n), settlement.couponDue(n));
        amount = amount % 2 == 0 && gap > 0 ? gap : bound(amount, 1, 20_000) * YEN;
        vm.startPrank(issuer);
        jpy.approve(address(settlement), amount);
        settlement.fundCoupon(n, amount);
        vm.stopPrank();
    }

    // 利払い日の前なら利払い日まで進めてから受け取る
    function claimCoupon(uint256 who, uint256 n) external at {
        n = n % 2;
        _passTo(bond.paymentDate(n));
        vm.prank(investors[who % 3]);
        settlement.claimCoupon(n);
    }
行 意味
n % 2 2回の利払いのどちらかを選ぶ
gap その回の総額のうち、まだ入っていない額
amount % 2 == 0 && gap > 0 ? gap : ... 半分の回は足りない分をちょうど入れる。
残りの回は決めた範囲の額を入れ、総額を超えて返す道と足りないまま残る道を通る
_passTo(bond.paymentDate(n)) 利払い日の前なら、利払い日まで進めてから受け取る

売買の操作を足します。

    function list(uint256 who, uint256 units, uint256 price) external at {
        address seller = investors[who % 3];
        units = bound(units, 1, 30);
        price = bound(price, 90_000, 110_000);
        vm.startPrank(seller);
        bond.approve(address(settlement), units);
        settlement.list(units, price);
        vm.stopPrank();
    }

    function buy(uint256 who, uint256 id) external at {
        uint256 count = settlement.orderCount();
        if (count == 0) return;
        vm.startPrank(investors[who % 3]);
        jpy.approve(address(settlement), type(uint256).max);
        settlement.buy(id % count);
        vm.stopPrank();
    }

listは1口の値段を90,000円から110,000円の間に収めます。
buyはid % countで、これまでに出た注文のどれかを選んで買います。

満期の操作と、ハンドラの中で使う関数を足します。

    // 半分の回は足りない分をちょうど入れ、残りの回は1円から3,000,000円の間で入れる
    function fundRedemption(uint256 amount) external at {
        uint256 gap = settlement.redemptionDue() - _min(settlement.redemptionFunded(), settlement.redemptionDue());
        amount = amount % 2 == 0 && gap > 0 ? gap : bound(amount, 1, 3_000_000) * YEN;
        vm.startPrank(issuer);
        jpy.approve(address(settlement), amount);
        settlement.fundRedemption(amount);
        vm.stopPrank();
    }

    // 満期の前なら満期まで進めてから償還を受ける
    function redeem(uint256 who) external at {
        _passTo(bond.maturity());
        vm.prank(investors[who % 3]);
        settlement.redeem();
    }

    function declareDefault() external at {
        _passTo(bond.maturity());
        settlement.declareDefault();
    }

    function _min(uint256 a, uint256 b) private pure returns (uint256) {
        return a < b ? a : b;
    }

    function _passTo(uint256 date) private {
        if (time < date) {
            time = date;
            vm.warp(time);
        }
    }
}

redeemとdeclareDefaultは、満期の前なら満期まで進めてから呼びます。
_passToは時刻を戻さないので、満期を過ぎた後に利払い日へ戻ることはありません。
償還の額を入れる前にdeclareDefaultが選ばれると不履行になり、入れた後に選ばれるとRedemptionFullyFundedで拒まれます。

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

contract DigitalBondInvariantTest is DigitalBondBase {
    BondHandler internal handler;

    function setUp() public override {
        super.setUp();
        // 1人で残りの全ての口数を申し込めるように、投資家にも円を足す
        vm.startPrank(issuer);
        jpy.issue(issuer, 9_000_000 * YEN, keccak256("issuer-more"));
        jpy.issue(alice, 5_000_000 * YEN, keccak256("alice-more"));
        jpy.issue(bob, 5_000_000 * YEN, keccak256("bob-more"));
        jpy.issue(carol, 5_000_000 * YEN, keccak256("carol-more"));
        vm.stopPrank();
        handler = new BondHandler(jpy, bond, settlement, issuer, [alice, bob, carol]);
        targetContract(address(handler));
    }

    // 社債を持てるのは本人確認を済ませた3人の投資家だけなので、3人の残高の和が供給量になる
    function invariant_BondSupplyEqualsBalances() public view {
        assertEq(bond.balanceOf(alice) + bond.balanceOf(bob) + bond.balanceOf(carol), bond.totalSupply());
    }

    // 決済のコントラクトは、預かった申込と、入れてもらってまだ払っていない利金と償還の額を必ず持っている
    function invariant_SettlementCoversOwedYen() public view {
        uint256 owed = settlement.closed() ? 0 : settlement.totalSubscribed() * FACE * YEN;
        for (uint256 n = 0; n < 2; n++) owed += settlement.couponFunded(n) - settlement.couponPaid(n);
        owed += settlement.redemptionFunded() - settlement.redemptionPaid();
        assertGe(jpy.balanceOf(address(settlement)), owed);
    }
}
行 意味
is DigitalBondBase DigitalBond.t.solの社債の条件と、本人確認を済ませた3人の投資家をそのまま使う
super.setUp() 円トークンと社債トークンと決済のコントラクトをデプロイし、名簿と円を用意する
jpy.issue(...) 1人で30口の全てを申し込めて、発行体が利金と償還の額を何度も入れられるように円を足す
targetContract(address(handler)) Foundryが呼ぶ相手をハンドラだけに絞る
invariant_BondSupplyEqualsBalances ハンドラを呼ぶたびに、3人の残高の和が社債の総数と等しいかを確かめる
invariant_SettlementCoversOwedYen ハンドラを呼ぶたびに、決済のコントラクトの円が払う約束の額以上かを確かめる

DigitalBondBaseのsetUpにはvirtualが付いているので、overrideで上書きして円を足せます。
払う約束の額は、次の3つを足して数えます。

約束の額 数え方
預かった申込 募集を締める前だけ、申込の口数に額面を掛けた額。
締めた後は発行体へ送ったか投資家へ返した
利金 回ごとに、入れてもらった額から払った額を引いた額
償還 入れてもらった額から払った額を引いた額

等しいことを確かめるassertEqではなく、以上であることを確かめるassertGeを使います。
誰かが決済のコントラクトへ円を直接送ると、持っている円は約束の額より多くなりますが、払えなくなるわけではないためです。

ハンドラの呼び出しの多くは、時刻や入金の条件で拒まれます。
拒まれても性質の確認は続けたいので、starter/contracts/foundry.tomlの末尾に[invariant]のセクションを足し、fail_on_revert = falseを書きます。

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

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

確かめる

starter/contractsのディレクトリでinvariantテストを実行します。

forge test --match-contract DigitalBondInvariantTest

次のように、2つの性質が2,048回の呼び出しの後も保たれたことが出ます。

[PASS] invariant_BondSupplyEqualsBalances() (runs: 64, calls: 2048, reverts: 1153)
[PASS] invariant_SettlementCoversOwedYen() (runs: 64, calls: 2048, reverts: 1184)
Suite result: ok. 2 passed; 0 failed; 0 skipped

Foundryは実行するたびに違う並びを作るので、revertsの数は毎回変わります。
[PASS]の行の下には、ハンドラの関数ごとに呼んだ回数と拒まれた回数の表が出ます。
どの関数も同じくらいの回数で呼ばれていることを、表で確かめられます。

性質が崩れた時の表示も見ておきます。
BondSettlement.solのfundRedemptionのredemptionFunded += kept;を、redemptionFunded += amount;に変えて実行します。
総額を超えて発行体へ返した分まで入金済みに数えるため、払う約束の額が持っている円を上回ります。
invariant_SettlementCoversOwedYenが[FAIL: assertion failed:で始まる行で失敗し、性質が崩れるまでの呼び出しの並びが出ます。
Foundryは並びを短く縮めてから出すので、どの呼び出しで崩れたかを追えます。

試したらkeptに戻し、forge testで全てのテストを実行します。
この時点で、26個のテストが全て通ります。
次のレッスンで、償還と不履行をブラウザから行う画面を作ります。