xl1-patterns

XL1 設計パターン

このスキルでは、XL1 上で一般的なアプリケーション機能を構築するための、具体的な手順を示すレシピ形式のパターンを紹介します。下位レイヤーが XL1 とは何か を説明するのに対し、このレイヤーでは XL1 上でどのように構築するか を説明します。

ルールの管理元。 以下の項目は、リンク先のファイルに全文が記載されているルールの概要です。正規の情報源はリンク先のファイルです。ここでの概要とリンク先のファイルに食い違いが生じた場合は、黙って整合させるのではなく、リンク先のファイルに従い、相違を報告してください。

スキルの識別情報。 このスキルのバージョンは、このファイルのフロントマターにある metadata.version で確認できます。計画、了承、完了の概要を提示する際は、参考にしたスキルを <skill-name> v<version> の形式で明記してください。バージョンは例ではなく、このファイルのフロントマターから読み取ってください。このプラグインの複数のスキルが有効な場合は、それぞれを記載できます。

スキルのレイヤー

これは XYO スキルスタックの レイヤー 5 です：xy-development (1) → xy-toolchain (2) → xyo-knowledge (3) → xl1-knowledge (4) → xl1-patterns (5) → xl1-dapp-kit (6) → xl1-testing (7) → xl1-scaffold (8) → xl1-build (9)。

• 基盤とするもの： xl1-knowledge (4) — チェーンのデータモデル、データレイク、ゲートウェイ（汎用、ブラウザー、Node）；xyo-knowledge (3) — ペイロード、バウンドウィットネス、モジュール、アイデンティティ；ariestools-skills (1–2) の xy-toolchain と xy-development — ビルドツール、ESLint、TypeScript の設定、Vitest；コーディング規約、Git、テスト、ワークフロー
• 引き継ぎ先： xl1-dapp-kit (6) — @xyo-network/dapp-kit* を採用する場合（ヘッドレスランタイム、アプリケーションポート、エフェクトジャーナルと復旧、ホスティング）；xl1-testing (7) — 作業を検証する場合（ヘッドレステストネット、ローカルチェーン、ブラウザーモード）、および完了を報告する前に dApp の完了定義を確認する場合；xl1-scaffold (8) — 新しい XL1 プロジェクトを開始する場合；xl1-build (9) — ビルドの依頼がまだ曖昧な場合

ペイロードスキーマとハッシュの前提条件

レシピを応用する前に、ペイロードスキーマの進化とアイデンティティを読んでください。安定した ASCII スキーマ名、明示的なバージョン／形状のサポート、意図的に閉じた凍結済みの定義、新しいアプリケーション参照／コミットメント向けのルートハッシュが記載されています。既存のプロトコル固有のデータハッシュアルゴリズムは引き続き契約として扱われます。文書化された例外があるからといって、新しいアプリケーションでデータハッシュを既定で使うことにはなりません。

目次

アーキテクチャの原則

複数の関係者にとって状態が重要となる XL1 dApp を設計またはレビューする際は、dapp-kit の有無にかかわらず、まず読んでください（ゲーム、市場、オークション、レジストリ、リーダーボード）。7 つの原則（dApp はエンジンであり、すべてのインターフェースはクライアントである；状態はアンカーされた証拠である；プロトコルを文書化する；ハウスはバウンドされたプロトコル上の役割である；再生ではなくインデックスから読み込む；インデックスのコストを一定に保つ；インデックスの回答は低コストで検証可能にする）、ワーカーの権限と連携、横断的なルール、信頼性の表、レビュー用の質問が含まれます。ワーカーの役割を割り当てるときや、作業の発見方法、並行処理、復旧、連携を選択するときは、採用したリビジョンに含まれる ariestools-architecture スキルも参照してください。利用可能かどうか、および XL1 固有の適用方法については、ワーカーの権限と連携で説明されています。

ブラウザー UX

