feat: add foreign key constraints and metrics for blockchain node

2025-09-28 06:04:30 +02:00
parent fe29631a86
commit b8b640666d
188 changed files with 15678 additions and 158 deletions
--- a/docs/done.md
+++ b/docs/done.md
@@ -41,8 +41,25 @@

 - Added `apps/wallet-daemon/src/app/receipts/service.py` providing `ReceiptVerifierService` that fetches and validates receipts via `aitbc_sdk`.
 - Created unit tests under `apps/wallet-daemon/tests/test_receipts.py` verifying service behavior.
+- Implemented wallet SDK receipt ingestion + attestation surfacing in `packages/py/aitbc-sdk/src/receipts.py`, including pagination client, signature verification, and failure diagnostics with full pytest coverage.

 ## Explorer Web

 - Initialized a Vite + TypeScript scaffold in `apps/explorer-web/` with `vite.config.ts`, `tsconfig.json`, and placeholder `src/main.ts` content.
 - Installed frontend dependencies locally to unblock editor tooling and TypeScript type resolution.
+- Implemented `overview` page stats rendering backed by mock block/transaction/receipt fetchers, including robust empty-state handling and TypeScript type fixes.
+
+## Pool Hub
+
+- Implemented FastAPI service scaffolding with Redis/PostgreSQL-backed repositories, match/health/metrics endpoints, and Prometheus instrumentation (`apps/pool-hub/src/poolhub/`).
+- Added Alembic migrations (`apps/pool-hub/migrations/`) and async integration tests covering repositories and endpoints (`apps/pool-hub/tests/`).
+
+## Solidity Token
+
+- Implemented attested minting logic in `packages/solidity/aitbc-token/contracts/AIToken.sol` using `AccessControl` role gates and ECDSA signature recovery.
+- Added Hardhat unit tests in `packages/solidity/aitbc-token/test/aitoken.test.ts` covering successful minting, replay prevention, and invalid attestor signatures.
+- Configured project TypeScript settings via `packages/solidity/aitbc-token/tsconfig.json` to align Hardhat, Node, and Mocha typings for the contract test suite.
+
+## JavaScript SDK
+
+- Delivered fetch-based client wrapper with TypeScript definitions and Vitest coverage under `packages/js/aitbc-sdk/`.
--- a/docs/explorer_web.md
+++ b/docs/explorer_web.md
@@ -1,33 +1,33 @@
 # Explorer Web – Task Breakdown

-## Status (2025-09-27)
+## Status (2025-09-28)

- **Stage 1**: UI scaffolding and mock data remain TODO; no implementation merged yet. Pending work should align with coordinator receipt history once backend endpoints stabilize.
+- **Stage 1**: Overview page renders block/transaction/receipt summaries from mock data with empty-state fallbacks. Remaining work focuses on blocks/transactions detail UIs, responsive polish, and live data toggle validation.

 ## Stage 1 (MVP)

 - **Structure & Assets**
-  - Populate `apps/explorer-web/public/` with `index.html`, `block.html`, `tx.html`, `address.html`, `receipts.html`, `404.html` scaffolds.
-  - Add base stylesheets (`css/base.css`, `css/layout.css`, `css/theme-dark.css`).
-  - Include logo and icon assets under `public/assets/`.
+  - ⏳ Populate `apps/explorer-web/public/` with `index.html`, `block.html`, `tx.html`, `address.html`, `receipts.html`, `404.html` scaffolds.
+  - ✅ Add base stylesheets (`public/css/base.css`, `public/css/layout.css`, `public/css/theme.css`).
+  - ⏳ Include logo and icon assets under `public/assets/`.

- **JavaScript Modules**
-  - Implement `js/config.js`, `js/api.js`, `js/store.js`, and `js/utils.js` helpers.
-  - Create component modules under `js/components/` (header, footer, searchbox, block-table, tx-table, pager, keyvalue).
-  - Implement page controllers under `js/pages/` for home, block detail, tx detail, address view, receipts view.
+- **TypeScript Modules**
+  - ✅ Provide configuration and data helpers (`src/config.ts`, `src/lib/mockData.ts`, `src/lib/models.ts`).
+  - ⏳ Add shared store/utilities module for cross-page state.
+  - ✅ Implement core page controllers and components under `src/pages/` and `src/components/` (overview, blocks, transactions, addresses, receipts, header/footer, data mode toggle).

 - **Mock Data**
