HandsOnChain

追加担保の請求の画面を作る

作るもの

このレッスンを終えると、担保維持率が110%を下回った借り手に、貸し手のページの借り手の表から追加担保の請求を記録できます。
請求を受けた借り手のページには、一番上に黄色の知らせが出ます。
知らせには猶予の終わりの日付が入り、110%以上に戻ると「解消を記録する」のボタンが出ます。
借り手のページと貸し手の表には、借り手ごとの状態の札も出ます。
ヘッダーの下の帯には「猶予の終わりへ進める」が加わり、3日を待たずにチェーンの時刻を猶予の終わりの後へ進められます。

背景

担保ローンの貸し手は、借り手ごとの担保維持率を毎日見て、下回った借り手へ連絡します。
借り手は連絡を受けて、いつまでに何をすればよいかを知ります。
この画面では、貸し手の見る表と借り手の受け取る知らせを、同じチェーンの値から出します。

画面の操作 ページ 呼ぶ関数 呼べる人
請求する 貸し手 markCall 誰でも
解消を記録する 借り手 cure 誰でも
猶予の終わりへ進める ヘッダーの下の帯 anvilの時刻を進めるevm_setNextBlockTimestampとevm_mine ローカルノードだけ

コントラクトは、担保維持率が下がっても自分では動きません。
誰かがmarkCallの取引を送った時に初めて、請求の時刻がチェーンに残ります。
そこで貸し手の表には、まだ請求を記録していない借り手に「請求できる」の札と「請求する」のボタンを出します。
画面はボタンを押せる時だけ出しますが、記録してよいかを最後に決めるのはコントラクトです。

借り手のページの知らせは、ローンのコントラクトのcalledAtを読んで出します。
貸し手の銀行がメールで知らせなくても、借り手は自分のページで請求と猶予の終わりを確かめられます。
貸し手の表と借り手の知らせは同じ値を読むので、猶予の終わりの日付が食い違うことはありません。

貸し手の表から請求し、借り手が解消を記録する
チェーンに残る値担保維持率107.1%112.5%請求なし2026-01-15なし貸し手のページ借り手の表ローンのコントラクトSecuritiesLoan借り手のページ借り手A11223344markCall(借り手A)markCall(借り手A)calledAtcalledAtcure(借り手A)

実装

まず、starter/app/src/components/use-loan.tsで、借り手ごとに請求の時刻と猶予の終わりを持たせます。
LoanPositionの型の末尾に、2つを足します。

  // 担保維持率 (1万分率)。借りていない時と価格を読めない間は undefined
  ratioBps: bigint | undefined;
  calledAt: bigint;
  // 猶予の終わり。請求のない時は0
  graceEnd: bigint;
};

positionOfが返すRawPositionの型にも、コントラクトのPositionと同じcalledAtを足します。

type RawPosition = {
  units: bigint;
  principal: bigint;
  borrowed: boolean;
  interestFrom: bigint;
  calledAt: bigint;
};

借り手ごとの値を組むpositionOfで、請求の時刻を読み、猶予の終わりを数えます。

    const value = priceNow === undefined ? undefined : units * priceNow;
    const calledAt = raw?.calledAt ?? 0n;
      ratioBps: value !== undefined && debt > 0n ? (value * 10_000n) / debt : undefined,
      calledAt,
      graceEnd: calledAt > 0n ? calledAt + 3n * 86_400n : 0n,
    };
コード 意味
raw?.calledAt ?? 0n positionOfで読んだ請求の時刻。
読めるまでの間は、請求のない0にしておく
calledAt + 3n * 86_400n 猶予の終わり。
コントラクトのgraceEndと同じく、請求の時刻に3日の秒数を足す
calledAt > 0n ? ... : 0n 請求のない時は0にする。
コントラクトのgraceEndと同じ値になる

猶予の終わりは、コントラクトのgraceEndを借り手ごとに読んでも出せます。
画面は既にpositionOfでcalledAtを読んでいるので、読む回数を増やさずに同じ式で数えます。

