Merge changes related to AI agent docs from staging

.codex/config.toml

@@ -0,0 +1,7 @@
+[mcp_servers.context7]
+url = "https://mcp.context7.com/mcp/oauth"
+
+[mcp_servers.github]
+url = "https://api.githubcopilot.com/mcp/"
+bearer_token_env_var = "GIVETH_GITHUB_MCP_PAT"
+http_headers = { "X-MCP-Toolsets" = "default,projects,notifications" }

.cursor/mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "context7": {
+      "url": "https://mcp.context7.com/mcp/oauth"
+    },
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${env:GIVETH_GITHUB_MCP_PAT}",
+        "X-MCP-Toolsets": "default,projects,notifications"
+      }
+    }
+  }
+}

.mcp.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp/oauth"
+    },
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${GIVETH_GITHUB_MCP_PAT:-}",
+        "X-MCP-Toolsets": "default,projects,notifications"
+      }
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,29 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Source lives in `src/`. `src/server.ts` boots the HTTP service, while `src/index.ts` exposes the library entrypoint. `src/api/` contains the Express app, route handlers, and middleware. `src/services/` holds transaction verification, price lookups, chain-specific integrations, and Safe support. Shared configuration is under `src/config/`, reusable helpers under `src/utils/`, and domain types under `src/types/`. Tests are colocated with code as `*.test.ts` files, for example `src/api/routes/transaction.routes.test.ts`. Reference material lives in `docs/`, and `dist/` is the TypeScript build output.
+
+## Build, Test, and Development Commands
+
+Run `npm ci` first to install the locked dependency set. Use `npm run dev` to start the API with hot reload from `src/server.ts`. Use `npm run build` to compile TypeScript into `dist/`, then `npm start` to run the compiled server. Run `npm test` for the Mocha suite, `npm run test:coverage` for NYC coverage output, and `npm run test:watch` while iterating. Use `npm run lint`, `npm run lint:fix`, and `npm run prettify` for style checks and formatting. For containerized local runs, copy `.env.example` to `.env` and use `docker-compose up -d`.
+
+## Coding Style & Naming Conventions
+
+This project uses TypeScript with ESLint and Prettier. Follow formatter settings: 2-space indentation, semicolons, single quotes, trailing commas, and an 80-character print width. Use `PascalCase` for classes and error types, `camelCase` for functions, services, and variables, and keep file names descriptive and consistent with patterns such as `transactionVerificationService.ts`, `chains.routes.ts`, and `*.test.ts`.
+
+## Testing Guidelines
+
+Tests run with Mocha, Chai, Sinon, and Supertest through `ts-node/register`. Add tests beside the code you change and name them `*.test.ts`. Prefer stubbing external RPC or service calls rather than hitting live networks. There is no enforced coverage gate in the repo today, so new features and bug fixes should include focused route or service tests to prevent regressions.
+
+## Commit & Pull Request Guidelines
+
+Recent history favors short, descriptive commit subjects such as `Add AA donation verification`, `fix service name`, and `Update healthcheck commands...`. Keep commits small and scoped to one change. Pull requests should describe the behavior change, note any required `.env` or deployment updates, link the related issue, and include sample requests or responses when API contracts change.
+
+## Security & Configuration Tips
+
+Start from `.env.example` and never commit secrets, RPC keys, or deployment credentials. Verify changes to Docker, health checks, or ports against the GitHub Actions workflows in `.github/workflows/`, since `staging` and `main` trigger image build and deploy pipelines.
+
+## Architecture & External Services
+
+If your task involves understanding how this service connects to other Giveth services, what external APIs or RPC providers it depends on, or how giveth-v6-core consumes it, read [docs/EXTERNAL-SERVICES.md](docs/EXTERNAL-SERVICES.md).

docs/EXTERNAL-SERVICES.md

