proxmox/rpc-translator-138/API_METHODS_SUPPORT.md

# Supported API Methods - RPC Translator 138

**Date**: 2026-01-05  
**References**: 
- [Besu Public Networks API](https://besu.hyperledger.org/public-networks/reference/api)
- [Besu Private Networks API](https://besu.hyperledger.org/private-networks/reference/api)

---

## Overview

The RPC Translator supports both **public network** and **private network** JSON-RPC API methods from Hyperledger Besu. All methods are passed through to the upstream Besu node(s), with the exception of `eth_sendTransaction` which is intercepted for signing.

---

## Public Network API Methods

All standard Ethereum JSON-RPC methods are supported and passed through to Besu:

### Standard Methods

- **`eth_*`**: Standard Ethereum methods
  - `eth_chainId`, `eth_getBalance`, `eth_blockNumber`
  - `eth_call`, `eth_getCode`, `eth_getStorageAt`
  - `eth_getTransactionReceipt`, `eth_getTransactionByHash`
  - `eth_getTransactionCount`, `eth_estimateGas`
  - `eth_gasPrice`, `eth_feeHistory`, `eth_maxPriorityFeePerGas`
  - `eth_getBlockByNumber`, `eth_getBlockByHash`
  - `eth_getLogs`, `eth_getBlockTransactionCountByNumber`
  - `eth_getBlockTransactionCountByHash`
  - `eth_getTransactionByBlockNumberAndIndex`
  - `eth_getTransactionByBlockHashAndIndex`
  - And other standard `eth_*` methods

- **`net_*`**: Network methods
  - `net_version`, `net_listening`, `net_peerCount`

- **`web3_*`**: Web3 utility methods
  - `web3_clientVersion`, `web3_sha3`

- **`eth_subscribe` / `eth_unsubscribe`**: WebSocket subscriptions
  - `newHeads`, `logs`, `newPendingTransactions`, `syncing`

---

## Private Network API Methods

Private network methods are **enabled by default** for ChainID 138 (private network):

### CLIQUE Methods (Proof of Authority)

- `clique_discard` - Discard a proposal to add/remove signer
- `clique_getSigners` - List signers for a block
- `clique_getSignerMetrics` - Get validator metrics
- `clique_getSignersAtHash` - List signers by block hash
- `clique_proposals` - Get current proposals
- `clique_propose` - Propose to add/remove signer

**Reference**: [Besu CLIQUE API](https://besu.hyperledger.org/private-networks/reference/api#clique-methods)

### IBFT 2.0 Methods

- `ibft_discardValidatorVote` - Discard a validator vote
- `ibft_getPendingVotes` - Get pending validator votes
- `ibft_getSignerMetrics` - Get validator metrics
- `ibft_getValidatorsByBlockHash` - Get validators by block hash
- `ibft_getValidatorsByBlockNumber` - Get validators by block number
- `ibft_proposeValidatorVote` - Propose to add/remove validator

**Reference**: [Besu IBFT 2.0 API](https://besu.hyperledger.org/private-networks/reference/api#ibft-20-methods)

### QBFT Methods

- `qbft_discardValidatorVote` - Discard a validator vote
- `qbft_getPendingVotes` - Get pending validator votes
- `qbft_getSignerMetrics` - Get validator metrics
- `qbft_getValidatorsByBlockHash` - Get validators by block hash
- `qbft_getValidatorsByBlockNumber` - Get validators by block number
- `qbft_proposeValidatorVote` - Propose to add/remove validator

**Reference**: [Besu QBFT API](https://besu.hyperledger.org/private-networks/reference/api#qbft-methods)

### PERM Methods (Permissioning)

- `perm_addAccountsToAllowlist` - Add accounts to allowlist
- `perm_addNodesToAllowlist` - Add nodes to allowlist
- `perm_getAccountsAllowlist` - Get accounts allowlist
- `perm_getNodesAllowlist` - Get nodes allowlist
- `perm_reloadPermissionsFromFile` - Reload permissions from file
- `perm_removeAccountsFromAllowlist` - Remove accounts from allowlist
- `perm_removeNodesFromAllowlist` - Remove nodes from allowlist

**Reference**: [Besu Permissioning API](https://besu.hyperledger.org/private-networks/reference/api#perm-permissioning-methods)

---

## Intercepted Methods

### `eth_sendTransaction`

**Status**: Intercepted and processed by the translator

**Behavior**:
1. Validates transaction (allowlist, chain ID, gas limits)
2. Fills missing fields (nonce, gas, fees)
3. Signs transaction via Web3Signer
4. Submits as `eth_sendRawTransaction` to Besu
5. Returns transaction hash

**Note**: The unsigned transaction is never sent to Besu. It is signed locally first.

---

## Denied Methods (Security)

The following methods are **denied** for security reasons:

### Admin Methods
- `admin_*` - All admin methods (node management)

### Debug Methods
- `debug_*` - All debug methods (tracing, inspection)

### Miner Methods
- `miner_*` - Miner control methods

### TxPool Methods
- `txpool_*` - Transaction pool inspection methods

---

## Configuration

### Enable/Disable Private Network Methods

Private network methods are **enabled by default**. To disable them, set in `.env`:

```bash
ALLOW_PRIVATE_NETWORK_METHODS=false
```

This will deny all `clique_*`, `ibft_*`, `qbft_*`, and `perm_*` methods.

---

## Method Routing

```
Client Request
    ↓
RPC Translator
    ↓
┌─────────────────────────────────────────┐
│ Method Check                            │
├─────────────────────────────────────────┤
│ Is denied? (admin_, debug_, etc.)      │ → Deny (Method not found)
│ Is intercepted? (eth_sendTransaction)  │ → Intercept & Sign
│ Is private network? (configurable)     │ → Pass through if enabled
│ Otherwise                               │ → Pass through to Besu
└─────────────────────────────────────────┘
    ↓
Besu Node(s)
```

---

## Examples

### Public Network Method

```bash
curl -X POST http://192.168.11.240:9545 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'
```

### Private Network Method (CLIQUE)

```bash
curl -X POST http://192.168.11.240:9545 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "clique_getSigners",
    "params": ["latest"],
    "id": 1
  }'
```

### Private Network Method (Permissioning)

```bash
curl -X POST http://192.168.11.240:9545 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "perm_getAccountsAllowlist",
    "params": [],
    "id": 1
  }'
```

### Intercepted Method

```bash
curl -X POST http://192.168.11.240:9545 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_sendTransaction",
    "params": [{
      "from": "0x...",
      "to": "0x...",
      "value": "0x0",
      "gas": "0x5208"
    }],
    "id": 1
  }'
```

---

## Enabling Private Network Methods in Besu

To use private network methods, ensure Besu is configured with:

```toml
# Enable CLIQUE API
rpc-http-api=["CLIQUE", "ETH", "NET", "WEB3"]

# Enable IBFT/QBFT API
rpc-http-api=["IBFT", "QBFT", "ETH", "NET", "WEB3"]

# Enable Permissioning API
rpc-http-api=["PERM", "ETH", "NET", "WEB3"]
```

See: [Besu API Documentation](https://besu.hyperledger.org/public-networks/reference/api)

---

## Testing

### Test Public Network Method

```bash
./scripts/test-rpc.sh 192.168.11.240 eth_chainId
```

### Test Private Network Method

```bash
curl -X POST http://192.168.11.240:9545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"clique_getSigners","params":["latest"],"id":1}'
```

---

## Summary

✅ **Public Network Methods**: Fully supported (all standard Ethereum methods)  
✅ **Private Network Methods**: Enabled by default (CLIQUE, IBFT, QBFT, PERM)  
✅ **Intercepted Methods**: `eth_sendTransaction` (signed automatically)  
❌ **Denied Methods**: `admin_*`, `debug_*`, `txpool_*`, `miner_*`  

**Configuration**: `ALLOW_PRIVATE_NETWORK_METHODS=true` (default) in `.env`