Go-ethereum 源碼解析之 consensus/clique/snapshot.go

package clique

import (
    "bytes"
    "encoding/json"
    "sort"

    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/core/types"
    "github.com/ethereum/go-ethereum/ethdb"
    "github.com/ethereum/go-ethereum/params"
    lru "github.com/hashicorp/golang-lru"
)

// Vote represents a single vote that an authorized signer made to modify the
// list of authorizations.
type Vote struct {
    Signer    common.Address `json:"signer"`    // Authorized signer that cast this vote
    Block     uint64         `json:"block"`     // Block number the vote was cast in (expire old votes)
    Address   common.Address `json:"address"`   // Account being voted on to change its authorization
    Authorize bool           `json:"authorize"` // Whether to authorize or deauthorize the voted account
}

// Tally is a simple vote tally to keep the current score of votes. Votes that
// go against the proposal aren't counted since it's equivalent to not voting.
type Tally struct {
    Authorize bool `json:"authorize"` // Whether the vote is about authorizing or kicking someone
    Votes     int  `json:"votes"`     // Number of votes until now wanting to pass the proposal
}

// Snapshot is the state of the authorization voting at a given point in time.
type Snapshot struct {
    config   *params.CliqueConfig // Consensus engine parameters to fine tune behavior
    sigcache *lru.ARCCache        // Cache of recent block signatures to speed up ecrecover

    Number  uint64                      `json:"number"`  // Block number where the snapshot was created
    Hash    common.Hash                 `json:"hash"`    // Block hash where the snapshot was created
    Signers map[common.Address]struct{} `json:"signers"` // Set of authorized signers at this moment
    Recents map[uint64]common.Address   `json:"recents"` // Set of recent signers for spam protections
    Votes   []*Vote                     `json:"votes"`   // List of votes cast in chronological order
    Tally   map[common.Address]Tally    `json:"tally"`   // Current vote tally to avoid recalculating
}

// signers implements the sort interface to allow sorting a list of addresses
type signers []common.Address

func (s signers) Len() int           { return len(s) }
func (s signers) Less(i, j int) bool { return bytes.Compare(s[i][:], s[j][:]) < 0 }
func (s signers) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }

// newSnapshot creates a new snapshot with the specified startup parameters. This
// method does not initialize the set of recent signers, so only ever use if for
// the genesis block.
func newSnapshot(config *params.CliqueConfig, sigcache *lru.ARCCache, number uint64, hash common.Hash, signers []common.Address) *Snapshot {
    snap := &Snapshot{
        config:   config,
        sigcache: sigcache,
        Number:   number,
        Hash:     hash,
        Signers:  make(map[common.Address]struct{}),
        Recents:  make(map[uint64]common.Address),
        Tally:    make(map[common.Address]Tally),
    }
    for _, signer := range signers {
        snap.Signers[signer] = struct{}{}
    }
    return snap
}

Appendix A. 總體批注

文件 clique/snapshot.go 主要是用于描述 Clique 共識(shí)算法中關(guān)于授權(quán)簽名者列表生成的快照信息炫刷，以及授權(quán)簽名者對(duì)給定區(qū)塊頭列表如何進(jìn)行具體簽名的規(guī)則。

假設(shè)授權(quán)簽名者列表的長(zhǎng)度為 K，當(dāng)前進(jìn)行投票的區(qū)塊編號(hào)為 N苦银，給定區(qū)塊頭中的投票簽名者在有序授權(quán)簽名者列表中的偏移為 P什往，偏移從 0 開始左敌。

快照中包含的主要信息有：

創(chuàng)建快照時(shí)的區(qū)塊編號(hào)
創(chuàng)建快照時(shí)的區(qū)塊哈希
授權(quán)簽名者集合
最近 K/2 + 1 個(gè)區(qū)塊中各區(qū)塊編號(hào)對(duì)應(yīng)的簽名者集合
按區(qū)塊編號(hào)順序投票的投票列表
以及各被投票簽名者的得票計(jì)數(shù)器始苇。

授權(quán)簽名者的具體簽名規(guī)則：

待應(yīng)用簽名的區(qū)塊頭列表需要滿足要求：區(qū)塊的編號(hào)是連續(xù)的绰沥。
K 個(gè)簽名者各自在最近連續(xù)的 K/2 + 1 個(gè)區(qū)塊最多只能投出一票瓦宜。
第 P 個(gè)簽名者只能在滿足 N % K == P 條件的區(qū)塊中進(jìn)行投票蔚万。
對(duì)于一個(gè)投票，得票數(shù)需要超過 K/2临庇，不包括 K/2反璃。

