JSON-RPC API

ShardoChain exposes a full JSON-RPC 2.0 surface for transaction submission, state queries, and explorer endpoints. Two endpoints coexist: the Go API at :8545 (full-featured, public-facing) and the Rust node's embedded RPC at :8547 (direct mempool access, higher throughput).

Endpoints

Request format

curl -sm5 /rpc \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"shard_blockNumber","params":[]}'

# → {"jsonrpc":"2.0","id":1,"result":21089}

Transaction submission

shard_sendRawTransaction

Submit a single signed transaction (borsh-serialized hex string).

{"jsonrpc":"2.0","id":1,"method":"shard_sendRawTransaction",
 "params":["0x01a0…"]}

Returns: tx_hash (32-byte hex).

shard_sendRawTransactionBatch

Submit multiple TX in one call. Used by stress tools for high-TPS submission.

{"jsonrpc":"2.0","id":1,"method":"shard_sendRawTransactionBatch",
 "params":[["0xtx1…","0xtx2…","0xtx3…"]]}

Block queries

shard_blockNumber

Current chain tip (highest committed height).

shard_getBlockByNumber

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

Returns the block at height: header, transactions, receipts.

shard_getBlockByHash

{"jsonrpc":"2.0","id":1,"method":"shard_getBlockByHash",
 "params":["0xab…"]}

shard_getRecentBlockhash

Returns the most recent blockhash usable for recent_blockhash in a transaction (Solana-style stateless signing window).

Account queries

shard_getBalance

{"jsonrpc":"2.0","id":1,"method":"shard_getBalance",
 "params":["shard1abc…"]}

Returns balance in shardoshi (10^18 = 1 SHARD).

shard_getAccount

Full AccountState: balance, stake, delegated_stake, nonce.

shard_getTransactionCount

Returns the account's nonce (for sequenced TX flows; mostly informational).

Transaction queries

shard_getTransactionByHash

Returns the signed transaction by its 32-byte hash.

shard_getTransactionReceipt

Returns the execution receipt: status (Success/Reverted), gas_used, block_height, logs.

shard_getTransactionsByAddress

Paginated TX history for an address.

shard_getLogs

Filter contract logs by address, topic, block range. ETH-style.

Chain metadata

shard_chainId

Numeric chain identifier (currently 590 on testnet).

shard_getValidators

Active validator set for an epoch.

shard_getEpoch

Current epoch number and slot range.

shard_getFinality

Finality status: tip_height, attested_height, committed_height.

shard_syncStatus

Sync progress: syncing (bool), current_height, highest_known_height.

shard_getSupply

Returns aggregate balance, stake, delegated stake, total supply.

shard_getPruningInfo v5.1.6+

Reports the pruning configuration and the lowest-readable block:

{
  "mode": "archive",
  "lowest_block": 0,
  "current_height": 21089,
  "keep_blocks": 1000,
  "history_gap": 21088
}

Explorer endpoints (REST)

The Go API exposes additional endpoints for the block explorer UI:

• GET /api/v1/explorer/stats — aggregate chain stats (chain_id, tip, TPS, validators, total TX, finality)
• GET /api/v1/explorer/blocks?limit=20&before=H — paginated block list
• GET /api/v1/explorer/transactions?limit=N — recent TX
• GET /api/v1/explorer/accounts/{addr}/transactions — TX history per address
• GET /api/v1/explorer/search?q={hash|height|address} — universal search
• GET /api/v1/explorer/stream — SSE event stream (new blocks + TX)

Errors

Standard JSON-RPC 2.0 error codes plus ShardoChain-specific ones:

Rate limits

Defaults (configurable via env vars on the Go API):

• Per-IP: 200 req/s (burst 400) for query methods
• Per-IP: 50 req/s (burst 100) for sendRawTransaction*
• WebSocket: max 100 concurrent connections per IP

Validators bypass these limits (whitelist by node IP).