HandsOnChain

担保維持率の画面を作る

作るもの

このレッスンを終えると、借り手のページで担保維持率と利息と返す額の合計を見て、ブラウザから返せます。
担保を預ける枠には、入れた口数を足した後の担保維持率が出ます。
貸し手のページの借り手の表には、借り手ごとの利息と担保維持率の列が加わります。
ローカルノードの時だけ、ヘッダーの下にチェーンの日付と社債1口の価格を出す帯が出ます。
帯の「価格を5%下げる」と「価格を5%上げる」を押すと、評価会社の名義で価格が入り、担保維持率がその場で変わります。

背景

担保維持率は、担保の評価額を元本と利息の合計で割った割合です。
借りた後は、価格が下がるか利息が増えるたびに下がります。
借り手は担保維持率を見て、担保を足すか一部を返すかを決めます。
貸し手は借り手ごとの担保維持率を並べて、下がった借り手を見つけます。

10口を預けて700,000円を借りた借り手Aで、帯の「価格を5%下げる」を押し続けた時の値は次のとおりです。
帯は今の価格に95%を掛け、1円未満を切り捨てた額を入れます。

押した回数 1口の価格 担保の評価額 担保維持率
0回 100,000円 1,000,000円 142.8%
1回 95,000円 950,000円 135.7%
2回 90,250円 902,500円 128.9%
3回 85,737円 857,370円 122.4%
4回 81,450円 814,500円 116.3%
5回 77,377円 773,770円 110.5%
6回 73,508円 735,080円 105.0%

6回押すと110%を下回り、次の節で作る追加担保の請求を受ける状態になります。

価格を下げた時の担保と借入
担保の評価額1000000950000902500773770元本と利息700000借りた直後5%下げるもう1回下げる5回下げる11223344

本物のローンでは、価格を入れるのは評価会社だけです。
ローカルノードには評価会社がいないので、帯のボタンが評価会社の代わりに価格を入れます。
anvilはcontracts/local.jsonのアカウントの鍵を持っているので、画面は評価会社の名義での取引をanvilに頼めます。
Fujiでは評価会社の鍵を画面が持たないので、帯は出しません。

帯のボタンで価格を下げる
画面に出る値1口の価格100,000円95,000円担保維持率142.8%135.7%帯のボタン価格を5%下げるローカルノードanvil価格のコントラクトCollateralPrice借り手のページuseLoan112233setPrice(95,000) を評価会社の名義で頼むsetPrice(95,000) を評価会社の名義で頼むsetPrice(95,000)setPrice(95,000)price()入れた時刻をupdatedAtに残す入れた時刻をupdatedAtに残す

画面は、ローンのコントラクトのratioBpsを呼ばずに、読んだ価格と口数と利息から同じ式で担保維持率を出します。
ratioBpsは価格が3日を過ぎるとStalePriceで拒むため、呼ぶと古い価格の時に担保維持率が出なくなるからです。
古い価格の時は、帯の価格の横に「3日を過ぎた価格」の札を出して知らせます。

実装

まず、starter/app/src/components/use-loan.tsで、利息と担保維持率と価格を使える期限を読めるようにします。
借り手1人の担保と借入を表すLoanPositionの末尾に、4つを足します。

  // 担保の評価額。価格を読めない間は undefined
  value: bigint | undefined;
  interest: bigint;
  interestFrom: bigint;
  debt: bigint;
  // 担保維持率 (1万分率)。借りていない時と価格を読めない間は undefined
  ratioBps: bigint | undefined;
};

コントラクトのpositionOfが返す形のRawPositionにも、利息を数え始める時刻を足します。

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

useNamedReadsに渡すローンと価格の読み取りに、価格を使える長さを足します。

      price: { ...price, functionName: "price" },
      updatedAt: { ...price, functionName: "updatedAt" },
      maxAge: { ...price, functionName: "MAX_AGE" },

借り手ごとの読み取りには、利息を足します。

        [`position:${account}`, { ...loan, functionName: "positionOf", args: [account] }],
        [`interest:${account}`, { ...loan, functionName: "interestOf", args: [account] }],

positionOfの中で、返す額の合計と担保維持率を出します。

    const raw = per[`position:${account}`] as RawPosition | undefined;
    const units = raw?.units ?? 0n;
    const principal = raw?.principal ?? 0n;
    const interest = (per[`interest:${account}`] as bigint | undefined) ?? 0n;
    const debt = principal + interest;
    const value = priceNow === undefined ? undefined : units * priceNow;
    return {
      address: account,
      units,
      principal,
      borrowed: raw?.borrowed ?? false,
      value,
      interest,
      interestFrom: raw?.interestFrom ?? 0n,
      debt,
      ratioBps: value !== undefined && debt > 0n ? (value * 10_000n) / debt : undefined,
    };

