HandsOnChain

担保と円の釣り合いをテストで守る

作るもの

このレッスンを終えると、担保と借入と処分の操作をどの順で行っても崩れない2つの性質を、Foundryのinvariantテストで確かめられます。
1つは、ローンのコントラクトが持つ社債の口数が、借り手の担保の和と等しいことです。
もう1つは、ローンのコントラクトが持つ円が、帳簿から数えた額と等しいことです。
Foundryは借り手3人と評価会社の操作を、順と引数を変えながら呼び、呼ぶたびにこの2つを確かめます。

背景

ローンのコントラクトは、借り手から預かった担保の社債と、貸し手が入れた円を持っています。
社債の口数は、借り手ごとに記録した担保の口数を足すと必ず一致します。
一致しない時は、預かる時か返す時か処分の時に、口数を数え違えたことになります。

円は、4つの帳簿の値から数えられます。

帳簿の値 増える時 ローンの円
funded 貸し手がfundで円を入れた 増える
lent 借り手がborrowで借りた 減る
repaid 借り手がrepayで利息と元本を返した 増える
recovered 処分で買い手が払い、利息と元本に充てた 増える

処分で借り手へ返した余りは、ローンの円に残らないのでrecoveredに数えません。
持っている円が帳簿と合わない時は、貸せる円を表すcashもずれ、貸し手が入れた以上の円を貸してしまうかもしれません。

性質 崩れた時に起きること
社債の口数が借り手の担保の和と等しい 全て返した借り手へ担保を戻せないか、処分で買い手へ渡す社債が足りない
ローンの円が帳簿から数えた額と等しい 貸せる円を多く数えて貸し過ぎるか、返された円や処分で受け取った円を貸せないまま残す

この節までに、時刻と価格で振る舞いが変わる操作が増えました。
利息は日数で増え、評価会社の価格は3日を過ぎると使えなくなり、請求から3日を過ぎると処分できるようになります。
決めた例を試すテストだけでは、操作の並びと時刻と価格の組み合わせを確かめ切れません。
そこで、Foundryが操作の順と引数を作り、ハンドラが範囲を整えて呼ぶinvariantテストで2つの性質を確かめます。

Foundryが操作を選び、呼ぶたびに帳簿を確かめる
チェーンに残る値入れた円1,000,000円貸した元本0円600,000円ローンの円1,000,000円400,000円Foundry操作と引数を選ぶLoanHandler引数を範囲に収めるローンのコントラクトSecuritiesLoan2つの不変条件invariant_で始まる関数11223344borrow(who, amount)borrow(who, amount)borrow(600,000)borrow(600,000)社債と円が帳簿と合う?400,001円から800,000円の間に収める400,001円から800,000円の間に収める

円の不変条件は、入れた円に返された額と処分で受け取った額を足してから、貸した元本を引いて数えます。
入れた円から先に貸した元本を引くと、返された円をまた貸した時に負の数になるためです。

返された円をまた貸すと、貸した元本の和が入れた円を超える
チェーンに残る値入れた円1,000,000円貸した元本の和0円800,000円1,600,000円返された額0円800,000円ローンの円1,000,000円200,000円1,000,000円200,000円銀行貸し手ローンのコントラクトSecuritiesLoan借り手A10口を預けた借り手B10口を預けた11223344fund(1,000,000)fund(1,000,000)800,000 HJPY800,000 HJPY800,000 HJPY800,000 HJPY800,000 HJPY

Solidityのuint256は負の数を持てないので、1,000,000 - 1,600,000を数えた所でpanic: arithmetic underflow or overflow (0x11)で止まります。
1,000,000 + 800,000 - 1,600,000と先に足してから引けば、途中の値も負にならずに200,000円が出ます。
ローンのコントラクトのcashも、同じ順にfunded + repaid + recovered - lentと書いています。

実装

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

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

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

import {BondToken} from "@handsonchain/digital-bond-contracts/contracts/BondToken.sol";
import {CollateralPrice} from "../contracts/CollateralPrice.sol";
import {SecuritiesLoan} from "../contracts/SecuritiesLoan.sol";
import {SecuritiesLoanBase} from "./SecuritiesLoan.t.sol";

