feat: harden indexing for production v1

.dockerignore

@@ -5,6 +5,7 @@ target/
 .env
 .env.example
 .dockerignore
+.temp/
 Dockerfile
 docker-compose.yml
 erpc.yaml

.env.example

@@ -1,17 +1,26 @@
+# Required bearer token for admin/data API routes.
+API_TOKEN=replace-with-a-long-random-token
 # Default `postgres-storage` build. A `mongodb-storage` build can instead use
 # mongodb://localhost:27017/?replicaSet=rs0 and STORAGE_DATABASE=parseon.
 STORAGE_URL=postgres://postgres:postgres@localhost:5432/parseon
 # STORAGE_DATABASE=parseon
 HTTP_LISTEN=0.0.0.0:8080
 RUST_LOG=info,parseon=debug
+# Comma-separated browser origins; empty keeps CORS disabled.
+CORS_ORIGINS=
+MAX_BODY_BYTES=1048576
 POLL_INTERVAL_MS=2000
 DEFAULT_BATCH_SIZE=10
 # Set to 0 to disable Parseon's in-memory block cache.
 BLOCK_CACHE_SIZE=512
 BLOCK_CONCURRENCY=4
 RPC_REQUEST_CONCURRENCY=16
 STORAGE_WRITE_CONCURRENCY=4
+CONFIRMATION_DEPTH=64
+ROLLBACK_RETENTION=256
 RPC_BATCH_SIZE=20
+# Only enable for local RPC containers; keep false in production.
+ALLOW_PRIVATE_RPC_NETWORKS=false
 # Required only when built with `webhook-sink`.
 # WEBHOOK_URL=http://localhost:9000/parseon
 # WEBHOOK_CONCURRENCY=16

.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ fmt:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add rustfmt --toolchain 1.96.0
+ - run: cargo +1.96.0 fmt --all -- --check
+
+ rust:
+ runs-on: ubuntu-24.04
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: postgres
+ features: parseon-server/postgres-storage
+ - name: postgres-webhook
+ features: parseon-server/postgres-storage,parseon-server/webhook-sink
+ - name: mongodb
+ features: parseon-server/mongodb-storage
+ - name: mongodb-webhook
+ features: parseon-server/mongodb-storage,parseon-server/webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add clippy --toolchain 1.96.0
+ - run: cargo +1.96.0 clippy -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short -- -D warnings
+ - run: cargo +1.96.0 test -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short
+ - run: cargo +1.96.0 build -q -p parseon-server --release --locked --no-default-features --features "${{ matrix.features }}"
+
+ docker:
+ runs-on: ubuntu-24.04
+ strategy:
+ matrix:
+ include:
+ - name: postgres
+ features: postgres-storage
+ - name: postgres-webhook
+ features: postgres-storage,webhook-sink
+ - name: mongodb
+ features: mongodb-storage
+ - name: mongodb-webhook
+ features: mongodb-storage,webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Build image
+ run: docker build --build-arg PARSEON_FEATURES='${{ matrix.features }}' --tag parseon:ci .
+ - name: Generate SBOM when Docker SBOM support is installed
+ shell: bash
+ run: |
+ if docker sbom --help >/dev/null 2>&1; then
+ docker sbom parseon:ci > "sbom-${{ matrix.name }}.spdx.json"
+ else
+ echo 'docker sbom is unavailable on this runner; image SBOM is delegated to the registry scanner.'
+ fi
+ - name: Scan image when Docker Scout support is installed
+ shell: bash
+ run: |
+ if docker scout version >/dev/null 2>&1; then
+ docker scout cves --only-fixed parseon:ci
+ else
+ echo 'docker scout is unavailable on this runner; image scanning is delegated to the registry.'
+ fi
+
+ release-gates:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Validate production Compose
+ shell: bash
+ run: |
+ export PARSEON_IMAGE=registry.example/parseon@sha256:$(printf 'a%.0s' {1..64})
+ export STORAGE_URL='postgres://postgres:5432/parseon'
+ export POSTGRES_PASSWORD=test
+ export API_TOKEN=test-token
+ docker compose -f compose.production.yml config >/dev/null
+ if [[ ! "$PARSEON_IMAGE" =~ @sha256:[0-9a-fA-F]{64}$ ]]; then
+ echo 'PARSEON_IMAGE must be digest-pinned' >&2
+ exit 1
+ fi
+ - name: Validate Helm chart and immutable deployment policy
+ shell: bash
+ run: |
+ digest="sha256:$(printf 'a%.0s' {1..64})"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 lint deploy/helm/parseon --set image.digest="$digest"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" >/dev/null
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" --set replicaCount=2 >/dev/null 2>&1; then
+ echo 'replicaCount=2 was accepted' >&2
+ exit 1
+ fi
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon >/dev/null 2>&1; then
+ echo 'missing image digest was accepted' >&2
+ exit 1
+ fi
+ - name: Validate scripts and monitoring artifacts
+ shell: bash
+ run: |
+ bash -n scripts/backup_postgres.sh scripts/restore_postgres.sh
+ python3 -m py_compile scripts/gen_erpc.py
+ python3 -m json.tool deploy/monitoring/parseon-dashboard.json >/dev/null
+ secrets:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ fetch-depth: 0
+ - name: Reject credential-bearing generated config
+ shell: bash
+ run: |
+ if git grep -n -I -i -E '://[^[:space:]/:@]+:[^[:space:]@]+@|(^|[?&])(api[_-]?key|access[_-]?token|token|secret|password)=[^[:space:]&]{8,}' -- ':!CHANGELOG.md' ':!docs/operations.md' ':!.env.example'; then
+ echo 'credential-bearing URL or query parameter found in tracked source' >&2
+ exit 1
+ fi
+ echo 'Historical credentials still require independent revoke/rotate evidence.'

.gitignore

@@ -1,2 +1,3 @@
 /target
 /.env
+/.temp

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Added
 
+- Add canonical block metadata, provisional/finalized lifecycle, bounded reorg rollback, and finalized promotion for both storage adapters.
+- Add production Compose and Helm deployment artifacts, backup/restore operations runbook, Prometheus alerts, Grafana dashboard, and CI release gates.
 - Apply chain creation, enable/disable, and deletion to running workers without restarting Parseon; deletions stop the worker before removing its data.
 - Rotate a chain's RPC endpoint URL in place on the running worker via Alloy's `Http::set_url`, resetting endpoint capability probes while keeping the cached chain ID; sources that cannot rotate restart their worker instead.
 - Allow multiple monitors to target the same chain, contract, and function selector or event topic while retaining independent ranges, filters, cursors, and result storage.
@@ -15,6 +17,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Changed
 
+- Require a bearer API token for protected HTTP routes, disable CORS by default, bound request bodies, add liveness/readiness probes, and reject unsafe RPC destinations by default.
+- Treat credential-bearing eRPC URLs as operator-injected configuration instead of generated repository content.
 - Pin the Compose eRPC image to the `0.1.1` release tag, set a 3 GiB container memory limit with `GOMEMLIMIT=2700MiB`, add `restart: unless-stopped`, and invoke `/erpc-server` explicitly so the distroless image starts correctly.
 - Reuse matching RPC data and compatible ABI decoders across overlapping monitor targets before applying each monitor's filter and persisting its own results.
 - Isolate ABI decode failures to the affected monitor layout so an incompatible definition cannot stall other monitors on the chain.
@@ -32,6 +36,8 @@ All notable changes to Parseon are documented in this file.
 ### Fixed
 
 - Keep persisted chain state and live workers ordered during concurrent mutations and startup reconciliation, and reject new worker starts once supervisor shutdown begins.
+- Reject mixed-branch result identities, fail closed when a retained reorg ancestor is unavailable, preserve finalized state for monitors added over existing blocks, and reset rollback cursors below a monitor's start block.
+- Pin validated RPC DNS addresses in the HTTP transport, verify generated endpoint chain IDs, expose worker freshness/state metrics, and require encrypted checksum-verified PostgreSQL backup artifacts.
 
 ### Breaking
 

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 resolver = "3"
 
 [workspace.package]
-version = "0.8.0"
+version = "1.0.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # ---- chef base: shared Rust toolchain + cargo-chef ----
-FROM rust:1.96-alpine AS chef
+FROM rust:1.96-alpine@sha256:a41f7740f8b45d45795624eec13a8b42263cc700f19f7e4e86e04d3dda08a479 AS chef
 RUN apk add --no-cache musl-dev
 RUN cargo install cargo-chef --locked
 WORKDIR /app
@@ -18,7 +18,7 @@ ARG PARSEON_FEATURES=postgres-storage
 ENV PARSEON_FEATURES=${PARSEON_FEATURES}
 RUN apk add --no-cache watchexec
 COPY --from=planner /app/recipe.json recipe.json
-RUN cargo chef cook --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+RUN cargo chef cook --locked --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 EXPOSE 8080
 CMD ["sh", "-c", "exec watchexec --restart --stop-signal SIGINT --exts rs,toml,lock,sql -- cargo run --no-default-features --features \"${PARSEON_FEATURES}\""]
@@ -29,15 +29,15 @@ ARG PARSEON_FEATURES=postgres-storage
 COPY --from=planner /app/recipe.json recipe.json
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo chef cook --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+ cargo chef cook --locked --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo build --release --no-default-features --features "${PARSEON_FEATURES}" && \
+ cargo build --release --locked --no-default-features --features "${PARSEON_FEATURES}" && \
  cp /app/target/release/parseon /usr/local/bin/parseon
 
 # ---- runtime: minimal alpine, non-root, healthcheck ----
-FROM alpine:3.20 AS runtime
+FROM alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc AS runtime
 RUN apk add --no-cache ca-certificates wget && \
  adduser -D -u 1000 parseon
 COPY --from=builder /usr/local/bin/parseon /usr/local/bin/parseon

README.md