最後に、返す値に価格を使える期限を足します。

  const now = block.data?.timestamp;
  const updatedAt = base.updatedAt as bigint | undefined;
  const maxAge = base.maxAge as bigint | undefined;
  return {
    now,
    price: priceNow,
    updatedAt,
    // 価格を使える期限。これを過ぎると借入と請求と処分が断られる
    usableUntil: updatedAt !== undefined && maxAge !== undefined && updatedAt > 0n ? updatedAt + maxAge : undefined,
コード 意味
functionName: "interestOf" 前のレッスンで作った、今払う利息を読む。
4秒ごとに読み直すので、日をまたぐと増える
principal + interest 返す額の合計。
コントラクトのdebtOfと同じ値になる
(value * 10_000n) / debt 担保維持率を1万分率で出す。
コントラクトのratioBpsと同じ式で、割り算は小数点以下を捨てる
debt > 0n 借りていない時は0で割らず、undefinedにする
updatedAt + maxAge 評価会社が最後に価格を入れた時刻に3日を足し、価格を使える期限にする

starter/app/src/lib/format.tsのformatPercentの後に、担保維持率を文字にする関数を足します。

// 担保維持率 (1万分率) を、0.1%未満を切り捨てた 142.6% の形にする。借りていない時は - を返す
export function formatRatio(bps: bigint | undefined): string {
  if (bps === undefined) return "-";
  return `${(Number(bps / 10n) / 10).toFixed(1)}%`;
}

14,285はbps / 10nで1,428になり、10で割って142.8%と出ます。
四捨五入でなく切り捨てるのは、110%をわずかに下回った10,999を110.0%と出さずに、109.9%と出すためです。

同じファイルのreasonsの末尾には、返済と古い価格のエラーの文を足します。

  OverLenderCash: "貸し手が入れた円が足りません",
  NothingToRepay: "返す元本と利息がありません",
  StalePrice: "最後の価格から3日を過ぎています。評価会社が価格を入れ直すまで待ってください",
};

続けて、帯に並べるボタンを決める関数をstarter/app/src/lib/band.tsとして作ります。

// ヘッダーの下の帯に並べるボタンを決める。価格のボタンは今の価格を5%上下させた額を、
// 時刻のボタンは処分できる時刻 (猶予の終わりと返済の期限の1秒後) を持つ。
// ローカルノード (anvil) だけが評価会社の名義で価格を入れて時刻を進められるので、それ以外のチェーンでは何も返さない

export const LOCAL_CHAIN_ID = 31337;

export type BandState = {
  // 社債1口の今の価格 (円)
  price: number;
};

export type BandButton =
  | { label: "価格を5%下げる" | "価格を5%上げる"; price: number }
  // 進める先のUnix時刻。もう進める先がない時は null にし、ボタンを押せなくする
  | { label: "猶予の終わりへ進める" | "返済の期限へ進める"; time: number | null };

export function bandButtons(chainId: number, now: number, state: BandState): BandButton[] {
  if (chainId !== LOCAL_CHAIN_ID) return [];
  return [
    // 1円未満は切り捨てる
    { label: "価格を5%下げる", price: Math.floor((state.price * 95) / 100) },
    { label: "価格を5%上げる", price: Math.floor((state.price * 105) / 100) },
  ];
}
コード 意味
LOCAL_CHAIN_ID anvilのチェーンの番号。
Fujiの43113では空の配列を返し、帯を出さない
Math.floor((state.price * 95) / 100) 今の価格の95%を、1円未満を切り捨てて出す。
100,000円は95,000円になる
time: number | null 時刻を進めるボタンの形。
ボタンそのものは次の節で足す

この関数はReactを使わない、値を受けて値を返すだけの関数です。
画面を開かなくても、Node.jsのテストから呼んで、並ぶボタンと価格を確かめられます。

帯のボタンが評価会社の名義で価格を入れる仕組みは、starter/app/src/components/use-local-chain.tsとして作ります。

"use client";

import { collateralPriceAbi } from "@contracts/generated/abi";
import { useQueryClient } from "@tanstack/react-query";
import { useState } from "react";
import { createPublicClient, createWalletClient, http } from "viem";

import { localChain, valuerAccount } from "@/lib/chains";

import { useSession } from "./session";

