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

# @xyo-network/xl1-s3-providers

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

> S3 providers (publishers and viewers) for the XL1 static REST layout.

## Description

XL1 is the XYO Layer One blockchain protocol. This package publishes finalized
chain data to the static REST file layout consumed by XL1 REST viewers. It is
designed for Node services that materialize finalized blocks, payloads, indexes,
chain state, and datalake objects into S3-compatible storage.

This package replaces the deprecated `@xyo-network/xl1-s3-publishers` and
`@xyo-network/xl1-rest-block-publisher` packages.

## Install

Using npm:

```sh
npm i --save @xyo-network/xl1-s3-providers
```

Using yarn:

```sh
yarn add @xyo-network/xl1-s3-providers
```

Using pnpm:

```sh
pnpm add @xyo-network/xl1-s3-providers
```

Using bun:

```sh
bun add @xyo-network/xl1-s3-providers
```

This package is Node-only and expects an `@aws-sdk/client-s3` `S3Client`.

## Usage

Publish finalized blocks and update chain state after the block files exist:

```ts
import { S3Client } from '@aws-sdk/client-s3'
import {
  S3BlockPublishRunner,
  S3ChainStatePublishRunner,
  S3IndexPublishRunner,
} from '@xyo-network/xl1-s3-providers'

const client = new S3Client({
  region: 'auto',
  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
  credentials: { accessKeyId, secretAccessKey },
})

const blocks = await S3BlockPublishRunner.create({ bucket: 'blocks', client, context, source })
const index = await S3IndexPublishRunner.create({ bucket: 'indexes', client, context, source })
const chainState = await S3ChainStatePublishRunner.create({ bucket: 'state', client, context })

const range = await blocks.sync()
if (range) {
  for (let n = range[0]; n <= range[1]; n++) await index.publishStepsCompletedBy(n)
  await chainState.publishHead()
}
```

Write head pointers last so readers never observe a head that references missing
block or index files.

`S3ChainStatePublishRunner` resolves its authoritative finalized head from the
`BlockViewer` registered in `context.locator`, and resolves chain-contract metadata
from the registered `ChainContractViewer`. `ChainStateViewer` reads the already-published
head and must not be used as the publisher's source.

## Documentation

Exports include:

- `S3BlockPublishRunner` - finalized block and payload publisher.
- `S3IndexPublishRunner` - completed-step summary publisher.
- `S3ChainStatePublishRunner` and `S3ChainStateViewer` - chain head writer and authenticated reader.
- `S3DataLakePublishRunner` - datalake payload publisher.
- `AbstractS3Provider`, `encodeBody`, and `decodeBody` - shared implementation utilities.

See `packages/protocol/STATIC_REST_LAYOUT.md` for the path layout consumed by
REST viewers.

## 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-s3-providers
pnpm xy test @xyo-network/xl1-s3-providers
pnpm xy lint @xyo-network/xl1-s3-providers
```

## 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-s3-providers.svg
[npm-link]: https://www.npmjs.com/package/@xyo-network/xl1-s3-providers
[license-badge]: https://img.shields.io/npm/l/@xyo-network/xl1-s3-providers.svg
[license-link]: ./LICENSE
[logo]: https://cdn.xy.company/img/brand/XYO_full_colored.png