@xyo-network/xl1-sdk

TypeScript gateway, provider, RPC, and SDK utilities for XL1.

Description

XL1 is the XYO Layer One blockchain protocol. This package is the primary non-React TypeScript SDK for XL1 services, CLIs, scripts, indexers, and tests.

It re-exports the protocol package and adds concrete gateway builders, remote and static REST viewers, JSON-RPC helpers, providers, wrappers, in-memory maps, and SDK utilities. React applications should usually start with @xyo-network/xl1-react-client-sdk.

Install

Using npm:

npm i --save @xyo-network/xl1-sdk

Using yarn:

yarn add @xyo-network/xl1-sdk

Using pnpm:

pnpm add @xyo-network/xl1-sdk

Using bun:

bun add @xyo-network/xl1-sdk

Usage

Build a read-only gateway from an XL1 RPC endpoint:

import { GatewayBuilder } from '@xyo-network/xl1-sdk/gateway'

const gateway = await new GatewayBuilder()
  .rpcUrl('https://beta.api.chain.xyo.network/rpc')
  .build()

const block = await gateway.connection.viewer.block.currentBlock()
console.log(block[0].block)

Build a read-only gateway from the static REST layout:

import { getRestGateway } from '@xyo-network/xl1-sdk/gateway'

const gateway = await getRestGateway('https://sample.mainnet.xyo.space')
const head = await gateway.connection.viewer.currentBlock()
console.log(head[0]._hash)

Documentation

Important subpaths:

• @xyo-network/xl1-sdk/gateway - GatewayBuilder, static REST gateway helpers, and signer wrapping.
• @xyo-network/xl1-sdk/protocol-sdk - config, services, wallet helpers, validation, and SDK primitives.
• @xyo-network/xl1-sdk/providers - concrete provider and locator implementations.
• @xyo-network/xl1-sdk/rpc - JSON-RPC schemas, transports, clients, servers, and handlers.
• @xyo-network/xl1-sdk/rest-block-viewer - static REST viewers for published chain data.
• @xyo-network/xl1-sdk/wrappers - chain and transaction wrappers.
• @xyo-network/xl1-sdk/driver-memory - in-memory map implementations.
• @xyo-network/xl1-sdk/test and @xyo-network/xl1-sdk/protocol-sdk/test - test helpers.

Use the SDK gateway APIs rather than hand-written JSON-RPC envelopes in applications. Raw RPC names are an implementation detail of the SDK and server packages.

deepCalculateFramesFromRange

Tile an arbitrary inclusive block range into the fewest largest step-aligned frames (StepSizes), then smaller remainders, then single-block frames. Export:

deepCalculateFramesFromRange(range, startingStep?) from @xyo-network/xl1-sdk/protocol-sdk (src/modules/protocol-sdk/block/primitives/frames/deepCalculateFramesFromRange.ts).

Use it whenever you need to cover a window with published step-summary files instead of walking block-by-block. Pass a family-specific cap as startingStep (e.g. blocksMaxStep for the blocks index). RestBlockViewer uses this for large blocksByNumber / blocksByHash walks: multi-block frames load via blocksByStep; only edge and in-flight leftovers use per-block GETs.

AI Agent Skills

Install the recommended XL1/XYO skills with Skills.sh:

npx skills add XYOracleNetwork/xyo-skills --all

In XY toolchain repos, the equivalent convenience command is:

pnpm xy skills defaults
pnpm xy skills lint --fix

For XL1 work, ask your agent to use xyo-knowledge, xl1-knowledge, and xl1-patterns. These skills cover XYO primitives, XL1 chain and gateway APIs, and application patterns for XL1 dApps.

Building Locally

pnpm xy build @xyo-network/xl1-sdk
pnpm xy test @xyo-network/xl1-sdk
pnpm xy lint @xyo-network/xl1-sdk

License

See the LICENSE file for license rights and limitations (LGPL-3.0-only).

Credits

Made with 🔥 and ❄️ by XYO Foundation