EffectStream

https://effectstream.github.io/docs/
Admin
EffectStream is a modular Web3 engine and sovereign rollup framework for building multi-chain...
Tokens:359,342
Snippets:2,885
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and Run Development Environment

Source: https://effectstream.github.io/docs/home/templates/shinkai

Commands to install dependencies and start the development server.

```bash
bun install  

bun run dev  
```

--------------------------------

### Start Backend Service

Source: https://effectstream.github.io/docs/home/templates/zswap-da

Commands to clone, install, and start the backend service.

```bash
git clone git@github.com:effectstream/zswap-offerfiles-kernel.git zswap-offerfile-kernel  

cd zswap-offerfile-kernel  

bun install  

bun run dev
```

--------------------------------

### Start Frontend Service

Source: https://effectstream.github.io/docs/home/templates/zswap-da

Commands to install and start the frontend development server.

```bash
cd effectstream/templates/zswap-da  

bun install  

bun run dev
```

--------------------------------

### Initialize and start the runtime

Source: https://effectstream.github.io/docs/home/packages/node/runtime

Example of using init() and start() within an Effection main() function to boot the runtime with a configuration.

```typescript
import { main } from "effection";  

import { init, start } from "@effectstream/runtime";  

import { Stm } from "@effectstream/sm";  

import { config } from "./config.dev.ts";  

  

await main(function* () {  

  yield* init();  

  

  const gameStm = new Stm(grammar);  

  gameStm.addStateTransition("join", function* () { /* ... */ });  

  

  yield* start({  

    config,  

    gameStateTransitions: [gameStm],  

    apiRouter: undefined,           // optional Fastify route plugin  

    migrations: [],                 // SQL migrations  

  });  

});  
```

--------------------------------

### Get started: clone, install, and run

Source: https://effectstream.github.io/docs/blog/farcaster-template

Commands to clone the farcaster-app repository, install dependencies with bun, and run the development server. After replacing the four game files, 'bun run dev' boots PGLite, the local chain, the node, and the frontend. For Cardano, apply the config diff and the same command switches to YACI DevKit and Dolos.

```bash
git clone https://github.com/effectstream/farcaster-app my-poll  
cd my-poll  
bun install  

# Replace the four game files, then:  
bun run dev  

```

--------------------------------

### Run the demo: install dependencies and build contracts

Source: https://effectstream.github.io/docs/home/templates/wallets

Commands to install dependencies, build EVM contracts, deploy standalone, compile Midnight contracts, and start the EVM dev server. Run these in the project root.

```bash
bun i  

bun run --cwd e2e/shared/contracts/evm build  

bun run --cwd e2e/shared/contracts/evm deploy:standalone  

bun run --cwd e2e/shared/contracts/midnight midnight-contract:compile  

bun run --cwd e2e/evm dev  

```

--------------------------------

### Install and Launch Stack

Source: https://effectstream.github.io/docs/home/templates/solana-starter

Commands to install dependencies and start the full development stack including PGLite, the counter program, and the Solana validator.

```bash
bun install

# Launch the full stack: PGLite, counter-program build check, solana-test-validator
# with counter.so preloaded, batcher airdrop, sync node, batcher, frontend.
bun run dev
```

--------------------------------

### Run the preorder template

Source: https://effectstream.github.io/docs/blog/cardano-onchain-preorder-validator

Commands to navigate to the template directory, install dependencies, and start the development environment.

```bash
cd templates/preorder  

bun install  

bun run dev   # PGLite + Hardhat + YACI DevKit + Dolos + sync node + frontend
```

--------------------------------

### Start the delegation sync node and pool-aware batcher

Source: https://effectstream.github.io/docs/blog/stakepool-delegation-batcher

Commands to clone the repository, install dependencies, and start the delegation sync node and the pool-aware batcher adapter.

```bash
# Terminal 1: Start the delegation sync node  

git clone https://github.com/effectstream/effectstream.git  

cd effectstream/templates/cardano-delegation  

bun install  

bun run dev  

# Sync node indexes delegations → http://localhost:10599  

  

# Terminal 2: Start the pool-aware batcher  

# Code lives in PR #691: https://github.com/effectstream/effectstream/pull/691  

# Check out that PR branch and run its batcher entrypoint.
```

--------------------------------

### Launch local Avail node and light client with launchAvail

Source: https://effectstream.github.io/docs/home/chains/avail

Starts a local Avail node and an Avail Light Client connected to it. Requires implementing scripts in package.json as noted. The example is from start.dev.ts.

```typescript
// in start.dev.ts  
import path from "node:path";  
import { launchAvail } from "@effectstream/orchestrator/launch-avail";  

const root = import.meta.dirname!;  

export default {  
  processes: [  
    ...launchAvail("@my-project/avail-contracts", {  
      cwd: path.join(root, "packages/contracts-avail"),  
    }),  
  ],  
} satisfies OrchestratorConfig;  

```

