xl1-knowledge

XL1 ブロックチェーンの知識

このスキルでは、データに特化した高スループットのデータアプリケーション向け Layer 1 である、XL1 ブロックチェーン（XYO Layer One）について説明します。XL1 は、ブロック、トランザクション、手数料、ステーキング、コンセンサスといったブロックチェーンのプリミティブによって XYO プロトコルを拡張します。

正確な型定義を確認する必要がある場合は、該当する @xyo-network/xl1-* パッケージをインストールし、dist/neutral/index.d.ts の TypeScript 宣言を確認してください。XL1 プロトコルイエローペーパーに、プロトコルの完全な仕様が記載されています。

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

スキルレイヤー

これは XYO スキルスタックの レイヤー 4 です：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)。

• 基盤となるスキル： xyo-knowledge (3) — プロトコルのプリミティブ（ペイロード、バウンドウィットネス、モジュール、アカウント、ウォレット）；ariestools-skills の xy-toolchain と xy-development (1–2) — ビルドツール（@ariestools/toolchain、ESLint、TypeScript 設定、Vitest）とコーディング規約（TypeScript、Git、テスト、ワークフロー）
• 引き継ぎ先： xl1-patterns (5) — Statement Graph（追記専用の署名付き関係主張、@xyo-network/xl1-statement-graph-*）や、コアチェーン以外のアプリケーション基盤を含むアプリケーション機能を構築する場合；xl1-dapp-kit (6) — ポータブルなヘッドレスアプリケーションコントラクト（@xyo-network/dapp-kit*）を採用する場合；xl1-testing (7) — ローカルチェーンまたは Sequence に対するチェーン操作を検証する場合；xl1-scaffold (8) — 新しい XL1 プロジェクトを開始する場合

ペイロードスキーマと識別規則

ペイロードを定義したり、識別子／コミットメントハッシュを選択したりする前に、ペイロードスキーマの進化と識別を読んでください。新しいスキーマ名には、構造上のバージョンサフィックスを含まない厳密な ASCII セグメントを使用します。$version は検証対象のメタデータです。ルートハッシュをアプリケーションのデフォルトとして使用します。公開済みのプロトコルハッシュコントラクトを維持し、認証されていない BoundWitness のバージョンによってコンセンサスや署名規則が選択されないようにしてください。

重要：生の RPC 呼び出しを決して行わないでください

XL1 ゲートウェイには SDK 経由でのみアクセスします。チェーンアクセスに関わるすべてのコード（dApp、サービス、インデクサー、テスト、検証スクリプト）には、次の 2 つの規則が適用されます。

1. XL1 JSON-RPC メソッドを名前で直接呼び出さないでください（blockViewer_blocksByNumber、transactionViewer_byHash、その他の <viewer>_<method> の組み合わせ。/rpc への生の fetch や、手書きの JSON-RPC クライアント経由の場合も含みます）。読み取りには gateway.connection.viewer.* を、書き込みにはゲートウェイのメソッドを使用してください。
2. Ethereum RPC メソッド（eth_getBalance、eth_blockNumber、eth_call、eth_sendTransaction、personal_sign など）や、Ethereum SDK（ethers、viem、web3.js）を XL1 に対して使用しないでください。XL1 は EVM チェーンではありません。XL1 が Ethereum と共有するのは、BIP44 の導出方式を共有することによるアドレス互換性だけです。

その理由、各 Ethereum メソッドに対応する XL1 のメソッド、および「完了」の判定に使う構造的な grep セルフチェックについては、ゲートウェイ — 生の RPC 呼び出しを決して行わないを参照してください。dApp の場合は、xl1-testing の完了判定でも同じチェックを行います：dApp の完了定義 — ゲートウェイとチェーンアクセス。

目次

XL1 Chain

XL1 ブロックチェーンの概念（ブロック、トランザクション、手数料、報酬、ノードの種類、コンセンサス）を扱うときにお読みください。チェーンのデータモデルと、XL1 が XYO の BoundWitness／Payload プリミティブをどのように拡張するかについて説明します。

Development on XL1

XL1 上でアプリケーションやサービスを構築するときにお読みください。Zod ファーストの型パターン、Viewer／Runner アーキテクチャ、プロバイダー（providerId による識別、MissingProviderIdError、UnknownProviderError ピンを含む）、検証、SDK パッケージの構成について説明します。

Identity & Wallets

XL1 のバックエンドコード（Node サービス、インデクサー、CLI、テスト）でウォレットや署名者を作成するときにお読みください。標準の generateXyoBaseWalletFromPhrase + derivePath('<index>') パターン、MetaMask および XYO ブラウザー拡張機能との環境をまたいだ互換性の保証、そして結果が AccountInstance となり、書き込み可能なランナーが必要な場合は GatewayBuilder.account(...) に直接渡すルールについて説明します。

Datalakes

XL1 チェーンデータのストレージ（アーカイブ、クエリ、ストレージバックエンドの設定）を扱うときにお読みください。DataLake 抽象化と、それが XYO Archivists を基盤としてどのように構築されるか、またオペレーター側のドライバーおよび S3 プロバイダーパッケージのインデックスについて説明します。

Gateway

XL1 チェーンに接続するときにお読みください。汎用ゲートウェイの概念、Viewer API、ネットワーク（REST ルートを含む）、トランザクションの送信（オプション、確認、フェーズ別の buildXl1Transaction … observeXl1TransactionFinality 関数によるクラッシュに強い永続的な送信）、トランスポート、ゲートウェイノードの実行方法について説明します。環境固有の構築方法は、2 つの別ファイルに記載されています。

Browser Gateway

React dApp、通常のページ、ワーカー、サービスワーカー、ブラウザー拡張機能など、あらゆるウェブサイトに XL1 を統合するときにお読みください。@xyo-network/xl1-browser-system が推奨される統合基盤であり、REST が推奨トランスポートです。React dApp では、ブラウザーシステムを直接起動するのではなく、transport="rest" を指定した InPageGatewaysProvider を通じて利用します。また、Chrome ウォレット拡張機能、WalletGatewayProvider／GatewayProvider、useProvidedGateway についても説明します。ゲートウェイ上に構築された UX パターンについては、Browser UX をご覧ください。

Node Gateway

バックエンドサービス、インデクサー、CLI、スケジュールされたジョブ、テスト、dApp のヘッドレス検証など、ブラウザー以外のあらゆるコンテキストでゲートウェイを構築するときにお読みください。標準の GatewayBuilder エントリーポイント（読み取り専用および書き込み可能）、所有するゲートウェイセッション（クリーンなシャットダウンのための buildSession()／buildRunnerSession() と stop()）、シードフレーズ署名者パターン、遅延プロミスのキャッシュパターン、basicRemoteViewerLocator による代替手段について説明します。

Finalized block stream

インデクサーやサービスで、順序どおりの確定済みブロック配信（FinalizedBlockStream／finalizedBlockStreamFromGateway）が必要なときにお読みください。非推奨の headUpdated ではなく、こちらを優先してください。Gateway の一節です。