PRC-1: the achievement standard​

We created PRC-1 (Paima Request for Comment), a community standard similar to CIPs for Cardano or ERCs for Ethereum, but for the EffectStream game ecosystem. PRC-1 defines how games register, track, and expose achievements through a standard HTTP API.

The spec is published at effectstream/midnight-game-api-spec.

A game implementing PRC-1 exposes two endpoints:

• GET /achievements/public/list returns all achievements defined by the game (name, description, display metadata)
• GET /achievements/wallet/:wallet returns which achievements a specific player has earned, with timestamps and completion data

The achievement list response is a flat TypeScript shape — no chain-specific fields, no platform-specific fields:

interface AchievementPublicList {
  achievements: {
    name: string;              // Unique achievement ID, e.g. "speed_demon"
    displayName: string;       // Player-facing title
    description: string;       // How to unlock
    isActive: boolean;         // Currently unlockable?
    score?: number;            // Optional point value
    category?: string;         // Optional grouping ("Gold", "Diamond", ...)
    percentCompleted?: number; // Percentage of players who have it
    iconURI?: string;          // Badge image URL
    iconGreyURI?: string;      // Badge image URL when not yet earned
    spoiler?: 'all' | 'description'; // Hide details until unlocked
    startDate?: string;        // ISO8601, optional time-limited start
    endDate?: string;          // ISO8601, optional time-limited end
  }[];
}

Per-player completion follows a matching shape, keyed by achievement name with completion timestamps and optional incremental progress (progress / total). The full schema is in prc-1.md.

Any game that implements these endpoints is automatically discoverable by achievement portals, leaderboard aggregators, and third-party tools. The standard is intentionally minimal: it defines the interface, not the implementation. Games track achievements however they want internally; they just expose results through these endpoints.

PRC-6: Midnight dApp integration extension​

For games running on the midnight.fun portal, we extended PRC-1 with PRC-6 (the Midnight dApp Integration Interface). PRC-6 adds:

• Channels for categorizing content within a game (modes, seasons, maps)
• Leaderboards with ranked player standings per channel
• Metrics for game-level statistics (total players, active sessions, transaction volume)
• Identity resolution to map session wallets to main wallets via delegation, so achievements earned through auto-sign sessions get correctly attributed to the player's primary identity

PRC-6 is what powers the rich game cards on midnight.fun. Each game tile shows live player counts, leaderboard positions, and achievement progress, all pulled from the standard API.

A PRC-6 application advertises its metadata, achievements, and channels at a single root endpoint:

GET {BASE_URL}/metrics

{
  "name": "Cyber Drifter",
  "description": "High-octane neon racing.",
  "achievements": [
    {
      "name": "speed_demon",
      "displayName": "Speed Demon",
      "description": "Finish a lap under 60 seconds.",
      "isActive": true,
      "percentCompleted": 14.2
    }
  ],
  "channels": [
    { "id": "leaderboard", "name": "Lap Time",
      "scoreUnit": "Lap Time (s)", "sortOrder": "ASC" },
    { "id": "kos", "name": "Knock Outs",
      "scoreUnit": "KOs", "sortOrder": "DESC" },
    { "id": "volume", "name": "USD Volume",
      "scoreUnit": "USD Volume", "sortOrder": "DESC", "auth": true }
  ]
}

The platform reads this once per game and uses it to render the game card, then queries each channel and per-user profile as needed.

The interesting trick is identity resolution. A query on a session wallet returns the resolved main wallet's stats, with the delegation chain made explicit:

GET {BASE_URL}/metrics/users/mn_session_abc123?channel=leaderboard

{
  "identity": {
    "address": "mn_main_driftking",
    "delegatedFrom": ["mn_session_abc123"],
    "displayName": "DriftKing"
  },
  "achievements": ["speed_demon", "first_blood"],
  "channels": {
    "leaderboard": {
      "stats": { "score": 45.2, "rank": 1 }
    }
  }
}

A player using auto-sign may hold dozens of session wallets across a game's lifetime; the platform collapses them all back to one main wallet for reputation and leaderboard purposes.

The full PRC-6 spec, including all channel definitions, authentication rules, and snapshot vs. cumulative semantics, lives at prc-6.md.

Implementing it in a game​

The spec repository ships with a runnable reference server that implements every endpoint against in-memory fixtures. The /metrics route is a few lines of Fastify:

import Fastify from "fastify";
import { APP_NAME, APP_DESCRIPTION, ACHIEVEMENTS, CHANNEL_DEFS }
  from "./data/store.js";

const app = Fastify();

app.get("/metrics", async () => ({
  name: APP_NAME,
  description: APP_DESCRIPTION,
  achievements: ACHIEVEMENTS,    // your achievement definitions
  channels: CHANNEL_DEFS,        // your metric channels
}));

await app.listen({ port: 3000 });

There is no SDK to install. PRC-6 is just HTTP. A new game spending an afternoon on this gets discoverable on midnight.fun and queryable by every third-party tool that speaks the standard.

Live implementation: three games on midnight.fun​

PRC-1 and PRC-6 are implemented in three live games on the midnight.fun portal:

• Block Kart Legends - racing achievements (lap times, win streaks, distance milestones)
• Kachina Kolosseum - PvP combat achievements (victories, combos, rank progression)
• Safe Solver - puzzle achievements (completion speed, streak bonuses, difficulty tiers)

The screenshot shows the midnight.fun portal pulling data from all three games. Each game card displays live achievement counts and leaderboard positions, sourced from the PRC-1 and PRC-6 APIs. There's no centralized database here; the data lives in each game's node, and the portal queries it on the fly.

The walkthrough below shows the full earn-to-display loop: a player plays a game, unlocks an achievement, and the unlock surfaces immediately on the live leaderboard via the PRC-6 endpoints.

How it works under the hood​

When a player connects their wallet to midnight.fun, the portal queries each game's PRC-1 endpoint to fetch that player's achievements. Because the standard uses wallet addresses as the primary identifier, achievements are cross-game and cross-platform by default: any portal or app can query any PRC-1 game.

For games using auto-sign (session key delegation), PRC-6's identity resolution makes sure achievements don't get "lost" on temporary session wallets. The delegation chain maps session keys back to the player's main wallet, so everything gets attributed correctly no matter which signing method was used.

An open ecosystem​

Unlike platform-locked achievement systems (Steam, Xbox, PlayStation), PRC-1 achievements follow your wallet, not your platform account. Any app can aggregate achievements from any PRC-1 game. There's no central authority controlling the registry. And PRC-6 shows how you can extend the base standard for specific platforms without breaking compatibility.

The achievement system code is built into EffectStream. Any new game built with the framework gets PRC-1 support out of the box: define your achievements as data, and the framework handles tracking and the API. Every new game that adopts the standard makes the whole ecosystem richer.

The problem with wallet pop-ups​

Blockchain games need cryptographic signatures to prove that a player authorized each action. Without auto-sign, every game move triggers a wallet confirmation dialog ("Sign this transaction?"). The result is an experience that feels nothing like a game and everything like filling out forms. Real-time gameplay is basically impossible under these conditions.

How auto-sign works​

The core insight is separating two types of blockchain interactions:

• Financial transactions (asset transfers, token minting, contract calls with value) always require explicit wallet approval
• Non-financial data submissions (game moves, messages, state updates) can be safely delegated to a session key

When a player starts a session, their wallet generates a temporary key pair and signs a delegation certificate. This certificate authorizes the session key to submit non-financial data on the player's behalf. The session key is scoped (can only submit game data, never move funds), time-bounded (expires when the session ends), and revocable (the player can cancel delegation at any time).

This preserves the security guarantees players expect: nobody can move their assets without explicit approval. It just removes the friction that makes real-time apps unusable.

Implementation in @effectstream/wallets​

Auto-sign lives in the @effectstream/wallets package, which provides multi-chain wallet support for EffectStream applications. The package handles the full delegation lifecycle: key generation, certificate signing, session management, and automatic signing of non-financial transactions.

The wallet layer supports multiple chains (EVM via injected providers and Ethers, Cardano, Midnight, Polkadot, Algorand, and Mina), and auto-sign works across all of them through a unified API. Developers don't need chain-specific signing logic; the framework handles the differences. Full reference is in the wallets documentation.

The three-step flow in Safe Solver is representative of every game on midnight.fun:

import {
  WalletMode,
  walletLogin,
  allInjectedWallets,
} from "@effectstream/wallets";

// 1. Initialize a local session wallet, silent and persisted in
//    encrypted browser storage. preferBatchedMode enables auto-sign.
const localWalletResult = await walletLogin({
  mode: WalletMode.EvmEthers,
  preferBatchedMode: true,
  connection: {
    metadata: { name: "session", displayName: "Session Wallet" },
    api: await getLocalSignerFromStorage(),
  },
});

// 2. Let the user connect their real wallet (Midnight Lace in this
//    example) — this is the only step that shows a pop-up.
const injected = await allInjectedWallets({
  signatureSupport: false,
  transactionSupport: false,
});
const midnightWallet = injected[WalletMode.Midnight][0];
const realWalletResult = await walletLogin({
  mode: WalletMode.Midnight,
  preference: { name: midnightWallet.metadata.name },
});

// 3. One-time delegation: the real wallet signs a message
//    authorising the session wallet to submit non-financial inputs
//    on its behalf. After this point, gameplay is silent.
await effectStreamService.connectWallets(
  localWalletResult.result,
  realWalletResult.result,
);

// 4. Every subsequent game input is signed by the session wallet —
//    no pop-ups for the rest of the session.
await sendGameMove({ move: "x10y20" });

The signing model is uniform regardless of chain: WalletMode.Midnight could be swapped for WalletMode.EvmInjected, WalletMode.Cardano, or any other supported chain and the rest of the flow stays the same.

