oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 6 Packages Projects Releases Wiki Activity

docs: enhance Ollama GPU test workflow, reorganize project structure, and fix pytest warnings

Browse Source 
- Upgrade ollama-gpu-provider skill to v2.0 with complete test workflow documentation
- Add comprehensive troubleshooting, monitoring commands, and CI/CD integration examples
- Update client.py default coordinator port from 8000 to 18000
- Clear currentissue.md and add usage guidelines for issue tracking
- Create dev-utils/ directory and move aitbc-pythonpath.pth from root
- Create docs/guides/ and docs
This commit is contained in:
oib
2026-01-29 13:20:09 +01:00
parent ff4554b9dd
commit b9688dacf3
18 changed files with 1247 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
docs/currentissue.md
View File

@@ -1,100 +1,18 @@
# Current Issues
## Cross-Site Synchronization - PARTIALLY IMPLEMENTED
*No current issues to report.*
### Date
2026-01-29
---
### Status
**PARTIALLY IMPLEMENTED** - Cross-site sync is running on all nodes. Transaction propagation works. Block import endpoint exists but has a database constraint issue with transaction import.
## Usage Guidelines
### Description
Cross-site synchronization has been integrated into all blockchain nodes. The sync module detects height differences between nodes and can propagate transactions via RPC.
When tracking a new issue:
1. Add a new section with a descriptive title
2. Include the date and current status
3. Describe the issue, affected components, and any fixes attempted
4. Update status as progress is made
5. Once resolved, move this file to `docs/issues/` with a machine-readable name
### Components Affected
- `/src/aitbc_chain/main.py` - Main blockchain node process
- `/src/aitbc_chain/cross_site.py` - Cross-site sync module (implemented but not integrated)
- All three blockchain nodes (localhost Node 1 & 2, remote Node 3)
## Recent Resolved Issues
### What Was Fixed
1. **main.py integration**: Removed problematic `AbstractAsyncContextManager` type annotation and simplified the code structure
2. **Cross-site sync module**: Integrated into all three nodes and now starts automatically
3. **Config settings**: Added `cross_site_sync_enabled`, `cross_site_remote_endpoints`, `cross_site_poll_interval` inside the `ChainSettings` class
4. **URL paths**: Fixed RPC endpoint paths (e.g., `/head` instead of `/rpc/head` for remote endpoints that already include `/rpc`)
### Current Status
- **All nodes**: Running with cross-site sync enabled
- **Transaction sync**: Working - mempool transactions can propagate between sites
- **Block sync**: ✅ FULLY IMPLEMENTED - `/blocks/import` endpoint works with transactions
- **Height difference**: Nodes maintain independent chains (local: 771153, remote: 40324)
- **Status**: Block import with transactions now working after nginx routing fix
### Resolved Issues
Block synchronization transaction import issue has been **FIXED**:
- `/blocks/import` POST endpoint is functional and deployed on all nodes
- Endpoint validates block hashes, parent blocks, and prevents conflicts
- ✅ Can import blocks with and without transactions
- ✅ Transaction data properly saved to database
- Root cause: nginx was routing to wrong port (8082 instead of 8081)
- Fix: Updated nginx config to route to correct blockchain-rpc-2 service
### Block Sync Implementation Progress
1. **✅ Block Import Endpoint Created** - `/src/aitbc_chain/rpc/router.py`:
- Added `@router.post("/blocks/import")` endpoint
- Implemented block validation (hash, parent, existence checks)
- Added transaction and receipt import logic
- Returns status: "imported", "exists", or error details
2. **✅ Cross-Site Sync Updated** - `/src/aitbc_chain/sync/cross_site.py`:
- Modified `import_block()` to call `/rpc/blocks/import`
- Formats block data correctly for import
- Handles import success/failure responses
3. **✅ Runtime Error Fixed**:
- Moved inline imports (hashlib, datetime, config) to top of file
- Added proper error logging and exception handling
- Fixed indentation issues in the function
- Endpoint now returns proper validation responses
4. **✅ Transaction Import Fixed**:
- Root cause was nginx routing to wrong port (8082 instead of 8081)
- Updated transaction creation to use constructor with all fields
- Server rebooted to clear all caches
- Nginx config fixed to route to blockchain-rpc-2 on port 8081
- Verified transaction is saved correctly with all fields
5. **⏳ Future Enhancements**:
- Add proposer signature validation
- Implement fork resolution for conflicting chains
- Add authorized node list configuration
### What Works Now
- Cross-site sync loop runs every 10 seconds
- Remote endpoint polling detects height differences
- Transaction propagation between sites via mempool sync
- ✅ Block import endpoint functional with validation
- ✅ Blocks with and without transactions can be imported between sites via RPC
- ✅ Transaction data properly saved to database
- Logging shows sync activity in journalctl
### Files Modified
- `/src/aitbc_chain/main.py` - Added cross-site sync integration
- `/src/aitbc_chain/cross_site.py` - Fixed URL paths, updated to use /blocks/import endpoint
- `/src/aitbc_chain/config.py` - Added sync settings inside ChainSettings class (all nodes)
- `/src/aitbc_chain/rpc/router.py` - Added /blocks/import POST endpoint with validation
### Next Steps
1. **Monitor Block Synchronization**:
- Watch logs for successful block imports with transactions
- Verify cross-site sync is actively syncing block heights
- Monitor for any validation errors or conflicts
2. **Future Enhancements**:
- Add proposer signature validation for security
- Implement fork resolution for conflicting chains
- Add sync metrics and monitoring dashboard
**Status**: ✅ COMPLETE - Block import with transactions working
**Impact**: Full cross-site block synchronization now available
**Resolution**: Server rebooted, nginx routing fixed to port 8081
See `docs/issues/` for resolved issues and their solutions.

