@xyo-network/xl1-s3-providers

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:

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

Using yarn:

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

Using pnpm:

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

Using bun:

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:

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:

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

License

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

Credits

Made with 🔥 and ❄️ by XYO Foundation