// fuzzが選んだ順に、借り手3人と評価会社の操作を呼ぶ。断られる操作もそのまま呼び、断られた後の状態も確かめる。
// 価格を読む操作の前には、評価会社が今の価格を入れ直す。入れ直さないと時刻を進めた後の操作が古い価格で断られてばかりになる
contract LoanHandler is Test {
    SecuritiesLoan internal loan;
    BondToken internal bond;
    CollateralPrice internal price;
    address internal valuer;
    address[3] internal actors;

    constructor(SecuritiesLoan loan_, CollateralPrice price_, address valuer_, address[3] memory actors_) {
        loan = loan_;
        bond = loan_.bond();
        price = price_;
        valuer = valuer_;
        actors = actors_;
    }
行 意味
import {BondToken} ... 2作目の社債トークンを、pnpmのワークスペースから読み込む
SecuritiesLoanBase SecuritiesLoan.t.solの社債の条件と、社債を10口ずつ持つ3人の借り手をそのまま使う
valuer 評価会社のアカウント。
価格を入れる操作は、このアカウントの名義で呼ぶ
actors 借り手3人。
どの操作も、Foundryが入れた数を3で割った余りで1人を選ぶ
loan_.bond() ローンのコントラクトが担保に取る社債トークンを読む

次に、担保と借入と価格と時刻の操作を足します。

    function pledge(uint256 who, uint256 units) external {
        address actor = actors[who % 3];
        uint256 held = bond.balanceOf(actor);
        if (held == 0) return;
        vm.prank(actor);
        loan.pledge(bound(units, 1, held));
    }

    function borrow(uint256 who, uint256 amount) external {
        address actor = actors[who % 3];
        _refreshPrice();
        uint256 limit = loan.borrowLimit(actor);
        uint256 most = limit < loan.cash() ? limit : loan.cash();
        if (most == 0) return;
        vm.prank(actor);
        // 枠の半分より多く借り、価格が少し下がれば請求と処分に届くようにする
        loan.borrow(bound(amount, most / 2 + 1, most));
    }

    function setPrice(uint256 price_) external {
        // 最初の価格100,000円の4割から1.5倍までで動かし、担保維持率を110%と100%の両側へ振る
        price_ = bound(price_, 40_000, 150_000);
        vm.prank(valuer);
        price.setPrice(price_);
    }

    function warp(uint256 seconds_) external {
        vm.warp(block.timestamp + bound(seconds_, 1, 3 days));
    }
行 意味
bound(units, 1, held) 預ける口数を、1口から持っている口数の間に収める
if (held == 0) return 社債を全て預けた借り手は、何もせずに戻る
limit < loan.cash() ? limit : loan.cash() 借りる額の上限を、借入枠と貸し手が貸せる残りの小さい方にする
bound(amount, most / 2 + 1, most) 借りる額を、上限の半分より多く上限までの間に収める
bound(price_, 40_000, 150_000) 評価会社の価格を40,000円から150,000円の間で動かす
bound(seconds_, 1, 3 days) 時刻を1秒から3日の間で進める。
何度か選ばれると、利息の日数と猶予の終わりと価格の古さをまたぐ

boundは、Foundryが入れた値を決めた範囲に収める関数です。
収める範囲は、請求と処分まで進む並びが増えるように決めます。

Foundryが作る数は、0や1のような小さい値と、型の最大の値に寄ります。
借りる額を1円から上限の間に収めるだけでは、数円だけ借りる並びが多くなります。
数円の借金に対して担保の評価額は数十万円あるので、担保維持率は110%からはるかに遠く、価格をどう動かしても請求と処分に届きません。
上限の半分より多く借りると、借りた時の担保維持率は125%以上250%未満に入ります。
掛け目80%の上限まで借りた時が125%で、上限の半分の時が250%です。

価格の範囲も同じ考えで決めます。
1口100,000円の時に125%で借りた借り手は、88,000円で110%を、80,000円で100%を下回ります。
250%近くで借りた借り手も、44,000円まで下がれば110%を下回ります。
下の端を40,000円にすると、どの借り手も請求できる所まで価格が下がります。
上の端を150,000円にすると、価格が戻って請求を解消する並びも通ります。
不履行になった社債の0円の価格は、後のレッスンの決めた例のテストで確かめます。

続けて、請求と解消と返済と処分の操作を足します。

    function markCall(uint256 who) external {
        _refreshPrice();
        loan.markCall(_debtor(who));
    }

    function cure(uint256 who) external {
        _refreshPrice();
        loan.cure(_debtor(who));
    }

    function repay(uint256 who, uint256 amount) external {
        address actor = _debtor(who);
        uint256 debt = loan.debtOf(actor);
        if (debt == 0) return;
        vm.prank(actor);
        loan.repay(bound(amount, 1, debt));
    }

    function liquidate(uint256 who, uint256 buyer) external {
        _refreshPrice();
        address borrower = _debtor(who);
        vm.prank(actors[buyer % 3]);
        loan.liquidate(borrower);
    }

markCallとcureは誰でも呼べるので、vm.prankを付けずにハンドラの名義で呼びます。
liquidateは、借り手3人のうち1人を買い手に選んで呼びます。
3人とも円トークンの許可リストに載り、setUpでローンのコントラクトに円と社債を任せてあるので、どの借り手も買い手になれます。
返す額は、1円から元本と利息の合計の間に収めます。

最後に、ハンドラの中で使う2つの関数を足して、ハンドラを閉じます。

    // whoの借り手から順に探し、借りている借り手を返す。誰も借りていなければwhoの借り手を返す
    function _debtor(uint256 who) internal view returns (address) {
        for (uint256 i = 0; i < 3; i++) {
            address actor = actors[(who + i) % 3];
            if (loan.debtOf(actor) > 0) return actor;
        }
        return actors[who % 3];
    }

    function _refreshPrice() internal {
        // 先に読んでおく。引数の中で読むと、その呼び出しが評価会社の名義を使ってしまう
        uint256 current = price.price();
        vm.prank(valuer);
        price.setPrice(current);
    }
}
行 意味
_debtor 借りている借り手を選ぶ。
借りていない借り手への請求と返済と処分は必ず断られるので、断られない並びを増やす
_refreshPrice 評価会社が今の価格をそのまま入れ直す。
時刻を進めた後でも、価格を読む操作がStalePriceで断られない
uint256 current = price.price() 入れ直す価格を、vm.prankの前に読んでおく

