第1章本書について#

本章は、本書の読者・範囲・免責を最初に確定するための章です。公開技術文書として、どこまでを保証し、どこからを読者の判断・専門家の確認に委ねるかを、はじめに明示します。技術的な内容は第2章以降で扱います。

はじめに(重要な前提): 本書は、Solana 上で現実資産(RWA)をトークン化するリファレンス実装の設計・実装を扱う技術文書であり、法的助言ではありません。トークンが表章する権利の帰属や、証券への該当性を含む法的な判断は、採用する法的ストラクチャや法域によって異なります。これらは必ず専門家に確認してください。本書は特定の銘柄・事業者を推奨せず、投資判断・価格に関する記述も行いません。

1.1 目的と想定読者#

本書の目的は、コンプライアンス要件を満たす RWA トークンを Solana 上に構築する一連の手順を、再現可能な形で示すことです。題材は私募債(プライベート・ボンド)のトークン化とし、発行・移転制限・凍結・強制回収・償還への接続までを、動作するリファレンス実装とともに解説します。

想定する読者は次のとおりです。

主読者: EVM 系または Web2 バックエンドの開発経験があるエンジニア(Solana は初学者〜中級)。AI コーディングエージェントの利用経験がある前提とします。
副読者: RWA 事業を検討する企画・法務の担当者。技術的詳細に立ち入らない第1〜3章を中心に読むことを想定します。

主読者は本書の全章を、副読者は第1〜3章を通読できるよう記述します。第4章以降はコードとコマンドを含む実装の章です。

1.2 本書で構築するもの#

本書で構築するのは、私募債トークンの発行から移転制限・凍結・強制回収までを扱うリファレンス実装です。完成形は、次の三つの要素で構成されます。

Token-2022 ミント(scripts/create-mint.ts):4つの拡張を持つミントを作成します。拡張は Transfer Hook / Permanent Delegate / Default Account State=Frozen / Metadata Pointer+Token Metadata です(第6章)。
registry プログラム(programs/registry):投資家の許可状態(Approved / Suspended)を管理するオンチェーン許可リストです(第7章)。
transfer_hook プログラム(programs/transfer_hook):転送時に Token-2022 本体から呼び出されます。送信者・受信者の双方が registry 上で Approved であることを検証します(第7章)。

これらが組み合わさることで、次の性質を持つトークンが実現します。新規口座は既定で Frozen であり、KYC 完了後に thaw して初めて受領できます。移転は許可済み投資家の間でのみ成立します。発行体は permanent delegate により強制回収を実行できます。全体像は次のとおりです。

flowchart TB
  subgraph offchain["オフチェーン(第8章:概念設計)"]
    kyc["KYC プロバイダ<br/>審査"]
    admin["管理者<br/>(発行体)"]
  end
  subgraph onchain["オンチェーン(第6・7章:実装済み)"]
    registry["registry プログラム<br/>投資家許可リスト<br/>Approved / Suspended"]
    hook["transfer_hook プログラム<br/>移転時に双方の許可を検証"]
    mint["Token-2022 ミント<br/>4拡張 + Metadata"]
  end
  inv["投資家の<br/>トークン口座<br/>(既定 Frozen)"]

  kyc -->|審査完了| admin
  admin -->|register_investor| registry
  admin -->|thaw / freeze| inv
  admin -->|mint_to| inv
  mint -->|Transfer Hook 拡張| hook
  hook -->|InvestorStatus を参照| registry
  inv -->|移転を試行| hook

本書のリファレンス実装で実証済みなのは、オンチェーンの三要素(registry / transfer_hook / ミント)です。加えて、devnet でのエンドツーエンド検証(第9章 T-40)、LiteSVM による全 26 テスト、CI の実機グリーン(第9章 9.7)を確認しています。一方、KYC プロバイダ連携・管理用 API・インデクシング・償還フローは概念設計であり、本リポジトリには含みません(第8章 8.1 の境界表)。この境界は本書を通じて明示します。

1.3 本書で扱わないこと#

本書は、次の事項を扱いません。

