@ariestools/chain-serve-local-s3

Dev/test only. Boots an ephemeral local XL1 environment for integration and e2e tests. Not for production.

One function call starts:

1. @ariestools/aries-chain-serve — S3-compatible published-chain layout (/blocks, /state, /indexes) via s3rver
2. @xyo-network/xl1-cli — api + producer + finalizer + mempool + indexer, publishing finalized blocks and index into that layout

Install

pnpm add -D @ariestools/chain-serve-local-s3

Pulls in @ariestools/aries-chain-serve, @xyo-network/xl1-cli, and @xyo-network/xl1-sdk as runtime dependencies.

Single-call usage

import { startLocalS3Chain } from '@ariestools/chain-serve-local-s3'

const chain = await startLocalS3Chain()

// chain.rpcUrl              http://127.0.0.1:<port>/rpc
// chain.apiPort
// chain.chainId
// chain.blockProducerWallet // path 0 of the insecure test mnemonic
// chain.s3Endpoint          s3rver origin
// chain.s3ReadUrls          { finalized, chainState, index }

await chain.stop()

Vitest setupFile (lifehash-style globals)

// test/setup/api-local-s3.ts
import { afterAll, beforeAll } from 'vitest'
import { registerLocalS3Chain } from '@ariestools/chain-serve-local-s3'

registerLocalS3Chain(
  { beforeAll, afterAll },
  { assignGlobals: true },
)

With assignGlobals: true, specs can read:

| Global | Description | | -------------------- | ------------------------------------------------ | | apiPort | XL1 API port | | rpcUrl | http://127.0.0.1:<port>/rpc | | chainId | Local chain id | | blockProducerWallet| Genesis / producer path-0 account | | s3ReadUrls | { finalized, chainState, index } read base URLs| | s3Endpoint | s3rver base URL |

Options

| Option | Default | | ----------------- | -------------------------------------------- | | apiPort | 8080 + VITEST_WORKER_ID (or free fallback) | | chainId | local-dev fixture id | | mnemonic | insecure test test … junk phrase | | healthTimeoutMs | 120_000 | | assignGlobals | false | | silent | true (s3rver) | | logXl1 | true (child logs → stderr) |

Notes

• The local API serves /rpc only (no REST datalake). Writers typically run in inline mode; body resolution on the read side is up to the test.
• S3 credentials accepted by the layout: S3RVER / S3RVER (exported as S3_CREDENTIALS).
• Parallel vitest workers get distinct preferred API ports via VITEST_WORKER_ID; Prometheus and health-check ports are disabled in the child config to avoid clashes.