Fluent Interface (Python)¶

With currently more than 430 million transactions in the Bitcoin blockchain, analyzing large parts of the blockchain has become largely infeasible using BlockSci’s Python interface. With the new version of BlockSci we are providing a new interface that allows for fast selection and filtering of blockchain data.

The new interface relies on the execution of queries in C++ for significantly better performance. Rather than iterating over transactions in Python, the new interface allows the analyst to specify complex queries that are executed in C++.

Take the anomalous fee query from the BlockSci paper as an example:

[tx for block in chain for tx in block if tx.fee > 1e7]

This query evaluates every transaction on the blockchain and selects those with a fee larger than 0.1 BTC. It does so by instantiating Python objects for every single transaction and retrieving the fee for each of them.

Let’s see how we can express this query using the new interface:

chain.blocks.txes.where(lambda tx: tx.fee > int(1e7))

Here, chain.blocks.txes selects all transactions in the blockchain. Then, the where clause allows to filter those transactions using the lambda syntax. where is only one of a variety of functions that can be applied to objects in the blockchain.

Using .select, we can retrieve a specific property for each object:

chain.blocks.select(lambda b: b.txes.size)

The above example returns the number of transactions in each block.

Available Functions¶

Command	Use
`.select()/.map()`	Selecting properties of objects
`.where()`	Filtering
`.max()`	Returns the largest value of a property
`.min()`	Returns the smallest value of a property
`.any()`	Evaluates a boolean expression and returns whether it holds for any item
`.all()`	Evaluates a boolean expression and returns whether it holds for all items
`.group_by()`	Aggregates properties based on another attribute
`.count/.size`	Returns the number of items
`.to_list()`	Returns a list of all items

Select¶

Count the number of transactions in every block (.select and .map have the exact same functionality):

chain.blocks.select(lambda b: b.txes.size)

Filter¶

Select all transactions with a transaction fee greater than 0.1 BTC.

chain.blocks.txes.where(lambda tx: tx.fee > 10**7))

Min and Max¶

Find the transaction with the largest fee in the blockchain:

chain.blocks.txes.max(lambda tx: tx.fee)

Retrieve the largest fee in every block of the blockchain:

chain.blocks.map(lambda b: b.txes.max(lambda tx: tx.fee).map(lambda tx: tx.fee).or_value(0))

Finding the block that includes the largest fee in the blockchain:

chain.blocks.max(lambda b: b.txes.max(lambda tx: tx.fee).map(lambda tx: tx.fee).or_value(0))

Aggregation¶

Aggregate the value sent to addresses in a block:

chain.blocks[-1].outputs.group_by(lambda o1: o1.address, lambda o2: o2.value.sum)

Aggregating the value stored in different types of addresses:

chain.blocks[-1].outputs.where(lambda o: ~o.is_spent).group_by(
  lambda output: output.address.type,
  lambda outputs: outputs.value.sum
)

Working with Optionals¶

Some fields return optional properties. For example, an unspent output does not have a spending transaction. Using .or_value, we can provide a default value.

Get the value of all outputs in a block that have been spent after 4320 blocks or more.

chain.blocks[-1].map(lambda b: b.txes.outputs.where(
  lambda o: o.spending_input.map(lambda i: i.age).or_value(0) > 4320)).value.sum
)

Equality, Comparison and Arithmetic¶

Most attributes support equality (==, !=) and comparison operations (>, >=, <=, <). When working with attributes that are represented by integers (e.g., transaction fees) the arithmetic operators +, -, *, //, % are supported. Note that only integer division can be used.

chain.blocks.map(lambda b: b.fee // b.size_bytes)

chain.blocks.txes.map(lambda tx: tx.input_value - tx.output_value)

Limitations¶

There are a few limitations you need to be aware of when using the interface.

The fluent interface does not work with Python’s logical boolean operators. Instead of and, or and not you’ll need to use &, | and ~.
The fluent interface does not support floating point computations (see section “Equality, Comparison and Arithmetic” above).