Starter Kit

Inmemory Environment

Perfect for rapid testing and experimentation, this environment keeps all state in memory without any persistence. Use it to quickly iterate on runtime logic and test new features before moving to persistent environments.

Characteristics:

• All state stored in memory
• No external services or databases
• Blocks are produced but not persisted
• Perfect for unit and integration testing

Chain Configuration (chain.config.ts):

const appChain = AppChain.from({
  Runtime: Runtime.from(runtime.modules),
  Protocol: Protocol.from(protocol.modules),
  Sequencer: Sequencer.from({
    WorkerModule: WorkerModule.from(
      VanillaTaskWorkerModules.withoutSettlement()
    ),
    TaskQueue: LocalTaskQueue,
    LocalSequencerCoreModule,
    Database: InMemoryDatabase,
    Mempool: PrivateMempool,
    Graphql: GraphqlSequencerModule.from(VanillaGraphqlModules.with({})),
    BlockTrigger: TimedBlockTrigger,
  }),
  TransactionSender: InMemoryTransactionSender,
  QueryTransportModule: StateServiceQueryModule,
  NetworkStateTransportModule: BlockStorageNetworkStateModule,
});

• WorkerModule.withoutSettlement() : Configures the worker without settlement capabilities so that your sequencer will focus purely on producing blocks without attempting to settle to L1.
• LocalTaskQueue : Handles tasks locally without external queue infrastructure.
• LocalSequencerCoreModule : Allows registration of BlockProducerModule and SequencerStartupModule for local block production and initialization.
• InMemoryDatabase : All state is stored in memory, no persistence across restarts.

How to Run:

Start the inmemory environment with both the UI and sequencer running with live reload:

pnpm env:inmemory dev

Then visit:

• UI: http://localhost:3000
• Sequencer GraphQL: http://localhost:8080/graphql

For running tests:

pnpm env:inmemory run test --filter=chain -- --watchAll

Development Environment

A complete development environment, where you can run sequencer, worker, indexer, and processor locally. Enables testing settlement logic and historical data indexing with all components running in separate processes.

Characteristics:

• PostgreSQL databases for persistent state
• Redis for caching and task queuing
• Settlement and bridging to L1 enabled
• Indexer for historical data
• Processor for custom business logic
• All components run in separate processes

Chain Configuration (chain.config.ts):

  Runtime: Runtime.from(runtime.modules),
  Protocol: Protocol.from({
    ...protocol.modules,
    ...protocol.settlementModules,
  }),
  Sequencer: Sequencer.from({
    // ordering of the modules matters due to dependency resolution
    Database: PrismaRedisDatabase,
    Graphql: GraphqlSequencerModule.from(VanillaGraphqlModules.with({})),
    Mempool: PrivateMempool,
    BlockTrigger: TimedBlockTrigger,
    SequencerCoreModule,
    ...baseSettlementSequencerModules,
    TaskQueue: BullQueue,
    IndexerNotifier,
  }),

Persistence & Settlement:

• Database: PrismaRedisDatabase : Uses Redis and PostgreSQL database to persists the sequencer states.
• ...protocol.settlementModules & ...baseSettlementSequencerModules : Enables settlement and bridging to L1 (Mina). Your sequencer can now bridge tokens and settle state to the L1.

Task Processing:

• TaskQueue: BullQueue : Uses BullMQ (backed by Redis) to handle asynchronous tasks. Tasks are processed in a separate worker processes.
• SequencerCoreModule : In addition to BlockProducerModule and SequencerStartupModule, also registers BatchProducerModule for batch processing of blocks.

Indexing:

• IndexerNotifier : Notifies the indexer about produced blocks, transactions, batches, and settlements, enabling historical data synchronization.

Indexer Configuration (indexer.config.ts):

const indexer = Indexer.from({
  Database: PrismaRedisDatabase,
  TaskQueue: BullQueue,
  TaskWorker: WorkerModule.from({
    IndexBlockTask,
    IndexPendingTxTask,
    IndexBatchTask,
    IndexSettlementTask,
  }),
  Graphql: GraphqlSequencerModule.from({
    GeneratedResolverFactory: GeneratedResolverFactoryGraphqlModule,
  }),
});

