Release: develop → main

.env.example

@@ -17,19 +17,28 @@ DATABASE_URL=postgresql://postgres:postgres@localhost:5432/programmatic-orders
 # Schema for this app (required when using Postgres; avoids "previously used by a different Ponder app")
 DATABASE_SCHEMA=programmatic_orders
 
-# Dev/local: reduce RPC usage during sync
-# DISABLE_POLL_RESULT_CHECK=true — skip C1 ContractPoller multicalls for non-deterministic generators
-# DISABLE_DETERMINISTIC_CANCEL_SWEEP=true — skip C5 singleOrders checks for deterministic generators
-# DISABLE_SETTLEMENT_FACTORY_CHECK=true — skip getCode + FACTORY() calls in the GPv2Settlement:Trade
-#   handler entirely. Use to benchmark base sync throughput vs. the cost of those RPC calls.
-
-# C1 ContractPoller per-block generator cap (optional; default: 200)
-# Hard ceiling on how many generators the block handler multicalls per block.
-# Overflow defers to the next block, prioritized by oldest lastCheckBlock.
+# Performance / escape-hatch flags (all optional; safe to omit in production)
+# DISABLE_POLL_RESULT_CHECK=true       # escape-hatch: skips OrderDiscoveryPoller multicalls for
+#                                      #   non-deterministic generators; leaves those orders undetected
+#                                      #   until re-enabled. Use only to benchmark or diagnose.
+# DISABLE_DETERMINISTIC_CANCEL_SWEEP=true # escape-hatch: skips CancellationWatcher singleOrders()
+#                                      #   reads; on-chain remove() on TWAP/StopLoss/CirclesBackingOrder
+#                                      #   generators will not be detected while disabled.
+# DISABLE_SETTLEMENT_FACTORY_CHECK=true   # escape-hatch: skips getCode + FACTORY() RPC calls in the
+#                                      #   GPv2Settlement handler. Benchmark-only; do not use in prod.
+
+# Per-block generator cap for OrderDiscoveryPoller + CancellationWatcher (optional; default: 200)
+# Hard ceiling per block per chain. Excess generators defer to the next block (oldest-first).
 # Override per chain with the numeric chain-id suffix:
 # MAX_GENERATORS_PER_BLOCK_1=200      # mainnet
 # MAX_GENERATORS_PER_BLOCK_100=400    # gnosis (shorter block time → higher budget)
 
+# eth_getLogs block range cap (optional; default: 1000)
+# Increase if your RPC provider supports a larger range to speed up backfill.
+# Override per chain with the numeric chain-id suffix:
+# ETH_GET_LOGS_BLOCK_RANGE_1=2000     # mainnet
+# ETH_GET_LOGS_BLOCK_RANGE_100=5000   # gnosis
+
 
 # Logging (optional)
 # PINO_LOG_LEVEL=info

.github/workflows/ci.yml

@@ -35,3 +35,6 @@ jobs:
         env:
           # Public RPC
           MAINNET_RPC_URL: https://eth.api.pocket.network
+
+      - name: Test
+        run: pnpm test

.github/workflows/deploy.yml

@@ -19,6 +19,18 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
       - name: Set up SSH key
         run: |
           mkdir -p ~/.ssh
@@ -45,8 +57,4 @@ jobs:
           echo "${{ secrets.DEPLOY_ENV_FILE_CONTENT }}" > .env
 
       - name: Run deploy script
-        run: |
-          cd deployment
-          bash deploy-remotely.sh \
-            cow-deploy:${{ secrets.DEPLOY_PATH }} \
-            ../.env
+        run: npx tsx deployment/deploy-remotely.ts cow-deploy:${{ secrets.DEPLOY_PATH }} ../.env

.github/workflows/docker.yml

@@ -0,0 +1,50 @@
+name: Publish Docker image
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build-and-push:
+    name: Build and push to ghcr.io
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=sha,format=long
+            type=ref,event=branch
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            PIPELINE_BUILD_TAG=${{ github.sha }}

README.md

@@ -37,6 +37,25 @@ pnpm dev
 
 The GraphQL API is at `http://localhost:42069` once the dev server starts.
 
+> **First run takes time.** The indexer must backfill all on-chain events from the contract's deploy block before it goes live. This can take several hours depending on your RPC endpoint. The API is queryable the whole time — data just fills in progressively.
+
+## Is it working?
+
+Use these endpoints to check indexer health without reading logs:
+
+| Endpoint | What to expect |
+|----------|----------------|
+| `GET /healthz` | `200 {"status":"ok"}` — process is alive |
+| `GET /ready` | `503` while backfilling, `200` once caught up |
+| `GET /status` | Per-chain block progress (current vs. latest) |
+| `GET /metrics` | Prometheus metrics (block lag, handler latency) |
+
+**Normal during backfill** — `/ready` returns `503` and `/status` shows `checkpoint` far behind `latest`. The indexer is working; it just hasn't caught up yet. Expect this for several hours on first run.
+
+**Stuck vs. slow** — if `/status` shows the same `checkpoint` block for more than 5 minutes _after_ backfill (i.e., once `/ready` returned `200`), the indexer may be stuck. Check `docker logs <container>` for errors.
+
+**Container crashed** — `/healthz` returns a connection error. Restart the container and check logs.
+
 ## Commands
 
 | Command | What it does |

