From 08318fa4bcac3dee4c3bc3469da07e561aa65495 Mon Sep 17 00:00:00 2001 From: Shruti Gupta Date: Sun, 5 Jul 2026 13:10:08 +0530 Subject: [PATCH 1/5] docs: add missing env vars documentation --- .env.example | 7 +++++++ README.md | 4 ++++ 2 files changed, 11 insertions(+) diff --git a/.env.example b/.env.example index bdfda40..257b65e 100644 --- a/.env.example +++ b/.env.example @@ -54,6 +54,13 @@ VERIFIER_REDIS_TIMEOUT_MS=2000 # Service URLs (for Docker/production) VERIFIER_URL=http://127.0.0.1:3002 +# Verifier warm-up endpoint used by frontend banner +# Default: see DEPLOY.md (used for frontend warm-up banner) +NEXT_PUBLIC_VERIFIER_URL= + +# Maximum allowed request body size in bytes for verifier +# Default: 1048576 (1MB) +MAX_REQUEST_BODY_BYTES=1048576 # Comma-separated frontend origins allowed by the gateway CORS middleware. # Use origins only, with no path/query/fragment. # Defaults to http://localhost:3001 when unset or blank. diff --git a/README.md b/README.md index eed1f7b..3be1e1b 100644 --- a/README.md +++ b/README.md @@ -242,6 +242,8 @@ Edit `.env` before starting the gateway. At minimum: - `SERVER_WALLET_PRIVATE_KEY`: required for signing receipts. Use an unfunded development key locally. - `RECIPIENT_ADDRESS`: recipient address embedded in payment contexts. - `CHAIN_ID` and `EXPECTED_CHAIN_ID`: must match. The default is `84532` for Base Sepolia. +- `NEXT_PUBLIC_VERIFIER_URL`: frontend verifier warm-up endpoint used by the banner to pre-warm the verifier (improves UX; optional). +- `MAX_REQUEST_BODY_BYTES`: verifier request body limit in bytes. Default `1048576` (1MB). The root `bun run stack` command starts the gateway with `RECEIPT_STORE=memory` and `CACHE_ENABLED=false` unless you exported different values in the shell. That means the normal quick start does not require Redis even though production-style receipt storage defaults to Redis. @@ -332,6 +334,8 @@ Core local variables live in [.env.example](.env.example). Production placeholde | `RECEIPT_STORE` | Gateway | `redis` by default, `memory` for tests/local experiments. | | `REDIS_URL` | Gateway/Verifier | Required when `RECEIPT_STORE=redis`, `CACHE_ENABLED=true`, or `VERIFIER_NONCE_STORE=redis`. | | `VERIFIER_URL` | Gateway | **Required.** Where the gateway calls `/verify` (e.g. `http://127.0.0.1:3002` for `bun run stack`, `https://.onrender.com` for Render). The gateway refuses to start if unset — no silent loopback fallback. | +| `NEXT_PUBLIC_VERIFIER_URL` | Web | Frontend verifier warm-up endpoint used by banner for pre-warming the verifier. | +| `MAX_REQUEST_BODY_BYTES` | Verifier | Maximum request body size in bytes for verifier. Default `1048576` (1MB). | | `CACHE_ENABLED` | Gateway | Optional response cache. Payment verification still runs on cache hits. | | `METRICS_ENABLED` | Gateway | Enables the Prometheus metrics endpoint by default. Set to `false` to disable. | | `METRICS_PATH` | Gateway | Gateway metrics path. Default `/metrics`; values without a leading slash are normalized. | From fa778487c40c3d4c88eef0a5e6ecfd1843cad791 Mon Sep 17 00:00:00 2001 From: Shruti Gupta Date: Sun, 5 Jul 2026 14:00:29 +0530 Subject: [PATCH 2/5] docs: address CodeRabbit review comments --- .env.example | 4 ++-- README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.env.example b/.env.example index 257b65e..3ea4f38 100644 --- a/.env.example +++ b/.env.example @@ -52,11 +52,11 @@ VERIFIER_NONCE_STORE=redis VERIFIER_NONCE_KEY_PREFIX=microai:verifier:nonce: VERIFIER_REDIS_TIMEOUT_MS=2000 -# Service URLs (for Docker/production) -VERIFIER_URL=http://127.0.0.1:3002 # Verifier warm-up endpoint used by frontend banner # Default: see DEPLOY.md (used for frontend warm-up banner) NEXT_PUBLIC_VERIFIER_URL= +# Service URLs (for Docker/production) +VERIFIER_URL=http://127.0.0.1:3002 # Maximum allowed request body size in bytes for verifier # Default: 1048576 (1MB) diff --git a/README.md b/README.md index 3be1e1b..1aec095 100644 --- a/README.md +++ b/README.md @@ -243,7 +243,7 @@ Edit `.env` before starting the gateway. At minimum: - `RECIPIENT_ADDRESS`: recipient address embedded in payment contexts. - `CHAIN_ID` and `EXPECTED_CHAIN_ID`: must match. The default is `84532` for Base Sepolia. - `NEXT_PUBLIC_VERIFIER_URL`: frontend verifier warm-up endpoint used by the banner to pre-warm the verifier (improves UX; optional). -- `MAX_REQUEST_BODY_BYTES`: verifier request body limit in bytes. Default `1048576` (1MB). +- `MAX_REQUEST_BODY_BYTES`: verifier request body limit in bytes. Must be a positive integer; values less than or equal to 0 or invalid values fall back to the default `1048576` (1MB). The root `bun run stack` command starts the gateway with `RECEIPT_STORE=memory` and `CACHE_ENABLED=false` unless you exported different values in the shell. That means the normal quick start does not require Redis even though production-style receipt storage defaults to Redis. @@ -335,7 +335,7 @@ Core local variables live in [.env.example](.env.example). Production placeholde | `REDIS_URL` | Gateway/Verifier | Required when `RECEIPT_STORE=redis`, `CACHE_ENABLED=true`, or `VERIFIER_NONCE_STORE=redis`. | | `VERIFIER_URL` | Gateway | **Required.** Where the gateway calls `/verify` (e.g. `http://127.0.0.1:3002` for `bun run stack`, `https://.onrender.com` for Render). The gateway refuses to start if unset — no silent loopback fallback. | | `NEXT_PUBLIC_VERIFIER_URL` | Web | Frontend verifier warm-up endpoint used by banner for pre-warming the verifier. | -| `MAX_REQUEST_BODY_BYTES` | Verifier | Maximum request body size in bytes for verifier. Default `1048576` (1MB). | +| `MAX_REQUEST_BODY_BYTES` | Verifier | Maximum request body size in bytes for verifier. Must be a positive integer; values less than or equal to 0 or invalid values fall back to the default `1048576` (1MB). | | `CACHE_ENABLED` | Gateway | Optional response cache. Payment verification still runs on cache hits. | | `METRICS_ENABLED` | Gateway | Enables the Prometheus metrics endpoint by default. Set to `false` to disable. | | `METRICS_PATH` | Gateway | Gateway metrics path. Default `/metrics`; values without a leading slash are normalized. | From 0cb3464f0cbb699cef3963a838fadafb948be5b9 Mon Sep 17 00:00:00 2001 From: Shruti Gupta Date: Wed, 8 Jul 2026 13:34:45 +0530 Subject: [PATCH 3/5] docs: address maintainer review comments --- .env.example | 7 ++++--- README.md | 3 --- web/README.md | 5 ++++- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/.env.example b/.env.example index 3ea4f38..b8a3b38 100644 --- a/.env.example +++ b/.env.example @@ -52,9 +52,6 @@ VERIFIER_NONCE_STORE=redis VERIFIER_NONCE_KEY_PREFIX=microai:verifier:nonce: VERIFIER_REDIS_TIMEOUT_MS=2000 -# Verifier warm-up endpoint used by frontend banner -# Default: see DEPLOY.md (used for frontend warm-up banner) -NEXT_PUBLIC_VERIFIER_URL= # Service URLs (for Docker/production) VERIFIER_URL=http://127.0.0.1:3002 @@ -120,8 +117,12 @@ CACHE_ENABLED=false CACHE_TTL_SECONDS=3600 # Frontend (Next.js / web/) — all read at build time, prefixed NEXT_PUBLIC_ +# Verifier warm-up endpoint used by frontend banner +# Default: see DEPLOY.md (used for frontend warm-up banner) +# NEXT_PUBLIC_VERIFIER_URL= https://.onrender.com # Gateway URL the browser hits for /api/ai/summarize and /api/receipts/:id # NEXT_PUBLIC_GATEWAY_URL=http://localhost:3000 + # Chain ID the wallet widget expects (must match the gateway CHAIN_ID). # Default 84532 (Base Sepolia). # NEXT_PUBLIC_EXPECTED_CHAIN_ID=84532 diff --git a/README.md b/README.md index 1aec095..7cf1233 100644 --- a/README.md +++ b/README.md @@ -242,9 +242,6 @@ Edit `.env` before starting the gateway. At minimum: - `SERVER_WALLET_PRIVATE_KEY`: required for signing receipts. Use an unfunded development key locally. - `RECIPIENT_ADDRESS`: recipient address embedded in payment contexts. - `CHAIN_ID` and `EXPECTED_CHAIN_ID`: must match. The default is `84532` for Base Sepolia. -- `NEXT_PUBLIC_VERIFIER_URL`: frontend verifier warm-up endpoint used by the banner to pre-warm the verifier (improves UX; optional). -- `MAX_REQUEST_BODY_BYTES`: verifier request body limit in bytes. Must be a positive integer; values less than or equal to 0 or invalid values fall back to the default `1048576` (1MB). - The root `bun run stack` command starts the gateway with `RECEIPT_STORE=memory` and `CACHE_ENABLED=false` unless you exported different values in the shell. That means the normal quick start does not require Redis even though production-style receipt storage defaults to Redis. ### Run The Stack diff --git a/web/README.md b/web/README.md index c14d7c4..a1f1828 100644 --- a/web/README.md +++ b/web/README.md @@ -20,7 +20,10 @@ The frontend reads these `NEXT_PUBLIC_*` environment variables at build time: | Variable | Default | Notes | | --- | --- | --- | | `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:3000` | Gateway base URL the browser fetches `/api/ai/summarize` and `/api/receipts/:id` from. | -| `NEXT_PUBLIC_EXPECTED_CHAIN_ID` | `84532` | Chain id the wallet widget expects. Must match the gateway's `CHAIN_ID`. Deployments on Base mainnet should set `8453` so the widget doesn't fight every payment context. | +| +| `NEXT_PUBLIC_VERIFIER_URL` | unset | Optional verifier endpoint used by the frontend warm-up banner to pre-warm the verifier and improve first-request UX. +| +`NEXT_PUBLIC_EXPECTED_CHAIN_ID` | `84532` | Chain id the wallet widget expects. Must match the gateway's `CHAIN_ID`. Deployments on Base mainnet should set `8453` so the widget doesn't fight every payment context. | | `NEXT_PUBLIC_EXPECTED_CHAIN_NAME` | `Base Sepolia` | Display name used by the wallet widget's `Switch to ` button and the summarize form's placeholder copy. | | `NEXT_PUBLIC_PAYMENT_AMOUNT` | `0.001` | Pre-challenge fee label shown under the summarize form. **Informational only** — the actual signed amount is whatever the gateway embeds in the 402 payment context. | | `NEXT_PUBLIC_PAYMENT_TOKEN` | `USDC` | Token symbol shown next to `NEXT_PUBLIC_PAYMENT_AMOUNT`. Same caveat — display-only. | From 5b12e7a799e076d2b092e822282331b53005ef47 Mon Sep 17 00:00:00 2001 From: Shruti Gupta Date: Thu, 9 Jul 2026 16:51:54 +0530 Subject: [PATCH 4/5] docs: fix web README table formatting --- web/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/web/README.md b/web/README.md index a1f1828..8c28364 100644 --- a/web/README.md +++ b/web/README.md @@ -21,8 +21,7 @@ The frontend reads these `NEXT_PUBLIC_*` environment variables at build time: | --- | --- | --- | | `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:3000` | Gateway base URL the browser fetches `/api/ai/summarize` and `/api/receipts/:id` from. | | -| `NEXT_PUBLIC_VERIFIER_URL` | unset | Optional verifier endpoint used by the frontend warm-up banner to pre-warm the verifier and improve first-request UX. -| +| `NEXT_PUBLIC_VERIFIER_URL` | unset | Optional verifier endpoint used by the frontend warm-up banner to pre-warm the verifier and improve first-request UX. | `NEXT_PUBLIC_EXPECTED_CHAIN_ID` | `84532` | Chain id the wallet widget expects. Must match the gateway's `CHAIN_ID`. Deployments on Base mainnet should set `8453` so the widget doesn't fight every payment context. | | `NEXT_PUBLIC_EXPECTED_CHAIN_NAME` | `Base Sepolia` | Display name used by the wallet widget's `Switch to ` button and the summarize form's placeholder copy. | | `NEXT_PUBLIC_PAYMENT_AMOUNT` | `0.001` | Pre-challenge fee label shown under the summarize form. **Informational only** — the actual signed amount is whatever the gateway embeds in the 402 payment context. | From 786eae23e257c6cc39707a7ae43a4d26da5f94d2 Mon Sep 17 00:00:00 2001 From: AnkanMisra Date: Thu, 9 Jul 2026 18:33:13 +0530 Subject: [PATCH 5/5] fix: wire verifier env docs to docker paths Co-authored-by: codex --- .env.example | 4 ++-- docker-compose.yml | 2 ++ web/Dockerfile | 2 ++ web/README.md | 3 +-- 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.env.example b/.env.example index b8a3b38..0d58c77 100644 --- a/.env.example +++ b/.env.example @@ -118,8 +118,8 @@ CACHE_TTL_SECONDS=3600 # Frontend (Next.js / web/) — all read at build time, prefixed NEXT_PUBLIC_ # Verifier warm-up endpoint used by frontend banner -# Default: see DEPLOY.md (used for frontend warm-up banner) -# NEXT_PUBLIC_VERIFIER_URL= https://.onrender.com +# Default: unset (set this to let the banner warm the verifier too) +# NEXT_PUBLIC_VERIFIER_URL=https://.onrender.com # Gateway URL the browser hits for /api/ai/summarize and /api/receipts/:id # NEXT_PUBLIC_GATEWAY_URL=http://localhost:3000 diff --git a/docker-compose.yml b/docker-compose.yml index 4a2cd3a..f48cbeb 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -46,6 +46,7 @@ services: - EXPECTED_CHAIN_ID=${EXPECTED_CHAIN_ID:-${CHAIN_ID:-84532}} - SIGNATURE_EXPIRY_SECONDS=${SIGNATURE_EXPIRY_SECONDS:-300} - SIGNATURE_CLOCK_SKEW_SECONDS=${SIGNATURE_CLOCK_SKEW_SECONDS:-60} + - MAX_REQUEST_BODY_BYTES=${MAX_REQUEST_BODY_BYTES:-1048576} - VERIFIER_NONCE_STORE=${VERIFIER_NONCE_STORE:-redis} - VERIFIER_NONCE_KEY_PREFIX=${VERIFIER_NONCE_KEY_PREFIX:-microai:verifier:nonce:} - VERIFIER_REDIS_TIMEOUT_MS=${VERIFIER_REDIS_TIMEOUT_MS:-2000} @@ -100,6 +101,7 @@ services: # mainnet chain id and the wallet widget + stat bar will contradict # each other. NEXT_PUBLIC_GATEWAY_URL: ${NEXT_PUBLIC_GATEWAY_URL:-http://localhost:3000} + NEXT_PUBLIC_VERIFIER_URL: ${NEXT_PUBLIC_VERIFIER_URL:-} NEXT_PUBLIC_EXPECTED_CHAIN_ID: ${NEXT_PUBLIC_EXPECTED_CHAIN_ID:-${CHAIN_ID:-84532}} NEXT_PUBLIC_EXPECTED_CHAIN_NAME: ${NEXT_PUBLIC_EXPECTED_CHAIN_NAME:-Base Sepolia} NEXT_PUBLIC_PAYMENT_AMOUNT: ${NEXT_PUBLIC_PAYMENT_AMOUNT:-${PAYMENT_AMOUNT:-0.001}} diff --git a/web/Dockerfile b/web/Dockerfile index 98a0700..d70e5e1 100644 --- a/web/Dockerfile +++ b/web/Dockerfile @@ -10,6 +10,7 @@ WORKDIR /app # in docker-compose / CI; otherwise the container ships the source defaults # regardless of the gateway's CHAIN_ID / PAYMENT_AMOUNT config. ARG NEXT_PUBLIC_GATEWAY_URL=http://localhost:3000 +ARG NEXT_PUBLIC_VERIFIER_URL= ARG NEXT_PUBLIC_EXPECTED_CHAIN_ID=84532 ARG NEXT_PUBLIC_EXPECTED_CHAIN_NAME="Base Sepolia" ARG NEXT_PUBLIC_PAYMENT_AMOUNT=0.001 @@ -18,6 +19,7 @@ ARG NEXT_PUBLIC_POSTHOG_ENABLED=false ARG NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN= ARG NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com ENV NEXT_PUBLIC_GATEWAY_URL=$NEXT_PUBLIC_GATEWAY_URL +ENV NEXT_PUBLIC_VERIFIER_URL=$NEXT_PUBLIC_VERIFIER_URL ENV NEXT_PUBLIC_EXPECTED_CHAIN_ID=$NEXT_PUBLIC_EXPECTED_CHAIN_ID ENV NEXT_PUBLIC_EXPECTED_CHAIN_NAME=$NEXT_PUBLIC_EXPECTED_CHAIN_NAME ENV NEXT_PUBLIC_PAYMENT_AMOUNT=$NEXT_PUBLIC_PAYMENT_AMOUNT diff --git a/web/README.md b/web/README.md index 8c28364..3af510a 100644 --- a/web/README.md +++ b/web/README.md @@ -20,9 +20,8 @@ The frontend reads these `NEXT_PUBLIC_*` environment variables at build time: | Variable | Default | Notes | | --- | --- | --- | | `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:3000` | Gateway base URL the browser fetches `/api/ai/summarize` and `/api/receipts/:id` from. | -| | `NEXT_PUBLIC_VERIFIER_URL` | unset | Optional verifier endpoint used by the frontend warm-up banner to pre-warm the verifier and improve first-request UX. | -`NEXT_PUBLIC_EXPECTED_CHAIN_ID` | `84532` | Chain id the wallet widget expects. Must match the gateway's `CHAIN_ID`. Deployments on Base mainnet should set `8453` so the widget doesn't fight every payment context. | +| `NEXT_PUBLIC_EXPECTED_CHAIN_ID` | `84532` | Chain id the wallet widget expects. Must match the gateway's `CHAIN_ID`. Deployments on Base mainnet should set `8453` so the widget doesn't fight every payment context. | | `NEXT_PUBLIC_EXPECTED_CHAIN_NAME` | `Base Sepolia` | Display name used by the wallet widget's `Switch to ` button and the summarize form's placeholder copy. | | `NEXT_PUBLIC_PAYMENT_AMOUNT` | `0.001` | Pre-challenge fee label shown under the summarize form. **Informational only** — the actual signed amount is whatever the gateway embeds in the 402 payment context. | | `NEXT_PUBLIC_PAYMENT_TOKEN` | `USDC` | Token symbol shown next to `NEXT_PUBLIC_PAYMENT_AMOUNT`. Same caveat — display-only. |