Indexer Details:

• Separate Database : Uses its own PostgreSQL database (configured via PrismaRedisDatabase) to store indexed data independently from the sequencer
• BullQueue Subscription : Listens to the Redis-backed task queue for events emitted by the sequencer
• Task Processing : Handles indexing of blocks, transactions, batches, and settlements
• GraphQL Endpoint : Serves a separate GraphQL API for querying historical data

Worker Configuration (worker.config.ts):

const appChain = AppChain.from({
  Runtime: Runtime.from(runtime.modules),
  Protocol: Protocol.from({
    ...protocol.modules,
    ...protocol.settlementModules,
  }),
  Sequencer: Sequencer.from({
    TaskQueue: BullQueue,
    WorkerModule: WorkerModule.from(VanillaTaskWorkerModules.allTasks()),
  }),
});

Worker Details:

• Separate Process : Unlike inmemory environment, the worker runs in a different process and connects via BullQueue
• VanillaTaskWorkerModules.allTasks() : Handles all tasks emitted by the sequencer

Processor Configuration (processor.config.ts):

const processor = Processor.from({
  Database: databaseModule,
  DatabasePruneModule: DatabasePruneModule,
  GraphqlSequencerModule: GraphqlSequencerModule.from({
    ResolverFactory: ResolverFactoryGraphqlModule.from(resolvers),
  }),
  HandlersExecutor: HandlersExecutor.from(handlers),
  BlockFetching,
  Trigger: TimedProcessorTrigger,
});

Processor Details:

• Custom Database : Uses a dedicated database to store processed data according to your schema
• Block Processing : Fetches blocks from the indexer and processes them through your custom handlers
• Handler Execution : Runs your defined business logic handlers
• GraphQL API : Exposes processed data via GraphQL resolvers
• Timed Trigger : Periodically checks for new blocks to process

Services:

• Sequencer (port 8080) - Main GraphQL API
• Indexer (port 8081) - Historical data GraphQL API
• Processor (port 8082) - Processed data GraphQL API
• PostgreSQL (ports 5432, 5433, 5434) - Three databases
• Redis (port 6379) - Task queue and caching
• Lightnet (ports 8083, 8085) - Local Mina network for settlement

How to Run:

First, start the containerized dependencies and set up databases:

# Start PostgreSQL and Redis containers
pnpm env:development docker:up -d
 
# Generate Prisma clients
pnpm env:development prisma:generate
 
# Run migrations
pnpm env:development prisma:migrate

Then run each component in separate terminals:

pnpm env:development worker:dev
 
pnpm env:development indexer:dev
 
pnpm env:development processor:dev
 
pnpm env:development dev

Access your app-chain:

• UI: http://localhost:3000
• Sequencer GraphQL: http://localhost:8080/graphql
• Indexer GraphQL: http://localhost:8081/graphql
• Processor GraphQL: http://localhost:8082/graphql

Sovereign Environment

A production-ready deployment with all services containerized, monitoring stack included, and reverse proxy for routing. Designed for deployments with full settlement capabilities, bridging support, and observability through metrics and tracing.

Characteristics:

• All services run in Docker containers
• PostgreSQL databases for persistent state
• Redis for task queuing
• Full monitoring stack (Grafana, Prometheus, Loki)
• Settlement and bridging to L1 enabled
• Caddy reverse proxy

Chain Configuration (chain.config.ts):

const appChain = AppChain.from({
  Runtime: Runtime.from(runtime.modules),
  Protocol: Protocol.from({
    ...protocol.modules,
    ...protocol.settlementModules,
  }),
  Sequencer: Sequencer.from({
    // ordering of the modules matters due to dependency resolution
    ...metricsSequencerModules,
    Database: PrismaRedisDatabase,
    TaskQueue: BullQueue,
    Graphql: GraphqlSequencerModule.from(VanillaGraphqlModules.with({})),
    Mempool: PrivateMempool,
    BlockTrigger: TimedBlockTrigger,
    SequencerCoreModule,
    ...baseSettlementSequencerModules,
    IndexerNotifier,
  }),
  TransactionSender: InMemoryTransactionSender,
  QueryTransportModule: StateServiceQueryModule,
  NetworkStateTransportModule: BlockStorageNetworkStateModule,
});