@@ -40,10 +40,14 @@ parseon-server
 └── parseon-webhook-sink ────> parseon-core
 ```
 
-Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL`, then register direct RPC or complete eRPC URLs through `POST /chains`.
+Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL` and set a non-empty `API_TOKEN`; protected API routes require `Authorization: Bearer <API_TOKEN>`. Register direct RPC or complete eRPC URLs through `POST /chains`. Private/loopback RPC destinations are rejected unless `ALLOW_PRIVATE_RPC_NETWORKS=true` is explicitly enabled for local development.
 
 See [adapter configuration and guarantees](./docs/adapters.md) for feature builds, MongoDB requirements, eRPC smoke checks, the webhook JSON contract, and Compose profiles.
 
+## Production deployment
+
+Use [`compose.production.yml`](./compose.production.yml) or the [`deploy/helm/parseon`](./deploy/helm/parseon) chart. Both require an externally managed `API_TOKEN` and storage URL, keep databases private, and expose liveness/readiness probes. Read the [production operations runbook](./docs/operations.md) before upgrading, restoring, or exposing the API through an ingress.
+
 ## License
 
 Licensed under either the [Apache License, Version 2.0](./LICENSE-APACHE) or the [MIT license](./LICENSE-MIT), at your option.

compose.production.yml

@@ -0,0 +1,70 @@
+services:
+ postgres:
+ image: ${POSTGRES_IMAGE:-postgres:16@sha256:f1c3376c26f2609ab9f29f71f824103fe2fcd8ee0346485cb6122a4f93df6f94}
+ restart: unless-stopped
+ environment:
+ POSTGRES_USER: ${POSTGRES_USER:-parseon}
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+ POSTGRES_DB: ${POSTGRES_DB:-parseon}
+ volumes:
+ - pgdata:/var/lib/postgresql/data
+ networks:
+ - backend
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ # No host port: PostgreSQL is reachable only by Parseon on the backend network.
+
+ parseon:
+ image: ${PARSEON_IMAGE:?set PARSEON_IMAGE to an immutable Parseon image}
+ restart: unless-stopped
+ depends_on:
+ postgres:
+ condition: service_healthy
+ environment:
+ STORAGE_URL: ${STORAGE_URL:?set STORAGE_URL}
+ API_TOKEN: ${API_TOKEN:?set API_TOKEN}
+ HTTP_LISTEN: 0.0.0.0:8080
+ RUST_LOG: ${RUST_LOG:-info}
+ POLL_INTERVAL_MS: ${POLL_INTERVAL_MS:-2000}
+ DEFAULT_BATCH_SIZE: ${DEFAULT_BATCH_SIZE:-10}
+ BLOCK_CACHE_SIZE: ${BLOCK_CACHE_SIZE:-512}
+ BLOCK_CONCURRENCY: ${BLOCK_CONCURRENCY:-4}
+ RPC_REQUEST_CONCURRENCY: ${RPC_REQUEST_CONCURRENCY:-16}
+ STORAGE_WRITE_CONCURRENCY: ${STORAGE_WRITE_CONCURRENCY:-4}
+ CONFIRMATION_DEPTH: ${CONFIRMATION_DEPTH:-64}
+ ROLLBACK_RETENTION: ${ROLLBACK_RETENTION:-256}
+ RPC_BATCH_SIZE: ${RPC_BATCH_SIZE:-20}
+ ALLOW_PRIVATE_RPC_NETWORKS: "false"
+ CORS_ORIGINS: ${CORS_ORIGINS:-}
+ MAX_BODY_BYTES: ${MAX_BODY_BYTES:-1048576}
+ expose:
+ - "8080"
+ networks:
+ - backend
+ - egress
+ read_only: true
+ tmpfs:
+ - /tmp
+ cap_drop:
+ - ALL
+ security_opt:
+ - no-new-privileges:true
+ mem_limit: ${PARSEON_MEMORY_LIMIT:-768m}
+ cpus: ${PARSEON_CPUS:-2}
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ interval: 10s
+ timeout: 5s
+ start_period: 20s
+ retries: 6
+
+volumes:
+ pgdata:
+
+networks:
+ backend:
+ internal: true
+ egress:

.dockerignore

@@ -5,6 +5,7 @@ target/
 .env
 .env.example
 .dockerignore
+.temp/
 Dockerfile
 docker-compose.yml
 erpc.yaml

.env.example

@@ -1,17 +1,26 @@
+# Required bearer token for admin/data API routes.
+API_TOKEN=replace-with-a-long-random-token
 # Default `postgres-storage` build. A `mongodb-storage` build can instead use
 # mongodb://localhost:27017/?replicaSet=rs0 and STORAGE_DATABASE=parseon.
 STORAGE_URL=postgres://postgres:postgres@localhost:5432/parseon
 # STORAGE_DATABASE=parseon
 HTTP_LISTEN=0.0.0.0:8080
 RUST_LOG=info,parseon=debug
+# Comma-separated browser origins; empty keeps CORS disabled.
+CORS_ORIGINS=
+MAX_BODY_BYTES=1048576
 POLL_INTERVAL_MS=2000
 DEFAULT_BATCH_SIZE=10
 # Set to 0 to disable Parseon's in-memory block cache.
 BLOCK_CACHE_SIZE=512
 BLOCK_CONCURRENCY=4
 RPC_REQUEST_CONCURRENCY=16
 STORAGE_WRITE_CONCURRENCY=4
+CONFIRMATION_DEPTH=64
+ROLLBACK_RETENTION=256
 RPC_BATCH_SIZE=20
+# Only enable for local RPC containers; keep false in production.
+ALLOW_PRIVATE_RPC_NETWORKS=false
 # Required only when built with `webhook-sink`.
 # WEBHOOK_URL=http://localhost:9000/parseon
 # WEBHOOK_CONCURRENCY=16

.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ fmt:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add rustfmt --toolchain 1.96.0
+ - run: cargo +1.96.0 fmt --all -- --check
+
+ rust:
+ runs-on: ubuntu-24.04
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: postgres
+ features: parseon-server/postgres-storage
+ - name: postgres-webhook
+ features: parseon-server/postgres-storage,parseon-server/webhook-sink
+ - name: mongodb
+ features: parseon-server/mongodb-storage
+ - name: mongodb-webhook
+ features: parseon-server/mongodb-storage,parseon-server/webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add clippy --toolchain 1.96.0
+ - run: cargo +1.96.0 clippy -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short -- -D warnings
+ - run: cargo +1.96.0 test -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short
+ - run: cargo +1.96.0 build -q -p parseon-server --release --locked --no-default-features --features "${{ matrix.features }}"
+
+ docker:
+ runs-on: ubuntu-24.04
+ strategy:
+ matrix:
+ include:
+ - name: postgres
+ features: postgres-storage
+ - name: postgres-webhook
+ features: postgres-storage,webhook-sink
+ - name: mongodb
+ features: mongodb-storage
+ - name: mongodb-webhook
+ features: mongodb-storage,webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Build image
+ run: docker build --build-arg PARSEON_FEATURES='${{ matrix.features }}' --tag parseon:ci .
+ - name: Generate SBOM when Docker SBOM support is installed
+ shell: bash
+ run: |
+ if docker sbom --help >/dev/null 2>&1; then
+ docker sbom parseon:ci > "sbom-${{ matrix.name }}.spdx.json"
+ else
+ echo 'docker sbom is unavailable on this runner; image SBOM is delegated to the registry scanner.'
+ fi
+ - name: Scan image when Docker Scout support is installed
+ shell: bash
+ run: |
+ if docker scout version >/dev/null 2>&1; then
+ docker scout cves --only-fixed parseon:ci
+ else
+ echo 'docker scout is unavailable on this runner; image scanning is delegated to the registry.'
+ fi
+
+ release-gates:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Validate production Compose
+ shell: bash
+ run: |
+ export PARSEON_IMAGE=registry.example/parseon@sha256:$(printf 'a%.0s' {1..64})
+ export STORAGE_URL='postgres://postgres:5432/parseon'
+ export POSTGRES_PASSWORD=test
+ export API_TOKEN=test-token
+ docker compose -f compose.production.yml config >/dev/null
+ if [[ ! "$PARSEON_IMAGE" =~ @sha256:[0-9a-fA-F]{64}$ ]]; then
+ echo 'PARSEON_IMAGE must be digest-pinned' >&2
+ exit 1
+ fi
+ - name: Validate Helm chart and immutable deployment policy
+ shell: bash
+ run: |
+ digest="sha256:$(printf 'a%.0s' {1..64})"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 lint deploy/helm/parseon --set image.digest="$digest"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" >/dev/null
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" --set replicaCount=2 >/dev/null 2>&1; then
+ echo 'replicaCount=2 was accepted' >&2
+ exit 1
+ fi
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon >/dev/null 2>&1; then
+ echo 'missing image digest was accepted' >&2
+ exit 1
+ fi
+ - name: Validate scripts and monitoring artifacts
+ shell: bash
+ run: |
+ bash -n scripts/backup_postgres.sh scripts/restore_postgres.sh
+ python3 -m py_compile scripts/gen_erpc.py
+ python3 -m json.tool deploy/monitoring/parseon-dashboard.json >/dev/null
+ secrets:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ fetch-depth: 0
+ - name: Reject credential-bearing generated config
+ shell: bash
+ run: |
+ if git grep -n -I -i -E '://[^[:space:]/:@]+:[^[:space:]@]+@|(^|[?&])(api[_-]?key|access[_-]?token|token|secret|password)=[^[:space:]&]{8,}' -- ':!CHANGELOG.md' ':!docs/operations.md' ':!.env.example'; then
+ echo 'credential-bearing URL or query parameter found in tracked source' >&2
+ exit 1
+ fi
+ echo 'Historical credentials still require independent revoke/rotate evidence.'

.gitignore

@@ -1,2 +1,3 @@
 /target
 /.env
+/.temp

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Added
 
+- Add canonical block metadata, provisional/finalized lifecycle, bounded reorg rollback, and finalized promotion for both storage adapters.
+- Add production Compose and Helm deployment artifacts, backup/restore operations runbook, Prometheus alerts, Grafana dashboard, and CI release gates.
 - Apply chain creation, enable/disable, and deletion to running workers without restarting Parseon; deletions stop the worker before removing its data.
 - Rotate a chain's RPC endpoint URL in place on the running worker via Alloy's `Http::set_url`, resetting endpoint capability probes while keeping the cached chain ID; sources that cannot rotate restart their worker instead.
 - Allow multiple monitors to target the same chain, contract, and function selector or event topic while retaining independent ranges, filters, cursors, and result storage.
@@ -15,6 +17,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Changed
 
+- Require a bearer API token for protected HTTP routes, disable CORS by default, bound request bodies, add liveness/readiness probes, and reject unsafe RPC destinations by default.
+- Treat credential-bearing eRPC URLs as operator-injected configuration instead of generated repository content.
 - Pin the Compose eRPC image to the `0.1.1` release tag, set a 3 GiB container memory limit with `GOMEMLIMIT=2700MiB`, add `restart: unless-stopped`, and invoke `/erpc-server` explicitly so the distroless image starts correctly.
 - Reuse matching RPC data and compatible ABI decoders across overlapping monitor targets before applying each monitor's filter and persisting its own results.
 - Isolate ABI decode failures to the affected monitor layout so an incompatible definition cannot stall other monitors on the chain.
@@ -32,6 +36,8 @@ All notable changes to Parseon are documented in this file.
 ### Fixed
 
 - Keep persisted chain state and live workers ordered during concurrent mutations and startup reconciliation, and reject new worker starts once supervisor shutdown begins.
+- Reject mixed-branch result identities, fail closed when a retained reorg ancestor is unavailable, preserve finalized state for monitors added over existing blocks, and reset rollback cursors below a monitor's start block.
+- Pin validated RPC DNS addresses in the HTTP transport, verify generated endpoint chain IDs, expose worker freshness/state metrics, and require encrypted checksum-verified PostgreSQL backup artifacts.
 
 ### Breaking
 

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 resolver = "3"
 
 [workspace.package]
-version = "0.8.0"
+version = "1.0.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # ---- chef base: shared Rust toolchain + cargo-chef ----
-FROM rust:1.96-alpine AS chef
+FROM rust:1.96-alpine@sha256:a41f7740f8b45d45795624eec13a8b42263cc700f19f7e4e86e04d3dda08a479 AS chef
 RUN apk add --no-cache musl-dev
 RUN cargo install cargo-chef --locked
 WORKDIR /app
@@ -18,7 +18,7 @@ ARG PARSEON_FEATURES=postgres-storage
 ENV PARSEON_FEATURES=${PARSEON_FEATURES}
 RUN apk add --no-cache watchexec
 COPY --from=planner /app/recipe.json recipe.json
-RUN cargo chef cook --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+RUN cargo chef cook --locked --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 EXPOSE 8080
 CMD ["sh", "-c", "exec watchexec --restart --stop-signal SIGINT --exts rs,toml,lock,sql -- cargo run --no-default-features --features \"${PARSEON_FEATURES}\""]
@@ -29,15 +29,15 @@ ARG PARSEON_FEATURES=postgres-storage
 COPY --from=planner /app/recipe.json recipe.json
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo chef cook --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+ cargo chef cook --locked --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo build --release --no-default-features --features "${PARSEON_FEATURES}" && \
+ cargo build --release --locked --no-default-features --features "${PARSEON_FEATURES}" && \
  cp /app/target/release/parseon /usr/local/bin/parseon
 
 # ---- runtime: minimal alpine, non-root, healthcheck ----
-FROM alpine:3.20 AS runtime
+FROM alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc AS runtime
 RUN apk add --no-cache ca-certificates wget && \
  adduser -D -u 1000 parseon
 COPY --from=builder /usr/local/bin/parseon /usr/local/bin/parseon

README.md

@@ -40,10 +40,14 @@ parseon-server
 └── parseon-webhook-sink ────> parseon-core
 ```
 
-Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL`, then register direct RPC or complete eRPC URLs through `POST /chains`.
+Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL` and set a non-empty `API_TOKEN`; protected API routes require `Authorization: Bearer <API_TOKEN>`. Register direct RPC or complete eRPC URLs through `POST /chains`. Private/loopback RPC destinations are rejected unless `ALLOW_PRIVATE_RPC_NETWORKS=true` is explicitly enabled for local development.
 
 See [adapter configuration and guarantees](./docs/adapters.md) for feature builds, MongoDB requirements, eRPC smoke checks, the webhook JSON contract, and Compose profiles.
 
+## Production deployment
+
+Use [`compose.production.yml`](./compose.production.yml) or the [`deploy/helm/parseon`](./deploy/helm/parseon) chart. Both require an externally managed `API_TOKEN` and storage URL, keep databases private, and expose liveness/readiness probes. Read the [production operations runbook](./docs/operations.md) before upgrading, restoring, or exposing the API through an ingress.
+
 ## License
 
 Licensed under either the [Apache License, Version 2.0](./LICENSE-APACHE) or the [MIT license](./LICENSE-MIT), at your option.

compose.production.yml

@@ -0,0 +1,70 @@
+services:
+ postgres:
+ image: ${POSTGRES_IMAGE:-postgres:16@sha256:f1c3376c26f2609ab9f29f71f824103fe2fcd8ee0346485cb6122a4f93df6f94}
+ restart: unless-stopped
+ environment:
+ POSTGRES_USER: ${POSTGRES_USER:-parseon}
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+ POSTGRES_DB: ${POSTGRES_DB:-parseon}
+ volumes:
+ - pgdata:/var/lib/postgresql/data
+ networks:
+ - backend
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ # No host port: PostgreSQL is reachable only by Parseon on the backend network.
+
+ parseon:
+ image: ${PARSEON_IMAGE:?set PARSEON_IMAGE to an immutable Parseon image}
+ restart: unless-stopped
+ depends_on:
+ postgres:
+ condition: service_healthy
+ environment:
+ STORAGE_URL: ${STORAGE_URL:?set STORAGE_URL}
+ API_TOKEN: ${API_TOKEN:?set API_TOKEN}
+ HTTP_LISTEN: 0.0.0.0:8080
+ RUST_LOG: ${RUST_LOG:-info}
+ POLL_INTERVAL_MS: ${POLL_INTERVAL_MS:-2000}
+ DEFAULT_BATCH_SIZE: ${DEFAULT_BATCH_SIZE:-10}
+ BLOCK_CACHE_SIZE: ${BLOCK_CACHE_SIZE:-512}
+ BLOCK_CONCURRENCY: ${BLOCK_CONCURRENCY:-4}
+ RPC_REQUEST_CONCURRENCY: ${RPC_REQUEST_CONCURRENCY:-16}
+ STORAGE_WRITE_CONCURRENCY: ${STORAGE_WRITE_CONCURRENCY:-4}
+ CONFIRMATION_DEPTH: ${CONFIRMATION_DEPTH:-64}
+ ROLLBACK_RETENTION: ${ROLLBACK_RETENTION:-256}
+ RPC_BATCH_SIZE: ${RPC_BATCH_SIZE:-20}
+ ALLOW_PRIVATE_RPC_NETWORKS: "false"
+ CORS_ORIGINS: ${CORS_ORIGINS:-}
+ MAX_BODY_BYTES: ${MAX_BODY_BYTES:-1048576}
+ expose:
+ - "8080"
+ networks:
+ - backend
+ - egress
+ read_only: true
+ tmpfs:
+ - /tmp
+ cap_drop:
+ - ALL
+ security_opt:
+ - no-new-privileges:true
+ mem_limit: ${PARSEON_MEMORY_LIMIT:-768m}
+ cpus: ${PARSEON_CPUS:-2}
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ interval: 10s
+ timeout: 5s
+ start_period: 20s
+ retries: 6
+
+volumes:
+ pgdata:
+
+networks:
+ backend:
+ internal: true
+ egress:

.dockerignore

@@ -5,6 +5,7 @@ target/
 .env
 .env.example
 .dockerignore
+.temp/
 Dockerfile
 docker-compose.yml
 erpc.yaml

.env.example

