ethrpc

README

ethrpc

Simple go lib to make RPC calls to Ethereum-like nodes easy

Example use

    target := ethrpc.New("https://cloudflare-eth.com")
    currentBlockNo, err := ethrpc.ReadUint64(target.Do("eth_blockNumber"))

TODO

• Support websocket

Documentation

Index

• Variables
• func ReadAs[T any](v json.RawMessage, e error) (T, error)
• func ReadBigInt(v json.RawMessage, e error) (*big.Int, error)
• func ReadString(v json.RawMessage, e error) (string, error)
• func ReadTo(target any) func(v json.RawMessage, e error) error
• func ReadUint64(v json.RawMessage, e error) (uint64, error)
• type Api
  • func (a *Api) BlockNumber(ctx context.Context) (uint64, error)
  • func (a *Api) ChainId(ctx context.Context) (uint64, error)
  • func (a *Api) Do(method string, args ...any) (json.RawMessage, error)
  • func (a *Api) To(target any, method string, args ...any) error
  • func (a *Api) ToCtx(ctx context.Context, target any, method string, args ...any) error
• type ErrorObject
  • func (e *ErrorObject) Error() string
• type ForwardOptions
• type Handler
  • func Evaluate(ctx context.Context, servers ...string) (Handler, error)
• type RPC
  • func New(h string) *RPC
  • func (r *RPC) Do(method string, args ...any) (json.RawMessage, error)
  • func (r *RPC) DoCtx(ctx context.Context, method string, args ...any) (json.RawMessage, error)
  • func (r *RPC) DoNamed(method string, args map[string]any) (json.RawMessage, error)
  • func (r *RPC) DoNamedCtx(ctx context.Context, method string, args map[string]any) (json.RawMessage, error)
  • func (r *RPC) Forward(ctx context.Context, rw http.ResponseWriter, req *Request, ...)
  • func (r *RPC) Override(method string, fnc any)
  • func (r *RPC) Send(req *Request) (json.RawMessage, error)
  • func (r *RPC) SendCtx(ctx context.Context, req *Request) (json.RawMessage, error)
  • func (r *RPC) SetBasicAuth(username, password string)
  • func (r *RPC) To(target any, method string, args ...any) error
• type RPCList
  • func (r RPCList) DoCtx(ctx context.Context, method string, args ...any) (json.RawMessage, error)
• type Request
  • func NewRequest(method string, params ...any) *Request
  • func (req *Request) HTTPRequest(ctx context.Context, host string) (*http.Request, error)
• type Response
• type ResponseIntf

Variables

var (
	ErrNoAvailableServer = errors.New("no available server")
)

Functions

func ReadAs

func ReadAs[T any](v json.RawMessage, e error) (T, error)

func ReadBigInt

func ReadBigInt(v json.RawMessage, e error) (*big.Int, error)

ReadBigInt can decode a json-encoded bigint in various ways, including if it is a number literal or a string.

func ReadString

func ReadString(v json.RawMessage, e error) (string, error)

ReadString decodes the return value as a string and returns it

func ReadTo

func ReadTo(target any) func(v json.RawMessage, e error) error

ReadTo returns a setter function that will return an error if an error happens. This is a bit convoluted because of limitation in Go's syntax, but this could be used as:

err = ReadTo(&block)(target.Do("eth_getBlockByNumber", "0x1b4", true))

func ReadUint64

func ReadUint64(v json.RawMessage, e error) (uint64, error)

ReadUint64 decodes the return value and passes it as a uint64.

This can be used as: res, err := ReadUint64(target.Do("eth_blockNumber"))

Types

type Api

type Api struct {
	Handler
}

func (*Api) BlockNumber

func (a *Api) BlockNumber(ctx context.Context) (uint64, error)

func (*Api) ChainId

func (a *Api) ChainId(ctx context.Context) (uint64, error)

func (*Api) Do

