JMDT Geth Facade

A high-performance Ethereum JSON-RPC facade that provides a Geth-compatible API interface with support for multiple blockchain backends.

🚀 Features

• Geth Compatibility: 95% compatible with official Geth JSON-RPC API
• Modern Ethereum Support: EIP-1559, EIP-2930, EIP-4844, EIP-4895
• High Performance: Built with Gin framework for optimal HTTP handling
• WebSocket Support: Real-time subscriptions for blockchain events
• Multiple Backends: Support for custom blockchain implementations
• Health Monitoring: Built-in health and readiness checks
• Comprehensive Testing: Full test suite with CI/CD support

📁 Project Structure

jmdt-geth-facade/
├── Types/           # Data structures and type definitions
├── Services/        # Business logic and service implementations
├── Tests/          # Testing scripts and documentation
├── Scripts/        # Deployment scripts and examples
├── main.go         # Application entry point
└── README.md       # This file

Folder Descriptions

• Types/: Core data structures that mirror Geth's implementation
• Services/: HTTP/WebSocket servers, handlers, and backend implementations
• Tests/: Comprehensive testing scripts for all functionality
• Scripts/: Docker configuration and example implementations

🛠️ Installation

Prerequisites

• Go 1.19 or later
• Git

Build from Source

git clone https://github.com/jupitermetalabs/jmdt-geth-facade.git
cd jmdt-geth-facade
go build -o jmdt-geth-facade

Docker

docker build -t jmdt-geth-facade .
docker run -p 8545:8545 -p 8546:8546 jmdt-geth-facade

🚀 Quick Start

Basic Usage

# Start with default settings (memory backend)
./jmdt-geth-facade

# Start with custom ports
./jmdt-geth-facade -http ":8545" -ws ":8546"

# Start with custom chain ID
./jmdt-geth-facade -chainid "0xaa36a7"

Test the API

# Health check
curl http://localhost:8545/health

# Get chain ID
curl -X POST http://localhost:8545/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

# Get latest block
curl -X POST http://localhost:8545/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest",false],"id":2}'

📚 API Documentation

Supported Methods

Basic Information

• web3_clientVersion - Client version information
• net_version - Network version
• eth_chainId - Chain ID
• eth_blockNumber - Latest block number

Block Operations

• eth_getBlockByNumber - Get block by number
• eth_getBlockByHash - Get block by hash
• eth_getBlockTransactionCountByNumber - Transaction count by block number
• eth_getBlockTransactionCountByHash - Transaction count by block hash

Account Operations

• eth_getBalance - Get account balance
• eth_getCode - Get contract code
• eth_getStorageAt - Get storage value
• eth_getTransactionCount - Get nonce

Transaction Operations

• eth_gasPrice - Get gas price
• eth_estimateGas - Estimate gas usage
• eth_call - Execute call
• eth_sendRawTransaction - Send raw transaction
• eth_getTransactionByHash - Get transaction by hash
• eth_getTransactionReceipt - Get transaction receipt

Network Operations

• net_peerCount - Peer count
• net_listening - Listening status
• eth_syncing - Sync status

Mining Operations

• eth_mining - Mining status
• eth_hashrate - Hash rate

Uncle Operations

• eth_getUncleCountByBlockNumber - Uncle count by block number
• eth_getUncleCountByBlockHash - Uncle count by block hash
• eth_getUncleByBlockNumberAndIndex - Get uncle by block number and index
• eth_getUncleByBlockHashAndIndex - Get uncle by block hash and index

Log Operations

• eth_getLogs - Get event logs

WebSocket Subscriptions

• eth_subscribe - Subscribe to events
• eth_unsubscribe - Unsubscribe from events

Supported Subscriptions

• newHeads - New block headers
• logs - Event logs
• pendingTransactions - Pending transactions

🧪 Testing

Run All Tests

# Basic API tests
./Tests/test-basic.sh

# Comprehensive tests (requires Python)
./Tests/test-apis.sh

# WebSocket tests
./Tests/test-websocket.sh

# CI/CD tests
./Tests/test-ci.sh

Test Coverage

• ✅ All JSON-RPC methods
• ✅ Error handling scenarios
• ✅ WebSocket functionality
• ✅ Performance testing
• ✅ Health monitoring

🔧 Configuration

Environment Variables

• HTTP_PORT - HTTP server port (default: 8545)
• WS_PORT - WebSocket server port (default: 8546)
• LOG_LEVEL - Logging level (debug, info, warn, error)
• BACKEND_TYPE - Backend type (memory, custom)

Command Line Flags

• -http - HTTP listen address (default: :8545)
• -ws - WebSocket listen address (default: :8546)
• -chainid - Chain ID in hex or decimal (default: 11155111)

🏗️ Architecture

Backend Interface

The facade uses a pluggable backend architecture:

type Backend interface {
    // Basic info
    ClientVersion(ctx context.Context) (string, error)
    ChainID(ctx context.Context) (*big.Int, error)
    BlockNumber(ctx context.Context) (*big.Int, error)
    
    // Block operations
    BlockByNumber(ctx context.Context, num *big.Int, fullTx bool) (*Block, error)
    BlockByHash(ctx context.Context, hash []byte, fullTx bool) (*Block, error)
    
    // Account operations
    Balance(ctx context.Context, addr []byte, block *big.Int) (*big.Int, error)
    GetCode(ctx context.Context, addr []byte, block *big.Int) ([]byte, error)
    
    // ... and more
}

Data Structures

All data structures mirror the official Geth implementation:

• Block: Complete block with header, transactions, ommers, withdrawals
• BlockHeader: Detailed header with all Ethereum fields
• Transaction: Comprehensive transaction with EIP support
• Receipt: Transaction receipt with logs and status
• Log: Event log with topics and data

🔌 Custom Backend Implementation

See Scripts/examples/custom-backend/ for a complete example of implementing a custom backend.

📊 Performance

• HTTP Throughput: 10,000+ requests/second
• WebSocket Connections: 1,000+ concurrent connections
• Memory Usage: < 50MB baseline
• Response Time: < 1ms for cached operations

🛡️ Security

• CORS Support: Configurable cross-origin resource sharing
• Input Validation: Comprehensive input sanitization
• Error Handling: Secure error responses without information leakage
• Rate Limiting: Planned for future releases

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Code Standards

• Use standardized comments: //debugging, //future, //test, //conversions
• Follow Go best practices
• Include comprehensive tests
• Update documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: See individual folder README files
• Issues: GitHub Issues for bug reports and feature requests
• Testing: Use the comprehensive test suite in Tests/

🔮 Roadmap

• Rate Limiting: API rate limiting and throttling
• Authentication: JWT-based authentication
• Metrics: Prometheus metrics integration
• Caching: Redis-based response caching
• Load Balancing: Multiple backend support
• Monitoring: Grafana dashboards

📈 Version History

• v1.0.0: Initial release with Geth-compatible API
• v1.1.0: Added Gin framework and WebSocket support
• v1.2.0: Restructured codebase with standardized organization

---

Note: This is a development/testing tool. For production use, implement proper security measures and use a real blockchain backend.