@@ -1,17 +1,26 @@
+# Required bearer token for admin/data API routes.
+API_TOKEN=replace-with-a-long-random-token
 # Default `postgres-storage` build. A `mongodb-storage` build can instead use
 # mongodb://localhost:27017/?replicaSet=rs0 and STORAGE_DATABASE=parseon.
 STORAGE_URL=postgres://postgres:postgres@localhost:5432/parseon
 # STORAGE_DATABASE=parseon
 HTTP_LISTEN=0.0.0.0:8080
 RUST_LOG=info,parseon=debug
+# Comma-separated browser origins; empty keeps CORS disabled.
+CORS_ORIGINS=
+MAX_BODY_BYTES=1048576
 POLL_INTERVAL_MS=2000
 DEFAULT_BATCH_SIZE=10
 # Set to 0 to disable Parseon's in-memory block cache.
 BLOCK_CACHE_SIZE=512
 BLOCK_CONCURRENCY=4
 RPC_REQUEST_CONCURRENCY=16
 STORAGE_WRITE_CONCURRENCY=4
+CONFIRMATION_DEPTH=64
+ROLLBACK_RETENTION=256
 RPC_BATCH_SIZE=20
+# Only enable for local RPC containers; keep false in production.
+ALLOW_PRIVATE_RPC_NETWORKS=false
 # Required only when built with `webhook-sink`.
 # WEBHOOK_URL=http://localhost:9000/parseon
 # WEBHOOK_CONCURRENCY=16

.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ fmt:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add rustfmt --toolchain 1.96.0
+ - run: cargo +1.96.0 fmt --all -- --check
+
+ rust:
+ runs-on: ubuntu-24.04
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: postgres
+ features: parseon-server/postgres-storage
+ - name: postgres-webhook
+ features: parseon-server/postgres-storage,parseon-server/webhook-sink
+ - name: mongodb
+ features: parseon-server/mongodb-storage
+ - name: mongodb-webhook
+ features: parseon-server/mongodb-storage,parseon-server/webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add clippy --toolchain 1.96.0
+ - run: cargo +1.96.0 clippy -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short -- -D warnings
+ - run: cargo +1.96.0 test -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short
+ - run: cargo +1.96.0 build -q -p parseon-server --release --locked --no-default-features --features "${{ matrix.features }}"
+
+ docker:
+ runs-on: ubuntu-24.04
+ strategy:
+ matrix:
+ include:
+ - name: postgres
+ features: postgres-storage
+ - name: postgres-webhook
+ features: postgres-storage,webhook-sink
+ - name: mongodb
+ features: mongodb-storage
+ - name: mongodb-webhook
+ features: mongodb-storage,webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Build image
+ run: docker build --build-arg PARSEON_FEATURES='${{ matrix.features }}' --tag parseon:ci .
+ - name: Generate SBOM when Docker SBOM support is installed
+ shell: bash
+ run: |
+ if docker sbom --help >/dev/null 2>&1; then
+ docker sbom parseon:ci > "sbom-${{ matrix.name }}.spdx.json"
+ else
+ echo 'docker sbom is unavailable on this runner; image SBOM is delegated to the registry scanner.'
+ fi
+ - name: Scan image when Docker Scout support is installed
+ shell: bash
+ run: |
+ if docker scout version >/dev/null 2>&1; then
+ docker scout cves --only-fixed parseon:ci
+ else
+ echo 'docker scout is unavailable on this runner; image scanning is delegated to the registry.'
+ fi
+
+ release-gates:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Validate production Compose
+ shell: bash
+ run: |
+ export PARSEON_IMAGE=registry.example/parseon@sha256:$(printf 'a%.0s' {1..64})
+ export STORAGE_URL='postgres://postgres:5432/parseon'
+ export POSTGRES_PASSWORD=test
+ export API_TOKEN=test-token
+ docker compose -f compose.production.yml config >/dev/null
+ if [[ ! "$PARSEON_IMAGE" =~ @sha256:[0-9a-fA-F]{64}$ ]]; then
+ echo 'PARSEON_IMAGE must be digest-pinned' >&2
+ exit 1
+ fi
+ - name: Validate Helm chart and immutable deployment policy
+ shell: bash
+ run: |
+ digest="sha256:$(printf 'a%.0s' {1..64})"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 lint deploy/helm/parseon --set image.digest="$digest"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" >/dev/null
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" --set replicaCount=2 >/dev/null 2>&1; then
+ echo 'replicaCount=2 was accepted' >&2
+ exit 1
+ fi
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon >/dev/null 2>&1; then
+ echo 'missing image digest was accepted' >&2
+ exit 1
+ fi
+ - name: Validate scripts and monitoring artifacts
+ shell: bash
+ run: |
+ bash -n scripts/backup_postgres.sh scripts/restore_postgres.sh
+ python3 -m py_compile scripts/gen_erpc.py
+ python3 -m json.tool deploy/monitoring/parseon-dashboard.json >/dev/null
+ secrets:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ fetch-depth: 0
+ - name: Reject credential-bearing generated config
+ shell: bash
+ run: |
+ if git grep -n -I -i -E '://[^[:space:]/:@]+:[^[:space:]@]+@|(^|[?&])(api[_-]?key|access[_-]?token|token|secret|password)=[^[:space:]&]{8,}' -- ':!CHANGELOG.md' ':!docs/operations.md' ':!.env.example'; then
+ echo 'credential-bearing URL or query parameter found in tracked source' >&2
+ exit 1
+ fi
+ echo 'Historical credentials still require independent revoke/rotate evidence.'

.gitignore

@@ -1,2 +1,3 @@
 /target
 /.env
+/.temp

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Added
 
+- Add canonical block metadata, provisional/finalized lifecycle, bounded reorg rollback, and finalized promotion for both storage adapters.
+- Add production Compose and Helm deployment artifacts, backup/restore operations runbook, Prometheus alerts, Grafana dashboard, and CI release gates.
 - Apply chain creation, enable/disable, and deletion to running workers without restarting Parseon; deletions stop the worker before removing its data.
 - Rotate a chain's RPC endpoint URL in place on the running worker via Alloy's `Http::set_url`, resetting endpoint capability probes while keeping the cached chain ID; sources that cannot rotate restart their worker instead.
 - Allow multiple monitors to target the same chain, contract, and function selector or event topic while retaining independent ranges, filters, cursors, and result storage.
@@ -15,6 +17,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Changed
 
+- Require a bearer API token for protected HTTP routes, disable CORS by default, bound request bodies, add liveness/readiness probes, and reject unsafe RPC destinations by default.
+- Treat credential-bearing eRPC URLs as operator-injected configuration instead of generated repository content.
 - Pin the Compose eRPC image to the `0.1.1` release tag, set a 3 GiB container memory limit with `GOMEMLIMIT=2700MiB`, add `restart: unless-stopped`, and invoke `/erpc-server` explicitly so the distroless image starts correctly.
 - Reuse matching RPC data and compatible ABI decoders across overlapping monitor targets before applying each monitor's filter and persisting its own results.
 - Isolate ABI decode failures to the affected monitor layout so an incompatible definition cannot stall other monitors on the chain.
@@ -32,6 +36,8 @@ All notable changes to Parseon are documented in this file.
 ### Fixed
 
 - Keep persisted chain state and live workers ordered during concurrent mutations and startup reconciliation, and reject new worker starts once supervisor shutdown begins.
+- Reject mixed-branch result identities, fail closed when a retained reorg ancestor is unavailable, preserve finalized state for monitors added over existing blocks, and reset rollback cursors below a monitor's start block.
+- Pin validated RPC DNS addresses in the HTTP transport, verify generated endpoint chain IDs, expose worker freshness/state metrics, and require encrypted checksum-verified PostgreSQL backup artifacts.
 
 ### Breaking
 

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 resolver = "3"
 
 [workspace.package]
-version = "0.8.0"
+version = "1.0.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # ---- chef base: shared Rust toolchain + cargo-chef ----
-FROM rust:1.96-alpine AS chef
+FROM rust:1.96-alpine@sha256:a41f7740f8b45d45795624eec13a8b42263cc700f19f7e4e86e04d3dda08a479 AS chef
 RUN apk add --no-cache musl-dev
 RUN cargo install cargo-chef --locked
 WORKDIR /app
@@ -18,7 +18,7 @@ ARG PARSEON_FEATURES=postgres-storage
 ENV PARSEON_FEATURES=${PARSEON_FEATURES}
 RUN apk add --no-cache watchexec
 COPY --from=planner /app/recipe.json recipe.json
-RUN cargo chef cook --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+RUN cargo chef cook --locked --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 EXPOSE 8080
 CMD ["sh", "-c", "exec watchexec --restart --stop-signal SIGINT --exts rs,toml,lock,sql -- cargo run --no-default-features --features \"${PARSEON_FEATURES}\""]
@@ -29,15 +29,15 @@ ARG PARSEON_FEATURES=postgres-storage
 COPY --from=planner /app/recipe.json recipe.json
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo chef cook --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+ cargo chef cook --locked --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo build --release --no-default-features --features "${PARSEON_FEATURES}" && \
+ cargo build --release --locked --no-default-features --features "${PARSEON_FEATURES}" && \
  cp /app/target/release/parseon /usr/local/bin/parseon
 
 # ---- runtime: minimal alpine, non-root, healthcheck ----
-FROM alpine:3.20 AS runtime
+FROM alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc AS runtime
 RUN apk add --no-cache ca-certificates wget && \
  adduser -D -u 1000 parseon
 COPY --from=builder /usr/local/bin/parseon /usr/local/bin/parseon

README.md