starter/app/src/lib/format.tsのreasonsの末尾に、請求と解消を拒んだ時の理由の文を足します。

  StalePrice: "最後の価格から3日を過ぎています。評価会社が価格を入れ直すまで待ってください",
  AlreadyCalled: "この借り手には、もう追加担保を請求しています",
  NotBelowCallLevel: "担保維持率が110%以上なので、請求できません",
  NotCalled: "この借り手には請求がありません",
  StillBelowCallLevel: "担保維持率が110%に戻っていないので、まだ解消できません",
};

次に、借り手の状態の札を決めるファイルをstarter/app/src/components/loan-status.tsに作ります。

import type { Tone } from "./ui";
import type { LoanPosition } from "./use-loan";

// 担保維持率の境目 (1万分率)。コントラクトの CALL_BPS と同じ値
const CALL_BPS = 11_000n;

export type LoanStatus = {
  label: string;
  tone: Tone;
};

// 借り手の担保と借入から、画面に出す状態を決める。請求を記録した後は、猶予の終わりを過ぎたかも見る
export function statusOf(position: LoanPosition, now: bigint): LoanStatus {
  const ratio = position.ratioBps;
  if (position.debt === 0n) return { label: position.units > 0n ? "借りる前" : "借入なし", tone: "plain" };
  if (position.calledAt > 0n && now > position.graceEnd) return { label: "猶予を過ぎた", tone: "bad" };
  if (position.calledAt > 0n) return { label: "追加担保の請求中", tone: "warn" };
  if (ratio !== undefined && ratio < CALL_BPS) return { label: "請求できる", tone: "warn" };
  return { label: "正常", tone: "good" };
}
札 出す時
借りる前 担保を預けたが、まだ借りていない
借入なし 担保も借金もない。
全て返して担保が戻った後もこの札になる
猶予を過ぎた 請求の時刻が残ったまま、猶予の終わりを過ぎた
追加担保の請求中 請求の時刻が残っていて、猶予の終わりの前。
110%以上に戻っても、解消を記録するまではこの札のまま
請求できる 110%を下回ったが、まだ誰も請求を記録していない
正常 110%以上で、請求もない

CALL_BPSは、コントラクトのCALL_BPSと同じ110%を1万分率で持ちます。
札は上の行から順に調べ、最初に当てはまった札を返します。
請求の時刻が残っている借り手は、担保維持率に関わらず「猶予を過ぎた」か「追加担保の請求中」になります。
どちらになるかは、チェーンの今の時刻のnowと猶予の終わりを比べて決めます。
猶予の終わりちょうどはまだ猶予の中なので、now > position.graceEndで過ぎたかを見ます。
猶予を過ぎた担保をどうするかは、次の節で作ります。

続けて、借り手のページのstarter/app/src/components/borrower-view.tsxを書き換えます。
頭のimportに、札を決める関数と、札と文を分ける部品を足します。

import { statusOf } from "./loan-status";
import { NotDeployed } from "./not-deployed";
import { useSession } from "./session";
import { Amount, Badge, Card, Field, NoticeLine, lines } from "./ui";

interestDaysの下で、この借り手の札を決めます。

  const interestDays = position && position.principal > 0n && now > position.interestFrom ? (now - position.interestFrom) / 86_400n : 0n;
  const status = position ? statusOf(position, now) : undefined;

ページの一番上に、請求の知らせを置きます。
知らせの色は、雛形のglobals.cssのbanner-warnが最初から持っています。

    <div className="stack">
      {position.calledAt > 0n ? (
        <div className="banner-warn" role="alert">
          <span>
            {lines(
              `担保維持率が110%を下回ったため、追加担保を求められています。${formatDate(position.graceEnd)}までに担保を足すか一部を返してください。過ぎると担保が処分されます。`,
            )}
          </span>
          {position.ratioBps !== undefined && position.ratioBps >= 11_000n ? (
            <button
              type="button"
              className="button button-small"
              disabled={pending !== undefined}
              onClick={() => send("cure", "追加担保の請求を解消しました", [{ ...loan, functionName: "cure", args: [me] }])}
            >
              {pending === "cure" ? "記録しています" : "解消を記録する"}
            </button>
          ) : null}
        </div>
      ) : null}
      <div className="hero">
