fix: restrict /metrics auth, harden exception filter, add issue templ…

.env.example

@@ -218,9 +218,10 @@ LOG_SERVICE_NAME=vortex-backend
 # Sentry DSN for error reporting. Leave blank to disable Sentry entirely.
 SENTRY_DSN=
 
-# Bearer token for GET /metrics (issue #298).
-# Empty = unauthenticated in dev/test; production always requires a value.
+# ─── Metrics access control (issue #298) ─────────────────────────────────────
+# Bearer token required for GET /metrics. Empty = endpoint disabled (403).
 # Generate with: openssl rand -hex 32
+# Required and validated (min 16 chars) in production.
 METRICS_TOKEN=
 
 # Optional log shipping to a central collector. Off by default so local dev and

.env.testnet.example

@@ -0,0 +1,122 @@
+# .env.testnet.example
+#
+# Environment template for LOCAL DEVELOPMENT against Stellar TESTNET.
+# Copy to .env and fill in any values marked with <CHANGE_ME>.
+#
+#   cp .env.testnet.example .env
+#
+# Testnet is safe to experiment with — tokens have no real value and contract
+# deployments are free via Friendbot.  Never reuse testnet keys on mainnet.
+#
+# Closes #136
+
+# ─── Database ────────────────────────────────────────────────────────────────
+# Local Docker Compose default.  Adjust if you use a remote or managed DB.
+DATABASE_URL=postgresql://vortex:vortex@localhost:5432/vortex?schema=public
+
+# ─── Server ──────────────────────────────────────────────────────────────────
+PORT=4000
+NODE_ENV=development
+
+# ─── Stellar / Soroban ───────────────────────────────────────────────────────
+STELLAR_NETWORK=testnet
+SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
+
+# Testnet contract IDs — leave blank until you have deployed contracts.
+# The service boots without them; on-chain write paths are no-ops when empty.
+SETTLEMENT_CONTRACT_ID=
+SOLVER_REGISTRY_CONTRACT_ID=
+
+# Testnet signing key — generate a throwaway keypair, fund it with Friendbot,
+# and paste the secret seed here.  Never reuse this key on mainnet.
+#
+#   # Generate a new key:
+#   npx @stellar/stellar-cli keys generate local-dev --network testnet
+#   npx @stellar/stellar-cli keys show local-dev
+#
+#   # Or via the SDK:
+#   node -e "console.log(require('@stellar/stellar-sdk').Keypair.random().secret())"
+#
+#   # Fund it (testnet only):
+#   curl "https://friendbot.stellar.org/?addr=<YOUR_PUBLIC_KEY>"
+#
+# Optional in development — leave blank to skip on-chain writes.
+SOROBAN_SIGNING_KEY=
+
+# Fee percentile used when estimating Soroban inclusion fees.
+# p50 is a safe default for testnet; raise to p90+ for time-sensitive mainnet txs.
+SOROBAN_FEE_PERCENTILE=p50
+
+# ─── CORS ────────────────────────────────────────────────────────────────────
+# Wildcard is fine for local development — tighten this in staging/production.
+CORS_ORIGIN=*
+
+# ─── WebSocket ───────────────────────────────────────────────────────────────
+WS_MAX_CONNECTIONS=1000
+
+# ─── Pluggable signer backend (issue #400) ───────────────────────────────────
+# SIGNER_BACKEND=local is the default for development.
+# In production use SIGNER_BACKEND=vault and supply VAULT_ADDR + VAULT_TOKEN.
+SIGNER_BACKEND=local
+VAULT_ADDR=
+VAULT_TOKEN=
+VAULT_TRANSIT_KEY_NAME=vortex-signer
+ALLOW_LOCAL_SIGNER_IN_PROD=false
+# ─── Resource-exhaustion limits (issue #476) ─────────────────────────────────
+# Maximum JSON nesting depth — rejects deeply-nested body attacks (default 10).
+JSON_MAX_DEPTH=10
+# Maximum chain values in a single WS subscribe message (default 20).
+WS_MAX_FILTER_CHAINS=20
+# Maximum active subscriptions per WS connection (default 10).
+WS_MAX_SUBSCRIPTIONS=10
+# Postgres statement_timeout for standard queries in ms (default 5000).
+DB_QUERY_TIMEOUT_MS=5000
+# Postgres statement_timeout for batch queries in ms (default 10000).
+DB_BATCH_QUERY_TIMEOUT_MS=10000
+# Postgres statement_timeout for stats queries in ms (default 15000).
+DB_STATS_QUERY_TIMEOUT_MS=15000
+
+# Emergency kill-switch (issue #477)
+# Postgres-backed so a pause survives a restart and reaches every replica.
+KILLSWITCH_OPERATOR_TOKEN=
+KILLSWITCH_REDIS_URL=
+KILLSWITCH_POLL_MS=2000
+KILLSWITCH_PERSISTENCE=prisma
+
+# ─── Observability (optional) ────────────────────────────────────────────────
+# Leave blank to disable Sentry error reporting.
+SENTRY_DSN=
+
+# ─── Metrics access control (issue #298) ─────────────────────────────────────
+# Bearer token required for GET /metrics. Empty = endpoint disabled (403).
+# Generate with: openssl rand -hex 32
+METRICS_TOKEN=
+
+# debug | info | warn | error  (defaults to "debug" in development)
+LOG_LEVEL=debug
+
+# ── Shadow-mode divergence monitor (issue #401) ─────────────────────────
+# Off by default in every environment. It runs read-only `simulateTransaction`
+# calls against SETTLEMENT_CONTRACT_ID in parallel with the off-chain intent
+# path and never signs or submits anything.
+#
+# SHADOW_SOURCE_ACCOUNT only has to be a valid Stellar public key: it is used to
+# populate the source-account field of the simulated envelope and is never
+# signed, never charged a fee and never broadcast. It must still be set, or
+# every transition reports "contract_unconfigured".
+SHADOW_MODE_ENABLED=false
+SHADOW_SAMPLE_RATE=1
+SHADOW_QUEUE_MAX=256
+SHADOW_CONCURRENCY=4
+SHADOW_SOURCE_ACCOUNT=
+# ─── Governance / Protocol Parameters ────────────────────────────────────────
+# On-chain governance parameters contract ID — leave blank to use code defaults.
+PARAMS_CONTRACT_ID=
+
+# Poll interval in ms.  30 000 is fine for testnet.
+PARAMS_POLL_INTERVAL_MS=30000
+# ─── Leader election ─────────────────────────────────────────────────────────
+# Enable for multi-replica testnet deployments.
+LEADER_ELECTION_ENABLED=false
+LEADER_ELECTION_HEARTBEAT_MS=5000
+

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,47 @@
+---
+name: Bug report
+about: Report a reproducible defect in the vortex-backend service
+title: "[Bug] "
+labels: ["bug", "needs-triage"]
+assignees: []
+---
+
+## Description
+
+<!-- A clear, concise description of what the bug is. -->
+
+## Steps to reproduce
+
+1. 
+2. 
+3. 
+
+## Expected behaviour
+
+<!-- What you expected to happen. -->
+
+## Actual behaviour
+
+<!-- What actually happened. Include error messages, stack traces, or log output. -->
+
+## Environment
+
+| Field | Value |
+|-------|-------|
+| Node version | <!-- e.g. 20.x --> |
+| `npm run build` passes? | <!-- yes / no --> |
+| `NODE_ENV` | <!-- development / production / test --> |
+| `INTENTS_PERSISTENCE` | <!-- memory / prisma --> |
+| Deployment target | <!-- local / Docker / staging / mainnet --> |
+
+## Relevant logs or screenshots
+
+<!-- Paste logs here (redact any secrets or private keys). -->
+
+```
+(paste here)
+```
+
+## Additional context
+
+<!-- Any other context — related issues, PRs, ADRs, runbook links, etc. -->