@@ -40,10 +40,14 @@ parseon-server
 └── parseon-webhook-sink ────> parseon-core
 ```
 
-Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL`, then register direct RPC or complete eRPC URLs through `POST /chains`.
+Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL` and set a non-empty `API_TOKEN`; protected API routes require `Authorization: Bearer <API_TOKEN>`. Register direct RPC or complete eRPC URLs through `POST /chains`. Private/loopback RPC destinations are rejected unless `ALLOW_PRIVATE_RPC_NETWORKS=true` is explicitly enabled for local development.
 
 See [adapter configuration and guarantees](./docs/adapters.md) for feature builds, MongoDB requirements, eRPC smoke checks, the webhook JSON contract, and Compose profiles.
 
+## Production deployment
+
+Use [`compose.production.yml`](./compose.production.yml) or the [`deploy/helm/parseon`](./deploy/helm/parseon) chart. Both require an externally managed `API_TOKEN` and storage URL, keep databases private, and expose liveness/readiness probes. Read the [production operations runbook](./docs/operations.md) before upgrading, restoring, or exposing the API through an ingress.
+
 ## License
 
 Licensed under either the [Apache License, Version 2.0](./LICENSE-APACHE) or the [MIT license](./LICENSE-MIT), at your option.

compose.production.yml

@@ -0,0 +1,70 @@
+services:
+ postgres:
+ image: ${POSTGRES_IMAGE:-postgres:16@sha256:f1c3376c26f2609ab9f29f71f824103fe2fcd8ee0346485cb6122a4f93df6f94}
+ restart: unless-stopped
+ environment:
+ POSTGRES_USER: ${POSTGRES_USER:-parseon}
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+ POSTGRES_DB: ${POSTGRES_DB:-parseon}
+ volumes:
+ - pgdata:/var/lib/postgresql/data
+ networks:
+ - backend
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ # No host port: PostgreSQL is reachable only by Parseon on the backend network.
+
+ parseon:
+ image: ${PARSEON_IMAGE:?set PARSEON_IMAGE to an immutable Parseon image}
+ restart: unless-stopped
+ depends_on:
+ postgres:
+ condition: service_healthy
+ environment:
+ STORAGE_URL: ${STORAGE_URL:?set STORAGE_URL}
+ API_TOKEN: ${API_TOKEN:?set API_TOKEN}
+ HTTP_LISTEN: 0.0.0.0:8080
+ RUST_LOG: ${RUST_LOG:-info}
+ POLL_INTERVAL_MS: ${POLL_INTERVAL_MS:-2000}
+ DEFAULT_BATCH_SIZE: ${DEFAULT_BATCH_SIZE:-10}
+ BLOCK_CACHE_SIZE: ${BLOCK_CACHE_SIZE:-512}
+ BLOCK_CONCURRENCY: ${BLOCK_CONCURRENCY:-4}
+ RPC_REQUEST_CONCURRENCY: ${RPC_REQUEST_CONCURRENCY:-16}
+ STORAGE_WRITE_CONCURRENCY: ${STORAGE_WRITE_CONCURRENCY:-4}
+ CONFIRMATION_DEPTH: ${CONFIRMATION_DEPTH:-64}
+ ROLLBACK_RETENTION: ${ROLLBACK_RETENTION:-256}
+ RPC_BATCH_SIZE: ${RPC_BATCH_SIZE:-20}
+ ALLOW_PRIVATE_RPC_NETWORKS: "false"
+ CORS_ORIGINS: ${CORS_ORIGINS:-}
+ MAX_BODY_BYTES: ${MAX_BODY_BYTES:-1048576}
+ expose:
+ - "8080"
+ networks:
+ - backend
+ - egress
+ read_only: true
+ tmpfs:
+ - /tmp
+ cap_drop:
+ - ALL
+ security_opt:
+ - no-new-privileges:true
+ mem_limit: ${PARSEON_MEMORY_LIMIT:-768m}
+ cpus: ${PARSEON_CPUS:-2}
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ interval: 10s
+ timeout: 5s
+ start_period: 20s
+ retries: 6
+
+volumes:
+ pgdata:
+
+networks:
+ backend:
+ internal: true
+ egress:

.dockerignore

@@ -5,6 +5,7 @@ target/
 .env
 .env.example
 .dockerignore
+.temp/
 Dockerfile
 docker-compose.yml
 erpc.yaml

.env.example

@@ -1,17 +1,26 @@
+# Required bearer token for admin/data API routes.
+API_TOKEN=replace-with-a-long-random-token
 # Default `postgres-storage` build. A `mongodb-storage` build can instead use
 # mongodb://localhost:27017/?replicaSet=rs0 and STORAGE_DATABASE=parseon.
 STORAGE_URL=postgres://postgres:postgres@localhost:5432/parseon
 # STORAGE_DATABASE=parseon
 HTTP_LISTEN=0.0.0.0:8080
 RUST_LOG=info,parseon=debug
+# Comma-separated browser origins; empty keeps CORS disabled.
+CORS_ORIGINS=
+MAX_BODY_BYTES=1048576
 POLL_INTERVAL_MS=2000
 DEFAULT_BATCH_SIZE=10
 # Set to 0 to disable Parseon's in-memory block cache.
 BLOCK_CACHE_SIZE=512
 BLOCK_CONCURRENCY=4
 RPC_REQUEST_CONCURRENCY=16
 STORAGE_WRITE_CONCURRENCY=4
+CONFIRMATION_DEPTH=64
+ROLLBACK_RETENTION=256
 RPC_BATCH_SIZE=20
+# Only enable for local RPC containers; keep false in production.
+ALLOW_PRIVATE_RPC_NETWORKS=false
 # Required only when built with `webhook-sink`.
 # WEBHOOK_URL=http://localhost:9000/parseon
 # WEBHOOK_CONCURRENCY=16

.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ fmt:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add rustfmt --toolchain 1.96.0
+ - run: cargo +1.96.0 fmt --all -- --check
+
+ rust:
+ runs-on: ubuntu-24.04
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: postgres
+ features: parseon-server/postgres-storage
+ - name: postgres-webhook
+ features: parseon-server/postgres-storage,parseon-server/webhook-sink
+ - name: mongodb
+ features: parseon-server/mongodb-storage
+ - name: mongodb-webhook
+ features: parseon-server/mongodb-storage,parseon-server/webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add clippy --toolchain 1.96.0
+ - run: cargo +1.96.0 clippy -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short -- -D warnings
+ - run: cargo +1.96.0 test -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short
+ - run: cargo +1.96.0 build -q -p parseon-server --release --locked --no-default-features --features "${{ matrix.features }}"
+
+ docker:
+ runs-on: ubuntu-24.04
+ strategy:
+ matrix:
+ include:
+ - name: postgres
+ features: postgres-storage
+ - name: postgres-webhook
+ features: postgres-storage,webhook-sink
+ - name: mongodb
+ features: mongodb-storage
+ - name: mongodb-webhook
+ features: mongodb-storage,webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Build image
+ run: docker build --build-arg PARSEON_FEATURES='${{ matrix.features }}' --tag parseon:ci .
+ - name: Generate SBOM when Docker SBOM support is installed
+ shell: bash
+ run: |
+ if docker sbom --help >/dev/null 2>&1; then
+ docker sbom parseon:ci > "sbom-${{ matrix.name }}.spdx.json"
+ else
+ echo 'docker sbom is unavailable on this runner; image SBOM is delegated to the registry scanner.'
+ fi
+ - name: Scan image when Docker Scout support is installed
+ shell: bash
+ run: |
+ if docker scout version >/dev/null 2>&1; then
+ docker scout cves --only-fixed parseon:ci
+ else
+ echo 'docker scout is unavailable on this runner; image scanning is delegated to the registry.'
+ fi
+
+ release-gates:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Validate production Compose
+ shell: bash
+ run: |
+ export PARSEON_IMAGE=registry.example/parseon@sha256:$(printf 'a%.0s' {1..64})
+ export STORAGE_URL='postgres://postgres:5432/parseon'
+ export POSTGRES_PASSWORD=test
+ export API_TOKEN=test-token
+ docker compose -f compose.production.yml config >/dev/null
+ if [[ ! "$PARSEON_IMAGE" =~ @sha256:[0-9a-fA-F]{64}$ ]]; then
+ echo 'PARSEON_IMAGE must be digest-pinned' >&2
+ exit 1
+ fi
+ - name: Validate Helm chart and immutable deployment policy
+ shell: bash
+ run: |
+ digest="sha256:$(printf 'a%.0s' {1..64})"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 lint deploy/helm/parseon --set image.digest="$digest"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" >/dev/null
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" --set replicaCount=2 >/dev/null 2>&1; then
+ echo 'replicaCount=2 was accepted' >&2
+ exit 1
+ fi
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon >/dev/null 2>&1; then
+ echo 'missing image digest was accepted' >&2
+ exit 1
+ fi
+ - name: Validate scripts and monitoring artifacts
+ shell: bash
+ run: |
+ bash -n scripts/backup_postgres.sh scripts/restore_postgres.sh
+ python3 -m py_compile scripts/gen_erpc.py
+ python3 -m json.tool deploy/monitoring/parseon-dashboard.json >/dev/null
+ secrets:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ fetch-depth: 0
+ - name: Reject credential-bearing generated config
+ shell: bash
+ run: |
+ if git grep -n -I -i -E '://[^[:space:]/:@]+:[^[:space:]@]+@|(^|[?&])(api[_-]?key|access[_-]?token|token|secret|password)=[^[:space:]&]{8,}' -- ':!CHANGELOG.md' ':!docs/operations.md' ':!.env.example'; then
+ echo 'credential-bearing URL or query parameter found in tracked source' >&2
+ exit 1
+ fi
+ echo 'Historical credentials still require independent revoke/rotate evidence.'

.gitignore

@@ -1,2 +1,3 @@
 /target
 /.env
+/.temp

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Added
 
+- Add canonical block metadata, provisional/finalized lifecycle, bounded reorg rollback, and finalized promotion for both storage adapters.
+- Add production Compose and Helm deployment artifacts, backup/restore operations runbook, Prometheus alerts, Grafana dashboard, and CI release gates.
 - Apply chain creation, enable/disable, and deletion to running workers without restarting Parseon; deletions stop the worker before removing its data.
 - Rotate a chain's RPC endpoint URL in place on the running worker via Alloy's `Http::set_url`, resetting endpoint capability probes while keeping the cached chain ID; sources that cannot rotate restart their worker instead.
 - Allow multiple monitors to target the same chain, contract, and function selector or event topic while retaining independent ranges, filters, cursors, and result storage.
@@ -15,6 +17,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Changed
 
+- Require a bearer API token for protected HTTP routes, disable CORS by default, bound request bodies, add liveness/readiness probes, and reject unsafe RPC destinations by default.
+- Treat credential-bearing eRPC URLs as operator-injected configuration instead of generated repository content.
 - Pin the Compose eRPC image to the `0.1.1` release tag, set a 3 GiB container memory limit with `GOMEMLIMIT=2700MiB`, add `restart: unless-stopped`, and invoke `/erpc-server` explicitly so the distroless image starts correctly.
 - Reuse matching RPC data and compatible ABI decoders across overlapping monitor targets before applying each monitor's filter and persisting its own results.
 - Isolate ABI decode failures to the affected monitor layout so an incompatible definition cannot stall other monitors on the chain.
@@ -32,6 +36,8 @@ All notable changes to Parseon are documented in this file.
 ### Fixed
 
 - Keep persisted chain state and live workers ordered during concurrent mutations and startup reconciliation, and reject new worker starts once supervisor shutdown begins.
+- Reject mixed-branch result identities, fail closed when a retained reorg ancestor is unavailable, preserve finalized state for monitors added over existing blocks, and reset rollback cursors below a monitor's start block.
+- Pin validated RPC DNS addresses in the HTTP transport, verify generated endpoint chain IDs, expose worker freshness/state metrics, and require encrypted checksum-verified PostgreSQL backup artifacts.
 
 ### Breaking
 

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 resolver = "3"
 
 [workspace.package]
-version = "0.8.0"
+version = "1.0.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # ---- chef base: shared Rust toolchain + cargo-chef ----
-FROM rust:1.96-alpine AS chef
+FROM rust:1.96-alpine@sha256:a41f7740f8b45d45795624eec13a8b42263cc700f19f7e4e86e04d3dda08a479 AS chef
 RUN apk add --no-cache musl-dev
 RUN cargo install cargo-chef --locked
 WORKDIR /app
@@ -18,7 +18,7 @@ ARG PARSEON_FEATURES=postgres-storage
 ENV PARSEON_FEATURES=${PARSEON_FEATURES}
 RUN apk add --no-cache watchexec
 COPY --from=planner /app/recipe.json recipe.json
-RUN cargo chef cook --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+RUN cargo chef cook --locked --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 EXPOSE 8080
 CMD ["sh", "-c", "exec watchexec --restart --stop-signal SIGINT --exts rs,toml,lock,sql -- cargo run --no-default-features --features \"${PARSEON_FEATURES}\""]
@@ -29,15 +29,15 @@ ARG PARSEON_FEATURES=postgres-storage
 COPY --from=planner /app/recipe.json recipe.json
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo chef cook --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+ cargo chef cook --locked --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo build --release --no-default-features --features "${PARSEON_FEATURES}" && \
+ cargo build --release --locked --no-default-features --features "${PARSEON_FEATURES}" && \
  cp /app/target/release/parseon /usr/local/bin/parseon
 
 # ---- runtime: minimal alpine, non-root, healthcheck ----
-FROM alpine:3.20 AS runtime
+FROM alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc AS runtime
 RUN apk add --no-cache ca-certificates wget && \
  adduser -D -u 1000 parseon
 COPY --from=builder /usr/local/bin/parseon /usr/local/bin/parseon

README.md

@@ -40,10 +40,14 @@ parseon-server
 └── parseon-webhook-sink ────> parseon-core
 ```
 
-Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL`, then register direct RPC or complete eRPC URLs through `POST /chains`.
+Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL` and set a non-empty `API_TOKEN`; protected API routes require `Authorization: Bearer <API_TOKEN>`. Register direct RPC or complete eRPC URLs through `POST /chains`. Private/loopback RPC destinations are rejected unless `ALLOW_PRIVATE_RPC_NETWORKS=true` is explicitly enabled for local development.
 
 See [adapter configuration and guarantees](./docs/adapters.md) for feature builds, MongoDB requirements, eRPC smoke checks, the webhook JSON contract, and Compose profiles.
 
+## Production deployment
+
+Use [`compose.production.yml`](./compose.production.yml) or the [`deploy/helm/parseon`](./deploy/helm/parseon) chart. Both require an externally managed `API_TOKEN` and storage URL, keep databases private, and expose liveness/readiness probes. Read the [production operations runbook](./docs/operations.md) before upgrading, restoring, or exposing the API through an ingress.
+
 ## License
 
 Licensed under either the [Apache License, Version 2.0](./LICENSE-APACHE) or the [MIT license](./LICENSE-MIT), at your option.

compose.production.yml

@@ -0,0 +1,70 @@
+services:
+ postgres:
+ image: ${POSTGRES_IMAGE:-postgres:16@sha256:f1c3376c26f2609ab9f29f71f824103fe2fcd8ee0346485cb6122a4f93df6f94}
+ restart: unless-stopped
+ environment:
+ POSTGRES_USER: ${POSTGRES_USER:-parseon}
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+ POSTGRES_DB: ${POSTGRES_DB:-parseon}
+ volumes:
+ - pgdata:/var/lib/postgresql/data
+ networks:
+ - backend
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ # No host port: PostgreSQL is reachable only by Parseon on the backend network.
+
+ parseon:
+ image: ${PARSEON_IMAGE:?set PARSEON_IMAGE to an immutable Parseon image}
+ restart: unless-stopped
+ depends_on:
+ postgres:
+ condition: service_healthy
+ environment:
+ STORAGE_URL: ${STORAGE_URL:?set STORAGE_URL}
+ API_TOKEN: ${API_TOKEN:?set API_TOKEN}
+ HTTP_LISTEN: 0.0.0.0:8080
+ RUST_LOG: ${RUST_LOG:-info}
+ POLL_INTERVAL_MS: ${POLL_INTERVAL_MS:-2000}
+ DEFAULT_BATCH_SIZE: ${DEFAULT_BATCH_SIZE:-10}
+ BLOCK_CACHE_SIZE: ${BLOCK_CACHE_SIZE:-512}
+ BLOCK_CONCURRENCY: ${BLOCK_CONCURRENCY:-4}
+ RPC_REQUEST_CONCURRENCY: ${RPC_REQUEST_CONCURRENCY:-16}
+ STORAGE_WRITE_CONCURRENCY: ${STORAGE_WRITE_CONCURRENCY:-4}
+ CONFIRMATION_DEPTH: ${CONFIRMATION_DEPTH:-64}
+ ROLLBACK_RETENTION: ${ROLLBACK_RETENTION:-256}
+ RPC_BATCH_SIZE: ${RPC_BATCH_SIZE:-20}
+ ALLOW_PRIVATE_RPC_NETWORKS: "false"
+ CORS_ORIGINS: ${CORS_ORIGINS:-}
+ MAX_BODY_BYTES: ${MAX_BODY_BYTES:-1048576}
+ expose:
+ - "8080"
+ networks:
+ - backend
+ - egress
+ read_only: true
+ tmpfs:
+ - /tmp
+ cap_drop:
+ - ALL
+ security_opt:
+ - no-new-privileges:true
+ mem_limit: ${PARSEON_MEMORY_LIMIT:-768m}
+ cpus: ${PARSEON_CPUS:-2}
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ interval: 10s
+ timeout: 5s
+ start_period: 20s
+ retries: 6
+
+volumes:
+ pgdata:
+
+networks:
+ backend:
+ internal: true
+ egress:

.dockerignore

@@ -5,6 +5,7 @@ target/
 .env
 .env.example
 .dockerignore
+.temp/
 Dockerfile
 docker-compose.yml
 erpc.yaml

.env.example

