Skip to content

API Usage

Jump to bottom
Ladislau Molnar edited this page Jun 14, 2023 · 27 revisions

How to use

  1. Add the BitcoinBlockchain NuGet package to your project.
  2. Instantiate a new BlockchainParser.
  3. Invoke BlockchainParser’s method ParseBlockchain and iterate over the result.

Sample:

using BitcoinBlockchain.Data;  
using BitcoinBlockchain.Parser;  

...  

string pathToBlockchain = @"C:\Bitcoin\blocks";  
IBlockchainParser blockchainParser = new BlockchainParser(pathToBlockchain);  
...  
foreach (Block block in blockchainParser.ParseBlockchain())  
{  
    // Do something with block.  
}

All classes in the BitcoinBlockchain namespaces are documented using XAML comments that you can access in Visual Studio.

Sample code

The sources in the GitHub repository include a very simple sample project: BitcoinBlockchainSample. The sample is implemented in BitcoinBlockchainSample\Program.cs

Stale Blocks

Make sure that you are aware of the concept of stale blocks. Depending on what your processing does, not accounting for stale blocks could lead to incorrect results. The parser has no way of knowing that a block is stale when it encounters it. It will enumerate it to you and you will have the chance to detect the stale blocks once the parsing of all blocks is complete.

More about stale and orphan blocks:

Usage scenarios

Here are three usage scenarios that correspond to the three available constructors of class BlockchainParser.

Parse all the blockchain files

Create a new BlockchainParser instance:

string pathToBlockchain = @"C:\Bitcoin\blocks";  
IBlockchainParser blockchainParser = new BlockchainParser(pathToBlockchain);

Then enumerate over the result of the parsing:

foreach (Block block in blockchainParser.ParseBlockchain())  
{  
    // Do something with block.  
}

Note that the BitcoinBlockchain library makes certain assumption about how the blockchain files are named. If that is not the case the constructor will throw an exception complaining that the files found on the file system do not conform with certain rules. Basically the blockchain folder must contain files named with the pattern "blkxxxxx.dat", starting from "blk00000.dat" and with no gaps in the numeric section. If for whatever reason that is not the case you need to either rename the blockchain files or use a different constructor.

Parse the blockchain starting from a certain file

This is useful in scenarios where the application using the BitcoinBlockchain library has an “incremental mode”. Suppose your application already processed the blockchain files in a session. After a while, the last blockchain file accumulates more blocks or maybe one or more new blockchain files are created. You can instantiate a BlockchainParser object and instruct it to parse the blockchain starting from a given file. Typically, in this situation, part of the first block file was already processed in the previous session of your application. You must be aware that enumerating the parsing results will provide you with blocks that you already parsed previously. If that matters for your application you will have to account for it.

The same rules mentioned before regarding the naming of the blockchain files apply here.

Create a new BlockchainParser instance:

string pathToBlockchain = @"C:\Users\MyUserName\AppData\Roaming\Bitcoin\blocks";
string firstFile = "blk00123.dat";
IBlockchainParser blockchainParser = new BlockchainParser(pathToBlockchain, firstFile);

Then enumerate over the result of the parsing:

foreach (Block block in blockchainParser.ParseBlockchain())
{
    // Do something with block.
}

Parse the blockchain content from a stream

If you have access to the content of the blockchain in ways other than physical files you can create a BlockchainParser instance and provide it with streams. You can also use this method if for whatever reason the blockchain files are not named the way BlockchainParser expects.

Create a new BlockchainParser instance:

IBlockchainParser blockchainParser = new BlockchainParser(GetBlockchainFiles());

...

private IEnumerable<BlockchainFile> GetBlockchainFiles()
{
    foreach (/* A loop of some kind where you get access to the content of the blockchain files */)
    {
        string fileName = "This is only for identification purposes";
        using (BinaryReader binaryReader = /* Get a binary reader with the content expected in a blockchain file */)
        {
            yield return new BlockchainFile(fileName, binaryReader);
        }
    }
}

Then enumerate over the result of the parsing:

IBlockchainParser blockchainParser = new BlockchainParser(GetBlockchainFiles());

foreach (Block block in blockchainParser.ParseBlockchain())
{
    // Do something with block.
}

Clone this wiki locally