Grove API Definition

Web Protocols

JSON-RPC

The Grove API supports all blockchains that use the JSON-RPC 2.0 Specification.

Example request using curl:

curl https://xrplevm.rpc.grove.city/v1/$GROVE_PORTAL_APP_ID \
 -X POST \
 -H 'Authorization: $GROVE_PORTAL_API_KEY' \
 -H 'Content-Type: application/json' \
 -d '{ "method": "eth_blockNumber", "params": [], "id": 1, "jsonrpc": "2.0" }'

JSON-RPC Supported Methods

List of Supported Methods

The following methods are supported on the Grove API:

• debug_traceCall
• debug_traceTransaction
• eth_accounts
• eth_blockNumber
• eth_call
• eth_chainId
• eth_coinbase
• eth_estimateGas
• eth_gasPrice
• eth_getBalance
• eth_getBlockByHash
• eth_getBlockByNumber
• eth_getBlockTransactionCountByHash
• eth_getBlockTransactionCountByNumber
• eth_getCode
• eth_getFilterChanges
• eth_getFilterLogs
• eth_getLogs
• eth_getStorageAt
• eth_getTransactionByBlockHashAndIndex
• eth_getTransactionByBlockNumberAndIndex
• eth_getTransactionByHash
• eth_getTransactionCount
• eth_getTransactionReceipt
• eth_getUncleByBlockHashAndIndex
• eth_getUncleByBlockNumberAndIndex
• eth_getUncleCountByBlockHash
• eth_getUncleCountByBlockNumber
• eth_getWork
• eth_hashrate
• eth_mining
• eth_newBlockFilter
• eth_newFilter
• eth_newPendingTransactionFilter
• eth_protocolVersion
• eth_sendRawTransaction
• eth_sendTransaction
• eth_sign
• eth_signTransaction
• eth_syncing
• eth_uninstallFilter
• net_listening
• net_peerCount
• net_version
• web3_clientVersion
• web3_sha3

JSON-RPC to HTTP Status Code Mapping

Grove takes an opinionated approach to mapping JSON-RPC errors to HTTP status codes. For more information, see PATH documentation or the table below.

It's common practice in JSON-RPC-over-HTTP implementations to map:

• Client errors (e.g., -32600 Invalid Request) to 4xx HTTP statuses
• Server errors (e.g., -32603 Internal error or -32000 "Server error") to 5xx HTTP statuses

PATH follows this practice and maps JSON-RPC errors to HTTP status codes as follows:

JSON-RPC Error Code	Common Meaning	HTTP Status Code
-32700	Parse error	400 Bad Request
-32600	Invalid request	400 Bad Request
-32601	Method not found	404 Not Found
-32602	Invalid params	400 Bad Request
-32603	Internal error	500 Server Error
-32098	Timeout	504 Gateway Timeout
-32097	Rate limited	429 Too Many Requests
-32000…-32099	Server error range	500 Server Error
> 0	Application errors (client-side)	400 Bad Request
< 0 (other negative)	Application errors (server-side)	500 Server Error

JSON-RPC Batch Requests

At Grove, we wholeheartedly support batching requests in adherence to the JSON-RPC 2.0 Specification. Our enhanced batching process ensures superior performance and reliability by providing individual Quality of Service (QoS) for each request within a batch. Additionally, we've updated our relay count policy to reflect the individual attention each request receives.

Grove Batching Process:

1. Initial Reception: Batches are received and processed for unpacking.
2. Unpacking: The batch is unpacked to individual requests, allowing for tailored processing.
3. QoS Processing: Each request undergoes independent QoS processing, ensuring it receives the optimal handling.
4. Repacking: After processing, the requests are repackaged into their original batch format.
5. Batch Delivery: The processed batch is then delivered back to the customer as a cohesive unit.

REST APIs

Grove API is able to support any RESTful API configuration.

Services that utilize a RESTful API will be provided in accordance with their individual specifications.

Cosmos & CometBFT

The Grove API has support for the CometBFT and Cosmos SDK APIs.

Example RESTful CometBFT request to v1/status:

curl -X GET https://xrplevm.rpc.grove.city/v1/status \
  -H "Authorization: $GROVE_PORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Portal-Application-Id: $GROVE_PORTAL_APP_ID"

Example RESTful Cosmos SDK request to v1/cosmos/bank/v1beta1/supply:

curl -X GET https://xrplevm.rpc.grove.city/v1/cosmos/bank/v1beta1/supply \
  -H "Authorization: $GROVE_PORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Portal-Application-Id: $GROVE_PORTAL_APP_ID"

Websockets

Grove supports WebSocket subscription for a subset of its services.

Example request using wscat:

wscat -c wss://xrplevm.rpc.grove.city/v1/$GROVE_PORTAL_APP_ID -H "Authorization: $GROVE_PORTAL_API_KEY"

And subscribe to newHeads like so:

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

gRPC

Coming soon!

Recommendations and Considerations

Data Size and Timeouts

The Grove Portal caps request and response size at 100MB, however, optimization can help to ensure successful responses.

The Portal has a 10 second timeout limit, so large or excessive data pulls may fail to return. If you encounter this issue, we recommend reducing the amount of data requested wherever possible and retrying the request.

Logs

The Grove Portal limits user requests to 100,000 log lines in a request. If you encounter issues when requesting log lines, please reduce the amount of data requested and try again.

Other Considerations

The Grove Portal is built on the decentralized Pocket Network and does not require any level of client specificity or client configuration. The PATH toolkit ensures that you are given the best and fastest response provided by the Pocket Network. This evaluation is made in real-time for your requests.

If a specific request fails, often times retrying the request can yield an improved result.