AGENTS

1. Use Node 18+; install deps with npm ci in root, backend/, web/, admin/ before CI-like runs.
2. Backend dev/prod: cd backend && npm run dev for local API, npm run build && npm start for production.
3. Backend tests: cd backend && npm test; single test: npx vitest run src/<path>/<file>.test.ts -t "test name".
4. Web/admin (Vite React): cd web|admin && npm run dev|build|test|lint|typecheck as needed.
5. Block reward bot: cd block-reward-bot && npm start (runs tsx index.ts).
6. Lint/typecheck/format backend: cd backend && npm run lint && npm run typecheck && npm run format (CI mirrors this in .github/workflows/ci.yml).
7. Formatting: Prettier (.prettierrc.json) with 100-char width, single quotes, semicolons, no trailing commas; run format before large diffs.
8. TypeScript style: prefer strict-friendly code, avoid any, and give explicit return types for exported functions and shared utilities.
9. Imports: group as Node builtins, external libs, then internal modules; use relative paths within each package (avoid cross-package imports without a clear reason).
10. Naming: camelCase for variables/functions, PascalCase for types/classes, SCREAMING_SNAKE_CASE for env-style constants and config keys.
11. Error handling: never swallow errors; centralize with Express middleware where possible, return sanitized messages, and log full details server-side only.
12. HTTP/Express layout: keep middleware in backend/src/middleware, routes in backend/src/routes, and keep each route file cohesive and minimal.
13. Tests: colocate Vitest files as *.test.ts under src; prefer HTTP-level tests via supertest plus focused unit tests for utilities and services.
14. When touching mining reward, withdrawal, or pool-like logic, always review and update related tests and architecture docs under docs/.
15. For "pool" / "VIDDHANA pool" work, first read contracts/pools/, contracts/rewards/, contracts/oracles/, contracts/risk/ and relevant docs/ to understand current design and risks.
16. For significant pool changes, sketch a brief blueprint (overview, asset flow, reward model, oracle updates, risk/circuit breaker, upgrade path) before coding large refactors.
17. Pool-related tests must at least cover deposit/withdraw happy paths, reward/APY calculation, emergency stop/pause, basic reentrancy attempts, and bad/stale oracle data using the repo's test framework.
18. When editing Solidity/contract-like code (e.g., under contracts/), keep changes small and audited-style, target Solidity 0.8.x, prefer OpenZeppelin over custom primitives, and document key invariants/assumptions in comments.
19. Security: treat all external input (HTTP, env, RPC, DB, oracle data) as untrusted; validate/parse minimally but explicitly, and respect existing auth, rate limiting, and circuit breaker mechanisms.
20. Repo hygiene/tooling: avoid large refactors or deletions without explicit user approval, summarize diffs by area (backend/web/admin/contracts/infra), and update this file if Cursor or Copilot instruction files are added.