// anvil は local.json のアカウントの鍵を持つので、評価会社の名義での送信を頼める
const wallet = createWalletClient({ chain: localChain, transport: http() });
const reader = createPublicClient({ chain: localChain, transport: http() });

// ローカルノードの時だけ、帯のボタンから評価会社の価格を入れ、時刻を進める
export function useLocalChain() {
  const { contracts } = useSession();
  const queryClient = useQueryClient();
  const [busy, setBusy] = useState(false);

  async function run(task: () => Promise<void>) {
    setBusy(true);
    try {
      await task();
      await queryClient.invalidateQueries();
    } finally {
      setBusy(false);
    }
  }

  // 今どのアカウントを選んでいても、評価会社の名義で社債1口の価格を入れる
  function setPrice(price: number) {
    return run(async () => {
      if (!contracts.price || !valuerAccount) return;
      const hash = await wallet.writeContract({
        address: contracts.price,
        abi: collateralPriceAbi,
        functionName: "setPrice",
        args: [BigInt(price)],
        account: valuerAccount.address,
      });
      await reader.waitForTransactionReceipt({ hash });
    });
  }

  return { busy, setPrice };
}
コード 意味
createWalletClient({ chain: localChain, transport: http() }) 鍵を持たずに、anvilへ取引を頼むクライアントを作る
account: valuerAccount.address 鍵でなくアドレスだけを渡すと、viemは署名をanvilに頼む。
anvilは評価会社の鍵で署名する
waitForTransactionReceipt 取引がブロックに入るまで待つ
queryClient.invalidateQueries() 画面の読み取りを全て読み直す。
4秒を待たずに新しい価格が出る
busy 送っている間はtrueにし、帯のボタンを押せなくする

帯そのものは、starter/app/src/components/band.tsxとして作ります。
帯の色と並びは、雛形のglobals.cssのtime-bandが最初から持っています。

"use client";

import { bandButtons, type BandButton } from "@/lib/band";
import { formatDate, formatWholeYen } from "@/lib/format";

import { useSession } from "./session";
import { Badge } from "./ui";
import { useLoan } from "./use-loan";
import { useLocalChain } from "./use-local-chain";

type PriceButton = Extract<BandButton, { price: number }>;

// ローカルノードの時だけ、ヘッダーの下に出す価格と時刻の帯。評価会社を待たずに価格を上下させ、猶予や期限を待たずに試せる
export function Band() {
  const { chainId, contracts } = useSession();
  const loan = useLoan();
  const { busy, setPrice } = useLocalChain();

  const now = Number(loan.now ?? 0n);
  const state = {
    price: Number(loan.price ?? 0n),
  };
  const buttons = contracts.loan && loan.now !== undefined && loan.price !== undefined ? bandButtons(chainId, now, state) : [];
  if (buttons.length === 0) return null;
  const priceButtons = buttons.filter((button): button is PriceButton => "price" in button);
  const stale = loan.usableUntil !== undefined && loan.now !== undefined && loan.now > loan.usableUntil;

  return (
    <div className="time-band">
      <div className="time-band-inner">
        <div className="time-band-meta">
          <p className="time-band-date">
            チェーンの日付 <time>{formatDate(now)}</time>
          </p>
          <span className="time-band-divider" aria-hidden="true" />
          <p className="time-band-date">
            社債1口の価格 <strong>{formatWholeYen(loan.price)}</strong>
            {stale ? <Badge tone="warn">3日を過ぎた価格</Badge> : null}
          </p>
        </div>
        <div className="time-band-actions">
          {priceButtons.map((button) => (
            <button
              key={button.label}
              type="button"
              className="button button-small"
              disabled={busy}
              title={`評価会社が1口${formatWholeYen(BigInt(button.price))}の価格を入れます`}
              onClick={() => setPrice(button.price)}
            >
              {button.label}
            </button>
          ))}
        </div>
      </div>
    </div>
  );
}
コード 意味
bandButtons(chainId, now, state) 今のチェーンと価格から、並べるボタンを決める。
ローンをデプロイする前と価格を読む前は空にする
if (buttons.length === 0) return null Fujiとデプロイする前は、帯ごと出さない
"price" in button 価格を持つボタンだけを選ぶ。
時刻を持つボタンは次の節で並べる
loan.now > loan.usableUntil チェーンの時刻が価格を使える期限を過ぎたら、価格の横に「3日を過ぎた価格」の札を出す
title={...} ボタンに指を乗せると、入れる価格を出す

starter/app/src/app/layout.tsxで帯を読み込み、ヘッダーの下に置きます。

import { Header } from "@/components/header";
import { Band } from "@/components/band";
          <Header />
          <Band />
          <main className="main">{children}</main>

