Develop

.env.example

@@ -0,0 +1,49 @@
+# The Graph gateway credential. Prefer sending this as an Authorization bearer
+# token instead of embedding it in a gateway URL.
+GRAPH_API_KEY=
+
+# Ordered Base mainnet RPC endpoints passed to Nuthatch as repeatable --rpc
+# arguments by nuthatch.service. Production loads them from the root-owned
+# /etc/default/nuthatch; nuthatch.toml does not interpolate environment
+# variables. Never commit keyed URLs or tokens. Use three independent providers
+# and probe each endpoint's eth_getLogs range cap before deploying it. All three
+# values are required by the documented nuthatch.service unit.
+BASE_RPC_URL_PRIMARY=
+BASE_RPC_URL_SECONDARY=
+BASE_RPC_URL_TERTIARY=
+
+# Private URL of the Nuthatch HTTP API, without a trailing slash. When
+# DeepTrace and Nuthatch are co-located, use loopback so normal operation does
+# not depend on Tailscale or public DNS. Never expose this URL to MCP users.
+# Production example: http://127.0.0.1:8288
+NUTHATCH_BASE_URL=
+
+# Reserved for authenticated admin access if --no-admin is removed.
+# Production currently disables the admin UI with --no-admin.
+NUTHATCH_ADMIN_TOKEN=
+
+# Gateway fixed-window rate limit: max requests per key (default: 30, maximum: 300).
+DEEPTRACE_RATE_LIMIT_MAX_REQUESTS=30
+
+# Gateway fixed-window duration in milliseconds (default: 60000, maximum: 3600000).
+DEEPTRACE_RATE_LIMIT_WINDOW_MS=60000
+
+# Per-source adapter timeout in milliseconds (default: 5000, maximum: 8000).
+DEEPTRACE_SOURCE_TIMEOUT_MS=5000
+
+# Where issued per-client bearer tokens are recorded, as SHA-256 digests only.
+# Must live outside the deployed tree: the deploy rsyncs it with --delete, so an
+# in-repo path is wiped on every release. Production: /var/lib/deeptrace/tokens.json
+DEEPTRACE_TOKEN_STORE=
+
+# Deprecated shared bearer token, kept only so pre-migration clients keep
+# working. One leak exposes every client and cannot be revoked selectively.
+# Leave it empty: clients mint their own token at /auth or through OAuth. When
+# set it must be at least 32 characters, or startup fails.
+DEEPTRACE_HTTP_TOKEN=
+
+# Inactive MCP sessions expire after this many milliseconds (default: 1800000).
+DEEPTRACE_HTTP_SESSION_IDLE_TIMEOUT_MS=1800000
+
+# How often inactive MCP sessions are reaped (default: 60000).
+DEEPTRACE_HTTP_SESSION_SWEEP_INTERVAL_MS=60000

.github/workflows/code-quality.yml

@@ -0,0 +1,41 @@
+name: code quality
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v6
+
+      - name: setup node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: install dependencies
+        run: npm ci
+
+      - name: check formatting
+        run: npm run format:check
+
+      - name: lint code
+        run: npm run lint
+
+      - name: check types
+        run: npm run typecheck
+
+      - name: run unit tests
+        run: npm test
+
+      - name: build project
+        run: npm run build

.github/workflows/nuthatch-check.yml

@@ -0,0 +1,53 @@
+name: nuthatch check
+
+on:
+  push:
+    paths:
+      - "nest/**"
+      - ".github/workflows/nuthatch-check.yml"
+  pull_request:
+    paths:
+      - "nest/**"
+      - ".github/workflows/nuthatch-check.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v6
+
+      - name: validate nest structure
+        run: |
+          test -f nest/nuthatch.toml || { echo "nest/nuthatch.toml missing"; exit 1; }
+          test -f nest/schema.json || { echo "nest/schema.json missing"; exit 1; }
+          test -d nest/abis || { echo "nest/abis/ missing"; exit 1; }
+          test -d nest/views || { echo "nest/views/ missing"; exit 1; }
+          test -d nest/checks || { echo "nest/checks/ missing"; exit 1; }
+          test -d nest/checks/expected || { echo "nest/checks/expected/ missing"; exit 1; }
+
+      - name: validate view SQL exists
+        run: |
+          for view in pool_swap_freshness pool_swap_search wallet_swap_activity; do
+            test -f "nest/views/${view}.sql" || { echo "missing nest/views/${view}.sql"; exit 1; }
+          done
+
+      - name: validate check SQL files exist
+        run: |
+          for check in view_shape latest_swap_identity recent_count_24h provenance_not_null decimal_columns hot_sealed_no_duplicates swap_search_parity wallet_activity_parity; do
+            test -f "nest/checks/${check}.sql" || { echo "missing nest/checks/${check}.sql"; exit 1; }
+            test -f "nest/checks/expected/${check}.json" || { echo "missing nest/checks/expected/${check}.json"; exit 1; }
+          done
+
+      - name: validate no secrets in nest
+        run: |
+          if grep -rn "GRAPH_API_KEY\|Bearer \|api_key=\|NUTHATCH_ADMIN_TOKEN" nest/; then
+            echo "Secret found in nest/"
+            exit 1
+          fi
+          echo "No secrets found in nest/"

.gitignore

@@ -3,6 +3,10 @@
 .env.*
 !.env.example
 
+# Local planning docs — working notes, not part of the deliverable
+/DATA_PIPE_PLAN.md
+/docs/M*_PLAN.md
+
 # TypeScript / Node
 node_modules/
 dist/
@@ -24,3 +28,5 @@ coverage/
 .yarn/cache/
 .yarn/unplugged/
 .pnp.*
+/DEEPTRACE_HANDOFF.md
+/DEV_PLAN.md

.prettierignore

@@ -0,0 +1,6 @@
+dist
+node_modules
+package-lock.json
+*.md
+LICENSE
+src/http/public/index.html

.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "printWidth": 100,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all"
+}