ethereumjs/ethereumjs-block-2-api

https://github.com/ethereumjs/ethereumjs-block/blob/master/docs/index.md

详细的调用代码可见本博客的ethereumjs/ethereumjs-block-3-tests

1.Block区块

Creates a new block object创建一个区块对象

Parameters输入参数

• data (Array | Buffer | Object) 相关数据
  
• opts Array Options 选项
  • opts.chain (String | Number) The chain for the block [default: 'mainnet'] 区块连接的链（默认为主链mainnet）
  • opts.hardfork String Hardfork for the block [default: null, block number-based behaviour]  区块的分支（默认为null，区块基于数量的行为，当区块的数量大于协议中的数量时就会进行分叉）
  • opts.common Object Alternatively pass a Common instance (ethereumjs-common) instead of setting chain/hardfork directly  可选地传递Common实例 (ethereumjs-common)以替代直接设置上面的chain/hardfork

Properties属性

• header Header the block's header  区块的头
• uncleList Array<Header> an array of uncle headers  叔块头的数组
• raw Array<Buffer> an array of buffers containing the raw blocks.  包含原始区块的buffers数组

调用：

const block1 = new Block(null, { 'chain': 'ropsten' }) //初始化，一种是提供chain/hardfork
const common = new Common('ropsten')
const block2 = new Block(null, { 'common': common })//另一种则是使用common，common和chain不能同时提供，会报错

const testData = require('./bcBlockGasLimitTest.json').tests
const bcBlockGasLimigTestData = testData.BlockGasLimit2p63m1

Object.keys(bcBlockGasLimigTestData).forEach(key => {
var parentBlock = new Block(rlp.decode(bcBlockGasLimigTestData[key].genesisRLP)) //使用genesisRLP初始化block得到的是父区块
var block = new Block(rlp.decode(bcBlockGasLimigTestData[key].blocks[].rlp)) //使用blocks[0].rlp初始化block得到的是本区块
block.header.validateGasLimit(parentBlock)//true
    })

hash

Produces a hash the RLP of the block  生成区块的RLP的hash值

调用：

var common = new Common('ropsten')
var genesisBlock = new Block(null, { common: common })
genesisBlock.setGenesisParams()
console.log(genesisBlock.hash().toString('hex') === common.genesis().hash.slice()) //true

isGenisis

Determines if a given block is the genesis block 定义给定的区块是否时创世区块

Returns any Boolean 返回任何布尔值

调用：

var block = new Block()
block.isGenesis()//查看是否为初始区块，为false
block.header.number = Buffer.from([])//决定因素是block.header.number，设置为空数组buffer即可
block.isGenesis()// true

setGenesisParams

turns the block into the canonical genesis block  将区块变为规范创世区块

调用：