法的助言。 証券該当性、開示義務、投資家保護などの法的判断は行いません。論点の名称を挙げ、専門家への相談を促すに留めます(第2章 2.5)。
証券・トークンの勧誘、投資判断、価格・投資リターンに関する記述。
特定業者・製品の推奨。 オフチェーン基盤や監視ツールは「選定基準+代表例」の列挙に留めます(第8章・第11章)。

また、本リファレンス実装では未実施の工程があります。これらは手順を公式一次情報に基づいて示しますが、本リポジトリで実行検証したものではありません。実施済みと誤読しないでください。

mainnet へのデプロイ(第11章 11.2)
upgrade authority のマルチシグ移管と immutable 化(第11章 11.3)
Verifiable Build の実施(第10章 10.5)
第三者監査(第10章 10.4)

1.4 動作確認済みバージョン表#

本書のコード・コマンドは、以下のバージョンで動作を確認しています。確認日は 2026 年 7 月 22 日です。本書全体でこの表を唯一の基準とし、本文中で「latest」「最新版」という表記は用いません。バージョンは四半期ごとに再確認します(第12章 12.4)。

ツールチェーン

ツール	固定バージョン	固定方法
Anchor CLI	1.1.2	`avm install 1.1.2` → `avm use 1.1.2`(ソースからビルド)
AVM	1.1.2 ²	第4章のクリーン環境再現でソースからビルド(4.9 TS-2)
Solana CLI(Agave)	3.1.13	既存(Anchor 1.1.x の CI 検証対は 3.1.10。同 3.1.x 系)
Rust(rustc / cargo)	1.89.0	`rust-toolchain.toml`(channel = "1.89.0")。anchor-lang 1.1.2 の MSRV と一致
Node.js	24.15.0 ¹	既存
Yarn	1.22.22	既存

主要な crate 依存(programs/registry / programs/transfer_hook)

crate	宣言バージョン	解決版	用途
anchor-lang	1.1.2	1.1.2	プログラム本体 / 型の共有
litesvm	0.10.0	0.10.0	Rust 高速テスト
spl-transfer-hook-interface	=2.1.0	2.1.0	Transfer Hook インターフェース
spl-tlv-account-resolution	=0.11.1	0.11.1	ExtraAccountMetaList / ExtraAccountMeta
spl-token-2022-interface	2	2.1.0	拡張・トークンアカウント読み取り
spl-pod	0.7	0.7.3	PodBool 等

互換性の注意: 旧来の monolith crate spl-token-2022(9.x 系)は solana-* ^2.2 ラインのため、本プロジェクト(solana-* ^3)と非互換です。anchor-spl 1.1.2 が用いる interface crate ライン(spl-token-2022-interface ^2 等)に統一しています。混在させないでください(詳細は第12章 12.4)。

主要な npm 依存(scripts/create-mint.ts)

パッケージ	固定バージョン	発行元 org	用途
@solana/kit	7.0.0	anza-xyz	クライアント基準 SDK
@solana-program/token-2022	0.13.0	solana-program	Token-2022 命令ビルダー
@solana-program/system	0.13.0	solana-program	createAccount 命令

crate・npm パッケージの発行元 org は、いずれも crates.io / npm の公式ページで確認済みです(フォークではありません。確認結果は docs/versions.md)。プログラム ID は docs/versions.md に記録した固定値を用います(ローカル生成のテスト用鍵)。

1.5 本書における AI 開発ツールの位置づけ#

本書は、Solana 開発で AI コーディングエージェントの利用が標準的になっている前提で書かれています。ただし、AI の利用は前提であって、必須ではありません。本書の全手順は、AI を使わずとも再現できるよう、コマンドとコードを明示しています。

本書が重視するのは、ツールそのものではなく統制(検証・責任・監査対応)です。AI が生成したコードも、人が書いたコードと同じ検証ゲート(ビルド・テスト・レビュー・依存監査)を通します。「AI が書いたか」ではなく「どう検証したか」を説明できる状態を作ることを、本書の各章は一貫して求めます。AI 駆動開発のワークフローと統制の詳細は第5章で扱います。

なお本書は、AI を使えば専門知識が不要になる、という立場を取りません。以降の章は、AI に生成させた場合でも、読者が出力の正否を自分で判定できる知識を提供するものです。

