Fukuii API Documentation¶

Welcome to the Fukuii JSON-RPC API documentation. This directory contains comprehensive documentation for interacting with Fukuii's JSON-RPC interface and planning for Model Context Protocol (MCP) integration.

📚 Documentation Index¶

Core API Documentation¶

Interactive API Reference 🆕
Fully browsable OpenAPI specification with Swagger UI
All 83 JSON-RPC endpoints with live examples
Organized by namespace with filtering
Try-it-out functionality for testing endpoints
Use this for: Exploring the API interactively, testing endpoints, integration planning
JSON-RPC API Reference
Complete reference for all JSON-RPC endpoints
Request/response examples for each method
Parameter descriptions and validation rules
Error codes and handling
Best practices for API usage
Use this for: Learning the API, integrating clients, reference lookup
RPC Endpoint Inventory 🆕
Comprehensive catalog of all 97 RPC endpoints
Organized by namespace with safety classifications
MCP coverage analysis
Production readiness indicators
Priority gaps for agent control
Use this for: Complete RPC endpoint reference, MCP planning
JSON-RPC Coverage Analysis
Comprehensive gap analysis vs Ethereum specification
Implementation status by namespace
Missing methods and their priority
EIP support status
Recommendations for completeness
Use this for: Understanding what's implemented, planning enhancements

MCP & Agent Control Documentation¶

MCP Analysis Summary 🆕
Executive summary of RPC inventory and MCP planning
Key findings and strategic recommendations
Security architecture overview
Implementation timeline and success metrics
Use this for: Understanding MCP strategy, stakeholder communication
MCP Enhancement Plan 🆕
Complete roadmap for agent-controlled node management
6-phase implementation plan (12-16 weeks)
45+ new tools, 20+ resources, 15+ prompts
Security considerations and acceptance criteria
Testing strategy and documentation requirements
Use this for: Implementing complete agent control, detailed planning
MCP Integration Guide
Architecture for Model Context Protocol server
Resource and tool definitions
Security considerations and authentication
Implementation roadmap
Deployment strategies
Use this for: Building AI integrations, planning MCP server development

Quick Links¶

Interactive API Reference - Browse all endpoints with Swagger UI
Insomnia Guide - How to use the Insomnia API collection
Maintaining API Reference - Guide for updating the API spec
Runbooks - Operational documentation
Documentation Home - Project overview and getting started

🎯 Quick Start¶

For Developers¶

Start Fukuii:
```
./bin/fukuii etc
```

Test the API:

curl -X POST http://localhost:8546 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_blockNumber",
    "params": []
  }'

Import Insomnia Workspace:
Open Insomnia
Import the Insomnia workspace from the repository root
Start exploring all 78 endpoints

For AI Integration¶

See MCP Integration Guide for building AI-powered blockchain tools using the Model Context Protocol.

📖 API Overview¶

Namespaces¶

Fukuii organizes JSON-RPC methods into namespaces:

Namespace	Endpoints	Purpose	Production Ready
ETH	52	Core blockchain operations	✅ Yes

| WEB3 | 2 | Utility methods | ✅ Yes | | NET | 9 | Network & peer management | ✅ Yes | | PERSONAL | 8 | Account management | ⚠️ Dev only | | DEBUG | 3 | Debugging and analysis | ⚠️ Use with caution | | QA | 3 | Testing utilities | ❌ Testing only | | CHECKPOINTING | 2 | ETC checkpointing | ✅ Yes (ETC specific) | | FUKUII | 1 | Custom extensions | ✅ Yes | | TEST | 7 | Test harness | ❌ Testing only | | IELE | 2 | IELE VM support | ⚠️ If IELE enabled | | MCP | 7 | Model Context Protocol | ✅ Yes | | RPC | 1 | RPC metadata | ✅ Yes | | TOTAL | 97 | All namespaces | Mixed |

Core Features¶

✅ Complete Coverage¶

All standard Ethereum JSON-RPC methods
Block queries and transactions
Account state and balances
Contract calls and gas estimation
Event logs and filtering
Mining operations

🔧 ETC Extensions¶

Raw transaction retrieval
Storage root queries
Checkpointing system
Account transaction history

🧪 Development Tools¶

Test chain manipulation
QA mining utilities
Debug peer information
Account management (personal namespace)

🔐 Security Considerations¶

Production Configuration¶

For production deployments:

Disable dangerous namespaces:

fukuii.network.rpc {
  http {
    apis = "eth,web3,net"  # Exclude personal, debug, test, qa
  }
}

Enable authentication:
Use reverse proxy (nginx, Caddy) for auth
Implement API key validation
Use firewall rules for IP whitelisting

Rate limiting:

fukuii.network.rpc {
  rate-limit {
    enabled = true
    min-request-interval = 100.milliseconds
  }
}

Use HTTPS/TLS:
Never expose RPC over plain HTTP
See TLS Operations Runbook

Method Safety¶

Safety Level	Namespaces	Notes
Safe	eth (read-only), web3, net	Always safe to expose
Restricted	eth (write ops)	Require authentication
Dangerous	personal, debug	Never expose publicly
Testing Only	test, qa	Disable in production