コード 意味
position.calledAt > 0n 請求の時刻が残っている間だけ知らせを出す。
解消を記録するか全て返すと消える
lines(...) 知らせの3つの文を、1文ごとに行を分けて出す
formatDate(position.graceEnd) 猶予の終わりを、日本時間の日付で出す
position.ratioBps >= 11_000n 110%以上に戻った時だけ「解消を記録する」を出す。
コントラクトのcureが拒む線と同じ
args: [me] 解消するのは、ページを開いているこの借り手の請求

担保維持率の下には、状態の札の行を足します。

          <li>
            <span>担保維持率</span>
            <span className="mono">{formatRatio(position.ratioBps)}</span>
          </li>
          <li>
            <span>状態</span>
            {status ? <Badge tone={status.tone}>{status.label}</Badge> : null}
          </li>
        </ul>

貸し手のページのstarter/app/src/components/lender-view.tsxでは、借り手の表に3つの列を足します。
頭のimportに、札を決める関数と札の部品を足します。

import { statusOf } from "./loan-status";
import { NotDeployed } from "./not-deployed";
import { useSession } from "./session";
import { Amount, Badge, Card, Field, NoticeLine } from "./ui";

lentの下で、借り手ごとに札を決めます。

  const lent = loanState.positions.reduce((sum, position) => sum + position.principal, 0n);
  const now = loanState.now ?? 0n;
  const statuses = loanState.positions.map((position) => ({ position, status: statusOf(position, now) }));

表の見出しの末尾に、状態と猶予の終わりと操作の列を足します。

                <th className="num">担保維持率</th>
                <th>状態</th>
                <th>猶予の終わり</th>
                <th aria-label="操作" />
              </tr>

