Middleman

This page is auto-synced from apps/middleman/README.md in the pokt-network/igniter repo. Edit it there — changes here are overwritten on every build.

Middleman is the delegator/owner-facing staking interface for Pocket Network. It handles staking, unstaking, importing suppliers, reward monitoring, and transaction tracking — giving delegators a self-hosted web interface to manage their staking portfolio on the Pocket Network (Shannon protocol).

This README is for delegators/owners running their own Middleman instance via Docker Compose.

Note: Middleman and Provider are independently deployed by different actors. A Middleman operator does not need to run their own Provider. For local development with Tilt, see the root CONTRIBUTING guide. This document covers production-style deployment only.

Table of Contents

• Prerequisites
• Environment Variables
• Deployment with Docker Compose
• Database Migrations
• Bootstrap Wizard
• Guides
• Reference

Prerequisites

Before deploying, you need:

• Docker and Docker Compose (v2+)
• A Pocket Network wallet address — used as the owner identity for SIWP login (OWNER_IDENTITY). Must be a valid pokt1... bech32 address.
• A Pocket Network private key — used for governance signing (APP_IDENTITY). This is a hex-encoded private key.
• Access to a Pocket Network node — you need both the Cosmos SDK REST API endpoint (port 1317) and the CometBFT RPC endpoint (port 26657). Both are configured during the setup wizard. The POKT_RPC_URL env var seeds the RPC URL into the database on first boot if not already set. You can use your own node or public endpoints.
• A CoinMarketCap API key — used to display POKT coin value to users. Get one at coinmarketcap.com/api

Environment Variables

Middleman reads its configuration from a single .env file at docker-compose/apps/middleman/.env. Copy .env.sample as a starting point.

All vars below are sourced from docker-compose/apps/middleman/.env.sample and verified against apps/middleman/src/config/env.ts.

Compose

Next.js

Temporal

PostgreSQL

Note: PGPASSWORD must exactly match POSTGRES_PASSWORD in docker-compose/dependencies/.env. If they don’t match, migrations and the app will fail to connect.

Pocket Network

Note: PROVIDERS_CDN_URL must be set in both the middleman app (for bootstrap) and middleman-workflows (for the scheduled GovernanceSync workflow). In local Tilt development, both are automatically overridden to use the local governance-nginx service.

Application

Note: Middleman runs on port 3000 by default. If running both Provider and Middleman on the same host, one of them must use a different port (Provider defaults to 3001).

Security

Note: Middleman does not use ENCRYPTION_IV or ENCRYPTION_KEY — it does not store private keys in the database the way Provider does. Only AUTH_SECRET is needed for session encryption.

External Services

Deployment with Docker Compose

Middleman runs as three Docker Compose services that depend on shared infrastructure (PostgreSQL + Temporal) started from docker-compose/dependencies/.

Step 1: Clone the repository

git clone https://github.com/pokt-network/igniter.git
cd igniter

Step 2: Start dependencies

The dependencies compose starts PostgreSQL and Temporal — both must be healthy before Middleman services can connect.

cd docker-compose/dependencies
cp .env.sample .env

Open .env and change the default passwords:

POSTGRES_PASSWORD=your-secure-password

Note: The default POSTGRES_PASSWORD=igniter is not suitable for production. Change it now — you will reference this same password in the Middleman .env.

Then start the dependencies:

docker compose up -d

Wait for all services to become healthy (docker compose ps). The igniter Docker network is created at this step — the Middleman services connect to it as an external network.

Step 3: Configure Middleman

cd docker-compose/apps/middleman
cp .env.sample .env

Fill in the required values in .env. At minimum, you must set:

• PGPASSWORD — must match POSTGRES_PASSWORD from the dependencies .env
• OWNER_IDENTITY — your pokt1... wallet address
• APP_IDENTITY — your hex private key for governance signing
• POKT_RPC_URL — CometBFT RPC endpoint (seeded into DB on first boot)
• AUTH_SECRET — generate with openssl rand -hex 24
• OWNER_EMAIL — your email address
• COIN_MARKET_CAP_API_KEY — your CoinMarketCap API key

Refer to the Environment Variables section above for the full reference.

Step 4: Start Middleman services

docker compose up -d

Docker Compose starts three services in dependency order:

All three services connect to the shared igniter Docker network created by the dependencies compose.

Step 5: Verify

docker compose ps

All three services should show running (or exited with code 0 for middleman-migration). The web app is accessible at the APP_URL you configured (default: http://localhost:3000).

Database Migrations

Migrations run automatically via the middleman-migration service every time you run docker compose up. The service uses Drizzle ORM to apply any pending schema changes, then exits with code 0. The web and workflows services will not start until migration completes successfully.

If you need to run migrations manually outside of Docker (e.g., in CI or during local development):

pnpm middleman:migration:migrate

Bootstrap Wizard

After deployment, Middleman is running but not yet configured. The bootstrap wizard is a one-time setup flow that configures the application for your environment.

How to access: Navigate to APP_URL/admin/setup and sign in using SIWP (Sign-In with Pocket). Only the wallet address set in OWNER_IDENTITY can log in before bootstrap is complete.

The wizard walks through 4 steps in sequence:

After completing all 4 steps and clicking Complete, you are redirected to /admin/overview.

Provider Discovery and Governance JSON Exchange

Middleman discovers available providers via the PROVIDERS_CDN_URL. This URL points to a governance repository JSON file that lists providers who have registered themselves as available for staking.

At runtime, {chainId} in PROVIDERS_CDN_URL is replaced with the value of CHAIN_ID to fetch the provider list for the correct network. The providers fetched from this URL are used during bootstrap (initial setup) and by the GovernanceSync Temporal workflow that runs every 5 minutes in middleman-workflows. The Reload button on the Providers admin page triggers this workflow manually. New providers are added as enabled and visible by default; providers removed from governance are disabled and hidden.

When a user stakes through Middleman, the application communicates directly with the selected Provider’s API to request supplier addresses, and the owner signs the stake transaction locally. Middleman discovers which providers are available via the governance JSON, but the staking and import-suppliers flows require direct network access between Middleman and Provider instances.

Admin vs. Delegator Interface

Once bootstrapped, Middleman exposes two interface areas:

• /admin/ — For the Middleman operator. Manage application settings, configure which providers are available, and view all transactions across all delegators.
• /app/ — For delegators. Stake, unstake, import suppliers, and monitor their staking portfolio and rewards.

Guides

Step-by-step tutorials for common Middleman workflows.

Reference

Detailed feature documentation for each area.