??? 第 1 個(gè)疑問：大多數(shù)時(shí)候在區(qū)塊頭中并不會(huì)進(jìn)行投票，而區(qū)塊頭列表又需要滿足連續(xù)性這個(gè)條件苔巨，但是看代碼中對(duì)于不包含投票的區(qū)塊頭并沒有直接過濾的操作版扩。

??? 第 2 個(gè)疑問：根據(jù)授權(quán)簽名者的具體簽名規(guī)則，在知道 K 的時(shí)候侄泽，能夠推斷出在區(qū)塊 N 中進(jìn)行投票的簽名者為 P礁芦。這在 PoA 聯(lián)盟鏈中會(huì)不會(huì)導(dǎo)致安全漏洞。

!!! 一個(gè) BUG：在投票解除授權(quán)簽名者時(shí)悼尾，存在一個(gè)問題柿扣。當(dāng)授權(quán)簽名者列表中只剩下一個(gè)簽名者，且該簽名者投票解除自己的授權(quán)時(shí)闺魏，會(huì)觸發(fā)此問題未状，導(dǎo)致授權(quán)簽名者列表為空，引起之后用授權(quán)簽名者列表長(zhǎng)度作分母時(shí)的代碼報(bào)除 0 錯(cuò)誤析桥。
- 真正有問題的代碼司草，具體代碼見方法 Snapshot.apply() 中的 delete(snap.Signers, header.Coinbase)。
- 觸發(fā)問題的代碼泡仗，具體代碼見方法 Snapshot.inturn() 中的 return (number % uint64(len(signers))) == uint64(offset)

定義了多種數(shù)據(jù)結(jié)構(gòu)埋虹，如：

數(shù)據(jù)結(jié)構(gòu) Vote 用于描述一次具體的投票信息。
數(shù)據(jù)結(jié)構(gòu) Tally 用于描述一個(gè)簡(jiǎn)單的投票計(jì)數(shù)器娩怎。
數(shù)據(jù)結(jié)構(gòu) Snapshot 用于描述指定時(shí)間點(diǎn)的授權(quán)投票狀態(tài)搔课。
數(shù)據(jù)結(jié)構(gòu) signers 用于描述授權(quán)簽名者列表的封裝器，并實(shí)現(xiàn)了排序接口截亦。數(shù)據(jù)結(jié)構(gòu) singers 支持對(duì)授權(quán)簽名者列表進(jìn)行升序排序爬泥，因此可以計(jì)算出給定簽名者在整個(gè)授權(quán)簽名者列表的有序偏移 P柬讨。

1. type Vote struct

數(shù)據(jù)結(jié)構(gòu) Vote 表示授權(quán)簽名者為了修改授權(quán)列表而進(jìn)行的一次投票。

Signer common.Address：投票的授權(quán)簽名者
Block uint6：投票的區(qū)塊編號(hào)（投票過期）
Address common.Address：被投票的帳戶袍啡，以更改其授權(quán)
Authorize bool：表示是否授權(quán)或取消對(duì)已投票帳戶的授權(quán)

2. type Tally struct

數(shù)據(jù)結(jié)構(gòu) Tally 是一個(gè)簡(jiǎn)單的投票計(jì)數(shù)器踩官，以保持當(dāng)前的投票得分。投票反對(duì)該提案不計(jì)算在內(nèi)葬馋，因?yàn)樗韧诓煌镀薄?/p>

Authorize bool：投票是關(guān)于授權(quán)還是踢某人
Votes int：到目前為止希望通過提案的投票數(shù)

3. type Snapshot struct

數(shù)據(jù)結(jié)構(gòu) Snapshot 表示指定時(shí)間點(diǎn)的授權(quán)投票狀態(tài)卖鲤。

