Implement RECEIPT_CLAIM transaction type

- Add status fields to Receipt model (status, claimed_at, claimed_by)
- Add RECEIPT_CLAIM handling to state_transition.py with validation and reward minting
- Add type field to Transaction model for reliable transaction type storage
- Update router to use TransactionRequest model to preserve type field
- Update poa.py to extract type from mempool transaction content and store only original payload
- Add RECEIPT_CLAIM to GasType enum with gas schedule

.windsurf/workflows/MULTI_NODE_MASTER_INDEX.md

@@ -435,7 +435,7 @@ Two-Node AITBC Blockchain:
 - Added quick reference commands and troubleshooting
 
 ### Previous Versions
-- **Monolithic Workflow**: `multi-node-blockchain-setup.md` (64KB, 2,098 lines)
+- **Archived Monolithic Workflow**: `archive/multi-node-blockchain-setup.md` (64KB, 2,098 lines)
 - **OpenClaw Integration**: `multi-node-blockchain-setup-openclaw.md`
 
 ## 🤝 Contributing

.windsurf/workflows/TEST_MASTER_INDEX.md

@@ -1,275 +0,0 @@
----
-description: Master index for AITBC testing workflows - links to all test modules and provides navigation
-title: AITBC Testing Workflows - Master Index
-version: 2.0 (100% Complete)
----
-
-# AITBC Testing Workflows - Master Index
-
-**Project Status**: ✅ **100% COMPLETED** (v0.3.0 - April 2, 2026)
-
-This master index provides navigation to all modules in the AITBC testing and debugging documentation. Each module focuses on specific aspects of testing and validation. All test workflows reflect the 100% project completion status with 100% test success rate achieved.
-
-## 🎉 **Testing Completion Status**
-
-### **✅ Test Results: 100% Success Rate**
-- **Production Monitoring Test**: ✅ PASSED
-- **Type Safety Test**: ✅ PASSED  
-- **JWT Authentication Test**: ✅ PASSED
-- **Advanced Features Test**: ✅ PASSED
-- **Overall Success Rate**: 100% (4/4 major test suites)
-
-### **✅ Test Coverage: All 9 Systems**
-1. **System Architecture**: ✅ Complete FHS compliance testing
-2. **Service Management**: ✅ Single marketplace service testing
-3. **Basic Security**: ✅ Secure keystore implementation testing
-4. **Agent Systems**: ✅ Multi-agent coordination testing
-5. **API Functionality**: ✅ 17/17 endpoints testing
-6. **Test Suite**: ✅ 100% test success rate validation
-7. **Advanced Security**: ✅ JWT auth and RBAC testing
-8. **Production Monitoring**: ✅ Prometheus metrics and alerting testing
-9. **Type Safety**: ✅ MyPy strict checking validation
-
----
-
-## 📚 Test Module Overview
-
-### 🔧 Basic Testing Module
-**File**: `test-basic.md`
-**Purpose**: Core CLI functionality and basic operations testing
-**Audience**: Developers, system administrators
-**Prerequisites**: None (base module)
-
-**Key Topics**:
-- CLI command testing
-- Basic blockchain operations
-- Wallet operations
-- Service connectivity
-- Basic troubleshooting
-
-**Quick Start**:
-```bash
-# Run basic CLI tests
-cd /opt/aitbc
-source venv/bin/activate
-python -m pytest cli/tests/ -v
-```
-
----
-
-### 🤖 OpenClaw Agent Testing Module
-**File**: `test-openclaw-agents.md`
-**Purpose**: OpenClaw agent functionality and coordination testing
-**Audience**: AI developers, system administrators
-**Prerequisites**: Basic Testing Module
-
-**Key Topics**:
-- Agent communication testing
-- Multi-agent coordination
-- Session management
-- Thinking levels
-- Agent workflow validation
-
-**Quick Start**:
-```bash
-# Test OpenClaw agents
-openclaw agent --agent GenesisAgent --session-id test --message "Test message" --thinking low
-openclaw agent --agent FollowerAgent --session-id test --message "Test response" --thinking low
-```
-
----
-
-### 🚀 AI Operations Testing Module
-**File**: `test-ai-operations.md`
-**Purpose**: AI job submission, processing, and resource management testing
-**Audience**: AI developers, system administrators
-**Prerequisites**: Basic Testing Module
-
-**Key Topics**:
-- AI job submission and monitoring
-- Resource allocation testing
-- Performance validation
-- AI service integration
-- Error handling and recovery
-
-**Quick Start**:
-```bash
-# Test AI operations
-./aitbc-cli ai submit --wallet genesis-ops --type inference --prompt "Test AI job" --payment 100
-./aitbc-cli ai status --job-id latest
-```
-
----
-
-### 🔄 Advanced AI Testing Module
-**File**: `test-advanced-ai.md`
-**Purpose**: Advanced AI capabilities including workflow orchestration and multi-model pipelines
-**Audience**: AI developers, system administrators
-**Prerequisites**: Basic Testing + AI Operations Modules
-
-**Key Topics**:
-- Advanced AI workflow orchestration
-- Multi-model AI pipelines
-- Ensemble management
-- Multi-modal processing
-- Performance optimization
-
-**Quick Start**:
-```bash
-# Test advanced AI operations
-./aitbc-cli ai submit --wallet genesis-ops --type parallel --prompt "Complex pipeline test" --payment 500
-./aitbc-cli ai submit --wallet genesis-ops --type multimodal --prompt "Multi-modal test" --payment 1000
-```
-
----
-
-### 🌐 Cross-Node Testing Module
-**File**: `test-cross-node.md`
-**Purpose**: Multi-node coordination, distributed operations, and node synchronization testing
-**Audience**: System administrators, network engineers
-**Prerequisites**: Basic Testing + AI Operations Modules
-
-**Key Topics**:
-- Cross-node communication
-- Distributed AI operations
-- Node synchronization
-- Multi-node blockchain operations
-- Network resilience testing
-
-**Quick Start**:
-```bash
-# Test cross-node operations
-ssh aitbc1 'cd /opt/aitbc && ./aitbc-cli blockchain info'
-./aitbc-cli resource status
-ssh aitbc1 'cd /opt/aitbc && ./aitbc-cli resource status'
-```
-
----
-
-### 📊 Performance Testing Module
-**File**: `test-performance.md`
-**Purpose**: System performance, load testing, and optimization validation
-**Audience**: Performance engineers, system administrators
-**Prerequisites**: All previous modules
-
-**Key Topics**:
-- Load testing
-- Performance benchmarking
-- Resource utilization analysis
-- Scalability testing
-- Optimization validation
-
-**Quick Start**:
-```bash
-# Run performance tests
-./aitbc-cli simulate blockchain --blocks 100 --transactions 1000 --delay 0
-./aitbc-cli resource allocate --agent-id perf-test --cpu 4 --memory 8192 --duration 3600
-```
-
----
-
-### 🛠️ Integration Testing Module
-**File**: `test-integration.md`
-**Purpose**: End-to-end integration testing across all system components
-**Audience**: QA engineers, system administrators
-**Prerequisites**: All previous modules
-
-**Key Topics**:
-- End-to-end workflow testing
-- Service integration validation
-- Cross-component communication
-- System resilience testing
-- Production readiness validation
-
-**Quick Start**:
-```bash
-# Run integration tests
-cd /opt/aitbc
-./scripts/workflow-openclaw/06_advanced_ai_workflow_openclaw.sh
-```
-
----
-
-## 🔄 Test Dependencies
-
-```
-test-basic.md (foundation)
-├── test-openclaw-agents.md (depends on basic)
-├── test-ai-operations.md (depends on basic)
-├── test-advanced-ai.md (depends on basic + ai-operations)
-├── test-cross-node.md (depends on basic + ai-operations)
-├── test-performance.md (depends on all previous)
-└── test-integration.md (depends on all previous)
-```
-
-## 🎯 Testing Strategy
-
-### Phase 1: Basic Validation
-1. **Basic Testing Module** - Verify core functionality
-2. **OpenClaw Agent Testing** - Validate agent operations
-3. **AI Operations Testing** - Confirm AI job processing
-
-### Phase 2: Advanced Validation
-4. **Advanced AI Testing** - Test complex AI workflows
-5. **Cross-Node Testing** - Validate distributed operations
-6. **Performance Testing** - Benchmark system performance
-
-### Phase 3: Production Readiness
-7. **Integration Testing** - End-to-end validation
-8. **Production Validation** - Production readiness confirmation
-
-## 📋 Quick Reference
-
-### 🚀 Quick Test Commands
-```bash
-# Basic functionality test
-./aitbc-cli --version && ./aitbc-cli blockchain info
-
-# OpenClaw agent test
-openclaw agent --agent GenesisAgent --session-id quick-test --message "Quick test" --thinking low
-
-# AI operations test
-./aitbc-cli ai submit --wallet genesis-ops --type inference --prompt "Quick test" --payment 50
-
-# Cross-node test
-ssh aitbc1 'cd /opt/aitbc && ./aitbc-cli blockchain info'
-
-# Performance test
-./aitbc-cli simulate blockchain --blocks 10 --transactions 50 --delay 0
-```
-
-### 🔍 Troubleshooting Quick Links
-- **[Basic Issues](test-basic.md#troubleshooting)** - CLI and service problems
-- **[Agent Issues](test-openclaw-agents.md#troubleshooting)** - OpenClaw agent problems
-- **[AI Issues](test-ai-operations.md#troubleshooting)** - AI job processing problems
-- **[Network Issues](test-cross-node.md#troubleshooting)** - Cross-node communication problems
-- **[Performance Issues](test-performance.md#troubleshooting)** - System performance problems
-
-## 📚 Related Documentation
-
-- **[Multi-Node Blockchain Setup](MULTI_NODE_MASTER_INDEX.md)** - System setup and configuration
-- **[CLI Documentation](../docs/CLI_DOCUMENTATION.md)** - Complete CLI reference
-- **[OpenClaw Agent Capabilities](../docs/openclaw/OPENCLAW_AGENT_CAPABILITIES_ADVANCED.md)** - Advanced agent features
-- **[GitHub Operations](github.md)** - Git operations and multi-node sync
-
-## 🎯 Success Metrics
-
-### Test Coverage Targets
-- **Basic Tests**: 100% core functionality coverage
-- **Agent Tests**: 95% agent operation coverage
-- **AI Tests**: 90% AI workflow coverage
-- **Performance Tests**: 85% performance scenario coverage
-- **Integration Tests**: 80% end-to-end scenario coverage
-
-### Quality Gates
-- **All Tests Pass**: 0 critical failures
-- **Performance Benchmarks**: Meet or exceed targets
-- **Resource Utilization**: Within acceptable limits
-- **Cross-Node Sync**: 100% synchronization success
-- **AI Operations**: 95%+ success rate
-
----
-
-**Last Updated**: 2026-03-30  
-**Version**: 1.0  
-**Status**: Ready for Implementation

.windsurf/workflows/aitbc-system-architecture-audit.md

@@ -162,6 +162,71 @@ echo "Tracked Runtime Files:"
 git ls-files | grep -E "(data/|config/|logs/|\.log|\.db)" || echo "✅ No tracked runtime files"
 ```
 
+#### 2.3 Node Identity Audit
+```bash
+# Audit unique node identities across all nodes
+echo "=== 5.5 NODE IDENTITY AUDIT ==="
+
+# Check aitbc node IDs
+echo "aitbc Node IDs:"
+grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env 2>/dev/null || echo "❌ Node ID files not found"
+
+# Check aitbc1 node IDs
+echo "aitbc1 Node IDs:"
+ssh aitbc1 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env' 2>/dev/null || echo "❌ aitbc1 node ID files not found"
+
+# Check gitea-runner node IDs
+echo "gitea-runner Node IDs:"
+ssh gitea-runner 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env' 2>/dev/null || echo "❌ gitea-runner node ID files not found"
+
+# Verify uniqueness
+echo "Uniqueness Verification:"
+AITBC_P2P=$(grep "^p2p_node_id=" /etc/aitbc/node.env 2>/dev/null | cut -d= -f2)
+AITBC1_P2P=$(ssh aitbc1 'grep "^p2p_node_id=" /etc/aitbc/node.env' 2>/dev/null | cut -d= -f2)
+GITEA_P2P=$(ssh gitea-runner 'grep "^p2p_node_id=" /etc/aitbc/node.env' 2>/dev/null | cut -d= -f2)
+
+DUPLICATE_COUNT=0
+if [ "$AITBC_P2P" == "$AITBC1_P2P" ] && [ -n "$AITBC_P2P" ]; then
+    echo "❌ Duplicate p2p_node_id between aitbc and aitbc1"
+    DUPLICATE_COUNT=$((DUPLICATE_COUNT + 1))
+fi
+if [ "$AITBC_P2P" == "$GITEA_P2P" ] && [ -n "$AITBC_P2P" ] && [ -n "$GITEA_P2P" ]; then
+    echo "❌ Duplicate p2p_node_id between aitbc and gitea-runner"
+    DUPLICATE_COUNT=$((DUPLICATE_COUNT + 1))
+fi
+if [ "$AITBC1_P2P" == "$GITEA_P2P" ] && [ -n "$AITBC1_P2P" ] && [ -n "$GITEA_P2P" ]; then
+    echo "❌ Duplicate p2p_node_id between aitbc1 and gitea-runner"
+    DUPLICATE_COUNT=$((DUPLICATE_COUNT + 1))
+fi
+
+if [ $DUPLICATE_COUNT -eq 0 ]; then
+    echo "✅ All node IDs are unique"
+else
+    echo "❌ Found $DUPLICATE_COUNT duplicate node ID(s)"
+    echo "Run remediation: python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py"
+fi
+```
+
+#### 2.4 P2P Network Configuration Audit
+```bash
+# Audit P2P network configuration
+echo "=== 5.6 P2P NETWORK CONFIGURATION AUDIT ==="
+
+# Check P2P service status
+echo "P2P Service Status:"
+systemctl status aitbc-blockchain-p2p.service --no-pager | grep -E "(Active|loaded)" || echo "❌ P2P service not found"
+ssh aitbc1 'systemctl status aitbc-blockchain-p2p.service --no-pager' | grep -E "(Active|loaded)" || echo "❌ aitbc1 P2P service not found"
+
+# Check for P2P handshake errors
+echo "P2P Handshake Errors:"
+journalctl -u aitbc-blockchain-p2p --no-pager | grep -c "invalid or self node_id" || echo "0 errors on aitbc"
+ssh aitbc1 'journalctl -u aitbc-blockchain-p2p --no-pager | grep -c "invalid or self node_id"' || echo "0 errors on aitbc1"
+
+# Verify P2P service uses p2p_node_id
+echo "P2P Service Configuration:"
+grep "node-id" /etc/systemd/system/aitbc-blockchain-p2p.service 2>/dev/null || echo "❌ P2P service not configured with node-id"
+```
+
 ### Phase 3: Path Rewire Operations
 **Objective**: Automatically rewire incorrect paths to system locations
 

.windsurf/workflows/blockchain-communication-test.md

@@ -215,6 +215,34 @@ ssh aitbc1 'systemctl restart aitbc-blockchain-p2p'
 ./aitbc-cli network status --verbose
 ```
 
+#### P2P Identity Conflict (Duplicate Node IDs)
+```bash
+# Check current node IDs on all nodes
+echo "=== aitbc node IDs ==="
+grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env
+
+echo "=== aitbc1 node IDs ==="
+ssh aitbc1 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env'
+
+echo "=== gitea-runner node IDs ==="
+ssh gitea-runner 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env'
+
+# Run unique ID generation on affected nodes
+python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py
+ssh aitbc1 'python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py'
+ssh gitea-runner 'python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py'
+
+# Restart P2P services on all nodes
+systemctl restart aitbc-blockchain-p2p
+ssh aitbc1 'systemctl restart aitbc-blockchain-p2p'
+ssh gitea-runner 'systemctl restart aitbc-blockchain-p2p'
+
+# Verify P2P connectivity
+journalctl -u aitbc-blockchain-p2p -n 30 --no-pager
+ssh aitbc1 'journalctl -u aitbc-blockchain-p2p -n 30 --no-pager'
+ssh gitea-runner 'journalctl -u aitbc-blockchain-p2p -n 30 --no-pager'
+```
+
 ## Success Criteria
 - Both nodes respond to health checks
 - Block heights match within 2 blocks

.windsurf/workflows/multi-node-blockchain-marketplace.md

@@ -180,6 +180,70 @@ DATA_SERVICE_ID=$(./aitbc-cli market search --query "data processing" | grep "se
 ./aitbc-cli market settle-payment --service-id $DATA_SERVICE_ID --amount 30 --wallet enterprise-1
 ```
 
+## Ollama GPU Provider Operations
+
+### Ollama GPU Provider Registration
+
+```bash
+# Register GPU provider with Ollama model support
+./aitbc-cli market create \
+    --type gpu-provider \
+    --price 100 \
+    --wallet gpu-provider \
+    --description "Ollama GPU inference with llama2, mistral, codellama support"
+
+# Register with specific model specifications
+./aitbc-cli provider register \
+    --name ollama-gpu-provider \
+    --gpu-model "NVIDIA RTX 4090" \
+    --gpu-count 1 \
+    --models "llama2,mistral,codellama,llama3.2:latest" \
+    --wallet gpu-provider
+
+# Verify provider registration
+./aitbc-cli provider status --provider-id "ollama-gpu-provider"
+```
+
+### Ollama GPU Provider Testing
+
+```bash
+# Test Ollama GPU inference with specific model
+./aitbc-cli ai submit --wallet test-wallet --type ollama \
+    --prompt "What is the capital of France?" \
+    --model "llama3.2:latest" \
+    --payment 50 \
+    --provider-id "ollama-gpu-provider"
+
+# Monitor Ollama job execution
+./aitbc-cli ai status --job-id "ollama_job_123"
+
+# Retrieve Ollama results
+./aitbc-cli ai results --job-id "ollama_job_123"
+
+# Test streaming Ollama responses
+./aitbc-cli ai submit --wallet test-wallet --type ollama-streaming \
+    --prompt "Generate a short story" \
+    --model "mistral" \
+    --payment 100 \
+    --provider-id "ollama-gpu-provider"
+```
+
+### GPU Provider Marketplace Operations
+
+```bash
+# List all registered GPU providers
+./aitbc-cli provider list --type gpu-provider
+
+# Check GPU provider availability
+./aitbc-cli provider availability --provider-id "ollama-gpu-provider"
+
+# Query GPU provider models
+./aitbc-cli provider models --provider-id "ollama-gpu-provider"
+
+# Compare GPU provider pricing
+./aitbc-cli provider pricing --type gpu-provider
+```
+
 ## GPU Provider Testing
 
 ### GPU Resource Allocation Testing

.windsurf/workflows/multi-node-blockchain-operations.md

@@ -101,6 +101,65 @@ ping -c 5 aitbc1
 ssh aitbc1 'ping -c 5 localhost'
 ```
 
+### Node Identity Verification
+
+```bash
+# Verify unique node IDs across all nodes
+echo "=== aitbc node IDs ==="
+grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env
+
+echo "=== aitbc1 node IDs ==="
+ssh aitbc1 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env'
+
+echo "=== gitea-runner node IDs ==="
+ssh gitea-runner 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env'
+
+# Check for duplicate IDs
+AITBC_P2P=$(grep "^p2p_node_id=" /etc/aitbc/node.env | cut -d= -f2)
+AITBC1_P2P=$(ssh aitbc1 'grep "^p2p_node_id=" /etc/aitbc/node.env | cut -d= -f2')
+
+if [ "$AITBC_P2P" == "$AITBC1_P2P" ]; then
+    echo "WARNING: Duplicate p2p_node_id detected!"
+    echo "Run: python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py"
+fi
+```
+
+### P2P Health Check
+
+```bash
+# Check P2P service status on all nodes
+systemctl status aitbc-blockchain-p2p.service --no-pager
+ssh aitbc1 'systemctl status aitbc-blockchain-p2p.service --no-pager'
+ssh gitea-runner 'systemctl status aitbc-blockchain-p2p.service --no-pager'
+
+# Verify P2P connectivity and peer connections
+journalctl -u aitbc-blockchain-p2p -n 30 --no-pager | grep -E "(peer|handshake|connected)"
+ssh aitbc1 'journalctl -u aitbc-blockchain-p2p -n 30 --no-pager | grep -E "(peer|handshake|connected)'
+
+# Check for P2P handshake rejections (duplicate IDs)
+journalctl -u aitbc-blockchain-p2p --no-pager | grep "invalid or self node_id"
+ssh aitbc1 'journalctl -u aitbc-blockchain-p2p --no-pager | grep "invalid or self node_id"
+```
+
+### Node Identity Remediation
+
+```bash
+# If duplicate IDs detected, run remediation
+python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py
+ssh aitbc1 'python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py'
+ssh gitea-runner 'python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py'
+
+# Restart P2P services on all nodes
+systemctl restart aitbc-blockchain-p2p
+ssh aitbc1 'systemctl restart aitbc-blockchain-p2p'
+ssh gitea-runner 'systemctl restart aitbc-blockchain-p2p'
+
+# Verify P2P connectivity after remediation
+sleep 5
+journalctl -u aitbc-blockchain-p2p -n 20 --no-pager
+ssh aitbc1 'journalctl -u aitbc-blockchain-p2p -n 20 --no-pager'
+```
+
 ## Troubleshooting Common Issues
 
 ### Service Issues

.windsurf/workflows/multi-node-blockchain-setup-core.md

@@ -46,6 +46,44 @@ The workflow uses the single central `/etc/aitbc/.env` file as the configuration
 - **Standard Location**: Config moved to `/etc/aitbc/` following system standards
 - **CLI Integration**: AITBC CLI tool uses this config file by default
 
+## Unique Node Identity Configuration
+
+Each node must have unique `proposer_id` and `p2p_node_id` for proper P2P network operation. The setup scripts automatically generate UUID-based IDs during initial setup.
+
+### Node Identity Files
+- `/etc/aitbc/.env` - Contains `proposer_id` for block signing and consensus
+- `/etc/aitbc/node.env` - Contains `p2p_node_id` for P2P network identity
+
+### Identity Generation Utility
+```bash
+# Generate or update unique node IDs (if missing or duplicate)
+python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py
+
+# Run on all nodes for remediation
+python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py
+ssh aitbc1 'python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py'
+ssh gitea-runner 'python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py'
+```
+
+### Verification
+```bash
+# Check node IDs are unique across all nodes
+echo "=== aitbc ==="
+grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env
+
+echo "=== aitbc1 ==="
+ssh aitbc1 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env'
+
+echo "=== gitea-runner ==="
+ssh gitea-runner 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env'
+```
+
+### P2P Identity Issues
+If nodes fail to connect due to duplicate IDs:
+1. Run the ID generation utility on affected nodes
+2. Restart P2P services: `systemctl restart aitbc-blockchain-p2p`
+3. Verify connectivity: `journalctl -u aitbc-blockchain-p2p -n 30`
+
 ## 🚨 Important: Genesis Block Architecture
 
 **CRITICAL**: Only the genesis authority node (aitbc) should have the genesis block!

.windsurf/workflows/multi-node-blockchain-setup-openclaw.md

@@ -75,6 +75,45 @@ python3 /tmp/aitbc1_heartbeat.py
 
 > All databases go in `/var/lib/aitbc/data/`, NOT in app directories.
 
+## Unique Node Identity Configuration
+
+Each node must have unique `proposer_id` and `p2p_node_id` for proper P2P network operation. The OpenClaw setup scripts automatically generate UUID-based IDs during initial setup.
+
+### Node Identity Files
+- `/etc/aitbc/.env` - Contains `proposer_id` for block signing and consensus
+- `/etc/aitbc/node.env` - Contains `p2p_node_id` for P2P network identity
+
+### Identity Generation Utility
+```bash
+# Generate or update unique node IDs (if missing or duplicate)
+python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py
+
+# Run on all nodes for remediation
+python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py
+ssh aitbc1 'python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py'
+ssh gitea-runner 'python3 /opt/aitbc/scripts/utils/generate_unique_node_ids.py'
+```
+
+### Verification
+```bash
+# Check node IDs are unique across all nodes
+echo "=== aitbc ==="
+grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env
+
+echo "=== aitbc1 ==="
+ssh aitbc1 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env'
+
+echo "=== gitea-runner ==="
+ssh gitea-runner 'grep -E "^(proposer_id|p2p_node_id)=" /etc/aitbc/.env /etc/aitbc/node.env'
+```
+
+### P2P Identity Issues
+If OpenClaw agents report P2P connection failures due to duplicate IDs:
+1. Run the ID generation utility on affected nodes
+2. Restart P2P services: `systemctl restart aitbc-blockchain-p2p`
+3. Verify connectivity: `journalctl -u aitbc-blockchain-p2p -n 30`
+4. Re-run OpenClaw agent coordination to confirm P2P connectivity
+
 ## Quick Start
 
 ### Full Deployment (Recommended)