deployment/deploy-remotely.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env tsx
+/**
+ * deploy-remotely.ts — rsync + SSH deploy or local deploy.
+ * Replaces deploy-remotely.sh.
+ *
+ * NOTE: This script is specific to Bleu's internal deployment workflow.
+ * It assumes a particular server layout and SSH setup. Adapt as needed for
+ * your own hosting environment.
+ *
+ * Usage:
+ *   npx tsx deployment/deploy-remotely.ts <deploy_target> [env_file_path]
+ *
+ * deploy_target:
+ *   -            Local deployment (runs manage.ts in this repo)
+ *   host:path    Remote deployment via SSH (rsync + scp + ssh)
+ *
+ * Note: Remote deployment requires Node 18+ and pnpm installed on the remote host.
+ * Run `pnpm install` on the remote after the first deploy to install tsx.
+ */
+
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+
+function run(
+  cmd: string,
+  args: string[],
+  opts: { cwd?: string; ignoreError?: boolean } = {}
+): void {
+  console.log(`+ ${cmd} ${args.join(" ")}`);
+  const result = spawnSync(cmd, args, {
+    stdio: "inherit",
+    cwd: opts.cwd,
+  });
+  if (!opts.ignoreError && result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function runCapture(cmd: string, args: string[]): string {
+  const result = spawnSync(cmd, args, { encoding: "utf-8" });
+  if (result.status !== 0) {
+    console.error(`Command failed: ${cmd} ${args.join(" ")}`);
+    console.error(result.stderr);
+    process.exit(result.status ?? 1);
+  }
+  return result.stdout.trim();
+}
+
+function usage(): never {
+  console.error(
+    `Usage: tsx deployment/deploy-remotely.ts <deploy_target> [env_file_path]
+
+  deploy_target:
+    -            Local deployment
+    host:path    Remote deployment via SSH
+
+  env_file_path: path to .env file (default: .env)
+`
+  );
+  process.exit(1);
+}
+
+const [deployTarget, envFilePath = ".env"] = process.argv.slice(2);
+
+if (!deployTarget) {
+  usage();
+}
+
+const appRevision = runCapture("git", ["rev-parse", "--short", "HEAD"]);
+const repoRootDir = runCapture("git", ["rev-parse", "--show-toplevel"]);
+const manageCmd = process.env["MANAGE_CMD_OVERRIDE"] ?? "up";
+
+if (deployTarget === "-") {
+  // Local deployment
+  const absoluteEnvFile = resolve(envFilePath);
+  run(
+    "npx",
+    [
+      "tsx",
+      "deployment/manage.ts",
+      manageCmd,
+      "--env-file",
+      absoluteEnvFile,
+      "--revision",
+      appRevision,
+    ],
+    { cwd: repoRootDir }
+  );
+} else if (/^[^:]+:.+/.test(deployTarget)) {
+  // Remote deployment via SSH
+  const colonIdx = deployTarget.indexOf(":");
+  const sshHost = deployTarget.slice(0, colonIdx);
+  const remotePath = deployTarget.slice(colonIdx + 1);
+
+  // rsync repo to remote host
+  run("rsync", [
+    "-avz",
+    "--delete",
+    "--mkpath",
+    "--exclude=.git",
+    "--exclude=node_modules",
+    "--exclude=.env",
+    "--exclude=.env.local",
+    "--exclude=.vite",
+    "--exclude=*.log",
+    "--exclude=tmp/",
+    `${repoRootDir}/`,
+    `${sshHost}:${remotePath}/`,
+  ]);
+
+  // Copy env file to remote deployment directory
+  const remoteEnvPath = `${remotePath}/deployment/.env`;
+  run("scp", [envFilePath, `${sshHost}:${remoteEnvPath}`]);
+
+  // Run manage.ts on the remote host
+  // Note: The remote host must have Node 18+ and pnpm installed.
+  // After the first deploy, run `pnpm install` on the remote to install tsx.
+  const remoteDeployDir = `${remotePath}/deployment`;
+  run("ssh", [
+    sshHost,
+    `cd ${remoteDeployDir} && npx tsx manage.ts ${manageCmd} --env-file .env --revision ${appRevision}`,
+  ]);
+} else {
+  console.error(
+    "Error: <deploy_target> must be '-' (local) or SSH_HOST:PATH (remote)"
+  );
+  usage();
+}