nimbus-eth1/nimbus/core/pow.nim

347 lines
12 KiB
Nim

# Nimbus
# Copyright (c) 2018 Status Research & Development GmbH
# Licensed under either of
# * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
# http://www.apache.org/licenses/LICENSE-2.0)
# * MIT license ([LICENSE-MIT](LICENSE-MIT) or
# http://opensource.org/licenses/MIT)
# at your option. This file may not be copied, modified, or distributed except
# according to those terms.
## Block PoW Support (Verifying & Mining)
## ======================================
##
import
std/[options, strutils],
../utils/utils,
./pow/[pow_cache, pow_dataset],
eth/[common, keys, p2p, rlp],
ethash,
stint
{.push raises: [Defect].}
type
PowDigest = tuple ##\
## Return value from the `hashimotoLight()` function
mixDigest: Hash256
value: Hash256
PowSpecs* = object ##\
## Relevant block header parts for PoW mining & verifying. This object
## might be more useful for testing and debugging than for production.
blockNumber*: BlockNumber
miningHash*: Hash256
nonce*: BlockNonce
mixDigest*: Hash256
difficulty*: DifficultyInt
PowHeader = object ##\
## Stolen from `p2p/validate.MiningHeader`
parentHash : Hash256
ommersHash : Hash256
coinbase : EthAddress
stateRoot : Hash256
txRoot : Hash256
receiptRoot : Hash256
bloom : common.BloomFilter
difficulty : DifficultyInt
blockNumber : BlockNumber
gasLimit : GasInt
gasUsed : GasInt
timestamp : EthTime
extraData : Blob
PowRef* = ref object of RootObj ##\
## PoW context descriptor
lightByEpoch: PowCacheRef ## PoW cache indexed by epoch
fullByEpoch: PowDatasetRef ## Ditto for dataset
nonceAttempts: uint64 ## Unsuccessful tests in last mining process
# You should only create one instance of the RNG per application / library
# Ref is used so that it can be shared between components
rng: ref HmacDrbgContext
# ------------------------------------------------------------------------------
# Private functions: RLP support
# ------------------------------------------------------------------------------
proc append(w: var RlpWriter; specs: PowSpecs) =
## RLP support
w.startList(5)
w.append(HashOrNum(isHash: false, number: specs.blockNumber))
w.append(HashOrNum(isHash: true, hash: specs.miningHash))
w.append(specs.nonce.toUint)
w.append(HashOrNum(isHash: true, hash: specs.mixDigest))
w.append(specs.difficulty)
proc read(rlp: var Rlp; Q: type PowSpecs): Q
{.raises: [Defect,RlpError].} =
## RLP support
rlp.tryEnterList()
result.blockNumber = rlp.read(HashOrNum).number
result.miningHash = rlp.read(HashOrNum).hash
result.nonce = rlp.read(uint64).toBlockNonce
result.mixDigest = rlp.read(HashOrNum).hash
result.difficulty = rlp.read(DifficultyInt)
proc rlpTextEncode(specs: PowSpecs): string =
"specs #" & $specs.blockNumber & " " & rlp.encode(specs).toHex
proc decodeRlpText(data: string): PowSpecs
{.raises: [Defect,CatchableError].} =
if 180 < data.len and data[0 .. 6] == "specs #":
let hexData = data.split
if hexData.len == 3:
var rlpData = hexData[2].rlpFromHex
result = rlpData.read(PowSpecs)
# ------------------------------------------------------------------------------
# Private functions
# ------------------------------------------------------------------------------
proc miningHash(header: BlockHeader): Hash256 =
## Calculate hash from mining relevant fields of the argument `header`
let miningHeader = PowHeader(
parentHash: header.parentHash,
ommersHash: header.ommersHash,
coinbase: header.coinbase,
stateRoot: header.stateRoot,
txRoot: header.txRoot,
receiptRoot: header.receiptRoot,
bloom: header.bloom,
difficulty: header.difficulty,
blockNumber: header.blockNumber,
gasLimit: header.gasLimit,
gasUsed: header.gasUsed,
timestamp: header.timestamp,
extraData: header.extraData)
rlp.encode(miningHeader).keccakHash
# ---------------
proc tryNonceFull(nonce: uint64;
ds: PowDatasetItemRef; hash: Hash256): UInt256 =
let
rc = hashimotoFull(ds.size, ds.data, hash, nonce)
value = readUintBE[256](rc.value.data)
# echo ">>> nonce=", nonce.toHex, " value=", value.toHex
return value
proc mineFull(tm: PowRef; blockNumber: BlockNumber; powHeaderDigest: Hash256,
difficulty: DifficultyInt; startNonce: BlockNonce): uint64
{.gcsafe,raises: [Defect,CatchableError].} =
## Returns a valid nonce. This function was inspired by the function
## python function `mine()` from
## `ethash <https://eth.wiki/en/concepts/ethash/ethash>`_.
result = startNonce.toUint
if difficulty.isZero:
# Ooops???
return
let
ds = tm.fullByEpoch.get(blockNumber)
valueMax = UInt256.high div difficulty
while valueMax < result.tryNonceFull(ds, powHeaderDigest):
result.inc # rely on uint overflow mod 2^64
# Book keeping, debugging support
tm.nonceAttempts = if result <= startNonce.toUint:
startNonce.toUint - result
else:
(uint64.high - startNonce.toUint) + result
# ---------------
proc init(tm: PowRef;
rng: Option[ref HmacDrbgContext];
light: Option[PowCacheRef];
full: Option[PowDatasetRef]) =
## Constructor
if rng.isSome:
tm.rng = rng.get
else:
tm.rng = newRng()
if light.isSome:
tm.lightByEpoch = light.get
else:
tm.lightByEpoch = PowCacheRef.new
if full.isSome:
tm.fullByEpoch = full.get
else:
tm.fullByEpoch = PowDatasetRef.new(cache = tm.lightByEpoch)
# ------------------------------------------------------------------------------
# Public functions, Constructor
# ------------------------------------------------------------------------------
proc new*(T: type PowRef;
rng: ref HmacDrbgContext;
cache: PowCacheRef;
dataset: PowDatasetRef): T =
## Constructor
new result
result.init(
some(rng), some(cache), some(dataset))
proc new*(T: type PowRef; cache: PowCacheRef; dataset: PowDatasetRef): T =
## Constructor
new result
result.init(
none(ref HmacDrbgContext), some(cache), some(dataset))
proc new*(T: type PowRef; rng: ref HmacDrbgContext): T =
## Constructor
new result
result.init(
some(rng), none(PowCacheRef), none(PowDatasetRef))
proc new*(T: type PowRef): T =
## Constructor
new result
result.init(
none(ref HmacDrbgContext), none(PowCacheRef), none(PowDatasetRef))
# ------------------------------------------------------------------------------
# Public functions
# ------------------------------------------------------------------------------
proc getPowSpecs*(header: BlockHeader): PowSpecs =
## Extracts relevant parts from the `header` argument that are needed
## for mining or pow verification. This function might be more useful for
## testing and debugging than for production.
PowSpecs(
blockNumber: header.blockNumber,
miningHash: header.miningHash,
nonce: header.nonce,
mixDigest: header.mixDigest,
difficulty: header.difficulty)
proc getPowCacheLookup*(tm: PowRef;
blockNumber: BlockNumber): (uint64, Hash256)
{.gcsafe, raises: [KeyError, Defect, CatchableError].} =
## Returns the pair `(size,digest)` derived from the lookup cache for the
## `hashimotoLight()` function for the given block number. The `size` is the
## full size of the dataset (the cache represents) as passed on to the
## `hashimotoLight()` function. The `digest` is a hash derived from the
## cache that would be passed on to `hashimotoLight()`.
##
## This function is intended for error reporting and might also be useful
## for testing and debugging.
let ds = tm.lightByEpoch.get(blockNumber)
if ds == nil:
raise newException(KeyError, "block not found")
result[0] = ds.size
result[1] = withKeccakHash:
for a in ds.data:
h.update(a.data)
# ------------------------
proc getPowDigest*(tm: PowRef; blockNumber: BlockNumber;
powHeaderDigest: Hash256; nonce: BlockNonce): PowDigest
{.gcsafe,raises: [Defect,CatchableError].} =
## Calculate the expected value of `header.mixDigest` using the
## `hashimotoLight()` library method.
let
ds = tm.lightByEpoch.get(blockNumber)
u64Nonce = uint64.fromBytesBE(nonce)
hashimotoLight(ds.size, ds.data, powHeaderDigest, u64Nonce)
proc getPowDigest*(tm: PowRef; header: BlockHeader): PowDigest
{.gcsafe,raises: [Defect,CatchableError].} =
## Variant of `getPowDigest()`
tm.getPowDigest(header.blockNumber, header.miningHash, header.nonce)
proc getPowDigest*(tm: PowRef; specs: PowSpecs): PowDigest
{.gcsafe,raises: [Defect,CatchableError].} =
## Variant of `getPowDigest()`
tm.getPowDigest(specs.blockNumber, specs.miningHash, specs.nonce)
# ------------------
proc getNonce*(tm: PowRef; number: BlockNumber; powHeaderDigest: Hash256;
difficulty: DifficultyInt; startNonce: BlockNonce): BlockNonce
{.gcsafe,raises: [Defect,CatchableError].} =
## Mining function that calculates the value of a `nonce` satisfying the
## difficulty challenge. This is the most basic function of the
## `getNonce()` series with explicit argument `startNonce`. If this is
## a valid `nonce` already, the function stops and returns that value.
## Otherwise it derives other nonces from the `startNonce` start and
## continues trying.
##
## The function depends on a mining dataset which can be generated with
## `generatePowDataset()` before that function is invoked.
##
## This mining logic was inspired by the Python function `mine()` from
## `ethash <https://eth.wiki/en/concepts/ethash/ethash>`_.
tm.mineFull(number, powHeaderDigest, difficulty, startNonce).toBytesBE
proc getNonce*(tm: PowRef; number: BlockNumber; powHeaderDigest: Hash256;
difficulty: DifficultyInt): BlockNonce
{.gcsafe,raises: [Defect,CatchableError].} =
## Variant of `getNonce()`
var startNonce: array[8,byte]
tm.rng[].generate(startNonce)
tm.getNonce(number, powHeaderDigest, difficulty, startNonce)
proc getNonce*(tm: PowRef; header: BlockHeader): BlockNonce
{.gcsafe,raises: [Defect,CatchableError].} =
## Variant of `getNonce()`
tm.getNonce(header.blockNumber, header.miningHash, header.difficulty)
proc getNonce*(tm: PowRef; specs: PowSpecs): BlockNonce
{.gcsafe,raises: [Defect,CatchableError].} =
## Variant of `getNonce()`
tm.getNonce(specs.blockNumber, specs.miningHash, specs.difficulty)
proc nGetNonce*(tm: PowRef): uint64 =
## Number of unsucchessful internal tests in the last invocation
## of `getNonce()`.
tm.nonceAttempts
# ------------------
proc generatePowDataset*(tm: PowRef; number: BlockNumber)
{.gcsafe,raises: [Defect,CatchableError].} =
## Prepare dataset for the `getNonce()` mining function. This dataset
## changes with the epoch of the argument `number` so it is applicable for
## the full epoch. If not generated explicitely, it will be done so by the
## next invocation of `getNonce()`.
##
## This is a slow process which produces a huge data table. So expect this
## function to hang on for a while and do not mind if the OS starts swapping.
## A list of the data sizes indexed by epoch is available at the end of
## the `ethash <https://eth.wiki/en/concepts/ethash/ethash>`_ Python
## reference implementation.
discard tm.fullByEpoch.get(number)
# ------------------------------------------------------------------------------
# Public functions, debugging & testing
# ------------------------------------------------------------------------------
proc dumpPowSpecs*(specs: PowSpecs): string =
## Text representation of `PowSpecs` argument object
specs.rlpTextEncode
proc dumpPowSpecs*(header: BlockHeader): string =
## Variant of `dumpPowSpecs()`
header.getPowSpecs.dumpPowSpecs
proc undumpPowSpecs*(data: string): PowSpecs
{.raises: [Defect,CatchableError].} =
## Recover `PowSpecs` object from text representation
data.decodeRlpText
# ------------------------------------------------------------------------------
# End
# ------------------------------------------------------------------------------