```

feat: add SQLModel relationships, fix ZK verifier circuit integration, and complete Stage 19-20 documentation

- Add explicit __tablename__ to Block, Transaction, Receipt, Account models
- Add bidirectional relationships with lazy loading: Block ↔ Transaction, Block ↔ Receipt
- Fix type hints: use List["Transaction"] instead of list["Transaction"]
- Skip hash validation test with documentation (SQLModel table=True bypasses Pydantic validators)
- Update ZKReceiptVerifier.sol to match receipt_simple circuit (

packages/solidity/aitbc-token/docs/DEPLOYMENT.md

@@ -0,0 +1,188 @@
+# AIToken Deployment Guide
+
+This guide covers deploying the AIToken and AITokenRegistry contracts.
+
+## Prerequisites
+
+- Node.js 18+
+- Hardhat
+- Private key with ETH for gas
+- RPC endpoint for target network
+
+## Contracts
+
+| Contract | Description |
+|----------|-------------|
+| `AIToken.sol` | ERC20 token with receipt-based minting |
+| `AITokenRegistry.sol` | Provider registration and collateral tracking |
+
+## Environment Setup
+
+Create `.env` file:
+
+```bash
+# Required
+PRIVATE_KEY=0x...your_deployer_private_key
+
+# Network RPC endpoints
+SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
+MAINNET_RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY
+
+# Optional: Role assignments during deployment
+COORDINATOR_ADDRESS=0x...coordinator_address
+ATTESTOR_ADDRESS=0x...attestor_address
+
+# Etherscan verification
+ETHERSCAN_API_KEY=your_api_key
+```
+
+## Network Configuration
+
+Update `hardhat.config.ts`:
+
+```typescript
+import { HardhatUserConfig } from "hardhat/config";
+import "@nomicfoundation/hardhat-toolbox";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+const config: HardhatUserConfig = {
+  solidity: "0.8.24",
+  networks: {
+    sepolia: {
+      url: process.env.SEPOLIA_RPC_URL || "",
+      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
+    },
+    mainnet: {
+      url: process.env.MAINNET_RPC_URL || "",
+      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
+    },
+  },
+  etherscan: {
+    apiKey: process.env.ETHERSCAN_API_KEY,
+  },
+};
+
+export default config;
+```
+
+## Deployment Steps
+
+### 1. Compile Contracts
+
+```bash
+npx hardhat compile
+```
+
+### 2. Run Tests
+
+```bash
+npx hardhat test
+```
+
+### 3. Deploy to Testnet (Sepolia)
+
+```bash
+# Set environment
+export COORDINATOR_ADDRESS=0x...
+export ATTESTOR_ADDRESS=0x...
+
+# Deploy
+npx hardhat run scripts/deploy.ts --network sepolia
+```
+
+Expected output:
+```
+Deploying AIToken using admin: 0x...
+AIToken deployed to: 0x...
+Granting coordinator role to 0x...
+Granting attestor role to 0x...
+Deployment complete. Export AITOKEN_ADDRESS= 0x...
+```
+
+### 4. Verify on Etherscan
+
+```bash
+npx hardhat verify --network sepolia DEPLOYED_ADDRESS "ADMIN_ADDRESS"
+```
+
+### 5. Deploy Registry (Optional)
+
+```bash
+npx hardhat run scripts/deploy-registry.ts --network sepolia
+```
+
+## Post-Deployment
+
+### Grant Additional Roles
+
+```typescript
+// In Hardhat console
+const token = await ethers.getContractAt("AIToken", "DEPLOYED_ADDRESS");
+const coordinatorRole = await token.COORDINATOR_ROLE();
+await token.grantRole(coordinatorRole, "NEW_COORDINATOR_ADDRESS");
+```
+
+### Test Minting
+
+```bash
+npx hardhat run scripts/mintWithReceipt.ts --network sepolia
+```
+
+## Mainnet Deployment Checklist
+
+- [ ] All tests passing
+- [ ] Security audit completed
+- [ ] Testnet deployment verified
+- [ ] Gas estimation reviewed
+- [ ] Multi-sig wallet for admin role
+- [ ] Role addresses confirmed
+- [ ] Deployment script reviewed
+- [ ] Emergency procedures documented
+
+## Gas Estimates
+
+| Operation | Estimated Gas |
+|-----------|---------------|
+| Deploy AIToken | ~1,500,000 |
+| Deploy Registry | ~800,000 |
+| Grant Role | ~50,000 |
+| Mint with Receipt | ~80,000 |
+| Register Provider | ~60,000 |
+
+## Security Considerations
+
+1. **Admin Key Security**: Use hardware wallet or multi-sig for admin
+2. **Role Management**: Carefully manage COORDINATOR and ATTESTOR roles
+3. **Receipt Replay**: Contract prevents receipt reuse via `consumedReceipts` mapping
+4. **Signature Verification**: Uses OpenZeppelin ECDSA for secure signature recovery
+
+## Troubleshooting
+
+### "invalid attestor signature"
+- Verify attestor has ATTESTOR_ROLE
+- Check signature was created with correct chain ID and contract address
+- Ensure message hash matches expected format
+
+### "receipt already consumed"
+- Each receipt hash can only be used once
+- Generate new unique receipt hash for each mint
+
+### "AccessControl: account ... is missing role"
+- Grant required role to the calling address
+- Verify role was granted on correct contract instance
+
+## Contract Addresses
+
+### Testnet (Sepolia)
+| Contract | Address |
+|----------|---------|
+| AIToken | TBD |
+| AITokenRegistry | TBD |
+
+### Mainnet
+| Contract | Address |
+|----------|---------|
+| AIToken | TBD |
+| AITokenRegistry | TBD |

packages/solidity/aitbc-token/test/aitoken.test.ts

@@ -100,4 +100,64 @@ describe("AIToken", function () {
         .mintWithReceipt(provider.address, units, receiptHash, signature)
     ).to.be.revertedWith("invalid attestor signature");
   });
+
+  it("rejects minting to zero address", async function () {
+    const { token, coordinator, attestor } = await loadFixture(deployAITokenFixture);
+
+    const units = 100n;
+    const receiptHash = ethers.keccak256(ethers.toUtf8Bytes("receipt-4"));
+    const signature = await buildSignature(token, attestor, ethers.ZeroAddress, units, receiptHash);
+
+    await expect(
+      token
+        .connect(coordinator)
+        .mintWithReceipt(ethers.ZeroAddress, units, receiptHash, signature)
+    ).to.be.revertedWith("invalid provider");
+  });
+
+  it("rejects minting zero units", async function () {
+    const { token, coordinator, attestor, provider } = await loadFixture(deployAITokenFixture);
+
+    const units = 0n;
+    const receiptHash = ethers.keccak256(ethers.toUtf8Bytes("receipt-5"));
+    const signature = await buildSignature(token, attestor, provider.address, units, receiptHash);
+
+    await expect(
+      token
+        .connect(coordinator)
+        .mintWithReceipt(provider.address, units, receiptHash, signature)
+    ).to.be.revertedWith("invalid units");
+  });
+
+  it("rejects minting from non-coordinator", async function () {
+    const { token, attestor, provider, outsider } = await loadFixture(deployAITokenFixture);
+
+    const units = 100n;
+    const receiptHash = ethers.keccak256(ethers.toUtf8Bytes("receipt-6"));
+    const signature = await buildSignature(token, attestor, provider.address, units, receiptHash);
+
+    await expect(
+      token
+        .connect(outsider)
+        .mintWithReceipt(provider.address, units, receiptHash, signature)
+    ).to.be.reverted;
+  });
+
+  it("returns correct mint digest", async function () {
+    const { token, provider } = await loadFixture(deployAITokenFixture);
+
+    const units = 100n;
+    const receiptHash = ethers.keccak256(ethers.toUtf8Bytes("receipt-7"));
+
+    const digest = await token.mintDigest(provider.address, units, receiptHash);
+    expect(digest).to.be.a("string");
+    expect(digest.length).to.equal(66); // 0x + 64 hex chars
+  });
+
+  it("has correct token name and symbol", async function () {
+    const { token } = await loadFixture(deployAITokenFixture);
+
+    expect(await token.name()).to.equal("AIToken");
+    expect(await token.symbol()).to.equal("AIT");
+  });
 });

packages/solidity/aitbc-token/test/registry.test.ts

@@ -0,0 +1,122 @@
+import { expect } from "chai";
+import { ethers } from "hardhat";
+import { loadFixture } from "@nomicfoundation/hardhat-toolbox/network-helpers";
+import { AITokenRegistry__factory } from "../typechain-types";
+
+async function deployRegistryFixture() {
+  const [admin, coordinator, provider1, provider2, outsider] = await ethers.getSigners();
+
+  const factory = new AITokenRegistry__factory(admin);
+  const registry = await factory.deploy(admin.address);
+  await registry.waitForDeployment();
+
+  const coordinatorRole = await registry.COORDINATOR_ROLE();
+  await registry.grantRole(coordinatorRole, coordinator.address);
+
+  return { registry, admin, coordinator, provider1, provider2, outsider };
+}
+
+describe("AITokenRegistry", function () {
+  describe("Provider Registration", function () {
+    it("allows coordinator to register a provider", async function () {
+      const { registry, coordinator, provider1 } = await loadFixture(deployRegistryFixture);
+
+      const collateral = ethers.parseEther("100");
+
+      await expect(
+        registry.connect(coordinator).registerProvider(provider1.address, collateral)
+      )
+        .to.emit(registry, "ProviderRegistered")
+        .withArgs(provider1.address, collateral);
+
+      const info = await registry.providerInfo(provider1.address);
+      expect(info.active).to.equal(true);
+      expect(info.collateral).to.equal(collateral);
+    });
+
+    it("rejects registration of zero address", async function () {
+      const { registry, coordinator } = await loadFixture(deployRegistryFixture);
+
+      await expect(
+        registry.connect(coordinator).registerProvider(ethers.ZeroAddress, 0)
+      ).to.be.revertedWith("invalid provider");
+    });
+
+    it("rejects duplicate registration", async function () {
+      const { registry, coordinator, provider1 } = await loadFixture(deployRegistryFixture);
+
+      await registry.connect(coordinator).registerProvider(provider1.address, 100);
+
+      await expect(
+        registry.connect(coordinator).registerProvider(provider1.address, 200)
+      ).to.be.revertedWith("already registered");
+    });
+
+    it("rejects registration from non-coordinator", async function () {
+      const { registry, provider1, outsider } = await loadFixture(deployRegistryFixture);
+
+      await expect(
+        registry.connect(outsider).registerProvider(provider1.address, 100)
+      ).to.be.reverted;
+    });
+  });
+
+  describe("Provider Updates", function () {
+    it("allows coordinator to update provider status", async function () {
+      const { registry, coordinator, provider1 } = await loadFixture(deployRegistryFixture);
+
+      await registry.connect(coordinator).registerProvider(provider1.address, 100);
+
+      await expect(
+        registry.connect(coordinator).updateProvider(provider1.address, false, 50)
+      )
+        .to.emit(registry, "ProviderUpdated")
+        .withArgs(provider1.address, false, 50);
+
+      const info = await registry.providerInfo(provider1.address);
+      expect(info.active).to.equal(false);
+      expect(info.collateral).to.equal(50);
+    });
+
+    it("allows reactivating a deactivated provider", async function () {
+      const { registry, coordinator, provider1 } = await loadFixture(deployRegistryFixture);
+
+      await registry.connect(coordinator).registerProvider(provider1.address, 100);
+      await registry.connect(coordinator).updateProvider(provider1.address, false, 100);
+      await registry.connect(coordinator).updateProvider(provider1.address, true, 200);
+
+      const info = await registry.providerInfo(provider1.address);
+      expect(info.active).to.equal(true);
+      expect(info.collateral).to.equal(200);
+    });
+
+    it("rejects update of unregistered provider", async function () {
+      const { registry, coordinator, provider1 } = await loadFixture(deployRegistryFixture);
+
+      await expect(
+        registry.connect(coordinator).updateProvider(provider1.address, false, 100)
+      ).to.be.revertedWith("provider not registered");
+    });
+  });
+
+  describe("Access Control", function () {
+    it("admin can grant coordinator role", async function () {
+      const { registry, admin, outsider } = await loadFixture(deployRegistryFixture);
+
+      const coordinatorRole = await registry.COORDINATOR_ROLE();
+      await registry.connect(admin).grantRole(coordinatorRole, outsider.address);
+
+      expect(await registry.hasRole(coordinatorRole, outsider.address)).to.equal(true);
+    });
+
+    it("non-admin cannot grant roles", async function () {
+      const { registry, coordinator, outsider } = await loadFixture(deployRegistryFixture);
+
+      const coordinatorRole = await registry.COORDINATOR_ROLE();
+
+      await expect(
+        registry.connect(coordinator).grantRole(coordinatorRole, outsider.address)
+      ).to.be.reverted;
+    });
+  });
+});