reqresp

package
v0.2.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 24, 2026 License: Apache-2.0 Imports: 33 Imported by: 0

Documentation

Overview

Package reqresp provides Ethereum consensus-layer request/response streams.

It owns canonical protocol IDs, response codes, SSZ-snappy framing, beacon status discovery, the participant's libp2p identity, sessions, and SSZ request encoders. Request is the one-shot API; NewSession reuses one libp2p host and peer connection for multiple streams.

response, err := reqresp.Request(
	ctx,
	target.ConsensusURL,
	target.ConsensusP2P,
	reqresp.PingV1,
	reqresp.SSZUint64(0),
	reqresp.RequestOptions{},
)
if err != nil {
	return err
}
fmt.Println(response.Code)

RawSSZSnappy, RawSSZSnappyWithVarint, WriteSSZSnappy, and ReadResponseChunk expose caller-controlled framing for applications that manage their own streams.

Index

Constants

View Source
const (
	// BlocksByRangeV1 is the BeaconBlocksByRange v1 protocol ID.
	BlocksByRangeV1 = ProtocolPrefix + "/beacon_blocks_by_range/1/" + Encoding
	// BlocksByRangeV2 is the BeaconBlocksByRange v2 protocol ID.
	BlocksByRangeV2 = ProtocolPrefix + "/beacon_blocks_by_range/2/" + Encoding
)
View Source
const (
	// BlocksByRootV1 is the BeaconBlocksByRoot v1 protocol ID.
	BlocksByRootV1 = ProtocolPrefix + "/beacon_blocks_by_root/1/" + Encoding
	// BlocksByRootV2 is the BeaconBlocksByRoot v2 protocol ID.
	BlocksByRootV2 = ProtocolPrefix + "/beacon_blocks_by_root/2/" + Encoding
)
View Source
const (
	// MaxDataColumnRootIdentifiers caps identifiers in one generated request.
	MaxDataColumnRootIdentifiers = 128
	// MaxDataColumnsPerIdentifier caps columns in one generated identifier.
	MaxDataColumnsPerIdentifier = 128
)
View Source
const (
	// ExecutionProofsByRangeV1 is the EIP-8025 range request protocol ID.
	ExecutionProofsByRangeV1 = ProtocolPrefix + "/execution_proofs_by_range/1/" + Encoding
	// ExecutionProofsByRootV1 is the EIP-8025 root request protocol ID.
	ExecutionProofsByRootV1 = ProtocolPrefix + "/execution_proofs_by_root/1/" + Encoding
	// ExecutionProofStatusV1 is the EIP-8025 proof status protocol ID.
	ExecutionProofStatusV1 = ProtocolPrefix + "/execution_proof_status/1/" + Encoding

	// MaxExecutionProofTypes is the EIP-8025 proof type list bound.
	MaxExecutionProofTypes = 4
	// MaxExecutionProofRootIdentifiers is the Deneb request block bound.
	MaxExecutionProofRootIdentifiers = 128
)
View Source
const (
	// MetadataV1 is the consensus Metadata v1 protocol ID.
	MetadataV1 = ProtocolPrefix + "/metadata/1/" + Encoding
	// MetadataV2 is the consensus Metadata v2 protocol ID.
	MetadataV2 = ProtocolPrefix + "/metadata/2/" + Encoding
	// MetadataV3 is the consensus Metadata v3 protocol ID.
	MetadataV3 = ProtocolPrefix + "/metadata/3/" + Encoding
)
View Source
const (
	// ProtocolPrefix is the consensus request/response namespace.
	ProtocolPrefix = "/eth2/beacon_chain/req"
	// Encoding is the consensus request/response encoding component.
	Encoding = "ssz_snappy"

	// CodeSuccess identifies a successful response chunk.
	CodeSuccess byte = 0
	// CodeInvalidRequest identifies the protocol-defined invalid-request response.
	CodeInvalidRequest byte = 1
	// CodeServerError identifies a responder-side failure.
	CodeServerError byte = 2
	// CodeResourceUnavailable identifies data unavailable at the responder.
	CodeResourceUnavailable byte = 3

	// ContextBytesLen is the fork-digest context length on contextual responses.
	ContextBytesLen = 4
	// MaxPayloadSize is the hard decoded ceiling for one response chunk.
	MaxPayloadSize = 10 * 1024 * 1024
	// MaxTotalResponseSize is the aggregate decoded-byte ceiling per request.
	MaxTotalResponseSize = 64 * 1024 * 1024
	// MaxResponseChunks is the response-frame ceiling per request.
	MaxResponseChunks uint64 = 1024
)
View Source
const (
	// StatusV1 is the consensus Status v1 protocol ID.
	StatusV1 = ProtocolPrefix + "/status/1/" + Encoding
	// StatusV2 is the consensus Status v2 protocol ID.
	StatusV2 = ProtocolPrefix + "/status/2/" + Encoding
)
View Source
const BlobSidecarsByRangeV1 = ProtocolPrefix + "/blob_sidecars_by_range/1/" + Encoding

