[![logo][]](https://xyo.network)

# @xyo-network/xl1-sdk

[![npm-badge][]][npm-link]
[![license-badge][]][license-link]

> 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:

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

Using yarn:

```sh
yarn add @xyo-network/xl1-sdk
```

Using pnpm:

```sh
pnpm add @xyo-network/xl1-sdk
```

Using bun:

```sh
bun add @xyo-network/xl1-sdk
```

## Usage

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

```ts
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:

```ts
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](https://skills.sh):

```sh
npx skills add XYOracleNetwork/xyo-skills --all
```

In XY toolchain repos, the equivalent convenience command is:

```sh
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

```sh
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](./LICENSE) file for license rights and limitations
(LGPL-3.0-only).

## Credits

[Made with 🔥 and ❄️ by XYO Foundation](https://xyo.network)

[npm-badge]: https://img.shields.io/npm/v/@xyo-network/xl1-sdk.svg
[npm-link]: https://www.npmjs.com/package/@xyo-network/xl1-sdk
[license-badge]: https://img.shields.io/npm/l/@xyo-network/xl1-sdk.svg
[license-link]: ./LICENSE
[logo]: https://cdn.xy.company/img/brand/XYO_full_colored.png
