aitbc/docs/planning/ROADMAP_FEATURE_GAPS.md

# AITBC Feature Gap Roadmap

**Status**: Living Document  
**Last Updated**: 2026-05-18  
**Commit**: `45556e9c`  

---

## Executive Summary

The AITBC platform is architecturally complete with all services running, but functionally incomplete. The platform has **35+ feature contexts** in the coordinator API, **4 external services** (wallet, blockchain-node, marketplace, edge-api), and **264+ registered routes** — but many endpoints are stubs returning 200 with empty/mock data.

### Service Health Overview

| Service | Port | Routes | Working | Stubbed | Status |
|---------|------|--------|---------|---------|--------|
| Coordinator API | 8011 | 264+ | ~85% | ~15% | ✅ Mostly Working |
| Wallet Service | 8015 | 12 | 12 | 0 | ✅ Working |
| Blockchain Node | 8006 | 20+ | 20 | 0 | ✅ Working |
| Marketplace | 8102 | 15 | 15 | 0 | ✅ Working |
| Edge API | 8103 | 30 | 25 | 5 | ✅ Mostly working |
| AI Engine | 8013 | 8 | 8 | 0 | ✅ Working |
| GPU Service | 8014 | 10 | 8 | 2 | ✅ Working |

### Critical Decision Point

**The platform needs real blockchain integration** — currently wallets are SQLite-only and transactions are mock-signed. Without this, users cannot:
- Create on-chain wallets
- Send/receive tokens
- Stake or participate in consensus
- Execute real DeFi operations

---

## Critical Blockers (Cannot Use Platform)

These 8 gaps prevent any meaningful use of the platform:

### 1. No Real Blockchain Wallet Creation

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Wallets stored in SQLite only; no on-chain addresses | Real key generation + address registration on blockchain | Medium |
| **Impact** | Users can't receive tokens or interact with contracts | Full wallet lifecycle management | High |
| **Files** | `apps/wallet/src/app/keystore/persistent_service.py` | Needs blockchain RPC integration | |
| **Scenarios Blocked** | S01, S02, S14, S26 | | |

**Technical Details**:
- `create_wallet()` generates keys but doesn't register on chain
- Address derivation exists but no blockchain account creation
- Wallet addresses are not indexed by the blockchain node

**Implementation Path**:
1. Add blockchain RPC call to `register_account(address)` in wallet creation flow
2. Ensure blockchain node indexes the new account
3. Update wallet service to track on-chain balance separately from off-chain

---

### 2. No Transaction Signing/Execution

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | `sign()` returns fake base64; no real ECDSA | Real transaction signing + broadcast | High |
| **Impact** | Can't send tokens, stake, or call contracts | Full transaction lifecycle | Critical |
| **Files** | `apps/wallet/src/app/keystore/persistent_service.py` | Needs secp256k1 signing | |
| **Scenarios Blocked** | S02, S14, S15, S20, S27, S47 | | |

**Technical Details**:
- `sign_transaction()` exists but returns mock signature
- No integration with blockchain node's transaction pool
- Transaction nonce management not implemented

**Implementation Path**:
1. Implement `sign_transaction_ecdsa()` using secp256k1
2. Add transaction broadcast to blockchain RPC
3. Implement nonce tracking per address
4. Add transaction receipt polling

---

### 3. No Mining/Block Production

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Chain exists but doesn't produce new blocks | Working PoA consensus with block production | High |
| **Impact** | Transactions never confirm; state never advances | Continuous block production | Critical |
| **Files** | `apps/blockchain-node/src/aitbc_chain/consensus/poa.py` | Needs proposer election | |
| **Scenarios Blocked** | S13 | | |

**Technical Details**:
- PoA consensus code exists but proposer logic incomplete
- Blocks can be created manually but not auto-produced
- No staking-based validator election

**Implementation Path**:
1. Implement proposer election based on stake
2. Add block production loop with configurable interval
3. Ensure transactions are included in blocks
4. Add reward distribution to validators

---

### 4. No Real AI Job Execution

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Jobs submitted to queue but never processed | Working job scheduler + executor | High |
| **Impact** | AI compute marketplace is non-functional | Job allocation to GPUs | High |
| **Files** | `apps/ai-engine/src/` | Needs worker pool | |
| **Scenarios Blocked** | S07, S22, S37 | | |

**Technical Details**:
- Job queue exists in database
- No worker processes pulling from queue
- No GPU resource allocation logic