@@ -1,17 +1,26 @@
+# Required bearer token for admin/data API routes.
+API_TOKEN=replace-with-a-long-random-token
 # Default `postgres-storage` build. A `mongodb-storage` build can instead use
 # mongodb://localhost:27017/?replicaSet=rs0 and STORAGE_DATABASE=parseon.
 STORAGE_URL=postgres://postgres:postgres@localhost:5432/parseon
 # STORAGE_DATABASE=parseon
 HTTP_LISTEN=0.0.0.0:8080
 RUST_LOG=info,parseon=debug
+# Comma-separated browser origins; empty keeps CORS disabled.
+CORS_ORIGINS=
+MAX_BODY_BYTES=1048576
 POLL_INTERVAL_MS=2000
 DEFAULT_BATCH_SIZE=10
 # Set to 0 to disable Parseon's in-memory block cache.
 BLOCK_CACHE_SIZE=512
 BLOCK_CONCURRENCY=4
 RPC_REQUEST_CONCURRENCY=16
 STORAGE_WRITE_CONCURRENCY=4
+CONFIRMATION_DEPTH=64
+ROLLBACK_RETENTION=256
 RPC_BATCH_SIZE=20
+# Only enable for local RPC containers; keep false in production.
+ALLOW_PRIVATE_RPC_NETWORKS=false
 # Required only when built with `webhook-sink`.
 # WEBHOOK_URL=http://localhost:9000/parseon
 # WEBHOOK_CONCURRENCY=16

.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ fmt:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add rustfmt --toolchain 1.96.0
+ - run: cargo +1.96.0 fmt --all -- --check
+
+ rust:
+ runs-on: ubuntu-24.04
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: postgres
+ features: parseon-server/postgres-storage
+ - name: postgres-webhook
+ features: parseon-server/postgres-storage,parseon-server/webhook-sink
+ - name: mongodb
+ features: parseon-server/mongodb-storage
+ - name: mongodb-webhook
+ features: parseon-server/mongodb-storage,parseon-server/webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add clippy --toolchain 1.96.0
+ - run: cargo +1.96.0 clippy -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short -- -D warnings
+ - run: cargo +1.96.0 test -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short
+ - run: cargo +1.96.0 build -q -p parseon-server --release --locked --no-default-features --features "${{ matrix.features }}"
+
+ docker:
+ runs-on: ubuntu-24.04
+ strategy:
+ matrix:
+ include:
+ - name: postgres
+ features: postgres-storage
+ - name: postgres-webhook
+ features: postgres-storage,webhook-sink
+ - name: mongodb
+ features: mongodb-storage
+ - name: mongodb-webhook
+ features: mongodb-storage,webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Build image
+ run: docker build --build-arg PARSEON_FEATURES='${{ matrix.features }}' --tag parseon:ci .
+ - name: Generate SBOM when Docker SBOM support is installed
+ shell: bash
+ run: |
+ if docker sbom --help >/dev/null 2>&1; then
+ docker sbom parseon:ci > "sbom-${{ matrix.name }}.spdx.json"
+ else
+ echo 'docker sbom is unavailable on this runner; image SBOM is delegated to the registry scanner.'
+ fi
+ - name: Scan image when Docker Scout support is installed
+ shell: bash
+ run: |
+ if docker scout version >/dev/null 2>&1; then
+ docker scout cves --only-fixed parseon:ci
+ else
+ echo 'docker scout is unavailable on this runner; image scanning is delegated to the registry.'
+ fi
+
+ release-gates:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Validate production Compose
+ shell: bash
+ run: |
+ export PARSEON_IMAGE=registry.example/parseon@sha256:$(printf 'a%.0s' {1..64})
+ export STORAGE_URL='postgres://postgres:5432/parseon'
+ export POSTGRES_PASSWORD=test
+ export API_TOKEN=test-token
+ docker compose -f compose.production.yml config >/dev/null
+ if [[ ! "$PARSEON_IMAGE" =~ @sha256:[0-9a-fA-F]{64}$ ]]; then
+ echo 'PARSEON_IMAGE must be digest-pinned' >&2
+ exit 1
+ fi
+ - name: Validate Helm chart and immutable deployment policy
+ shell: bash
+ run: |
+ digest="sha256:$(printf 'a%.0s' {1..64})"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 lint deploy/helm/parseon --set image.digest="$digest"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" >/dev/null
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" --set replicaCount=2 >/dev/null 2>&1; then
+ echo 'replicaCount=2 was accepted' >&2
+ exit 1
+ fi
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon >/dev/null 2>&1; then
+ echo 'missing image digest was accepted' >&2
+ exit 1
+ fi
+ - name: Validate scripts and monitoring artifacts
+ shell: bash
+ run: |
+ bash -n scripts/backup_postgres.sh scripts/restore_postgres.sh
+ python3 -m py_compile scripts/gen_erpc.py
+ python3 -m json.tool deploy/monitoring/parseon-dashboard.json >/dev/null
+ secrets:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ fetch-depth: 0
+ - name: Reject credential-bearing generated config
+ shell: bash
+ run: |
+ if git grep -n -I -i -E '://[^[:space:]/:@]+:[^[:space:]@]+@|(^|[?&])(api[_-]?key|access[_-]?token|token|secret|password)=[^[:space:]&]{8,}' -- ':!CHANGELOG.md' ':!docs/operations.md' ':!.env.example'; then
+ echo 'credential-bearing URL or query parameter found in tracked source' >&2
+ exit 1
+ fi
+ echo 'Historical credentials still require independent revoke/rotate evidence.'

.gitignore

@@ -1,2 +1,3 @@
 /target
 /.env
+/.temp

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Added
 
+- Add canonical block metadata, provisional/finalized lifecycle, bounded reorg rollback, and finalized promotion for both storage adapters.
+- Add production Compose and Helm deployment artifacts, backup/restore operations runbook, Prometheus alerts, Grafana dashboard, and CI release gates.
 - Apply chain creation, enable/disable, and deletion to running workers without restarting Parseon; deletions stop the worker before removing its data.
 - Rotate a chain's RPC endpoint URL in place on the running worker via Alloy's `Http::set_url`, resetting endpoint capability probes while keeping the cached chain ID; sources that cannot rotate restart their worker instead.
 - Allow multiple monitors to target the same chain, contract, and function selector or event topic while retaining independent ranges, filters, cursors, and result storage.
@@ -15,6 +17,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Changed
 
+- Require a bearer API token for protected HTTP routes, disable CORS by default, bound request bodies, add liveness/readiness probes, and reject unsafe RPC destinations by default.
+- Treat credential-bearing eRPC URLs as operator-injected configuration instead of generated repository content.
 - Pin the Compose eRPC image to the `0.1.1` release tag, set a 3 GiB container memory limit with `GOMEMLIMIT=2700MiB`, add `restart: unless-stopped`, and invoke `/erpc-server` explicitly so the distroless image starts correctly.
 - Reuse matching RPC data and compatible ABI decoders across overlapping monitor targets before applying each monitor's filter and persisting its own results.
 - Isolate ABI decode failures to the affected monitor layout so an incompatible definition cannot stall other monitors on the chain.
@@ -32,6 +36,8 @@ All notable changes to Parseon are documented in this file.
 ### Fixed
 
 - Keep persisted chain state and live workers ordered during concurrent mutations and startup reconciliation, and reject new worker starts once supervisor shutdown begins.
+- Reject mixed-branch result identities, fail closed when a retained reorg ancestor is unavailable, preserve finalized state for monitors added over existing blocks, and reset rollback cursors below a monitor's start block.
+- Pin validated RPC DNS addresses in the HTTP transport, verify generated endpoint chain IDs, expose worker freshness/state metrics, and require encrypted checksum-verified PostgreSQL backup artifacts.
 
 ### Breaking
 

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 resolver = "3"
 
 [workspace.package]
-version = "0.8.0"
+version = "1.0.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # ---- chef base: shared Rust toolchain + cargo-chef ----
-FROM rust:1.96-alpine AS chef
+FROM rust:1.96-alpine@sha256:a41f7740f8b45d45795624eec13a8b42263cc700f19f7e4e86e04d3dda08a479 AS chef
 RUN apk add --no-cache musl-dev
 RUN cargo install cargo-chef --locked
 WORKDIR /app
@@ -18,7 +18,7 @@ ARG PARSEON_FEATURES=postgres-storage
 ENV PARSEON_FEATURES=${PARSEON_FEATURES}
 RUN apk add --no-cache watchexec
 COPY --from=planner /app/recipe.json recipe.json
-RUN cargo chef cook --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+RUN cargo chef cook --locked --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 EXPOSE 8080
 CMD ["sh", "-c", "exec watchexec --restart --stop-signal SIGINT --exts rs,toml,lock,sql -- cargo run --no-default-features --features \"${PARSEON_FEATURES}\""]
@@ -29,15 +29,15 @@ ARG PARSEON_FEATURES=postgres-storage
 COPY --from=planner /app/recipe.json recipe.json
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo chef cook --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+ cargo chef cook --locked --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo build --release --no-default-features --features "${PARSEON_FEATURES}" && \
+ cargo build --release --locked --no-default-features --features "${PARSEON_FEATURES}" && \
  cp /app/target/release/parseon /usr/local/bin/parseon
 
 # ---- runtime: minimal alpine, non-root, healthcheck ----
-FROM alpine:3.20 AS runtime
+FROM alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc AS runtime
 RUN apk add --no-cache ca-certificates wget && \
  adduser -D -u 1000 parseon
 COPY --from=builder /usr/local/bin/parseon /usr/local/bin/parseon

README.md