1.6 免責事項とライセンス#

免責事項(テンプレート):

本書および付属のサンプルコードは、情報提供および技術的な参考を目的として現状有姿で提供されます。本書の内容は、法的・財務・税務上の助言を構成するものではありません。RWA のトークン化には、証券規制・資金決済規制・KYC/AML など各法域の規制が関わります。実際の事業への適用にあたっては、必ず有資格の専門家に相談してください。本書の記載に基づいて生じたいかなる結果についても、発行主体は責任を負いません。記載のバージョン・仕様・市場数値は確認日時点のものであり、変更される可能性があります。

ライセンス:

本書(文書)およびサンプルコードリポジトリのライセンスは、本稿の執筆時点では未設定です。公開にあたっては、文書とコードのそれぞれについてライセンスを確定させてください(発注側の決定事項。第12章 12.5)。サンプルコードで参照する外部 crate・npm パッケージのライセンスは、各パッケージの表記に従います。

1.7 表記規則#

本書では、以下の表記規則を用います。

コマンド: シェルコマンドの入力行には $ プレフィックスを付します(出力行には付しません)。
プレースホルダ: 読者が置き換える値は <...> で示します(例:<PROGRAM_ID>)。
コードブロック: 言語指定とファイルパスを付します。省略する場合は // --- 省略 --- を明示します。
相互参照: 章・節・項は「章.節.項」形式の番号で参照します(例:第7章 7.5.3)。
ネットワーク: 断りのない限り、コマンドは devnet を対象とします。mainnet 固有の記述は明示します。
鍵の扱い: 本書で扱う鍵は、すべてローカル生成のテスト用です。秘密鍵・シードフレーズ・本番 RPC キーは扱いません。

1.8 本章の自己チェック表#

観点	結果
スタイル規則違反	なし(です・ます調、一文概ね80字以内、相互参照は番号、価格・投資リターン・マーケティング語彙・法的判断示唆なし。冒頭に法的助言でない旨を明記)
バージョン表の出所	`docs/versions.md`(確認日 2026-07-22)からの転記。数値の新規断定なし。本文中に「latest」「最新版」の記載なし
Node の差の扱い	固定値 24.15.0 と検証コンテナ実測 24.18.0 の差を脚注で明示し、第4章 4.1.3・4.6 と整合(マイナー差はビルドに影響しない)
「本書で構築するもの」の実態整合	完成した全章(2〜11)と実装(registry / transfer_hook / create-mint.ts)に即して記述。実証済み(devnet E2E・26テスト・CI 緑)と概念設計(第8章)の境界を明記
免責の扱い	テンプレを掲載し、「公開前に法務レビュー必須」を HTML コメントで明示(設計書第1章執筆上の注意)
ライセンス	未設定である旨を明記(公開前に文書・コード別に確定=発注側の決定事項。第12章 12.5)
`[要検証]` の残数	0件(バージョンは versions.md 転記、実装実態は完成稿・README と一致。未確定事項=ライセンスは「未設定」と事実として明記)
章間の接続	第2章(RWA・Solana)、第4章(環境=バージョン表)、第5章(AI 統制)、第6・7章(実装)、第8章(概念設計の境界)、第10・11章(未実施工程)、第12章(用語・チェックリスト・参考文献)へ接続

第4章のクリーン環境再現では、検証コンテナに Node.js 24.18.0 が導入されました。本表の固定値 24.15.0 とはマイナーバージョンが異なりますが、この差はビルド・テストに影響しないことを第4章 4.1.3・4.6 で確認しています。読者環境では 24.15.0 以上の同系(24.x)を用いてください。 ↩
本表の AVM のバージョン 1.1.2 は、第4章のクリーン環境で検証した値です(Anchor CLI 1.1.2 をソースからビルドする過程で導入。手順は第4章 4.9 の TS-2)。なお、ホスト機では旧 avm(0.30.1)からの Anchor CLI 1.1.2 のソースビルドも動作を確認済みです。avm 自体のバージョンは、インストール対象の Anchor のバージョンを制約しません。 ↩

第1章 本書について#