aitbc/docs/apps/mining/miner.md

Miner

Status

✅ Operational

Overview

Mining and block validation service for the AITBC blockchain using Proof-of-Authority consensus.

Architecture

Core Components

• Block Validator: Validates blocks from the network
• Block Proposer: Proposes new blocks (for authorized proposers)
• Transaction Validator: Validates transactions before inclusion
• Reward Claimer: Claims mining rewards
• Sync Manager: Manages blockchain synchronization

Quick Start (End Users)

Prerequisites

• Python 3.13+
• Access to blockchain RPC endpoint
• Valid proposer credentials (if proposing blocks)

Installation

cd /opt/aitbc/apps/miner
.venv/bin/pip install -r requirements.txt

Configuration

Set environment variables in .env:

BLOCKCHAIN_RPC_URL=http://localhost:8006
PROPOSER_ID=your-proposer-id
PROPOSER_PRIVATE_KEY=encrypted-key
MINING_ENABLED=true
VALIDATION_ENABLED=true

Running the Service

.venv/bin/python main.py

Developer Guide

Development Setup

1. Clone the repository
2. Create virtual environment: python -m venv .venv
3. Install dependencies: pip install -r requirements.txt
4. Configure blockchain RPC endpoint
5. Configure proposer credentials (if proposing)
6. Run tests: pytest tests/

Project Structure

miner/
├── src/
│   ├── block_validator/      # Block validation
│   ├── block_proposer/       # Block proposal
│   ├── transaction_validator/ # Transaction validation
│   ├── reward_claimer/       # Reward claiming
│   └── sync_manager/        # Sync management
├── tests/                   # Test suite
└── pyproject.toml           # Project configuration

Testing

# Run all tests
pytest tests/

# Run block validator tests
pytest tests/test_validator.py

# Run block proposer tests
pytest tests/test_proposer.py

API Reference

Block Validation

Validate Block

POST /api/v1/mining/validate/block
Content-Type: application/json

{
  "block": {},
  "chain_id": "ait-mainnet"
}

Get Validation Status

GET /api/v1/mining/validation/status

Block Proposal

Propose Block

POST /api/v1/mining/propose/block
Content-Type: application/json

{
  "chain_id": "ait-mainnet",
  "transactions": [{}],
  "timestamp": "2024-01-01T00:00:00Z"
}

Get Proposal Status

GET /api/v1/mining/proposal/status

Transaction Validation

Validate Transaction

POST /api/v1/mining/validate/transaction
Content-Type: application/json

{
  "transaction": {},
  "chain_id": "ait-mainnet"
}

Get Validation Queue

GET /api/v1/mining/validation/queue?limit=100

Reward Claiming

Claim Reward

POST /api/v1/mining/rewards/claim
Content-Type: application/json

{
  "block_height": 1000,
  "proposer_id": "string"
}

Get Reward History

GET /api/v1/mining/rewards/history?proposer_id=string

Sync Management

Get Sync Status

GET /api/v1/mining/sync/status

Trigger Sync

POST /api/v1/mining/sync/trigger
Content-Type: application/json

{
  "from_height": 1000,
  "to_height": 2000
}

Configuration

Environment Variables

• BLOCKCHAIN_RPC_URL: Blockchain RPC endpoint
• PROPOSER_ID: Proposer identifier
• PROPOSER_PRIVATE_KEY: Encrypted proposer private key
• MINING_ENABLED: Enable block proposal
• VALIDATION_ENABLED: Enable block validation
• SYNC_INTERVAL: Sync interval in seconds

Consensus Parameters

• Block Time: Time between blocks (default: 10s)
• Max Transactions: Maximum transactions per block
• Block Size: Maximum block size in bytes

Validation Rules

• Signature Validation: Validate block signatures
• Transaction Validation: Validate transaction format
• State Validation: Validate state transitions

Troubleshooting

Block validation failed: Check block signature and state transitions.

Proposal rejected: Verify proposer authorization and block validity.

Sync not progressing: Check blockchain RPC connectivity and network status.

Reward claim failed: Verify proposer ID and block height.

Security Notes

• Secure proposer private key storage
• Validate all blocks before acceptance
• Monitor for double-spending attacks
• Implement rate limiting for proposal
• Regularly audit mining operations
• Use secure key management