@@ -40,10 +40,14 @@ parseon-server
 └── parseon-webhook-sink ────> parseon-core
 ```
 
-Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL`, then register direct RPC or complete eRPC URLs through `POST /chains`.
+Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL` and set a non-empty `API_TOKEN`; protected API routes require `Authorization: Bearer <API_TOKEN>`. Register direct RPC or complete eRPC URLs through `POST /chains`. Private/loopback RPC destinations are rejected unless `ALLOW_PRIVATE_RPC_NETWORKS=true` is explicitly enabled for local development.
 
 See [adapter configuration and guarantees](./docs/adapters.md) for feature builds, MongoDB requirements, eRPC smoke checks, the webhook JSON contract, and Compose profiles.
 
+## Production deployment
+
+Use [`compose.production.yml`](./compose.production.yml) or the [`deploy/helm/parseon`](./deploy/helm/parseon) chart. Both require an externally managed `API_TOKEN` and storage URL, keep databases private, and expose liveness/readiness probes. Read the [production operations runbook](./docs/operations.md) before upgrading, restoring, or exposing the API through an ingress.
+
 ## License
 
 Licensed under either the [Apache License, Version 2.0](./LICENSE-APACHE) or the [MIT license](./LICENSE-MIT), at your option.

compose.production.yml

@@ -0,0 +1,70 @@
+services:
+ postgres:
+ image: ${POSTGRES_IMAGE:-postgres:16@sha256:f1c3376c26f2609ab9f29f71f824103fe2fcd8ee0346485cb6122a4f93df6f94}
+ restart: unless-stopped
+ environment:
+ POSTGRES_USER: ${POSTGRES_USER:-parseon}
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+ POSTGRES_DB: ${POSTGRES_DB:-parseon}
+ volumes:
+ - pgdata:/var/lib/postgresql/data
+ networks:
+ - backend
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ # No host port: PostgreSQL is reachable only by Parseon on the backend network.
+
+ parseon:
+ image: ${PARSEON_IMAGE:?set PARSEON_IMAGE to an immutable Parseon image}
+ restart: unless-stopped
+ depends_on:
+ postgres:
+ condition: service_healthy
+ environment:
+ STORAGE_URL: ${STORAGE_URL:?set STORAGE_URL}
+ API_TOKEN: ${API_TOKEN:?set API_TOKEN}
+ HTTP_LISTEN: 0.0.0.0:8080
+ RUST_LOG: ${RUST_LOG:-info}
+ POLL_INTERVAL_MS: ${POLL_INTERVAL_MS:-2000}
+ DEFAULT_BATCH_SIZE: ${DEFAULT_BATCH_SIZE:-10}
+ BLOCK_CACHE_SIZE: ${BLOCK_CACHE_SIZE:-512}
+ BLOCK_CONCURRENCY: ${BLOCK_CONCURRENCY:-4}
+ RPC_REQUEST_CONCURRENCY: ${RPC_REQUEST_CONCURRENCY:-16}
+ STORAGE_WRITE_CONCURRENCY: ${STORAGE_WRITE_CONCURRENCY:-4}
+ CONFIRMATION_DEPTH: ${CONFIRMATION_DEPTH:-64}
+ ROLLBACK_RETENTION: ${ROLLBACK_RETENTION:-256}
+ RPC_BATCH_SIZE: ${RPC_BATCH_SIZE:-20}
+ ALLOW_PRIVATE_RPC_NETWORKS: "false"
+ CORS_ORIGINS: ${CORS_ORIGINS:-}
+ MAX_BODY_BYTES: ${MAX_BODY_BYTES:-1048576}
+ expose:
+ - "8080"
+ networks:
+ - backend
+ - egress
+ read_only: true
+ tmpfs:
+ - /tmp
+ cap_drop:
+ - ALL
+ security_opt:
+ - no-new-privileges:true
+ mem_limit: ${PARSEON_MEMORY_LIMIT:-768m}
+ cpus: ${PARSEON_CPUS:-2}
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ interval: 10s
+ timeout: 5s
+ start_period: 20s
+ retries: 6
+
+volumes:
+ pgdata:
+
+networks:
+ backend:
+ internal: true
+ egress:

.dockerignore

@@ -5,6 +5,7 @@ target/
 .env
 .env.example
 .dockerignore
+.temp/
 Dockerfile
 docker-compose.yml
 erpc.yaml

.env.example

@@ -1,17 +1,26 @@
+# Required bearer token for admin/data API routes.
+API_TOKEN=replace-with-a-long-random-token
 # Default `postgres-storage` build. A `mongodb-storage` build can instead use
 # mongodb://localhost:27017/?replicaSet=rs0 and STORAGE_DATABASE=parseon.
 STORAGE_URL=postgres://postgres:postgres@localhost:5432/parseon
 # STORAGE_DATABASE=parseon
 HTTP_LISTEN=0.0.0.0:8080
 RUST_LOG=info,parseon=debug
+# Comma-separated browser origins; empty keeps CORS disabled.
+CORS_ORIGINS=
+MAX_BODY_BYTES=1048576
 POLL_INTERVAL_MS=2000
 DEFAULT_BATCH_SIZE=10
 # Set to 0 to disable Parseon's in-memory block cache.
 BLOCK_CACHE_SIZE=512
 BLOCK_CONCURRENCY=4
 RPC_REQUEST_CONCURRENCY=16
 STORAGE_WRITE_CONCURRENCY=4
+CONFIRMATION_DEPTH=64
+ROLLBACK_RETENTION=256
 RPC_BATCH_SIZE=20
+# Only enable for local RPC containers; keep false in production.
+ALLOW_PRIVATE_RPC_NETWORKS=false
 # Required only when built with `webhook-sink`.
 # WEBHOOK_URL=http://localhost:9000/parseon
 # WEBHOOK_CONCURRENCY=16

.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ fmt:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add rustfmt --toolchain 1.96.0
+ - run: cargo +1.96.0 fmt --all -- --check
+
+ rust:
+ runs-on: ubuntu-24.04
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: postgres
+ features: parseon-server/postgres-storage
+ - name: postgres-webhook
+ features: parseon-server/postgres-storage,parseon-server/webhook-sink
+ - name: mongodb
+ features: parseon-server/mongodb-storage
+ - name: mongodb-webhook
+ features: parseon-server/mongodb-storage,parseon-server/webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add clippy --toolchain 1.96.0
+ - run: cargo +1.96.0 clippy -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short -- -D warnings
+ - run: cargo +1.96.0 test -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short
+ - run: cargo +1.96.0 build -q -p parseon-server --release --locked --no-default-features --features "${{ matrix.features }}"
+
+ docker:
+ runs-on: ubuntu-24.04
+ strategy:
+ matrix:
+ include:
+ - name: postgres
+ features: postgres-storage
+ - name: postgres-webhook
+ features: postgres-storage,webhook-sink
+ - name: mongodb
+ features: mongodb-storage
+ - name: mongodb-webhook
+ features: mongodb-storage,webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Build image
+ run: docker build --build-arg PARSEON_FEATURES='${{ matrix.features }}' --tag parseon:ci .
+ - name: Generate SBOM when Docker SBOM support is installed
+ shell: bash
+ run: |
+ if docker sbom --help >/dev/null 2>&1; then
+ docker sbom parseon:ci > "sbom-${{ matrix.name }}.spdx.json"
+ else
+ echo 'docker sbom is unavailable on this runner; image SBOM is delegated to the registry scanner.'
+ fi
+ - name: Scan image when Docker Scout support is installed
+ shell: bash
+ run: |
+ if docker scout version >/dev/null 2>&1; then
+ docker scout cves --only-fixed parseon:ci
+ else
+ echo 'docker scout is unavailable on this runner; image scanning is delegated to the registry.'
+ fi
+
+ release-gates:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Validate production Compose
+ shell: bash
+ run: |
+ export PARSEON_IMAGE=registry.example/parseon@sha256:$(printf 'a%.0s' {1..64})
+ export STORAGE_URL='postgres://postgres:5432/parseon'
+ export POSTGRES_PASSWORD=test
+ export API_TOKEN=test-token
+ docker compose -f compose.production.yml config >/dev/null
+ if [[ ! "$PARSEON_IMAGE" =~ @sha256:[0-9a-fA-F]{64}$ ]]; then
+ echo 'PARSEON_IMAGE must be digest-pinned' >&2
+ exit 1
+ fi
+ - name: Validate Helm chart and immutable deployment policy
+ shell: bash
+ run: |
+ digest="sha256:$(printf 'a%.0s' {1..64})"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 lint deploy/helm/parseon --set image.digest="$digest"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" >/dev/null
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" --set replicaCount=2 >/dev/null 2>&1; then
+ echo 'replicaCount=2 was accepted' >&2
+ exit 1
+ fi
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon >/dev/null 2>&1; then
+ echo 'missing image digest was accepted' >&2
+ exit 1
+ fi
+ - name: Validate scripts and monitoring artifacts
+ shell: bash
+ run: |
+ bash -n scripts/backup_postgres.sh scripts/restore_postgres.sh
+ python3 -m py_compile scripts/gen_erpc.py
+ python3 -m json.tool deploy/monitoring/parseon-dashboard.json >/dev/null
+ secrets:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ fetch-depth: 0
+ - name: Reject credential-bearing generated config
+ shell: bash
+ run: |
+ if git grep -n -I -i -E '://[^[:space:]/:@]+:[^[:space:]@]+@|(^|[?&])(api[_-]?key|access[_-]?token|token|secret|password)=[^[:space:]&]{8,}' -- ':!CHANGELOG.md' ':!docs/operations.md' ':!.env.example'; then
+ echo 'credential-bearing URL or query parameter found in tracked source' >&2
+ exit 1
+ fi
+ echo 'Historical credentials still require independent revoke/rotate evidence.'

.gitignore

@@ -1,2 +1,3 @@
 /target
 /.env
+/.temp

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Added
 
+- Add canonical block metadata, provisional/finalized lifecycle, bounded reorg rollback, and finalized promotion for both storage adapters.
+- Add production Compose and Helm deployment artifacts, backup/restore operations runbook, Prometheus alerts, Grafana dashboard, and CI release gates.
 - Apply chain creation, enable/disable, and deletion to running workers without restarting Parseon; deletions stop the worker before removing its data.
 - Rotate a chain's RPC endpoint URL in place on the running worker via Alloy's `Http::set_url`, resetting endpoint capability probes while keeping the cached chain ID; sources that cannot rotate restart their worker instead.
 - Allow multiple monitors to target the same chain, contract, and function selector or event topic while retaining independent ranges, filters, cursors, and result storage.
@@ -15,6 +17,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Changed
 
+- Require a bearer API token for protected HTTP routes, disable CORS by default, bound request bodies, add liveness/readiness probes, and reject unsafe RPC destinations by default.
+- Treat credential-bearing eRPC URLs as operator-injected configuration instead of generated repository content.
 - Pin the Compose eRPC image to the `0.1.1` release tag, set a 3 GiB container memory limit with `GOMEMLIMIT=2700MiB`, add `restart: unless-stopped`, and invoke `/erpc-server` explicitly so the distroless image starts correctly.
 - Reuse matching RPC data and compatible ABI decoders across overlapping monitor targets before applying each monitor's filter and persisting its own results.
 - Isolate ABI decode failures to the affected monitor layout so an incompatible definition cannot stall other monitors on the chain.
@@ -32,6 +36,8 @@ All notable changes to Parseon are documented in this file.
 ### Fixed
 
 - Keep persisted chain state and live workers ordered during concurrent mutations and startup reconciliation, and reject new worker starts once supervisor shutdown begins.
+- Reject mixed-branch result identities, fail closed when a retained reorg ancestor is unavailable, preserve finalized state for monitors added over existing blocks, and reset rollback cursors below a monitor's start block.
+- Pin validated RPC DNS addresses in the HTTP transport, verify generated endpoint chain IDs, expose worker freshness/state metrics, and require encrypted checksum-verified PostgreSQL backup artifacts.
 
 ### Breaking
 

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 resolver = "3"
 
 [workspace.package]
-version = "0.8.0"
+version = "1.0.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # ---- chef base: shared Rust toolchain + cargo-chef ----
-FROM rust:1.96-alpine AS chef
+FROM rust:1.96-alpine@sha256:a41f7740f8b45d45795624eec13a8b42263cc700f19f7e4e86e04d3dda08a479 AS chef
 RUN apk add --no-cache musl-dev
 RUN cargo install cargo-chef --locked
 WORKDIR /app
@@ -18,7 +18,7 @@ ARG PARSEON_FEATURES=postgres-storage
 ENV PARSEON_FEATURES=${PARSEON_FEATURES}
 RUN apk add --no-cache watchexec
 COPY --from=planner /app/recipe.json recipe.json
-RUN cargo chef cook --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+RUN cargo chef cook --locked --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 EXPOSE 8080
 CMD ["sh", "-c", "exec watchexec --restart --stop-signal SIGINT --exts rs,toml,lock,sql -- cargo run --no-default-features --features \"${PARSEON_FEATURES}\""]
@@ -29,15 +29,15 @@ ARG PARSEON_FEATURES=postgres-storage
 COPY --from=planner /app/recipe.json recipe.json
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo chef cook --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+ cargo chef cook --locked --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo build --release --no-default-features --features "${PARSEON_FEATURES}" && \
+ cargo build --release --locked --no-default-features --features "${PARSEON_FEATURES}" && \
  cp /app/target/release/parseon /usr/local/bin/parseon
 
 # ---- runtime: minimal alpine, non-root, healthcheck ----
-FROM alpine:3.20 AS runtime
+FROM alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc AS runtime
 RUN apk add --no-cache ca-certificates wget && \
  adduser -D -u 1000 parseon
 COPY --from=builder /usr/local/bin/parseon /usr/local/bin/parseon

README.md

@@ -40,10 +40,14 @@ parseon-server
 └── parseon-webhook-sink ────> parseon-core
 ```
 
-Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL`, then register direct RPC or complete eRPC URLs through `POST /chains`.
+Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL` and set a non-empty `API_TOKEN`; protected API routes require `Authorization: Bearer <API_TOKEN>`. Register direct RPC or complete eRPC URLs through `POST /chains`. Private/loopback RPC destinations are rejected unless `ALLOW_PRIVATE_RPC_NETWORKS=true` is explicitly enabled for local development.
 
 See [adapter configuration and guarantees](./docs/adapters.md) for feature builds, MongoDB requirements, eRPC smoke checks, the webhook JSON contract, and Compose profiles.
 
+## Production deployment
+
+Use [`compose.production.yml`](./compose.production.yml) or the [`deploy/helm/parseon`](./deploy/helm/parseon) chart. Both require an externally managed `API_TOKEN` and storage URL, keep databases private, and expose liveness/readiness probes. Read the [production operations runbook](./docs/operations.md) before upgrading, restoring, or exposing the API through an ingress.
+
 ## License
 
 Licensed under either the [Apache License, Version 2.0](./LICENSE-APACHE) or the [MIT license](./LICENSE-MIT), at your option.

compose.production.yml

@@ -0,0 +1,70 @@
+services:
+ postgres:
+ image: ${POSTGRES_IMAGE:-postgres:16@sha256:f1c3376c26f2609ab9f29f71f824103fe2fcd8ee0346485cb6122a4f93df6f94}
+ restart: unless-stopped
+ environment:
+ POSTGRES_USER: ${POSTGRES_USER:-parseon}
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+ POSTGRES_DB: ${POSTGRES_DB:-parseon}
+ volumes:
+ - pgdata:/var/lib/postgresql/data
+ networks:
+ - backend
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ # No host port: PostgreSQL is reachable only by Parseon on the backend network.
+
+ parseon:
+ image: ${PARSEON_IMAGE:?set PARSEON_IMAGE to an immutable Parseon image}
+ restart: unless-stopped
+ depends_on:
+ postgres:
+ condition: service_healthy
+ environment:
+ STORAGE_URL: ${STORAGE_URL:?set STORAGE_URL}
+ API_TOKEN: ${API_TOKEN:?set API_TOKEN}
+ HTTP_LISTEN: 0.0.0.0:8080
+ RUST_LOG: ${RUST_LOG:-info}
+ POLL_INTERVAL_MS: ${POLL_INTERVAL_MS:-2000}
+ DEFAULT_BATCH_SIZE: ${DEFAULT_BATCH_SIZE:-10}
+ BLOCK_CACHE_SIZE: ${BLOCK_CACHE_SIZE:-512}
+ BLOCK_CONCURRENCY: ${BLOCK_CONCURRENCY:-4}
+ RPC_REQUEST_CONCURRENCY: ${RPC_REQUEST_CONCURRENCY:-16}
+ STORAGE_WRITE_CONCURRENCY: ${STORAGE_WRITE_CONCURRENCY:-4}
+ CONFIRMATION_DEPTH: ${CONFIRMATION_DEPTH:-64}
+ ROLLBACK_RETENTION: ${ROLLBACK_RETENTION:-256}
+ RPC_BATCH_SIZE: ${RPC_BATCH_SIZE:-20}
+ ALLOW_PRIVATE_RPC_NETWORKS: "false"
+ CORS_ORIGINS: ${CORS_ORIGINS:-}
+ MAX_BODY_BYTES: ${MAX_BODY_BYTES:-1048576}
+ expose:
+ - "8080"
+ networks:
+ - backend
+ - egress
+ read_only: true
+ tmpfs:
+ - /tmp
+ cap_drop:
+ - ALL
+ security_opt:
+ - no-new-privileges:true
+ mem_limit: ${PARSEON_MEMORY_LIMIT:-768m}
+ cpus: ${PARSEON_CPUS:-2}
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ interval: 10s
+ timeout: 5s
+ start_period: 20s
+ retries: 6
+
+volumes:
+ pgdata:
+
+networks:
+ backend:
+ internal: true
+ egress:

.dockerignore

@@ -5,6 +5,7 @@ target/
 .env
 .env.example
 .dockerignore
+.temp/
 Dockerfile
 docker-compose.yml
 erpc.yaml

.env.example

@@ -1,17 +1,26 @@
+# Required bearer token for admin/data API routes.
+API_TOKEN=replace-with-a-long-random-token
 # Default `postgres-storage` build. A `mongodb-storage` build can instead use
 # mongodb://localhost:27017/?replicaSet=rs0 and STORAGE_DATABASE=parseon.
 STORAGE_URL=postgres://postgres:postgres@localhost:5432/parseon
 # STORAGE_DATABASE=parseon
 HTTP_LISTEN=0.0.0.0:8080
 RUST_LOG=info,parseon=debug