-  - Provide optional mock JSON fixtures under `public/js/vendors/` or `public/mock/`.
-  - Enable mock mode toggle via `CONFIG.USE_MOCK`.
+  - ✅ Provide mock JSON fixtures under `public/mock/`.
+  - ✅ Enable mock/live mode toggle via `getDataMode()` and `<data-mode-toggle>` components.

 - **Interaction & UX**
-  - Implement search box detection for block numbers, hashes, and addresses.
-  - Add pagination/infinite scroll for block and transaction tables.
-  - Ensure dark theme styling with readable typography and table hover states.
+  - ⏳ Implement search box detection for block numbers, hashes, and addresses.
+  - ⏳ Add pagination or infinite scroll for block and transaction tables.
+  - ⏳ Expand responsive polish beyond overview cards (tablet/mobile grid, table hover states).

 - **Documentation**
-  - Update `apps/explorer-web/README.md` with build/run instructions and API assumptions.
-  - Document required CORS configuration for blockchain node.
+  - ✅ Update `apps/explorer-web/README.md` with build/run instructions and API assumptions.
+  - ✅ Capture coordinator API + CORS considerations in README deployment notes.

 ## Stage 2+

--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -17,10 +17,10 @@ This roadmap aggregates high-priority tasks derived from the bootstrap specifica

 - **Blockchain Node**
  - ✅ Define SQLModel schema for blocks, transactions, accounts, receipts (`apps/blockchain-node/src/aitbc_chain/models.py`).
-  - ⏳ Harden schema parity across runtime + storage:
-    - Generate Alembic baseline and incremental migrations in `apps/blockchain-node/migrations/` mirroring the current SQLModel definitions.
-    - Wire explicit SQLModel relationships (`Relationship`, `ForeignKey`) for block ↔ transaction ↔ receipt joins per bootstrap spec.
-    - Add validation hooks (SQLModel validators / custom service checks) to enforce hash formatting, foreign key integrity, and enum bounds before persistence.
+  - ✅ Harden schema parity across runtime + storage:
+    - Alembic baseline + follow-on migrations in `apps/blockchain-node/migrations/` now track the SQLModel schema (blocks, transactions, receipts, accounts).
+    - Added `Relationship` + `ForeignKey` wiring in `apps/blockchain-node/src/aitbc_chain/models.py` for block ↔ transaction ↔ receipt joins.
+    - Introduced hex/enum validation hooks via Pydantic validators to ensure hash integrity and safe persistence.
  - ✅ Implement PoA proposer loop with block assembly (`apps/blockchain-node/src/aitbc_chain/consensus/poa.py`).
  - ✅ Expose REST RPC endpoints for tx submission, balances, receipts (`apps/blockchain-node/src/aitbc_chain/rpc/router.py`).
  - ⏳ Deliver WebSocket RPC + P2P gossip layer:
@@ -38,25 +38,24 @@ This roadmap aggregates high-priority tasks derived from the bootstrap specifica
 - **Receipt Schema**
  - ✅ Finalize canonical JSON receipt format under `protocols/receipts/` (includes sample signed receipts).
  - ✅ Implement signing/verification helpers in `packages/py/aitbc-crypto` (JS SDK pending).
-  - Translate `docs/bootstrap/aitbc_tech_plan.md` contract skeleton into Solidity project.
-  - Add deployment/test scripts and document minting flow.
+  - ✅ Translate `docs/bootstrap/aitbc_tech_plan.md` contract skeleton into Solidity project (`packages/solidity/aitbc-token/`).
+  - ✅ Add deployment/test scripts and document minting flow (`packages/solidity/aitbc-token/scripts/` and `docs/run.md`).

 - **Wallet Daemon**
-  - Implement encrypted keystore (Argon2id + XChaCha20-Poly1305).
-  - Provide REST and JSON-RPC endpoints for wallet management and signing.
-  - Add mock ledger adapter with SQLite backend.
+  - ✅ Implement encrypted keystore (Argon2id + XChaCha20-Poly1305) via `KeystoreService`.
+  - ✅ Provide REST and JSON-RPC endpoints for wallet management and signing (`api_rest.py`, `api_jsonrpc.py`).
+  - ✅ Add mock ledger adapter with SQLite backend powering event history (`ledger_mock/`).
  - ✅ Integrate Python receipt verification helpers (`aitbc_sdk`) and expose API/service utilities validating miner + coordinator signatures.
