/// <summary>
/// Locates the point in the chain at which newStoredBlock and chainHead diverge. Returns null if no split point was
/// found (ie they are part of the same chain).
/// </summary>
/// <exception cref="BlockStoreException"/>
private StoredBlock FindSplit(StoredBlock newChainHead, StoredBlock chainHead)
{
var currentChainCursor = chainHead;
var newChainCursor = newChainHead;
// Loop until we find the block both chains have in common. Example:
//
// A -> B -> C -> D
// \--> E -> F -> G
//
// findSplit will return block B. chainHead = D and newChainHead = G.
while (!currentChainCursor.Equals(newChainCursor))
{
if (currentChainCursor.Height > newChainCursor.Height)
{
currentChainCursor = currentChainCursor.GetPrev(_blockStore);
Debug.Assert(newChainCursor != null, "Attempt to follow an orphan chain");
}
else
{
newChainCursor = newChainCursor.GetPrev(_blockStore);
Debug.Assert(currentChainCursor != null, "Attempt to follow an orphan chain");
}
}
return(currentChainCursor);
}
/// <summary>
/// Called as part of connecting a block when the new block results in a different chain having higher total work.
/// </summary>
/// <exception cref="BlockStoreException"/>
/// <exception cref="VerificationException"/>
private void HandleNewBestChain(StoredBlock newChainHead)
{
// This chain has overtaken the one we currently believe is best. Reorganize is required.
//
// Firstly, calculate the block at which the chain diverged. We only need to examine the
// chain from beyond this block to find differences.
var splitPoint = FindSplit(newChainHead, _chainHead);
_log.InfoFormat("Re-organize after split at height {0}", splitPoint.Height);
_log.InfoFormat("Old chain head: {0}", _chainHead.Header.HashAsString);
_log.InfoFormat("New chain head: {0}", newChainHead.Header.HashAsString);
_log.InfoFormat("Split at block: {0}", splitPoint.Header.HashAsString);
// Then build a list of all blocks in the old part of the chain and the new part.
var oldBlocks = GetPartialChain(_chainHead, splitPoint);
var newBlocks = GetPartialChain(newChainHead, splitPoint);
// Now inform the wallet. This is necessary so the set of currently active transactions (that we can spend)
// can be updated to take into account the re-organize. We might also have received new coins we didn't have
// before and our previous spends might have been undone.
foreach (var wallet in _wallets)
{
wallet.Reorganize(oldBlocks, newBlocks);
}
// Update the pointer to the best known block.
ChainHead = newChainHead;
}
/// <summary>
/// Adds the given block to the internal serializable set of blocks in which this transaction appears. This is
/// used by the wallet to ensure transactions that appear on side chains are recorded properly even though the
/// block stores do not save the transaction data at all.
/// </summary>
internal void AddBlockAppearance(StoredBlock block)
{
if (AppearsIn == null)
{
AppearsIn = new HashSet <StoredBlock>();
}
AppearsIn.Add(block);
}
/// <summary>
/// Constructs a BlockChain connected to the given list of wallets and a store.
/// </summary>
/// <exception cref="BlockStoreException"/>
public BlockChain(NetworkParameters @params, IEnumerable <Wallet> wallets, IBlockStore blockStore)
{
_blockStore = blockStore;
_chainHead = blockStore.GetChainHead();
_log.InfoFormat("chain head is:{0}{1}", Environment.NewLine, _chainHead.Header);
_params = @params;
_wallets = new List <Wallet>(wallets);
}
/// <summary>
/// Returns the set of contiguous blocks between 'higher' and 'lower'. Higher is included, lower is not.
/// </summary>
/// <exception cref="BlockStoreException"/>
private IList <StoredBlock> GetPartialChain(StoredBlock higher, StoredBlock lower)
{
Debug.Assert(higher.Height > lower.Height);
var results = new LinkedList <StoredBlock>();
var cursor = higher;
while (true)
{
results.AddLast(cursor);
cursor = cursor.GetPrev(_blockStore);
Debug.Assert(cursor != null, "Ran off the end of the chain");
if (cursor.Equals(lower))
{
break;
}
}
return(results.ToList());
}
/// <exception cref="BlockStoreException"/>
/// <exception cref="VerificationException"/>
private void ConnectBlock(StoredBlock newStoredBlock, StoredBlock storedPrev, IDictionary <Wallet, List <Transaction> > newTransactions)
{
if (storedPrev.Equals(_chainHead))
{
// This block connects to the best known block, it is a normal continuation of the system.
ChainHead = newStoredBlock;
_log.DebugFormat("Chain is now {0} blocks high", _chainHead.Height);
if (newTransactions != null)
{
SendTransactionsToWallet(newStoredBlock, NewBlockType.BestChain, newTransactions);
}
}
else
{
// This block connects to somewhere other than the top of the best known chain. We treat these differently.
//
// Note that we send the transactions to the wallet FIRST, even if we're about to re-organize this block
// to become the new best chain head. This simplifies handling of the re-org in the Wallet class.
var haveNewBestChain = newStoredBlock.MoreWorkThan(_chainHead);
if (haveNewBestChain)
{
_log.Info("Block is causing a re-organize");
}
else
{
var splitPoint = FindSplit(newStoredBlock, _chainHead);
var splitPointHash = splitPoint != null ? splitPoint.Header.HashAsString : "?";
_log.InfoFormat("Block forks the chain at {0}, but it did not cause a reorganize:{1}{2}",
splitPointHash, Environment.NewLine, newStoredBlock);
}
// We may not have any transactions if we received only a header. That never happens today but will in
// future when GetHeaders is used as an optimization.
if (newTransactions != null)
{
SendTransactionsToWallet(newStoredBlock, NewBlockType.SideChain, newTransactions);
}
if (haveNewBestChain)
{
HandleNewBestChain(newStoredBlock);
}
}
}
/// <exception cref="VerificationException"/>
private static void SendTransactionsToWallet(StoredBlock block, NewBlockType blockType, IDictionary <Wallet, List <Transaction> > newTransactions)
{
foreach (var item in newTransactions)
{
try
{
foreach (var tx in item.Value)
{
item.Key.Receive(tx, block, blockType);
}
}
catch (ScriptException e)
{
// We don't want scripts we don't understand to break the block chain so just note that this tx was
// not scanned here and continue.
_log.WarnFormat("Failed to parse a script: {0}", e);
}
}
}
/// <summary>
/// Called as part of connecting a block when the new block results in a different chain having higher total work.
/// </summary>
/// <exception cref="BlockStoreException"/>
/// <exception cref="VerificationException"/>
private void HandleNewBestChain(StoredBlock newChainHead)
{
// This chain has overtaken the one we currently believe is best. Reorganize is required.
//
// Firstly, calculate the block at which the chain diverged. We only need to examine the
// chain from beyond this block to find differences.
var splitPoint = FindSplit(newChainHead, _chainHead);
_log.InfoFormat("Re-organize after split at height {0}", splitPoint.Height);
_log.InfoFormat("Old chain head: {0}", _chainHead.Header.HashAsString);
_log.InfoFormat("New chain head: {0}", newChainHead.Header.HashAsString);
_log.InfoFormat("Split at block: {0}", splitPoint.Header.HashAsString);
// Then build a list of all blocks in the old part of the chain and the new part.
var oldBlocks = GetPartialChain(_chainHead, splitPoint);
var newBlocks = GetPartialChain(newChainHead, splitPoint);
// Now inform the wallet. This is necessary so the set of currently active transactions (that we can spend)
// can be updated to take into account the re-organize. We might also have received new coins we didn't have
// before and our previous spends might have been undone.
foreach (var wallet in _wallets)
{
wallet.Reorganize(oldBlocks, newBlocks);
}
// Update the pointer to the best known block.
ChainHead = newChainHead;
}
/// <summary>
/// Returns the set of contiguous blocks between 'higher' and 'lower'. Higher is included, lower is not.
/// </summary>
/// <exception cref="BlockStoreException"/>
private IList<StoredBlock> GetPartialChain(StoredBlock higher, StoredBlock lower)
{
Debug.Assert(higher.Height > lower.Height);
var results = new LinkedList<StoredBlock>();
var cursor = higher;
while (true)
{
results.AddLast(cursor);
cursor = cursor.GetPrev(_blockStore);
Debug.Assert(cursor != null, "Ran off the end of the chain");
if (cursor.Equals(lower)) break;
}
return results.ToList();
}
/// <summary>
/// Locates the point in the chain at which newStoredBlock and chainHead diverge. Returns null if no split point was
/// found (ie they are part of the same chain).
/// </summary>
/// <exception cref="BlockStoreException"/>
private StoredBlock FindSplit(StoredBlock newChainHead, StoredBlock chainHead)
{
var currentChainCursor = chainHead;
var newChainCursor = newChainHead;
// Loop until we find the block both chains have in common. Example:
//
// A -> B -> C -> D
// \--> E -> F -> G
//
// findSplit will return block B. chainHead = D and newChainHead = G.
while (!currentChainCursor.Equals(newChainCursor))
{
if (currentChainCursor.Height > newChainCursor.Height)
{
currentChainCursor = currentChainCursor.GetPrev(_blockStore);
Debug.Assert(newChainCursor != null, "Attempt to follow an orphan chain");
}
else
{
newChainCursor = newChainCursor.GetPrev(_blockStore);
Debug.Assert(currentChainCursor != null, "Attempt to follow an orphan chain");
}
}
return currentChainCursor;
}
/// <exception cref="BlockStoreException"/>
/// <exception cref="VerificationException"/>
private void ConnectBlock(StoredBlock newStoredBlock, StoredBlock storedPrev, IDictionary<Wallet, List<Transaction>> newTransactions)
{
if (storedPrev.Equals(_chainHead))
{
// This block connects to the best known block, it is a normal continuation of the system.
ChainHead = newStoredBlock;
_log.DebugFormat("Chain is now {0} blocks high", _chainHead.Height);
if (newTransactions != null)
SendTransactionsToWallet(newStoredBlock, NewBlockType.BestChain, newTransactions);
}
else
{
// This block connects to somewhere other than the top of the best known chain. We treat these differently.
//
// Note that we send the transactions to the wallet FIRST, even if we're about to re-organize this block
// to become the new best chain head. This simplifies handling of the re-org in the Wallet class.
var haveNewBestChain = newStoredBlock.MoreWorkThan(_chainHead);
if (haveNewBestChain)
{
_log.Info("Block is causing a re-organize");
}
else
{
var splitPoint = FindSplit(newStoredBlock, _chainHead);
var splitPointHash = splitPoint != null ? splitPoint.Header.HashAsString : "?";
_log.InfoFormat("Block forks the chain at {0}, but it did not cause a reorganize:{1}{2}",
splitPointHash, Environment.NewLine, newStoredBlock);
}
// We may not have any transactions if we received only a header. That never happens today but will in
// future when GetHeaders is used as an optimization.
if (newTransactions != null)
{
SendTransactionsToWallet(newStoredBlock, NewBlockType.SideChain, newTransactions);
}
if (haveNewBestChain)
HandleNewBestChain(newStoredBlock);
}
}
/// <summary>
/// Called by the <see cref="BlockChain"/> when we receive a new block that sends coins to one of our addresses or
/// spends coins from one of our addresses (note that a single transaction can do both).
/// </summary>
/// <remarks>
/// This is necessary for the internal book-keeping Wallet does. When a transaction is received that sends us
/// coins it is added to a pool so we can use it later to create spends. When a transaction is received that
/// consumes outputs they are marked as spent so they won't be used in future.<p/>
/// A transaction that spends our own coins can be received either because a spend we created was accepted by the
/// network and thus made it into a block, or because our keys are being shared between multiple instances and
/// some other node spent the coins instead. We still have to know about that to avoid accidentally trying to
/// double spend.<p/>
/// A transaction may be received multiple times if is included into blocks in parallel chains. The blockType
/// parameter describes whether the containing block is on the main/best chain or whether it's on a presently
/// inactive side chain. We must still record these transactions and the blocks they appear in because a future
/// block might change which chain is best causing a reorganize. A re-org can totally change our balance!
/// </remarks>
/// <exception cref="VerificationException"/>
/// <exception cref="ScriptException"/>
internal void Receive(Transaction tx, StoredBlock block, BlockChain.NewBlockType blockType)
{
lock (this)
{
Receive(tx, block, blockType, false);
}
}
/// <summary>
/// Constructs a BlockChain connected to the given list of wallets and a store.
/// </summary>
/// <exception cref="BlockStoreException"/>
public BlockChain(NetworkParameters @params, IEnumerable<Wallet> wallets, IBlockStore blockStore)
{
_blockStore = blockStore;
_chainHead = blockStore.GetChainHead();
_log.InfoFormat("chain head is:{0}{1}", Environment.NewLine, _chainHead.Header);
_params = @params;
_wallets = new List<Wallet>(wallets);
}
/// <summary>
/// Throws an exception if the blocks difficulty is not correct.
/// </summary>
/// <exception cref="BlockStoreException"/>
/// <exception cref="VerificationException"/>
private void CheckDifficultyTransitions(StoredBlock storedPrev, StoredBlock storedNext)
{
var prev = storedPrev.Header;
var next = storedNext.Header;
// Is this supposed to be a difficulty transition point?
if ((storedPrev.Height + 1) % _params.Interval != 0)
{
// No ... so check the difficulty didn't actually change.
if (next.DifficultyTarget != prev.DifficultyTarget)
{
throw new VerificationException("Unexpected change in difficulty at height " + storedPrev.Height +
": " + next.DifficultyTarget.ToString("x") + " vs " +
prev.DifficultyTarget.ToString("x"));
}
return;
}
// We need to find a block far back in the chain. It's OK that this is expensive because it only occurs every
// two weeks after the initial block chain download.
var now = Environment.TickCount;
var cursor = _blockStore.Get(prev.Hash);
for (var i = 0; i < _params.Interval - 1; i++)
{
if (cursor == null)
{
// This should never happen. If it does, it means we are following an incorrect or busted chain.
throw new VerificationException(
"Difficulty transition point but we did not find a way back to the genesis block.");
}
cursor = _blockStore.Get(cursor.Header.PrevBlockHash);
}
_log.DebugFormat("Difficulty transition traversal took {0}ms", Environment.TickCount - now);
var blockIntervalAgo = cursor.Header;
var timespan = (int)(prev.TimeSeconds - blockIntervalAgo.TimeSeconds);
// Limit the adjustment step.
if (timespan < _params.TargetTimespan / 4)
{
timespan = _params.TargetTimespan / 4;
}
if (timespan > _params.TargetTimespan * 4)
{
timespan = _params.TargetTimespan * 4;
}
var newDifficulty = Utils.DecodeCompactBits(blockIntervalAgo.DifficultyTarget);
newDifficulty = newDifficulty.Multiply(BigInteger.ValueOf(timespan));
newDifficulty = newDifficulty.Divide(BigInteger.ValueOf(_params.TargetTimespan));
if (newDifficulty.CompareTo(_params.ProofOfWorkLimit) > 0)
{
_log.DebugFormat("Difficulty hit proof of work limit: {0}", newDifficulty.ToString(16));
newDifficulty = _params.ProofOfWorkLimit;
}
var accuracyBytes = (int)(next.DifficultyTarget >> 24) - 3;
var receivedDifficulty = next.GetDifficultyTargetAsInteger();
// The calculated difficulty is to a higher precision than received, so reduce here.
var mask = BigInteger.ValueOf(0xFFFFFF).ShiftLeft(accuracyBytes * 8);
newDifficulty = newDifficulty.And(mask);
if (newDifficulty.CompareTo(receivedDifficulty) != 0)
{
throw new VerificationException("Network provided difficulty bits do not match what was calculated: " +
receivedDifficulty.ToString(16) + " vs " + newDifficulty.ToString(16));
}
}
/// <summary>
/// Adds the given block to the internal serializable set of blocks in which this transaction appears. This is
/// used by the wallet to ensure transactions that appear on side chains are recorded properly even though the
/// block stores do not save the transaction data at all.
/// </summary>
internal void AddBlockAppearance(StoredBlock block)
{
if (AppearsIn == null)
{
AppearsIn = new HashSet<StoredBlock>();
}
AppearsIn.Add(block);
}
/// <exception cref="VerificationException"/>
private static void SendTransactionsToWallet(StoredBlock block, NewBlockType blockType, IDictionary<Wallet, List<Transaction>> newTransactions)
{
foreach (var item in newTransactions)
{
try
{
foreach (var tx in item.Value)
{
item.Key.Receive(tx, block, blockType);
}
}
catch (ScriptException e)
{
// We don't want scripts we don't understand to break the block chain so just note that this tx was
// not scanned here and continue.
_log.WarnFormat("Failed to parse a script: {0}", e);
}
}
}
/// <summary>
/// Returns true if this objects chainWork is higher than the others.
/// </summary>
public bool MoreWorkThan(StoredBlock other)
{
return _chainWork.CompareTo(other._chainWork) > 0;
}
/// <summary>
/// Throws an exception if the blocks difficulty is not correct.
/// </summary>
/// <exception cref="BlockStoreException"/>
/// <exception cref="VerificationException"/>
private void CheckDifficultyTransitions(StoredBlock storedPrev, StoredBlock storedNext)
{
var prev = storedPrev.Header;
var next = storedNext.Header;
// Is this supposed to be a difficulty transition point?
if ((storedPrev.Height + 1)%_params.Interval != 0)
{
// No ... so check the difficulty didn't actually change.
if (next.DifficultyTarget != prev.DifficultyTarget)
throw new VerificationException("Unexpected change in difficulty at height " + storedPrev.Height +
": " + next.DifficultyTarget.ToString("x") + " vs " +
prev.DifficultyTarget.ToString("x"));
return;
}
// We need to find a block far back in the chain. It's OK that this is expensive because it only occurs every
// two weeks after the initial block chain download.
var now = Environment.TickCount;
var cursor = _blockStore.Get(prev.Hash);
for (var i = 0; i < _params.Interval - 1; i++)
{
if (cursor == null)
{
// This should never happen. If it does, it means we are following an incorrect or busted chain.
throw new VerificationException(
"Difficulty transition point but we did not find a way back to the genesis block.");
}
cursor = _blockStore.Get(cursor.Header.PrevBlockHash);
}
_log.DebugFormat("Difficulty transition traversal took {0}ms", Environment.TickCount - now);
var blockIntervalAgo = cursor.Header;
var timespan = (int) (prev.TimeSeconds - blockIntervalAgo.TimeSeconds);
// Limit the adjustment step.
if (timespan < _params.TargetTimespan/4)
timespan = _params.TargetTimespan/4;
if (timespan > _params.TargetTimespan*4)
timespan = _params.TargetTimespan*4;
var newDifficulty = Utils.DecodeCompactBits(blockIntervalAgo.DifficultyTarget);
newDifficulty = newDifficulty.Multiply(BigInteger.ValueOf(timespan));
newDifficulty = newDifficulty.Divide(BigInteger.ValueOf(_params.TargetTimespan));
if (newDifficulty.CompareTo(_params.ProofOfWorkLimit) > 0)
{
_log.DebugFormat("Difficulty hit proof of work limit: {0}", newDifficulty.ToString(16));
newDifficulty = _params.ProofOfWorkLimit;
}
var accuracyBytes = (int) (next.DifficultyTarget >> 24) - 3;
var receivedDifficulty = next.GetDifficultyTargetAsInteger();
// The calculated difficulty is to a higher precision than received, so reduce here.
var mask = BigInteger.ValueOf(0xFFFFFF).ShiftLeft(accuracyBytes*8);
newDifficulty = newDifficulty.And(mask);
if (newDifficulty.CompareTo(receivedDifficulty) != 0)
throw new VerificationException("Network provided difficulty bits do not match what was calculated: " +
receivedDifficulty.ToString(16) + " vs " + newDifficulty.ToString(16));
}
/// <exception cref="VerificationException"/>
/// <exception cref="ScriptException"/>
private void Receive(Transaction tx, StoredBlock block, BlockChain.NewBlockType blockType, bool reorg)
{
lock (this)
{
// Runs in a peer thread.
var prevBalance = GetBalance();
var txHash = tx.Hash;
var bestChain = blockType == BlockChain.NewBlockType.BestChain;
var sideChain = blockType == BlockChain.NewBlockType.SideChain;
var valueSentFromMe = tx.GetValueSentFromMe(this);
var valueSentToMe = tx.GetValueSentToMe(this);
var valueDifference = (long) (valueSentToMe - valueSentFromMe);
if (!reorg)
{
_log.InfoFormat("Received tx{0} for {1} BTC: {2}", sideChain ? " on a side chain" : "",
Utils.BitcoinValueToFriendlyString(valueDifference), tx.HashAsString);
}
// If this transaction is already in the wallet we may need to move it into a different pool. At the very
// least we need to ensure we're manipulating the canonical object rather than a duplicate.
Transaction wtx;
if (Pending.TryGetValue(txHash, out wtx))
{
Pending.Remove(txHash);
_log.Info(" <-pending");
// A transaction we created appeared in a block. Probably this is a spend we broadcast that has been
// accepted by the network.
//
// Mark the tx as appearing in this block so we can find it later after a re-org.
wtx.AddBlockAppearance(block);
if (bestChain)
{
if (valueSentToMe.Equals(0))
{
// There were no change transactions so this tx is fully spent.
_log.Info(" ->spent");
Debug.Assert(!Spent.ContainsKey(wtx.Hash), "TX in both pending and spent pools");
Spent[wtx.Hash] = wtx;
}
else
{
// There was change back to us, or this tx was purely a spend back to ourselves (perhaps for
// anonymization purposes).
_log.Info(" ->unspent");
Debug.Assert(!Unspent.ContainsKey(wtx.Hash), "TX in both pending and unspent pools");
Unspent[wtx.Hash] = wtx;
}
}
else if (sideChain)
{
// The transaction was accepted on an inactive side chain, but not yet by the best chain.
_log.Info(" ->inactive");
// It's OK for this to already be in the inactive pool because there can be multiple independent side
// chains in which it appears:
//
// b1 --> b2
// \-> b3
// \-> b4 (at this point it's already present in 'inactive'
if (_inactive.ContainsKey(wtx.Hash))
_log.Info("Saw a transaction be incorporated into multiple independent side chains");
_inactive[wtx.Hash] = wtx;
// Put it back into the pending pool, because 'pending' means 'waiting to be included in best chain'.
Pending[wtx.Hash] = wtx;
}
}
else
{
if (!reorg)
{
// Mark the tx as appearing in this block so we can find it later after a re-org.
tx.AddBlockAppearance(block);
}
// This TX didn't originate with us. It could be sending us coins and also spending our own coins if keys
// are being shared between different wallets.
if (sideChain)
{
_log.Info(" ->inactive");
_inactive[tx.Hash] = tx;
}
else if (bestChain)
{
ProcessTxFromBestChain(tx);
}
}
_log.InfoFormat("Balance is now: {0}", Utils.BitcoinValueToFriendlyString(GetBalance()));
// Inform anyone interested that we have new coins. Note: we may be re-entered by the event listener,
// so we must not make assumptions about our state after this loop returns! For example,
// the balance we just received might already be spent!
if (!reorg && bestChain && valueDifference > 0 && CoinsReceived != null)
{
lock (CoinsReceived)
{
CoinsReceived(this, new WalletCoinsReceivedEventArgs(tx, prevBalance, GetBalance()));
}
}
}
}
/// <summary>
/// Returns true if this objects chainWork is higher than the others.
/// </summary>
public bool MoreWorkThan(StoredBlock other)
{
return(_chainWork.CompareTo(other._chainWork) > 0);
}