+# Comma-separated browser origins; empty keeps CORS disabled.
+CORS_ORIGINS=
+MAX_BODY_BYTES=1048576
 POLL_INTERVAL_MS=2000
 DEFAULT_BATCH_SIZE=10
 # Set to 0 to disable Parseon's in-memory block cache.
 BLOCK_CACHE_SIZE=512
 BLOCK_CONCURRENCY=4
 RPC_REQUEST_CONCURRENCY=16
 STORAGE_WRITE_CONCURRENCY=4
+CONFIRMATION_DEPTH=64
+ROLLBACK_RETENTION=256
 RPC_BATCH_SIZE=20
+# Only enable for local RPC containers; keep false in production.
+ALLOW_PRIVATE_RPC_NETWORKS=false
 # Required only when built with `webhook-sink`.
 # WEBHOOK_URL=http://localhost:9000/parseon
 # WEBHOOK_CONCURRENCY=16

.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ fmt:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add rustfmt --toolchain 1.96.0
+ - run: cargo +1.96.0 fmt --all -- --check
+
+ rust:
+ runs-on: ubuntu-24.04
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: postgres
+ features: parseon-server/postgres-storage
+ - name: postgres-webhook
+ features: parseon-server/postgres-storage,parseon-server/webhook-sink
+ - name: mongodb
+ features: parseon-server/mongodb-storage
+ - name: mongodb-webhook
+ features: parseon-server/mongodb-storage,parseon-server/webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add clippy --toolchain 1.96.0
+ - run: cargo +1.96.0 clippy -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short -- -D warnings
+ - run: cargo +1.96.0 test -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short
+ - run: cargo +1.96.0 build -q -p parseon-server --release --locked --no-default-features --features "${{ matrix.features }}"
+
+ docker:
+ runs-on: ubuntu-24.04
+ strategy:
+ matrix:
+ include:
+ - name: postgres
+ features: postgres-storage
+ - name: postgres-webhook
+ features: postgres-storage,webhook-sink
+ - name: mongodb
+ features: mongodb-storage
+ - name: mongodb-webhook
+ features: mongodb-storage,webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Build image
+ run: docker build --build-arg PARSEON_FEATURES='${{ matrix.features }}' --tag parseon:ci .
+ - name: Generate SBOM when Docker SBOM support is installed
+ shell: bash
+ run: |
+ if docker sbom --help >/dev/null 2>&1; then
+ docker sbom parseon:ci > "sbom-${{ matrix.name }}.spdx.json"
+ else
+ echo 'docker sbom is unavailable on this runner; image SBOM is delegated to the registry scanner.'
+ fi
+ - name: Scan image when Docker Scout support is installed
+ shell: bash
+ run: |
+ if docker scout version >/dev/null 2>&1; then
+ docker scout cves --only-fixed parseon:ci
+ else
+ echo 'docker scout is unavailable on this runner; image scanning is delegated to the registry.'
+ fi
+
+ release-gates:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Validate production Compose
+ shell: bash
+ run: |
+ export PARSEON_IMAGE=registry.example/parseon@sha256:$(printf 'a%.0s' {1..64})
+ export STORAGE_URL='postgres://postgres:5432/parseon'
+ export POSTGRES_PASSWORD=test
+ export API_TOKEN=test-token
+ docker compose -f compose.production.yml config >/dev/null
+ if [[ ! "$PARSEON_IMAGE" =~ @sha256:[0-9a-fA-F]{64}$ ]]; then
+ echo 'PARSEON_IMAGE must be digest-pinned' >&2
+ exit 1
+ fi
+ - name: Validate Helm chart and immutable deployment policy
+ shell: bash
+ run: |
+ digest="sha256:$(printf 'a%.0s' {1..64})"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 lint deploy/helm/parseon --set image.digest="$digest"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" >/dev/null
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" --set replicaCount=2 >/dev/null 2>&1; then
+ echo 'replicaCount=2 was accepted' >&2
+ exit 1
+ fi
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon >/dev/null 2>&1; then
+ echo 'missing image digest was accepted' >&2
+ exit 1
+ fi
+ - name: Validate scripts and monitoring artifacts
+ shell: bash
+ run: |
+ bash -n scripts/backup_postgres.sh scripts/restore_postgres.sh
+ python3 -m py_compile scripts/gen_erpc.py
+ python3 -m json.tool deploy/monitoring/parseon-dashboard.json >/dev/null
+ secrets:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ fetch-depth: 0
+ - name: Reject credential-bearing generated config
+ shell: bash
+ run: |
+ if git grep -n -I -i -E '://[^[:space:]/:@]+:[^[:space:]@]+@|(^|[?&])(api[_-]?key|access[_-]?token|token|secret|password)=[^[:space:]&]{8,}' -- ':!CHANGELOG.md' ':!docs/operations.md' ':!.env.example'; then
+ echo 'credential-bearing URL or query parameter found in tracked source' >&2
+ exit 1
+ fi
+ echo 'Historical credentials still require independent revoke/rotate evidence.'

.gitignore

@@ -1,2 +1,3 @@
 /target
 /.env
+/.temp

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Added
 
+- Add canonical block metadata, provisional/finalized lifecycle, bounded reorg rollback, and finalized promotion for both storage adapters.
+- Add production Compose and Helm deployment artifacts, backup/restore operations runbook, Prometheus alerts, Grafana dashboard, and CI release gates.
 - Apply chain creation, enable/disable, and deletion to running workers without restarting Parseon; deletions stop the worker before removing its data.
 - Rotate a chain's RPC endpoint URL in place on the running worker via Alloy's `Http::set_url`, resetting endpoint capability probes while keeping the cached chain ID; sources that cannot rotate restart their worker instead.
 - Allow multiple monitors to target the same chain, contract, and function selector or event topic while retaining independent ranges, filters, cursors, and result storage.
@@ -15,6 +17,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Changed
 
+- Require a bearer API token for protected HTTP routes, disable CORS by default, bound request bodies, add liveness/readiness probes, and reject unsafe RPC destinations by default.
+- Treat credential-bearing eRPC URLs as operator-injected configuration instead of generated repository content.
 - Pin the Compose eRPC image to the `0.1.1` release tag, set a 3 GiB container memory limit with `GOMEMLIMIT=2700MiB`, add `restart: unless-stopped`, and invoke `/erpc-server` explicitly so the distroless image starts correctly.
 - Reuse matching RPC data and compatible ABI decoders across overlapping monitor targets before applying each monitor's filter and persisting its own results.
 - Isolate ABI decode failures to the affected monitor layout so an incompatible definition cannot stall other monitors on the chain.
@@ -32,6 +36,8 @@ All notable changes to Parseon are documented in this file.
 ### Fixed
 
 - Keep persisted chain state and live workers ordered during concurrent mutations and startup reconciliation, and reject new worker starts once supervisor shutdown begins.
+- Reject mixed-branch result identities, fail closed when a retained reorg ancestor is unavailable, preserve finalized state for monitors added over existing blocks, and reset rollback cursors below a monitor's start block.
+- Pin validated RPC DNS addresses in the HTTP transport, verify generated endpoint chain IDs, expose worker freshness/state metrics, and require encrypted checksum-verified PostgreSQL backup artifacts.
 
 ### Breaking
 

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 resolver = "3"
 
 [workspace.package]
-version = "0.8.0"
+version = "1.0.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # ---- chef base: shared Rust toolchain + cargo-chef ----
-FROM rust:1.96-alpine AS chef
+FROM rust:1.96-alpine@sha256:a41f7740f8b45d45795624eec13a8b42263cc700f19f7e4e86e04d3dda08a479 AS chef
 RUN apk add --no-cache musl-dev
 RUN cargo install cargo-chef --locked
 WORKDIR /app
@@ -18,7 +18,7 @@ ARG PARSEON_FEATURES=postgres-storage
 ENV PARSEON_FEATURES=${PARSEON_FEATURES}
 RUN apk add --no-cache watchexec
 COPY --from=planner /app/recipe.json recipe.json
-RUN cargo chef cook --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+RUN cargo chef cook --locked --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 EXPOSE 8080
 CMD ["sh", "-c", "exec watchexec --restart --stop-signal SIGINT --exts rs,toml,lock,sql -- cargo run --no-default-features --features \"${PARSEON_FEATURES}\""]
@@ -29,15 +29,15 @@ ARG PARSEON_FEATURES=postgres-storage
 COPY --from=planner /app/recipe.json recipe.json
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo chef cook --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+ cargo chef cook --locked --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo build --release --no-default-features --features "${PARSEON_FEATURES}" && \
+ cargo build --release --locked --no-default-features --features "${PARSEON_FEATURES}" && \
  cp /app/target/release/parseon /usr/local/bin/parseon
 
 # ---- runtime: minimal alpine, non-root, healthcheck ----
-FROM alpine:3.20 AS runtime
+FROM alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc AS runtime
 RUN apk add --no-cache ca-certificates wget && \
  adduser -D -u 1000 parseon
 COPY --from=builder /usr/local/bin/parseon /usr/local/bin/parseon

README.md