-  - ⏳ Implement Wallet SDK receipt ingestion + attestation surfacing:
-    - Add client for `/v1/jobs/{job_id}/receipts` with pagination + retry support (`packages/py/aitbc-sdk/src/receipts.py`).
-    - Reuse signature verification helpers to validate miner + coordinator attestations before exposing results.
-    - Surface aggregated attestation status + failure reasons via SDK API for UI consumption; mirror logic in pending JS helper.
+  - ✅ Implement Wallet SDK receipt ingestion + attestation surfacing:
+    - Added `/v1/jobs/{job_id}/receipts` client helpers with cursor pagination, retry/backoff, and summary reporting (`packages/py/aitbc-sdk/src/receipts.py`).
+    - Reused crypto helpers to validate miner and coordinator signatures, capturing per-key failure reasons for downstream UX.
+    - Surfaced aggregated attestation status (`ReceiptStatus`) and failure diagnostics for SDK + UI consumers; JS helper parity still planned.

-## Stage 3 — Pool Hub & Marketplace
+## Stage 2 — Pool Hub & Marketplace

 - **Pool Hub**
-  - Implement miner registry, scoring engine, and `/v1/match` API.
-  - Integrate Redis/PostgreSQL backing stores per bootstrap spec.
-  - Add observability endpoints (`/v1/health`, `/v1/metrics`).
+  - ✅ Implement miner registry, scoring engine, and `/v1/match` API with Redis/PostgreSQL backing stores.
+  - ✅ Add observability endpoints (`/v1/health`, `/v1/metrics`) plus Prometheus instrumentation and integration tests.

 - **Marketplace Web**
  - Initialize Vite project with vanilla TypeScript.
@@ -69,6 +68,7 @@ This roadmap aggregates high-priority tasks derived from the bootstrap specifica
  - ✅ Seed mock datasets (`public/mock/`) and fetch helpers powering overview + blocks tables.
  - ✅ Extend mock integrations to transactions, addresses, and receipts pages.
  - ✅ Implement styling system, mock/live data toggle, and coordinator API wiring scaffold.
+  - ✅ Render overview stats from mock block/transaction/receipt summaries with graceful empty-state fallbacks.
  - ⏳ Validate live mode + responsive polish:
    - Hit live coordinator endpoints (`/v1/blocks`, `/v1/transactions`, `/v1/addresses`, `/v1/receipts`) via `getDataMode() === "live"` and reconcile payloads with UI models.
    - Add fallbacks + error surfacing for partial/failed live responses (toast + console diagnostics).
@@ -84,8 +84,7 @@ This roadmap aggregates high-priority tasks derived from the bootstrap specifica
    - Provide end-to-end tests + examples validating Pool Hub + wallet flows leveraging the coordinator receipt verification primitives.

 - **JavaScript SDK (`packages/js/aitbc-sdk`)**
-  - Provide fetch-based wrapper for web clients.
-  - Offer TypeScript definitions and basic auth handling.
+  - ✅ Provide fetch-based wrapper for web clients with TypeScript definitions and basic auth helpers.

 - **Examples**
  - Populate quickstart clients (Python/JS) with working code.
@@ -109,6 +108,7 @@ Use this roadmap as the canonical checklist during implementation. Mark complete

 - **Blockchain Node**: bootstrap module layout (`apps/blockchain-node/src/`), implement SQLModel schemas and RPC stubs aligned with historical/attested receipts.
 - **Explorer Web**: finish mock integration across all pages, add styling + mock/live toggle, and begin wiring coordinator endpoints (e.g., `/v1/jobs/{job_id}/receipts`).
+  - Current focus: reuse new overview metrics scaffolding for blocks/transactions detail views and expand coverage to live data mode.
 - **Marketplace Web**: scaffold Vite/vanilla frontends with mock integrations consuming the coordinator receipt history endpoints and SDK examples.
 - **Pool Hub**: initialize FastAPI project, scoring registry, and telemetry ingestion hooks leveraging coordinator/miner metrics.
 - **CI Enhancements**: add blockchain-node tests once available and frontend build/lint checks to `.github/workflows/python-tests.yml` or follow-on workflows.