行を作るloanState.positions.map((position) => (を、札と組にしたstatusesのmapに書き換えます。

              {statuses.map(({ position, status }) => (

担保維持率の列の後に、3つの列の中身を足します。

                  <td className="num">{formatRatio(position.ratioBps)}</td>
                  <td>
                    <Badge tone={status.tone}>{status.label}</Badge>
                  </td>
                  <td>{position.calledAt > 0n ? formatDate(position.graceEnd) : "-"}</td>
                  <td className="num">
                    {status.label === "請求できる" ? (
                      <button
                        type="button"
                        className="button button-small"
                        disabled={pending !== undefined}
                        onClick={() =>
                          send(`call-${position.address}`, "追加担保の請求を記録しました", [{ ...loan, functionName: "markCall", args: [position.address] }])
                        }
                      >
                        {pending === `call-${position.address}` ? "記録しています" : "請求する"}
                      </button>
                    ) : null}
                  </td>
                </tr>

借り手のいない時の行は、列が9つになったのでcolSpanを9にします。

                  <td colSpan={9} className="muted">
コード 意味
status.label === "請求できる" まだ請求していない借り手が110%を下回った時だけ「請求する」を出す
args: [position.address] その行の借り手に請求を記録する。
押した人が借り手でも貸し手でもなくても、コントラクトは受け付ける
`call-${position.address}` 送っている間の印を借り手ごとに分け、押した行のボタンだけを「記録しています」にする
formatDate(position.graceEnd) 請求のある借り手だけ猶予の終わりを出し、ほかの借り手は-にする

最後に、ヘッダーの下の帯に「猶予の終わりへ進める」を足します。
starter/app/src/lib/band.tsのBandStateに猶予の終わりを足します。

export type BandState = {
  // 社債1口の今の価格 (円)
  price: number;
  // 請求の猶予の終わり。請求のない時は0
  graceEnd: number;
};

bandButtonsが返すボタンの末尾に、時刻のボタンを足します。

    { label: "価格を5%上げる", price: Math.floor((state.price * 105) / 100) },
    // 猶予の終わりちょうどはまだ処分できないので、その1秒後へ進める
    { label: "猶予の終わりへ進める", time: state.graceEnd > 0 && now <= state.graceEnd ? state.graceEnd + 1 : null },
  ];
コード 意味
state.graceEnd + 1 猶予の終わりの1秒後へ進める。
後のレッスンの処分は、猶予の終わりを過ぎた時から認める
state.graceEnd > 0 請求のない時は進める先がないので、nullにしてボタンを押せなくする
now <= state.graceEnd もう猶予の終わりを過ぎた時も、進める先がないので押せなくする

starter/app/src/components/use-local-chain.tsには、anvilの時刻を進める関数を足します。
viemから読み込む関数にcreateTestClientを足します。

import { createPublicClient, createTestClient, createWalletClient, http } from "viem";

readerの下に、anvilを操作するクライアントを作ります。

const reader = createPublicClient({ chain: localChain, transport: http() });
// anvil に次のブロックの時刻を決めさせてから1ブロック掘り、チェーンの時刻を進める
const anvil = createTestClient({ mode: "anvil", chain: localChain, transport: http() });

setPriceの後にmoveToを足し、返す値にも加えます。

  function moveTo(time: number) {
    return run(async () => {
      await anvil.setNextBlockTimestamp({ timestamp: BigInt(time) });
      await anvil.mine({ blocks: 1 });
    });
  }

  return { busy, setPrice, moveTo };
}
コード 意味
createTestClient({ mode: "anvil", ... }) anvilだけが持つ、時刻を変える呼び出しを送るクライアント
setNextBlockTimestamp 次に掘るブロックの時刻を決める
mine({ blocks: 1 }) 1ブロックを掘る。
ここでチェーンの時刻が進み、画面が読むblock.timestampも変わる
run(...) 前のレッスンのsetPriceと同じく、送っている間はボタンを押せなくし、終わったら読み直す

starter/app/src/components/band.tsxでは、時刻のボタンを並べます。
価格のボタンの型の下に、時刻のボタンの型を足します。

type PriceButton = Extract<BandButton, { price: number }>;
type TimeButton = Extract<BandButton, { time: number | null }>;

useLocalChainからmoveToも受け取り、借り手の猶予の終わりのうち一番早いものを帯へ渡します。

  const { busy, setPrice, moveTo } = useLocalChain();

  const now = Number(loan.now ?? 0n);
  // 猶予の終わりは、まだ来ていない請求のうち一番早いもの
  const graceEnd = loan.positions
    .map((position) => Number(position.graceEnd))
    .filter((time) => time > 0 && time >= now)
    .sort((a, b) => a - b)[0];
  const state = {
    price: Number(loan.price ?? 0n),
    graceEnd: graceEnd ?? 0,
  };

priceButtonsの下で時刻のボタンを分け、価格のボタンの後に並べます。

  const timeButtons = buttons.filter((button): button is TimeButton => "time" in button);
          {timeButtons.map((button) => (
            <button
              key={button.label}
              type="button"
              className="button button-small"
              disabled={button.time === null || busy}
              title={button.time === null ? undefined : `${formatDate(button.time)}へ進めます`}
              onClick={() => button.time !== null && moveTo(button.time)}
            >
              {button.label}
            </button>
          ))}
コード 意味
.filter((time) => time > 0 && time >= now) 請求のない借り手と、もう猶予の終わりを過ぎた借り手を除く
.sort((a, b) => a - b)[0] 残った猶予の終わりのうち、一番早いものを選ぶ
button.time === null 進める先がない時は押せなくする
title ボタンに重ねると、進める先の日付が出る
借り手の状態の札を上から順に決める
ないある過ぎたまだ110%以上始まり終わり借り手の担保と借入借金がある?請求の時刻がある?110%を下回る?請求できる借りる前か借入なし猶予の終わりを過ぎた?正常猶予を過ぎた追加担保の請求中11223344あるあるあるないないない下回る

確かめる

starter/appのディレクトリで動いているpnpm devを止め、もう一度実行します。
anvilが空の状態から立ち上がり、コントラクトのデプロイと社債の受け渡しが済むと、チェーンの日付は2026-01-15になります。
ブラウザでポート3403の画面を開きます。

まず、借り手Aに借りさせます。
ヘッダーの「貸し手」のページへ移り、右上のアカウントを「銀行」に切り替えます。
「円を入れる」の枠の入れる額に1000000を入れて「入れる」を押すと、「1,000,000円を入れました」と出ます。
「借り手」のページへ戻って「借り手A」に切り替え、「担保を預ける」の枠で10口を預けます。
「借りる」の枠の借りる額に800000を入れて「借りる」を押すと、掛け目いっぱいの800,000円を借りられます。
担保維持率は125.0%になり、状態の札は「正常」です。

ヘッダーの下の帯の「価格を5%下げる」を3回押します。

押した回 社債1口の価格 担保維持率
1回目 95,000円 118.7%
2回目 90,250円 112.8%
3回目 85,737円 107.1%

価格は1回ごとに今の価格の95%になり、1円未満は切り捨てます。
110%を下回ったところで、状態の札が「請求できる」に変わります。

「貸し手」のページへ移ると、借り手の表の借り手Aの行に「請求できる」の札と「請求する」のボタンが出ています。
「請求する」を押すと「追加担保の請求を記録しました」と出て、札は「追加担保の請求中」に変わります。
猶予の終わりの列には、請求の日の3日後の2026-01-18が出ます。

担保維持率が107.1%に下がった借り手Aに、貸し手のページから追加担保の請求を記録したところ
担保維持率が107.1%に下がった借り手Aに、貸し手のページから追加担保の請求を記録したところ

「借り手」のページへ戻って「借り手A」に切り替えると、一番上に黄色の知らせが出ています。
知らせには「2026-01-18までに担保を足すか一部を返してください。」と、猶予の終わりの日付が入ります。
この時はまだ107.1%なので、「解消を記録する」のボタンはありません。

帯の「価格を5%上げる」を1回押すと、価格は90,023円に戻り、担保維持率は112.5%になります。
110%以上に戻ったので、知らせの右に「解消を記録する」が出ます。

請求を受けた借り手Aのページで、価格が戻って「解消を記録する」が出たところ
請求を受けた借り手Aのページで、価格が戻って「解消を記録する」が出たところ

「解消を記録する」を押すと「追加担保の請求を解消しました」と出て、知らせは消え、札は「正常」に戻ります。
価格を戻す代わりに「返す」の枠で100000円を返しても、担保維持率は122.4%に戻るので、同じように解消を記録できます。

最後に、猶予の終わりへ進めるボタンを試します。
もう一度「価格を5%下げる」を押して110%を下回らせ、貸し手のページで「請求する」を押します。
続けて帯の「猶予の終わりへ進める」を押します。
チェーンの時刻が猶予の終わりの1秒後へ進み、借り手Aの札は「猶予を過ぎた」に変わります。
最後に価格を入れてから3日を過ぎたので、帯の価格の横には「3日を過ぎた価格」の札も出ます。
請求の時刻が残ったままなので、猶予の終わりの列は変わりません。

請求から3日の猶予の終わりを過ぎ、借り手Aの札が「猶予を過ぎた」に変わったところ
請求から3日の猶予の終わりを過ぎ、借り手Aの札が「猶予を過ぎた」に変わったところ

猶予を過ぎて110%を下回ったままの借り手の担保をどうするかは、次の節で作ります。