package enr

import "github.com/ethereum/go-ethereum/p2p/enr"

Package enr implements Ethereum Node Records as defined in EIP-778. A node record holds arbitrary information about a node on the peer-to-peer network. Node information is stored in key/value pairs. To store and retrieve key/values in a record, use the Entry interface.

Signature Handling

Records must be signed before transmitting them to another node.

Decoding a record doesn't check its signature. Code working with records from an untrusted source must always verify two things: that the record uses an identity scheme deemed secure, and that the signature is valid according to the declared scheme.

When creating a record, set the entries you want and use a signing function provided by the identity scheme to add the signature. Modifying a record invalidates the signature.

Package enr supports the "secp256k1-keccak" identity scheme.

Index

Constants 

const IDv4 = ID("v4") // the default identity scheme

const SizeLimit = 300 // maximum encoded size of a node record in bytes

Variables 

var (
	ErrInvalidSig = errors.New("invalid signature on node record")
)

Functions

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports whether the given error means that a key/value pair is missing from a record.

Types

type Entry 

type Entry interface {
	ENRKey() string
}

Entry is implemented by known node record entry types.

To define a new entry that is to be included in a node record, create a Go type that satisfies this interface. The type should also implement rlp.Decoder if additional checks are needed on the value.

func WithEntry 

func WithEntry(k string, v interface{}) Entry

WithEntry wraps any value with a key name. It can be used to set and load arbitrary values in a record. The value v must be supported by rlp. To use WithEntry with Load, the value must be a pointer.

type ID 

type ID string

ID is the "id" key, which holds the name of the identity scheme.

func (ID) ENRKey 

func (v ID) ENRKey() string

type IP 

type IP net.IP

IP is either the "ip" or "ip6" key, depending on the value. Use this value to encode IP addresses that can be either v4 or v6. To load an address from a record use the IPv4 or IPv6 types.

func (*IP) DecodeRLP 

func (v *IP) DecodeRLP(s *rlp.Stream) error

DecodeRLP implements rlp.Decoder.

func (IP) ENRKey 

func (v IP) ENRKey() string

func (IP) EncodeRLP 

func (v IP) EncodeRLP(w io.Writer) error

EncodeRLP implements rlp.Encoder.

type IPv4 

type IPv4 net.IP

IPv4 is the "ip" key, which holds the IP address of the node.

func (*IPv4) DecodeRLP 

func (v *IPv4) DecodeRLP(s *rlp.Stream) error

DecodeRLP implements rlp.Decoder.

func (IPv4) ENRKey 

func (v IPv4) ENRKey() string

func (IPv4) EncodeRLP 

func (v IPv4) EncodeRLP(w io.Writer) error

EncodeRLP implements rlp.Encoder.

type IPv4Addr 

type IPv4Addr netip.Addr

IPv4Addr is the "ip" key, which holds the IP address of the node.

func (*IPv4Addr) DecodeRLP 

func (v *IPv4Addr) DecodeRLP(s *rlp.Stream) error

DecodeRLP implements rlp.Decoder.

func (IPv4Addr) ENRKey 

func (v IPv4Addr) ENRKey() string

func (IPv4Addr) EncodeRLP 

func (v IPv4Addr) EncodeRLP(w io.Writer) error

EncodeRLP implements rlp.Encoder.

type IPv6 

type IPv6 net.IP

IPv6 is the "ip6" key, which holds the IP address of the node.

func (*IPv6) DecodeRLP 

func (v *IPv6) DecodeRLP(s *rlp.Stream) error

DecodeRLP implements rlp.Decoder.

func (IPv6) ENRKey 

func (v IPv6) ENRKey() string

func (IPv6) EncodeRLP 

func (v IPv6) EncodeRLP(w io.Writer) error

EncodeRLP implements rlp.Encoder.

type IPv6Addr 

type IPv6Addr netip.Addr

IPv6Addr is the "ip6" key, which holds the IP address of the node.

func (*IPv6Addr) DecodeRLP 

func (v *IPv6Addr) DecodeRLP(s *rlp.Stream) error

DecodeRLP implements rlp.Decoder.

func (IPv6Addr) ENRKey 

func (v IPv6Addr) ENRKey() string

func (IPv6Addr) EncodeRLP 

func (v IPv6Addr) EncodeRLP(w io.Writer) error

EncodeRLP implements rlp.Encoder.

type IdentityScheme 