UI を備えたすべての dApp で必読です。ほとんどの dApp が該当します。ウォレット接続のライフサイクル（ConnectAccountsStack とそのスロットプロパティ）、onAccountsChanged を使って許可されたアカウントをアプリの状態に反映する方法（互換性維持のための onAccountConnected ではありません）、useConnectAccount のシングルトンに関する落とし穴、機能に応じたコンポーネント（許可されたアカウントと書き込み可能なランナーの組み合わせ）、dApp の UI 構造、表示規則（ハッシュ／アドレスの省略表示、クリップボードへのコピー）を扱います。Browser Gateway の構築に重ねる UX レイヤーです。作業に本当に UI がない場合（純粋なインデクサーサービスや CLI）に限り、読み飛ばしてください。

ウォレット

dApp が ConnectAccountsStack のデフォルトの処理を超えて XL1 ブラウザーウォレットに権限をリクエストする必要がある場合、または「データレイクの権限」をリクエストしようとしていて、それが誤った方法である理由を知りたい場合に読んでください。登録済みの 5 つの RPC 権限について説明します。一般にサポートされている 2 つのアカウントメソッドは 1 つの許可を共有します（xyoWallet_getAccounts をリクエストすると、xyoSigner_address も利用できます）。さらに、xyoSigner_sign に対する実験的な自動署名権限と、xyoDataLakes_*（SDK の DataLake* コンポーネントを含む、内部専用）を使用してはならないという厳格なルールも扱います。また、ConnectAccountsStack より低いレベルで操作するための SDK フック（useGrantedAccounts、RequestPermissionsButton、usePermissions）についても説明します。

ブラウザー ↔ サービスの接続