🚀 Common Use Cases¶

1. Query Latest Block¶

curl -X POST http://localhost:8546 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_blockNumber",
    "params": []
  }'

2. Get Account Balance¶

curl -X POST http://localhost:8546 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getBalance",
    "params": ["0xYourAddress", "latest"]
  }'

3. Call Smart Contract¶

curl -X POST http://localhost:8546 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_call",
    "params": [{
      "to": "0xContractAddress",
      "data": "0xFunctionSignature"
    }, "latest"]
  }'

4. Query Event Logs¶

curl -X POST http://localhost:8546 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getLogs",
    "params": [{
      "fromBlock": "0x0",
      "toBlock": "latest",
      "address": "0xContractAddress"
    }]
  }'

5. Send Raw Transaction¶

curl -X POST http://localhost:8546 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_sendRawTransaction",
    "params": ["0xSignedTransactionData"]
  }'

📊 API Performance¶

Response Times (Typical)¶

Operation	Average	95^th Percentile
Block queries	<10ms	<50ms
Transaction receipts	<10ms	<30ms
Account balance	<5ms	<20ms
Contract calls	<50ms	<200ms
Log queries (1000 blocks)	<100ms	<500ms
Gas estimation	<20ms	<100ms

Caching Strategy¶

Fukuii caches: - ✅ Historical blocks (immutable) - ✅ Transaction receipts (immutable) - ⚠️ Latest block (TTL: 30s) - ❌ Pending data (not cached)

🔧 Troubleshooting¶

Common Issues¶

1. Connection Refused¶

Error: connect ECONNREFUSED 127.0.0.1:8546

Solution: Ensure Fukuii is running and RPC is enabled:

fukuii.network.rpc {
  http {
    enabled = true
    interface = "127.0.0.1"
    port = 8546
  }
}

2. Method Not Found¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Solution: Check that the namespace is enabled in configuration:

fukuii.network.rpc {
  http {
    apis = "eth,web3,net,personal"  # Add required namespaces
  }
}

3. Rate Limited¶

Solution: Adjust rate limiting configuration or implement backoff in client:

async function callWithRetry(method, params, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await rpcCall(method, params);
    } catch (error) {
      if (error.code === -32005 && i < maxRetries - 1) {
        await sleep(1000 * (i + 1)); // Exponential backoff
      } else {
        throw error;
      }
    }
  }
}

📈 Monitoring¶

Health Checks¶

Fukuii provides built-in health check endpoints:

# Liveness (is server running?)
curl http://localhost:8546/health

# Readiness (is node synced and ready?)
curl http://localhost:8546/readiness

# Detailed health info
curl http://localhost:8546/healthcheck

See Metrics & Monitoring for comprehensive monitoring setup.

Key Metrics to Monitor¶

Sync Status: eth_syncing
Peer Count: net_peerCount
Latest Block: eth_blockNumber
Gas Price: eth_gasPrice
Chain ID: eth_chainId

🤝 Contributing¶

Found an issue or want to suggest an improvement? See our Contributing Guide.

Documentation Updates¶

When updating API documentation:

Update the relevant markdown file
Update the Insomnia workspace (insomnia_workspace.json in repository root) if adding/modifying endpoints
Regenerate the OpenAPI spec by running: python3 scripts/convert_insomnia_to_openapi.py
Update coverage analysis if implementation status changes
Test all examples and code snippets
Submit PR with clear description

Updating the Interactive API Reference¶

The interactive API reference is automatically generated from the Insomnia workspace:

# 1. Update insomnia_workspace.json with new/modified endpoints
# 2. Run the conversion script
python3 scripts/convert_insomnia_to_openapi.py

# 3. Verify the OpenAPI spec
python3 -c "import json; print(json.load(open('docs/api/openapi.json'))['info']['title'])"

# 4. Build and preview the docs
mkdocs serve
# Visit http://localhost:8000/api/interactive-api-reference/

📚 Additional Resources¶

Official Documentation¶

Tools & Libraries¶

JavaScript/TypeScript: ethers.js, web3.js
Python: web3.py
Go: go-ethereum (geth)
Rust: ethers-rs
Java: web3j

Community¶

📋 Changelog¶

2025-12-12¶

✅ Complete RPC endpoint inventory (97 endpoints cataloged)
✅ MCP analysis and enhancement plan created
✅ Identified MCP coverage gaps (7.2% → 85% target)
✅ 6-phase roadmap for agent-controlled node management
✅ Security architecture for multi-level access control

2025-11-24¶

✅ Created comprehensive API documentation
✅ Completed coverage analysis
✅ Added MCP integration guide
✅ Updated Insomnia workspace
✅ Documented all endpoints

Future Plans¶

Implement MCP Enhancement Plan (Phases 1-6)
Add 45+ new MCP tools for complete node control
Implement multi-level access control for agents
Add transaction tracing (debug namespace)
Add WebSocket subscription support
Implement GraphQL endpoint (optional)

Maintained by: Chippr Robotics LLC
Last Updated: 2025-11-24
License: Apache 2.0