--- a/docs/run.md
+++ b/docs/run.md
@@ -75,34 +75,84 @@ These instructions cover the newly scaffolded services. Install dependencies usi
   print("miner signature valid:", verification.miner_signature.valid)
   print("coordinator attestations:", [att.valid for att in verification.coordinator_attestations])
   PY
-   ```
   For receipts containing `attestations`, iterate the list and verify each entry with the corresponding public key.
   A JavaScript helper will ship with the Stage 2 SDK under `packages/js/`; until then, receipts can be verified with Node.js by loading the canonical JSON and invoking an Ed25519 verify function from `tweetnacl` (the payload is `canonical_json(receipt)` and the public key is `receipt.signature.public_key`).
   Example Node.js snippet:
   ```bash
   node <<'JS'
-   import fs from "fs";
-   import nacl from "tweetnacl";
-   import canonical from "json-canonicalize";
+  import fs from "fs";
+  import nacl from "tweetnacl";
+  import canonical from "json-canonicalize";

-   const receipt = JSON.parse(fs.readFileSync("receipt.json", "utf-8"));
-   const message = canonical(receipt).trim();
-   const sig = receipt.signature.sig;
-   const key = receipt.signature.key_id;
+  const receipt = JSON.parse(fs.readFileSync("receipt.json", "utf-8"));
+  const message = canonical(receipt).trim();
+  const sig = receipt.signature.sig;
+  const key = receipt.signature.key_id;

   const signature = Buffer.from(sig.replace(/-/g, "+").replace(/_/g, "/"), "base64");
   const publicKey = Buffer.from(key.replace(/-/g, "+").replace(/_/g, "/"), "base64");

   const ok = nacl.sign.detached.verify(Buffer.from(message, "utf-8"), signature, publicKey);
-   console.log("verified:", ok);
-   JS
+  console.log("verified:", ok);
+  JS
+  ```
+
+## Solidity Token (`packages/solidity/aitbc-token/`)
+
+1. Navigate to the token project:
+   ```bash
+   cd packages/solidity/aitbc-token
+   npm install
   ```
+2. Run the contract unit tests:
+   ```bash
+   npx hardhat test
+   ```
+3. Deploy `AIToken` to the configured Hardhat network. Provide the coordinator (required) and attestor (optional) role recipients via environment variables:
+   ```bash
+   COORDINATOR_ADDRESS=0xCoordinator \
+   ATTESTOR_ADDRESS=0xAttestor \
+   npx hardhat run scripts/deploy.ts --network localhost
+   ```
+   The script prints the deployed address and automatically grants the coordinator and attestor roles if they are not already assigned. Export the printed address for follow-on steps:
+   ```bash
+   export AITOKEN_ADDRESS=0xDeployedAddress
+   ```
+4. Mint tokens against an attested receipt by calling the contract from Hardhat’s console or a script. The helper below loads the deployed contract and invokes `mintWithReceipt` with an attestor signature:
+   ```ts
+   // scripts/mintWithReceipt.ts
+   import { ethers } from "hardhat";
+   import { AIToken__factory } from "../typechain-types";
+
+   async function main() {
+     const [coordinator] = await ethers.getSigners();
+     const token = AIToken__factory.connect(process.env.AITOKEN_ADDRESS!, coordinator);
+
+     const provider = "0xProvider";
+     const units = 100n;
+     const receiptHash = "0x...";
+     const signature = "0xSignedStructHash";
+
+     const tx = await token.mintWithReceipt(provider, units, receiptHash, signature);
+     await tx.wait();
+     console.log("Mint complete", await token.balanceOf(provider));
+   }
+
+   main().catch((err) => {
+     console.error(err);
+     process.exitCode = 1;
+   });
+   ```
+   Execute the helper with `AITOKEN_ADDRESS` exported and the signature produced by the attestor key used in your tests or integration flow:
+   ```bash
+   AITOKEN_ADDRESS=$AITOKEN_ADDRESS npx ts-node scripts/mintWithReceipt.ts
+   ```
+5. To derive the signature payload, reuse the `buildSignature` helper from `test/aitoken.test.ts` or recreate it in a script. The struct hash encodes `(chainId, contractAddress, provider, units, receiptHash)` and must be signed by an authorized attestor account.

 ## Wallet Daemon (`apps/wallet-daemon/`)

 1. Navigate to the service directory:
   ```bash
-   cd apps/wallet-daemon
   ```
 2. Install dependencies:
   ```bash