const block1 = new Block(null, { 'chain': 'ropsten' }) //初始化，一种是提供chain/hardfork
const common = new Common('ropsten')
const block2 = new Block(null, { 'common': common })//另一种则是使用common，common和chain不能同时提供，会报错
block1.setGenesisParams()//就是将该区块设置为规范初始区块
block2.setGenesisParams()
)//因为两个都设置为规范初始区块，所以相应的值是相同的
block1.hash().toString('hex')
block2.hash().toString('hex'

serialize

Produces a serialization of the block.  生成块的序列化

Parameters 参数

• rlpEncode Boolean whether to rlp encode the block or not 是否对区块进行rlp编码

调用：

const testDataGenesis = require('./genesishashestest.json').test//(初始区块信息)
var genesisBlock = new Block()
genesisBlock.setGenesisParams()//设置为初始区块
var rlp = genesisBlock.serialize() //序列化，就是将其生产rlp格式
console.log(rlp.toString('hex') === testDataGenesis.genesis_rlp_hex) //true
console.log(genesisBlock.hash().toString('hex') === testDataGenesis.genesis_hash) //true

genTxTrie

Generate transaction trie. The tx trie must be generated before the transaction trie can be validated with validateTransactionTrie


生成交易前缀树。交易前缀树一定要在交易前缀树能够被validateTransactionTrie验证之前生成

Parameters参数

• cb Function the callback 回调函数

调用：

const block = new Block(null, { 'chain': 'ropsten' })
block.genTxTrie(function () {//必须要先生成了前缀树后才能调用验证前缀树的操作
    block.validateTransactionsTrie()// true
})

validateTransactionTrie

Validates the transaction trie 验证交易前缀树

Returns Boolean

调用看上面

validateTransactions

Validates the transactions 验证交易

Parameters输入参数

• stringError Boolean? whether to return a string with a description of why the validation failed or return a Bloolean (optional, default false) 是否返回带有描述验证失败原因的字符串或返回一个布尔值（可选，默认为false）

Returns Boolean

调用：

const block = new Block(null, { 'chain': 'ropsten' })
block.validateTransactions()// true

validate

Validates the entire block. Returns a string to the callback if block is invalid 验证整个区块。如果区块无效则返回字符串给回调函数

Parameters输入参数

• blockChain BlockChain the blockchain that this block wants to be part of 区块想要加入的区块链
• cb Function the callback which is given a String if the block is not valid 如果区块无效将会提供给字符串的回调函数

validateUncleHash

Validates the uncle's hash 验证叔块的hash

Returns Boolean

调用：

const testData2 = require('./testdata2.json')
var block = new Block(rlp.decode(testData2.blocks[].rlp)) //从区块信息文件生成相同区块
block.validateUnclesHash()// true，验证该区块的叔块hash

validateUncles

Validates the uncles that are in the block if any. Returns a string to the callback if uncles are invalid

如果区块中有叔块，则对其进行验证

Parameters

• blockChaina Blockchain an instance of the Blockchain 区块链实例
• cb Function the callback 回调函数
• blockChain


toJSON

Converts the block to JSON

将区块转换成JSON格式

Parameters输入参数

• labeled Bool whether to create an labeled object or an array 是否要创建一个标签对象或一个数组

Returns Object

调用：

var block = new Block(rlp.decode(testData2.blocks[].rlp))
console.log(typeof (block.toJSON()) === 'object') //true

2.BlockHeader区块头

An object that repersents the block header 代表区块头的对象

Parameters输入参数

• data Array raw data, deserialized 原始数据，非序列化
• opts Array Options
  • opts.chain (String | Number) The chain for the block header [default: 'mainnet']  区块连接的链（默认为主链mainnet）
  • opts.hardfork String Hardfork for the block header [default: null, block number-based behaviour] 区块的分支（默认为null，区块基于数量的行为，当区块的数量大于协议中的数量时就会进行分叉）
  • opts.common Object Alternatively pass a Common instance instead of setting chain/hardfork directly 可选地传递Common实例 (ethereumjs-common)以替代直接设置上面的chain/hardfork

Properties属性

• parentHash Buffer the blocks' parent's hash  区块的父区块的hash值
• uncleHash Buffer sha3(rlp_encode(uncle_list))   叔块列表的rlp编码的hash值
• coinbase Buffer the miner address  矿工的地址
• stateRoot Buffer The root of a Merkle Patricia tree  Merkle Patricia树的根
• transactionTrie Buffer the root of a Trie containing the transactions 包含交易的前缀树的根
• receiptTrie Buffer the root of a Trie containing the transaction Reciept  包含交易收据的前缀树的根
• bloom Buffer
• difficulty Buffer 设置的挖矿的困难度
• number Buffer the block's height 区块的高度
• gasLimit Buffer 使用gas的限制
• gasUsed Buffer  真正使用的gas
• timestamp Buffer  区块的时间戳
• extraData Buffer 额外的数据
• raw Array<Buffer> an array of buffers containing the raw blocks. 包含原始区块的buffers数组

调用：

const header1 = new Header(null, { 'chain': 'ropsten' }) //初始化，一种是提供chain/hardfork
const common = new Common('ropsten')
const header2 = new Header(null, { 'common': common })//另一种则是使用common，common和chain不能同时提供，会报错

canonicalDifficulty

Returns the canoncical difficulty of the block

返回区块头的规范困难度

Parameters输入参数

• parentBlock Block the parent Block of the this header 这个区块头的父区块

Returns BN

从父区块得到的区块头规范困难度与当前区块头的困难度应该是相等的

validateDifficulty

checks that the block's difficuly matches the canonical difficulty

查看区块头是否符合规范困难度的区块困难度

Parameters

• parentBlock Block this block's parent 这个区块的父区块

Returns Boolean

validateGasLimit

Validates the gasLimit

验证gas限制

Parameters

• parentBlock Block this block's parent 区块的父区块

Returns Boolean

validate

Validates the entire block header

验证整个区块头

Parameters输入参数

• blockChain Blockchain the blockchain that this block is validating against 验证区块所在的区块链
• height Bignum? if this is an uncle header, this is the height of the block that is including it 如果是一个叔块头，这将是包含这个叔块区块的区块的高度
• cb Function the callback function. The callback is given an error if the block is invalid 回调函数。如果区块无效，回调则返回错误
• blockchain

hash

Returns the sha3 hash of the blockheader

返回区块头的sha3 hash值

Returns Buffer

isGenesis

checks if the blockheader is a genesis header

查看区块头是否是初始区块头

Returns Boolean

调用：

var header = new Header() //查看该区块头是否为初始区块
header.isGenesis()//false)
header.number = Buffer.from([]) //通过设置header.number为空buffer数组就能得到是初始区块的结果
header.isGenesis()// true

setGenesisParams

turns the header into the canonical genesis block header

转换该区块成规范初始区块头

调用：

const header2 = new Header(null, { 'common': common })//使用common初始化，common和chain不能同时提供，会报错
header1.setGenesisParams()//就是将该区块头设置为规范初始区块头