帯は全てのページで同じものを出すので、ページごとでなくlayout.tsxに置きます。
借り手のページでも貸し手のページでも、同じ価格を上下させられます。

続けて、借り手のページのstarter/app/src/components/borrower-view.tsxを書き換えます。
頭の読み込みに、円トークンのABIと担保維持率を文字にする関数を足します。

import { bondTokenAbi, jpyTokenAbi, securitiesLoanAbi } from "@contracts/generated/abi";
import { formatDate, formatPercent, formatRatio, formatUnitsCount, formatWholeYen, parseCount, shortAddress, YEN } from "@/lib/format";

bondの行の後に円トークンを足します。
limitの行の後には、返す額の欄と預けた後の担保維持率と利息の日数を足します。

  const bond = { abi: bondTokenAbi as Abi, address: contracts.bond };
  const jpy = { abi: jpyTokenAbi as Abi, address: contracts.jpy };
  const limit = position ? (position.units * price * loanState.ltvBps) / 10_000n : undefined;
  const [repayAmount, setRepayAmount] = useState("");
  const repayValue = parseCount(repayAmount);
  // 入れた口数を足した後の担保維持率。借りていない時は出さない
  const afterRatio =
    position && position.debt > 0n ? ((position.units + (pledgeCount ?? 0n)) * price * 10_000n) / position.debt : undefined;
  const now = loanState.now ?? 0n;
  const interestDays = position && position.principal > 0n && now > position.interestFrom ? (now - position.interestFrom) / 86_400n : 0n;
コード 意味
jpy 返す時に、ローンのコントラクトに円を任せるために使う
pledgeCount ?? 0n 預ける口数の欄に入れた口数。
何も入れていない時は0口を足す
afterRatio 入れた口数を預けた後の担保維持率。
追加担保の請求を受けた時に、何口足せば戻るかを試せる
(now - position.interestFrom) / 86_400n 利息を数え始めてから経った日数。
コントラクトと同じく、1日に満たない時間は数えない

ヒーローの横の一覧に、担保維持率を足します。

          <li>
            <span>担保の評価額</span>
            <span className="mono">{formatWholeYen(position.value)}</span>
          </li>
          <li>
            <span>担保維持率</span>
            <span className="mono">{formatRatio(position.ratioBps)}</span>
          </li>
        </ul>

担保を預けるの枠の一覧の末尾に、預けた後の担保維持率を足します。

            <div>
              <dt>1口の評価額</dt>
              <dd>{formatWholeYen(loanState.price)}</dd>
            </div>
            {afterRatio !== undefined ? (
              <div>
                <dt>預けた後の担保維持率</dt>
                <dd>{formatRatio(afterRatio)}</dd>
              </div>
            ) : null}
          </dl>

grid-2の後に、返すの枠を置きます。

      <Card title="返す" description="返した額は利息に充ててから元本に充てます。元本と利息を全て返すと、担保の社債が戻ります。">
        <dl className="facts">
          <div>
            <dt>元本</dt>
            <dd>{formatWholeYen(position.principal)}</dd>
          </div>
          <div>
            <dt>
              利息 ({position.principal > 0n ? `${formatDate(position.interestFrom)}から${interestDays}日 年${formatPercent(loanState.rateBps)}` : "借りていません"})
            </dt>
            <dd>{formatWholeYen(position.interest)}</dd>
          </div>
          <div>
            <dt>返す額の合計</dt>
            <dd>{formatWholeYen(position.debt)}</dd>
          </div>
        </dl>
        <form
          className="form form-inline"
          onSubmit={async (event) => {
            event.preventDefault();
            if (repayValue === undefined) return;
            const ok = await send("repay", `${formatWholeYen(repayValue)}を返しました`, [
              { ...jpy, functionName: "approve", args: [contracts.loan, repayValue * YEN] },
              { ...loan, functionName: "repay", args: [repayValue] },
            ]);
            if (ok) setRepayAmount("");
          }}
        >
          <Field label="返す額" unit="円">
            <input inputMode="numeric" value={repayAmount} onChange={(event) => setRepayAmount(event.target.value)} placeholder={position.debt.toString()} />
          </Field>
          <button className="button button-primary" type="submit" disabled={repayValue === undefined || pending !== undefined}>
            {pending === "repay" ? "返しています" : "返す"}
          </button>
        </form>
      </Card>
