protocolio

package
v0.0.0-...-beefb37 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package protocolio provides bounded, redacted I/O for protocol adapters.

Index

Constants

View Source
const MaxReadBatch = 256

MaxReadBatch bounds one backend request. ReadGroup chunks larger independent groups.

View Source
const StandardMulticall3 = "0xcA11bde05977b3631167028862bE2a173976CA11"

StandardMulticall3 is the official deployment address. A missing or incompatible deployment causes aggregation to fail; hosts must never silently substitute it.

Variables

This section is empty.

Functions

func Action

func Action(s string) error

func AddressWord

func AddressWord(a common.Address) []byte

func Ancestor

func Ancestor(ctx context.Context, r interface {
	HeaderByHash(context.Context, common.Hash) (*types.Header, error)
}, witness *types.Header, number *big.Int) (*types.Header, error)

Ancestor follows parent hashes from witness down to number.

func BlockArgument

func BlockArgument(number *big.Int) string

BlockArgument preserves exact pinned heights and special block tags.

func Bytes

func Bytes(s string, max int) ([]byte, error)

func CallArgument

func CallArgument(msg ethereum.CallMsg) map[string]any

CallArgument matches ethclient's complete CallMsg encoding, including zero From, typed transactions and authorizations. Unknown contracts are isolated eth_calls.

func CallData

func CallData(ctx context.Context, r provider.Reader, s provider.Snapshot, to common.Address, data []byte) ([]byte, error)

CallData performs a pinned raw read; callers use generated typed Pack/Unpack methods.

func CallFailure

func CallFailure(method string, call ethereum.CallMsg, block *big.Int, err error) error

CallFailure retains public call identity, never arguments, signatures or URLs.

func CallHTTPBatch

func CallHTTPBatch(ctx context.Context, client *http.Client, endpoint string, batch []rpc.BatchElem) error

CallHTTPBatch uses ordinary RPC objects for contract reads and singleton groups. Only groups containing other RPC methods use arrays. The supplied host transport and strict response validation apply to both shapes.

func Canonical

func Canonical(ctx context.Context, r provider.Reader, s provider.Snapshot) error

Canonical checks the pinned hash after external I/O and before external mutations. Numeric-block eth_call alone cannot detect an intervening reorganization.

func CheckHeader

func CheckHeader(header *types.Header, number *big.Int) error

CheckHeader requires a uint64-numbered header, at number when one is given.

func Digest

func Digest(domain, structure common.Hash) common.Hash

func Domain

func Domain(name, version string, chainID *big.Int, contract common.Address) common.Hash

func Execution

func Execution(ctx context.Context, r provider.Reader, s provider.Snapshot) error

Execution verifies evidence from the authorizing transaction against the pinned confirmed snapshot. A later receipt or an orphaned request cannot authorize progress.

func Failure

func Failure(operation string, err error) error

func Hash

func Hash(s string) (common.Hash, error)

func Snapshot

func Snapshot(s provider.Snapshot) error

func Word

func Word(n *big.Int) []byte

Types

type AggregateCall

type AggregateCall struct {
	Target common.Address
	Data   []byte
}

AggregateCall and AggregateResult keep ABI generation in the host codec.

type AggregateCodec

type AggregateCodec interface {
	Encode([]AggregateCall) ([]byte, error)
	Decode([]byte) ([]AggregateResult, error)
}

type AggregateResult

type AggregateResult struct {
	Success bool
	Data    []byte
}

type BatchReader

type BatchReader interface {
	BatchRead(context.Context, []ReadRequest) ([]ReadResult, error)
}

BatchReader is optional. It must return exactly one ordered result per request; member errors stay attached to their member, independently of transport failure. Implementations must not retry an actual failed batch as individual reads.

type Client

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

func NewHTTP

func NewHTTP(c HTTPConfig, injected *http.Client) (*Client, error)

func (*Client) JSON

func (c *Client) JSON(ctx context.Context, method, path string, in, out any) (int, error)

JSON returns a status even on non-2xx replies, allowing callers to distinguish 404 from an uncertain request.

type HTTPConfig

type HTTPConfig struct {
	URL              string
	TimeoutSeconds   int
	MaxResponseBytes int64
}

HTTPConfig bounds one public protocol API. All errors omit URLs, response bodies and headers.

type RPCBatchCall

type RPCBatchCall func(context.Context, []rpc.BatchElem) error

RPCBatchCall sends one bounded logical group, reporting each member in its Result.

type RPCBatchReader

type RPCBatchReader struct {
	Call      RPCBatchCall
	Multicall common.Address
	Codec     AggregateCodec
}

RPCBatchReader groups only source-reviewed, caller-independent getters. The host supplies its existing read transport and generated aggregate binding.

func (RPCBatchReader) BatchRead

func (r RPCBatchReader) BatchRead(ctx context.Context, requests []ReadRequest) ([]ReadResult, error)

type ReadKind

type ReadKind uint8
const (
	ReadCall ReadKind = iota + 1
	ReadHeader
	ReadLogs
	ReadReceipt
)

type ReadRequest

type ReadRequest struct {
	Kind          ReadKind
	Call          ethereum.CallMsg
	Block         *big.Int
	Filter        ethereum.FilterQuery
	Hash          common.Hash
	MulticallSafe bool
}

ReadRequest describes an independent read. MulticallSafe is an explicit promise that a getter is caller-independent, read-only and unaffected by shared transient state. A backend may aggregate compatible safe calls; other calls retain Call's exact execution context in isolated eth_call requests. Block nil means latest.

func ContractRead

func ContractRead(target common.Address, data []byte, block *big.Int, safe bool) ReadRequest

type ReadResult

type ReadResult struct {
	Data    []byte
	Header  *types.Header
	Logs    []types.Log
	Receipt *types.Receipt
	Err     error
}

func (ReadResult) CallData

func (r ReadResult) CallData() ([]byte, error)

CallData preserves the protocol read error boundary for batched member failures.

type ReadResults

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

ReadResults is scoped to one sequential read stage, not a cross-block cache. At lazily reads single-call backends, preserving early-return behavior and existing interfaces. Real batches execute once and defer only consumption of member errors. It is intended for use by one goroutine.

func ReadGroup

func ReadGroup(ctx context.Context, reader any, requests ...ReadRequest) (*ReadResults, error)

func (*ReadResults) At

func (g *ReadResults) At(index int) ReadResult

Jump to

Keyboard shortcuts

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