@@ -0,0 +1,91 @@
+# External Services — Blockchain Integration Service
+
+> Every external service and internal consumer this repo connects to. For implementation details, read the source files referenced in each section.
+
+---
+
+## System Diagram
+
+```
+
+                    ┌──────────────────────────────────────┐
+                    │   giveth-v6-core (NestJS · GraphQL)  │
+                    └──────────────┬───────────────────────┘
+                                   │  HTTP REST
+                                   ▼
+                    ┌──────────────────────────────────────┐
+                    │   Blockchain Integration Service     │
+                    │         Express · REST               │
+                    └──┬───┬───┬───┬───────────────────────┘
+                       │   │   │   │
+       ┌───────────────┘   │   │   └────────────────────┐
+       │         ┌─────────┘   └──────────┐             │
+       ▼         ▼                        ▼             ▼
+ ┌──────────┐ ┌──────────┐        ┌────────────┐ ┌───────────┐
+ │ EVM RPC  │ │  Solana  │        │  CoinGecko │ │ Safe API  │
+ │Providers │ │   RPC    │        │  (prices)  │ │ (multisig)│
+ └────┬─────┘ └──────────┘        └────────────┘ └───────────┘
+      │
+      ▼
+ ┌──────────────────────────────────────────────────────────┐
+ │  DonationHandler.sol contracts + ERC-20 token contracts  │
+ └──────────────────────────────────────────────────────────┘
+
+```
+
+---
+
+## Consumer
+
+### giveth-v6-core
+
+The only direct consumer. v6-core proxies all blockchain interaction through this service via REST endpoints for transaction verification, token price lookups, and chain metadata queries.
+
+- **Their client code:** `giveth-v6-core/src/integrations/blockchain/blockchain.service.ts`
+- **Endpoints actively consumed:** `POST /api/verify`, `POST /api/timestamp`, `POST /api/price`, `GET /api/chains`, `GET /api/chains/:networkId/transaction-url/:txHash`
+- **Endpoint wired but not yet called:** `POST /api/verify-batch` (client method exists in v6-core but no call site uses it)
+
+---
+
+## Dependencies
+
+### EVM RPC Providers
+
+JSON-RPC connections to 9 EVM networks (Ethereum, Polygon, Optimism, Arbitrum, Gnosis, Celo, Base, BSC, Avalanche) via ethers.js. Used for fetching transaction receipts, parsing event logs, and reading token metadata. Also supports `debug_traceTransaction` for Account Abstraction (EIP-4337) internal transfers, with graceful fallback.
+
+- **Config:** `src/config/networks.ts` — each network has a `*_RPC_URL` env var.
+
+### Solana RPC
+
+Direct connection via `@solana/web3.js` for parsing Solana transactions and calculating SOL/SPL token balance changes.
+
+- **Config:** `SOLANA_RPC_URL` env var.
+
+### CoinGecko API
+
+Token price lookups in USD by symbol or contract address. Results cached in-memory (1-min TTL).
+
+- **Source:** `src/services/priceService.ts`
+
+### Safe API (Gnosis Safe)
+
+Resolves Safe multisig `safeTxHash` values to actual on-chain transaction hashes so the service can then verify the real transaction.
+
+- **Package:** `@safe-global/api-kit`
+- **Source:** `src/services/safe/safeTransactionService.ts`
+
+### DonationHandler Smart Contracts
+
+Giveth's upgradeable Solidity contracts (repo: `donation-handler-foundry`) deployed on 7 EVM networks. This service parses their `DonationMade` events to verify individual donations within batch transactions.
+
+- **Address registry:** `src/config/donationHandlers.ts`
+
+### ERC-20 Token Contracts
+
+Interacts with ERC-20 contracts for `symbol()` validation, `decimals()` lookups (some paths fall back to 18), and `Transfer` event log parsing during donation verification.
+
+---
+
+## Infrastructure
+
+Deployed via Docker Compose (repo: `giveth-v6-deploy`) alongside giveth-v6-core, Redis, and Caddy reverse proxy. This service is **stateless** — no database and no persistent business data. It does hold in-memory caches and connection pools (CoinGecko price cache, EVM provider instances, Solana connections, chain handler registry) that are rebuilt on restart.