enr

Documentation

Overview

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
• Variables
• func IsNotFound(err error) bool
• type Entry
  • func WithEntry(k string, v interface{}) Entry
• type ID
  • func (v ID) ENRKey() string
• type IP
  • func (v *IP) DecodeRLP(s *rlp.Stream) error
  • func (v IP) ENRKey() string
  • func (v IP) EncodeRLP(w io.Writer) error
• type IPv4
  • func (v *IPv4) DecodeRLP(s *rlp.Stream) error
  • func (v IPv4) ENRKey() string
  • func (v IPv4) EncodeRLP(w io.Writer) error
• type IPv6
  • func (v *IPv6) DecodeRLP(s *rlp.Stream) error
  • func (v IPv6) ENRKey() string
  • func (v IPv6) EncodeRLP(w io.Writer) error
• type IdentityScheme
• type KeyError
  • func (err *KeyError) Error() string
• type Record
  • func (r *Record) AppendElements(list []interface{}) []interface{}
  • func (r *Record) DecodeRLP(s *rlp.Stream) error
  • func (r Record) EncodeRLP(w io.Writer) error
  • func (r *Record) IdentityScheme() string
  • func (r *Record) Load(e Entry) error
  • func (r *Record) Seq() uint64
  • func (r *Record) Set(e Entry)
  • func (r *Record) SetSeq(s uint64)
  • func (r *Record) SetSig(s IdentityScheme, sig []byte) error
  • func (r *Record) Signature() []byte
  • func (r *Record) VerifySignature(s IdentityScheme) error
• type SchemeMap
  • func (m SchemeMap) NodeAddr(r *Record) []byte
  • func (m SchemeMap) Verify(r *Record, sig []byte) error
• type TCP
  • func (v TCP) ENRKey() string
• type TCP6
  • func (v TCP6) ENRKey() string
• type UDP
  • func (v UDP) ENRKey() string
• type UDP6
  • func (v UDP6) ENRKey() string

Constants

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

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

一条节点的记录最多不能超过300字节

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. Entry代表Record对象中的一条记录, 记录类型包括预定义类型和通用类型 预定义类型: ID,Secp256k1,IP,IPv4,IPv6,TCP,TCP6,UDP,UDP6

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. 构造一个通用的Entry对象,用于用户设置自定义的键值对,例如: r := enr.Record{} r.Set(enr.WithEntry("myentry","hello")) // 设置键值对 "myentry":"hello" var m string r.Load(enr.WithEntry("myentry",&m)) // 重新加载myentry对应的值到m中,这里要使用m的指针

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. IP类型可以处理ipv4和ipv6

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. 明确代表ipv4,代表的key是ip

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 IPv6

type IPv6 net.IP

IPv6 is the "ip6" key, which holds the IP address of the node. 明确表示ipv6,代表的key是ip6

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 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. IdentityScheme对象可以验证记录签名的有效性 还能够通过记录计算出地址 实现这个接口的有V4ID,v4CompatID,NullID

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.

type Record

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

Record represents a node record. The zero value is an empty record. Record对象了包括三个部分,seq代表记录的序号,pairs记录里的各个键值对,signature记录的签名 其中signature最后生成,在设置好序号和所有键值对后再进行签名

func (*Record) AppendElements

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

AppendElements appends the sequence number and entries to the given slice. 将Record对象转换成[seq,k1,v1,k2,v2]形式的列表,追加到输入的列表后面 这个函数如果输入nil,其实就是将Record对象转换成了一个数组,接下来一般是进行rlp编码

func (*Record) DecodeRLP

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

DecodeRLP implements rlp.Decoder. Decoding doesn't verify the signature. 从rlp流中解码出一个Record对象 Record的rlp编码是一个list 第一项是signature,第二项是seq,后面依次每两个组成一个键值对

func (Record) EncodeRLP

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

EncodeRLP implements rlp.Encoder. Encoding fails if the record is unsigned. 对Record对象进行rlp编码,未签名的Record对象不能编码 对Record的rlp编码就是写入保存的raw 因为在SetSig函数中signature和raw字段被同时设置 所以signature不是nil,raw里就保存了rlp编码

func (*Record) IdentityScheme

func (r *Record) IdentityScheme() string

IdentityScheme returns the name of the identity scheme in the record. 获取Record的pairs中保存的id字段

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. 从Record.pairs中读取指定的key到Entry里

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. 更新或插入Record.pairs中的一项

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. 修改r.seq为输入的值,并清空signature和raw 由于修改了序号,缓存的rlp编码和原来的签名都无效了

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. SeqSig用于为Record对象设置签名 参数要求: 需要传入身份模式和签名,两者要么同时为nil,要么都不为nil 同时为nil: 用于清空Record对象的签名和缓存的rlp编码 都不为nil:

func (*Record) Signature

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

Signature returns the signature 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. 保存多种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

UDP is the "udp" key, which holds the IPv6-specific UDP 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