HandsOnChain

口数の履歴を残す

作るもの

このレッスンを終えると、社債トークンは移転のたびに口数を時刻と一緒に残し、過去の時刻に持っていた口数と発行の総数を読めるようになります。
balanceAt(アカウント, 時刻)はその時刻にアカウントが持っていた口数を返し、totalSupplyAt(時刻)はその時刻の発行の総数を返します。
次のレッスンからは、この2つの関数で記録日の口数を読み、利金の額と受け取る人を決めます。

背景

社債の利金は、決まった利払い日に持ち主へ払います。
日本の普通社債の利息は、年2回払いが多くなっています。
日本の社債の多くは振替制度で受け渡します。
振替制度は社債、株式等の振替に関する法律が定める仕組みで、証券保管振替機構(ほふり)の帳簿の記録として社債を受け渡します。

社債は利払い日と利払い日の間にも売り買いされます。
利払い日の当日に誰へ払うかを決めようとすると、その日の売り買いが済むのを待たなければ、受け取る人が決まりません。
そこで、利払い日より前に、受け取る人を決める日を置きます。
このコースではこの日を記録日と呼び、利払い日の5日前に置きます。

記録日に社債を持っていた人は、記録日の後に売っても、その回の利金を受け取ります。
次の図は、投資家Aが記録日の次の日に投資家Bへ4口を売った時に、第1回の利金を誰がいくら受け取るかを示します。

記録日の後に売った時の第1回の利金
第1回の利金投資家A10口分3,960円投資家B12口分4,752円7〜10日7〜10日投資家Aが10口を持つ11〜15日11〜15日投資家Aが6口を持つ7〜10日7〜10日投資家Bが12口を持つ11〜15日11〜15日投資家Bが16口を持つ7日8日10日12日14日16日4口を売る記録日記録日口数が決まる利払い日利払い日利金を払う112233

利払い日に払う額を決めるには、利払い日の時点で、記録日の口数を後からさかのぼって読む必要があります。
ところが、ERC-20のbalanceOfは今の残高だけを返し、過去の残高を残しません。
利払い日にbalanceOfを読むと、投資家Aは売った後の6口になってしまいます。

そこで、口数が変わるたびに、変わった時刻と変わった後の口数の組をコントラクトに積んでおきます。
ほふりの帳簿が受け渡しの記録を残しているのと同じように、社債トークンが自分で口数の履歴を持ちます。
OpenZeppelin ContractsのCheckpointsは、この組を時刻の順に積む配列と、ある時刻の値を探す関数を持ちます。
過去の時点の投票の重みを読むERC20Votesも、同じCheckpointsで履歴を残しています。

関数 何をするか
push(時刻, 値) 時刻と値の組を末尾に積む。
最後の組と同じ時刻なら、その組の値を書き換える
upperLookupRecent(時刻) その時刻と同じか前の組のうち、最も新しい組の値を返す。
組がなければ0を返す

実装

starter/contracts/contracts/BondToken.solを開き、CheckpointsとSafeCastの読み込みを足します。

import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
import {Checkpoints} from "@openzeppelin/contracts/utils/structs/Checkpoints.sol";
import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";

SafeCastは、大きな整数の型を小さな型へ変える時に、収まらない値なら取引を拒む関数をまとめたライブラリです。

コントラクトの頭で、履歴の型にCheckpointsの関数を付けます。