Observability & Monitoring:

• ...metricsSequencerModules : Enables comprehensive observability with OpenTelemetry tracing and metrics collection for production monitoring

Indexer Configuration (indexer.config.ts):

const indexer = Indexer.from({
  Database: PrismaRedisDatabase,
  TaskQueue: BullQueue,
  TaskWorker: WorkerModule.from({
    IndexBlockTask,
    IndexPendingTxTask,
    IndexBatchTask,
    IndexSettlementTask,
  }),
  Graphql: GraphqlSequencerModule.from({
    GeneratedResolverFactory: GeneratedResolverFactoryGraphqlModule,
  }),
  OpenTelemetryServer,
});

Indexer Details:

• Separate Container : Runs in its own Docker container with dedicated PostgreSQL database
• OpenTelemetry Integration : Built-in tracing and metrics for production monitoring
• Redis Task Queue : Subscribes to BullQueue tasks
• GraphQL API : Exposes on port 8081 through Caddy reverse proxy
• Prometheus Metrics : Exports metrics for Grafana dashboards

Worker Configuration (worker.config.ts):

The sovereign environment supports multiple worker variants for specialized task processing:

const variants = {
  default: VanillaTaskWorkerModules.allTasks(),
  l2: VanillaTaskWorkerModules.withoutSettlement(),
  l1: {
    SettlementProvingTask,
    SettlementCompileTask,
    WorkerRegistrationTask,
  },
  transaction: {
    RuntimeProvingTask,
    TransactionProvingTask,
    TransactionReductionTask,
    WorkerRegistrationTask,
  },
  st: {
    StateTransitionTask,
    StateTransitionReductionTask,
    WorkerRegistrationTask,
  },
  block: {
    BlockReductionTask,
    NewBlockTask,
    WorkerRegistrationTask,
  },
};

Docker Services (.env COMPOSE_PROFILES):

COMPOSE_PROFILES=db,monolithic-sequencer,proxy,web,worker-monolithic,indexer,monitoring,explorer,lightnet

Services:

• db : PostgreSQL databases (sequencer, indexer, processor)
• monolithic-sequencer : Sequencer container
• proxy : Caddy reverse proxy for HTTPS and routing
• web : Next.js UI container
• worker-monolithic : Worker container
• indexer : Indexer container
• monitoring : Grafana, Prometheus, Loki stack
• explorer : Protokit explorer UI
• lightnet : Local Mina network for settlement

Services Access (Behind Caddy Proxy):

• UI: https://yourdomain.com
• Sequencer GraphQL: https://yourdomain.com/graphql
• Indexer GraphQL: https://yourdomain.com/indexer/graphql
• Processor GraphQL: https://yourdomain.com/processor/graphql
• Explorer: https://explorer.yourdomain.com
• Grafana: https://grafana.yourdomain.com

For Production Deployment:

Replace the wildcard configuration with your actual domain:

yourdomain.com {
    reverse_proxy /graphql sequencer:8080
    reverse_proxy /indexer/graphql indexer:8081
    reverse_proxy /processor/graphql processor:8082
    reverse_proxy web:3000
    encode gzip
}

explorer.yourdomain.com {
    reverse_proxy explorer:3000
}

grafana.yourdomain.com {
    reverse_proxy grafana:3000
}

How to Run:

First, build the Docker images:

pnpm env:sovereign docker:build

Then start all services:

# Start all containerized services
pnpm env:sovereign docker:up -d

Access your app-chain:

• UI: https://localhost
• Sequencer GraphQL: https://localhost/graphql
• Indexer GraphQL: https://localhost/indexer/graphql
• Processor GraphQL: https://localhost/processor/graphql
• Grafana: https://grafana.localhost
• Explorer: https://explorer.localhost.com