Live on midnight.fun​

Auto-sign is live and in production on midnight.fun, powering three games:

• Safe Solver - a puzzle game where auto-sign lets you submit moves rapidly
• Kachina Kolosseum - PvP combat where timing matters and pop-ups would ruin the experience
• Block Kart Legends - racing where dozens of state updates happen per session

The difference is immediately noticeable. Players approve wallet access once when connecting, then play freely. A typical Safe Solver session generates 20-30 signatures, all handled by the session key in the background.

Before and after​

Without auto-sign: Connect wallet → Start game → Pop-up → Approve → Make move → Pop-up → Approve → Make move → Pop-up → Approve → ... (player gives up after 3 moves)

With auto-sign: Connect wallet → Approve delegation → Play freely for the entire session → Done

The gameplay goes from "blockchain app with constant interruptions" to "normal game that happens to be on-chain." And it's not just games: chat apps, collaborative tools, IoT dashboards, anything that needs rapid interaction benefits from session key delegation. The security model (limited scope, time-bounded, revocable) applies to all of them.

Why a data availability layer?​

Every EffectStream application needs to post user actions somewhere persistent and verifiable. For low-frequency applications, the settlement chain (Cardano, EVM) works fine. But when your application generates hundreds or thousands of actions per minute (game moves, chat messages, sensor readings), posting each one as a settlement-layer transaction gets expensive fast.

A DA layer like Celestia provides an alternative: post high-throughput data cheaply to the DA layer, while settlement (asset transfers, contract state changes) stays on the main chain. EffectStream's state machine processes events from both layers without the developer having to think about it.

Celestia integration architecture​

The Celestia integration adds a new data path to EffectStream's batcher system. The batcher aggregates individual user submissions into batches and posts them to Celestia for data availability, while settlement transactions go to the configured settlement chain.

The integration lives in the bun-zswap-da template, which includes:

• Batcher that aggregates and posts batches to Celestia
• Database tracking submitted batches, token states, and offer lifecycle
• Frontend demo UI for interacting with the DA-backed application
• E2E tests verifying the full pipeline from user action to Celestia submission to state machine processing

How it works​

The batch processor submits data to Celestia and tracks each submission:

The backend database tracks the complete state (tokens, offers, batch references):

Parallel funnel architecture​

EffectStream uses a "funnel" abstraction to read data from multiple blockchains through a unified interface. The Celestia funnel runs in parallel with other chain funnels: Celestia blocks arrive independently from the settlement chain, so the funnel ingests them concurrently. No blocking, no waiting for one chain to catch up to another.

This matters for multi-chain apps. In a game that settles on Cardano but posts moves to Celestia, you don't want Cardano's block time to bottleneck your data layer. Both chains process at their native speed, and the state machine receives events from each as they arrive.

When to use a DA layer​

A DA layer makes sense when:

• High throughput: your app generates more data than the settlement layer can handle economically
• Low-value actions: individual actions don't need settlement-layer security (a game move isn't a financial transaction)
• Real-time requirements: you need sub-second data posting, not the settlement chain's block time

We learned this the hard way building Tarochi (an earlier EffectStream game): using EVM as the DA layer caused sync time issues as the chain of events grew. Moving high-frequency data to a purpose-built DA layer keeps the settlement chain lean, handling only the transactions that actually need its security.

Hybrid dApp pattern​

With Celestia support, developers can build hybrid applications:

The developer configures which data goes where, and the framework handles routing, batching, and event delivery.

• Celestia integration code (bun-zswap-da template)
• Celestia documentation

What a primitive is​

A primitive is a small contract between a chain and an application state machine:

1. A predicate that the indexer (Dolos via UTxORPC) evaluates server-side to filter transactions before they ever leave the gRPC stream.
2. A typed grammar — a TypeBox schema declaring the shape of the event the primitive emits.
3. An IVM (Indexed View Materializer) — a PostgreSQL materialised view definition that maintains a queryable snapshot of state as events arrive.
4. A state-machine prefix — every event the primitive emits routes to the application's addStateTransition(prefix, ...) handler under this name.

Five primitives ship with EffectStream today, all sharing the same architecture:

Source for all five lives in packages/node-sdk/sm/primitives/src.

Why this isn't just an indexer​

The temptation when wiring a new chain integration is to start with a generic block listener and write parsing logic in the application. That works once. By the second integration you're re-parsing UTXOs in two places; by the third you're trying to remember which event normalisation lives in which template.

The primitive pattern pushes three concerns down the stack:

• Filtering moves to the gRPC layer. Dolos evaluates the predicate before serialising — your application never sees a transaction it doesn't care about.
• Parsing moves into the primitive. The Hololocker datum, Conway delegation certificates, CIP-14 asset fingerprints — each gets parsed once, in the primitive, into a stable typed payload.
• State materialisation moves into Postgres. The IVM definition declares the table shape and the triggers; EffectStream keeps it consistent with the stream.

What's left in the application is the part you actually wanted to write: the state transition handler that decides what your game does when a delegation changes or an NFT gets locked.

Worked example: the Projected NFT primitive​

The CardanoProjectedNFT primitive is the densest of the five because the Hololocker contract has a non-trivial state machine — Lock, Unlocking (with a time-lock expiry), and Claim — and each of those transitions has to be reconstructed from raw inputs and outputs.

The grammar declares the typed payload:

export const projectedNftGrammar = [
  ["ownerAddress", Type.String()],
  ["previousTxId", Type.String()],
  ["previousOutputIndex", Type.String()],
  ["currentTxId", Type.String()],
  ["currentOutputIndex", Type.String()],
  ["policyId", Type.String()],
  ["assetName", Type.String()],
  ["status", Type.String()],     // "Lock" | "Unlocking" | "Claim"
  ["forHowLong", Type.String()], // time-lock expiry for Unlocking
] as const;

Wiring it into a config is a few lines:

.buildPrimitives(builder =>
  builder.addPrimitive(
    (sp) => sp.parallelUtxoRpc,
    () => ({
      name: "GameNFTLocker",
      type: PrimitiveTypeCardanoProjectedNFT,
      startBlockHeight: 1,
      stateMachinePrefix: "cardano-projected-nft",
      scriptHash: "abc123...",  // hololocker script hash
      network: "yaci",
    }),
  )
)

And the state machine subscribes by registering a handler against the prefix:

stm.addStateTransition("cardano-projected-nft", function* (data) {
  const { ownerAddress, policyId, assetName, status, forHowLong } =
    data.parsedInput;

  if (status === "Lock") {
    yield* World.resolve(grantPower, { address: ownerAddress, policyId });
  } else if (status === "Claim") {
    yield* World.resolve(revokePower, { address: ownerAddress, policyId });
  }
});

The primitive itself does the heavy lifting: walking tx.inputs and tx.outputs at the script address, parsing the Hololocker State datum, matching consumed inputs to produced outputs to detect state transitions, and emitting one event per transition. None of that logic appears in the game.

Why projected NFTs are the same architecture as pool delegation​

The CardanoPoolDelegation primitive was the first to ship under this pattern (as part of the stake pool delegation work). When we built CardanoProjectedNFT, almost everything carried over:

• Same UTxORPC parallel sync protocol (CARDANO_UTXORPC_PARALLEL).
• Same grammar + state-machine prefix mechanic.
• Same IVM scaffolding for the materialised view (UPSERT on transitions, DELETE on terminal events).
• Same handler signature on the state-machine side.

What differs is local: the predicate (has_certificate for delegation, has_address for the script), the payload (delegation triple vs. NFT lock state), the IVM trigger logic (replace-on-change vs. lock/unlocking/claim lifecycle), and the datum parser (no datum for delegation; a CBOR Plutus datum walk for Projected NFTs). The shared scaffold is what lets a new primitive be a few hundred lines of focused code rather than a multi-week integration.

The five primitives that ship today are the ones we needed for the templates we're building. Adding a sixth — Cardano voting, drep delegation, governance actions — would follow the same shape.

Running the template​

Each primitive is paired with a runnable template that exercises it end-to-end:

• templates/cardano-delegation — CardanoPoolDelegation + Stake Pool Delegation Explorer dApp
• templates/projected-nft-preorder — CardanoProjectedNFT + Hololocker lock/unlock/claim UI plus a campaign + marketplace state machine on top

Both templates start the same way:

git clone https://github.com/effectstream/effectstream.git
cd effectstream/templates/projected-nft-preorder   # or cardano-delegation
bun install
bun run dev

The orchestrator brings up PGLite, YACI DevKit, Dolos, the sync node, and the frontend together. Open the URL printed in the terminal and the primitive is live — every state transition emitted by the primitive is observable in the materialised view and surfaced on the frontend.

What this unlocks​

Once a chain has a primitive layer, the cost of adding a new on-chain integration drops to "implement the predicate + parser + IVM, then write the game logic." The five primitives that ship today cover the most common Cardano integration patterns — fungible transfers, native-asset lifecycle, mint/burn, stake-pool delegation, and projected-NFT custody. A new primitive can plug into the same machinery without touching the framework.

• All five Cardano primitives source
• Cardano Primitives reference docs
• Stake Pool Delegation post — the first primitive built on this architecture
• Projected NFTs post — the Hololocker dApp + ProjectedNFT primitive end-to-end
• cardano-delegation template
• projected-nft-preorder template

Two DA options: Avail and Celestia​

EffectStream ships generic DA primitives for both networks. They follow the same shape:

Both grammars are intentionally minimal:

// celestia-generic-grammar.ts (avail-generic-grammar.ts is identical in shape)
export const celestiaGenericGrammar = [
  ["payload", Type.Object({ suppliedValue: Type.String() })],
] as const;

The primitive's job is to watch its DA layer and deliver each posted blob to the state machine as a payload event. What the blob means is up to your application — that's the part you index.