contract BondToken is ERC20, AccessControl {
    using Checkpoints for Checkpoints.Trace208;

利払い日と記録日の並びの後に、口数の履歴を足します。

    uint64[] private _paymentDates;
    uint64[] private _recordDates;

    /// @dev アカウントごとの残高と供給量を、変わった時刻と一緒に積む
    mapping(address account => Checkpoints.Trace208) private _balanceHistory;
    Checkpoints.Trace208 private _supplyHistory;
行 意味
using Checkpoints for Checkpoints.Trace208 _supplyHistory.push(...)のように、履歴の変数からCheckpointsの関数を呼べるようにする
Checkpoints.Trace208 時刻を48ビットの整数で、値を208ビットの整数で持つ組の並び
_balanceHistory アカウントごとの口数の履歴
_supplyHistory 発行の総数の履歴

burnの関数の後に、履歴を読む2つの関数を足します。

    /// @notice ある時刻のアカウントの残高。記録日の持ち主を決める時に使う
    function balanceAt(address account, uint256 time) external view returns (uint256) {
        return _balanceHistory[account].upperLookupRecent(SafeCast.toUint48(time));
    }

    /// @notice ある時刻の供給量
    function totalSupplyAt(uint256 time) external view returns (uint256) {
        return _supplyHistory.upperLookupRecent(SafeCast.toUint48(time));
    }
行 意味
SafeCast.toUint48(time) 履歴の時刻は48ビットで持つため、渡された時刻を48ビットにする。
Unix時刻は48ビットに十分収まる
upperLookupRecent(...) 渡した時刻と同じか前の、最も新しい口数を返す。
まだ口数を持ったことのないアカウントは0になる

記録日の時刻は日本時間の0時なので、balanceAt(アカウント, 記録日)は記録日になった時の口数を返します。
まだ来ていない時刻を渡すと、最も新しい組の値、つまり今の口数を返します。

最後に、残高が動く時に必ず呼ばれる_updateの末尾で、動いた後の口数を履歴に積みます。

    /// @dev 発行と移転と償還は全てここを通るため、名簿の確かめと残高の記録を1か所に置く
    function _update(address from, address to, uint256 value) internal override {
        if (from != address(0)) _checkAccount(from);
        if (to != address(0)) _checkAccount(to);
        super._update(from, to, value);
        uint48 time = SafeCast.toUint48(block.timestamp);
        if (from != address(0)) _balanceHistory[from].push(time, SafeCast.toUint208(balanceOf(from)));
        if (to != address(0)) _balanceHistory[to].push(time, SafeCast.toUint208(balanceOf(to)));
        if (from == address(0) || to == address(0)) _supplyHistory.push(time, SafeCast.toUint208(totalSupply()));
    }
行 意味
super._update(...)の後 ERC-20の本来の処理で残高を動かした後に、動いた後の口数を読んで積む
block.timestamp 今のブロックの時刻。
前のブロックより前に戻らないため、組は必ず時刻の順に積まれる
from != address(0) 発行の時は送り手がいないため、送り手の履歴を積まない。
受け手のtoも同じで、burnの時は積まない
from == address(0)かto == address(0) 発行の時とburnの時だけ総数が変わるので、その時だけ総数の履歴を積む

同じブロックの中で2回移転すると、2回目のpushは同じ時刻の組を書き換えます。
時刻ごとに残るのは、そのブロックを終えた時の口数です。
Checkpointsは、最後の組より前の時刻を積もうとすると取引を拒むため、時刻を取り違えて履歴を壊すこともありません。

starter/contracts/test/DigitalBond.t.solのDigitalBondTestの末尾に、この節のテストを足します。

    // 節3 利払いと記録日

    function test_BalanceAtKeepsHistory() public {
        _mint(alice, 10);
        vm.warp(RECORD_1 + 1 days);
        vm.prank(alice);
        bond.transfer(bob, 4);
        assertEq(bond.balanceAt(alice, RECORD_1), 10);
        assertEq(bond.balanceAt(bob, RECORD_1), 0);
        assertEq(bond.balanceAt(alice, block.timestamp), 6);
        assertEq(bond.totalSupplyAt(RECORD_1), 10);
    }
行 意味
_mint(alice, 10) テストの中で発行の役割を持つminterから、2026-01-01にaliceへ10口を発行する
vm.warp(RECORD_1 + 1 days) チェーンの時刻を第1回の記録日の次の日へ進める
bond.transfer(bob, 4) 記録日の後に、aliceがbobへ4口を移す
balanceAt(alice, RECORD_1) 記録日の口数は、移す前の10口のまま読める
balanceAt(alice, block.timestamp) 今の口数は、移した後の6口になる

確かめる

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

forge test --match-contract DigitalBondTest

次の行が出れば、テストは通っています。

[PASS] test_BalanceAtKeepsHistory()
Suite result: ok. 11 passed; 0 failed; 0 skipped

_updateの_balanceHistory[from].push(...)の行を消して実行すると、test_BalanceAtKeepsHistoryが失敗します。

[FAIL: assertion failed: 10 != 6] test_BalanceAtKeepsHistory()

送り手の履歴を積まないと、aliceの履歴は発行の時の10口で止まります。
今の口数を履歴から読んでも、売った後の6口が出てきません。
確かめたら、消した行を戻しておきます。

次のレッスンで、この履歴から記録日の総数を読み、利払いの総額を計算します。