Skip to main content

RPC API

Orbinum exposes both Substrate and Ethereum-compatible JSON-RPC interfaces.

Table of Contents​

Connection​

Endpoints​

ProtocolDefault PortURL
WebSocket9944ws://localhost:9944
HTTP9944http://localhost:9944

Request Format​

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "method_name",
    "params": []
}

Response Format​

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "..."
}

Substrate RPC​

Standard Substrate RPC methods.

system​

system_health​

Check node health status.

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

Response:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "peers": 5,
        "isSyncing": false,
        "shouldHavePeers": true
    }
}

system_chain​

Get chain name.

{
    "method": "system_chain",
    "params": []
}
// Result: "Orbinum"

system_version​

Get node version.

{
    "method": "system_version",
    "params": []
}
// Result: "0.1.0"

system_properties​

Get chain properties.

{
    "method": "system_properties",
    "params": []
}
// Result: {"tokenSymbol": "ORB", "tokenDecimals": 18}

chain​

chain_getBlockHash​

Get block hash by number.

{
    "method": "chain_getBlockHash",
    "params": [100]
}
// Result: "0x1234..."

chain_getBlock​

Get block by hash.

{
    "method": "chain_getBlock",
    "params": ["0x1234..."]
}

chain_getHeader​

Get block header.

{
    "method": "chain_getHeader",
    "params": ["0x1234..."]
}

chain_getFinalizedHead​

Get latest finalized block hash.

{
    "method": "chain_getFinalizedHead",
    "params": []
}

state​

state_getStorage​

Query storage at a key.

{
    "method": "state_getStorage",
    "params": ["0x1234...", null]
}

state_getRuntimeVersion​

Get runtime version.

{
    "method": "state_getRuntimeVersion",
    "params": []
}

author​

author_submitExtrinsic​

Submit a signed transaction.

{
    "method": "author_submitExtrinsic",
    "params": ["0x...signed_extrinsic..."]
}

author_pendingExtrinsics​

List pending transactions.

{
    "method": "author_pendingExtrinsics",
    "params": []
}

Ethereum RPC​

Full Ethereum JSON-RPC compatibility via Frontier.

eth​

eth_chainId​

Get chain ID.

{
    "method": "eth_chainId",
    "params": []
}
// Result: "0x1234"

eth_blockNumber​

Get latest block number.

{
    "method": "eth_blockNumber",
    "params": []
}
// Result: "0x64" (100)

eth_getBalance​

Get account balance.

{
    "method": "eth_getBalance",
    "params": ["0x1234...", "latest"]
}
// Result: "0xde0b6b3a7640000" (1 ETH in wei)

eth_getTransactionCount​

Get account nonce.

{
    "method": "eth_getTransactionCount",
    "params": ["0x1234...", "latest"]
}
// Result: "0x5"

eth_sendRawTransaction​

Submit raw transaction.

{
    "method": "eth_sendRawTransaction",
    "params": ["0x...rlp_encoded_tx..."]
}
// Result: "0x...transaction_hash..."

eth_call​

Execute contract call (read-only).

{
    "method": "eth_call",
    "params": [{
        "to": "0x1234...",
        "data": "0x..."
    }, "latest"]
}

eth_estimateGas​

Estimate gas for transaction.

{
    "method": "eth_estimateGas",
    "params": [{
        "to": "0x1234...",
        "data": "0x..."
    }]
}
// Result: "0x5208" (21000)

eth_getTransactionReceipt​

Get transaction receipt.

{
    "method": "eth_getTransactionReceipt",
    "params": ["0x...tx_hash..."]
}

Response includes:

  • status: 0x1 (success) or 0x0 (failure)
  • gasUsed: Gas consumed
  • logs: Event logs

eth_getLogs​

Get logs matching filter.

{
    "method": "eth_getLogs",
    "params": [{
        "fromBlock": "0x1",
        "toBlock": "latest",
        "address": "0x1234...",
        "topics": ["0x...event_signature..."]
    }]
}

net​

net_version​

Get network ID.

{
    "method": "net_version",
    "params": []
}

net_listening​

Check if node is listening.

{
    "method": "net_listening",
    "params": []
}
// Result: true

net_peerCount​

Get connected peer count.

{
    "method": "net_peerCount",
    "params": []
}
// Result: "0x5"

web3​

web3_clientVersion​

Get client version.

{
    "method": "web3_clientVersion",
    "params": []
}
// Result: "Orbinum/v0.1.0"

debug​

Requires Flag

Debug methods require --ethapi=debug flag.

debug_traceTransaction​

Trace transaction execution.

{
    "method": "debug_traceTransaction",
    "params": ["0x...tx_hash...", {}]
}

txpool​

Requires Flag

Txpool methods require --ethapi=txpool flag.

txpool_status​

Get transaction pool status.

{
    "method": "txpool_status",
    "params": []
}
// Result: {"pending": "0x5", "queued": "0x2"}

Custom RPC​

Orbinum-specific RPC methods.

shieldedPool​

WIP

Custom RPC methods are under development.

shieldedPool_getMerkleRoot​

Get current Merkle root.

{
    "method": "shieldedPool_getMerkleRoot",
    "params": []
}
// Result: "0x..."

shieldedPool_getPoolBalance​

Get total shielded balance.

{
    "method": "shieldedPool_getPoolBalance",
    "params": []
}
// Result: "1000000000000000000"

shieldedPool_getNullifierStatus​

Check if nullifier is spent.

{
    "method": "shieldedPool_getNullifierStatus",
    "params": ["0x...nullifier..."]
}
// Result: true/false

zkVerifier​

zkVerifier_getCircuitInfo​

Get circuit metadata.

{
    "method": "zkVerifier_getCircuitInfo",
    "params": [1]
}
// Result: {"name": "transfer", "publicInputs": 5, ...}

WebSocket Subscriptions​

Subscribe to New Heads​

const ws = new WebSocket('ws://localhost:9944');

ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'chain_subscribeNewHeads',
    params: []
}));

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.method === 'chain_newHead') {
        console.log('New block:', data.params.result);
    }
};

Subscribe to Logs (Ethereum)​

ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_subscribe',
    params: ['logs', {
        address: '0x1234...'
    }]
}));

Error Codes​

CodeMessageDescription
-32700Parse errorInvalid JSON
-32600Invalid RequestInvalid request object
-32601Method not foundUnknown method
-32602Invalid paramsInvalid parameters
-32603Internal errorInternal server error