In practice, when do you pick which?

• Avail has Substrate ergonomics — useful if your team already runs Substrate infra or wants account-model semantics on the DA side.
• Celestia has the most mature blob-namespace model and a wide light-node ecosystem — useful if you want anyone to verify your data without trusting a full node.

Both are interchangeable at the EffectStream layer: same grammar, same state-machine handler shape, only the config changes.

When a DA layer makes sense​

Settlement chains (Cardano, Arbitrum, etc.) are expensive per byte and slow per block. They are the right home for: asset transfers, contract state, anything where censorship-resistance and finality are load-bearing for the value being moved. They are the wrong home for: high-volume, low-value data where speed isn't critical but you still need verifiability.

Three patterns where a DA layer is the right choice:

1. Many small messages. Game moves, chat lines, IoT sensor readings, application logs. Each individual record isn't worth a settlement-chain transaction, but together they're the bulk of your application's data. Post them as DA blobs at hundreds-to-thousands per minute, settle only the things that move value.

2. Large blobs. Generated assets, ZK proof artefacts, encoded media, sealed game replays. Anything over a few kilobytes that you don't want sitting in settlement-chain calldata. DA layers handle these cheaply — settlement chains do not.

3. Cold storage with main-chain hashes. When the data itself doesn't need to live on the settlement chain, but its existence does. Post the blob to Avail/Celestia, post only the blob's hash (and any commitment) to Cardano/EVM. Anyone can verify the hash matches and pull the body from DA on demand. This is the right pattern for "we promised to keep this immutable" data that nobody reads often.

