# 🌍 AI Ledger - Global Decentralized AI-Powered Blockchain
> **Join the worldwide AI-powered consensus network instantly with a single command**
[](https://badge.fury.io/py/blockless-ai-ledger)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/netharalabs/blockless)
[](https://ailedger.network)
## 🚀 **Instant Global Network Participation**
```bash
# Install AI Ledger (macOS may require --break-system-packages)
pip3 install --break-system-packages blockless-ai-ledger
# Join the global network instantly
ailedger join --openai-key YOUR_KEY
# Or try demo mode first
ailedger join --demo
```
**Your node automatically connects to the worldwide AI Ledger network!** 🌍
## 🤖 What This Is
**AI Ledger** is a revolutionary distributed ledger that replaces blockchain mining with **AI-powered validation**:
- **🌍 Global Network**: Anyone worldwide can join with one command
- **🤖 AI Consensus**: GPT-4 validators replace energy-hungry miners
- **⚡ Instant Finality**: Transactions complete in 1-2 seconds globally
- **📝 Natural Language**: Submit transactions in plain English
- **🔒 Byzantine Secure**: 5-of-7 validator consensus across the planet
- **🌱 Zero Energy Waste**: No mining, no proof-of-work, environmentally friendly
## 🎯 Key Features
### 🧠 AI-Powered Consensus
- **Multiple AI Validators** independently evaluate each transaction
- **Risk Assessment** with explainable scoring (0.0 = safe, 1.0 = risky)
- **Quorum Decision** requires 5 of 7 validators to approve with low risk
- **Human Judgment** layer on top of deterministic rules
### ⚡ Production Ready
- **Battle-Tested Security**: Ed25519 signatures, domain separation, replay protection
- **Decimal Precision**: No floating-point errors, proper financial math
- **Comprehensive Validation**: Clock skew protection, rate limiting, nonce management
- **Durable Storage**: Checksummed logs with fsync guarantees
### 🔍 Transparency & Verification
- **Tamper-Evident Receipts**: Every transaction gets a cryptographic receipt
- **Merkle Trees**: Account state integrity with inclusion proofs
- **Full Audit Trail**: Every decision is logged and verifiable
- **Real-Time Monitoring**: Health checks, metrics, and observability
## 🚀 **Global Network Quick Start**
### **Prerequisites**
- **Python 3.11+**
- **OpenAI API key** (get one at [platform.openai.com](https://platform.openai.com/api-keys))
- **Internet connection** (for global network discovery)
- **2GB RAM** (recommended 4GB for production)
### **🌍 Join the Global Network (2 Steps)**
**Step 1: Install AI Ledger**
```bash
# On most systems
pip install blockless-ai-ledger
# On newer macOS systems
pip3 install --break-system-packages blockless-ai-ledger
```
**Step 2: Join the Worldwide Network**
```bash
# With your OpenAI API key (production mode)
ailedger join --openai-key sk-your-key-here
# Or demo mode first (no API key needed)
ailedger join --demo
```
**That's it!** Your node automatically:
- Discovers its public IP address
- Connects to the global AI Ledger network
- Finds other nodes worldwide using DHT + Gossip protocols
- Starts participating in global consensus
### **🎮 Try the Interactive Demo**
```bash
# No installation required - test locally
ailedger demo
# Or with real AI
export OPENAI_API_KEY="your-key"
ailedger demo --mode openai
```
### **🔍 Check Your Installation**
```bash
ailedger doctor # Health check
ailedger network stats # View global network
ailedger balance alice # Check account balance
```
### **📱 One-Line Global Deployment**
```bash
# Ultimate simplicity - works on any system with Python 3.11+
curl -sSL https://install.ailedger.network | bash
```
## 📖 Demo Walkthrough
The demo runs 5 realistic transactions and shows you exactly how AI validation works:
```bash
🚀 AI Ledger Demo
Mode: STUB
============================================================
🌍 Initial State:
alice 100.0 LABS (nonce=0, txs=0)
bob 0.0 LABS (nonce=0, txs=0)
treasury 900.0 LABS (nonce=0, txs=0)
💫 Demo Transactions
============================================================
Transaction 1: Normal Payment
📤 Submitting: Alice pays Bob 25 LABS for web design work
alice → bob: 25.0 LABS
✓ Accepted: abc123def456...
🤖 Validator Opinions:
✓ val001: Risk=0.15 █▌ Normal meal transaction
✓ val002: Risk=0.12 █▏ Valid transaction
✓ val003: Risk=0.18 █▊ Normal payment pattern
✅ APPROVED (5/7 validators, risk=0.150, time=1.2s)
📊 Final Results
============================================================
alice 75.0 LABS (nonce=1, txs=1)
bob 25.0 LABS (nonce=0, txs=1)
🎉 Demo completed successfully!
```
## 🏗️ Architecture Overview
```
User submits "Pay Bob $50" → Node → AI Validators → Quorum → Receipt
↓ ↓ ↓ ↓
Mempool AI+Rules Consensus Chain
```
### Core Components
1. **Transaction Layer**: Natural language transactions with comprehensive validation
2. **Validator Network**: AI-powered validators with fallback rule systems
3. **Quorum Manager**: Collects opinions and determines consensus
4. **Storage Engine**: Durable, checksummed append-only logs
5. **Account Manager**: Balance tracking with atomic operations
### Trust Model
Instead of proof-of-work:
1. **Transaction Submitted** in natural language to any node
2. **Multiple AI Validators** evaluate independently using rules + AI judgment
3. **Quorum Consensus** requires 5/7 validators to approve with average risk ≤0.25
4. **Tamper-Evident Receipt** created with cryptographic proofs
5. **Account State Updated** atomically with full audit trail
## 🛠️ Usage Examples
### Running a Node
```bash
# Start a node on port 8001 (OpenAI API key required!)
export OPENAI_API_KEY="your-key-here"
python3 -m ai_ledger.node --port 8001
# With custom log directory
export OPENAI_API_KEY="your-key-here"
python3 -m ai_ledger.node --port 8001 --log-dir ./my-logs
# Enable debug logging
export OPENAI_API_KEY="your-key-here"
python3 -m ai_ledger.node --port 8001 --log-level DEBUG
```
### Submit Transactions via API
```python
import httpx
async def send_payment():
async with httpx.AsyncClient() as client:
# Submit transaction
response = await client.post("http://localhost:8001/submit", json={
"nl_description": "Alice pays Bob 25 LABS for lunch",
"from_acct": "alice",
"to_acct": "bob",
"amount": "25.0",
"nonce": 1
})
tx_id = response.json()["transaction_id"]
print(f"Transaction submitted: {tx_id}")
# Wait for finality
while True:
receipt = await client.get(f"http://localhost:8001/receipt/{tx_id}")
if receipt.status_code == 200 and "receipt_id" in receipt.json():
print("Transaction finalized!")
break
await asyncio.sleep(1)
```
### Generate Validator Keys
```bash
# Generate 7 validators for production
python3 -m ai_ledger.keygen generate --count 7 --output-dir ./production-keys
# Verify generated keys
python3 -m ai_ledger.keygen verify --file ./production-keys/validators.json
```
### Verify System Integrity
```bash
# Check specific receipt
python3 -m ai_ledger.verify receipt abc123def456...
# Verify account chain integrity
python3 -m ai_ledger.verify account alice
# Full storage integrity check
python3 -m ai_ledger.verify storage-integrity
# Verify all recent receipts
python3 -m ai_ledger.verify all-receipts --limit 100
```
## 🔧 Configuration
### Environment Variables
```bash
# REQUIRED for production nodes and OpenAI mode
export OPENAI_API_KEY="your-openai-api-key"
# Optional configuration
export AI_LEDGER_LOG_LEVEL="INFO"
export AI_LEDGER_LOG_DIR="./logs"
export AI_LEDGER_PORT="8001"
```
### ⚠️ Important: OpenAI API Key Requirements
- **Demo Mode**: No API key needed for `python3 -m ai_ledger.demo`
- **Production Nodes**: OpenAI API key **REQUIRED** for `python3 -m ai_ledger.node`
- **Real Validation**: Without API key, nodes use stub/rule-only validation
- **Get API Key**: Sign up at [platform.openai.com](https://platform.openai.com/api-keys)
### Configuration Files
Edit `ai_ledger/params.py` to customize:
```python
# Consensus parameters
N_VALIDATORS = 7 # Number of validators
QUORUM_K = 5 # Required approvals
MAX_RISK_AVG = 0.25 # Maximum average risk score
# LLM configuration
LLM_MODE = "stub" # "openai", "stub", or "rule_only"
OPENAI_MODEL = "gpt-4-turbo-preview"
# Security settings
MAX_CLOCK_SKEW_SECS = 120
RATE_LIMIT_TPS = 10
```
## 🧪 Testing
Run the comprehensive test suite:
```bash
# Run all tests
python3 -m pytest
# Run specific test categories
python3 -m pytest ai_ledger/tests/test_canonical.py # Deterministic hashing
python3 -m pytest ai_ledger/tests/test_quorum.py # Consensus mechanics
python3 -m pytest ai_ledger/tests/test_replay.py # Replay protection
python3 -m pytest ai_ledger/tests/test_llm_safety.py # AI safety
# Run with coverage
python3 -m pytest --cov=ai_ledger --cov-report=html
```
### Test Coverage
- **Canonical JSON**: Deterministic serialization and hashing
- **Quorum Consensus**: Validator opinion collection and consensus rules
- **Replay Protection**: Nonce management and duplicate prevention
- **LLM Safety**: Prompt injection resistance and consistent behavior
- **Storage Integrity**: Checksum verification and corruption detection
## 📊 Monitoring & Observability
### Health Checks
```bash
curl http://localhost:8001/health
```
```json
{
"status": "healthy",
"uptime_seconds": 3600,
"components": {
"storage": {"status": "healthy", "stats": {...}},
"validators": {"status": "healthy", "eligible_validators": 5},
"accounts": {"status": "healthy", "account_count": 3}
}
}
```
### Metrics (Prometheus Compatible)
```bash
curl http://localhost:8001/metrics
```
```
# HELP transactions_submitted Total transactions submitted
# TYPE transactions_submitted counter
transactions_submitted 1250
# HELP avg_finality_time Average time to finality in seconds
# TYPE avg_finality_time gauge
avg_finality_time 1.234
```
### Debug Endpoints
```bash
# View mempool contents
curl http://localhost:8001/debug/mempool
# Get consensus parameters
curl http://localhost:8001/params
# Check account balances
curl http://localhost:8001/account/alice
```
## 🔐 Security Model
### Cryptographic Security
- **Ed25519 Signatures** for all validator opinions and receipts
- **Domain Separation** prevents cross-protocol signature reuse
- **Blake3 Hashing** for tamper-evident integrity
- **Merkle Trees** for efficient state verification
### Economic Security
- **Validator Reputation** system with automatic stake adjustment
- **Rate Limiting** prevents spam and DoS attacks
- **Nonce Management** prevents replay attacks
- **Clock Skew Protection** prevents timestamp manipulation
### AI Safety
- **Fail-Closed Design**: Errors result in transaction rejection
- **Prompt Injection Resistance**: Multiple layers of input sanitization
- **Deterministic Fallbacks**: Rule-only mode when AI unavailable
- **Multi-Validator Consensus**: No single AI can approve transactions
## 🎯 Production Deployment
### System Requirements
**Minimum**:
- 2 CPU cores
- 4GB RAM
- 10GB SSD storage
- 100 Mbps network
**Recommended**:
- 4 CPU cores
- 8GB RAM
- 50GB SSD storage
- 1 Gbps network
### Docker Deployment
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -e .
EXPOSE 8001
CMD ["python3", "-m", "ai_ledger.node", "--port", "8001", "--host", "0.0.0.0"]
```
```bash
# Build and run
docker build -t ai-ledger .
docker run -p 8001:8001 -v ./logs:/app/logs ai-ledger
```
### Kubernetes Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ai-ledger-node
spec:
replicas: 3
selector:
matchLabels:
app: ai-ledger
template:
metadata:
labels:
app: ai-ledger
spec:
containers:
- name: ai-ledger
image: ai-ledger:latest
ports:
- containerPort: 8001
env:
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: ai-ledger-secrets
key: openai-api-key
volumeMounts:
- name: logs
mountPath: /app/logs
```
## 🛣️ Roadmap
### Phase 1: Core System ✅
- [x] AI-powered transaction validation
- [x] Quorum consensus mechanism
- [x] Deterministic state management
- [x] Comprehensive test coverage
- [x] Production security features
### Phase 2: Network Layer 🚧
- [ ] Multi-node consensus protocol
- [ ] Network partition tolerance
- [ ] Validator discovery and selection
- [ ] Cross-node receipt verification
### Phase 3: Advanced Features 📋
- [ ] Multi-asset support (USD, EUR, BTC)
- [ ] Smart contract equivalent (AI-validated programs)
- [ ] Web dashboard and explorer
- [ ] Mobile SDK and wallet apps
- [ ] Enterprise integrations
### Phase 4: Scale & Optimize 📋
- [ ] Horizontal scaling (1000+ TPS)
- [ ] Advanced AI models (GPT-5, Claude-4)
- [ ] Zero-knowledge privacy features
- [ ] Cross-ledger interoperability
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone and install in development mode
git clone https://github.com/netharalabs/blockless.git
cd blockless
pip3 install -e ".[dev]"
# Run tests
python3 -m pytest
# Format code
black ai_ledger/
ruff ai_ledger/
# Type checking
mypy ai_ledger/
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **OpenAI** for GPT models that power our AI validators
- **NaCl/libsodium** for production-grade cryptography
- **Blake3** for high-performance hashing
- **FastAPI** for the modern web framework
- **Pydantic** for data validation and serialization
## 📞 Support & Community
- **Documentation**: [docs.ai-ledger.org](https://docs.ai-ledger.org)
- **Issues**: [GitHub Issues](https://github.com/netharalabs/blockless/issues)
- **Discussions**: [GitHub Discussions](https://github.com/netharalabs/blockless/discussions)
- **Discord**: [Join our community](https://discord.gg/ai-ledger)
---
**Built with ❤️ by the AI Ledger team**
*"The future of money is intelligent, transparent, and instant."*
Raw data
{
"_id": null,
"home_page": "https://github.com/netharalabs/blockless",
"name": "blockless-ai-ledger",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "blockchain, ai, distributed-ledger, cryptocurrency, validation, decentralized, global, consensus",
"author": "Nethara Labs",
"author_email": "Nethara Labs <contact@netharalabs.com>",
"download_url": "https://files.pythonhosted.org/packages/6c/37/02ba94f0c9d1d5c515c70d3455688bd0f38b5a6dee20023a9842e85b4736/blockless_ai_ledger-1.0.4.tar.gz",
"platform": "any",
"description": "# \ud83c\udf0d AI Ledger - Global Decentralized AI-Powered Blockchain\n\n> **Join the worldwide AI-powered consensus network instantly with a single command**\n\n[](https://badge.fury.io/py/blockless-ai-ledger)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/netharalabs/blockless)\n[](https://ailedger.network)\n\n## \ud83d\ude80 **Instant Global Network Participation**\n\n```bash\n# Install AI Ledger (macOS may require --break-system-packages)\npip3 install --break-system-packages blockless-ai-ledger\n\n# Join the global network instantly\nailedger join --openai-key YOUR_KEY\n\n# Or try demo mode first \nailedger join --demo\n```\n\n**Your node automatically connects to the worldwide AI Ledger network!** \ud83c\udf0d\n\n## \ud83e\udd16 What This Is\n\n**AI Ledger** is a revolutionary distributed ledger that replaces blockchain mining with **AI-powered validation**:\n\n- **\ud83c\udf0d Global Network**: Anyone worldwide can join with one command\n- **\ud83e\udd16 AI Consensus**: GPT-4 validators replace energy-hungry miners\n- **\u26a1 Instant Finality**: Transactions complete in 1-2 seconds globally\n- **\ud83d\udcdd Natural Language**: Submit transactions in plain English\n- **\ud83d\udd12 Byzantine Secure**: 5-of-7 validator consensus across the planet\n- **\ud83c\udf31 Zero Energy Waste**: No mining, no proof-of-work, environmentally friendly\n\n## \ud83c\udfaf Key Features\n\n### \ud83e\udde0 AI-Powered Consensus\n- **Multiple AI Validators** independently evaluate each transaction\n- **Risk Assessment** with explainable scoring (0.0 = safe, 1.0 = risky) \n- **Quorum Decision** requires 5 of 7 validators to approve with low risk\n- **Human Judgment** layer on top of deterministic rules\n\n### \u26a1 Production Ready\n- **Battle-Tested Security**: Ed25519 signatures, domain separation, replay protection\n- **Decimal Precision**: No floating-point errors, proper financial math\n- **Comprehensive Validation**: Clock skew protection, rate limiting, nonce management\n- **Durable Storage**: Checksummed logs with fsync guarantees\n\n### \ud83d\udd0d Transparency & Verification\n- **Tamper-Evident Receipts**: Every transaction gets a cryptographic receipt\n- **Merkle Trees**: Account state integrity with inclusion proofs\n- **Full Audit Trail**: Every decision is logged and verifiable\n- **Real-Time Monitoring**: Health checks, metrics, and observability\n\n## \ud83d\ude80 **Global Network Quick Start**\n\n### **Prerequisites**\n- **Python 3.11+** \n- **OpenAI API key** (get one at [platform.openai.com](https://platform.openai.com/api-keys))\n- **Internet connection** (for global network discovery)\n- **2GB RAM** (recommended 4GB for production)\n\n### **\ud83c\udf0d Join the Global Network (2 Steps)**\n\n**Step 1: Install AI Ledger**\n```bash\n# On most systems\npip install blockless-ai-ledger\n\n# On newer macOS systems \npip3 install --break-system-packages blockless-ai-ledger\n```\n\n**Step 2: Join the Worldwide Network**\n```bash\n# With your OpenAI API key (production mode)\nailedger join --openai-key sk-your-key-here\n\n# Or demo mode first (no API key needed)\nailedger join --demo\n```\n\n**That's it!** Your node automatically:\n- Discovers its public IP address\n- Connects to the global AI Ledger network\n- Finds other nodes worldwide using DHT + Gossip protocols\n- Starts participating in global consensus\n\n### **\ud83c\udfae Try the Interactive Demo**\n```bash\n# No installation required - test locally\nailedger demo\n\n# Or with real AI\nexport OPENAI_API_KEY=\"your-key\"\nailedger demo --mode openai\n```\n\n### **\ud83d\udd0d Check Your Installation**\n```bash\nailedger doctor # Health check\nailedger network stats # View global network \nailedger balance alice # Check account balance\n```\n\n### **\ud83d\udcf1 One-Line Global Deployment**\n```bash\n# Ultimate simplicity - works on any system with Python 3.11+\ncurl -sSL https://install.ailedger.network | bash\n```\n\n## \ud83d\udcd6 Demo Walkthrough\n\nThe demo runs 5 realistic transactions and shows you exactly how AI validation works:\n\n```bash\n\ud83d\ude80 AI Ledger Demo\nMode: STUB\n============================================================\n\n\ud83c\udf0d Initial State:\n alice 100.0 LABS (nonce=0, txs=0)\n bob 0.0 LABS (nonce=0, txs=0)\n treasury 900.0 LABS (nonce=0, txs=0)\n\n\ud83d\udcab Demo Transactions\n============================================================\n\nTransaction 1: Normal Payment\n \ud83d\udce4 Submitting: Alice pays Bob 25 LABS for web design work\n alice \u2192 bob: 25.0 LABS\n \u2713 Accepted: abc123def456...\n \ud83e\udd16 Validator Opinions:\n \u2713 val001: Risk=0.15 \u2588\u258c Normal meal transaction \n \u2713 val002: Risk=0.12 \u2588\u258f Valid transaction\n \u2713 val003: Risk=0.18 \u2588\u258a Normal payment pattern\n \u2705 APPROVED (5/7 validators, risk=0.150, time=1.2s)\n\n\ud83d\udcca Final Results\n============================================================\n alice 75.0 LABS (nonce=1, txs=1)\n bob 25.0 LABS (nonce=0, txs=1)\n\n\ud83c\udf89 Demo completed successfully!\n```\n\n## \ud83c\udfd7\ufe0f Architecture Overview\n\n```\nUser submits \"Pay Bob $50\" \u2192 Node \u2192 AI Validators \u2192 Quorum \u2192 Receipt\n \u2193 \u2193 \u2193 \u2193\n Mempool AI+Rules Consensus Chain\n```\n\n### Core Components\n\n1. **Transaction Layer**: Natural language transactions with comprehensive validation\n2. **Validator Network**: AI-powered validators with fallback rule systems\n3. **Quorum Manager**: Collects opinions and determines consensus \n4. **Storage Engine**: Durable, checksummed append-only logs\n5. **Account Manager**: Balance tracking with atomic operations\n\n### Trust Model\n\nInstead of proof-of-work:\n1. **Transaction Submitted** in natural language to any node\n2. **Multiple AI Validators** evaluate independently using rules + AI judgment \n3. **Quorum Consensus** requires 5/7 validators to approve with average risk \u22640.25\n4. **Tamper-Evident Receipt** created with cryptographic proofs\n5. **Account State Updated** atomically with full audit trail\n\n## \ud83d\udee0\ufe0f Usage Examples\n\n### Running a Node\n\n```bash\n# Start a node on port 8001 (OpenAI API key required!)\nexport OPENAI_API_KEY=\"your-key-here\"\npython3 -m ai_ledger.node --port 8001\n\n# With custom log directory\nexport OPENAI_API_KEY=\"your-key-here\"\npython3 -m ai_ledger.node --port 8001 --log-dir ./my-logs\n\n# Enable debug logging\nexport OPENAI_API_KEY=\"your-key-here\"\npython3 -m ai_ledger.node --port 8001 --log-level DEBUG\n```\n\n### Submit Transactions via API\n\n```python\nimport httpx\n\nasync def send_payment():\n async with httpx.AsyncClient() as client:\n # Submit transaction\n response = await client.post(\"http://localhost:8001/submit\", json={\n \"nl_description\": \"Alice pays Bob 25 LABS for lunch\",\n \"from_acct\": \"alice\", \n \"to_acct\": \"bob\",\n \"amount\": \"25.0\",\n \"nonce\": 1\n })\n \n tx_id = response.json()[\"transaction_id\"]\n print(f\"Transaction submitted: {tx_id}\")\n \n # Wait for finality\n while True:\n receipt = await client.get(f\"http://localhost:8001/receipt/{tx_id}\")\n if receipt.status_code == 200 and \"receipt_id\" in receipt.json():\n print(\"Transaction finalized!\")\n break\n await asyncio.sleep(1)\n```\n\n### Generate Validator Keys\n\n```bash\n# Generate 7 validators for production\npython3 -m ai_ledger.keygen generate --count 7 --output-dir ./production-keys\n\n# Verify generated keys\npython3 -m ai_ledger.keygen verify --file ./production-keys/validators.json\n```\n\n### Verify System Integrity\n\n```bash\n# Check specific receipt\npython3 -m ai_ledger.verify receipt abc123def456...\n\n# Verify account chain integrity \npython3 -m ai_ledger.verify account alice\n\n# Full storage integrity check\npython3 -m ai_ledger.verify storage-integrity\n\n# Verify all recent receipts\npython3 -m ai_ledger.verify all-receipts --limit 100\n```\n\n## \ud83d\udd27 Configuration\n\n### Environment Variables\n\n```bash\n# REQUIRED for production nodes and OpenAI mode\nexport OPENAI_API_KEY=\"your-openai-api-key\"\n\n# Optional configuration\nexport AI_LEDGER_LOG_LEVEL=\"INFO\"\nexport AI_LEDGER_LOG_DIR=\"./logs\"\nexport AI_LEDGER_PORT=\"8001\"\n```\n\n### \u26a0\ufe0f Important: OpenAI API Key Requirements\n\n- **Demo Mode**: No API key needed for `python3 -m ai_ledger.demo`\n- **Production Nodes**: OpenAI API key **REQUIRED** for `python3 -m ai_ledger.node`\n- **Real Validation**: Without API key, nodes use stub/rule-only validation\n- **Get API Key**: Sign up at [platform.openai.com](https://platform.openai.com/api-keys)\n\n### Configuration Files\n\nEdit `ai_ledger/params.py` to customize:\n\n```python\n# Consensus parameters\nN_VALIDATORS = 7 # Number of validators\nQUORUM_K = 5 # Required approvals\nMAX_RISK_AVG = 0.25 # Maximum average risk score\n\n# LLM configuration \nLLM_MODE = \"stub\" # \"openai\", \"stub\", or \"rule_only\"\nOPENAI_MODEL = \"gpt-4-turbo-preview\"\n\n# Security settings\nMAX_CLOCK_SKEW_SECS = 120\nRATE_LIMIT_TPS = 10\n```\n\n## \ud83e\uddea Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\npython3 -m pytest\n\n# Run specific test categories\npython3 -m pytest ai_ledger/tests/test_canonical.py # Deterministic hashing\npython3 -m pytest ai_ledger/tests/test_quorum.py # Consensus mechanics\npython3 -m pytest ai_ledger/tests/test_replay.py # Replay protection\npython3 -m pytest ai_ledger/tests/test_llm_safety.py # AI safety\n\n# Run with coverage\npython3 -m pytest --cov=ai_ledger --cov-report=html\n```\n\n### Test Coverage\n- **Canonical JSON**: Deterministic serialization and hashing\n- **Quorum Consensus**: Validator opinion collection and consensus rules\n- **Replay Protection**: Nonce management and duplicate prevention \n- **LLM Safety**: Prompt injection resistance and consistent behavior\n- **Storage Integrity**: Checksum verification and corruption detection\n\n## \ud83d\udcca Monitoring & Observability\n\n### Health Checks\n\n```bash\ncurl http://localhost:8001/health\n```\n\n```json\n{\n \"status\": \"healthy\",\n \"uptime_seconds\": 3600,\n \"components\": {\n \"storage\": {\"status\": \"healthy\", \"stats\": {...}},\n \"validators\": {\"status\": \"healthy\", \"eligible_validators\": 5},\n \"accounts\": {\"status\": \"healthy\", \"account_count\": 3}\n }\n}\n```\n\n### Metrics (Prometheus Compatible)\n\n```bash\ncurl http://localhost:8001/metrics\n```\n\n```\n# HELP transactions_submitted Total transactions submitted\n# TYPE transactions_submitted counter\ntransactions_submitted 1250\n\n# HELP avg_finality_time Average time to finality in seconds \n# TYPE avg_finality_time gauge\navg_finality_time 1.234\n```\n\n### Debug Endpoints\n\n```bash\n# View mempool contents\ncurl http://localhost:8001/debug/mempool\n\n# Get consensus parameters\ncurl http://localhost:8001/params\n\n# Check account balances\ncurl http://localhost:8001/account/alice\n```\n\n## \ud83d\udd10 Security Model\n\n### Cryptographic Security\n- **Ed25519 Signatures** for all validator opinions and receipts\n- **Domain Separation** prevents cross-protocol signature reuse\n- **Blake3 Hashing** for tamper-evident integrity\n- **Merkle Trees** for efficient state verification\n\n### Economic Security \n- **Validator Reputation** system with automatic stake adjustment\n- **Rate Limiting** prevents spam and DoS attacks \n- **Nonce Management** prevents replay attacks\n- **Clock Skew Protection** prevents timestamp manipulation\n\n### AI Safety\n- **Fail-Closed Design**: Errors result in transaction rejection\n- **Prompt Injection Resistance**: Multiple layers of input sanitization\n- **Deterministic Fallbacks**: Rule-only mode when AI unavailable\n- **Multi-Validator Consensus**: No single AI can approve transactions\n\n## \ud83c\udfaf Production Deployment\n\n### System Requirements\n\n**Minimum**:\n- 2 CPU cores\n- 4GB RAM \n- 10GB SSD storage\n- 100 Mbps network\n\n**Recommended**:\n- 4 CPU cores\n- 8GB RAM\n- 50GB SSD storage \n- 1 Gbps network\n\n### Docker Deployment\n\n```dockerfile\nFROM python:3.11-slim\n\nWORKDIR /app\nCOPY . .\nRUN pip install -e .\n\nEXPOSE 8001\nCMD [\"python3\", \"-m\", \"ai_ledger.node\", \"--port\", \"8001\", \"--host\", \"0.0.0.0\"]\n```\n\n```bash\n# Build and run\ndocker build -t ai-ledger .\ndocker run -p 8001:8001 -v ./logs:/app/logs ai-ledger\n```\n\n### Kubernetes Deployment\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: ai-ledger-node\nspec:\n replicas: 3\n selector:\n matchLabels:\n app: ai-ledger\n template:\n metadata:\n labels:\n app: ai-ledger\n spec:\n containers:\n - name: ai-ledger\n image: ai-ledger:latest\n ports:\n - containerPort: 8001\n env:\n - name: OPENAI_API_KEY\n valueFrom:\n secretKeyRef:\n name: ai-ledger-secrets\n key: openai-api-key\n volumeMounts:\n - name: logs\n mountPath: /app/logs\n```\n\n## \ud83d\udee3\ufe0f Roadmap\n\n### Phase 1: Core System \u2705\n- [x] AI-powered transaction validation\n- [x] Quorum consensus mechanism\n- [x] Deterministic state management\n- [x] Comprehensive test coverage\n- [x] Production security features\n\n### Phase 2: Network Layer \ud83d\udea7\n- [ ] Multi-node consensus protocol\n- [ ] Network partition tolerance\n- [ ] Validator discovery and selection\n- [ ] Cross-node receipt verification\n\n### Phase 3: Advanced Features \ud83d\udccb\n- [ ] Multi-asset support (USD, EUR, BTC)\n- [ ] Smart contract equivalent (AI-validated programs)\n- [ ] Web dashboard and explorer\n- [ ] Mobile SDK and wallet apps\n- [ ] Enterprise integrations\n\n### Phase 4: Scale & Optimize \ud83d\udccb\n- [ ] Horizontal scaling (1000+ TPS)\n- [ ] Advanced AI models (GPT-5, Claude-4)\n- [ ] Zero-knowledge privacy features\n- [ ] Cross-ledger interoperability\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone and install in development mode\ngit clone https://github.com/netharalabs/blockless.git\ncd blockless\npip3 install -e \".[dev]\"\n\n# Run tests\npython3 -m pytest\n\n# Format code \nblack ai_ledger/\nruff ai_ledger/\n\n# Type checking\nmypy ai_ledger/\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **OpenAI** for GPT models that power our AI validators\n- **NaCl/libsodium** for production-grade cryptography\n- **Blake3** for high-performance hashing\n- **FastAPI** for the modern web framework\n- **Pydantic** for data validation and serialization\n\n## \ud83d\udcde Support & Community\n\n- **Documentation**: [docs.ai-ledger.org](https://docs.ai-ledger.org)\n- **Issues**: [GitHub Issues](https://github.com/netharalabs/blockless/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/netharalabs/blockless/discussions)\n- **Discord**: [Join our community](https://discord.gg/ai-ledger)\n\n---\n\n**Built with \u2764\ufe0f by the AI Ledger team**\n\n*\"The future of money is intelligent, transparent, and instant.\"*\n",
"bugtrack_url": null,
"license": null,
"summary": "\ud83c\udf0d Global AI-powered blockchain - Join the worldwide decentralized network instantly",
"version": "1.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/netharalabs/blockless/issues",
"Documentation": "https://github.com/netharalabs/blockless",
"Homepage": "https://github.com/netharalabs/blockless",
"Source": "https://github.com/netharalabs/blockless"
},
"split_keywords": [
"blockchain",
" ai",
" distributed-ledger",
" cryptocurrency",
" validation",
" decentralized",
" global",
" consensus"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "76fd4e98a5c120ff3bcdc0f31b3cf7189f21426d7f53f02de954f63adb79a9ac",
"md5": "f2304f44a925712fa9de3e53e4287c82",
"sha256": "1776c2953bee8336dd0052742b967e795f0fb83321ea413ca6ddf6a3a02e0464"
},
"downloads": -1,
"filename": "blockless_ai_ledger-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f2304f44a925712fa9de3e53e4287c82",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 92091,
"upload_time": "2025-09-03T17:34:31",
"upload_time_iso_8601": "2025-09-03T17:34:31.664466Z",
"url": "https://files.pythonhosted.org/packages/76/fd/4e98a5c120ff3bcdc0f31b3cf7189f21426d7f53f02de954f63adb79a9ac/blockless_ai_ledger-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6c3702ba94f0c9d1d5c515c70d3455688bd0f38b5a6dee20023a9842e85b4736",
"md5": "3793e016c8e09fbaa30950297d6f45c2",
"sha256": "61520762b137f7d417172ca5a508cada4a4d153ba75c216a775be0895660bdae"
},
"downloads": -1,
"filename": "blockless_ai_ledger-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "3793e016c8e09fbaa30950297d6f45c2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 85770,
"upload_time": "2025-09-03T17:34:33",
"upload_time_iso_8601": "2025-09-03T17:34:33.027950Z",
"url": "https://files.pythonhosted.org/packages/6c/37/02ba94f0c9d1d5c515c70d3455688bd0f38b5a6dee20023a9842e85b4736/blockless_ai_ledger-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 17:34:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "netharalabs",
"github_project": "blockless",
"github_not_found": true,
"lcname": "blockless-ai-ledger"
}
JSON