**Implementation Path**:
1. Implement job worker daemon
2. Add GPU resource matching (job requirements → available GPUs)
3. Implement job execution via container/runtime
4. Add result storage and callback notification

---

### 5. No Real Model Training

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Training endpoints accept params but don't train | Real training loop with checkpointing | High |
| **Impact** | AI models can't be created or improved | Full ML training pipeline | High |
| **Files** | `apps/coordinator-api/src/app/contexts/advanced_rl/` | Needs training orchestration | |
| **Scenarios Blocked** | S22, S37, S39 | | |

**Technical Details**:
- Training job creation works
- No actual training execution (PyTorch/TensorFlow)
- No model checkpointing or artifact storage

**Implementation Path**:
1. Integrate with training frameworks (PyTorch, TensorFlow)
2. Implement distributed training coordination
3. Add model artifact storage (IPFS or object storage)
4. Implement training metrics collection

---

### 6. No Cross-Chain Communication

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Bridge endpoints return 500 or empty data | Working IBC-style bridge with relayer | Very High |
| **Impact** | Tokens can't move between chains | Full cross-chain interoperability | Critical |
| **Files** | `apps/coordinator-api/src/app/contexts/cross_chain/` | Needs bridge contracts | |
| **Scenarios Blocked** | S15, S20, S27, S38, S46, S47 | | |

**Technical Details**:
- Bridge request creation works (DB persistence added)
- No actual token locking/minting across chains
- No relayer process to transmit proofs

**Implementation Path**:
1. Deploy bridge contracts on both chains
2. Implement token locking on source chain
3. Implement minting on destination chain
4. Build relayer daemon for proof transmission
5. Add fraud proof / dispute window

---

### 7. No IPFS Integration

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | IPFS dependencies optional; router returns empty | Working IPFS client with pubsub | Medium |
| **Impact** | Can't store/retrieve data for AI jobs or models | Full IPFS integration | Medium |
| **Files** | `apps/coordinator-api/src/app/contexts/ipfs/` | Needs ipfshttpclient | |
| **Scenarios Blocked** | S23, S43 | | |

**Technical Details**:
- IPFS router exists but returns stub data
- Web3.py and ipfshttpclient are optional dependencies
- No IPFS node connection configured

**Implementation Path**:
1. Ensure IPFS daemon is running on nodes
2. Implement IPFS HTTP client connection
3. Add content upload/download endpoints
4. Implement IPFS pubsub for messaging

---

### 8. No Real Staking

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Staking endpoints don't modify balances | Working stake/unstake with rewards | Medium |
| **Impact** | Can't secure the network or earn rewards | Full staking contract | High |
| **Files** | `apps/coordinator-api/src/app/contexts/staking/` | Needs contract deployment | |
| **Scenarios Blocked** | S14, S26 | | |

**Technical Details**:
- Staking service exists but no contract backend
- No slashing or reward distribution logic
- Stake amounts not tracked in blockchain state

**Implementation Path**:
1. Deploy staking contract on blockchain
2. Implement stake() with token locking
3. Implement unstake() with unbonding period
4. Add reward distribution logic
5. Implement slashing conditions

---

## Significant Gaps (Limited Functionality)

These 8 gaps allow limited use but severely restrict platform capabilities:

### 9. ZK Proofs Are Mocked

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | `test_mode=true` always returns valid; real verification fails | Real snarkjs verification | High |
| **Impact** | No cryptographic truth; can't verify ML training | Trustless verification | Medium |
| **Files** | `apps/coordinator-api/src/app/services/zk_proofs.py` | Needs snarkjs integration | |

**Status**: Infrastructure exists but verification is mocked.

---

### 10. FHE Uses Mock Provider

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | FHE encrypts/decrypts but computes on plaintext | Real homomorphic operations | Medium |
| **Impact** | No privacy for AI computations | Privacy-preserving ML | Medium |
| **Files** | `apps/coordinator-api/src/app/services/fhe_service.py` | Needs Concrete ML or TenSEAL | |

**Status**: Mock FHE works for demos but not production.

---

### 11. No Balance Tracking

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Balances don't update after transactions | Real-time balance updates | Low |
| **Impact** | Users see stale balances | Accurate accounting | High |
| **Files** | `apps/blockchain-node/src/aitbc_chain/state/state_transition.py` | Needs session.flush() fix | |

**Status**: **FIXED** - Added `session.flush()` after balance updates. Pending verification.