type IdentityScheme interface {
	Verify(r *Record, sig []byte) error
	NodeAddr(r *Record) []byte
}

An IdentityScheme is capable of verifying record signatures and deriving node addresses.

type KeyError 

type KeyError struct {
	Key string
	Err error
}

KeyError is an error related to a key.

func (*KeyError) Error 

func (err *KeyError) Error() string

Error implements error.

func (*KeyError) Unwrap 

func (err *KeyError) Unwrap() error

type QUIC 

type QUIC uint16

QUIC is the "quic" key, which holds the QUIC port of the node.

func (QUIC) ENRKey 

func (v QUIC) ENRKey() string

type QUIC6 

type QUIC6 uint16

QUIC6 is the "quic6" key, which holds the IPv6-specific quic6 port of the node.

func (QUIC6) ENRKey 

func (v QUIC6) ENRKey() string

type Record 

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

Record represents a node record. The zero value is an empty record.

func (*Record) AppendElements 

func (r *Record) AppendElements(list []interface{}) []interface{}

AppendElements appends the sequence number and entries to the given slice.

func (*Record) DecodeRLP 

func (r *Record) DecodeRLP(s *rlp.Stream) error

DecodeRLP implements rlp.Decoder. Decoding doesn't verify the signature.

func (Record) EncodeRLP 

func (r Record) EncodeRLP(w io.Writer) error

EncodeRLP implements rlp.Encoder. Encoding fails if the record is unsigned.

func (*Record) IdentityScheme 

func (r *Record) IdentityScheme() string

IdentityScheme returns the name of the identity scheme in the record.

func (*Record) Load 

func (r *Record) Load(e Entry) error

Load retrieves the value of a key/value pair. The given Entry must be a pointer and will be set to the value of the entry in the record.

Errors returned by Load are wrapped in KeyError. You can distinguish decoding errors from missing keys using the IsNotFound function.

func (*Record) Seq 

func (r *Record) Seq() uint64

Seq returns the sequence number.

func (*Record) Set 

func (r *Record) Set(e Entry)

Set adds or updates the given entry in the record. It panics if the value can't be encoded. If the record is signed, Set increments the sequence number and invalidates the sequence number.

func (*Record) SetSeq 

func (r *Record) SetSeq(s uint64)

SetSeq updates the record sequence number. This invalidates any signature on the record. Calling SetSeq is usually not required because setting any key in a signed record increments the sequence number.

func (*Record) SetSig 

func (r *Record) SetSig(s IdentityScheme, sig []byte) error

SetSig sets the record signature. It returns an error if the encoded record is larger than the size limit or if the signature is invalid according to the passed scheme.

You can also use SetSig to remove the signature explicitly by passing a nil scheme and signature.

SetSig panics when either the scheme or the signature (but not both) are nil.

func (*Record) Signature 

func (r *Record) Signature() []byte

Signature returns the signature of the record.

func (*Record) Size 

func (r *Record) Size() uint64

Size returns the encoded size of the record.

func (*Record) VerifySignature 

func (r *Record) VerifySignature(s IdentityScheme) error

VerifySignature checks whether the record is signed using the given identity scheme.

type SchemeMap 

type SchemeMap map[string]IdentityScheme

SchemeMap is a registry of named identity schemes.

func (SchemeMap) NodeAddr 

func (m SchemeMap) NodeAddr(r *Record) []byte

func (SchemeMap) Verify 

func (m SchemeMap) Verify(r *Record, sig []byte) error

type TCP 

type TCP uint16

TCP is the "tcp" key, which holds the TCP port of the node.

func (TCP) ENRKey 

func (v TCP) ENRKey() string

type TCP6 

type TCP6 uint16

TCP6 is the "tcp6" key, which holds the IPv6-specific tcp6 port of the node.

func (TCP6) ENRKey 

func (v TCP6) ENRKey() string

type UDP 

type UDP uint16

UDP is the "udp" key, which holds the UDP port of the node.

func (UDP) ENRKey 

func (v UDP) ENRKey() string

type UDP6 

type UDP6 uint16

UDP6 is the "udp6" key, which holds the IPv6-specific UDP port of the node.

func (UDP6) ENRKey 

func (v UDP6) ENRKey() string

Source Files

enr.go entries.go

Version
v1.16.1 (latest)
Published
Jul 2, 2025
Platform
linux/amd64
Imports
8 packages
Last checked
3 days ago –

Tools for package owners.