config *params.CliqueConfig：共識(shí)引擎參數(shù)以微調(diào)行為
sigcache *lru.ARCCache：緩存最近的塊簽名以加速函數(shù) ecrecover()
Number uint64: 創(chuàng)建快照的區(qū)塊編號(hào)
Hash common.Hash：創(chuàng)建快照的區(qū)塊哈希
Signers map[common.Address]struct{}：這一刻的授權(quán)簽名者集合
Recents map[uint64]common.Address：一組最近的簽名者集，用于防止 spam 攻擊畴嘶。分別記錄最近 k/2 + 1 次的區(qū)塊編號(hào)對(duì)應(yīng)的簽名者蛋逾。
Votes []*Vote：按區(qū)塊編號(hào)順序投票的投票列表
Tally map[common.Address]Tally：目前的投票計(jì)數(shù)器，以避免重新計(jì)算
通過構(gòu)造函數(shù)
newSnapshot() 使用指定的啟動(dòng)參數(shù)創(chuàng)建新快照窗悯。這種方法不會(huì)初始化最近的簽名者集区匣，所以只能用于創(chuàng)世塊。
通過函數(shù) loadSnapshot() 從數(shù)據(jù)庫加載已經(jīng)存在的快照蒋院。
通過方法 store() 將快照插入數(shù)據(jù)庫亏钩。
通過方法 copy() 會(huì)創(chuàng)建快照的深層副本，但不會(huì)創(chuàng)建單獨(dú)的投票欺旧。
通過方法 validVote() 返回在給定的快照上下文中投出的特定投票是否有意義（例如姑丑，不要嘗試添加已經(jīng)授權(quán)的簽名者）。
通過方法 cast() 往投票計(jì)數(shù)器 Snapshot.tally 中增加新的投票辞友。
通過方法 uncast() 從投票計(jì)數(shù)器 Snapshot.tally 中移除之前的一次投票栅哀。
通過方法 apply() 通過將給定的區(qū)塊頭列表應(yīng)用于原始的快照來生成新的授權(quán)快照。
通過方法 signers() 按升序返回授權(quán)簽名者列表称龙。
通過方法 inturn() 返回簽名者在給定區(qū)塊高度是否是 in-turn 的留拾。

4. type signers []common.Address

封裝器 signers 實(shí)現(xiàn)了排序接口，以允許排序地址列表鲫尊。

通過方法 Len() 返回列表中元素的個(gè)數(shù)痴柔。
通過方法 Less() 比較列表中第 i 個(gè)元素是否比第 j 個(gè)元素的小，如果是返回 true疫向。
通過方法 Swap() 交換列表中第 i 個(gè)元素和第 j 個(gè)元素咳蔚。

Appendix B. 詳細(xì)批注

1. type Vote struct

數(shù)據(jù)結(jié)構(gòu) Vote 表示授權(quán)簽名者為了修改授權(quán)列表而進(jìn)行的一次投票。

Signer common.Address：投票的授權(quán)簽名者
Block uint6：投票的區(qū)塊編號(hào)（投票過期）
Address common.Address：被投票的帳戶搔驼，以更改其授權(quán)
Authorize bool：表示是否授權(quán)或取消對(duì)已投票帳戶的授權(quán)

2. type Tally struct

數(shù)據(jù)結(jié)構(gòu) Tally 是一個(gè)簡(jiǎn)單的投票計(jì)數(shù)器谈火，以保持當(dāng)前的投票得分。投票反對(duì)該提案不計(jì)算在內(nèi)匙奴，因?yàn)樗韧诓煌镀薄?/p>

Authorize bool：投票是關(guān)于授權(quán)還是踢某人
Votes int：到目前為止希望通過提案的投票數(shù)

3. type Snapshot struct

數(shù)據(jù)結(jié)構(gòu) Snapshot 表示指定時(shí)間點(diǎn)的授權(quán)投票狀態(tài)堆巧。

config *params.CliqueConfig：共識(shí)引擎參數(shù)以微調(diào)行為
sigcache *lru.ARCCache：緩存最近的塊簽名以加速函數(shù) ecrecover()
Number uint64: 創(chuàng)建快照的區(qū)塊編號(hào)
Hash common.Hash：創(chuàng)建快照的區(qū)塊哈希
Signers map[common.Address]struct{}：這一刻的授權(quán)簽名者集合
Recents map[uint64]common.Address：一組最近的簽名者集妄荔，用于防止 spam 攻擊泼菌。分別記錄最近 k/2 + 1 次的區(qū)塊編號(hào)對(duì)應(yīng)的簽名者谍肤。
Votes []*Vote：按區(qū)塊編號(hào)順序投票的投票列表
Tally map[common.Address]Tally：目前的投票計(jì)數(shù)器，以避免重新計(jì)算

1. func newSnapshot(config params.CliqueConfig, sigcache lru.ARCCache, number uint64, hash common.Hash, signers []common.Address) *Snapshot

構(gòu)造函數(shù)
newSnapshot() 使用指定的啟動(dòng)參數(shù)創(chuàng)建新快照哗伯。這種方法不會(huì)初始化最近的簽名者集荒揣，所以只能用于創(chuàng)世塊。