@@ -40,10 +40,14 @@ parseon-server
 └── parseon-webhook-sink ────> parseon-core
 ```
 
-Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL`, then register direct RPC or complete eRPC URLs through `POST /chains`.
+Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL` and set a non-empty `API_TOKEN`; protected API routes require `Authorization: Bearer <API_TOKEN>`. Register direct RPC or complete eRPC URLs through `POST /chains`. Private/loopback RPC destinations are rejected unless `ALLOW_PRIVATE_RPC_NETWORKS=true` is explicitly enabled for local development.
 
 See [adapter configuration and guarantees](./docs/adapters.md) for feature builds, MongoDB requirements, eRPC smoke checks, the webhook JSON contract, and Compose profiles.
 
+## Production deployment
+
+Use [`compose.production.yml`](./compose.production.yml) or the [`deploy/helm/parseon`](./deploy/helm/parseon) chart. Both require an externally managed `API_TOKEN` and storage URL, keep databases private, and expose liveness/readiness probes. Read the [production operations runbook](./docs/operations.md) before upgrading, restoring, or exposing the API through an ingress.
+
 ## License
 
 Licensed under either the [Apache License, Version 2.0](./LICENSE-APACHE) or the [MIT license](./LICENSE-MIT), at your option.

compose.production.yml

@@ -0,0 +1,70 @@
+services:
+ postgres:
+ image: ${POSTGRES_IMAGE:-postgres:16@sha256:f1c3376c26f2609ab9f29f71f824103fe2fcd8ee0346485cb6122a4f93df6f94}
+ restart: unless-stopped
+ environment:
+ POSTGRES_USER: ${POSTGRES_USER:-parseon}
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+ POSTGRES_DB: ${POSTGRES_DB:-parseon}
+ volumes:
+ - pgdata:/var/lib/postgresql/data
+ networks:
+ - backend
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ # No host port: PostgreSQL is reachable only by Parseon on the backend network.
+
+ parseon:
+ image: ${PARSEON_IMAGE:?set PARSEON_IMAGE to an immutable Parseon image}
+ restart: unless-stopped
+ depends_on:
+ postgres:
+ condition: service_healthy
+ environment:
+ STORAGE_URL: ${STORAGE_URL:?set STORAGE_URL}
+ API_TOKEN: ${API_TOKEN:?set API_TOKEN}
+ HTTP_LISTEN: 0.0.0.0:8080
+ RUST_LOG: ${RUST_LOG:-info}
+ POLL_INTERVAL_MS: ${POLL_INTERVAL_MS:-2000}
+ DEFAULT_BATCH_SIZE: ${DEFAULT_BATCH_SIZE:-10}
+ BLOCK_CACHE_SIZE: ${BLOCK_CACHE_SIZE:-512}
+ BLOCK_CONCURRENCY: ${BLOCK_CONCURRENCY:-4}
+ RPC_REQUEST_CONCURRENCY: ${RPC_REQUEST_CONCURRENCY:-16}
+ STORAGE_WRITE_CONCURRENCY: ${STORAGE_WRITE_CONCURRENCY:-4}
+ CONFIRMATION_DEPTH: ${CONFIRMATION_DEPTH:-64}
+ ROLLBACK_RETENTION: ${ROLLBACK_RETENTION:-256}
+ RPC_BATCH_SIZE: ${RPC_BATCH_SIZE:-20}
+ ALLOW_PRIVATE_RPC_NETWORKS: "false"
+ CORS_ORIGINS: ${CORS_ORIGINS:-}
+ MAX_BODY_BYTES: ${MAX_BODY_BYTES:-1048576}
+ expose:
+ - "8080"
+ networks:
+ - backend
+ - egress
+ read_only: true
+ tmpfs:
+ - /tmp
+ cap_drop:
+ - ALL
+ security_opt:
+ - no-new-privileges:true
+ mem_limit: ${PARSEON_MEMORY_LIMIT:-768m}
+ cpus: ${PARSEON_CPUS:-2}
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ interval: 10s
+ timeout: 5s
+ start_period: 20s
+ retries: 6
+
+volumes:
+ pgdata:
+
+networks:
+ backend:
+ internal: true
+ egress:

.dockerignore

@@ -5,6 +5,7 @@ target/
 .env
 .env.example
 .dockerignore
+.temp/
 Dockerfile
 docker-compose.yml
 erpc.yaml

.env.example

@@ -1,17 +1,26 @@
+# Required bearer token for admin/data API routes.
+API_TOKEN=replace-with-a-long-random-token
 # Default `postgres-storage` build. A `mongodb-storage` build can instead use
 # mongodb://localhost:27017/?replicaSet=rs0 and STORAGE_DATABASE=parseon.
 STORAGE_URL=postgres://postgres:postgres@localhost:5432/parseon
 # STORAGE_DATABASE=parseon
 HTTP_LISTEN=0.0.0.0:8080
 RUST_LOG=info,parseon=debug
+# Comma-separated browser origins; empty keeps CORS disabled.
+CORS_ORIGINS=
+MAX_BODY_BYTES=1048576
 POLL_INTERVAL_MS=2000
 DEFAULT_BATCH_SIZE=10
 # Set to 0 to disable Parseon's in-memory block cache.
 BLOCK_CACHE_SIZE=512
 BLOCK_CONCURRENCY=4
 RPC_REQUEST_CONCURRENCY=16
 STORAGE_WRITE_CONCURRENCY=4
+CONFIRMATION_DEPTH=64
+ROLLBACK_RETENTION=256
 RPC_BATCH_SIZE=20
+# Only enable for local RPC containers; keep false in production.
+ALLOW_PRIVATE_RPC_NETWORKS=false
 # Required only when built with `webhook-sink`.
 # WEBHOOK_URL=http://localhost:9000/parseon
 # WEBHOOK_CONCURRENCY=16

.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ fmt:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add rustfmt --toolchain 1.96.0
+ - run: cargo +1.96.0 fmt --all -- --check
+
+ rust:
+ runs-on: ubuntu-24.04
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: postgres
+ features: parseon-server/postgres-storage
+ - name: postgres-webhook
+ features: parseon-server/postgres-storage,parseon-server/webhook-sink
+ - name: mongodb
+ features: parseon-server/mongodb-storage
+ - name: mongodb-webhook
+ features: parseon-server/mongodb-storage,parseon-server/webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Install Rust toolchain
+ run: rustup toolchain install 1.96.0 --profile minimal && rustup component add clippy --toolchain 1.96.0
+ - run: cargo +1.96.0 clippy -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short -- -D warnings
+ - run: cargo +1.96.0 test -q --workspace --all-targets --locked --no-default-features --features "${{ matrix.features }}" --message-format=short
+ - run: cargo +1.96.0 build -q -p parseon-server --release --locked --no-default-features --features "${{ matrix.features }}"
+
+ docker:
+ runs-on: ubuntu-24.04
+ strategy:
+ matrix:
+ include:
+ - name: postgres
+ features: postgres-storage
+ - name: postgres-webhook
+ features: postgres-storage,webhook-sink
+ - name: mongodb
+ features: mongodb-storage
+ - name: mongodb-webhook
+ features: mongodb-storage,webhook-sink
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Build image
+ run: docker build --build-arg PARSEON_FEATURES='${{ matrix.features }}' --tag parseon:ci .
+ - name: Generate SBOM when Docker SBOM support is installed
+ shell: bash
+ run: |
+ if docker sbom --help >/dev/null 2>&1; then
+ docker sbom parseon:ci > "sbom-${{ matrix.name }}.spdx.json"
+ else
+ echo 'docker sbom is unavailable on this runner; image SBOM is delegated to the registry scanner.'
+ fi
+ - name: Scan image when Docker Scout support is installed
+ shell: bash
+ run: |
+ if docker scout version >/dev/null 2>&1; then
+ docker scout cves --only-fixed parseon:ci
+ else
+ echo 'docker scout is unavailable on this runner; image scanning is delegated to the registry.'
+ fi
+
+ release-gates:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ - name: Validate production Compose
+ shell: bash
+ run: |
+ export PARSEON_IMAGE=registry.example/parseon@sha256:$(printf 'a%.0s' {1..64})
+ export STORAGE_URL='postgres://postgres:5432/parseon'
+ export POSTGRES_PASSWORD=test
+ export API_TOKEN=test-token
+ docker compose -f compose.production.yml config >/dev/null
+ if [[ ! "$PARSEON_IMAGE" =~ @sha256:[0-9a-fA-F]{64}$ ]]; then
+ echo 'PARSEON_IMAGE must be digest-pinned' >&2
+ exit 1
+ fi
+ - name: Validate Helm chart and immutable deployment policy
+ shell: bash
+ run: |
+ digest="sha256:$(printf 'a%.0s' {1..64})"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 lint deploy/helm/parseon --set image.digest="$digest"
+ docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" >/dev/null
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon --set image.digest="$digest" --set replicaCount=2 >/dev/null 2>&1; then
+ echo 'replicaCount=2 was accepted' >&2
+ exit 1
+ fi
+ if docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work alpine/helm:3.17@sha256:d899e6316789fec04ee95300a18e454b7942539cbb3d89bde3e0655d6ca2e895 template parseon deploy/helm/parseon >/dev/null 2>&1; then
+ echo 'missing image digest was accepted' >&2
+ exit 1
+ fi
+ - name: Validate scripts and monitoring artifacts
+ shell: bash
+ run: |
+ bash -n scripts/backup_postgres.sh scripts/restore_postgres.sh
+ python3 -m py_compile scripts/gen_erpc.py
+ python3 -m json.tool deploy/monitoring/parseon-dashboard.json >/dev/null
+ secrets:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ fetch-depth: 0
+ - name: Reject credential-bearing generated config
+ shell: bash
+ run: |
+ if git grep -n -I -i -E '://[^[:space:]/:@]+:[^[:space:]@]+@|(^|[?&])(api[_-]?key|access[_-]?token|token|secret|password)=[^[:space:]&]{8,}' -- ':!CHANGELOG.md' ':!docs/operations.md' ':!.env.example'; then
+ echo 'credential-bearing URL or query parameter found in tracked source' >&2
+ exit 1
+ fi
+ echo 'Historical credentials still require independent revoke/rotate evidence.'

.gitignore

@@ -1,2 +1,3 @@
 /target
 /.env
+/.temp

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Added
 
+- Add canonical block metadata, provisional/finalized lifecycle, bounded reorg rollback, and finalized promotion for both storage adapters.
+- Add production Compose and Helm deployment artifacts, backup/restore operations runbook, Prometheus alerts, Grafana dashboard, and CI release gates.
 - Apply chain creation, enable/disable, and deletion to running workers without restarting Parseon; deletions stop the worker before removing its data.
 - Rotate a chain's RPC endpoint URL in place on the running worker via Alloy's `Http::set_url`, resetting endpoint capability probes while keeping the cached chain ID; sources that cannot rotate restart their worker instead.
 - Allow multiple monitors to target the same chain, contract, and function selector or event topic while retaining independent ranges, filters, cursors, and result storage.
@@ -15,6 +17,8 @@ All notable changes to Parseon are documented in this file.
 
 ### Changed
 
+- Require a bearer API token for protected HTTP routes, disable CORS by default, bound request bodies, add liveness/readiness probes, and reject unsafe RPC destinations by default.
+- Treat credential-bearing eRPC URLs as operator-injected configuration instead of generated repository content.
 - Pin the Compose eRPC image to the `0.1.1` release tag, set a 3 GiB container memory limit with `GOMEMLIMIT=2700MiB`, add `restart: unless-stopped`, and invoke `/erpc-server` explicitly so the distroless image starts correctly.
 - Reuse matching RPC data and compatible ABI decoders across overlapping monitor targets before applying each monitor's filter and persisting its own results.
 - Isolate ABI decode failures to the affected monitor layout so an incompatible definition cannot stall other monitors on the chain.
@@ -32,6 +36,8 @@ All notable changes to Parseon are documented in this file.
 ### Fixed
 
 - Keep persisted chain state and live workers ordered during concurrent mutations and startup reconciliation, and reject new worker starts once supervisor shutdown begins.
+- Reject mixed-branch result identities, fail closed when a retained reorg ancestor is unavailable, preserve finalized state for monitors added over existing blocks, and reset rollback cursors below a monitor's start block.
+- Pin validated RPC DNS addresses in the HTTP transport, verify generated endpoint chain IDs, expose worker freshness/state metrics, and require encrypted checksum-verified PostgreSQL backup artifacts.
 
 ### Breaking
 

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 resolver = "3"
 
 [workspace.package]
-version = "0.8.0"
+version = "1.0.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # ---- chef base: shared Rust toolchain + cargo-chef ----
-FROM rust:1.96-alpine AS chef
+FROM rust:1.96-alpine@sha256:a41f7740f8b45d45795624eec13a8b42263cc700f19f7e4e86e04d3dda08a479 AS chef
 RUN apk add --no-cache musl-dev
 RUN cargo install cargo-chef --locked
 WORKDIR /app
@@ -18,7 +18,7 @@ ARG PARSEON_FEATURES=postgres-storage
 ENV PARSEON_FEATURES=${PARSEON_FEATURES}
 RUN apk add --no-cache watchexec
 COPY --from=planner /app/recipe.json recipe.json
-RUN cargo chef cook --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+RUN cargo chef cook --locked --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 EXPOSE 8080
 CMD ["sh", "-c", "exec watchexec --restart --stop-signal SIGINT --exts rs,toml,lock,sql -- cargo run --no-default-features --features \"${PARSEON_FEATURES}\""]
@@ -29,15 +29,15 @@ ARG PARSEON_FEATURES=postgres-storage
 COPY --from=planner /app/recipe.json recipe.json
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo chef cook --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
+ cargo chef cook --locked --release --recipe-path recipe.json --no-default-features --features "${PARSEON_FEATURES}"
 COPY . .
 RUN --mount=type=cache,target=/root/.cargo/registry \
  --mount=type=cache,target=/app/target \
- cargo build --release --no-default-features --features "${PARSEON_FEATURES}" && \
+ cargo build --release --locked --no-default-features --features "${PARSEON_FEATURES}" && \
  cp /app/target/release/parseon /usr/local/bin/parseon
 
 # ---- runtime: minimal alpine, non-root, healthcheck ----
-FROM alpine:3.20 AS runtime
+FROM alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc AS runtime
 RUN apk add --no-cache ca-certificates wget && \
  adduser -D -u 1000 parseon
 COPY --from=builder /usr/local/bin/parseon /usr/local/bin/parseon

README.md

@@ -40,10 +40,14 @@ parseon-server
 └── parseon-webhook-sink ────> parseon-core
 ```
 
-Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL`, then register direct RPC or complete eRPC URLs through `POST /chains`.
+Start PostgreSQL with `docker compose up -d`, or start the MongoDB development replica set and eRPC gateway with `docker compose --profile mongodb --profile erpc up -d`. Configure the selected backend through `STORAGE_URL` and set a non-empty `API_TOKEN`; protected API routes require `Authorization: Bearer <API_TOKEN>`. Register direct RPC or complete eRPC URLs through `POST /chains`. Private/loopback RPC destinations are rejected unless `ALLOW_PRIVATE_RPC_NETWORKS=true` is explicitly enabled for local development.
 
 See [adapter configuration and guarantees](./docs/adapters.md) for feature builds, MongoDB requirements, eRPC smoke checks, the webhook JSON contract, and Compose profiles.
 
+## Production deployment
+
+Use [`compose.production.yml`](./compose.production.yml) or the [`deploy/helm/parseon`](./deploy/helm/parseon) chart. Both require an externally managed `API_TOKEN` and storage URL, keep databases private, and expose liveness/readiness probes. Read the [production operations runbook](./docs/operations.md) before upgrading, restoring, or exposing the API through an ingress.
+
 ## License
 
 Licensed under either the [Apache License, Version 2.0](./LICENSE-APACHE) or the [MIT license](./LICENSE-MIT), at your option.

compose.production.yml

@@ -0,0 +1,70 @@
+services:
+ postgres:
+ image: ${POSTGRES_IMAGE:-postgres:16@sha256:f1c3376c26f2609ab9f29f71f824103fe2fcd8ee0346485cb6122a4f93df6f94}
+ restart: unless-stopped
+ environment:
+ POSTGRES_USER: ${POSTGRES_USER:-parseon}
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+ POSTGRES_DB: ${POSTGRES_DB:-parseon}
+ volumes:
+ - pgdata:/var/lib/postgresql/data
+ networks:
+ - backend
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ # No host port: PostgreSQL is reachable only by Parseon on the backend network.
+
+ parseon:
+ image: ${PARSEON_IMAGE:?set PARSEON_IMAGE to an immutable Parseon image}
+ restart: unless-stopped
+ depends_on:
+ postgres:
+ condition: service_healthy
+ environment:
+ STORAGE_URL: ${STORAGE_URL:?set STORAGE_URL}
+ API_TOKEN: ${API_TOKEN:?set API_TOKEN}
+ HTTP_LISTEN: 0.0.0.0:8080
+ RUST_LOG: ${RUST_LOG:-info}
+ POLL_INTERVAL_MS: ${POLL_INTERVAL_MS:-2000}
+ DEFAULT_BATCH_SIZE: ${DEFAULT_BATCH_SIZE:-10}
+ BLOCK_CACHE_SIZE: ${BLOCK_CACHE_SIZE:-512}
+ BLOCK_CONCURRENCY: ${BLOCK_CONCURRENCY:-4}
+ RPC_REQUEST_CONCURRENCY: ${RPC_REQUEST_CONCURRENCY:-16}
+ STORAGE_WRITE_CONCURRENCY: ${STORAGE_WRITE_CONCURRENCY:-4}
+ CONFIRMATION_DEPTH: ${CONFIRMATION_DEPTH:-64}
+ ROLLBACK_RETENTION: ${ROLLBACK_RETENTION:-256}
+ RPC_BATCH_SIZE: ${RPC_BATCH_SIZE:-20}
+ ALLOW_PRIVATE_RPC_NETWORKS: "false"
+ CORS_ORIGINS: ${CORS_ORIGINS:-}
+ MAX_BODY_BYTES: ${MAX_BODY_BYTES:-1048576}
+ expose:
+ - "8080"
+ networks:
+ - backend
+ - egress
+ read_only: true
+ tmpfs:
+ - /tmp
+ cap_drop:
+ - ALL
+ security_opt:
+ - no-new-privileges:true
+ mem_limit: ${PARSEON_MEMORY_LIMIT:-768m}
+ cpus: ${PARSEON_CPUS:-2}
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ interval: 10s
+ timeout: 5s
+ start_period: 20s
+ retries: 6
+
+volumes:
+ pgdata:
+
+networks:
+ backend:
+ internal: true
+ egress: