feat: Convert HTML documentation to markdown and add web format
- Convert all HTML documentation files to markdown format in /docs folder - Add markdown links to HTML documentation pages - Update all aitbc.io references to aitbc.bubuit.net - Create HTML web format versions of key documentation files - Update documentation index to show both HTML and web format options - Add flowchart documentation explaining CLI job submission process
This commit is contained in:
oib
488
website/docs/blockchain-node-md.html
Normal file
488
website/docs/blockchain-node-md.html
Normal file
@@ -0,0 +1,488 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Blockchain Node - AITBC Documentation</title>
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">
|
||||
<style>
|
||||
:root {
|
||||
--primary-color: #2563eb;
|
||||
--secondary-color: #1e40af;
|
||||
--success-color: #10b981;
|
||||
--warning-color: #f59e0b;
|
||||
--danger-color: #ef4444;
|
||||
--text-dark: #1f2937;
|
||||
--text-light: #6b7280;
|
||||
--bg-light: #f9fafb;
|
||||
--bg-white: #ffffff;
|
||||
--border-color: #e5e7eb;
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
|
||||
line-height: 1.6;
|
||||
color: var(--text-dark);
|
||||
background: var(--bg-white);
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.container {
|
||||
max-width: 1200px;
|
||||
margin: 0 auto;
|
||||
padding: 0 20px;
|
||||
}
|
||||
|
||||
header {
|
||||
background: var(--text-dark);
|
||||
color: white;
|
||||
padding: 1rem 0;
|
||||
position: sticky;
|
||||
top: 0;
|
||||
z-index: 100;
|
||||
}
|
||||
|
||||
nav {
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.logo {
|
||||
font-size: 1.5rem;
|
||||
font-weight: bold;
|
||||
color: white;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.nav-links {
|
||||
display: flex;
|
||||
gap: 2rem;
|
||||
list-style: none;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.nav-links a {
|
||||
color: white;
|
||||
text-decoration: none;
|
||||
transition: color 0.3s;
|
||||
}
|
||||
|
||||
.nav-links a:hover {
|
||||
color: var(--primary-color);
|
||||
}
|
||||
|
||||
.breadcrumb {
|
||||
padding: 1rem 0;
|
||||
color: var(--text-light);
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
.breadcrumb a {
|
||||
color: var(--text-light);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.breadcrumb a:hover {
|
||||
color: var(--primary-color);
|
||||
}
|
||||
|
||||
.doc-header {
|
||||
padding: 3rem 0;
|
||||
background: var(--bg-light);
|
||||
margin-bottom: 2rem;
|
||||
}
|
||||
|
||||
.doc-header h1 {
|
||||
font-size: 2.5rem;
|
||||
margin-bottom: 1rem;
|
||||
color: var(--text-dark);
|
||||
}
|
||||
|
||||
.doc-header p {
|
||||
font-size: 1.2rem;
|
||||
color: var(--text-light);
|
||||
max-width: 800px;
|
||||
}
|
||||
|
||||
.status-badge {
|
||||
display: inline-block;
|
||||
padding: 0.25rem 0.75rem;
|
||||
background: #10b98120;
|
||||
color: var(--success-color);
|
||||
border-radius: 20px;
|
||||
font-size: 0.875rem;
|
||||
font-weight: 600;
|
||||
margin-top: 1rem;
|
||||
}
|
||||
|
||||
.content-section {
|
||||
margin-bottom: 3rem;
|
||||
}
|
||||
|
||||
.content-section h2 {
|
||||
font-size: 1.8rem;
|
||||
margin-bottom: 1.5rem;
|
||||
color: var(--text-dark);
|
||||
border-bottom: 2px solid var(--border-color);
|
||||
padding-bottom: 0.5rem;
|
||||
}
|
||||
|
||||
.content-section h3 {
|
||||
font-size: 1.4rem;
|
||||
margin: 2rem 0 1rem;
|
||||
color: var(--text-dark);
|
||||
}
|
||||
|
||||
.content-section h4 {
|
||||
font-size: 1.2rem;
|
||||
margin: 1.5rem 0 0.5rem;
|
||||
color: var(--text-dark);
|
||||
}
|
||||
|
||||
.content-section p {
|
||||
margin-bottom: 1rem;
|
||||
color: var(--text-dark);
|
||||
}
|
||||
|
||||
.content-section ul {
|
||||
margin-bottom: 1rem;
|
||||
padding-left: 2rem;
|
||||
}
|
||||
|
||||
.content-section li {
|
||||
margin-bottom: 0.5rem;
|
||||
}
|
||||
|
||||
.feature-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
|
||||
gap: 1.5rem;
|
||||
margin: 2rem 0;
|
||||
}
|
||||
|
||||
.feature-card {
|
||||
background: var(--bg-white);
|
||||
padding: 1.5rem;
|
||||
border-radius: 8px;
|
||||
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
|
||||
}
|
||||
|
||||
.feature-card h4 {
|
||||
margin-top: 0;
|
||||
color: var(--primary-color);
|
||||
}
|
||||
|
||||
.api-endpoint {
|
||||
background: var(--bg-light);
|
||||
padding: 1rem;
|
||||
border-radius: 8px;
|
||||
margin: 1rem 0;
|
||||
border-left: 4px solid var(--primary-color);
|
||||
}
|
||||
|
||||
.api-endpoint code {
|
||||
display: block;
|
||||
font-weight: bold;
|
||||
margin-bottom: 0.5rem;
|
||||
color: var(--primary-color);
|
||||
}
|
||||
|
||||
pre {
|
||||
background: #1f2937;
|
||||
color: #f9fafb;
|
||||
padding: 1.5rem;
|
||||
border-radius: 8px;
|
||||
overflow-x: auto;
|
||||
margin: 1rem 0;
|
||||
}
|
||||
|
||||
code {
|
||||
font-family: 'Courier New', Courier, monospace;
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
pre code {
|
||||
background: none;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.back-button {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
color: var(--primary-color);
|
||||
text-decoration: none;
|
||||
margin-bottom: 2rem;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.back-button:hover {
|
||||
color: var(--secondary-color);
|
||||
}
|
||||
|
||||
footer {
|
||||
background: var(--text-dark);
|
||||
color: white;
|
||||
padding: 2rem 0;
|
||||
text-align: center;
|
||||
margin-top: 4rem;
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.nav-links {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.doc-header h1 {
|
||||
font-size: 2rem;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<nav class="container">
|
||||
<a href="../index.html" class="logo">AITBC</a>
|
||||
<ul class="nav-links">
|
||||
<li><a href="../index.html">Home</a></li>
|
||||
<li><a href="index.html">Documentation</a></li>
|
||||
<li><a href="mailto:aitbc@bubuit.net">Contact</a></li>
|
||||
</ul>
|
||||
</nav>
|
||||
</header>
|
||||
|
||||
<main>
|
||||
<div class="container">
|
||||
<!-- Breadcrumb -->
|
||||
<div class="breadcrumb">
|
||||
<a href="index.html">Documentation</a>
|
||||
<span>›</span>
|
||||
<a href="#">Components</a>
|
||||
<span>›</span>
|
||||
<span>Blockchain Node</span>
|
||||
</div>
|
||||
|
||||
<!-- Back Button -->
|
||||
<a href="components.html" class="back-button">
|
||||
<i class="fas fa-arrow-left"></i>
|
||||
Back to Components
|
||||
</a>
|
||||
|
||||
<!-- Header -->
|
||||
<div class="doc-header">
|
||||
<h1><i class="fas fa-cube"></i> Blockchain Node</h1>
|
||||
<p>PoA/PoS consensus blockchain with REST/WebSocket RPC, real-time gossip layer, and comprehensive observability</p>
|
||||
<span class="status-badge">● Live</span>
|
||||
</div>
|
||||
|
||||
<!-- Overview -->
|
||||
<section class="content-section">
|
||||
<h2>Overview</h2>
|
||||
<p>The AITBC Blockchain Node is the core infrastructure component that maintains the distributed ledger. It implements a hybrid Proof-of-Authority/Proof-of-Stake consensus mechanism with fast finality and supports high throughput for AI workload transactions.</p>
|
||||
|
||||
<h3>Key Features</h3>
|
||||
<ul>
|
||||
<li>Hybrid PoA/PoS consensus with sub-second finality</li>
|
||||
<li>REST and WebSocket RPC APIs</li>
|
||||
<li>Real-time gossip protocol for block propagation</li>
|
||||
<li>Comprehensive observability with Prometheus metrics</li>
|
||||
<li>SQLModel-based data persistence</li>
|
||||
<li>Built-in devnet tooling and scripts</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Architecture -->
|
||||
<section class="content-section">
|
||||
<h2>Architecture</h2>
|
||||
<p>The blockchain node is built with a modular architecture separating concerns for consensus, storage, networking, and API layers.</p>
|
||||
|
||||
<div class="feature-grid">
|
||||
<div class="feature-card">
|
||||
<h4>Consensus Engine</h4>
|
||||
<p>Hybrid PoA/PoS with proposer rotation and validator sets</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<h4>Storage Layer</h4>
|
||||
<p>SQLModel with SQLite/PostgreSQL support</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<h4>Networking</h4>
|
||||
<p>WebSocket gossip + REST API</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<h4>Observability</h4>
|
||||
<p>Prometheus metrics + structured logging</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- API Reference -->
|
||||
<section class="content-section">
|
||||
<h2>API Reference</h2>
|
||||
<p>The blockchain node exposes both REST and WebSocket APIs for interaction.</p>
|
||||
|
||||
<h3>REST Endpoints</h3>
|
||||
<div class="api-endpoint">
|
||||
<code>GET /rpc/get_head</code>
|
||||
<p>Get the latest block header</p>
|
||||
</div>
|
||||
|
||||
<div class="api-endpoint">
|
||||
<code>POST /rpc/send_tx</code>
|
||||
<p>Submit a new transaction</p>
|
||||
</div>
|
||||
|
||||
<div class="api-endpoint">
|
||||
<code>GET /rpc/get_balance/{address}</code>
|
||||
<p>Get account balance</p>
|
||||
</div>
|
||||
|
||||
<div class="api-endpoint">
|
||||
<code>GET /rpc/get_block/{height}</code>
|
||||
<p>Get block by height</p>
|
||||
</div>
|
||||
|
||||
<h3>WebSocket Subscriptions</h3>
|
||||
<ul>
|
||||
<li><code>new_blocks</code> - Real-time block notifications</li>
|
||||
<li><code>new_transactions</code> - Transaction pool updates</li>
|
||||
<li><code>consensus_events</code> - Consensus round updates</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Configuration -->
|
||||
<section class="content-section">
|
||||
<h2>Configuration</h2>
|
||||
<p>The node can be configured via environment variables or configuration file.</p>
|
||||
|
||||
<h3>Key Settings</h3>
|
||||
<pre><code># Database
|
||||
DATABASE_URL=sqlite:///blockchain.db
|
||||
|
||||
# Network
|
||||
RPC_HOST=0.0.0.0
|
||||
RPC_PORT=9080
|
||||
WS_PORT=9081
|
||||
|
||||
# Consensus
|
||||
CONSENSUS_MODE=poa
|
||||
VALIDATOR_ADDRESS=0x...
|
||||
BLOCK_TIME=1s
|
||||
|
||||
# Observability
|
||||
METRICS_PORT=9090
|
||||
LOG_LEVEL=info</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- Running a Node -->
|
||||
<section class="content-section">
|
||||
<h2>Running a Node</h2>
|
||||
|
||||
<h3>Development Mode</h3>
|
||||
<pre><code># Initialize devnet
|
||||
python -m blockchain.scripts.init_devnet
|
||||
|
||||
# Start node
|
||||
python -m blockchain.main --config devnet.yaml</code></pre>
|
||||
|
||||
<h3>Production Mode</h3>
|
||||
<pre><code># Using Docker
|
||||
docker run -d \
|
||||
-v /data/blockchain:/data \
|
||||
-p 9080:9080 \
|
||||
-p 9081:9081 \
|
||||
-p 9090:9090 \
|
||||
aitbc/blockchain-node:latest</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- Monitoring -->
|
||||
<section class="content-section">
|
||||
<h2>Monitoring</h2>
|
||||
|
||||
<h3>Prometheus Metrics</h3>
|
||||
<p>Available at <code>http://localhost:9090/metrics</code></p>
|
||||
|
||||
<p>Key metrics:</p>
|
||||
<ul>
|
||||
<li><code>blockchain_blocks_total</code> - Total blocks produced</li>
|
||||
<li><code>blockchain_transactions_total</code> - Total transactions processed</li>
|
||||
<li><code>blockchain_consensus_rounds</code> - Consensus rounds completed</li>
|
||||
<li><code>blockchain_network_peers</code> - Active peer connections</li>
|
||||
</ul>
|
||||
|
||||
<h3>Health Checks</h3>
|
||||
<pre><code># Node status
|
||||
curl http://localhost:9080/health
|
||||
|
||||
# Sync status
|
||||
curl http://localhost:9080/sync_status</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- Troubleshooting -->
|
||||
<section class="content-section">
|
||||
<h2>Troubleshooting</h2>
|
||||
|
||||
<h3>Common Issues</h3>
|
||||
<ol>
|
||||
<li><strong>Node not syncing</strong>
|
||||
<ul>
|
||||
<li>Check peer connections: <code>curl /rpc/peers</code></li>
|
||||
<li>Verify network connectivity</li>
|
||||
<li>Check logs for consensus errors</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>High memory usage</strong>
|
||||
<ul>
|
||||
<li>Reduce <code>block_cache_size</code> in config</li>
|
||||
<li>Enable block pruning</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>RPC timeouts</strong>
|
||||
<ul>
|
||||
<li>Increase <code>rpc_timeout</code> setting</li>
|
||||
<li>Check system resources</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
</section>
|
||||
|
||||
<!-- Development -->
|
||||
<section class="content-section">
|
||||
<h2>Development</h2>
|
||||
|
||||
<h3>Building from Source</h3>
|
||||
<pre><code>git clone https://github.com/aitbc/blockchain
|
||||
cd blockchain
|
||||
pip install -e .</code></pre>
|
||||
|
||||
<h3>Running Tests</h3>
|
||||
<pre><code># Unit tests
|
||||
pytest tests/
|
||||
|
||||
# Integration tests
|
||||
pytest tests/integration/</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- Security Considerations -->
|
||||
<section class="content-section">
|
||||
<h2>Security Considerations</h2>
|
||||
<ul>
|
||||
<li>Validator keys should be kept secure</li>
|
||||
<li>Use HTTPS in production</li>
|
||||
<li>Implement rate limiting on RPC endpoints</li>
|
||||
<li>Regular security updates for dependencies</li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
</main>
|
||||
|
||||
<footer>
|
||||
<div class="container">
|
||||
<p>© 2025 AITBC. All rights reserved.</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user