.github/ISSUE_TEMPLATE/contributor_claim.md

@@ -0,0 +1,40 @@
+---
+name: Contributor claim (Drips Wave)
+about: Claim a numbered issue from issues.md to work on as part of a Drips Wave
+title: "[Claim] #<issue-number> — <short title>"
+labels: ["drips-wave", "contributor-claim"]
+assignees: []
+---
+
+## Issue being claimed
+
+<!-- Link the numbered issue from issues.md you want to work on.
+     Example: #298 Restrict access to GET /metrics -->
+
+**Issue:** #
+
+## Contributor
+
+<!-- Your GitHub handle and any relevant background (optional). -->
+
+**GitHub:** @
+
+## Approach outline
+
+<!-- Brief description of how you plan to solve this.
+     This is a conversation-starter, not a binding spec — we can iterate. -->
+
+## Questions or blockers
+
+<!-- Anything you need clarified before starting, or known risks.
+     If none, write "None". -->
+
+## Estimated timeline
+
+<!-- Rough estimate: e.g. "a few days", "this weekend", "~1 week".
+     Not binding — just helps us co-ordinate. -->
+
+---
+
+_By claiming this issue you agree to follow the [CONTRIBUTING.md](../CONTRIBUTING.md)
+guidelines and the [Code of Conduct](../CODE_OF_CONDUCT.md)._

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,35 @@
+---
+name: Feature request
+about: Propose a new feature or improvement for vortex-backend
+title: "[Feature] "
+labels: ["enhancement", "needs-triage"]
+assignees: []
+---
+
+## Summary
+
+<!-- One-sentence description of the feature. -->
+
+## Motivation
+
+<!-- Why is this needed? What problem does it solve, or what opportunity does it unlock?
+     Link to any relevant discussion, ADR, RFC, or roadmap item. -->
+
+## Proposed solution
+
+<!-- Describe how you'd like this to work. Be as specific as you can.
+     If you have more than one idea, list them separately. -->
+
+## Alternatives considered
+
+<!-- What other approaches did you consider, and why did you rule them out? -->
+
+## Acceptance criteria
+
+<!-- What does "done" look like for this feature? -->
+- [ ] 
+- [ ] 
+
+## Additional context
+
+<!-- Any other context — mockups, related issues, performance budgets, etc. -->