Go-ethereum 源码解析之 core/types/log.go
package types
import (
"io"
"github.com/ethereum/go-ethereum/common"
"github.com/ethereum/go-ethereum/common/hexutil"
"github.com/ethereum/go-ethereum/rlp"
)
//go:generate gencodec -type Log -field-override logMarshaling -out gen_log_json.go
// Log represents a contract log event. These events are generated by the LOG opcode and
// stored/indexed by the node.
type Log struct {
// Consensus fields:
// address of the contract that generated the event
Address common.Address `json:"address" gencodec:"required"`
// list of topics provided by the contract.
Topics []common.Hash `json:"topics" gencodec:"required"`
// supplied by the contract, usually ABI-encoded
Data []byte `json:"data" gencodec:"required"`
// Derived fields. These fields are filled in by the node
// but not secured by consensus.
// block in which the transaction was included
BlockNumber uint64 `json:"blockNumber"`
// hash of the transaction
TxHash common.Hash `json:"transactionHash" gencodec:"required"`
// index of the transaction in the block
TxIndex uint `json:"transactionIndex" gencodec:"required"`
// hash of the block in which the transaction was included
BlockHash common.Hash `json:"blockHash"`
// index of the log in the receipt
Index uint `json:"logIndex" gencodec:"required"`
// The Removed field is true if this log was reverted due to a chain reorganisation.
// You must pay attention to this field if you receive logs through a filter query.
Removed bool `json:"removed"`
}
type logMarshaling struct {
Data hexutil.Bytes
BlockNumber hexutil.Uint64
TxIndex hexutil.Uint
Index hexutil.Uint
}
type rlpLog struct {
Address common.Address
Topics []common.Hash
Data []byte
}
type rlpStorageLog struct {
Address common.Address
Topics []common.Hash
Data []byte
BlockNumber uint64
TxHash common.Hash
TxIndex uint
BlockHash common.Hash
Index uint
}
// EncodeRLP implements rlp.Encoder.
func (l *Log) EncodeRLP(w io.Writer) error {
return rlp.Encode(w, rlpLog{Address: l.Address, Topics: l.Topics, Data: l.Data})
}
// DecodeRLP implements rlp.Decoder.
func (l *Log) DecodeRLP(s *rlp.Stream) error {
var dec rlpLog
err := s.Decode(&dec)
if err == nil {
l.Address, l.Topics, l.Data = dec.Address, dec.Topics, dec.Data
}
return err
}
// LogForStorage is a wrapper around a Log that flattens and parses the entire content of
// a log including non-consensus fields.
type LogForStorage Log
// EncodeRLP implements rlp.Encoder.
func (l *LogForStorage) EncodeRLP(w io.Writer) error {
return rlp.Encode(w, rlpStorageLog{
Address: l.Address,
Topics: l.Topics,
Data: l.Data,
BlockNumber: l.BlockNumber,
TxHash: l.TxHash,
TxIndex: l.TxIndex,
BlockHash: l.BlockHash,
Index: l.Index,
})
}
// DecodeRLP implements rlp.Decoder.
func (l *LogForStorage) DecodeRLP(s *rlp.Stream) error {
var dec rlpStorageLog
err := s.Decode(&dec)
if err == nil {
*l = LogForStorage{
Address: dec.Address,
Topics: dec.Topics,
Data: dec.Data,
BlockNumber: dec.BlockNumber,
TxHash: dec.TxHash,
TxIndex: dec.TxIndex,
BlockHash: dec.BlockHash,
Index: dec.Index,
}
}
return err
}
Appendix A. 总体批注
文件 core/types/log.go 中主要定义了数据结构 Log，用于表示合约的一个日志事件。
数据结构 Log 中包含共识字段和派生字段两部分。
- 由数据结构 logMarshaling 表示某些字段的 JSON 编码。
- 共识字段支持 RLP 编码，由数据结构 rlpLog 表示。
- 数据结构 logMarshaling、rlpLog、rlpStorageLog 是流形式。
- 通过方法 EncodeRLP() 编码 Log。
- 通过方法 DecodeRLP() 解码 Log。
数据结构 LogForStorage 只是 Log 的封装器，便于与数据结构 rlpStorageLog 进行映射。
- 通过方法 EncodeRLP() 编码由 LogForStorage 临时构建的 rlpStorageLog。
- 通过方法 DecodeRLP() 解码成临时的 rlpStorageLog，再还原出 LogForStorage。
Appendix B. 详细批注
type Log struct
Log 表示合约的一个日志事件。 这些事件由 LOG 操作码生成并且由节点存储和索引。
// Consensus fields:
Address common.Address： 生成事件的合约地址
Topics []common.Hash： 由合约提供的主题列表
Data []byte： 由合约提供，通常是 ABI 编码的
// Derived fields. These fields are filled in by the node
// but not secured by consensus.
BlockNumber uint64： 事务所属的区块
TxHash common.Hash： 事务的哈希
TxIndex uint： 事务在区块中的索引
BlockHash common.Hash： 事务所属的区块的哈希
Index uint： Log 在 Receipt 中的索引
Removed bool： 如果由于链重新组织导致 Log 被恢复则此字段为 true。如果是通过过滤器查询接收此日志，则必须小心此字段。
- func (l *Log) EncodeRLP(w io.Writer) error
方法 EncodeRLP() 实现了 rlp.Encoder 接口，并将 Log 的共识字段扁平化成 RLP 流。
将 Log 的 RLP 编码写入到参数 w 中。
- 具体的实现是调用函数 rlp.Encode() 完成的。
- func (l *Log) DecodeRLP(s *rlp.Stream) error
方法 DecodeRLP() 实现了 rlp.Decoder 接口，并从 RLP 流中加载 Log 的共识字段。
从参数 s 中加载共识字段。
- 具体的实现是调用方法 rlp.Stream.Decode() 完成的。
type logMarshaling struct
Log 的 JSON 编码。
各字段的意义同 Log 中的同名字段。
- Data hexutil.Bytes：
- BlockNumber hexutil.Uint64：
- TxIndex hexutil.Uint：
- Index hexutil.Uint：
type rlpLog struct
Log 的 RLP 编码。
各字段的意义同 Log 中的同名字段。
- Address common.Address
- Topics []common.Hash
- Data []byte
type rlpStorageLog struct
Log RLP 编码后的存储结构，包含了 Log 的大部分字段。
各字段的意义同 Log 中的同名字段。
- Address common.Address
- Topics []common.Hash
- Data []byte
- BlockNumber uint64
- TxHash common.Hash
- TxIndex uint
- BlockHash common.Hash
- Index uint
type LogForStorage Log
LogForStorage 是 Log 的封装器，用于扁平化和分析 Log 的整个内容，而不仅仅是原始的共识字段。
- func (l *LogForStorage) EncodeRLP(w io.Writer) error
方法 EncodeRLP() 实现了 rlp.Encoder 接口，并将 LogForStorage 的所有字段扁平化成 RLP 流。
将 LogForStorage 的 RLP 编码写入到参数 w 中。
- 具体的实现是调用函数 rlp.Encode() 完成的。
- 将临时创建的 rlpStorageLog 编码成 RLP 流。
- func (l *LogForStorage) DecodeRLP(s *rlp.Stream) error
方法 DecodeRLP() 实现了 rlp.Decoder 接口，并从 RLP 流中加载 LogForStorage 的所有字段。
从参数 s 中同时加载共识字段和实现字段。
- 具体的实现是调用方法 rlp.Stream.Decode() 完成的。
- 从解码后的 receiptStorageRLP 中还原其它字段。
Reference
Contributor
- Windstamp