--------------------------------

### Run the Cardano template

Source: https://effectstream.github.io/docs/blog/cardano-primitives

Commands to clone the repository, navigate to a specific template directory, install dependencies, and start the development environment.

```bash
git clone https://github.com/effectstream/effectstream.git  

cd effectstream/templates/projected-nft-preorder   # or cardano-delegation  

bun install  

bun run dev  
```

--------------------------------

### Clone and run the preorder template with Bun

Source: https://effectstream.github.io/docs/home/templates/preorder

Clones the repository, installs dependencies, and starts the local development stack. `bun run dev` is `NODE_ENV=development bunx orchestrator start`, which reads `start.dev.ts` and brings up all services in dependency order.

```bash
git clone https://github.com/effectstream/effectstream.git  

cd effectstream/templates/preorder  

  

bun install          # standalone; inside the monorepo run ./link.sh instead  

bun run dev          # boots the whole local stack
```

--------------------------------

### Build and run with Docker

Source: https://effectstream.github.io/docs/home/templates/evm-midnight

Builds and runs the Docker image, which installs Bun, Node, Foundry, and Compact, pre-warms the solc cache, and starts the orchestrator. On Apple Silicon, set DOCKER_DEFAULT_PLATFORM to linux/amd64. The test suite runs inside the container with `bun run test`.

```bash
# On macOS Apple Silicon  

export DOCKER_DEFAULT_PLATFORM=linux/amd64  

  

docker build -f ./Dockerfile . -t evm-midnight  

docker run -p 10599:10599 -p 9999:9999 -p 8545:8545 -p 8546:8546 \  

           -p 8088:8088 -p 6300:6300 -p 9944:9944 -p 4747:4747 evm-midnight  

  

# Run the test suite inside the container  

docker run evm-midnight bun run test  
```

--------------------------------

### Clone and Run Development Environment

Source: https://effectstream.github.io/docs/home/templates/batcher-validations

Commands to clone the repository, install dependencies, and start the development services including PGLite, Hardhat, sync node, batcher, and frontend.

```bash
git clone https://github.com/effectstream/effectstream.git

cd effectstream/templates/batcher-validations

  

bun install          # standalone; inside the monorepo run ./link.sh instead

bun run dev          # PGLite, Hardhat + deploy, sync node, batcher, frontend
```

--------------------------------

### Clone and run the template with link.sh and bun run dev

Source: https://effectstream.github.io/docs/home/templates/projected-nft-preorder

Clones the effectstream repository, navigates to the projected-nft-preorder template, runs link.sh to install dependencies and symlink local packages, then starts the development environment with bun run dev. The first run downloads the YACI DevKit and Cardano node, so it takes longer.

```bash
git clone https://github.com/effectstream/effectstream.git  

cd effectstream/templates/projected-nft-preorder  

  
# Inside the monorepo, use link.sh — it installs npm deps and then symlinks  
# every @effectstream/* package to its local source. Standalone copies of the  
# template use `bun install` instead.  
./link.sh  

  
# Starts PGLite, YACI DevKit and Dolos; mints a test NFT and writes the  
# Hololocker script hash; then starts the sync node and the frontend.  
bun run dev  

```

--------------------------------

### HTTP Start Event Listener Example

Source: https://effectstream.github.io/docs/home/components/batcher/advanced-topics

Example listener for the http:start event.

```typescript
batcher.addStateTransition("http:start", ({ port }) => {  

  console.log(`🌐 HTTP API: http://localhost:${port}`);  

  console.log(`📖 Docs: http://localhost:${port}/documentation`);  

});  
```

--------------------------------

### Start the proof server with bunx

Source: https://effectstream.github.io/docs/home/packages/binaries/midnight-proof-server

Run this command to start the proof server. It will download the binary on the first run.

```shell
# Start the proof server (downloads the binary on first run)  

bunx npm-midnight-proof-server  
```

--------------------------------

### Batch Process Start Event Listener Example

Source: https://effectstream.github.io/docs/home/components/batcher/advanced-topics

Example listener for the batch:process:start event.

```typescript
batcher.addStateTransition("batch:process:start", ({ target, inputCount }) => {  

  console.log(`⚙️ Processing ${inputCount} inputs for ${target}`);  

  metrics.increment("batcher.batch.start", { target });  

});  
```

--------------------------------

### GET /queue-stats cURL Example

Source: https://effectstream.github.io/docs/home/components/batcher/advanced-topics

Example cURL command to retrieve queue statistics.

```bash
curl http://localhost:3334/queue-stats  
```

--------------------------------

### GET /status cURL Example

Source: https://effectstream.github.io/docs/home/components/batcher/advanced-topics

Example cURL command to retrieve the batcher status.

```bash
curl http://localhost:3334/status  
```

--------------------------------

### Setup and run IPP application components

Source: https://effectstream.github.io/docs/blog/ipp-clinical-records-cardano

Commands to clone the repository and initialize the Cardano node, backend, web viewer, and iOS project.

```bash
git clone https://github.com/effectstream/ipp-app  

cd ipp-app  

# Cardano - local node + indexer + sync node, all on one machine  

cd cardano && bun install && bun run dev  

# Backend (separate terminal)  

cd ../backend && cp .env.example .env   # set DATABASE_URL; CHAIN=cardano  

bun install && bun run dev               # http://localhost:3334  

# Web viewer (separate terminal)  

cd ../web && bun install && bun run dev   # http://localhost:5174  

# iOS app  

cd ../ios && xcodegen generate && open IPP.xcodeproj
```

--------------------------------

### Startup Event Listener Example

Source: https://effectstream.github.io/docs/home/components/batcher/advanced-topics

Example listener for the startup event.

```typescript
batcher.addStateTransition("startup", ({ publicConfig }) => {  

  console.log(`🚀 Batcher started on port ${publicConfig.port}`);  

  console.log(`   Default target: ${publicConfig.defaultTarget}`);  

  console.log(`   Adapters: ${publicConfig.adapterTargets.join(", ")}`);  

});  
```

--------------------------------

### Example API response row

Source: https://effectstream.github.io/docs/home/templates/evm-midnight

Example JSON response from GET /api/erc721 showing a token with its owner, block height, and a property.

```JSON
[{"token_id":"111","owner":"","block_height":1395,"property_name":"Name","value":"Starlight Bridge Token","property_block_height":1395}]
```

--------------------------------

### Instantiate and Launch Batcher

Source: https://effectstream.github.io/docs/home/components/batcher/configuration

Step 2 of the unified configuration approach, demonstrating how to initialize storage and start the batcher instance.

```typescript
const storage = new FileStorage("./batcher-data");  

const batcher = createNewBatcher(config, storage);  

await batcher.init();
```

--------------------------------

### Install @effectstream/event-client

Source: https://effectstream.github.io/docs/home/packages/sdk/event-client

Installation commands for Bun and npm.

```bash
bun add @effectstream/event-client  

# or  

npm install @effectstream/event-client
```

--------------------------------

### Complete Batcher Setup with Effection

Source: https://effectstream.github.io/docs/home/components/batcher/overview

This example shows the complete setup for the Effectstream Batcher. It creates an EffectstreamL2DefaultAdapter with a contract address, private key, fee, and sync protocol name. Then it creates a Batcher with polling interval, port, HTTP server, event system, and empty adapters, using FileStorage. The adapter is added with hybrid criteria (time window and max batch size) and set as default target. State transitions for 'startup' and 'batch:submit' are added for monitoring. Finally, the batcher is run with Effection's main and suspend.

```typescript
import { main, suspend } from "effection";  

import { Batcher, FileStorage, EffectstreamL2DefaultAdapter } from "@effectstream/batcher-sdk";  

  

// 1. Create adapter  

const adapter = new EffectstreamL2DefaultAdapter(  

  "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",  // Contract address  

  process.env.PRIVATE_KEY!,                       // Private key  

  0n,                                              // Fee  

  "mainEvmRPC"                                     // Sync protocol name  

);  

  

// 2. Create batcher  

const batcher = new Batcher({  

  pollingIntervalMs: 1000,  

  port: 3334,  

  enableHttpServer: true,  

  enableEventSystem: true,  

  adapters: {}  // Start empty, add dynamically  

}, new FileStorage("./batcher-data"));  

  

// 3. Wire adapter with criteria  

batcher.addBlockchainAdapter("ethereum", adapter, {  

  criteriaType: "hybrid",  

  timeWindowMs: 5000,  

  maxBatchSize: 50  

}).setDefaultTarget("ethereum");  

  

// 4. Add monitoring  

batcher.addStateTransition("startup", ({ publicConfig }) => {  

  console.log(`🚀 Batcher started on port ${publicConfig.port}`);  

});  

  

batcher.addStateTransition("batch:submit", ({ txHash }) => {  

  console.log(`🚀 Batch submitted: ${txHash}`);  

});  

  

// 5. Run with Effection  

main(function* () {  

  yield* batcher.runBatcher();  

  yield* suspend();  

});  

  

```

--------------------------------

### GET /health Request

Source: https://effectstream.github.io/docs/home/components/batcher/advanced-topics

Example cURL command to check the health of the service.

```bash
curl http://localhost:3334/health
```

--------------------------------

### Install @effectstream/frontend-sdk

Source: https://effectstream.github.io/docs/home/packages/tools/frontend-sdk

Commands to install the package using bun or npm.

```bash
bun add @effectstream/frontend-sdk  

# or  

npm install @effectstream/frontend-sdk
```

--------------------------------

### Install Foundry (forge)

Source: https://effectstream.github.io/docs/home/templates/evm-midnight

Installs Foundry, which provides the `forge` compiler required to compile Solidity artifacts. The orchestrator checks for `forge` on PATH and refuses to start without it.

```bash
curl -L https://foundry.paradigm.xyz | bash && foundryup  
```

--------------------------------

### Start Grafana Loki with config file

Source: https://effectstream.github.io/docs/home/packages/binaries/grafana-loki

Start Loki with a config file using bunx, or invoke through the package with bun run. The package installs a pinned binary into node_modules/.bin/grafana-loki.

```bash
# Start Loki with a config file  

bunx grafana-loki -config.file=loki.yaml  

  

# Or invoke through this package  

bun run --bun @effectstream/grafana-loki/start  
```

--------------------------------

### Operation: runHttpServer

Source: https://effectstream.github.io/docs/home/components/batcher/advanced-topics

Starts only the HTTP server, useful for custom setups where polling is not required.

```javascript
main(function* () {  

  yield* call(() => batcher.storage.init());  

  yield* batcher.runHttpServer();  // Just HTTP, no polling  

  yield* suspend();  

});
```

--------------------------------

### Run the demo: start wallets UI in another terminal

Source: https://effectstream.github.io/docs/home/templates/wallets

Run this command in a separate terminal to start the wallets UI dev server.

```bash
bun run --cwd e2e/wallets-ui dev  

```

--------------------------------

### Define and register a database migration with start(...)

Source: https://effectstream.github.io/docs/home/effectstream-engine/database

These three files define and register a database migration: the SQL creates the `inputs_log` table in the `public` schema, the migration-order file pairs the SQL text with a name, and the node entry point passes the migration table to `start(...)`. The engine applies any unrun migrations in array order during startup.

```sql
CREATE TABLE inputs_log (  
  id SERIAL PRIMARY KEY,  
  signer TEXT NOT NULL,  
  payload JSONB NOT NULL,  
  block_height INTEGER NOT NULL  
);  
```

```typescript
import type { DBMigrations } from "@effectstream/runtime";  
import initSql from "./migrations/000-init.sql" with { type: "text" };  
  
export const migrationTable: DBMigrations[] = [  
  { name: "000-init.sql", sql: initSql },  
];  
```

```typescript
import { migrationTable } from "@my-app/database";  
  
yield* start({  
  appName: "my-app",  
  appVersion: "1.0.0",  
  syncInfo: toSyncProtocolWithNetwork(config),  
  migrations: migrationTable,  
  // …grammar, gameStateTransitions, apiRouter  
});  
```

--------------------------------

### Install @effectstream/npm-avail-light-client with bun or npm

Source: https://effectstream.github.io/docs/home/packages/binaries/avail-light-client

Install the package using bun add or npm install. The package downloads the pinned light-client binary for your OS/arch during install.

```bash
bun add @effectstream/npm-avail-light-client  

# or  

npm install @effectstream/npm-avail-light-client  
```

--------------------------------

### Node Startup Sequence

Source: https://effectstream.github.io/docs/quick-start

Example of the main function used to initialize and start the EffectStream node with specific configuration parameters.

```typescript
main(function* () {  

  yield* init();  

  

  yield* withEffectstreamStaticConfig(localhostConfig, function* () {  

    yield* start({  

      appName: "My-dApp",  

      appVersion: "1.0.0",  

      syncInfo: toSyncProtocolWithNetwork(localhostConfig),  

      gameStateTransitions,  

      migrations,  

      apiRouter,  

      grammar,  

    });  

  });  

  

  yield* suspend();  

});
```

--------------------------------

### Basic Effection Batcher Implementation

Source: https://effectstream.github.io/docs/home/components/batcher/advanced-topics

A minimal example using main() to start the batcher and suspend() to keep the process alive.

```typescript
import { main, suspend } from "effection";

import { Batcher } from "@effectstream/batcher-sdk";



const batcher = new Batcher(config, storage);



main(function* () {

  // Run the batcher (starts HTTP server and polling)

  yield* batcher.runBatcher();

  

  // Keep the main operation alive

  yield* suspend();

});
```

--------------------------------

### Orchestrator CLI Usage Examples

Source: https://effectstream.github.io/docs/home/packages/tools/orchestrator

Common usage patterns for starting, restarting, and stopping processes using the orchestrator CLI.

```bash
orchestrator start hardhat deploy-evm-contracts  

orchestrator start --only=midnight-node,midnight-indexer  

orchestrator start --except=avail-client  

orchestrator start --silence=midnight-node,bitcoin-core  

orchestrator restart midnight-node  

orchestrator stop batcher  
```
Tokens:
Raw