vm.prankは、その次に行う外への呼び出し1回だけを、決めたアカウントの名義にします。
vm.prank(valuer); price.setPrice(price.price());と書くと、引数のprice.price()が先に呼ばれ、評価会社の名義はその読み取りに使われます。
続くsetPriceはハンドラの名義になり、AccessControlUnauthorizedAccountで断られます。
そのため、価格を先に読んでからvm.prankを置きます。

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

contract SecuritiesLoanInvariantTest is SecuritiesLoanBase {
    LoanHandler internal handler;

    function setUp() public override {
        super.setUp();
        handler = new LoanHandler(loan, price, valuer, [alice, bob, carol]);
        targetContract(address(handler));
    }

    /// ローンのコントラクトが持つ社債の口数は、借り手の担保の和と等しい
    function invariant_CollateralEqualsPledges() public view {
        uint256 pledged = loan.positionOf(alice).units + loan.positionOf(bob).units + loan.positionOf(carol).units;
        assertEq(bond.balanceOf(address(loan)), pledged);
    }

    /// ローンのコントラクトが持つ円は、入れた円に返された額と処分で受け取った額を足し、貸した元本を引いた額と等しい。
    /// 返された円はまた貸すので、貸した元本の和は入れた円を超えうる。先に足してから引く
    function invariant_LoanCashMatchesLedger() public view {
        uint256 ledger = loan.funded() + loan.repaid() + loan.recovered() - loan.lent();
        assertEq(jpy.balanceOf(address(loan)), ledger * YEN);
        assertEq(loan.cash(), ledger);
    }
}
行 意味
is SecuritiesLoanBase 円トークンと社債トークンと価格とローンのコントラクトをデプロイし、貸し手が1,000,000円を入れた状態から始める
targetContract(address(handler)) Foundryが呼ぶ相手をハンドラだけに絞る
invariant_CollateralEqualsPledges ハンドラを呼ぶたびに、ローンの社債の口数が3人の担保の和と等しいかを確かめる
loan.funded() + loan.repaid() + loan.recovered() - loan.lent() 帳簿から数えた円。
先に足してから引くので、貸した元本の和が入れた円を超えても負にならない
ledger * YEN 帳簿は1円単位の整数で数えるので、円トークンの18桁の単位に直して残高と比べる
assertEq(loan.cash(), ledger) 貸せる円を表すcashも、同じ額になるかを確かめる