dApp に React アプリとそれに付随する HTTP サービスの両方がある場合は必読です（モノレポのデフォルトのフロー）。指定されたポートの組み合わせ（:3000 アプリ、:3001 サービス）、/api/* のベースパス規則、すべてを同一オリジンに保つ Vite 開発プロキシ、本番環境における単一ドメインのリバースプロキシ構成について説明します。デフォルトで同一オリジンを使うため、サービスに CORS ミドルウェアは不要です。本当にクロスオリジンの構成が必要な場合の代替手段も説明しますが、例外として扱います。サービスがない場合（読み取り専用の React アプリのみ、または UI のないサービスのみのプロジェクト）に限り、読み飛ばしてください。

チェーンデータのインデックス作成 — 役割別

プロトコル／クライアント／サービスの分離に従う、このレイヤーの最初のパターンです。まずプロトコルファイルを読み、その後、構築するものに合った役割別ファイルを読んでください。

チェーンデータのインデックス作成 — プロトコル

アプリケーション固有のチェーンデータを取得、フィルタリング、監視するための概念的なルールを説明します。スキーマ、アンカリングの選択肢（Path A/B/C）、Destination as Protocol（センチネルアドレス）、4 つのスキャン戦略、finalized と latest の意味上の違いを扱います。環境に依存せず、クライアントとサービスの両方がこのルールに従います。

チェーンデータのインデックス作成 — クライアント

ブラウザー側の読み取りについて説明します。ただし、一時的で、単一ユーザー向けの単純なケースに限ります。ポーリングによる読み取りのための useChainData フックのレシピ（SDK がエクスポートするものではなく、独自に実装するコード）、コンポーネントでの機能検出、ブラウザーに置くべきものと置くべきでないものの明確な境界を扱います。マルチユーザー対応、永続性、またはリオーグの影響を受ける処理が必要な場合は、代わりにサービスのファイルを参照してください。

チェーンデータのインデックス作成 — サービス

長時間稼働するインデクサーサービスについて説明します。プロセスモデル（同期／永続化／提供の各ループ）、状態の永続化とアトミックなチェックポイント、再起動後の再開セマンティクス、HTTP API による結果の公開、署名者インデクサーと永続的な送信、デプロイ構成（プロセス監視、単一インスタンス、/api/healthz、環境変数によるネットワーク指定）を扱います。

コミット・リビールのプリミティブ

複数の当事者が同時に意思決定を行い、他者の選択を先に知ることが不公平になる機能を構築する場合に読んでください。2 段階のコミット・リビールワークフロー、コミットとリビールのスキーマ設計、オンチェーンへの記録、ハッシュの検証、タイムアウトの処理について説明します。

ページ内データレイク

React dApp でウォレット接続を必要とせず、チェーンデータへの読み取り専用アクセスが必要な場合にお読みください。ページ内ゲートウェイのアーキテクチャ（defaultGateway はウォレットがインストールされている場合はウォレットのものになるため、gateways.inPageGateway を使ってパブリックな読み取りを行う方法）、React コンポーネントからデータレイクにクエリを実行する方法、読み取り専用アクセスとウォレットが必要な書き込みを組み合わせる方法について説明します。

コミット・リビール型予測市場

ゲーム、予測市場、またはステーク、コミット、リビール、決済のライフサイクルを持つアプリケーションを構築する場合にお読みください。コミット・リビール、チェーンデータのインデックス作成、ページ内データレイクを組み合わせた複合パターンで、完全なレシピを提供します。nbf／exp の有効期間、設定された outcomeAuthorities、簡潔な決済ペイロード、各フェーズ間の $sources による関連付けを使用します。

アトミック交換

2 者以上がアセットをアトミックに交換する必要がある場合にお読みください。すべての当事者が取り消し不能なコミットを行わない限り、どの当事者も望むものを得られません。XYO／XNS のエスクローフローを dApp 向けに投影したもので、複数当事者のペア化されたシークレット、複数署名者の BoundWitness、査定と受領証に対する設定可能な権限リスト、簡潔な結果ペイロード、リビールがない場合は権利放棄ではなく決済を妨げるという厳格なルールを扱います。コミット・リビールを、隠された選択のプロトコルではなく、アセット解放のゲーティング機構として組み合わせます。

インスクリプション基盤

アプリケーションで XL1 上に永続的で、譲渡可能かつ所有者を持つオブジェクト（Bitcoin の Ordinals に相当するもの）が必要な場合にお読みください。アーティファクトとイベントの分離、コンテンツアドレス型のインスクリプション ID、単一ステップの署名付き譲渡、ファイナライズのみを対象とするインデクサーの再生、所有権台帳の導出について説明します。ファンジブルトークン、コレクション、再帰的コンテンツなど、上位レイヤーのプロトコルがその上に構成される基盤です。

ファンジブルトークン（XRC-20）

Bitcoin の BRC-20 形式にならって XL1 上でファンジブルトークンを構築する場合にお読みください。オープンなティッカー登録、上限付きミント、アドレス間の送金、オンチェーンイベントに基づくオフチェーン台帳を扱います。インスクリプション基盤の上に直接レイヤー化されています。デプロイ／ミント／送金のスキーマ、2 パスのインデクサー、正規の順序規則、BRC-20 の 2 ステップ送金方式から意図的に変更した点について説明します。

ステートメントグラフ

XL1 上で再生可能かつソースに帰属する関係／アサーショングラフ（バインディング、権限付与、承認、メンバーシップ）が必要な場合にお読みください。ライフサイクルは閉じており（{ source, subject, hashes } を含む 1 つの network.xyo.statement.claim）、プロダクトの語彙はオープンです。fold 4 には取り消しを表す動詞がなく、主張されたすべてのオブジェクトがクレーム自体のトランザクション内に存在する必要があります。インスクリプション基盤の対となるものであり、NFT のようなカストディ用途には向きません。

認証済みウェイク配信

スリープ可能なインデクサー／ホストを、Statement Graph の権限付与とアクティブな D-005 ハンドシェイクサブスクリプションによって認可されたウォレット JWT 発行者が起動する必要がある場合にお読みください。HMAC ウェブフックではありません。Event Kit 2.2.x（Node ≥ 26）では、ファイナライズ済み XL1／ファイナライズ済み Ethereum／UTC 間隔ソース、明示的な durable／best-effort 配信、アクティブソースの受付、wakeId と jti の違い、WakeQueue リースを扱います。ウェイクは作業をスケジュールしますが、チェーンの真実を示すものではありません。

dApp の完了定義（xl1-testing 内）

XL1 dApp の作業完了を報告する前に必ず実施してください — 上記すべてのパターンに対する完了判定は、xl1-testing（レイヤー 7）が管理しています。手順に沿って確認し、該当するセクションごとに合格／不合格を報告してください。