The shared property: speed is not the critical dimension. If you need a record to be visible to the application within one block, DA is wrong — use the settlement chain (or your L2's mempool). DA is for "eventually-visible, cheaply, in volume."

You must index what you posted​

A blob on Celestia or Avail is just bytes. Your application doesn't see those bytes until the state machine reads the primitive's event and writes a row to PostgreSQL. The indexer is the part of your application that turns blobs back into queryable state.

The state-machine handler does three things on every DA event:

1. Decode the blob into a typed record.
2. Validate it (signature, sequence, schema).
3. Write it to one or more tables keyed by something useful to the application.

Here's the minimal shape, wired against the Celestia generic primitive:

import { Stm } from "@effectstream/sm";
import { World } from "@effectstream/coroutine";
import { grammar } from "./grammar.ts";
import { insertDaRecord } from "@my-app/database";

const stm = new Stm<typeof grammar, {}>(grammar);

// "celestia-blobs" is the stateMachinePrefix declared in the primitive config.
stm.addStateTransition("celestia-blobs", function* (data) {
  const { suppliedValue } = data.parsedInput.payload;

  // 1. Decode — the blob is whatever your app posted (JSON, CBOR, protobuf...).
  let record: { kind: string; key: string; body: unknown };
  try {
    record = JSON.parse(suppliedValue);
  } catch {
    return; // malformed blob, skip
  }

  // 2. Validate — schema check, signature, idempotency, etc.
  if (!record.kind || !record.key) return;

  // 3. Index — one INSERT per blob keyed by something queryable.
  yield* World.resolve(insertDaRecord, {
    da_block_height: data.blockHeight,
    da_namespace: "celestia:my-app",
    record_kind: record.kind,
    record_key: record.key,
    record_body: JSON.stringify(record.body),
    posted_at: data.blockTimestamp,
  });
});

Swap "celestia-blobs" for "avail-blobs" and the handler is identical against the Avail primitive — that's the whole point of the matched grammar.

The table this writes to is the application's index:

CREATE TABLE da_records (
  id SERIAL PRIMARY KEY,
  da_block_height INTEGER NOT NULL,
  da_namespace TEXT NOT NULL,
  record_kind TEXT NOT NULL,
  record_key TEXT NOT NULL,
  record_body TEXT NOT NULL,
  posted_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX idx_da_records_kind_key
  ON da_records(record_kind, record_key);

Now the application can SELECT … WHERE record_kind = 'zswap' AND record_key = '0xabc...' and get the blob body back, sorted by DA block height, without re-reading the DA layer.

The two things to get right at this layer are idempotency (each DA blob should produce the same row on replay — keep (da_namespace, da_block_height, record_key) unique) and decode-failure tolerance (a malformed blob shouldn't halt the state machine — log it, skip it, move on).

Worked example: indexing ZSwap offers​

ZSwap is the concrete case the M2 template demonstrates. ZSwap offers are short JSON records — wallet, token in, token out, amounts, nonce, signature — typically a few hundred bytes each. A busy ZSwap market generates thousands of offers per hour. Three properties matter:

• Each offer is small (a few hundred bytes).
• The volume is high (orders of magnitude more than settlement-chain capacity).
• The data must be decentralised — offers are public, fillable by any participant, with no privileged operator.

A traditional settlement chain is the wrong home: per-byte cost is prohibitive at that volume. A centralised database is wrong for a different reason: any operator can censor offers. A DA layer is the right answer — every offer is publicly retrievable, cheap, and anyone with the namespace can verify the full offer book by reading directly from Celestia or Avail.

The bun-zswap-da template applies the indexing pattern above against a richer schema. Offers, batches, and settlement state each get their own table; the DA handler decodes blobs into offer records and writes them; settlement-chain events on the EVM side mark offers as filled or expired. The on-chain footprint is one batch reference per N offers; the rest is on the DA layer.

// State-machine slice from bun-zswap-da, simplified
stm.addStateTransition("zswap-offer", function* (data) {
  const offer = parseZswapOffer(data.parsedInput.payload.suppliedValue);
  if (!offer || !isSignatureValid(offer)) return;

  yield* World.resolve(insertOffer, {
    offer_id:        offer.id,
    wallet:          offer.wallet,
    token_in:        offer.tokenIn,
    token_out:       offer.tokenOut,
    amount_in:       offer.amountIn.toString(),
    amount_out:      offer.amountOut.toString(),
    da_block_height: data.blockHeight,
    da_namespace:    "celestia:zswap",
    status:          "open",
  });
});

The query surface on top of this is straightforward — "show me all open ZSwap offers for this token pair" becomes a single indexed SELECT, even though the underlying data lives on Celestia (or Avail) rather than in the application's own write path.

When NOT to use a DA layer​

The mirror-image of the three patterns above:

• One transaction is enough. If your application generates handful of records per hour and each one moves value, the settlement chain is simpler — no DA layer to keep healthy, no indexer to maintain, no extra namespace to fund.
• Real-time visibility is required. DA layers have their own block time and the indexer adds further delay. If a user needs to see a record reflected in application state within one settlement-chain block, DA is the wrong tool.
• The data is private. DA layers are public. A private payload still needs a settlement-side mechanism (encryption, ZK commitments) — DA alone gives you availability, not confidentiality.

The decision tree is short:

Is the data high-volume, low-individual-value, and verifiable rather than hidden? If yes, DA. If no, settle on the main chain or look at L2/ZK.

Wrap-up​

DA layers are a sharp tool, not a free upgrade. They unlock workloads that were previously stuck between "too expensive for settlement" and "too important for a private database" — but only if the data has a clear indexing strategy and a use-case where availability matters more than instant visibility. The same primitive abstraction in EffectStream covers both Avail and Celestia, so the architectural decision is whether to use DA at all; the network choice is a tactical one you can change later.

• Part 1: Celestia Data Availability — the integration architecture
• bun-zswap-da template (Celestia DA worked example)
• Avail Generic primitive source
• Celestia Generic primitive source

EVM-Cardano local development environment​

One of the biggest friction points for multi-chain developers is setting up a local dev environment. Syncing a Cardano indexer like Carp can take days on testnet and even longer on mainnet, which makes rapid iteration pretty much impossible. We built a template that replaces this entire workflow with an instant localhost setup.

The EVM-Cardano template, available in the monorepo, combines:

• Hardhat v3 for EVM smart contract development and a local EVM chain
• YACI DevKit for a local Cardano devnet
• Dolos with UTxORPC for Cardano indexing via gRPC

The result: spin up a full multi-chain dev environment (EVM + Cardano) in minutes, not days.

The template includes an explorer UI for interacting with the local environment. You can mint NFTs on EVM, send ADA on Cardano, and see cross-chain events in a unified feed:

This is a complete local dev environment for building cross-chain applications. Write smart contracts on both chains, test interactions between them, iterate fast. No testnet, no waiting for chain sync.

Controlling the stack: the orchestrator​

A multi-chain dev environment is not one process — it's six or seven, with dependencies between them: PGLite has to come up before the sync node, Dolos needs cardano-node, the contracts have to be deployed before the frontend can talk to them. We built bunx orchestrator as the master controller for this. It launches every process in dependency order, restarts individual ones, follows their logs, and silences the noisy ones, all from a single CLI.

$ bunx orchestrator --help

orchestrator — Bun-based process orchestration CLI

Usage:
  orchestrator <command> [options]

Commands:
  start   [config|name...]    Start all processes, or specific ones by name
  status                      Show status of running processes
  restart <name>              Restart a specific process by name
  stop    [name]              Stop a specific process (or all if no name given)
  list    [config]            List processes in config without starting them
  silence [name...]           Suppress terminal output for processes
  unsilence <name...>         Resume terminal output for processes
  logs    [name...]           Follow background daemon log files (like tail -f)

Global options:
  -c, --config  <path>        Config file (default: auto-detected)
  -h, --help                  Print help

Options for `start`:
  -b, --background            Run as a detached background daemon
  -p, --port    <n>           Orchestrator API port (default: 4747)
  -o, --only    <p1,p2,...>   Run only these processes (+ dependencies)
  -e, --except  <p1,p2,...>   Skip these processes
  -s, --serial                Launch one at a time instead of in parallel waves
  --no-deps                   Launch only named processes, skip dependency resolution
  --log-dir     <path>        Log directory when using -b (default: .orchestrator-logs)
  --no-api                    Disable the HTTP API server
  --silence     <p1,p2,...>   Suppress terminal output for these processes

Options for `status`:
  -f, --follow                Continuously refresh the status table (1s interval)

In practice, the developer workflow is just:

bunx orchestrator start              # bring up the whole stack
bunx orchestrator status             # see what's running and what failed
bunx orchestrator restart midnight-node   # bounce a single process
bunx orchestrator logs sync-node     # tail the logs of one process
bunx orchestrator stop               # tear everything down

The --only and --except flags let you run partial stacks — useful when you're iterating on the sync node and don't need the frontend rebuilding, or when you're testing the batcher in isolation. --background runs the whole orchestrator as a detached daemon with logs going to files, which is how the e2e test suite runs the same stack on CI.

The point is that the same bun run dev command that boots the EVM-Cardano template also boots the cardano-delegation template, the zk-cardano template, and every other template in the monorepo — they all share the orchestrator and just declare a different process graph in their config.

Game Maker integration​

Not every on-chain game needs to be built from scratch. We created a template that integrates EffectStream with Game Maker, one of the most popular 2D game engines. Game designers use familiar visual tools for gameplay while EffectStream handles the blockchain backend: on-chain state, wallet interactions, and multi-chain settlement.

The point here is that EffectStream isn't limited to web-based games. Any engine that can make HTTP calls can talk to an EffectStream backend, and Game Maker's event-driven architecture maps naturally to EffectStream's state machine model.

Farcaster Frame integration​

Farcaster Frames are mini-applications that run directly inside Farcaster's social feed. We built a template that turns an EffectStream game into a Frame, playable without leaving the feed. No app install required.

This is a completely different distribution model. Instead of "download our app and connect your wallet," it's "play this game right here in your feed." Every share is a playable instance. The social feed becomes the game platform.

• Template code

The integration handles the constraints of the Frame environment (limited UI real estate, server-side rendering requirements, Farcaster's auth model) while keeping full EffectStream backend functionality.

Mobile with GPS​

The most ambitious integration: a game template combining GPS location data for iOS and Android. Location-based gameplay where the assets you find, collect, and trade are real on-chain tokens.

The mobile app communicates with an EffectStream backend that manages on-chain state, while the mobile layer renders game objects at GPS-determined positions. It shows that EffectStream works well beyond the browser.

• Template code (paima-game-templates repository)

The common thread​

All templates are open-source in the game templates repository. The EVM-Cardano template with its Dolos-based local development stack is probably the most impactful: it removes the biggest barrier to Cardano development by getting rid of the sync time that's historically made local testing impractical.

• EVM-Cardano template code (Dolos + YACI DevKit)
• Cardano Primitives documentation

Safe Solver: multichain L2 on Arbitrum + Midnight​

Safe Solver is a fast, interactive puzzle game that runs multichain on Arbitrum and Midnight. It demonstrates EffectStream working as an L2 across both chains, with deterministic randomness derived per block and L2 interaction for game execution.

The game itself is a puzzle where players solve safe combinations on-chain. The random puzzle generation is deterministic per block, so all nodes reach the same result. EffectStream handles game logic and state transitions as an L2, while Arbitrum and Midnight provide the settlement layers. This is a good example of how a fast, interactive game can work on-chain without sacrificing responsiveness.

Most on-chain games either commit to a single chain or accept inconsistent state across chains. Safe Solver runs the same game logic over Arbitrum and Midnight blocks simultaneously, with EffectStream computing the deterministic result both chains independently agree on — and this multichain L2 pattern is the foundation the other four templates build on.

• Source code
• Play live

Kachina Kolosseum: multiplayer Midnight ZK game​

Kachina Kolosseum is a multiplayer PvP game built entirely on Midnight, demonstrating commit-reveal schemes written in Compact (Midnight's ZK language). All proofs are generated in the browser, so players don't need any backend infrastructure to play.

In PvP on a public blockchain, the second player has an inherent advantage: they can see the first player's move and counter it. The commit-reveal scheme in Compact fixes this. Both players commit their moves privately, then reveal simultaneously. ZK proofs verify the revealed move matches the original commitment without exposing it early. If someone refuses to reveal (griefing), a timeout kicks in and they forfeit. Proof generation happens client-side and completes in under a second.

The protocol is named after the academic work it builds on — Kachina: Foundations of Private Smart Contracts (Kerber, Kiayias, Kohlweiss; University of Edinburgh, 2020) and the extended 2021 manuscript, which formalises the model for private smart contracts that underlies Midnight's design. Kachina Kolosseum is the gameplay-shaped instantiation of those ideas: a trustless commit-reveal arena where the cryptography is the rulebook.

• Play live
• Source code

Block Kart Legends: on-chain TypeScript simulation on Arbitrum + Midnight​

Block Kart Legends is a racing game that runs complex TypeScript on-chain code cross-chain on Arbitrum and Midnight. It generates a deterministic L2 based on EVM + Midnight blocks, where it executes the race simulations. The entire race physics run deterministically in the L2, so every node computes the same result.

"On-chain TypeScript code" is the unusual part. Most chains run a custom VM (EVM, Move, Cairo) or expose a constrained DSL. Block Kart's game loop is plain TypeScript — collisions, friction, momentum, lap detection — running as the L2's state transition function and replayed identically by every full node. The language doesn't change between local development, testing, and on-chain execution, which is what makes it practical to ship a real physics simulation as on-chain logic rather than as a thin coordination layer over an off-chain server.

Arbitrum handles the transaction layer (race entries, rewards, leaderboard updates), while Midnight provides ZK verification of race results. This means a player's race time is provably legitimate without needing a centralized game server to validate every result.

• Play live
• Source code

Dust-2-Dust: large-scale ZK game in Compact​

The most technically complex template, by a clear margin. Dust-2-Dust is a roguelike deck builder written entirely in Compact (Midnight's ZK language), proving that ZK languages can encode and execute complex game behaviors. All proofs are calculated with WASM in the browser.

This isn't a simple proof-of-concept. It's a full game with hidden inventory, private resource management, and strategic decisions that stay secret until their effects show up in gameplay. Multiple interacting ZK circuits compose together for complex game logic while preserving privacy throughout.

Where most ZK games stop at a single circuit — one private state, one reveal — Dust-2-Dust threads many circuits together: drawing cards, using items, combat resolution, level progression, each with their own private state, all composed into one game session that lasts dozens of turns. The template is deliberately pushing the limits of state-of-the-art ZK circuit complexity: how much logic can you fit in a single Compact program, how many circuits can compose without proof generation becoming impractical, how much hidden state can persist between rounds without leaking through the public commitment? Dust-2-Dust's answers to those questions are the upper bound for what's currently shippable as a browser-side ZK game.

• Play live
• Source code

Go Fish: ZK Mental Poker​

Go Fish is a ZK implementation of "Mental Poker," the classic cryptographic problem of playing a fair card game without a trusted dealer. It's built entirely on a ZK contract, which means any card-like game can be implemented on top of the same protocol. Trustless card games, no server needed.

The protocol uses a commit-reveal scheme combined with shared secret derivation. When cards are "dealt," the deck is encrypted so that neither player can read it alone. Each card reveal requires cooperative decryption: both players contribute their share to reveal a card, which means neither side can peek ahead or manipulate the draw order. A fair deal is enforced by the math, not by trusting a server.

Once you have a trustless deck, the protocol generalises. Poker, blackjack, and trick-taking games all fall out of the same foundation. So do trading-card games with hidden hands — a Magic: The Gathering-style game, where each player has a private hand drawn from a shuffled deck and cards are revealed when played, is exactly the shape of the problem Go Fish solves. The same circuit that makes "Go Fish" trustless makes a full Magic-style card game trustless too: the only thing that changes is the card definitions and the turn rules, both of which run on top of the shared deck-and-hand primitive.

• Template code
• Cryptography design document

All templates at a glance​

Every template is a complete, deployable game you can fork, modify, and ship. The game templates repository is the fastest way to start building with EffectStream.

The privacy gap on Cardano​

Cardano's UTxO model is transparent by design: every transaction, every datum, every output is visible on the public ledger. That's great for financial transparency, but it's a problem for applications that need private state:

• Voting: ballots should stay private until the vote closes
• Games: hidden hands, fog-of-war, and secret strategies need private state
• Business logic: competitive information shouldn't be visible to rivals

Midnight is a privacy-focused blockchain with native zero-knowledge proof support. Combining Cardano's settlement with Midnight's private computation gives applications the best of both worlds.

Private Delegation Voting template​

To show this cross-chain privacy pattern in practice, we built a Private Delegation Voting template that combines Cardano stake pool delegation data with Midnight's ZK proofs for private ballot casting.

Here's the concept: a governance vote where voting power comes from your Cardano stake pool delegation, but your actual vote stays private. The system proves via zero-knowledge that:

1. The voter has a valid Cardano delegation (verified on-chain)
2. The vote was cast correctly (the ballot is well-formed)
3. The voter hasn't voted twice (nullifier prevents double-voting)

...without revealing which pool the voter delegates to or how they voted. The delegation data comes from Cardano via EffectStream's PoolDelegation primitive, and the privacy layer runs on Midnight.

The full ZK-Cardano template is available in the monorepo alongside five new Cardano primitives.

How it works​

EffectStream uses a "funnel" abstraction to read data from multiple blockchains through a unified interface. Adding a new chain means implementing a new funnel; the developer's state machine receives events from all configured chains without needing to know each chain's data format.

For the Midnight + Cardano integration:

1. Cardano funnel reads delegation state via Dolos/UTxORPC (who delegates to which pool, how much stake)
2. Midnight funnel reads ZK proof submissions and private state transitions
3. EffectStream state machine combines both data sources, verifying delegation eligibility from Cardano while preserving vote privacy from Midnight

The batcher system supports Midnight wallets via @effectstream/wallets, which provides unified wallet support across EVM, Cardano, Midnight, Polkadot, Algorand, and Mina. Users can sign transactions with Midnight wallets, making it a first-class chain in the framework.

Beyond voting: the privacy pattern​

Private Delegation Voting is one application of the Cardano + ZK pattern, but the architecture generalizes. Any scenario where public chain data needs private processing fits:

• Private governance - vote with your Cardano stake without revealing your position
• Hidden-hand games - use Cardano NFTs as game pieces with hidden state on Midnight
• Confidential analytics - prove facts about on-chain data without revealing the underlying data
• Anonymous credentials - prove you meet criteria (delegation amount, token holdings) without identifying yourself

Each follows the same template: read public state from Cardano, process it privately on Midnight, publish only the ZK proof.

Local ZK proof generation​

Beyond chain-integrated ZK, EffectStream also supports computing zero-knowledge proofs locally, without settling to any ZK chain. This removes the network dependency while keeping the privacy guarantees:

• Lower latency (no network round-trip)
• Lower cost (no on-chain fees for proof verification)
• Offline capability (proofs can be generated without network access)

The trade-off is in verification: chain-verified proofs inherit the chain's security guarantees, while locally-verified proofs need the application to validate them. For many use cases (anti-cheat in games, client-side validation), local proofs are sufficient and quite a bit faster.

Template: Werewolf (multiplayer ZK with browser proofs)​

The clearest worked example of local proofs is Werewolf — a multiplayer Mafia-style template where every player's role, night action, and vote stays private behind a ZK proof. The Compact contract tracks alive players in a Merkle tree and uses nullifiers to prevent double-voting; each player-side proof is generated in the browser before the input reaches the game server.

The night/day loop is structured around two ZK actions:

• Night action — werewolves submit an encrypted target with a ZK proof that they hold the werewolf role. The role itself never appears in any log.
• Vote — any alive player votes to eliminate, attaching a ZK inclusion proof against the alive-player Merkle root plus a nullifier so the same player can't vote twice.

The full stack runs locally with no external dependency: Midnight node, indexer, proof server, game server, and frontend all spin up from the template's README. Template source: effectstream/werewolf-game.

A second template, Go Fish, uses the same local-proof pattern for ZK Mental Poker — trustless card games without a dealer, with all card commitments and reveals proved client-side.

• Werewolf template code
• Werewolf Compact contract source
• Go Fish template (ZK Mental Poker)
• ZK-Cardano template code
• Cardano Primitives documentation
• Midnight Network
• UTxORPC Watch Module - streaming protocol for Cardano data

The pre-order smart contract​

The foundation is a smart contract that manages the NFT pre-order lifecycle. When a campaign launches, the contract accepts deposits from participants. Each deposit is recorded with the contributor's wallet address, amount, and selected items. The contract enforces campaign rules: deposit limits, time windows, and refund conditions. If a campaign doesn't reach its goal, contributors can reclaim their funds. If it succeeds, the creator fulfills orders and distributes NFTs.

The contract uses Aiken for Cardano-side validation and Solidity for EVM. Transaction metadata is validated on-chain to ensure payment integrity, and merkle trees efficiently prove participation for later NFT claims.

The EVM contract exposes two payment paths — native (ETH) and ERC-20 — and emits a BuyItems event that the EffectStream state machine indexes:

contract PaimaLaunchpad is OwnableUpgradeable, UUPSUpgradeable {
    event BuyItems(
        address indexed receiver,
        address indexed buyer,
        address indexed paymentToken,
        uint256 amount,
        address referrer,
        uint256[] itemsIds,
        uint256[] itemsQuantities
    );

    function buyItemsNative(
        address receiver,
        address payable referrer,
        uint256[] calldata itemsIds,
        uint256[] calldata itemsQuantities
    ) external payable { /* ... */ }

    function buyItemsErc20(
        address paymentToken,
        uint256 paymentAmount,
        address receiver,
        address referrer,
        uint256[] calldata itemsIds,
        uint256[] calldata itemsQuantities
    ) external { /* ... */ }
}

A factory contract (PaimaLaunchpadFactory) lets each campaign deploy its own launchpad instance with its own accepted-token list and referrer-reward configuration.

• Preorder template — full multi-chain stack, runs locally with one command
• EVM contract source (PaimaLaunchpad.sol)
• Cardano contract integration
• (Original repository: https://github.com/PaimaStudios/paima-preorder — preserved for reference)

Why separate deployments​

The backend is powered by EffectStream, with each presale campaign running as its own deployment. This isn't just organizational; it's a performance decision.

If all campaigns shared one EffectStream instance, you'd need to resync one very long chain of events for every new campaign. That's especially painful when campaigns monitor multiple chains for payments, since each chain adds sync overhead. Separate deployments keep sync times fast and campaigns independent of each other.

EffectStream's NTP-based sync (instead of block-based) makes this practical. The "main clock" is an NTP server, which is very cheap to poll, rather than a blockchain. The system only fetches blockchain data when relevant events occur, so a lightweight campaign deployment costs almost nothing when idle.

The launchpad UI​

The launchpad UI supports both EVM and Cardano wallets. Creators set up sales with configurable parameters (countdown timers, reward tiers, package bundles, item catalogs). Buyers browse campaigns, add items to a cart, and contribute funds from whichever chain they prefer.

• Launchpad portal components
• Portal repository

Cross-chain payments​

The launchpad accepts payments natively on each chain: Cardano users pay in ADA, EVM users pay in ETH or ERC-20 tokens. We originally planned to use bridge-based payments (Milkomeda for Cardano↔EVM), but pivoted to native chain primitives when the bridge infrastructure proved unreliable. Turned out to be simpler and more reliable anyway, with no dependency on third-party bridge availability.

All payments are tracked in the backend database with full transaction details:

The state machine handles two distinct payment paths — EVM events and Cardano UTXO outputs — under a unified schema:

import { Stm } from "@effectstream/sm";
import { grammar } from "./grammar.ts";
import { World } from "@effectstream/coroutine";

const stm = new Stm<typeof grammar, {}>(grammar);

// EVM purchase event (from the BuyItems event above)
stm.addStateTransition("buy-items", function* (data) {
  const { receiver, paymentToken, amount, itemsIds, itemsQuantities }
    = data.parsedInput;

  // Validate items, supply limits, payment amount...
  const validationResult = yield* validateItems(/* ... */);

  yield* World.resolve(insertParticipation, {
    launchpad: launchpadData.address,
    wallet: receiver,
    payment_token: paymentToken,
    payment_amount: amount,
    item_ids: itemsIds.join(","),
    item_quantities: itemsQuantities.join(","),
    chain: "evm",
    participation_valid: validationResult !== null,
  });
});

// Cardano payment — read UTXO outputs + transaction metadata (label 42)
stm.addStateTransition("cardano-payment", function* (data) {
  const { txId, outputs, metadata } = data.parsedInput;
  // Metadata format: { "42": [{ k: "p", v: "preorder" },
  //                          { k: "w", v: walletBech32 },
  //                          { k: "i", v: [[itemId, qty], ...] }] }
  const metaItems = parseMetadataItems(metadata);

  for (const output of JSON.parse(outputs)) {
    const matchingLaunchpad = launchpadsData.find(
      (l) => l.cardanoPaymentAddressHex === output.address,
    );
    if (!matchingLaunchpad) continue;

    yield* World.resolve(insertCardanoPayment, {
      tx_hash: txId,
      amount: output.coin,
      payment_address: matchingLaunchpad.cardanoPaymentAddress,
      block_height: data.blockHeight,
    });
    // ... item validation and participation upsert
  }
});

The two handlers write to the same participations and launchpad_user_items tables, so a downstream consumer (the portal UI, an off-chain fulfillment service) sees a uniform view regardless of which chain the buyer paid on.

Running the template locally​

The Preorder template ships as a one-command stack: PGLite, Hardhat, YACI DevKit, Dolos, the sync node, and the frontend all come up together under the EffectStream orchestrator.

git clone https://github.com/effectstream/effectstream.git
cd effectstream/templates/preorder
bun install
bun run dev

The orchestrator starts each component on a dedicated port:

Open http://localhost:10599 and the full launchpad is live against the local devnets — you can mint test ERC-20s and ADA, buy items with each, and watch the participations land in PostgreSQL in real time.

The same start.dev.ts config also drives the E2E test suite (bun run test), which covers infrastructure boot, native ETH purchase, ERC-20 purchase, validation (supply limits, underpayment), Cardano ADA payment, the REST API, and the frontend build.

Offline by design​

The launchpad isn't deployed as a single shared site, and that's a deliberate decision. Each presale campaign is its own EffectStream deployment: separate database, separate sync node, separate frontend. Three reasons:

1. Sync cost — if every campaign shared one deployment, each new launch would pay the sync cost of every chain ever monitored. Independent deployments keep sync times bounded per campaign.
2. Operator independence — a creator can take their campaign down without affecting anyone else's; an operator can hard-fork the template to add custom validation, accept exotic payment tokens, or wire in their own KYC.
3. Devnet-first development — the YACI DevKit + Hardhat stack runs entirely on the developer's machine. You can iterate on contract logic, test edge cases (underpayment, supply exhaustion, refund flows), and validate the full multi-chain pipeline before touching mainnet. The same template config and tests carry over to testnet and mainnet deployments unchanged.

The trade-off is that there's no single hosted demo to click through. Instead, anyone can clone the template and have a full multi-chain launchpad running on their machine in under five minutes — and that local stack is the same stack a real campaign would deploy to production.

What this gets you​

Creators get a turnkey platform for multi-chain NFT sales: deploy a campaign, configure tiers and pricing, accept payments from both Cardano and EVM wallets through a single interface. Buyers get a familiar e-commerce experience no matter which chain they're on.

The Aiken smart contract​

The Projected NFT smart contract is written in Aiken, Cardano's Rust-based smart contract language. It manages the full projection lifecycle:

1. Lock - the user sends their NFT to the contract, which records the owner and NFT details in the datum
2. Use - the application reads the locked state and grants in-app utility (powers, access, cosmetics)
3. Unlock - the user initiates a withdrawal request
4. Claim - after a cooldown period, the user claims the NFT back to their wallet

The cooldown on withdrawal prevents flash-loan-style exploits where a user could project, gain benefits, and immediately unproject in the same transaction. A CI pipeline validates that the contract compiles on every change.

The Hololocker dApp​

We built a full dApp called Hololocker for projecting and managing NFTs. It supports the complete lifecycle: mint new NFTs, lock them into the projection contract, view locked state, initiate unlock, and complete withdrawal.

• Source code

Indexing with UTxORPC and Dolos​

To track NFT lock/unlock events in real-time, we originally built a Carp indexer task. But Carp requires heavy synchronization (days on testnet, even longer on mainnet), which made rapid development impractical.

We've since moved to Dolos via the UTxORPC protocol. The new ProjectedNFT primitive in EffectStream reads projection events directly from Dolos's gRPC stream, parsing the datum to extract lock status, owner, policy ID, and asset name. It is one of five new Cardano primitives backed by an IVM (Indexed View Materializer) with PostgreSQL materialized views.

The ProjectedNFT primitive tracks:

• Lock events (NFT enters the projection contract)
• Unlock requests (user initiates withdrawal)
• Claim completions (NFT returns to user's wallet)
• Current projection status per NFT (datum parsing for owner, policy, asset)

All state changes are streamed in real-time through UTxORPC's Watch module, which supports filtering by address, delegation part, and asset policy.

Framework integration​

The ProjectedNFT primitive connects to EffectStream's funnel system, the abstraction layer that reads data from multiple blockchains. When an NFT is projected or unprojected, the event flows through the funnel into the application's state machine. Developers react to it in their game logic like any other event.

A game could grant in-game powers when a player projects a specific NFT, remove them when it's unprojected, or display a player's projected collection as their in-game inventory.

The integration is end-to-end tested with 21 E2E tests covering the full lifecycle: stake registration, delegation, lock, unlock, and claim, all verified against a local Dolos instance.

• ProjectedNFT primitive source code
• Cardano Primitives documentation

The full stack​

Five layers work together to make Projected NFTs possible:

This lets games use Cardano NFTs for in-game utility without transferring ownership, DeFi protocols collateralize without moving assets, and social platforms gate features based on NFT holdings. The NFT stays under the user's control the whole time.

This is the key use case for stake pool operators: free transactions for your delegators. The SPO runs a batcher that covers gas fees, but only for users delegating to their pool.

What the Batcher does​

The EffectStream Batcher is a standalone service that:

1. Receives user inputs via HTTP (POST /send-input)
2. Validates each input using a chain-specific adapter
3. Queues valid inputs in persistent storage
4. Batches them into a single on-chain transaction when criteria are met
5. Submits the batch and waits for confirmation

The adapter is the extension point. By implementing a custom BlockchainAdapter, you control validation, serialization, and submission. For the delegation use case, we add a validateInput() method that queries the delegations table before accepting the input.

See the full Batcher documentation for the complete API.

Architecture​

1. The delegation-aware adapter​

The core idea: extend the default EVM adapter with a validateInput() method that checks the user's delegation status before accepting their input. The batcher reads from the same delegations table that the sync node writes to (from Part 2).

import {
  type BlockchainAdapter,
  type DefaultBatcherInput,
  type ValidationResult,
  EffectStreamL2DefaultAdapter,
} from "@effectstream/batcher";
import { getDelegationsByAddress } from "@cardano-delegation/database";
import type { Pool } from "pg";

export class DelegationAwareBatcherAdapter
  extends EffectStreamL2DefaultAdapter
{
  private readonly dbConn: Pool;
  private readonly enabledPools: Set<string>;

  constructor(
    contractAddress: string,
    privateKey: string,
    fee: bigint,
    syncProtocolName: string,
    dbConn: Pool,
    enabledPools: string[],
  ) {
    super(contractAddress, privateKey, fee, syncProtocolName);
    this.dbConn = dbConn;
    this.enabledPools = new Set(
      enabledPools.map((p) => p.toLowerCase()),
    );
  }

  async validateInput(
    input: DefaultBatcherInput,
  ): Promise<ValidationResult> {
    // Look up the user's current delegation
    const delegations = await getDelegationsByAddress.run(
      { address: input.address },
      this.dbConn,
    );

    if (delegations.length === 0) {
      return {
        valid: false,
        error: "No delegation found for this address",
      };
    }

    // Check if the most recent delegation is to an enabled pool
    const latestDelegation = delegations[0];
    if (!this.enabledPools.has(latestDelegation.pool.toLowerCase())) {
      return {
        valid: false,
        error: `Not delegating to an enabled pool. ` +
          `Current pool: ${latestDelegation.pool}`,
      };
    }

    return { valid: true };
  }
}

The getDelegationsByAddress query is the same pgtyped query from Part 2 — it returns delegations ordered by id DESC, so delegations[0] is the most recent one.

2. Configuring the batcher​

Wire the adapter into a batcher instance with the pool hashes you want to subsidize:

import { main, suspend } from "effection";
import {
  createNewBatcher,
  FileStorage,
  type BatcherConfig,
} from "@effectstream/batcher";
import { getConnection } from "@effectstream/db";
import { DelegationAwareBatcherAdapter } from "./delegation-adapter.ts";

const ENABLED_POOLS = [
  "7301761068762f5900bde9eb7c1c15b09840285130f5b0f53606cc57",
  "82ec502f8c0a51e7c0db410e6722dd42df3b8e11f48e833f9fdf2941",
];

const dbConn = getConnection();

const adapter = new DelegationAwareBatcherAdapter(
  process.env.L2_CONTRACT_ADDRESS!,
  process.env.BATCHER_PRIVATE_KEY!,
  0n,                        // Free for delegators
  "mainEvmRPC",
  dbConn,
  ENABLED_POOLS,
);

const config: BatcherConfig = {
  pollingIntervalMs: 1000,
  adapters: { evm: adapter },
  defaultTarget: "evm",
  batchingCriteria: {
    evm: {
      criteriaType: "hybrid",
      timeWindowMs: 5000,      // Batch every 5 seconds
      maxBatchSize: 50,        // Or when 50 inputs queue up
    },
  },
  confirmationLevel: "wait-receipt",
  enableHttpServer: true,
  port: 3334,
  enableEventSystem: true,
};

const batcher = createNewBatcher(config, new FileStorage("./batcher-data"));

main(function* () {
  batcher.addStateTransition("startup", ({ publicConfig }) => {
    console.log(
      `Pool-aware batcher started on port ${publicConfig.port}`,
    );
    console.log(
      `Enabled pools: ${ENABLED_POOLS.length}`,
    );
  });

  batcher.addStateTransition("batch:submit", ({ txHash }) => {
    console.log(`Batch submitted: ${txHash}`);
  });

  yield* batcher.runBatcher();
  yield* suspend();
});

The fee: 0n means the SPO covers the cost. Users delegating to the enabled pools get free transactions. Users delegating elsewhere get rejected at the validateInput() step before their input even enters the queue.

3. The validation flow​

When a user submits an input, the batcher pipeline processes it in order:

1. Targeting — route to the correct adapter based on input.target
2. Signature verification — verify the user's wallet signature (inherited from EffectStreamL2DefaultAdapter)
3. Input validation — our custom validateInput() runs:
   • Query delegations table by input.address
   • Check if the latest delegation pool is in enabledPools
   • Return { valid: true } or { valid: false, error: "..." }
4. Storage — if valid, the input is persisted to disk
5. Batching — when criteria are met, inputs are serialized and submitted

A rejected input returns immediately with an error:

curl -X POST http://localhost:3334/send-input \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "address": "0x742d35Cc...",
      "addressType": 0,
      "input": "gameMove|x10y20",
      "signature": "0x...",
      "timestamp": "1234567890"
    }
  }'

# If not delegating to an enabled pool:
# { "success": false, "error": "Not delegating to an enabled pool. Current pool: abc123..." }

# If delegating to an enabled pool:
# { "success": true, "hash": "0x..." }

The walkthrough below shows the full flow end-to-end: the batcher is started with two enabled pools, a delegator of one of those pools submits a transaction and is accepted, and a non-delegator submits the same transaction and is rejected — both responses visible at the HTTP layer.

4. Batching criteria options​

The batcher supports multiple strategies for when to submit batches. Choose based on your game's requirements:

// Time-based: submit every N milliseconds
{ criteriaType: "time", timeWindowMs: 5000 }

// Size-based: submit when N inputs are queued
{ criteriaType: "size", maxBatchSize: 50 }

// Hybrid: whichever comes first
{ criteriaType: "hybrid", timeWindowMs: 5000, maxBatchSize: 50 }

// Value-based: submit when accumulated value reaches threshold
{
  criteriaType: "value",
  valueAccumulatorFn: (input) => parseFloat(input.input.split("|")[1]),
  targetValue: 1000,
}

// Custom: any logic you want
{
  criteriaType: "custom",
  isBatchReadyFn: (inputs, lastProcessTime) => {
    // Process immediately if any high-priority input exists
    return inputs.some((i) => i.input.startsWith("urgent|"));
  },
}

5. Adding event monitoring​

The batcher emits lifecycle events you can use for monitoring and observability:

batcher.addStateTransition("startup", ({ publicConfig }) => {
  console.log(`Batcher ready on port ${publicConfig.port}`);
});

batcher.addStateTransition("batch:submit", ({ txHash }) => {
  console.log(`Batch submitted: ${txHash}`);
});

batcher.addStateTransition("batch:confirmed", ({ receipt }) => {
  console.log(`Confirmed in block ${receipt.blockNumber}`);
});

batcher.addStateTransition("input:rejected", ({ error }) => {
  console.warn(`Input rejected: ${error}`);
});

What SPOs can build with this​

With the delegation-aware batcher, stake pool operators can offer tangible benefits to their delegators:

• Free game transactions — delegators play without paying gas fees, the SPO covers the cost
• Priority batching — delegators of partner pools get their inputs processed first
• Tiered access — different pools unlock different game features or areas
• Dynamic pricing — charge non-delegators, subsidize delegators

The configuration is straightforward: add your pool hash to ENABLED_POOLS, fund the batcher wallet, and point your game's frontend at the batcher endpoint. The delegation check happens automatically on every input.

Running the full stack​

The complete delegation + batcher stack runs as two pieces: the cardano-delegation template (sync node + indexing) and the pool-aware batcher adapter from PR #691. Both share the same PostgreSQL database — the sync node writes delegation events, the batcher reads them during validation.

# 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.

• Pool-aware batcher code example (PR #691) — the DelegationAwareBatcherAdapter source
• Batcher documentation
• Custom Adapters guide
• Part 1: Connecting Cardano SPOs
• Part 2: Building the State Machine
• Cardano delegation template source code

From event consumer to consensus input​

The progression across this series goes like this:

By Part 3 a stake pool delegation could already decide whether your transaction gets free batching. Part 4 raises the stakes: delegating to a registered SPO contributes to that pool's share of blocks produced on Midnight. The same delegation certificate now does two things at once — it routes ADA rewards on Cardano, and it weights consensus participation on a partner chain.

What a Partner Chain is​

Midnight is a Partner Chain. Partner Chains are blockchains that run in parallel to Cardano and inherit Cardano's security model by reusing its set of Stake Pool Operators as block producers. The Partner Chains Toolkit — built by IOG, the same engineering team behind Cardano itself — provides the off-chain CLI, on-chain Plutus scripts, and Substrate runtime pallets that turn a generic Substrate chain into a Cardano-anchored partner chain.

The toolkit pulls three things from Cardano:

1. SPO registrations — a Cardano transaction in which an SPO signs a message declaring they want to produce blocks on the partner chain.
2. Delegation stake — read off Cardano's ledger via db-sync, used to weight how many blocks a registered SPO produces.
3. Governance parameters — the D-Parameter and the permissioned validator whitelist, written to a Cardano script address and observed by the partner chain runtime.

The arrows are not metaphorical. Every Midnight epoch, the runtime re-reads Cardano state — registrations from the CommitteeCandidateValidator address, the D-Parameter from DParameterValidator, the permissioned candidates list — and feeds them into Ariadne, the committee selection algorithm. Ariadne outputs the validator set for the next epoch. That set is what Aura (Substrate's slot-based consensus) uses to produce Midnight blocks.

How Cardano SPOs become Midnight validators​

The registration flow is intentionally permissionless. An SPO who wants to produce Midnight blocks runs three CLI commands from the Partner Chains Toolkit. The exact commands live in the toolkit documentation; the shape of the flow is:

# 1. Generate the registration signatures on an offline machine
#    (cold keys never touch the internet)
pc-node registration-signatures \
  --genesis-utxo $GENESIS_UTXO \
  --mainchain-signing-key cold.skey \
  --sidechain-signing-key partner-chain.skey \
  --registration-utxo $REGISTRATION_UTXO

# 2. Submit the registration as a Cardano transaction
pc-node smart-contracts register \
  --genesis-utxo $GENESIS_UTXO \
  --registration-utxo $REGISTRATION_UTXO \
  --payment-key-file payment.skey \
  --partner-chain-public-keys $PC_PUB:$AURA_PUB:$GRANDPA_PUB \
  --partner-chain-signature $PC_SIG \
  --spo-public-key $SPO_PUB \
  --spo-signature $SPO_SIG

# 3. Confirm activation — registrations made in epoch N
#    become active in epoch N+2
pc-node registration-status \
  --stake-pool-pub-key $SPO_PUB \
  --mc-epoch-number $EPOCH

What lands on Cardano after step 2 is a UTXO at the CommitteeCandidateValidator script address, with a datum that carries the SPO's main-chain public key, their partner-chain public key, their Aura and Grandpa session keys, and the cross-signature proving the same operator controls both sides. Midnight's runtime reads that datum every epoch and treats it as a vote: "I, this SPO, with my Cardano delegators behind me, want to produce blocks on this chain."

The crucial property is that the stake weight comes from Cardano's ledger, not from a token on Midnight. There is no separate "Midnight validator stake" to bond. The delegators who already delegated their ADA to that SPO on Cardano are — without any extra action — backing the SPO's block production on Midnight.

The D-Parameter: governance over the registered/permissioned ratio​

Block producers on a partner chain come from two pools:

• Registered validators — Cardano SPOs who completed the registration flow above.
• Permissioned validators — a whitelist maintained by the chain's governance authority, intended to bootstrap the network when SPO registrations are still rolling in.

The split between them is governed by a single on-chain value, the D-Parameter, written to Cardano via:

pc-node smart-contracts upsert-d-parameter \
  --permissioned-candidates-count 3 \
  --registered-candidates-count 7 \
  --payment-key-file governance.skey \
  --genesis-utxo $GENESIS_UTXO

This particular setting reserves 3 of the 10 committee seats per epoch for permissioned validators and lets the remaining 7 be filled by registered SPOs proportional to delegation stake. The two-epoch delay before changes take effect gives the network a stable window to observe new parameters before they apply.

A chain typically launches near permissioned=N, registered=0 and ramps toward permissioned=0, registered=N as SPO registrations stabilise. This is the same decentralisation curve Cardano itself walked from Byron through Shelley, but governed transparently on-chain instead of by a hard fork.

Querying partner chain state from EffectStream​

Everything above is observable, which means application code can read it. The Partner Chains Toolkit exposes the relevant state via CLI commands and JSON-RPC. For an EffectStream app running on top of (or alongside) a partner chain, the two queries that matter for delegation-aware logic are:

• ariadne-parameters --mc-epoch-number N — returns the registered candidates, the permissioned candidates, the D-Parameter, and the delegation stakes effective at epoch N. Use this to find out which SPOs are actually producing blocks right now.
• registration-status --stake-pool-pub-key K --mc-epoch-number N — returns whether SPO K is registered and active at epoch N. Use this to gate features on whether a specific pool has joined the partner chain.

Wired into a state machine transition, these become first-class inputs alongside the delegations table from Part 2:

import { World } from "@effectstream/runtime";
import {
  getDelegationsByAddress,
  getActivePartnerChainSPOs,
} from "@cardano-delegation/database";
import {
  fetchAriadneParameters,
  type AriadneParameters,
} from "@effectstream/partner-chains";

stm.addStateTransition("delegation-bonus", function* (data) {
  const { address } = data.parsedInput as { address: string };

  // 1. Cardano side: where is this address currently delegating?
  const delegations = yield* World.resolve(
    getDelegationsByAddress, { address },
  );
  if (delegations.length === 0) return;
  const userPool = delegations[0].pool.toLowerCase();

  // 2. Partner-chain side: which SPOs are in the active committee
  //    for the current Cardano epoch?
  const epoch = slotToEpoch(data.blockHeight);
  const params: AriadneParameters = yield* fetchAriadneParameters({
    mcEpochNumber: epoch,
  });
  const activeProducers = new Set(
    params.registeredCandidates.map((c) =>
      c.stakePoolPubKey.toLowerCase()
    ),
  );

  // 3. Game-side: if the user's delegated SPO is actively producing
  //    blocks on the partner chain this epoch, grant a bonus.
  if (activeProducers.has(userPool)) {
    yield* World.resolve(grantBonus, {
      address,
      pool: userPool,
      epoch,
      multiplier: 2.0,
      reason: "active-validator-delegator",
    });
  }
});

What this handler captures is the full loop:

1. The user delegated ADA to an SPO on Cardano (Part 1 indexed it).
2. The state machine wrote that delegation to PostgreSQL (Part 2).
3. The SPO registered on the partner chain and is now in the block-production committee.
4. The application reads both sides and rewards the user proportional to consensus participation, not just delegation existence.

A user who switches to a non-registered pool keeps earning Cardano staking rewards but loses the application-side bonus. A user who switches to a pool that just got into the committee for next epoch picks it up automatically two epochs later — the same cadence Cardano itself uses for stake-distribution snapshots.

Cross-chain identity: associating Cardano and partner-chain addresses​

One more piece of the Partner Chains Toolkit is worth pointing at because it makes everything above clean to use: address association. A user with a Cardano stake address and a partner-chain address can sign a message linking the two, then submit the signature to the partner-chain ledger:

pc-node sign-address-association \
  --genesis-utxo $GENESIS_UTXO \
  --partnerchain-address $PC_ADDRESS \
  --signing-key cardano-stake.skey

Once associated, application code on the partner chain can resolve partner-chain address → Cardano stake address → current delegation without the user re-signing anything per session. For games this matters more than it sounds: it removes a per-transaction wallet prompt from the loop, and combined with the auto-sign work from the wallets release, it gives delegators a friction-free path from "I stake to this pool on Cardano" to "I have the right state inside this game on Midnight."

What runs on this today​

The applications already deployed on Midnight are the proof that this is not a thought experiment. Four games — Safe Solver, Kachina Kolosseum, Block Kart Legends, and Dust-2-Dust — run on a chain whose validator set is selected from registered Cardano SPOs by Ariadne, and whose epoch boundaries are tied to Cardano's. We covered the games themselves in the game templates post; the point here is that the consensus underneath them is the same delegation system we spent Parts 1–3 indexing from inside an application. The difference in Part 4 is that the chain itself does the reading.

For SPOs the practical consequence is a second product line:

• Each new partner chain is another network where their existing delegators carry over.
• Each application on those chains is another place where their delegators can collect benefits.
• Registration is permissionless and observable; deregistration is symmetric.
• Block participation rewards (covered in the Partner Chains Toolkit's block-participation-rewards module) flow back to delegators in the partner chain's native token.

The outreach mechanic is the registration mechanic. SPOs don't need a marketing pitch from us to participate — they need a Cardano transaction and two epochs of patience.

Wrap-up​

Four parts in, the story has gone from "watch a UTXO change" to "weight a consensus committee." The same pool field that started as a string in a delegations row in Part 1 ends up, in Part 4, as a vote that decides who produces the next block on a chain that hosts production games. The indexing layer, the state machine, and the batcher we built in Parts 1–3 still apply on top — they just now sit on a chain that already shares their assumption that stake pool delegation is a first-class signal.

• Part 1: Connecting Cardano SPOs
• Part 2: Building the State Machine
• Part 3: Building a Pool-Aware Batcher
• Partner Chains Toolkit
• Partner Chains Rust docs
• Game templates running on Midnight

Architecture overview​

The delegation template is a complete EffectStream application. It connects to a local Cardano devnet (YACI DevKit + Dolos), watches for delegation certificates, and stores them in PostgreSQL. The orchestrator spins up all infrastructure with a single bun run dev.

Cardano (YACI DevKit)
    → Dolos (UTxORPC gRPC)
        → EffectStream Sync Node
            → PoolDelegation Primitive (extracts certificates)
                → State Machine (writes to DB)
                    → REST API (reads from DB)
                        → Frontend (Delegation Explorer)

1. Configuration: connecting the chains​

The config defines two networks and two sync protocols. The NTP network provides the main clock, while the Cardano network connects to Dolos via UTxORPC:

// packages/node/config.dev.ts
export const config = new ConfigBuilder()
  .setNamespace((builder) =>
    builder.setSecurityNamespace("cardano-delegation")
  )
  .buildNetworks((builder) =>
    builder
      .addNetwork({
        name: "ntp",
        type: ConfigNetworkType.NTP,
        startTime: launchStartTime ?? new Date().getTime(),
        blockTimeMS: 1000,
      })
      .addNetwork({
        name: "yaci",
        type: ConfigNetworkType.CARDANO,
        nodeUrl: "http://127.0.0.1:10000",
        network: "yaci",
      }),
  )
  .buildSyncProtocols((builder) =>
    builder
      .addMain(
        (networks) => networks.ntp,
        () => ({
          name: mainSyncProtocolName,
          type: ConfigSyncProtocolType.NTP_MAIN,
          chainUri: "",
          startBlockHeight: 1,
          pollingInterval: 1000,
        }),
      )
      .addParallel(
        (networks) => (networks as any).yaci,
        () => ({
          name: "parallelUtxoRpc",
          type: ConfigSyncProtocolType.CARDANO_UTXORPC_PARALLEL,
          rpcUrl: "http://127.0.0.1:50051",
          startChainPoint: "origin",
          confirmationDepth: 0,
          delayMs: yaciDevKitStartTime ?? 0,
          pollingInterval: 1000,
          headers: { "x-rpc-key": "dev" },
        }),
      ),
  )

The key detail is CARDANO_UTXORPC_PARALLEL — this tells EffectStream to use a parallel sync protocol that streams blocks from Dolos via gRPC, independently of the main NTP clock. The confirmationDepth: 0 means we process blocks immediately (appropriate for a local devnet).

2. The primitive: filtering and extracting delegation certificates​

The primitive is registered in the config with a pool filter:

// packages/node/config.dev.ts
.buildPrimitives((builder) =>
  builder.addPrimitive(
    (syncProtocols) => (syncProtocols as any).parallelUtxoRpc,
    () => ({
      name: "CardanoPoolDelegation",
      type: PrimitiveTypeCardanoPoolDelegation,
      startBlockHeight: 1,
      stateMachinePrefix: "cardano-pool-delegation",
      pools: [
        "7301761068762f5900bde9eb7c1c15b09840285130f5b0f53606cc57",
        "82ec502f8c0a51e7c0db410e6722dd42df3b8e11f48e833f9fdf2941",
      ],
      network: "yaci",
    }),
  ),
)

The pools array filters which delegation events to track. Only delegations to these specific pool operator keyhashes will reach the state machine. Remove the filter to track all pools.

Under the hood, the primitive uses a UTxORPC predicate to tell Dolos to only send transactions containing certificates — filtering out the vast majority of transfer-only transactions at the gRPC level:

// CardanoPoolDelegationPrimitive.getConfig()
predicate: { match: { cardano: { has_certificate: true } } }

The getPayload() method then iterates the certificates array, handling both pre-Conway (stakeDelegation) and Conway-era (stakeRegDelegCert, stakeVoteDelegCert) certificate types:

// CardanoPoolDelegationPrimitive.getPayload()
for (const cert of tx.certificates) {
  const c = cert.certificate;
  if (c.case !== "stakeDelegation"
    && c.case !== "stakeRegDelegCert"
    && c.case !== "stakeVoteDelegCert") continue;

  const cred = stakeCredentialToHex(deleg.stakeCredential);
  const poolKeyhash = uint8ArrayToHexString(deleg.poolKeyhash);

  // Filter by configured pools (skip if not in our watch list)
  if (this.pools.length > 0
    && !this.pools.includes(poolKeyhash.toLowerCase())) continue;

  // Generate state machine input from the grammar
  const stateMachinePayload = generateRawStmInput(
    this.grammar, this.stateMachinePrefix, {
      address: cred.hash,
      pool: poolKeyhash,
      epoch: String(slotToEpoch(absoluteSlot, this.network)),
    }
  );
}

3. The grammar: defining the input shape​

The grammar is a TypeBox schema that defines the shape of data flowing from the primitive into the state machine. It's intentionally minimal:

// packages/node/grammar.ts
import { builtinGrammars } from "@effectstream/sm/grammar";

export const grammar = {
  "cardano-pool-delegation": builtinGrammars.cardanoPoolDelegation,
} as const satisfies GrammarDefinition;

The built-in grammar resolves to:

// pool-delegation-grammar.ts
export const poolDelegationGrammar = [
  ["address", Type.String()],  // staking credential hash (hex)
  ["pool", Type.String()],     // pool operator keyhash (hex)
  ["epoch", Type.String()],    // computed from slot + network params
] as const;

The grammar key "cardano-pool-delegation" matches the stateMachinePrefix in the primitive config. This is how EffectStream routes primitive outputs to the correct state machine transition.

4. The state machine: turning events into application state​

This is where on-chain data becomes application state. The state machine receives parsed delegation events and writes them to PostgreSQL:

// packages/node/state-machine.ts
const stm = new Stm<typeof grammar, {}>(grammar);

stm.addStateTransition("cardano-pool-delegation", function* (data) {
  const { address, pool, epoch } = data.parsedInput as {
    address: string;
    pool: string;
    epoch: string;
  };

  if (!address || !pool) return;

  // Insert the delegation record
  yield* World.resolve(insertDelegation, {
    block_height: data.blockHeight,
    address,
    pool,
    epoch,
    tx_hash: null,
  });

  // Update aggregate pool statistics
  yield* World.resolve(updatePoolStats, {
    pool,
    latest_epoch: epoch,
    latest_block: data.blockHeight,
  });
});

World.resolve() executes a pgtyped prepared query inside the EffectStream coroutine context. The queries run in the same transaction as the block processing, so if anything fails, the entire block rolls back cleanly.

The gameStateTransitions export wires this into the EffectStream runtime:

// packages/node/state-machine.ts
export const gameStateTransitions: StartConfigGameStateTransitions =
  function* (
    blockHeight: number,
    input: BaseStfInput,
  ): SyncStateUpdateStream<void> {
    yield* stm.processInput(input);
  };

5. Database schema​

The database has two tables — raw delegation events and aggregate pool statistics:

-- packages/database/migrations/000-init.sql
CREATE TABLE delegations (
  id SERIAL PRIMARY KEY,
  block_height INTEGER NOT NULL,
  address TEXT NOT NULL,
  pool TEXT NOT NULL,
  epoch TEXT NOT NULL,
  tx_hash TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_delegations_pool ON delegations(pool);
CREATE INDEX idx_delegations_address ON delegations(address);

CREATE TABLE pool_stats (
  pool TEXT PRIMARY KEY,
  total_delegators INTEGER NOT NULL DEFAULT 0,
  latest_epoch TEXT NOT NULL DEFAULT '0',
  latest_block INTEGER NOT NULL DEFAULT 0
);

The pool_stats table is maintained by an upsert query that recalculates total_delegators on each new delegation:

INSERT INTO pool_stats (pool, total_delegators, latest_epoch, latest_block)
VALUES (:pool!, 1, :latest_epoch!, :latest_block!)
ON CONFLICT (pool) DO UPDATE SET
  total_delegators = (
    SELECT COUNT(DISTINCT address) FROM delegations WHERE pool = :pool!
  ),
  latest_epoch = GREATEST(pool_stats.latest_epoch, :latest_epoch!),
  latest_block = GREATEST(pool_stats.latest_block, :latest_block!)