func (a *Api) Do(method string, args ...any) (json.RawMessage, error)

func (*Api) To

func (a *Api) To(target any, method string, args ...any) error

func (*Api) ToCtx

func (a *Api) ToCtx(ctx context.Context, target any, method string, args ...any) error

type ErrorObject

type ErrorObject struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

func (*ErrorObject) Error

func (e *ErrorObject) Error() string

type ForwardOptions

type ForwardOptions struct {
	Pretty bool
	Cache  time.Duration
}

type Handler

type Handler interface {
	DoCtx(ctx context.Context, method string, args ...any) (json.RawMessage, error)
}

func Evaluate

func Evaluate(ctx context.Context, servers ...string) (Handler, error)

Evaluate will call the various servers in the list and return a list of servers that work (if any)

This will send a eth_blockNumber request to all the servers and measure the response time

type RPC

type RPC struct {
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

TODO support ws protocol

func New

func New(h string) *RPC

New returns a new instance of RPC to perform requests to the given RPC endpoint

func (*RPC) Do

func (r *RPC) Do(method string, args ...any) (json.RawMessage, error)

Do performs a RPC request

func (*RPC) DoCtx

func (r *RPC) DoCtx(ctx context.Context, method string, args ...any) (json.RawMessage, error)

DoCtx performs a RPC request, taking an optional context that can be cancelled to stop the request

func (*RPC) DoNamed

func (r *RPC) DoNamed(method string, args map[string]any) (json.RawMessage, error)

DoNamed performs a RPC request using named arguments

func (*RPC) DoNamedCtx

func (r *RPC) DoNamedCtx(ctx context.Context, method string, args map[string]any) (json.RawMessage, error)

DoNamedCtx performs a RPC request using named arguments, taking an optional context that can be cancelled to stop the request

func (*RPC) Forward

func (r *RPC) Forward(ctx context.Context, rw http.ResponseWriter, req *Request, opts *ForwardOptions)

Forward will write the RPC response to the given http.ResponseWriter.

func (*RPC) Override

func (r *RPC) Override(method string, fnc any)

Override allows redirecting calls to a RPC method to a standard go function

func (*RPC) Send

func (r *RPC) Send(req *Request) (json.RawMessage, error)

Send sends a raw request for processing

func (*RPC) SendCtx

func (r *RPC) SendCtx(ctx context.Context, req *Request) (json.RawMessage, error)

func (*RPC) SetBasicAuth

func (r *RPC) SetBasicAuth(username, password string)

SetBasicAuth sets basic auth params for all subsequent RPC requests

func (*RPC) To

func (r *RPC) To(target any, method string, args ...any) error

To performs the request and puts the result into target

type RPCList

type RPCList []*RPC

func (RPCList) DoCtx

func (r RPCList) DoCtx(ctx context.Context, method string, args ...any) (json.RawMessage, error)

type Request

type Request struct {
	JsonRpc string `json:"jsonrpc"` // 2.0
	Method  string `json:"method"`
	Params  any    `json:"params"`
	Id      any    `json:"id"`
}

func NewRequest

func NewRequest(method string, params ...any) *Request

NewRequest makes a new Request fit to use with methods like Send.

func (*Request) HTTPRequest

func (req *Request) HTTPRequest(ctx context.Context, host string) (*http.Request, error)

HTTPRequest returns a http.Request for the given json-rpc request.

type Response

type Response struct {
	JsonRpc string          `json:"jsonrpc"` // 2.0
	Result  json.RawMessage `json:"result"`
	Error   *ErrorObject    `json:"error,omitempty"`
	Id      any             `json:"id"`
}

type ResponseIntf

type ResponseIntf struct {
	JsonRpc string       `json:"jsonrpc"` // 2.0
	Result  any          `json:"result"`
	Error   *ErrorObject `json:"error,omitempty"`
	Id      any          `json:"id"`
}

RPCResponseIntf is same as rpcResponse except Result is a any