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.

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 provides the full protocol specification.

Skill identity. This skill's version is exposed in this file's frontmatter under metadata.version. Whenever you present a plan, an acknowledgement, or a completion summary, state which skills informed it, formatted as <skill-name> v<version> — read the version from this file's frontmatter, never from an example. When multiple skills from this plugin are active, each may be listed.

Skill layers

This is Layer 4 of the XYO skill stack: 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).

• Builds on: xyo-knowledge (3) — protocol primitives (payloads, bound witnesses, modules, accounts, wallets); xy-toolchain and xy-development from ariestools-skills (1–2) — build tooling (@ariestools/toolchain, ESLint, TypeScript config, Vitest) and coding conventions (TypeScript, Git, testing, workflow)
• Hands off to: xl1-patterns (5) — when building application features, including the Statement Graph (append-only signed relationship claims, @xyo-network/xl1-statement-graph-*) and other application substrates that are not core chain; xl1-dapp-kit (6) — when adopting the portable headless application contracts (@xyo-network/dapp-kit*); xl1-testing (7) — when verifying chain interactions against a local chain or Sequence; xl1-scaffold (8) — when starting a new XL1 project

Payload schema and identity rules

Before defining payloads or choosing identity/commitment hashes, read Payload Schema Evolution and Identity. 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 <viewer>_<method> 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 for the rationale, the XL1 equivalents for each Ethereum method, and the structural grep self-check that gates "done." For dApps, the completion gate in xl1-testing walks the same check: dApp Definition of Done — Gateway & Chain Access.

Table of Contents

XL1 Chain

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

Read when building applications or services on XL1. Covers the Zod-first type pattern, Viewer/Runner architecture, providers (including providerId identity, MissingProviderIdError, and UnknownProviderError pins), validation, and the SDK package structure.

Identity & Wallets

Read when creating a wallet or signer in XL1 backend code (Node services, indexers, CLIs, tests). Covers the canonical generateXyoBaseWalletFromPhrase + derivePath('<index>') 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

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, and indexes the operator-side driver and S3 provider packages.

Gateway

Read when connecting to the XL1 chain — generic gateway concepts, viewer API, networks (including REST roots), transaction submission (options, confirmation, and crash-safe durable submission with the phased buildXl1Transaction … observeXl1TransactionFinality functions), transports, and how to run a gateway node. Environment-specific construction lives in two sibling files.

Browser Gateway

Read when integrating XL1 into any website — React dApps, plain pages, workers, service workers, and browser extensions. @xyo-network/xl1-browser-system is the preferred integration substrate and REST is the preferred transport; React dApps reach it through InPageGatewaysProvider with transport="rest" rather than launching a browser system directly. Also covers the Chrome wallet extension, WalletGatewayProvider / GatewayProvider, and useProvidedGateway. UX patterns built on top of the gateway live in Browser UX.

Node Gateway

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), owned gateway sessions (buildSession() / buildRunnerSession() and stop() for clean shutdown), the seed-phrase signer pattern, the lazy-promise caching pattern, and the basicRemoteViewerLocator escape hatch.

Finalized block stream

Read when an indexer or service needs ordered finalized delivery (FinalizedBlockStream / finalizedBlockStreamFromGateway); prefer it over the deprecated headUpdated. A section of Gateway.