# Xl1 Knowledge > XL1 blockchain development (XYO Layer One). Covers the XL1 chain, datalakes, gateway (generic, browser, and Node — including FinalizedBlockStream), identity, and pointers to application substrates (Statement Graph, dapp-kit). Activates when building on XL1, working with @xyo-network/xl1-* packages, or developing blockchain-backed applications. - Skill: `xyoraclenetwork/xl1-knowledge` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add xyoraclenetwork/xl1-knowledge` - Raw SKILL.md: https://api.skillmd.com/api/skills/xyoraclenetwork/xl1-knowledge/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: xyoraclenetwork (https://skillmd.com/u/xyoraclenetwork) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xyoraclenetwork/xl1-knowledge --- # XL1 Blockchain Knowledge This skill covers the XL1 blockchain (XYO Layer One) — a data-focused Layer 1 designed for high-throughput data applications. XL1 extends the XYO protocol with blockchain primitives: blocks, transactions, fees, staking, and consensus. **Skill identity.** This skill's version is exposed in this file's frontmatter under `metadata.version`. When reporting which skills informed your work, format as ` v` (e.g. `xl1-knowledge v1.1.19`). When multiple skills from this plugin are active, each may be listed. ## Lower Layer Skills XL1 builds on the full skill stack. When working on XL1 projects, also consult: - **[XYO Knowledge](../xyo-knowledge/SKILL.md)** — for protocol primitives (payloads, bound witnesses, modules, accounts, wallets) - **[XY Toolchain](../xy-toolchain/SKILL.md)** — for build tooling (@ariestools/toolchain, ESLint, TypeScript config, Vitest) - **[Development](../xy-development/SKILL.md)** — for coding conventions (TypeScript, Git, testing, workflow) When you need to look up exact type definitions, install the relevant `@xyo-network/xl1-*` package and read the TypeScript declarations at `dist/neutral/index.d.ts`. The [XL1 Protocol Yellow Paper](https://docs.xyo.network) provides the full protocol specification. ## Payload schema and identity rules Before defining payloads or choosing identity/commitment hashes, read [Payload Schema Evolution and Identity](../xyo-knowledge/payload-schema-evolution.md). New schema names use strict ASCII segments without structural version suffixes; `$version` is validated metadata; root hashes are the application default. Preserve shipped protocol hash contracts and do not let an unauthenticated BoundWitness version select consensus or signature rules. ## Critical: Never Issue Raw RPC Calls The XL1 gateway is reached exclusively through the SDK. Two rules apply to every piece of code that touches chain access — dApp, service, indexer, test, verification script: 1. **Never call XL1 JSON-RPC methods by name** (`blockViewer_blocksByNumber`, `transactionViewer_byHash`, and any other `_` pair — whether via raw `fetch` to `/rpc` or a hand-rolled JSON-RPC client). Go through `gateway.connection.viewer.*` for reads and gateway methods for writes. 2. **Never use Ethereum RPC methods** (`eth_getBalance`, `eth_blockNumber`, `eth_call`, `eth_sendTransaction`, `personal_sign`, etc.) or Ethereum SDKs (`ethers`, `viem`, `web3.js`) against XL1. XL1 is not an EVM chain. Address compatibility via shared BIP44 derivation is the *only* thing XL1 shares with Ethereum. See [Gateway — Never Issue Raw RPC Calls](gateway.md#never-issue-raw-rpc-calls) for the rationale, the XL1 equivalents for each Ethereum method, and the structural grep self-check that gates "done." Enforced by [dApp Checklist — Gateway & Chain Access](../xl1-patterns/dapp-checklist.md#gateway--chain-access). ## Table of Contents ### [XL1 Chain](chain.md) Read when working with XL1 blockchain concepts — blocks, transactions, fees, rewards, node types, or consensus. Covers the chain data model and how XL1 extends XYO's BoundWitness/Payload primitives. ### [Development on XL1](development.md) Read when building applications or services on XL1. Covers the Zod-first type pattern, Viewer/Runner architecture, providers, validation, and the SDK package structure. ### [Identity & Wallets](identity.md) Read when creating a wallet or signer in XL1 backend code (Node services, indexers, CLIs, tests). Covers the canonical `generateXyoBaseWalletFromPhrase` + `derivePath('')` pattern, the cross-environment compatibility guarantee with MetaMask and the XYO browser extension, and the rule that the result is an `AccountInstance`, which goes directly to `GatewayBuilder.account(...)` when a write-capable runner is needed. ### [Datalakes](datalakes.md) Read when working with XL1 chain data storage — archiving, querying, or configuring storage backends. Covers the DataLake abstraction and how it builds on XYO Archivists. ### [Gateway](gateway.md) Read when connecting to the XL1 chain — generic gateway concepts, viewer API, networks, transports, and how to run a gateway node. Environment-specific construction lives in two sibling files. ### [Browser Gateway](gateway-browser.md) Read when constructing a gateway in a React dApp — the Chrome wallet extension, `WalletGatewayProvider` / `GatewayProvider` / `InPageGatewaysProvider`, and `useProvidedGateway`. UX patterns built on top of the gateway live in [Browser UX](../xl1-patterns/browser-ux.md). ### [Node Gateway](gateway-node.md) Read when constructing a gateway in any non-browser context — backend services, indexers, CLIs, scheduled jobs, tests, and headless verification of dApps. Covers the canonical `GatewayBuilder` entry point (read-only and write-capable), the seed-phrase signer pattern, the lazy-promise caching pattern, and the `basicRemoteViewerLocator` escape hatch. ### Application substrates (not core chain) - **[Statement Graph](../xl1-patterns/statement-graph.md)** — append-only signed relationship claims (`network.xyo.statement.claim`); application-layer package family `@xyo-network/xl1-statement-graph-*`. - **[XL1 dApp Kit](../xl1-dapp-kit/SKILL.md)** — portable headless application contracts (`@xyo-network/dapp-kit*`). - **[Finalized block stream](gateway.md#finalized-block-stream)** — ordered finalized delivery for indexers (`FinalizedBlockStream` / `finalizedBlockStreamFromGateway`); prefer over deprecated `headUpdated`.