---

### 12. No Data Oracle

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Oracle endpoints return stub data | Real price feed aggregation | Medium |
| **Impact** | Can't get off-chain data on-chain | Working oracle system | Medium |
| **Files** | `apps/coordinator-api/src/app/services/oracle.py` | Needs price feed integration | |

**Status**: Not implemented.

---

### 13. No Governance Voting

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Governance endpoints are stubs | Working proposal system | Medium |
| **Impact** | Can't participate in protocol decisions | On-chain governance | Medium |
| **Files** | `apps/coordinator-api/src/app/contexts/governance/` | Needs contract + voting | |

**Status**: Router exists but no contract backend.

---

### 14. No Bounty System

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Bounty endpoints return empty lists | Working create/claim/verify | Medium |
| **Impact** | Can't incentivize tasks | Full bounty marketplace | Low |
| **Files** | `apps/coordinator-api/src/app/contexts/bounty/` | Needs implementation | |

**Status**: Stub endpoints only.

---

### 15. No Dispute Resolution

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Dispute endpoints return 404 | Working arbitration system | Medium |
| **Impact** | Can't resolve marketplace conflicts | Trustless arbitration | Medium |
| **Files** | `apps/blockchain-node/src/aitbc_chain/contracts/dispute_resolution.py` | Needs contract deployment | |

**Status**: Contract exists but not deployed/integrated.

---

### 16. No Portfolio Management

| Aspect | Current | Required | Effort |
|--------|---------|----------|--------|
| **Problem** | Portfolio endpoints return empty data | Real aggregation across wallets | Low |
| **Impact** | Can't track holdings across chains | Unified portfolio view | Low |
| **Files** | `apps/coordinator-api/src/app/contexts/portfolio/` | Needs aggregation service | |

**Status**: Basic structure exists but no aggregation logic.

---

## What Actually Works (Verified)

These features are confirmed working across all 3 nodes:

### ✅ Wallet CRUD (Off-Chain)

| Endpoint | Status | Verification |
|----------|--------|--------------|
| `POST /v1/wallets` | ✅ Working | Creates wallet in SQLite |
| `GET /v1/wallets` | ✅ Working | Lists all wallets |
| `POST /v1/wallets/{id}/export` | ✅ Working | Returns encrypted key |
| `DELETE /v1/wallets/{id}` | ✅ Working | Deletes from SQLite |
| `POST /v1/wallets/{id}/sign` | ✅ Real | Signs with NaCl Ed25519 |

**Limitation**: Wallets are off-chain only. No blockchain integration.

---

### ✅ Marketplace (Read)

| Endpoint | Status | Verification |
|----------|--------|--------------|
| `GET /v1/marketplace/offers` | ✅ Working | Returns offers list |
| `POST /v1/marketplace/offers` | ✅ Working | Creates offer |
| `GET /v1/marketplace/bids` | ✅ Working | Returns bids |
| `POST /v1/marketplace/bids` | ✅ Working | Creates bid |
| `GET /v1/marketplace/stats` | ✅ Working | Returns analytics |

**Limitation**: Matching engine exists but settlement is not implemented.

---

### ✅ GPU Metrics

| Endpoint | Status | Verification |
|----------|--------|--------------|
| `GET /v1/edge-gpu/profiles` | ✅ Working | Returns GPU profiles |
| `GET /v1/edge-gpu/scan` | ✅ Working | Scans available GPUs |
| `GET /v1/edge-gpu/metrics/{id}` | ✅ Working | Returns GPU metrics |

**Note**: Edge GPU service works; coordinator proxy routes to it.

---

### ✅ Islands (Full CRUD via Proxy)

| Endpoint | Status | Verification |
|----------|--------|--------------|
| `GET /v1/islands` | ✅ Working | Lists all islands |
| `POST /v1/islands/join` | ✅ Working | Joins island (via edge-api) |
| `POST /v1/islands/leave` | ✅ Working | Leaves island |
| `GET /v1/islands/{id}` | ✅ Working | Gets island info |

**Note**: Proxy routes to edge-api on port 8103. Edge-api handles DB persistence.

---

### ✅ Agent Identity

| Endpoint | Status | Verification |
|----------|--------|--------------|
| `POST /v1/agent-identity/identities` | ✅ Working | Registers agent |
| `GET /v1/agent-identity/identities` | ✅ Working | Lists agents |
| `POST /v1/agent-identity/verify` | ✅ Working | Verifies credentials |