コード 意味
formatDate(position.interestFrom) 利息を数え始めた日。
返すと数えた日数の分だけ進む
formatPercent(loanState.rateBps) 年の金利。
200は2.00%と出る
placeholder={position.debt.toString()} 返す額の欄に、全て返す時の額を薄く出す
repayValue * YEN 1円単位の額を、18桁を持つ円トークンの最小単位にしてローンのコントラクトに任せる
approveとrepay 円を任せてから返す。
2つの取引を順に送る

最後に、貸し手のページのstarter/app/src/components/lender-view.tsxを書き換えます。
頭の読み込みにformatRatioを足します。

import { formatDate, formatPercent, formatRatio, formatUnitsCount, formatWholeYen, formatYen, parseAmount, parseCount, shortAddress, YEN } from "@/lib/format";

担保の価格の枠の一覧の末尾に、価格を使える期限を足します。

            <div>
              <dt>入れた日</dt>
              <dd>{loanState.updatedAt ? formatDate(loanState.updatedAt) : "-"}</dd>
            </div>
            <div>
              <dt>使える期限</dt>
              <dd className={loanState.usableUntil !== undefined && (loanState.now ?? 0n) > loanState.usableUntil ? "bad" : undefined}>
                {formatDate(loanState.usableUntil)}
              </dd>
            </div>
          </dl>

借り手の表に、利息と担保維持率の列を足します。

                <th className="num">元本</th>
                <th className="num">利息</th>
                <th className="num">担保維持率</th>
              </tr>
                  <td className="num">{formatWholeYen(position.principal)}</td>
                  <td className="num">{formatWholeYen(position.interest)}</td>
                  <td className="num">{formatRatio(position.ratioBps)}</td>
                </tr>

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

                  <td colSpan={6} className="muted">
コード 意味
className={... ? "bad" : undefined} 価格を使える期限を過ぎたら、期限の日付を赤で出す。
色は雛形のglobals.cssのfacts dd.badが持つ
formatRatio(position.ratioBps) 借り手ごとの担保維持率。
借りていない借り手は-と出る

確かめる

starter/appのディレクトリで動いているpnpm devを止め、もう一度実行します。
anvilが空の状態から立ち上がり、デプロイの後にチェーンの日付は2026-01-15へ進みます。
ブラウザでポート3403の画面を開くと、ヘッダーの下に帯が出て、チェーンの日付 2026-01-15と社債1口の価格 100,000円が並びます。

まず、貸し手の銀行が円を入れます。
ヘッダーの「貸し手」のページへ移り、右上のアカウントを「銀行」に切り替えます。
「円を入れる」の枠の入れる額に1000000を入れて「入れる」を押すと、「1,000,000円を入れました」と出ます。
「担保の価格」の枠には、使える期限の2026-01-18が出ます。

次に、ヘッダーの「借り手」のページへ移り、右上のアカウントを「借り手A」に切り替えます。
「担保を預ける」の枠の預ける口数に10を入れて「預ける」を押し、「借りる」の枠の借りる額に700000を入れて「借りる」を押します。
ヒーローの横の担保維持率に142.8%が出ます。
「返す」の枠には、元本700,000円と利息 (2026-01-15から0日 年2.00%)の0円が並びます。
返す額の合計は700,000円です。

帯の「価格を5%下げる」を押します。
帯の価格は95,000円になり、担保の評価額は950,000円に、担保維持率は135.7%に下がります。

借り手Aが10口を預けて700,000円を借り、帯で価格を5%下げたところ
借り手Aが10口を預けて700,000円を借り、帯で価格を5%下げたところ

続けて、一部を返します。
「返す」の枠の返す額に200000を入れて「返す」を押すと、「200,000円を返しました」と出ます。
まだ1日も経っていないので利息は0円で、200,000円は全て元本に充たります。
元本は500,000円になり、担保維持率は950,000 ÷ 500,000 = 190.0%に上がります。

価格を5%下げた後に、借り手Aが200,000円を返して担保維持率が上がったところ
価格を5%下げた後に、借り手Aが200,000円を返して担保維持率が上がったところ

借り手Aは10口を全て預けたので、持っている社債は0口です。
それでも預ける口数に2と入れると、預けた後の担保維持率に12口で数えた228.0%が出ます。
持っていない口数なので「預ける」を押しても通りませんが、何口を足せばどこまで戻るかを前もって見られます。

「貸し手」のページへ移ると、借り手の表の借り手Aの行に、元本500,000円と利息0円と担保維持率190.0%が並びます。
時刻を進めるボタンは、次の節で帯に足します。
3日を過ぎると、帯の価格の横に「3日を過ぎた価格」の札が出て、貸し手のページの使える期限が赤くなります。
次の節で、担保維持率が110%を下回った借り手に、追加担保を請求できるようにします。