3
docs/developer/index.md
View File

@@ -32,7 +32,8 @@ Welcome to the AITBC developer documentation. This section contains resources fo
## Testing
- [Testing Guide](testing.md) - How to test your AITBC applications
- [Testing Guide](../guides/WINDSURF_TESTING_GUIDE.md) - Comprehensive testing with Windsurf
- [Test Setup](../guides/WINDSURF_TEST_SETUP.md) - Quick testing setup
- [Test Examples](../examples/) - Test code examples
## Deployment

33
docs/done.md
View File

@@ -406,3 +406,36 @@ This document tracks components that have been successfully deployed and are ope
- Updated `publicSignals` to `uint[1]` (1 public signal: receiptHash)
- Fixed authorization checks: `require(authorizedVerifiers[msg.sender])`
- Created `contracts/docs/ZK-VERIFICATION.md` with integration guide
### Recent Updates (2026-01-29)
- ✅ **Cross-Site Synchronization Issue Resolved**
- Fixed database foreign key constraint in transaction/receipt tables
- Updated import code to use block.id instead of block.height
- Applied database migration to all nodes
- Full details in: `docs/issues/2026-01-29_cross-site-sync-resolved.md`
- ✅ **Ollama GPU Provider Test Workflow**
- Complete end-to-end test from client submission to blockchain recording
- Created `/home/oib/windsurf/aitbc/home/test_ollama_blockchain.py`
- Updated skill: `.windsurf/skills/ollama-gpu-provider/SKILL.md` (v2.0)
- Created workflow: `.windsurf/workflows/ollama-gpu-test.md`
- Verified payment flow: Client → Miner (0.05206 AITBC for inference)
- ✅ **Issue Management Workflow**
- Created `.windsurf/workflows/issue-management.md`
- Established process for tracking and archiving resolved issues
- Moved resolved cross-site sync issue to `docs/issues/`
- ✅ **Pytest Warning Fixes**
- Fixed `PytestReturnNotNoneWarning` in `test_blockchain_nodes.py`
- Fixed `PydanticDeprecatedSince20` by migrating to V2 style validators
- Fixed `PytestUnknownMarkWarning` by moving `pytest.ini` to project root
- ✅ **Directory Organization**
- Created `docs/guides/` and moved 2 guide files from root
- Created `docs/reports/` and moved 10 report files from root
- Created `scripts/testing/` and moved 13 test scripts from root
- Created `dev-utils/` and moved `aitbc-pythonpath.pth`
- Updated `docs/files.md` with new structure
- Fixed systemd service path for GPU miner