BlobSidecarsByRangeV1 is the BlobSidecarsByRange v1 protocol ID.

View Source
const BlobSidecarsByRootV1 = ProtocolPrefix + "/blob_sidecars_by_root/1/" + Encoding

BlobSidecarsByRootV1 is the BlobSidecarsByRoot v1 protocol ID.

View Source
const DataColumnsByRangeV1 = ProtocolPrefix + "/data_column_sidecars_by_range/1/" + Encoding

DataColumnsByRangeV1 is the DataColumnSidecarsByRange v1 protocol ID.

View Source
const DataColumnsByRootV1 = ProtocolPrefix + "/data_column_sidecars_by_root/1/" + Encoding

DataColumnsByRootV1 is the DataColumnSidecarsByRoot v1 protocol ID.

View Source
const ExecutionPayloadEnvelopesByRangeV1 = ProtocolPrefix + "/execution_payload_envelopes_by_range/1/" + Encoding

ExecutionPayloadEnvelopesByRangeV1 is the corresponding v1 protocol ID.

View Source
const ExecutionPayloadEnvelopesByRootV1 = ProtocolPrefix + "/execution_payload_envelopes_by_root/1/" + Encoding

ExecutionPayloadEnvelopesByRootV1 is the corresponding v1 protocol ID.

View Source
const GoodbyeV1 = ProtocolPrefix + "/goodbye/1/" + Encoding

GoodbyeV1 is the consensus Goodbye v1 protocol ID.

View Source
const LightClientBootstrapV1 = ProtocolPrefix + "/light_client_bootstrap/1/" + Encoding

LightClientBootstrapV1 is the corresponding v1 protocol ID.

View Source
const LightClientFinalityUpdateV1 = ProtocolPrefix + "/light_client_finality_update/1/" + Encoding

LightClientFinalityUpdateV1 is the corresponding v1 protocol ID.

View Source
const LightClientOptimisticUpdateV1 = ProtocolPrefix + "/light_client_optimistic_update/1/" + Encoding

LightClientOptimisticUpdateV1 is the corresponding v1 protocol ID.

View Source
const LightClientUpdatesByRangeV1 = ProtocolPrefix + "/light_client_updates_by_range/1/" + Encoding

LightClientUpdatesByRangeV1 is the corresponding v1 protocol ID.

View Source
const MaxDataColumnsByRange = 1 << 20

MaxDataColumnsByRange is the SDK allocation ceiling for encoded columns.

View Source
const MaxSSZBlobIdentifiers = 1 << 20

MaxSSZBlobIdentifiers is the allocation ceiling for SSZBlobIdentifiers.

View Source
const MaxSSZRootListItems = 1 << 20

MaxSSZRootListItems is the allocation ceiling for SSZRootList.

View Source
const PingV1 = ProtocolPrefix + "/ping/1/" + Encoding

PingV1 is the consensus Ping v1 protocol ID.

Variables

View Source
var ErrEmptyResponse = fmt.Errorf("empty response stream: %w", io.EOF)

ErrEmptyResponse reports a cleanly closed response stream that contained no response chunks. It unwraps to io.EOF for callers that classify stream ends.

Functions

func BeaconStatus

func BeaconStatus(ctx context.Context, beaconURL string) ([]byte, []byte, error)

BeaconStatus builds the canonical Status v1 and v2 request bodies.

func CLKey added in v0.2.5

CLKey returns the case identity in libp2p's secp256k1 representation.

func CLPeerIdentities added in v0.2.5

func CLPeerIdentities(identity *utils.ParticipantIdentity) ([]string, error)

CLPeerIdentities returns the exact libp2p peer ID and discv5 node ID.

func Multiaddr

func Multiaddr(p2pAddr string, peerID peer.ID) (ma.Multiaddr, error)

Multiaddr normalizes a libp2p multiaddress or host:port endpoint.

func PeerID

func PeerID(ctx context.Context, beaconURL, p2pAddr string) (peer.ID, error)

PeerID resolves the peer ID from a full multiaddress or the beacon identity API.

func ProtocolID

func ProtocolID(message string, version int) (string, error)

ProtocolID returns the canonical request/response protocol identifier.

func RawSSZSnappy

func RawSSZSnappy(payload []byte) ([]byte, error)

RawSSZSnappy returns one canonical length-prefixed framed-snappy body.

func RawSSZSnappyWithVarint