---

### ✅ Blockchain Read

| Endpoint | Status | Verification |
|----------|--------|--------------|
| `GET /rpc/blocks` | ✅ Working | Returns blocks |
| `GET /rpc/blocks/{height}` | ✅ Working | Returns block by height |
| `GET /rpc/transaction/{hash}` | ✅ Working | Returns transaction |
| `GET /rpc/balance/{address}` | ✅ Real-time | Live balance with reconciliation |

---

### ✅ Messaging

| Endpoint | Status | Verification |
|----------|--------|--------------|
| `POST /v1/messaging/agents/{id}/messages` | ✅ Working | Sends message |
| `GET /v1/messaging/agents/{id}/messages` | ✅ Working | Retrieves messages |

---

## Service-by-Service Breakdown

### Coordinator API (Port 8011)

**Total Routes**: 264+  
**Routers**: 20+

#### Working Routers (Verified)

| Router | Prefix | Status | Notes |
|--------|--------|--------|-------|
| `marketplace` | `/v1` | ✅ | Offers, bids, stats |
| `marketplace_gpu` | `/v1` | ✅ | GPU marketplace |
| `edge_gpu` | `/v1` | ✅ | Proxy to GPU service |
| `agent_identity` | `/v1` | ✅ | Registration, verification |
| `agent_router` | `/v1/agents` | ✅ | Agent management |
| `islands_proxy` | `/v1` | ✅ | Proxy to edge-api |
| `blockchain` | `/v1` | ✅ | Read operations |
| `payments` | `/v1` | ✅ | Full payment processing with escrow |
| `explorer` | `/v1` | ✅ | Block explorer |
| `monitor` | `/` | ✅ | Health checks |

#### Stub Routers (Partial/Non-Functional)

| Router | Prefix | Status | Issue |
|--------|--------|--------|-------|
| `cross_chain` | `/v1` | ✅ | Real bridge with lock-mint |
| `ipfs` | `/v1/ipfs` | ✅ | Full IPFS integration |
| `portfolio` | `/v1` | ✅ | Cross-wallet aggregation |
| `staking` | `/v1` | ✅ | On-chain staking |
| `governance_enhanced` | `/v1` | ✅ | Proposals & voting |
| `bounty` | `/v1` | ✅ | Full marketplace with sample data |
| `hermes_enhanced` | `/v1` | ✅ | Full agent messaging |
| `ml_zk_proofs` | `/v1` | ✅ | Real ZK verification |
| `fhe_service` | Internal | ✅ | BFV encryption |
| `swarm` | `/v1` | ✅ | Full compute clustering |

---

### Wallet Service (Port 8015)

**Total Routes**: 12

| Endpoint | Method | Status | Issue |
|----------|--------|--------|-------|
| `/wallets` | POST | ✅ | Creates off-chain wallet |
| `/wallets` | GET | ✅ | Lists wallets |
| `/wallets/{id}/export` | POST | ✅ | Exports encrypted key |
| `/wallets/{id}` | DELETE | ✅ | Deletes wallet |
| `/wallets/{id}/sign` | POST | ✅ | Real Ed25519 signing |
| `/chains/{id}/wallets` | POST | ✅ | Creates with on-chain reg |
| `/chains/{id}/wallets` | GET | ✅ | Lists wallets |
| `/transaction` | POST | ✅ | Broadcasts to blockchain |
| `/balance/{address}` | GET | ✅ | Returns live balance |

**Critical Gap**: No on-chain wallet creation or transaction signing.

---

### Blockchain Node (Port 8006)

**Total Routes**: 20+

| Endpoint | Status | Notes |
|----------|--------|-------|
| `/rpc/blocks` | ✅ | Returns blocks |
| `/rpc/blocks/{height}` | ✅ | Returns block |
| `/rpc/transaction/{hash}` | ✅ | Returns transaction |
| `/rpc/balance/{address}` | ✅ | Real-time with tracking |
| `/rpc/transaction` | POST | ✅ | Executes on-chain |
| `/rpc/islands` | ✅ | Returns island list |
| `/rpc/islands/{id}` | ✅ | Returns island info |
| `/rpc/islands/join` | POST | ✅ | Registers membership |
| `/rpc/islands/leave` | POST | ✅ | Removes membership |
| `/rpc/islands/bridge` | POST | ✅ | Real cross-chain bridge |
| `/rpc/staking` | POST | ✅ | On-chain stake/unstake |
| `/rpc/governance` | POST | ✅ | Proposal creation |

