Crate alloy_json_rpc

Alloy JSON-RPC data types.

This crate provides data types for use with the JSON-RPC 2.0 protocol. It does not provide any functionality for actually sending or receiving JSON-RPC data.

If you find yourself importing this crate, and you are not implementing a JSON-RPC client or transport, you are likely at the wrong layer of abstraction. If you want to use a JSON-RPC client, consider using the alloy-transport crate.

Usage

This crate models the JSON-RPC 2.0 protocol data-types. It is intended to be used to build JSON-RPC clients or servers. Most users will not need to import this crate.

This crate provides the following low-level data types:

• Request - A JSON-RPC request.
• Response - A JSON-RPC response.
• ErrorPayload - A JSON-RPC error response payload, including code and message.
• ResponsePayload - The payload of a JSON-RPC response, either a success payload, or an ErrorPayload.

For client-side Rust ergonomics, we want to map responses to Results. To that end, we provide the following types:

• RpcError - An error that can occur during JSON-RPC communication. This type aggregates errors that are common to all transports, such as (de)serialization, error responses, and includes a generic transport error.
• RpcResult - A result modeling an Rpc outcome as Result<T, RpcError<E>>.

We recommend that transport implementers use RpcResult as the return type for their transport methods, parameterized by their transport error type. This will allow them to return either a successful response or an error.

Note On (De)Serialization

Request, Response, and similar types are generic over the actual data being passed to and from the RPC. We can achieve partial (de)serialization by making them generic over a serde_json::RawValue.

• For Request - PartiallySerializedRequest is a Request<Box<RawValue>. It represents a Request whose parameters have been serialized. SerializedRequest, on the other hand is a request that has been totally serialized. For client-development purposes, its Id and method have been preserved.
• For Response - BorrowedResponse is a Response<&RawValue>. It represents a Response whose Id and return status (success or failure) have been deserialized, but whose payload has not.

Allowing partial serialization lets us include many unlike Request objects in collections (e.g. in a batch request). This is useful for implementing a client.

Allowing partial deserialization lets learn request status, and associate the raw response data with the corresponding client request before doing full deserialization work. This is useful for implementing a client.

In general, partially deserialized responses can be further deserialized. E.g. an BorrowedRpcResult may have success responses deserialized with crate::try_deserialize_ok::<U>, which will transform it to an RpcResult<U>.

Structs

ErrorPayload

A JSON-RPC 2.0 error object.

EthNotification

An ethereum-style notification, not to be confused with a JSON-RPC notification.

Request

A JSON-RPC 2.0 request object.

RequestMeta

RequestMeta contains the Id and method name of a request.

Response

A JSON-RPC 2.0 response object containing a ResponsePayload.

SerializedRequest

A JSON-RPC 2.0 request object that has been serialized, with its Id and method preserved.

Enums

Id

A JSON-RPC 2.0 ID object. This may be a number, a string, or null.

PubSubItem

An item received over an Ethereum pubsub transport.

RequestPacket

A RequestPacket is a SerializedRequest or a batch of serialized request.

ResponsePacket

A ResponsePacket is a Response or a batch of responses.

ResponsePayload

A JSON-RPC 2.0 response payload.

RpcError

An RPC error.

SubId

A subscription ID.

Traits

BorrowedRpcObject

An object that can be both sent and received over RPC, borrowing from the the deserialization context.

RpcBorrow

An object that can be received over RPC, borrowing from the deserialization context.

RpcObject

An object that can be both sent and received over RPC.

RpcRecv

An object that can be received over RPC.

RpcSend

An object that can be sent over RPC.

Functions

transform_response

Transform a transport response into an RpcResult, discarding the Id.

transform_result

Transform a transport outcome into an RpcResult, discarding the Id.

try_deserialize_ok

Attempt to deserialize the Ok(_) variant of an RpcResult.

Type Aliases

BorrowedErrorPayload

A ErrorPayload that has been partially deserialized, borrowing its contents from the deserializer. This is used primarily for intermediate deserialization. Most users will not require it.

BorrowedResponse

A Response that has been partially deserialized, borrowing its contents from the deserializer. This is used primarily for intermediate deserialization. Most users will not require it.

BorrowedResponsePacket

A BorrowedResponsePacket is a ResponsePacket that has been partially deserialized, borrowing its contents from the deserializer.

BorrowedResponsePayload

A ResponsePayload that has been partially deserialized, borrowing its contents from the deserializer. This is used primarily for intermediate deserialization. Most users will not require it.

BorrowedRpcResult

A partially deserialized RpcResult, borrowing from the deserializer.

PartiallySerializedRequest

A Request that has been partially serialized.

RpcResult

The result of a JSON-RPC request.