func RawSSZSnappyWithVarint(varintPrefix, payload []byte) ([]byte, error)

RawSSZSnappyWithVarint frames payload after an exact caller-supplied prefix.

func ReadSSZSnappy added in v0.1.9

func ReadSSZSnappy(r io.Reader, maxPayload uint64) ([]byte, error)

ReadSSZSnappy decodes one bounded length-prefixed framed-snappy body.

func SSZBlobIdentifiers

func SSZBlobIdentifiers(identifiers []BlobIdentifier) ([]byte, error)

SSZBlobIdentifiers encodes exactly the caller-supplied identifiers.

func SSZBlocksByRangeRequest

func SSZBlocksByRangeRequest(startSlot, count, step uint64) []byte

SSZBlocksByRangeRequest encodes start slot, count, and step.

func SSZDataColumnsByRangeRequest

func SSZDataColumnsByRangeRequest(startSlot, count uint64, columns []uint64) ([]byte, error)

SSZDataColumnsByRangeRequest encodes a DataColumnSidecarsByRange request.

func SSZDataColumnsByRootIdentifiers

func SSZDataColumnsByRootIdentifiers(identifiers []DataColumnIdentifier) ([]byte, error)

SSZDataColumnsByRootIdentifiers encodes exactly the caller-supplied identifiers.

func SSZExecutionProofStatus added in v0.1.9

func SSZExecutionProofStatus(blockRoot Root, slot uint64, proofTypes []byte) ([]byte, error)

SSZExecutionProofStatus encodes the EIP-8025 status request and response.

func SSZExecutionProofsByRange added in v0.1.9

func SSZExecutionProofsByRange(startSlot, count uint64, proofTypes []byte) ([]byte, error)

SSZExecutionProofsByRange encodes the EIP-8025 range request container.

func SSZExecutionProofsByRoot added in v0.1.9

func SSZExecutionProofsByRoot(identifiers []ProofByRootIdentifier) ([]byte, error)

SSZExecutionProofsByRoot encodes the EIP-8025 variable identifier list.

func SSZRootList

func SSZRootList(roots []Root) ([]byte, error)

SSZRootList encodes exactly the caller-supplied SSZ roots.

func SSZTwoUint64Request

func SSZTwoUint64Request(first, second uint64) []byte

SSZTwoUint64Request returns two consecutive SSZ uint64 fields.

func SSZUint64

func SSZUint64(value uint64) []byte

SSZUint64 returns the SSZ encoding of value.

func WriteResponseChunk added in v0.1.9

func WriteResponseChunk(w io.Writer, chunk ResponseChunk) error

WriteResponseChunk writes one canonical response chunk.

func WriteSSZSnappy

func WriteSSZSnappy(w io.Writer, payload []byte) error

WriteSSZSnappy writes one length-prefixed framed-snappy request body.

Types

type AcceptOptions added in v0.1.9

type AcceptOptions struct {
	NoBody     bool
	MaxPayload uint64
	Timeout    time.Duration
}

AcceptOptions controls one inbound request/response stream.

type BlobIdentifier

type BlobIdentifier struct {
	BlockRoot Root
	Index     uint64
}

BlobIdentifier is one caller-owned block-root and blob-index pair.

type DataColumnIdentifier

type DataColumnIdentifier struct {
	BlockRoot Root
	Columns   []uint64
}

DataColumnIdentifier is one caller-owned block-root and column list.

type InboundRequest added in v0.1.9

type InboundRequest struct {
	// contains filtered or unexported fields
}

InboundRequest is one request stream initiated by the connected peer.

func (*InboundRequest) Close added in v0.1.9

func (r *InboundRequest) Close() error

Close completes the response stream.

func (*InboundRequest) Payload added in v0.1.9

func (r *InboundRequest) Payload() []byte

Payload returns a copy of the decoded request body.

func (*InboundRequest) Protocol added in v0.1.9

func (r *InboundRequest) Protocol() string

Protocol returns the negotiated request/response protocol identifier.

func (*InboundRequest) Reset added in v0.1.9

func (r *InboundRequest) Reset() error

Reset aborts the response stream.

func (*InboundRequest) WriteRaw added in v0.1.9

func (r *InboundRequest) WriteRaw(payload []byte) error

WriteRaw writes exact caller-owned response bytes.

func (*InboundRequest) WriteResponse added in v0.1.9

func (r *InboundRequest) WriteResponse(chunk ResponseChunk) error

WriteResponse writes one canonical response chunk.

type ProofByRootIdentifier added in v0.1.9

type ProofByRootIdentifier struct {
	BlockRoot  Root
	ProofTypes []byte
}

ProofByRootIdentifier selects proof types for one block root.

type RequestOptions

