@effectstream/sync 0.100.14 → 0.100.16

package/README.md

@@ -0,0 +1,73 @@
+# @effectstream/sync
+
+The blockchain-sync service inside an EffectStream node. Reads finalized
+blocks from every chain you've configured (EVM, Bitcoin, Cardano, Midnight,
+Avail, Celestia, NEAR…), normalizes them into a single rollup ordering,
+and stages the inputs the state machine consumes.
+
+- Blockchain-sync service: reads finalized blocks from every configured chain.
+- Normalises into a single rollup ordering and stages inputs for the state machine.
+- Drop-in fetchers: EVM, Bitcoin, Cardano UTXO-RPC, Midnight, Avail, Celestia, NEAR, NTP.
+- `genSyncProtocols(config)` is what the runtime calls during boot.
+
+## Install
+
+```bash
+bun add @effectstream/sync
+# or
+npm install @effectstream/sync
+```
+
+## Usage
+
+This package pairs with [`@effectstream/runtime`](https://www.npmjs.com/package/@effectstream/runtime),
+which boots sync as part of `start()`: it calls `genSyncProtocols(...)`
+against the `syncProtocols` section of your
+[`@effectstream/config`](https://www.npmjs.com/package/@effectstream/config),
+then drives the resulting fetcher + state pairs every block. As an app
+author you declare which protocols to sync in your config; everything
+else runs automatically.
+
+If you're building a new chain integration, implement the sync-protocol
+interfaces in [`src/sync-protocols/`](https://github.com/effectstream/effectstream/tree/main/packages/node-sdk/sync/src/sync-protocols).
+
+## Inside EffectStream
+
+`genSyncProtocols(config)` is what the runtime calls during boot. It walks
+the `syncProtocols` section of your `@effectstream/config`, instantiates a
+fetcher for each chain (viem for EVM, UTXORpc for Cardano, the Midnight
+SDK for Midnight, etc.), and writes paginated blocks into PostgreSQL
+through `@effectstream/db`. The state machine then drains that queue.
+
+```typescript
+import { genSyncProtocols } from "@effectstream/sync";
+// inside the runtime startup path:
+const protocols = await genSyncProtocols(config);
+// protocols.parallelEvmRPC_fast.runOne()  // poll one block
+```
+
+## Key exports
+
+- `genSyncProtocols(dbConn, syncInfo)` — Effection generator that instantiates a runtime fetcher + state pair for every protocol in `syncInfo` (from `config.syncProtocols`). Called from the runtime's process-blocks loop.
+- `AllSyncProtocols` — union type covering every supported protocol; useful when authoring config that fans out.
+- `ChainBlock`, plus base `Fetcher`/`State` types from `sync-protocols/base/` — the wire shape per chain.
+
+Per-chain `Fetcher` / `SyncState` classes (`EvmFetcher`,
+`BitcoinFetcher`, `MidnightFetcher`, `AvailFetcher`, `UtxoRpcFetcher`,
+`NtpFetcher`, `CelestiaFetcher`, `NearFetcher`, and matching `*SyncState`
+classes) are exported but are internal to the factory wiring —
+application code drives them through `genSyncProtocols` rather than
+instantiating them directly. Reach for them only if you're writing a
+custom orchestration layer.
+
+## Examples
+
+End-to-end sync test (boots a node, reads blocks, asserts the DB):
+[`e2e/evm/sync/`](https://github.com/effectstream/effectstream/tree/main/e2e/evm/sync).
+
+Runnable: [`test/examples.test.ts`](./test/examples.test.ts).
+
+## Links
+
+- Docs: https://effectstream.github.io/docs/packages/node/sync
+- Source: https://github.com/effectstream/effectstream/tree/main/packages/node-sdk/sync

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/sync",
-  "version": "0.100.14",
+  "version": "0.100.16",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,10 +13,10 @@
   },
   "exports": "./src/mod.ts",
   "dependencies": {
-    "@effectstream/config": "0.100.14",
-    "@effectstream/db": "0.100.14",
-    "@effectstream/log": "0.100.14",
-    "@effectstream/utils": "0.100.14",
+    "@effectstream/config": "0.100.16",
+    "@effectstream/db": "0.100.16",
+    "@effectstream/log": "0.100.16",
+    "@effectstream/utils": "0.100.16",
     "@midnight-ntwrk/ledger-v8": "8.0.3",
     "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "4.0.2",
     "@midnight-ntwrk/onchain-runtime": "npm:@midnight-ntwrk/onchain-runtime-v3@3.0.0",

package/test/examples.test.ts

@@ -0,0 +1,18 @@
+// Examples for the README — verify public exports resolve.
+
+import { test, expect } from "bun:test";
+import * as sync from "../src/mod.ts";
+
+test("README: genSyncProtocols is exported as a generator factory", () => {
+  expect(typeof sync.genSyncProtocols).toBe("function");
+});
+
+test("README: per-chain fetchers and states are exported", () => {
+  // A sampling of the protocols supported by the package.
+  expect("EvmFetcher" in sync).toBe(true);
+  expect("BitcoinFetcher" in sync).toBe(true);
+  expect("MidnightFetcher" in sync).toBe(true);
+  expect("AvailFetcher" in sync).toBe(true);
+  expect("UtxoRpcFetcher" in sync).toBe(true);
+  expect("CelestiaFetcher" in sync).toBe(true);
+});