円の性質は、以上であることを確かめるassertGeではなく、等しいことを確かめるassertEqで確かめます。
ローンのコントラクトの円は、帳簿に数えた操作でしか動かないためです。
処分で借り手へ返す余りは、受け取った同じ取引の中で送り出すので、ローンの円に残りません。

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

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

runsは操作の並びを作り直す回数で、depthは1つの並びでハンドラを呼ぶ回数です。
猶予を過ぎた担保の処分まで進むには、1つの並びの中で次の操作がこの順に選ばれる必要があります。

順 選ばれる操作
1 pledgeで担保を預ける
2 borrowで借りる
3 setPriceで価格を110%を下回る所まで下げる
4 markCallで請求を記録する
5 warpを2回以上選び、請求から3日を過ぎる。
1回で進めるのは3日までなので、1回では猶予の終わりを越えられない
6 liquidateで処分する

ハンドラの関数は8つあり、Foundryはどれかを毎回選び直します。
1つの並びで32回しか呼ばないと、この順を全て含む並びはまれです。
128回呼ぶと、1回の実行の中で何度か処分まで進みます。

確かめる

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

forge test --match-contract SecuritiesLoanInvariantTest

次のように、2つの性質が8,192回の呼び出しの後も保たれたことが出ます。
[PASS]の行の下には、ハンドラの関数ごとに呼んだ回数と断られた回数の表が出ます。

[PASS] invariant_CollateralEqualsPledges() (runs: 64, calls: 8192, reverts: 3653)
╭-------------+-----------+-------+---------+----------╮
| Contract    | Selector  | Calls | Reverts | Discards |
+======================================================+
| LoanHandler | borrow    | 1049  | 632     | 0        |
|-------------+-----------+-------+---------+----------|
| LoanHandler | cure      | 1022  | 1013    | 0        |
|-------------+-----------+-------+---------+----------|
| LoanHandler | liquidate | 970   | 958     | 0        |
|-------------+-----------+-------+---------+----------|
| LoanHandler | markCall  | 1063  | 1045    | 0        |
|-------------+-----------+-------+---------+----------|
| LoanHandler | pledge    | 1036  | 0       | 0        |
|-------------+-----------+-------+---------+----------|
| LoanHandler | repay     | 1026  | 5       | 0        |
|-------------+-----------+-------+---------+----------|
| LoanHandler | setPrice  | 997   | 0       | 0        |
|-------------+-----------+-------+---------+----------|
| LoanHandler | warp      | 1029  | 0       | 0        |
╰-------------+-----------+-------+---------+----------╯
[PASS] invariant_LoanCashMatchesLedger() (runs: 64, calls: 8192, reverts: 3780)
Suite result: ok. 2 passed; 0 failed; 0 skipped

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

[PASS]が出ても、処分の道を1度も通っていなければ、処分の後の帳簿は確かめられていません。
表のCallsからRevertsを引くと、断られずに通った回数が分かります。
上の表では、liquidateが970回のうち12回通っています。
markCallは1,063回のうち18回、cureは1,022回のうち9回です。
liquidateのCallsとRevertsが同じ数の時は、処分が1回も通っていません。
借りる額と価格の範囲を広げ過ぎたり、depthを小さくしたりすると、こうなります。
借りる額を1円から上限まで、価格を0円から150,000円までにしてdepthを32で試すと、処分は241回のうち1回しか通りませんでした。

性質が崩れた時の表示も見ておきます。
SecuritiesLoan.solのrepayのrepaid += amount;の行を消して実行します。
返された円を帳簿に数えないので、ローンの円が帳簿から数えた額より多くなります。
invariant_LoanCashMatchesLedgerが[FAIL:で始まる行で失敗し、性質が崩れるまでの呼び出しの並びが出ます。
Foundryは並びを短く縮めてから出すので、どの呼び出しで崩れたかを追えます。
試したら行を戻しておきます。

足す順も確かめます。
invariant_LoanCashMatchesLedgerの式をloan.funded() - loan.lent() + loan.repaid() + loan.recovered()に変えて実行します。
借りて返してまた借りる並びで貸した元本の和が入れた円を超え、[FAIL: panic: arithmetic underflow or overflow (0x11)]で失敗します。
ローンのコントラクトに誤りがなくても、不変条件の式の順だけで失敗すると分かります。
試したら、先に足してから引く式に戻しておきます。

forge testで全てのテストを実行すると、27個のテストが全て通ります。
次のレッスンで、処分できる借り手の担保を貸し手のページから買う画面を作ります。