type RequestOptions struct {
	NoBody          bool
	RawBody         []byte
	HasRawBody      bool
	HasContext      bool
	Handshake       bool
	Timeout         time.Duration
	MaxPayload      uint64
	MaxTotalPayload uint64
	MaxChunks       uint64
	SkipResponse    bool
	// BeforeSend runs after setup and immediately before request bytes are written.
	BeforeSend func() error
}

RequestOptions controls one request/response exchange.

type ResponseChunk

type ResponseChunk struct {
	Code    byte
	Context []byte
	Payload []byte
}

ResponseChunk is one decoded response frame.

func ReadResponseChunk

func ReadResponseChunk(r io.Reader, hasContext bool, maxPayload uint64) (*ResponseChunk, error)

ReadResponseChunk decodes exactly one bounded response chunk.

func Request

func Request(ctx context.Context, beaconURL, p2pAddr, proto string, payload []byte, options RequestOptions) (*ResponseChunk, error)

Request connects, performs one exchange, and closes the session.

func RequestChunks

func RequestChunks(ctx context.Context, beaconURL, p2pAddr, proto string, payload []byte, options RequestOptions) ([]*ResponseChunk, error)

RequestChunks connects, performs one multi-response exchange, and closes the session.

type ResponseReader

type ResponseReader struct {
	// contains filtered or unexported fields
}

ResponseReader decodes consecutive response chunks through one persistent buffer while enforcing per-chunk, aggregate-byte, and chunk-count ceilings.

func NewResponseReader

func NewResponseReader(r io.Reader, hasContext bool, maxPayload, maxTotal, maxChunks uint64) (*ResponseReader, error)

NewResponseReader creates a bounded decoder for a sequence of response chunks.

func (*ResponseReader) Next

func (r *ResponseReader) Next() (*ResponseChunk, error)

Next returns the next response chunk or io.EOF after a clean stream end.

type Root

type Root [32]byte

Root is one caller-owned SSZ root.

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session is one connected consensus request/response peer.

func NewSession

func NewSession(ctx context.Context, beaconURL, p2pAddr string) (*Session, error)

NewSession connects a transient libp2p host using the current case identity. The host runs a gossipsub router, so Identify lists the gossipsub protocols. Consensus clients such as Lighthouse disconnect a peer that does not list them.

func NewSessionWithIdentity added in v0.1.8

func NewSessionWithIdentity(ctx context.Context, beaconURL, p2pAddr string, identity libp2pcrypto.PrivKey) (*Session, error)

NewSessionWithIdentity connects a transient libp2p host using an explicit local identity. Multi-identity cases must opt in explicitly through this path. The host runs a gossipsub router, as NewSession does.

func (*Session) Accept added in v0.1.9

func (s *Session) Accept(ctx context.Context, proto string, options AcceptOptions) (*InboundRequest, error)

Accept waits for one peer-initiated request on proto.

func (*Session) Close

func (s *Session) Close() error

Close stops the gossipsub router and releases the libp2p host and all of its streams.

func (*Session) Host

func (s *Session) Host() host.Host

Host returns the connected libp2p host for protocols such as gossipsub that share the same consensus peer transport.

func (*Session) OpenStream added in v0.1.9

func (s *Session) OpenStream(ctx context.Context, protocolID string, timeout time.Duration) (network.Stream, error)

OpenStream opens one raw protocol stream on this connected peer session. The caller owns the returned stream.

func (*Session) PubSub added in v0.2.8

func (s *Session) PubSub() *pubsub.PubSub

PubSub returns the gossipsub router that runs on the session host. The session owns it. A host can run one router only.

func (*Session) Request

func (s *Session) Request(proto string, payload []byte, options RequestOptions) (*ResponseChunk, error)

Request performs one exchange on an existing session.

func (*Session) RequestChunks

func (s *Session) RequestChunks(proto string, payload []byte, options RequestOptions) ([]*ResponseChunk, error)

RequestChunks performs one exchange and reads every response chunk until EOF.

func (*Session) StatusWarmup

func (s *Session) StatusWarmup(beaconURL string) error

StatusWarmup completes a Status v2 handshake, falling back to Status v1.

Fulu clients drop Status v1, so the fallback usually fails with "protocol not supported" or with a closed connection. That message hides why v2 failed, so both attempts are reported when neither succeeds.

type TransportEndpoints added in v0.1.9

type TransportEndpoints struct {
	TCP  string
	UDP  string
	QUIC bool
}

TransportEndpoints are the socket endpoints advertised by one libp2p peer.

func ResolveTransportEndpoints added in v0.1.9

func ResolveTransportEndpoints(p2pAddr string, peerID peer.ID) (TransportEndpoints, error)

ResolveTransportEndpoints extracts TCP and UDP socket endpoints from a normalized libp2p address.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址