42
docs/files.md
View File

@@ -5,7 +5,7 @@ This document categorizes all files and folders in the repository by their statu
- **Greylist (⚠️)**: Uncertain status, may need review
- **Blacklist (❌)**: Legacy, unused, outdated, candidates for removal
Last updated: 2026-01-26
Last updated: 2026-01-29
---
@@ -32,6 +32,7 @@ Last updated: 2026-01-26
| `scripts/deploy/` | ✅ Active | Deployment scripts |
| `scripts/service/` | ✅ Active | Service management |
| `scripts/dev_services.sh` | ✅ Active | Local development |
| `scripts/testing/` | ✅ Active | Test scripts (moved from root, 13 files) |
### Infrastructure (`infra/`, `systemd/`)
@@ -61,6 +62,8 @@ Last updated: 2026-01-26
| `docs/reference/components/miner_node.md` | ✅ Active | Miner documentation |
| `docs/reference/components/coordinator_api.md` | ✅ Active | API documentation |
| `docs/developer/integration/skills-framework.md` | ✅ Active | Skills documentation |
| `docs/guides/` | ✅ Active | Development guides (moved from root) |
| `docs/reports/` | ✅ Active | Generated reports (moved from root) |
### Cascade Skills (`.windsurf/`)
@@ -94,19 +97,32 @@ Last updated: 2026-01-26
|------|--------|-------|
| `plugins/ollama/` | ✅ Active | Ollama integration |
### Development Utilities (`dev-utils/`)
| Path | Status | Notes |
|------|--------|-------|
| `dev-utils/` | ✅ Active | Development utilities (newly created) |
| `dev-utils/aitbc-pythonpath.pth` | ✅ Active | Python path configuration |
### Data Directory (`data/`)
| Path | Status | Notes |
|------|--------|-------|
| `data/` | ✅ Active | Runtime data directory (gitignored) |
| `data/coordinator.db` | ⚠️ Runtime | SQLite database, moved from root |
### Root Files
| Path | Status | Notes |
|------|--------|-------|
| `README.md` | ✅ Active | Project readme |
| `README.md` | ✅ Active | Project readme, updated with new structure |
| `LICENSE` | ✅ Active | License file |
| `.gitignore` | ✅ Active | Recently updated (145 lines) |
| `pyproject.toml` | ✅ Active | Python project config |
| `.editorconfig` | ✅ Active | Editor config |
| `INTEGRATION_TEST_FIXES.md` | ✅ Active | Integration test fixes documentation |
| `INTEGRATION_TEST_UPDATES.md` | ✅ Active | Integration test real features implementation |
| `SKIPPED_TESTS_ROADMAP.md` | ✅ Active | Skipped tests roadmap status |
| `TEST_FIXES_COMPLETE.md` | ✅ Active | Complete test fixes summary |
| `pytest.ini` | ✅ Active | Pytest configuration with custom markers |
| `CLEANUP_SUMMARY.md` | ✅ Active | Documentation of directory cleanup |
| `test_block_import.py` | ⚠️ Duplicate | Recreated in root (exists in scripts/testing/) |
---
@@ -283,6 +299,15 @@ These empty folders are intentional scaffolding for planned future work per the
- Q2 2026: Infrastructure (`infra/terraform/`, `infra/helm/`)
- Q2 2026: Pool Hub components
5. **Directory Organization (2026-01-29)**:
- ✅ Created `docs/guides/` and moved 2 guide files from root
- ✅ Created `docs/reports/` and moved 10 report files from root
- ✅ Created `scripts/testing/` and moved 13 test scripts from root
- ✅ Created `dev-utils/` and moved `aitbc-pythonpath.pth`
- ✅ Moved `coordinator.db` to `data/` directory
- ✅ Updated README.md with new structure
- ✅ Created index README files for new directories
---
## Folder Structure Recommendation
@@ -297,13 +322,18 @@ aitbc/
│ └── zk-circuits/ # ✅ Keep
├── cli/ # ✅ CLI tools
├── docs/ # ✅ Markdown documentation
│ ├── guides/ # Development guides
│ └── reports/ # Generated reports
├── infra/ # ✅ Infrastructure configs
├── packages/ # ✅ Keep (aitbc-crypto, aitbc-sdk, aitbc-token)
├── plugins/ # ✅ Keep (ollama)
├── scripts/ # ✅ Keep - organized
│ └── testing/ # Test scripts
├── systemd/ # ✅ Keep
├── tests/ # ✅ Keep (e2e, integration, unit, security, load)
├── website/ # ✅ Keep
├── dev-utils/ # ✅ Development utilities
├── data/ # ✅ Runtime data (gitignored)
└── .windsurf/ # ✅ Keep
```

7
docs/guides/WINDSURF_TESTING_GUIDE.md
View File

@@ -26,9 +26,14 @@ This guide explains how to use Windsurf's integrated testing features with the A
### 4. Pytest Configuration
- ✅ `pyproject.toml` - Main configuration with markers
- ✅ `tests/pytest.ini` - Simplified for discovery
- ✅ `pytest.ini` - Moved to project root with custom markers
- ✅ `tests/conftest.py` - Fixtures with fallback mocks
### 5. Test Scripts (2026-01-29)
- ✅ `scripts/testing/` - All test scripts moved here
- ✅ `test_ollama_blockchain.py` - Complete GPU provider test
- ✅ `test_block_import.py` - Blockchain block import testing
## 🚀 How to Use
### Test Discovery

108
docs/issues/2026-01-29_cross-site-sync-resolved.md Normal file
View File

@@ -0,0 +1,108 @@
# Current Issues
## Cross-Site Synchronization - ✅ RESOLVED
### Date
2026-01-29
### Status
**FULLY IMPLEMENTED** - Cross-site sync is running on all nodes. Transaction propagation works. Block import endpoint works with transactions after database foreign key fix.
### Description
Cross-site synchronization has been integrated into all blockchain nodes. The sync module detects height differences between nodes and can propagate transactions via RPC.
### Components Affected
- `/src/aitbc_chain/main.py` - Main blockchain node process
- `/src/aitbc_chain/cross_site.py` - Cross-site sync module (implemented but not integrated)
- All three blockchain nodes (localhost Node 1 & 2, remote Node 3)
### What Was Fixed
1. **main.py integration**: Removed problematic `AbstractAsyncContextManager` type annotation and simplified the code structure
2. **Cross-site sync module**: Integrated into all three nodes and now starts automatically
3. **Config settings**: Added `cross_site_sync_enabled`, `cross_site_remote_endpoints`, `cross_site_poll_interval` inside the `ChainSettings` class
4. **URL paths**: Fixed RPC endpoint paths (e.g., `/head` instead of `/rpc/head` for remote endpoints that already include `/rpc`)
### Current Status
- **All nodes**: Running with cross-site sync enabled
- **Transaction sync**: Working - mempool transactions can propagate between sites
- **Block sync**: ✅ FULLY IMPLEMENTED - `/blocks/import` endpoint works with transactions
- **Height difference**: Nodes maintain independent chains (local: 771153, remote: 40324)
- **Status**: ✅ RESOLVED - Fixed database foreign key constraint issue (2026-01-29)
### Database Fix Applied (2026-01-29)
- **Issue**: Transaction and receipt tables had foreign key to `block.height` instead of `block.id`
- **Solution**:
1. Updated database schema to reference `block.id`
2. Fixed import code in `/src/aitbc_chain/rpc/router.py` to use `block.id`
3. Applied migration to existing databases
- **Result**: Block import with transactions now works correctly
### Resolved Issues
Block synchronization transaction import issue has been **FIXED**:
- `/blocks/import` POST endpoint is functional and deployed on all nodes
- Endpoint validates block hashes, parent blocks, and prevents conflicts
- ✅ Can import blocks with and without transactions
- ✅ Transaction data properly saved to database
- Root cause: nginx was routing to wrong port (8082 instead of 8081)
- Fix: Updated nginx config to route to correct blockchain-rpc-2 service
### Block Sync Implementation Progress
1. **✅ Block Import Endpoint Created** - `/src/aitbc_chain/rpc/router.py`:
- Added `@router.post("/blocks/import")` endpoint
- Implemented block validation (hash, parent, existence checks)
- Added transaction and receipt import logic
- Returns status: "imported", "exists", or error details
2. **✅ Cross-Site Sync Updated** - `/src/aitbc_chain/sync/cross_site.py`:
- Modified `import_block()` to call `/rpc/blocks/import`
- Formats block data correctly for import
- Handles import success/failure responses
3. **✅ Runtime Error Fixed**:
- Moved inline imports (hashlib, datetime, config) to top of file
- Added proper error logging and exception handling
- Fixed indentation issues in the function
- Endpoint now returns proper validation responses
4. **✅ Transaction Import Fixed**:
- Root cause was nginx routing to wrong port (8082 instead of 8081)
- Updated transaction creation to use constructor with all fields
- Server rebooted to clear all caches
- Nginx config fixed to route to blockchain-rpc-2 on port 8081
- Verified transaction is saved correctly with all fields
5. **⏳ Future Enhancements**:
- Add proposer signature validation
- Implement fork resolution for conflicting chains
- Add authorized node list configuration
### What Works Now
- Cross-site sync loop runs every 10 seconds
- Remote endpoint polling detects height differences
- Transaction propagation between sites via mempool sync
- ✅ Block import endpoint functional with validation
- ✅ Blocks with and without transactions can be imported between sites via RPC
- ✅ Transaction data properly saved to database
- Logging shows sync activity in journalctl
### Files Modified
- `/src/aitbc_chain/main.py` - Added cross-site sync integration
- `/src/aitbc_chain/cross_site.py` - Fixed URL paths, updated to use /blocks/import endpoint
- `/src/aitbc_chain/config.py` - Added sync settings inside ChainSettings class (all nodes)
- `/src/aitbc_chain/rpc/router.py` - Added /blocks/import POST endpoint with validation
### Next Steps
1. **Monitor Block Synchronization**:
- Watch logs for successful block imports with transactions
- Verify cross-site sync is actively syncing block heights
- Monitor for any validation errors or conflicts
2. **Future Enhancements**:
- Add proposer signature validation for security
- Implement fork resolution for conflicting chains
- Add sync metrics and monitoring dashboard
**Status**: ✅ COMPLETE - Block import with transactions working
**Impact**: Full cross-site block synchronization now available
**Resolution**: Server rebooted, nginx routing fixed to port 8081

4
docs/reference/index.md
View File

@@ -31,8 +31,8 @@ Welcome to the AITBC reference documentation. This section contains technical sp
## Project Documentation
- [Roadmap](roadmap.md) - Development roadmap
- [Completed Tasks](done.md) - List of completed features
- [Roadmap](../roadmap.md) - Development roadmap
- [Completed Tasks](../done.md) - List of completed features
- [Beta Release Plan](beta-release-plan.md) - Beta release planning
## Historical

21
docs/roadmap.md
View File

@@ -731,5 +731,26 @@ Current Status: Canonical receipt schema specification moved from `protocols/rec
| `docs/reference/specs/receipt-spec.md` finalize | Low | Q2 2026 | 🔄 Pending extensions |
| Cross-site synchronization | High | Q1 2026 | ✅ Complete (2026-01-29) |
## Recent Progress (2026-01-29)
### Testing Infrastructure
- **Ollama GPU Provider Test Workflow** ✅ COMPLETE
- End-to-end test from client submission to blockchain recording
- Payment processing verified (0.05206 AITBC for inference job)
- Created comprehensive test script and workflow documentation
### Code Quality
- **Pytest Warning Fixes** ✅ COMPLETE
- Fixed all pytest warnings (`PytestReturnNotNoneWarning`, `PydanticDeprecatedSince20`, `PytestUnknownMarkWarning`)
- Migrated Pydantic validators to V2 style
- Moved `pytest.ini` to project root with proper marker configuration
### Project Organization
- **Directory Cleanup** ✅ COMPLETE
- Reorganized root files into logical directories
- Created `docs/guides/`, `docs/reports/`, `scripts/testing/`, `dev-utils/`
- Updated documentation to reflect new structure
- Fixed GPU miner systemd service path
the canonical checklist during implementation. Mark completed tasks with ✅ and add dates or links to relevant PRs as development progresses.