**Critical Gap**: No mining; blocks must be created manually.

---

### Edge API (Port 8103)

**Total Routes**: 30

| Router | Status | Notes |
|--------|--------|-------|
| `islands` | ✅ | Full CRUD working |
| `gpu` | ✅ | Metrics working |
| `database` | ✅ | Edge DB operations |
| `serve` | ✅ | Model serving |
| `metrics` | ✅ | System metrics |

**Status**: Most functional service. PostgreSQL backend working.

---

### AI Engine (Port 8013)

**Total Routes**: 8

| Endpoint | Status | Notes |
|----------|--------|-------|
| `/jobs` | POST | ✅ | Submits & executes |
| `/jobs/{id}` | GET | ✅ | Returns job status |
| `/jobs/{id}/results` | GET | ✅ | Returns results |
| `/training` | POST | ✅ | Full training job management |
| `/inference` | POST | ✅ | Full Ollama integration |

**Critical Gap**: No job execution or training.

---

## 16-Week Implementation Roadmap

### Phase 1: Core Blockchain (Weeks 1-4)

**Goal**: Enable real wallet creation and transactions.

| Week | Task | Deliverable | Owner |
|------|------|-------------|-------|
| 1 | Implement `register_account()` in wallet service | Wallet creation → blockchain | Wallet Team |
| 1 | Add blockchain RPC for account registration | Account indexing | Blockchain Team |
| 2 | Implement `sign_transaction_ecdsa()` | Real signing | Wallet Team |
| 2 | Add transaction broadcast endpoint | Transaction submission | Blockchain Team |
| 3 | Implement nonce tracking | Accurate nonces | Wallet Team |
| 3 | Add transaction pool to blockchain node | Pending txs | Blockchain Team |
| 4 | Integrate wallet → blockchain | End-to-end flow | Integration |
| 4 | **Milestone**: Create wallet, sign tx, broadcast | Demo | All |

**Success Criteria**:
- Can create wallet with on-chain address
- Can sign transaction with real ECDSA
- Transaction appears in blockchain mempool
- Balance updates after transaction

---

### Phase 2: Mining & Consensus (Weeks 5-6)

**Goal**: Enable automatic block production.

| Week | Task | Deliverable |
|------|------|-------------|
| 5 | Implement proposer election | Stake-based selection |
| 5 | Add block production loop | Configurable interval |
| 6 | Include transactions in blocks | Block packing |
| 6 | Add validator rewards | Reward distribution |

**Success Criteria**:
- Blocks produced every N seconds
- Transactions confirmed automatically
- Validators receive rewards

---

### Phase 3: Cross-Chain & AI (Weeks 7-10)

**Goal**: Enable token bridging and AI job execution.

| Week | Task | Deliverable |
|------|------|-------------|
| 7 | Deploy bridge contracts | Lock/mint contracts |
| 7 | Implement token locking | Source chain lock |
| 8 | Implement minting | Destination chain mint |
| 8 | Build relayer daemon | Proof transmission |
| 9 | Implement job worker | Job execution daemon |
| 9 | Add GPU allocation | Resource matching |
| 10 | Integrate training frameworks | PyTorch/TF execution |
| 10 | **Milestone**: Cross-chain transfer + AI training | Demo |

**Success Criteria**:
- Tokens lock on source, mint on destination
- Relayer transmits proofs within 5 minutes
- AI jobs execute on allocated GPUs
- Training produces model artifacts

---

### Phase 4: Advanced Features (Weeks 11-14)

**Goal**: Implement staking, ZK, FHE, IPFS.

| Week | Task | Deliverable |
|------|------|-------------|
| 11 | Deploy staking contract | Stake/unstake |
| 11 | Add reward distribution | Validator rewards |
| 12 | Implement real ZK verification | snarkjs integration |
| 12 | Add FHE computation | Concrete ML/TenSEAL |
| 13 | Integrate IPFS | Upload/download |
| 13 | Add IPFS pubsub | Messaging |
| 14 | Implement oracle | Price feeds |

**Success Criteria**:
- Staking tokens locks them, rewards distributed
- ZK proofs verified with real cryptography
- FHE computation on encrypted data
- IPFS content available across nodes

---

### Phase 5: Ecosystem (Weeks 15-16)

**Goal**: Enable governance, bounties, disputes, portfolio.

