1 package blockchain
2 3 import (
4 "container/list"
5 "fmt"
6 block2 "github.com/p9c/p9/pkg/block"
7 "github.com/p9c/p9/pkg/fork"
8 "sync"
9 "time"
10 11 "go.uber.org/atomic"
12 13 "github.com/p9c/p9/pkg/chaincfg"
14 "github.com/p9c/p9/pkg/chainhash"
15 "github.com/p9c/p9/pkg/database"
16 "github.com/p9c/p9/pkg/txscript"
17 "github.com/p9c/p9/pkg/wire"
18 )
19 20 const // maxOrphanBlocks is the maximum number of orphan blocks that can be
21 // queued.
22 maxOrphanBlocks = 100
23 24 // BlockLocator is used to help locate a specific block. The algorithm for building the block locator is to add the
25 // hashes in reverse order until the genesis block is reached. In order to keep the list of locator hashes to a
26 // reasonable number of entries, first the most recent previous 12 block hashes are added, then the step is doubled each
27 // loop iteration to exponentially decrease the number of hashes as a function of the distance from the block being
28 // located. For example: assume a block chain with a side chain as depicted below:
29 //
30 // genesis -> 1 -> 2 -> ... -> 15 -> 16 -> 17 -> 18
31 // \-> 16a -> 17a
32 // The block locator for block 17a would be the hashes of blocks:
33 // [ 17a 16a 15 14 13 12 11 10 9 8 7 6 4... ]
34 type BlockLocator []*chainhash.Hash
35 36 // orphanBlock represents a block that we don't yet have the parent for.
37 // It is a normal block plus an expiration time to prevent caching the orphan
38 // forever.
39 type orphanBlock struct {
40 block *block2.Block
41 expiration time.Time
42 }
43 44 // BestState houses information about the current best block and other info related to the state of the main chain as it
45 // exists from the point of view of the current best block. The BestSnapshot method can be used to obtain access to this
46 // information in a concurrent safe manner and the data will not be changed out from under the caller when chain state
47 // changes occur as the function name implies. However, the returned snapshot must be treated as immutable since it is
48 // shared by all callers.
49 type BestState struct {
50 Hash chainhash.Hash // The hash of the block.
51 Height int32 // The height of the block.
52 Version int32
53 Bits uint32 // The difficulty bits of the block.
54 BlockSize uint64 // The size of the block.
55 BlockWeight uint64 // The weight of the block.
56 NumTxns uint64 // The number of txns in the block.
57 TotalTxns uint64 // The total number of txns in the chain.
58 MedianTime time.Time // Median time as per CalcPastMedianTime.
59 }
60 61 // newBestState returns a new best stats instance for the given parameters.
62 func newBestState(
63 node *BlockNode, blockSize, blockWeight, numTxns,
64 totalTxns uint64, medianTime time.Time,
65 ) *BestState {
66 return &BestState{
67 Hash: node.hash,
68 Height: node.height,
69 Version: node.version,
70 Bits: node.bits,
71 BlockSize: blockSize,
72 BlockWeight: blockWeight,
73 NumTxns: numTxns,
74 TotalTxns: totalTxns,
75 MedianTime: medianTime,
76 }
77 }
78 79 // BlockChain provides functions for working with the bitcoin block chain. It
80 // includes functionality such as rejecting duplicate blocks, ensuring blocks
81 // follow all rules, orphan handling, checkpoint handling, and best chain
82 // selection with reorganization.
83 type BlockChain struct {
84 // The following fields are set when the instance is created and can't be
85 // changed afterwards so there is no need to protect them with a separate mutex.
86 checkpoints []chaincfg.Checkpoint
87 checkpointsByHeight map[int32]*chaincfg.Checkpoint
88 db database.DB
89 params *chaincfg.Params
90 timeSource MedianTimeSource
91 sigCache *txscript.SigCache
92 indexManager IndexManager
93 hashCache *txscript.HashCache
94 // The following fields are calculated based upon the provided chain parameters.
95 // They are also set when the instance is created and can't be changed
96 // afterwards, so there is no need to protect them with a separate mutex.
97 minRetargetTimespan int64 // target timespan / adjustment factor
98 maxRetargetTimespan int64 // target timespan * adjustment factor
99 blocksPerRetarget int32 // target timespan / target time per block
100 // ChainLock protects concurrent access to the vast majority of the fields in this struct below this point.
101 ChainLock sync.RWMutex
102 // These fields are related to the memory block index. They both have their own
103 // locks, however they are often also protected by the chain lock to help
104 // prevent logic races when blocks are being processed. index houses the entire
105 // block index in memory. The block index is a tree-shaped structure. BestChain
106 // tracks the current active chain by making use of an efficient chain view into
107 // the block index.
108 Index *blockIndex
109 BestChain *chainView
110 // These fields are related to handling of orphan blocks. They are protected by
111 // a combination of the chain lock and the orphan lock.
112 orphanLock sync.RWMutex
113 orphans map[chainhash.Hash]*orphanBlock
114 prevOrphans map[chainhash.Hash][]*orphanBlock
115 oldestOrphan *orphanBlock
116 // These fields are related to checkpoint handling. They are protected by the chain lock.
117 nextCheckpoint *chaincfg.Checkpoint
118 checkpointNode *BlockNode
119 // The state is used as a fairly efficient way to cache information about the
120 // current best chain state that is returned to callers when requested. It
121 // operates on the principle of MVCC such that any time a new block becomes the
122 // best block, the state pointer is replaced with a new struct and the old state
123 // is left untouched. In this way, multiple callers can be pointing to different
124 // best chain states. This is acceptable for most callers because the state is
125 // only being queried at a specific point in time. In addition, some of the
126 // fields are stored in the database so the chain state can be quickly
127 // reconstructed on load.
128 stateLock sync.RWMutex
129 stateSnapshot *BestState
130 // // The following caches are used to efficiently keep track of the current deployment threshold state of each rule
131 // // change deployment. This information is stored in the database so it can be quickly reconstructed on load.
132 // // warningCaches caches the current deployment threshold state for blocks in each of the **possible** deployments.
133 // // This is used in order to detect when new unrecognized rule changes are being voted on and/or have been activated
134 // // such as will be the case when older versions of the software are being used deploymentCaches caches the current
135 // // deployment threshold state for blocks in each of the actively defined deployments.
136 //
137 // warningCaches []thresholdStateCache
138 // deploymentCaches []thresholdStateCache
139 // // The following fields are used to determine if certain warnings have already been shown. unknownRulesWarned refers
140 // // to warnings due to unknown rules being activated. unknownVersionsWarned refers to warnings due to unknown
141 // // versions being mined.
142 // unknownRulesWarned bool
143 // unknownVersionsWarned bool
144 // The notifications field stores a slice of callbacks to be executed on certain
145 // blockchain events.
146 notifications []NotificationCallback
147 notificationsLock sync.RWMutex
148 // DifficultyAdjustments keeps track of the latest difficulty adjustment for each algorithm
149 DifficultyAdjustments map[string]float64
150 DifficultyBits atomic.Value
151 DifficultyHeight atomic.Int32
152 }
153 154 // HaveBlock returns whether or not the chain instance has the block represented
155 // by the passed hash. This includes checking the various places a block can be
156 // like part of the main chain, on a side chain, or in the orphan pool. This
157 // function is safe for concurrent access.
158 func (b *BlockChain) HaveBlock(hash *chainhash.Hash) (bool, error) {
159 exists, e := b.blockExists(hash)
160 if e != nil {
161 return false, e
162 }
163 return exists || b.IsKnownOrphan(hash), nil
164 }
165 166 // IsKnownOrphan returns whether the passed hash is currently a known orphan.
167 // Keep in mind that only a limited number of orphans are held onto for a
168 // limited amount of time so this function must not be used as an absolute way
169 // to test if a block is an orphan block. A full block (as opposed to just its
170 // hash) must be passed to ProcessBlock for that purpose.
171 //
172 // However, calling ProcessBlock with an orphan that already exists results in
173 // an error, so this function provides a mechanism for a caller to intelligently
174 // detect *recent* duplicate orphans and react accordingly. This function is
175 // safe for concurrent access.
176 func (b *BlockChain) IsKnownOrphan(hash *chainhash.Hash) bool {
177 // Protect concurrent access. Using a read lock only so multiple readers can query without blocking each other.
178 b.orphanLock.RLock()
179 _, exists := b.orphans[*hash]
180 b.orphanLock.RUnlock()
181 return exists
182 }
183 184 // GetOrphanRoot returns the head of the chain for the provided hash from the
185 // map of orphan blocks. This function is safe for concurrent access.
186 func (b *BlockChain) GetOrphanRoot(hash *chainhash.Hash) *chainhash.Hash {
187 // Protect concurrent access. Using a read lock only so multiple readers can query without blocking each other.
188 b.orphanLock.RLock()
189 defer b.orphanLock.RUnlock()
190 // Keep looping while the parent of each orphaned block is known and is an orphan itself.
191 orphanRoot := hash
192 prevHash := hash
193 for {
194 orphan, exists := b.orphans[*prevHash]
195 if !exists {
196 break
197 }
198 orphanRoot = prevHash
199 prevHash = &orphan.block.WireBlock().Header.PrevBlock
200 }
201 return orphanRoot
202 }
203 204 // removeOrphanBlock removes the passed orphan block from the orphan pool and
205 // previous orphan index.
206 func (b *BlockChain) removeOrphanBlock(orphan *orphanBlock) {
207 // Protect concurrent access.
208 b.orphanLock.Lock()
209 defer b.orphanLock.Unlock()
210 // Remove the orphan block from the orphan pool.
211 orphanHash := orphan.block.Hash()
212 delete(b.orphans, *orphanHash)
213 // Remove the reference from the previous orphan index too. An indexing for loop
214 // is intentionally used over a range here as range does not reevaluate the
215 // slice on each iteration nor does it adjust the index for the modified slice.
216 prevHash := &orphan.block.WireBlock().Header.PrevBlock
217 orphans := b.prevOrphans[*prevHash]
218 for i := 0; i < len(orphans); i++ {
219 hash := orphans[i].block.Hash()
220 if hash.IsEqual(orphanHash) {
221 copy(orphans[i:], orphans[i+1:])
222 orphans[len(orphans)-1] = nil
223 orphans = orphans[:len(orphans)-1]
224 i--
225 }
226 }
227 b.prevOrphans[*prevHash] = orphans
228 // Remove the map entry altogether if there are no longer any orphans which
229 // depend on the parent hash.
230 if len(b.prevOrphans[*prevHash]) == 0 {
231 delete(b.prevOrphans, *prevHash)
232 }
233 }
234 235 // addOrphanBlock adds the passed block (which is already determined to be an
236 // orphan prior calling this function) to the orphan pool. It lazily cleans up
237 // any expired blocks so a separate cleanup poller doesn't need to be run. It
238 // also imposes a maximum limit on the number of outstanding orphan blocks and
239 // will remove the oldest received orphan block if the limit is exceeded.
240 func (b *BlockChain) addOrphanBlock(block *block2.Block) {
241 // Remove expired orphan blocks.
242 for _, oBlock := range b.orphans {
243 if time.Now().After(oBlock.expiration) {
244 b.removeOrphanBlock(oBlock)
245 continue
246 }
247 // Update the oldest orphan block pointer so it can be discarded in case the orphan pool fills up.
248 if b.oldestOrphan == nil || oBlock.expiration.Before(
249 b.oldestOrphan.
250 expiration,
251 ) {
252 b.oldestOrphan = oBlock
253 }
254 }
255 // Limit orphan blocks to prevent memory exhaustion.
256 if len(b.orphans)+1 > maxOrphanBlocks {
257 // Remove the oldest orphan to make room for the new one.
258 b.removeOrphanBlock(b.oldestOrphan)
259 b.oldestOrphan = nil
260 }
261 // Protect concurrent access. This is intentionally done here instead of near
262 // the top since removeOrphanBlock does its own locking and the range iterator
263 // is not invalidated by removing map entries.
264 b.orphanLock.Lock()
265 defer b.orphanLock.Unlock()
266 // Insert the block into the orphan map with an expiration time 1 hour from now.
267 expiration := time.Now().Add(time.Hour)
268 oBlock := &orphanBlock{
269 block: block,
270 expiration: expiration,
271 }
272 b.orphans[*block.Hash()] = oBlock
273 // Add to previous hash lookup index for faster dependency lookups.
274 prevHash := &block.WireBlock().Header.PrevBlock
275 b.prevOrphans[*prevHash] = append(b.prevOrphans[*prevHash], oBlock)
276 }
277 278 //
279 // // SequenceLock represents the converted relative lock-time in seconds, and absolute block-height for a transaction
280 // // input's relative lock-times. According to SequenceLock after the referenced input has been confirmed within a block a
281 // // transaction spending that input can be included into a block either after 'seconds' (according to past median time)
282 // // or once the 'BlockHeight' has been reached.
283 // type SequenceLock struct {
284 // Seconds int64
285 // BlockHeight int32
286 // }
287 288 // // CalcSequenceLock computes a relative lock-time SequenceLock for the passed transaction using the passed UtxoViewpoint
289 // // to obtain the past median time for blocks in which the referenced inputs of the transactions were included within.
290 // // The generated SequenceLock lock can be used in conjunction with a block height and adjusted median block time to
291 // // determine if all the inputs referenced within a transaction have reached sufficient maturity allowing the candidate
292 // // transaction to be included in a block. This function is safe for concurrent access.
293 // func (b *BlockChain) CalcSequenceLock(tx *util.Tx, utxoView *UtxoViewpoint, mempool bool) (*SequenceLock, error) {
294 // b.chainLock.Lock()
295 // defer b.chainLock.Unlock()
296 // return b.calcSequenceLock(b.BestChain.Tip(), tx, utxoView, mempool)
297 // }
298 299 // // calcSequenceLock computes the relative lock-times for the passed transaction. See the exported version
300 // // CalcSequenceLock for further details. This function MUST be called with the chain state lock held (for writes).
301 // func (b *BlockChain) calcSequenceLock(node *BlockNode, tx *util.Tx, utxoView *UtxoViewpoint, mempool bool) (*SequenceLock, error) {
302 // // A value of -1 for each relative lock type represents a relative time lock value that will allow a transaction to
303 // // be included in a block at any given height or time.
304 // //
305 // // This value is returned as the relative lock time in the case that BIP 68 is disabled, or has not yet been
306 // // activated.
307 // sequenceLock := &SequenceLock{Seconds: -1, BlockHeight: -1}
308 // // The sequence locks semantics are always active for transactions within the mempool.
309 // csvSoftforkActive := mempool
310 // // If we're performing block validation, then we need to query the BIP9 state.
311 // if !csvSoftforkActive {
312 // // Obtain the latest BIP9 version bits state for the CSV-package soft -fork deployment. The adherence of
313 // // sequence locks depends on the current soft-fork state.
314 // csvState, e := b.deploymentState(node.parent, chaincfg.DeploymentCSV)
315 // if e != nil {
316 // // return nil, e
317 // }
318 // csvSoftforkActive = csvState == ThresholdActive
319 // }
320 // // If the transaction's version is less than 2, and BIP 68 has not yet been activated then sequence locks are
321 // // disabled. Additionally, sequence locks don't apply to coinbase transactions Therefore, we return sequence lock
322 // // values of -1 indicating that this transaction can be included within a block at any given height or time.
323 // mTx := tx.MsgTx()
324 // sequenceLockActive := mTx.Version >= 2 && csvSoftforkActive
325 // if !sequenceLockActive || IsCoinBase(tx) {
326 // return sequenceLock, nil
327 // }
328 // // Grab the next height from the PoV of the passed BlockNode to use for inputs present in the mempool.
329 // nextHeight := node.height + 1
330 // for txInIndex, txIn := range mTx.TxIn {
331 // utxo := utxoView.LookupEntry(txIn.PreviousOutPoint)
332 // if utxo == nil {
333 // str := fmt.Sprintf(
334 // "output %v referenced from transaction %s:%d either does not"+
335 // " exist or has already been spent",
336 // txIn.PreviousOutPoint, tx.Hash(), txInIndex,
337 // )
338 // return sequenceLock, ruleError(ErrMissingTxOut, str)
339 // }
340 // // If the input height is set to the mempool height, then we assume the transaction makes it into the next block
341 // // when evaluating its sequence blocks.
342 // inputHeight := utxo.BlockHeight()
343 // if inputHeight == 0x7fffffff {
344 // inputHeight = nextHeight
345 // }
346 // // Given a sequence number, we apply the relative time lock mask in order to obtain the time lock delta required
347 // // before this input can be spent.
348 // sequenceNum := txIn.Sequence
349 // relativeLock := int64(sequenceNum & wire.SequenceLockTimeMask)
350 // switch {
351 // // Relative time locks are disabled for this input, so we can skip any further calculation.
352 // case sequenceNum&wire.SequenceLockTimeDisabled == wire.SequenceLockTimeDisabled:
353 // continue
354 // case sequenceNum&wire.SequenceLockTimeIsSeconds == wire.SequenceLockTimeIsSeconds:
355 // // This input requires a relative time lock expressed in seconds before it can be spent. Therefore, we need
356 // // to query for the block prior to the one in which this input was included within so we can compute the
357 // // past median time for the block prior to the one which included this referenced output.
358 // prevInputHeight := inputHeight - 1
359 // if prevInputHeight < 0 {
360 // prevInputHeight = 0
361 // }
362 // blockNode := node.Ancestor(prevInputHeight)
363 // medianTime := blockNode.CalcPastMedianTime()
364 // // Time based relative time-locks as defined by BIP 68 have a time granularity of RelativeLockSeconds, so we
365 // // shift left by this amount to convert to the proper relative time-lock.
366 // //
367 // // We also subtract one from the relative lock to maintain the original lockTime semantics.
368 // timeLockSeconds := (relativeLock << wire.SequenceLockTimeGranularity) - 1
369 // timeLock := medianTime.Unix() + timeLockSeconds
370 // if timeLock > sequenceLock.Seconds {
371 // sequenceLock.Seconds = timeLock
372 // }
373 // default:
374 // // The relative lock-time for this input is expressed in blocks so we calculate the relative offset from the
375 // // input's height as its converted absolute lock-time.
376 // //
377 // // We subtract one from the relative lock in order to maintain the original lockTime semantics.
378 // blockHeight := inputHeight + int32(relativeLock-1)
379 // if blockHeight > sequenceLock.BlockHeight {
380 // sequenceLock.BlockHeight = blockHeight
381 // }
382 // }
383 // }
384 // return sequenceLock, nil
385 // }
386 387 // // LockTimeToSequence converts the passed relative locktime to a sequence number in accordance to BIP-68. See:
388 // // https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki
389 // // * (Compatibility)
390 // func LockTimeToSequence(isSeconds bool, locktime uint32) uint32 {
391 // // If we're expressing the relative lock time in blocks, then the corresponding sequence number is simply the
392 // // desired input age.
393 // if !isSeconds {
394 // return locktime
395 // }
396 // // Set the 22nd bit which indicates the lock time is in seconds, then shift the locktime over by 9 since the time
397 // // granularity is in 512 -second intervals (2^9). This results in a max lock-time of 33,553, 920 seconds, or 1.1
398 // // years.
399 // return wire.SequenceLockTimeIsSeconds |
400 // locktime>>wire.SequenceLockTimeGranularity
401 // }
402 403 // getReorganizeNodes finds the fork point between the main chain and the passed
404 // node and returns a list of block nodes that would need to be detached from
405 // the main chain and a list of block nodes that would need to be attached to
406 // the fork point ( which will be the end of the main chain after detaching the
407 // returned list of block nodes) in order to reorganize the chain such that the
408 // passed node is the new end of the main chain. The lists will be empty if the
409 // passed node is not on a side chain. This function may modify node statuses in
410 // the block index without flushing. This function MUST be called with the chain
411 // state lock held ( for reads).
412 func (b *BlockChain) getReorganizeNodes(node *BlockNode) (*list.List, *list.List) {
413 attachNodes := list.New()
414 detachNodes := list.New()
415 // Do not reorganize to a known invalid chain. Ancestors deeper than the direct
416 // parent are checked below but this is a quick check before doing more
417 // unnecessary work.
418 if b.Index.NodeStatus(node.parent).KnownInvalid() {
419 b.Index.SetStatusFlags(node, statusInvalidAncestor)
420 return detachNodes, attachNodes
421 }
422 // Find the fork point (if any) adding each block to the list of nodes to attach
423 // to the main tree.
424 //
425 // Push them onto the list in reverse order so they are attached in the appropriate order when iterating the list
426 // later.
427 forkNode := b.BestChain.FindFork(node)
428 invalidChain := false
429 for n := node; n != nil && n != forkNode; n = n.parent {
430 if b.Index.NodeStatus(n).KnownInvalid() {
431 invalidChain = true
432 break
433 }
434 attachNodes.PushFront(n)
435 }
436 // If any of the node's ancestors are invalid, unwind attachNodes, marking each
437 // one as invalid for future reference.
438 if invalidChain {
439 var next *list.Element
440 for e := attachNodes.Front(); e != nil; e = next {
441 next = e.Next()
442 n := attachNodes.Remove(e).(*BlockNode)
443 b.Index.SetStatusFlags(n, statusInvalidAncestor)
444 }
445 return detachNodes, attachNodes
446 }
447 // Start from the end of the main chain and work backwards until the common
448 // ancestor adding each block to the list of nodes to detach from the main
449 // chain.
450 for n := b.BestChain.Tip(); n != nil && n != forkNode; n = n.parent {
451 detachNodes.PushBack(n)
452 }
453 return detachNodes, attachNodes
454 }
455 456 // connectBlock handles connecting the passed node/block to the end of the main
457 // (best) chain.
458 //
459 // This passed utxo view must have all referenced txos the block spends marked
460 // as spent and all of the new txos the block creates added to it.
461 //
462 // In addition, the passed stxos slice must be populated with all of the
463 // information for the spent txos.
464 //
465 // This approach is used because the connection validation that must happen
466 // prior to calling this function requires the same details, so it would be
467 // inefficient to repeat it. This function MUST be called with the chain state
468 // lock held (for writes).
469 func (b *BlockChain) connectBlock(
470 node *BlockNode, block *block2.Block,
471 view *UtxoViewpoint, stxos []SpentTxOut,
472 ) (e error) {
473 // Make sure it's extending the end of the best chain.
474 prevHash := &block.WireBlock().Header.PrevBlock
475 if !prevHash.IsEqual(&b.BestChain.Tip().hash) {
476 str := "connectBlock must be called with a block that extends the" +
477 " main chain"
478 D.Ln(str)
479 return AssertError(str)
480 }
481 // Sanity check the correct number of stxos are provided.
482 if len(stxos) != countSpentOutputs(block) {
483 str := "connectBlock called with inconsistent spent transaction out" +
484 " information"
485 D.Ln(str)
486 return AssertError(str)
487 }
488 489 // // No warnings about unknown rules or versions until the chain is current.
490 // if b.isCurrent() {
491 // // // Warn if any unknown new rules are either about to activate or have already
492 // // // been activated.
493 // // if e := b.warnUnknownRuleActivations(node); E.Chk(e) {
494 // // T.Ln("warnUnknownRuleActivations ", err)
495 // // return e
496 // // }
497 // }
498 // Write any block status changes to DB before updating best state.
499 T.Ln("flushing block status changes to db before updating best state")
500 if e = b.Index.flushToDB(); E.Chk(e) {
501 return e
502 }
503 // Generate a new best state snapshot that will be used to update the database and later memory if all database
504 // updates are successful.
505 b.stateLock.RLock()
506 curTotalTxns := b.stateSnapshot.TotalTxns
507 b.stateLock.RUnlock()
508 numTxns := uint64(len(block.WireBlock().Transactions))
509 blockSize := uint64(block.WireBlock().SerializeSize())
510 blockWeight := uint64(GetBlockWeight(block))
511 state := newBestState(
512 node, blockSize, blockWeight, numTxns,
513 curTotalTxns+numTxns, node.CalcPastMedianTime(),
514 )
515 // Atomically insert info into the database.
516 T.Ln("inserting block into database")
517 e = b.db.Update(
518 func(dbTx database.Tx) (e error) {
519 // update best block state.
520 e = dbPutBestState(dbTx, state, node.workSum)
521 if e != nil {
522 T.Ln("dbPutBestState", e)
523 return e
524 }
525 // Add the block hash and height to the block index which tracks the main chain.
526 e = dbPutBlockIndex(dbTx, block.Hash(), node.height)
527 if e != nil {
528 T.Ln("dbPutBlockIndex", e)
529 return e
530 }
531 // update the utxo set using the state of the utxo view. This entails removing all of the utxos spent and adding
532 // the new ones created by the block.
533 e = dbPutUtxoView(dbTx, view)
534 if e != nil {
535 T.Ln("dbPutUtxoView", e)
536 return e
537 }
538 539 // Update the transaction spend journal by adding a record for the block that contains all txos spent by it.
540 e = dbPutSpendJournalEntry(dbTx, block.Hash(), stxos)
541 if e != nil {
542 T.Ln("dbPutSpendJournalEntry", e)
543 return e
544 }
545 // Allow the index manager to call each of the currently active optional indexes with the block being connected
546 // so they can update themselves accordingly
547 if b.indexManager != nil {
548 e := b.indexManager.ConnectBlock(dbTx, block, stxos)
549 if e != nil {
550 T.Ln("connectBlock ", e)
551 return e
552 }
553 }
554 return nil
555 },
556 )
557 if e != nil {
558 T.Ln("error updating database ", e)
559 return e
560 }
561 // Prune fully spent entries and mark all entries in the view unmodified now that the modifications have been
562 // committed to the database.
563 T.Ln("committing new view")
564 view.commit()
565 566 // This node is now the end of the best chain.
567 T.Ln("setting new chain tip")
568 b.BestChain.SetTip(node)
569 // Update the state for the best block. Notice how this replaces the entire struct instead of updating the existing
570 // one. This effectively allows the old version to act as a snapshot which callers can use freely without needing to
571 // hold a lock for the duration. See the comments on the state variable for more details.
572 b.stateLock.Lock()
573 b.stateSnapshot = state
574 b.stateLock.Unlock()
575 //
576 // // TODO: this should not run if the chain is syncing
577 // tN := time.Now()
578 // tB, e := b.CalcNextRequiredDifficultyPlan9Controller(node)
579 // if e != nil {
580 // L.Script // }
581 // T.Ln(time.Now().Sub(tN), "to compute all block difficulties")
582 // node.Bits = tB
583 //
584 // Notify the caller that the block was connected to the main chain. The caller would typically want to react with
585 // actions such as updating wallets.
586 T.Ln("sending notifications for new block")
587 b.ChainLock.Unlock()
588 b.sendNotification(NTBlockConnected, block)
589 b.ChainLock.Lock()
590 return nil
591 }
592 593 // disconnectBlock handles disconnecting the passed node/block from the end of the main (best) chain. This function MUST
594 // be called with the chain state lock held (for writes).
595 func (b *BlockChain) disconnectBlock(
596 node *BlockNode, block *block2.Block,
597 view *UtxoViewpoint,
598 ) (e error) {
599 // Make sure the node being disconnected is the end of the best chain.
600 if !node.hash.IsEqual(&b.BestChain.Tip().hash) {
601 return AssertError(
602 "disconnectBlock must be called with the block at" +
603 " the end of the main chain",
604 )
605 }
606 // Load the previous block since some details for it are needed below.
607 prevNode := node.parent
608 var prevBlock *block2.Block
609 e = b.db.View(
610 func(dbTx database.Tx) (e error) {
611 prevBlock, e = dbFetchBlockByNode(dbTx, prevNode)
612 return e
613 },
614 )
615 if e != nil {
616 return e
617 }
618 // Write any block status changes to DB before updating best state.
619 e = b.Index.flushToDB()
620 if e != nil {
621 return e
622 }
623 // Generate a new best state snapshot that will be used to update the database and later memory if all database
624 // updates are successful.
625 b.stateLock.RLock()
626 curTotalTxns := b.stateSnapshot.TotalTxns
627 b.stateLock.RUnlock()
628 numTxns := uint64(len(prevBlock.WireBlock().Transactions))
629 blockSize := uint64(prevBlock.WireBlock().SerializeSize())
630 blockWeight := uint64(GetBlockWeight(prevBlock))
631 newTotalTxns := curTotalTxns - uint64(len(block.WireBlock().Transactions))
632 state := newBestState(
633 prevNode, blockSize, blockWeight, numTxns,
634 newTotalTxns, prevNode.CalcPastMedianTime(),
635 )
636 e = b.db.Update(
637 func(dbTx database.Tx) (e error) {
638 // Update best block state.
639 e = dbPutBestState(dbTx, state, node.workSum)
640 if e != nil {
641 return e
642 }
643 // Remove the block hash and height from the block index which tracks the main chain.
644 e = dbRemoveBlockIndex(dbTx, block.Hash(), node.height)
645 if e != nil {
646 return e
647 }
648 // Update the utxo set using the state of the utxo view. This entails restoring all of the utxos spent and
649 // removing the new ones created by the block.
650 e = dbPutUtxoView(dbTx, view)
651 if e != nil {
652 return e
653 }
654 // Before we delete the spend journal entry for this back, we'll fetch it as is so the indexers can utilize if
655 // needed.
656 stxos, e := dbFetchSpendJournalEntry(dbTx, block)
657 if e != nil {
658 return e
659 }
660 // Update the transaction spend journal by removing the record that contains all txos spent by the block.
661 e = dbRemoveSpendJournalEntry(dbTx, block.Hash())
662 if e != nil {
663 return e
664 }
665 // Allow the index manager to call each of the currently active optional indexes with the block being
666 // disconnected so they can update themselves accordingly.
667 if b.indexManager != nil {
668 e := b.indexManager.DisconnectBlock(dbTx, block, stxos)
669 if e != nil {
670 return e
671 }
672 }
673 return nil
674 },
675 )
676 if e != nil {
677 return e
678 }
679 // Prune fully spent entries and mark all entries in the view unmodified now that the modifications have been
680 // committed to the database.
681 view.commit()
682 // This node's parent is now the end of the best chain.
683 b.BestChain.SetTip(node.parent)
684 // Update the state for the best block. Notice how this replaces the entire struct instead of updating the existing
685 // one. This effectively allows the old version to act as a snapshot which callers can use freely without needing to
686 // hold a lock for the duration. See the comments on the state variable for more details.
687 b.stateLock.Lock()
688 b.stateSnapshot = state
689 b.stateLock.Unlock()
690 // Notify the caller that the block was disconnected from the main chain. The caller would typically want to react
691 // with actions such as updating wallets.
692 b.ChainLock.Unlock()
693 b.sendNotification(NTBlockDisconnected, block)
694 b.ChainLock.Lock()
695 return nil
696 }
697 698 // countSpentOutputs returns the number of utxos the passed block spends.
699 func countSpentOutputs(block *block2.Block) int {
700 // Exclude the coinbase transaction since it can't spend anything.
701 var numSpent int
702 for _, tx := range block.Transactions()[1:] {
703 numSpent += len(tx.MsgTx().TxIn)
704 }
705 return numSpent
706 }
707 708 // reorganizeChain reorganizes the block chain by disconnecting the nodes in the detachNodes list and connecting the
709 // nodes in the attach list. It expects that the lists are already in the correct order and are in sync with the end of
710 // the current best chain. Specifically, nodes that are being disconnected must be in reverse order ( think of popping
711 // them off the end of the chain) and nodes the are being attached must be in forwards order ( think pushing them onto
712 // the end of the chain). This function may modify node statuses in the block index without flushing. This function MUST
713 // be called with the chain state lock held ( for writes).
714 func (b *BlockChain) reorganizeChain(detachNodes, attachNodes *list.List) (e error) {
715 // Nothing to do if no reorganize nodes were provided.
716 if detachNodes.Len() == 0 && attachNodes.Len() == 0 {
717 return nil
718 }
719 // Ensure the provided nodes match the current best chain.
720 tip := b.BestChain.Tip()
721 if detachNodes.Len() != 0 {
722 firstDetachNode := detachNodes.Front().Value.(*BlockNode)
723 if firstDetachNode.hash != tip.hash {
724 return AssertError(
725 fmt.Sprintf(
726 "reorganize nodes to detach are "+
727 "not for the current best chain -- first detach node %v, "+
728 "current chain %v", &firstDetachNode.hash, &tip.hash,
729 ),
730 )
731 }
732 }
733 // Ensure the provided nodes are for the same fork point.
734 if attachNodes.Len() != 0 && detachNodes.Len() != 0 {
735 firstAttachNode := attachNodes.Front().Value.(*BlockNode)
736 lastDetachNode := detachNodes.Back().Value.(*BlockNode)
737 if firstAttachNode.parent.hash != lastDetachNode.parent.hash {
738 return AssertError(
739 fmt.Sprintf(
740 "reorganize nodes do not have the same fork point -- first"+
741 " attach parent %v, last detach parent %v",
742 &firstAttachNode.parent.hash, &lastDetachNode.parent.hash,
743 ),
744 )
745 }
746 }
747 // Track the old and new best chains heads.
748 oldBest := tip
749 newBest := tip
750 // All of the blocks to detach and related spend journal entries needed to unspend transaction outputs in the blocks
751 // being disconnected must be loaded from the database during the reorg check phase below and then they are needed
752 // again when doing the actual database updates. Rather than doing two loads, cache the loaded data into these
753 // slices.
754 detachBlocks := make([]*block2.Block, 0, detachNodes.Len())
755 detachSpentTxOuts := make([][]SpentTxOut, 0, detachNodes.Len())
756 attachBlocks := make([]*block2.Block, 0, attachNodes.Len())
757 // Disconnect all of the blocks back to the point of the fork. This entails loading the blocks and their associated
758 // spent txos from the database and using that information to unspend all of the spent txos and remove the utxos
759 // created by the blocks.
760 view := NewUtxoViewpoint()
761 view.SetBestHash(&oldBest.hash)
762 for e := detachNodes.Front(); e != nil; e = e.Next() {
763 n := e.Value.(*BlockNode)
764 var block *block2.Block
765 e := b.db.View(
766 func(dbTx database.Tx) (e error) {
767 block, e = dbFetchBlockByNode(dbTx, n)
768 return e
769 },
770 )
771 if e != nil {
772 return e
773 }
774 if n.hash != *block.Hash() {
775 return AssertError(
776 fmt.Sprintf(
777 "detach block node hash %v ("+
778 "height %v) does not match previous parent block hash %v",
779 &n.hash, n.height, block.Hash(),
780 ),
781 )
782 }
783 // Load all of the utxos referenced by the block that aren't already in the view.
784 e = view.fetchInputUtxos(b.db, block)
785 if e != nil {
786 return e
787 }
788 // Load all of the spent txos for the block from the spend journal.
789 var stxos []SpentTxOut
790 e = b.db.View(
791 func(dbTx database.Tx) (e error) {
792 stxos, e = dbFetchSpendJournalEntry(dbTx, block)
793 return e
794 },
795 )
796 if e != nil {
797 return e
798 }
799 // Store the loaded block and spend journal entry for later.
800 detachBlocks = append(detachBlocks, block)
801 detachSpentTxOuts = append(detachSpentTxOuts, stxos)
802 e = view.disconnectTransactions(b.db, block, stxos)
803 if e != nil {
804 return e
805 }
806 newBest = n.parent
807 }
808 // Set the fork point only if there are nodes to attach since otherwise blocks are only being disconnected and thus
809 // there is no fork point.
810 var forkNode *BlockNode
811 if attachNodes.Len() > 0 {
812 forkNode = newBest
813 }
814 // Perform several checks to verify each block that needs to be attached to the main chain can be connected without
815 // violating any rules and without actually connecting the block.
816 //
817 // NOTE: These checks could be done directly when connecting a block, however the downside to that approach is that
818 // if any of these checks fail after disconnecting some blocks or attaching others, all of the operations have to be
819 // rolled back to get the chain back into the state it was before the rule violation (or other failure). There are
820 // at least a couple of ways accomplish that rollback, but both involve tweaking the chain and/or database. This
821 // approach catches these issues before ever modifying the chain.
822 for e := attachNodes.Front(); e != nil; e = e.Next() {
823 n := e.Value.(*BlockNode)
824 var block *block2.Block
825 er := b.db.View(
826 func(dbTx database.Tx) (e error) {
827 block, e = dbFetchBlockByNode(dbTx, n)
828 return e
829 },
830 )
831 if er != nil {
832 return er
833 }
834 // Store the loaded block for later.
835 attachBlocks = append(attachBlocks, block)
836 // Skip checks if node has already been fully validated. Although checkConnectBlock gets skipped, we still need
837 // to update the UTXO view.
838 if b.Index.NodeStatus(n).KnownValid() {
839 er = view.fetchInputUtxos(b.db, block)
840 if er != nil {
841 return er
842 }
843 er = view.connectTransactions(block, nil)
844 if er != nil {
845 return er
846 }
847 newBest = n
848 continue
849 }
850 // Notice the spent txout details are not requested here and thus will not be generated.
851 //
852 // This is done because the state is not being immediately written to the database, so it is not needed.
853 //
854 // In the case the block is determined to be invalid due to a rule violation, mark it as invalid and mark all of
855 // its descendants as having an invalid ancestor.
856 er = b.checkConnectBlock(n, block, view, nil)
857 if er != nil {
858 if _, ok := er.(RuleError); ok {
859 b.Index.SetStatusFlags(n, statusValidateFailed)
860 for de := e.Next(); de != nil; de = de.Next() {
861 dn := de.Value.(*BlockNode)
862 b.Index.SetStatusFlags(dn, statusInvalidAncestor)
863 }
864 }
865 return er
866 }
867 b.Index.SetStatusFlags(n, statusValid)
868 newBest = n
869 }
870 // Reset the view for the actual connection code below. This is required because the view was previously modified
871 // when checking if the reorg would be successful and the connection code requires the view to be valid from the
872 // viewpoint of each block being connected or disconnected.
873 view = NewUtxoViewpoint()
874 view.SetBestHash(&b.BestChain.Tip().hash)
875 // Disconnect blocks from the main chain.
876 for i, e := 0, detachNodes.Front(); e != nil; i, e = i+1, e.Next() {
877 n := e.Value.(*BlockNode)
878 block := detachBlocks[i]
879 // Load all of the utxos referenced by the block that aren't already in the view.
880 e := view.fetchInputUtxos(b.db, block)
881 if e != nil {
882 return e
883 }
884 // Update the view to unspend all of the spent txos and remove the utxos created by the block.
885 e = view.disconnectTransactions(
886 b.db, block,
887 detachSpentTxOuts[i],
888 )
889 if e != nil {
890 return e
891 }
892 // Update the database and chain state.
893 e = b.disconnectBlock(n, block, view)
894 if e != nil {
895 return e
896 }
897 }
898 // Connect the new best chain blocks.
899 for i, e := 0, attachNodes.Front(); e != nil; i, e = i+1, e.Next() {
900 n := e.Value.(*BlockNode)
901 block := attachBlocks[i]
902 // Load all of the utxos referenced by the block that aren't already in the view.
903 e := view.fetchInputUtxos(b.db, block)
904 if e != nil {
905 return e
906 }
907 // Update the view to mark all utxos referenced by the block as spent and add all transactions being created by
908 // this block to it. Also, provide an stxo slice so the spent txout details are generated.
909 stxos := make([]SpentTxOut, 0, countSpentOutputs(block))
910 e = view.connectTransactions(block, &stxos)
911 if e != nil {
912 return e
913 }
914 // Update the database and chain state.
915 e = b.connectBlock(n, block, view, stxos)
916 if e != nil {
917 return e
918 }
919 }
920 // Log the point where the chain forked and old and new best chain
921 // heads.
922 if forkNode != nil {
923 I.F(
924 "REORGANIZE: Chain forks at %v (height %v)",
925 forkNode.hash, forkNode.height,
926 )
927 }
928 I.F(
929 "REORGANIZE: Old best chain head was %v (height %v)",
930 &oldBest.hash, oldBest.height,
931 )
932 I.F(
933 "REORGANIZE: New best chain head is %v (height %v)",
934 newBest.hash, newBest.height,
935 )
936 return nil
937 }
938 939 // connectBestChain handles connecting the passed block to the chain while respecting proper chain selection according
940 // to the chain with the most proof of work. In the typical case the new block simply extends the main chain.
941 //
942 // However it may also be extending (or creating) a side chain (fork) which may or may not end up becoming the main
943 // chain depending on which fork cumulatively has the most proof of work. It returns whether or not the block ended up
944 // on the main chain (either due to extending the main chain or causing a reorganization to become the main chain).
945 //
946 // The flags modify the behavior of this function as follows:
947 //
948 // - BFFastAdd: Avoids several expensive transaction validation operations.
949 // This is useful when using checkpoints.
950 //
951 // This function MUST be called with the chain state lock held (for writes).
952 func (b *BlockChain) connectBestChain(node *BlockNode, block *block2.Block, flags BehaviorFlags) (bool, error) {
953 T.Ln("running connectBestChain")
954 fastAdd := flags&BFFastAdd == BFFastAdd
955 flushIndexState := func() {
956 // Intentionally ignore errors writing updated node status to DB. If it fails to write, it's not the end of the
957 // world. If the block is valid, we flush in connectBlock and if the block is invalid, the worst that can happen
958 // is we revalidate the block after a restart.
959 if writeErr := b.Index.flushToDB(); writeErr != nil {
960 T.Ln("ScriptError flushing block index changes to disk:", writeErr)
961 }
962 }
963 // We are extending the main (best) chain with a new block. This is the most common case.
964 parentHash := &block.WireBlock().Header.PrevBlock
965 if parentHash.IsEqual(&b.BestChain.Tip().hash) {
966 T.Ln("extending main chain")
967 // Skip checks if node has already been fully validated.
968 fastAdd = fastAdd || b.Index.NodeStatus(node).KnownValid()
969 // Perform several checks to verify the block can be connected to the main chain without violating any rules and
970 // without actually connecting the block.
971 view := NewUtxoViewpoint()
972 view.SetBestHash(parentHash)
973 stxos := make([]SpentTxOut, 0, countSpentOutputs(block))
974 if !fastAdd {
975 e := b.checkConnectBlock(node, block, view, &stxos)
976 if e == nil {
977 b.Index.SetStatusFlags(node, statusValid)
978 } else if _, ok := e.(RuleError); ok {
979 b.Index.SetStatusFlags(node, statusValidateFailed)
980 } else {
981 return false, e
982 }
983 flushIndexState()
984 if e != nil {
985 return false, e
986 }
987 }
988 // In the fast add case the code to check the block connection was skipped, so the utxo view needs to load the
989 // referenced utxos, spend them, and add the new utxos being created by this block.
990 if fastAdd {
991 e := view.fetchInputUtxos(b.db, block)
992 if e != nil {
993 return false, e
994 }
995 e = view.connectTransactions(block, &stxos)
996 if e != nil {
997 return false, e
998 }
999 }
1000 // Connect the block to the main chain.
1001 T.Ln("connecting block to main chain")
1002 var e error
1003 if e = b.connectBlock(node, block, view, stxos); E.Chk(e) {
1004 E.Ln("connect block error: ", e)
1005 // If we got hit with a rule error, then we'll mark that status of the block as invalid and flush the index
1006 // state to disk before returning with the error.
1007 if _, ok := e.(RuleError); ok {
1008 b.Index.SetStatusFlags(node, statusValidateFailed)
1009 }
1010 flushIndexState()
1011 return false, e
1012 }
1013 T.Ln("block connected to main chain")
1014 // If this is fast add, or this block node isn't yet marked as valid, then we'll update its status and flush the
1015 // state to disk again.
1016 if fastAdd || !b.Index.NodeStatus(node).KnownValid() {
1017 b.Index.SetStatusFlags(node, statusValid)
1018 flushIndexState()
1019 }
1020 if fastAdd {
1021 W.F("fastAdd set in the side chain case? %v\n", block.Hash())
1022 }
1023 return true, nil
1024 }
1025 T.Ln("calculating work sum at new node")
1026 node.workSum = CalcWork(node.bits, node.height, node.version)
1027 // We're extending (or creating) a side chain, but the cumulative work for this new side chain is not enough to make
1028 // it the new chain.
1029 if node.workSum.Cmp(b.BestChain.Tip().workSum) <= 0 {
1030 // Log information about how the block is forking the chain.
1031 f := b.BestChain.FindFork(node)
1032 if f.hash.IsEqual(parentHash) {
1033 T.F(
1034 "FORK: Block %v forks the chain at height %d/block %v, "+
1035 "but does not cause a reorganize. workSum=%d",
1036 node.hash, f.height, f.hash, f.workSum,
1037 )
1038 } else {
1039 T.F(
1040 "EXTEND FORK: Height %7d Block %v extends a side chain which"+
1041 " forks the chain at height %d/block %v. workSum=%d",
1042 node.height, node.hash, f.height, f.hash, f.workSum,
1043 )
1044 }
1045 return false, nil
1046 }
1047 // We're extending (or creating) a side chain and the cumulative work for this new side chain is more than the old
1048 // best chain, so this side chain needs to become the main chain. In order to accomplish that, find the common
1049 // ancestor of both sides of the fork, disconnect the blocks that form the ( now) old fork from the main chain, and
1050 // attach the blocks that form the new chain to the main chain starting at the common ancestor (the point where the
1051 // chain forked).
1052 detachNodes, attachNodes := b.getReorganizeNodes(node)
1053 // Reorganize the chain.
1054 W.F("REORGANIZE: block %v is causing a reorganize", node.hash)
1055 e := b.reorganizeChain(detachNodes, attachNodes)
1056 // Either getReorganizeNodes or reorganizeChain could have made unsaved changes to the block index, so flush
1057 // regardless of whether there was an error. The index would only be dirty if the block failed to connect, so we can
1058 // ignore any errors writing.
1059 if writeErr := b.Index.flushToDB(); writeErr != nil {
1060 T.Ln("ScriptError flushing block index changes to disk:", writeErr)
1061 }
1062 return e == nil, e
1063 }
1064 1065 // isCurrent returns whether or not the chain believes it is current. Several factors are used to guess, but the key
1066 // factors that allow the chain to believe it is current are:
1067 //
1068 // - Latest block height is after the latest checkpoint (if enabled)
1069 // - Latest block has a timestamp newer than 24 hours ago
1070 //
1071 // This function MUST be called with the chain state lock held (for reads).
1072 func (b *BlockChain) isCurrent() bool {
1073 // Not current if the latest main (best) chain height is before the latest known good checkpoint (when checkpoints
1074 // are enabled).
1075 checkpoint := b.LatestCheckpoint()
1076 if checkpoint != nil && b.BestChain.Tip().height < checkpoint.Height {
1077 return false
1078 }
1079 // Not current if the latest best block has a timestamp before 24 hours ago. The chain appears to be current if none
1080 // of the checks reported otherwise.
1081 minus24Hours := b.timeSource.AdjustedTime().Add(-24 * time.Hour).Unix()
1082 return b.BestChain.Tip().timestamp >= minus24Hours
1083 }
1084 1085 // IsCurrent returns whether or not the chain believes it is current. Several factors are used to guess, but the key
1086 // factors that allow the chain to believe it is current are:
1087 //
1088 // - Latest block height is after the latest checkpoint (if enabled)
1089 // - Latest block has a timestamp newer than 24 hours ago
1090 //
1091 // This function is safe for concurrent access.
1092 func (b *BlockChain) IsCurrent() bool {
1093 b.ChainLock.RLock()
1094 defer b.ChainLock.RUnlock()
1095 return b.isCurrent()
1096 }
1097 1098 // BestSnapshot returns information about the current best chain block and related state as of the current point in
1099 // time. The returned instance must be treated as immutable since it is shared by all callers. This function is safe for
1100 // concurrent access.
1101 func (b *BlockChain) BestSnapshot() *BestState {
1102 b.stateLock.RLock()
1103 snapshot := b.stateSnapshot
1104 b.stateLock.RUnlock()
1105 return snapshot
1106 }
1107 1108 // HeaderByHash returns the block header identified by the given hash or an error if it doesn't exist.
1109 //
1110 // Note that this will return headers from both the main and side chains.
1111 func (b *BlockChain) HeaderByHash(hash *chainhash.Hash) (bh wire.BlockHeader, e error) {
1112 node := b.Index.LookupNode(hash)
1113 if node == nil {
1114 e = fmt.Errorf("block %s is not known", hash)
1115 return wire.BlockHeader{}, e
1116 }
1117 return node.Header(), nil
1118 }
1119 1120 // MainChainHasBlock returns whether or not the block with the given hash is in the main chain. This function is safe
1121 // for concurrent access.
1122 func (b *BlockChain) MainChainHasBlock(hash *chainhash.Hash) bool {
1123 node := b.Index.LookupNode(hash)
1124 return node != nil && b.BestChain.Contains(node)
1125 }
1126 1127 // BlockLocatorFromHash returns a block locator for the passed block hash. See BlockLocator for details on the algorithm
1128 // used to create a block locator. In addition to the general algorithm referenced above, this function will return the
1129 // block locator for the latest known tip of the main (best) chain if the passed hash is not currently known.
1130 //
1131 // This function is safe for concurrent access.
1132 func (b *BlockChain) BlockLocatorFromHash(hash *chainhash.Hash) BlockLocator {
1133 b.ChainLock.RLock()
1134 node := b.Index.LookupNode(hash)
1135 locator := b.BestChain.blockLocator(node)
1136 b.ChainLock.RUnlock()
1137 return locator
1138 }
1139 1140 // LatestBlockLocator returns a block locator for the latest known tip of the main (best) chain. This function is safe
1141 // for concurrent access.
1142 func (b *BlockChain) LatestBlockLocator() (BlockLocator, error) {
1143 b.ChainLock.RLock()
1144 locator := b.BestChain.BlockLocator(nil)
1145 b.ChainLock.RUnlock()
1146 return locator, nil
1147 }
1148 1149 // BlockHeightByHash returns the height of the block with the given hash in the main chain. This function is safe for
1150 // concurrent access.
1151 func (b *BlockChain) BlockHeightByHash(hash *chainhash.Hash) (int32, error) {
1152 node := b.Index.LookupNode(hash)
1153 if node == nil || !b.BestChain.Contains(node) {
1154 str := fmt.Sprintf(
1155 "BlockHeightByHash: block %s is not in the main"+
1156 " chain", hash,
1157 )
1158 return 0, errNotInMainChain(str)
1159 }
1160 return node.height, nil
1161 }
1162 1163 // BlockHashByHeight returns the hash of the block at the given height in the main chain. This function is safe for
1164 // concurrent access.
1165 func (b *BlockChain) BlockHashByHeight(blockHeight int32) (*chainhash.Hash, error) {
1166 node := b.BestChain.NodeByHeight(blockHeight)
1167 if node == nil {
1168 str := fmt.Sprintf(
1169 "BlockHashByHeight: no block at height %d exists",
1170 blockHeight,
1171 )
1172 return nil, errNotInMainChain(str)
1173 }
1174 return &node.hash, nil
1175 }
1176 1177 // HeightRange returns a range of block hashes for the given start and end heights. It is inclusive of the start height
1178 // and exclusive of the end height. The end height will be limited to the current main chain height.
1179 //
1180 // This function is safe for concurrent access.
1181 func (b *BlockChain) HeightRange(startHeight, endHeight int32) (
1182 []chainhash.
1183 Hash, error,
1184 ) {
1185 // Ensure requested heights are sane.
1186 if startHeight < 0 {
1187 return nil, fmt.Errorf(
1188 "start height of fetch range must not be less"+
1189 " than zero - got %d", startHeight,
1190 )
1191 }
1192 if endHeight < startHeight {
1193 return nil, fmt.Errorf(
1194 "end height of fetch range must not be less"+
1195 " than the start height - got start %d, end %d",
1196 startHeight, endHeight,
1197 )
1198 }
1199 // There is nothing to do when the start and end heights are the same, so return now to avoid the chain view lock.
1200 if startHeight == endHeight {
1201 return nil, nil
1202 }
1203 // Grab a lock on the chain view to prevent it from changing due to a reorg while building the hashes.
1204 b.BestChain.mtx.Lock()
1205 defer b.BestChain.mtx.Unlock()
1206 // When the requested start height is after the most recent best chain height, there is nothing to do.
1207 latestHeight := b.BestChain.tip().height
1208 if startHeight > latestHeight {
1209 return nil, nil
1210 }
1211 // Limit the ending height to the latest height of the chain.
1212 if endHeight > latestHeight+1 {
1213 endHeight = latestHeight + 1
1214 }
1215 // Fetch as many as are available within the specified range.
1216 hashes := make([]chainhash.Hash, 0, endHeight-startHeight)
1217 for i := startHeight; i < endHeight; i++ {
1218 hashes = append(hashes, b.BestChain.nodeByHeight(i).hash)
1219 }
1220 return hashes, nil
1221 }
1222 1223 // HeightToHashRange returns a range of block hashes for the given start height and end hash, inclusive on both ends.
1224 // The hashes are for all blocks that are ancestors of endHash with height greater than or equal to startHeight.
1225 //
1226 // The end hash must belong to a block that is known to be valid.
1227 //
1228 // This function is safe for concurrent access.
1229 func (b *BlockChain) HeightToHashRange(
1230 startHeight int32,
1231 endHash *chainhash.Hash, maxResults int,
1232 ) ([]chainhash.Hash, error) {
1233 endNode := b.Index.LookupNode(endHash)
1234 if endNode == nil {
1235 return nil, fmt.Errorf("no known block header with hash %v", endHash)
1236 }
1237 if !b.Index.NodeStatus(endNode).KnownValid() {
1238 return nil, fmt.Errorf("block %v is not yet validated", endHash)
1239 }
1240 endHeight := endNode.height
1241 if startHeight < 0 {
1242 return nil, fmt.Errorf("start height (%d) is below 0", startHeight)
1243 }
1244 if startHeight > endHeight {
1245 return nil, fmt.Errorf(
1246 "start height (%d) is past end height (%d)",
1247 startHeight, endHeight,
1248 )
1249 }
1250 resultsLength := int(endHeight - startHeight + 1)
1251 if resultsLength > maxResults {
1252 return nil, fmt.Errorf(
1253 "number of results (%d) would exceed max (%d)",
1254 resultsLength, maxResults,
1255 )
1256 }
1257 // Walk backwards from endHeight to startHeight, collecting block hashes.
1258 node := endNode
1259 hashes := make([]chainhash.Hash, resultsLength)
1260 for i := resultsLength - 1; i >= 0; i-- {
1261 hashes[i] = node.hash
1262 node = node.parent
1263 }
1264 return hashes, nil
1265 }
1266 1267 // IntervalBlockHashes returns hashes for all blocks that are ancestors of endHash where the block height is a positive
1268 // multiple of interval.
1269 //
1270 // This function is safe for concurrent access.
1271 func (b *BlockChain) IntervalBlockHashes(
1272 endHash *chainhash.Hash, interval int,
1273 ) ([]chainhash.Hash, error) {
1274 endNode := b.Index.LookupNode(endHash)
1275 if endNode == nil {
1276 return nil, fmt.Errorf("no known block header with hash %v", endHash)
1277 }
1278 if !b.Index.NodeStatus(endNode).KnownValid() {
1279 return nil, fmt.Errorf("block %v is not yet validated", endHash)
1280 }
1281 endHeight := endNode.height
1282 resultsLength := int(endHeight) / interval
1283 hashes := make([]chainhash.Hash, resultsLength)
1284 b.BestChain.mtx.Lock()
1285 defer b.BestChain.mtx.Unlock()
1286 blockNode := endNode
1287 for index := int(endHeight) / interval; index > 0; index-- {
1288 // Use the BestChain chainView for faster lookups once lookup
1289 // intersects the best chain.
1290 blockHeight := int32(index * interval)
1291 if b.BestChain.contains(blockNode) {
1292 blockNode = b.BestChain.nodeByHeight(blockHeight)
1293 } else {
1294 blockNode = blockNode.Ancestor(blockHeight)
1295 }
1296 hashes[index-1] = blockNode.hash
1297 }
1298 return hashes, nil
1299 }
1300 1301 // locateInventory returns the node of the block after the first known block in the locator along with the number of
1302 // subsequent nodes needed to either reach the provided stop hash or the provided max number of entries.
1303 //
1304 // In addition, there are two special cases:
1305 //
1306 // - When no locators are provided, the stop hash is treated as a request for that block, so it will either return the
1307 // node associated with the stop hash if it is known, or nil if it is unknown
1308 //
1309 // - When locators are provided, but none of them are known, nodes starting after the genesis block will be returned
1310 //
1311 // This is primarily a helper function for the locateBlocks and locateHeaders functions. This function MUST be called
1312 // with the chain state lock held (for reads).
1313 func (b *BlockChain) locateInventory(
1314 locator BlockLocator,
1315 hashStop *chainhash.Hash, maxEntries uint32,
1316 ) (*BlockNode, uint32) {
1317 // There are no block locators so a specific block is being requested as identified by the stop hash.
1318 stopNode := b.Index.LookupNode(hashStop)
1319 if len(locator) == 0 {
1320 if stopNode == nil {
1321 // No blocks with the stop hash were found so there is nothing to do.
1322 return nil, 0
1323 }
1324 return stopNode, 1
1325 }
1326 // Find the most recent locator block hash in the main chain. In the case none of the hashes in the locator are in
1327 // the main chain, fall back to the genesis block.
1328 startNode := b.BestChain.Genesis()
1329 for _, hash := range locator {
1330 node := b.Index.LookupNode(hash)
1331 if node != nil && b.BestChain.Contains(node) {
1332 startNode = node
1333 break
1334 }
1335 }
1336 // Start at the block after the most recently known block. When there is no next block it means the most recently
1337 // known block is the tip of the best chain, so there is nothing more to do.
1338 startNode = b.BestChain.Next(startNode)
1339 if startNode == nil {
1340 return nil, 0
1341 }
1342 // Calculate how many entries are needed.
1343 total := uint32((b.BestChain.Tip().height - startNode.height) + 1)
1344 if stopNode != nil && b.BestChain.Contains(stopNode) &&
1345 stopNode.height >= startNode.height {
1346 total = uint32((stopNode.height - startNode.height) + 1)
1347 }
1348 if total > maxEntries {
1349 total = maxEntries
1350 }
1351 return startNode, total
1352 }
1353 1354 // locateBlocks returns the hashes of the blocks after the first known block in the locator until the provided stop hash
1355 // is reached, or up to the provided max number of block hashes.
1356 //
1357 // See the comment on the exported function for more details on special cases.
1358 //
1359 // This function MUST be called with the chain state lock held (for reads).
1360 func (b *BlockChain) locateBlocks(
1361 locator BlockLocator, hashStop *chainhash.Hash,
1362 maxHashes uint32,
1363 ) []chainhash.Hash {
1364 // Find the node after the first known block in the locator and the total number of nodes after it needed while
1365 // respecting the stop hash and max entries.
1366 node, total := b.locateInventory(locator, hashStop, maxHashes)
1367 if total == 0 {
1368 return nil
1369 }
1370 // Populate and return the found hashes.
1371 hashes := make([]chainhash.Hash, 0, total)
1372 for i := uint32(0); i < total; i++ {
1373 hashes = append(hashes, node.hash)
1374 node = b.BestChain.Next(node)
1375 }
1376 return hashes
1377 }
1378 1379 // LocateBlocks returns the hashes of the blocks after the first known block in the locator until the provided stop hash
1380 // is reached, or up to the provided max number of block hashes.
1381 //
1382 // In addition, there are two special cases:
1383 //
1384 // - When no locators are provided, the stop hash is treated as a request for that block, so it will either return the
1385 // stop hash itself if it is known, or nil if it is unknown
1386 //
1387 // - When locators are provided, but none of them are known, hashes starting after the genesis block will be returned
1388 //
1389 // This function is safe for concurrent access.
1390 func (b *BlockChain) LocateBlocks(locator BlockLocator, hashStop *chainhash.Hash, maxHashes uint32) []chainhash.Hash {
1391 b.ChainLock.RLock()
1392 hashes := b.locateBlocks(locator, hashStop, maxHashes)
1393 b.ChainLock.RUnlock()
1394 return hashes
1395 }
1396 1397 // locateHeaders returns the headers of the blocks after the first known block in the locator until the provided stop
1398 // hash is reached, or up to the provided max number of block headers.
1399 //
1400 // See the comment on the exported function for more details on special cases.
1401 //
1402 // This function MUST be called with the chain state lock held ( for reads).
1403 func (b *BlockChain) locateHeaders(
1404 locator BlockLocator,
1405 hashStop *chainhash.Hash,
1406 maxHeaders uint32,
1407 ) []wire.BlockHeader {
1408 // Find the node after the first known block in the locator and the total number of nodes after it needed while
1409 // respecting the stop hash and max entries.
1410 node, total := b.locateInventory(locator, hashStop, maxHeaders)
1411 if total == 0 {
1412 return nil
1413 }
1414 // Populate and return the found headers.
1415 headers := make([]wire.BlockHeader, 0, total)
1416 for i := uint32(0); i < total; i++ {
1417 headers = append(headers, node.Header())
1418 node = b.BestChain.Next(node)
1419 }
1420 return headers
1421 }
1422 1423 // LocateHeaders returns the headers of the blocks after the first known block in the locator until the provided stop
1424 // hash is reached, or up to a max of wire.MaxBlockHeadersPerMsg headers.
1425 //
1426 // In addition, there are two special cases:
1427 //
1428 // - When no locators are provided, the stop hash is treated as a request for that header, so it will either return the
1429 // header for the stop hash itself if it is known, or nil if it is unknown
1430 //
1431 // - When locators are provided, but none of them are known, headers starting after the genesis block will be returned
1432 //
1433 // This function is safe for concurrent access.
1434 func (b *BlockChain) LocateHeaders(locator BlockLocator, hashStop *chainhash.Hash) []wire.BlockHeader {
1435 b.ChainLock.RLock()
1436 headers := b.locateHeaders(locator, hashStop, wire.MaxBlockHeadersPerMsg)
1437 b.ChainLock.RUnlock()
1438 return headers
1439 }
1440 1441 // IndexManager provides a generic interface that the is called when blocks are connected and disconnected to and from
1442 // the tip of the main chain for the purpose of supporting optional indexes.
1443 type IndexManager interface {
1444 // Init is invoked during chain initialize in order to allow the index manager to initialize itself and any indexes
1445 // it is managing. The channel parameter specifies a channel the caller can close to signal that the process should
1446 // be interrupted. It can be nil if that behavior is not desired.
1447 Init(*BlockChain, <-chan struct{}) error
1448 // ConnectBlock is invoked when a new block has been connected to the main chain. The set of output spent within a
1449 // block is also passed in so indexers can access the previous output scripts input spent if required.
1450 ConnectBlock(database.Tx, *block2.Block, []SpentTxOut) error
1451 // DisconnectBlock is invoked when a block has been disconnected from the main chain. The set of outputs scripts
1452 // that were spent within this block is also returned so indexers can clean up the prior index state for this block.
1453 DisconnectBlock(database.Tx, *block2.Block, []SpentTxOut) error
1454 }
1455 1456 // Config is a descriptor which specifies the blockchain instance configuration.
1457 type Config struct {
1458 // DB defines the database which houses the blocks and will be used to store all metadata created by this package
1459 // such as the utxo set. This field is required.
1460 DB database.DB
1461 // Interrupt specifies a channel the caller can close to signal that long running operations, such as catching up
1462 // indexes or performing database migrations, should be interrupted. This field can be nil if the caller does not
1463 // desire the behavior.
1464 Interrupt <-chan struct{}
1465 // ChainParams identifies which chain parameters the chain is associated with. This field is required.
1466 ChainParams *chaincfg.Params
1467 // Checkpoints hold caller-defined checkpoints that should be added to the default checkpoints in ChainParams.
1468 // Checkpoints must be sorted by height. This field can be nil if the caller does not wish to specify any
1469 // checkpoints.
1470 Checkpoints []chaincfg.Checkpoint
1471 // TimeSource defines the median time source to use for things such as block processing and determining whether or
1472 // not the chain is current. The caller is expected to keep a reference to the time source as well and add time
1473 // samples from other peers on the network so the local time is adjusted to be in agreement with other peers.
1474 TimeSource MedianTimeSource
1475 // SigCache defines a signature cache to use when when validating signatures. This is typically most useful when
1476 // individual transactions are already being validated prior to their inclusion in a block such as what is usually
1477 // done via a transaction memory pool. This field can be nil if the caller is not interested in using a signature
1478 // cache.
1479 SigCache *txscript.SigCache
1480 // IndexManager defines an index manager to use when initializing the chain and connecting and disconnecting blocks.
1481 // This field can be nil if the caller does not wish to make use of an index manager.
1482 IndexManager IndexManager
1483 // HashCache defines a transaction hash mid-state cache to use when validating transactions. This cache has the
1484 // potential to greatly speed up transaction validation as re-using the pre-calculated mid-state eliminates the
1485 // O(N^2) validation complexity due to the SigHashAll flag. This field can be nil if the caller is not interested in
1486 // using a signature cache.
1487 HashCache *txscript.HashCache
1488 }
1489 1490 // New returns a BlockChain instance using the provided configuration details.
1491 func New(config *Config) (*BlockChain, error) {
1492 // Enforce required config fields.
1493 if config.DB == nil {
1494 return nil, AssertError("blockchain.New database is nil")
1495 }
1496 if config.ChainParams == nil {
1497 return nil, AssertError("blockchain.New chain parameters nil")
1498 }
1499 if config.TimeSource == nil {
1500 return nil, AssertError("blockchain.New timesource is nil")
1501 }
1502 // Generate a checkpoint by height map from the provided checkpoints and assert the provided checkpoints are sorted
1503 // by height as required.
1504 var checkpointsByHeight map[int32]*chaincfg.Checkpoint
1505 var prevCheckpointHeight int32
1506 if len(config.Checkpoints) > 0 {
1507 checkpointsByHeight = make(map[int32]*chaincfg.Checkpoint)
1508 for i := range config.Checkpoints {
1509 checkpoint := &config.Checkpoints[i]
1510 if checkpoint.Height <= prevCheckpointHeight {
1511 return nil, AssertError(
1512 "blockchain.New checkpoints are not sorted by height",
1513 )
1514 }
1515 checkpointsByHeight[checkpoint.Height] = checkpoint
1516 prevCheckpointHeight = checkpoint.Height
1517 }
1518 }
1519 params := config.ChainParams
1520 targetTimespan := params.TargetTimespan
1521 targetTimePerBlock := params.TargetTimePerBlock
1522 adjustmentFactor := params.RetargetAdjustmentFactor
1523 b := BlockChain{
1524 checkpoints: config.Checkpoints,
1525 checkpointsByHeight: checkpointsByHeight,
1526 db: config.DB,
1527 params: params,
1528 timeSource: config.TimeSource,
1529 sigCache: config.SigCache,
1530 indexManager: config.IndexManager,
1531 minRetargetTimespan: targetTimespan / adjustmentFactor,
1532 maxRetargetTimespan: targetTimespan * adjustmentFactor,
1533 blocksPerRetarget: int32(targetTimespan / targetTimePerBlock),
1534 Index: newBlockIndex(config.DB, params),
1535 hashCache: config.HashCache,
1536 BestChain: newChainView(nil),
1537 orphans: make(map[chainhash.Hash]*orphanBlock),
1538 prevOrphans: make(map[chainhash.Hash][]*orphanBlock),
1539 // warningCaches: newThresholdCaches(vbNumBits),
1540 // deploymentCaches: newThresholdCaches(chaincfg.DefinedDeployments),
1541 DifficultyAdjustments: make(map[string]float64),
1542 }
1543 b.DifficultyBits.Store(make(Diffs))
1544 // Initialize the chain state from the passed database. When the db does not yet contain any chain state, both it
1545 // and the chain state will be initialized to contain only the genesis block.
1546 if e := b.initChainState(); E.Chk(e) {
1547 return nil, e
1548 }
1549 // Perform any upgrades to the various chain-specific buckets as needed.
1550 if e := b.maybeUpgradeDbBuckets(config.Interrupt); E.Chk(e) {
1551 return nil, e
1552 }
1553 // Initialize and catch up all of the currently active optional indexes as needed.
1554 if config.IndexManager != nil {
1555 e := config.IndexManager.Init(&b, config.Interrupt)
1556 if e != nil {
1557 return nil, e
1558 }
1559 }
1560 // // Initialize rule change threshold state caches.
1561 // if e := b.initThresholdCaches(); E.Chk(e) {
1562 // return nil, e
1563 // }
1564 bestNode := b.BestChain.Tip()
1565 df, ok := bestNode.Diffs.Load().(Diffs)
1566 if df == nil || !ok ||
1567 len(df) != len(fork.List[1].AlgoVers) {
1568 bitsMap, e := b.CalcNextRequiredDifficultyPlan9Controller(bestNode)
1569 if e != nil {
1570 }
1571 bestNode.Diffs.Store(bitsMap)
1572 }
1573 I.F(
1574 "chain state (height %d, hash %v, totaltx %d, work %v)",
1575 bestNode.height, bestNode.hash, b.stateSnapshot.TotalTxns,
1576 bestNode.workSum,
1577 )
1578 return &b, nil
1579 }
1580