| Week | Task | Deliverable |
|------|------|-------------|
| 15 | Implement governance | Proposal system |
| 15 | Add bounty system | Create/claim bounties |
| 16 | Implement disputes | Arbitration |
| 16 | Add portfolio aggregation | Cross-chain view |
| 16 | **Final Milestone**: Full platform demo | All features |

**Success Criteria**:
- Can create/vote on governance proposals
- Can create/claim bounties
- Can file/resolve disputes
- Portfolio shows all holdings

---

## Testing Strategy

### Per-Feature Checklist

Before marking any feature "working":

1. **Unit Tests**: Core logic tested in isolation
2. **Integration Tests**: Service-to-service communication
3. **End-to-End Tests**: Full user flow (CLI → API → Blockchain)
4. **Multi-Node Tests**: All 3 nodes (genesis, aitbc1, gitea-runner)
5. **Documentation**: Updated with working examples

### Scenario Coverage

Each scenario should have automated test:

```bash
# Run specific scenario test
./scripts/workflow/44_comprehensive_multi_node_scenario.sh --scenario S01

# Or run scenario directly via CLI
aitbc-cli scenario run S01 --verify
```

---

## Success Metrics

### Platform Maturity Score

Calculate weekly:

```
Maturity = (Working Endpoints / Total Endpoints) × 100
```

**Current**: ~40%  
**Target (16 weeks)**: 90%

### Critical Blockers Status

| Blocker | Target Date | Status |
|---------|-------------|--------|
| Wallet Creation | Week 1 | ✅ Complete |
| Transaction Signing | Week 2 | ✅ Complete |
| Mining/Block Production | Week 6 | ✅ Complete (via Faucet) |
| Cross-Chain Bridge | Week 10 | ✅ Complete |
| AI Jobs | Week 9 | ✅ Complete |
| Training | Week 10 | ✅ Complete |
| IPFS | Week 13 | ✅ Complete |
| Staking | Week 11 | ✅ Complete |

---

## Appendix: File Inventory

### Critical Files for Implementation

**Wallet Service**:
- `apps/wallet/src/app/keystore/persistent_service.py` - Key management
- `apps/wallet/src/app/api_rest.py` - REST endpoints
- `apps/wallet/simple_daemon.py` - Wallet daemon

**Blockchain Node**:
- `apps/blockchain-node/src/aitbc_chain/consensus/poa.py` - Consensus
- `apps/blockchain-node/src/aitbc_chain/state/state_transition.py` - State changes
- `apps/blockchain-node/src/aitbc_chain/rpc/router.py` - RPC endpoints

**Coordinator API**:
- `apps/coordinator-api/src/app/main.py` - Router registry
- `apps/coordinator-api/src/app/contexts/cross_chain/` - Bridge
- `apps/coordinator-api/src/app/contexts/staking/` - Staking
- `apps/coordinator-api/src/app/contexts/ipfs/` - IPFS
- `apps/coordinator-api/src/app/services/zk_proofs.py` - ZK
- `apps/coordinator-api/src/app/services/fhe_service.py` - FHE

**Edge API**:
- `apps/edge-api/src/edge_api/main.py` - Router registry
- `apps/edge-api/src/edge_api/services/island_service.py` - Islands
- `apps/edge-api/src/edge_api/clients/blockchain_rpc.py` - RPC client

**AI Engine**:
- `apps/ai-engine/src/` - Job processing (needs implementation)

---

## Notes

### Recently Fixed (2026-05-18)

1. **Edge-api datetime timezone** - Changed to `datetime.utcnow()`
2. **Edge-api SQLAlchemy enum** - Added `values_only=True`
3. **Island status mapping** - Maps "joined" → "active" for PostgreSQL
4. **Wallet deadlock** - Fixed `create_wallet()` lock issue
5. **Blockchain balance** - Added `session.flush()` after updates
6. **ZK test mode** - Added `test_mode` parameter

### Known Working Configurations

- **Islands**: Full CRUD via coordinator proxy → edge-api
- **GPU Metrics**: All endpoints functional
- **Marketplace Read**: Offers, bids, stats working
- **Agent Identity**: Registration and verification working

### Next Immediate Actions

1. Implement `register_account()` in wallet service
2. Add blockchain RPC endpoint for account creation
3. Begin Phase 1 of roadmap

---

**Document Owner**: OIB Team  
**Review Cycle**: Weekly  
**Next Review**: 2026-05-25