We previously worked through the process of generating a Bitcoin private address and translating it into a shareable public address using only the tools and libraries shipped with Elixir and Erlang.

The guiding force behind that article was Andreas Antonopoulos’ excellent Mastering Bitcoin book.

Let’s take another bite out of Mastering Bitcoin and implement the algorithm Andreas describes for “mining for vanity addresses” at the end of chapter four. After we implement the basic algorithm, we’ll add our Elixir special sauce and turn it into a fully parallelized procedure.

What is a Vanity Address?

The concept of a vanity address is simple. It’s a normal Bitcoin public address that contains some sequence of desired characters.

For example, a random Bitcoin public address might look like the following:

1HKz4XU7ENT46ztEzsT83jRezyiDjvnBV8

On the live network, Bitcoin addresses always begin with 1, but the remaining characters are entirely random.

A vanity address might look like this:

1pete7qrCiembh8AEf1zRP2zn6nDsLoHC

You’ll notice that the first five characters of this address are 1pete. This isn’t an accident! I’ve intentionally sought out a public address that begins with my name, Pete, so people know who they’re sending their large sums of Bitcoin to.

While the term “mining” sounds intimidating, the actual process of generating these vanity addresses is laughably simple.

How do you Mine Vanity Addresses?

“Mining,” in this context, is just another term for repeatedly doing something until some condition is met. As in, “keep digging until you find gold!”

We’ll mine our vanity public address by repeatedly generating a private key, transforming it into a public address, and checking if the resulting address matches our desired pattern.

That’s it!

Building that in Elixir should be a walk in the park. We’ll start off by creating a new VanityAddress module and stubbing out a generate_private_key/2 function:

defmodule VanityAddress do
  def generate_private_key(regex, version \\ <<0x00>>)
end

Our generate_private_key/2 function expects a regex which represents the pattern we’re trying to find in a vanity address (like ~r/^1pete/), and a version byte that will used to indicate where this Bitcoin address will be used.

Within our generate_private_key/2 function, we’ll kick off the mining process by generating a random private key and transforming it into a public address:

private_key = PrivateKey.generate
public_address = PrivateKey.to_public_address(private_key)

If the public_address we generated matches the pattern we provided in our regex, we’ve successfully mined a vanity address! In that case, we’ll return the private_key. Otherwise, we’ll repeat the entire process with a recursive call to generate_private_key/2:

case public_address =~ regex do
  true -> private_key
  false -> generate_private_key(regex, version)
end

That’s all there is to it.

We can use our new generate_private_key/2 function in conjunction with the PrivateKey.to_public_address/2 function we built last time to view our newly mined vanity key:

VanityAddress.generate_private_key(~r/^1pete/)
|> PrivateKey.to_public_address

Congratulations; we’re miners!

I find myself producing lots of ranging content from books and articles, like the one you're reading now, to open source software projects. If you like what I'm doing, nothing shows your support more than signing up for my mailing list.

Thinking in Parallel

The problem with our simple implementation of generate_private_key/2 is that it’s slow.

While it’s true that the mining algorithm is inherently slow, there are many optimizations we could make to the code we’ve written. The most obvious improvement that comes to mind when using a “process-oriented” programming language like Elixir is to parallelize the mining algorithm across multiple processes.

However, parallelizing our mining algorithm presents an interesting set of challenges.

Each individual call to generate_private_key/2 is completely synchronous and sequential. We won’t see much of a benefit by queuing up multiple concurrent calls to generate_private_key/2 on the same CPU core. That said, while we’re running generate_private_key/2 within a single process bound to a single CPU core, any other cores available to us are sitting idle.

Ideally, we could simultaneously run as many instances of our generate_private_key/2 execution as we have cores. The moment any of our parallel executions find a matching key, it would be returned to the caller.

Creating a Stream of Parallel Tasks

Elixir’s little known (to me) Task.async_stream/3 function is the tool we need to implement this functionality.

Task.async_stream/3 expects an enumerable as its first argument and a function to be applied concurrently to each element in the enumerable. Each element in the enumerable will have the provided function applied to it in a new process.

If we squint our eyes a little, we can see that this gives us what we need. The “enumerable” we pass into Task.async_stream/3 will really be an infinite stream of zero-argument anonymous functions. Each of those anonymous functions simply calls generate_private_key/2.

We’ll use Stream.cycle/2 to create an infinite stream of these functions:

[fn -> generate_private_key(regex, version) end]
|> Stream.cycle

The function that we want to run in parallel simply executes each of those passed in anonymous functions, one at a time, each in its own process:

|> Task.async_stream(fn f -> f.() end)

This is where our parallelization happens. Each call to generate_private_key/2 is happening in a new process, and Elixir’s scheduler will spread each new process out over the available cores in the system.

By default, Task.async_stream/3 will run up to System.schedulers_online/0 parallel instances of our generate_private_key/2 execution, and System.schedulers_online/0 defaults to the number of available CPU cores in the system. This means we’ll always have one instance of generate_private_key/2 running on each of our cores.

Perfect!

Filtering Our Stream

Task.async_stream/3 returns a stream that produces either an {:ok, value} tuple on success, or an {:exit, reason} tuple on failure. We don’t anticipate or care about failures in this situation, so we’ll nil them out with Stream.map/2:

|> Stream.map(fn
  {:ok, thing} -> thing
  _ -> nil
end)

Now we can use Stream.reject/2 to filter out any nil values from our mapped stream:

|> Stream.reject(&(&1 == nil))

Let’s wrap what we’ve done in a function called stream_private_keys/2 that accepts a regex and a version:

def stream_private_keys(regex, version \\ <<0x00>>) do
  [fn -> generate_private_key(regex, version) end]
  |> Stream.cycle
  |> Task.async_stream(fn f -> f.() end)
  |> Stream.map(fn
    {:ok, thing} -> thing
    _ -> nil
  end)
  |> Stream.reject(&(&1 == nil))
end

What we’re left with is a stream that will produce any number of valid Bitcoin vanity addresses for a given regex and version, using all of the available CPU cores on our system.

Putting Our Stream to Use

Our stream doesn’t actually do anything until we try to pull values out of it using a function from the Enum module. Let’s use Enum.take/2 to pull out three vanity Bitcoin addresses that match our desired pattern (123):

VanityAddress.stream_private_keys(~r/^123/)
|> Enum.take(3)
|> Enum.map(&PrivateKey.to_public_address/1)

["123avbA76Zk98jik3ymTHkjbjKKftAhJiZ",
 "123aGknGk5F2NPkB6e4e6pehVGL7gBR8az",
 "123hzDB1CxcyDwusfsb8Pfh3Ti2i4NQLGR"]

If we take a look at our CPU usage while our mining pipeline is chugging away, we’ll see that all of the CPUs on our machine are being fully utilized.

Success!

Final Thoughts

Spoiler alert: the process of mining for Bitcoin is nearly identical to mining for vanity addresses. Instead of hashing private keys and looking for a random leading string like 1pete, Bitcoin miners hash transaction data, looking for hashes that begin with some number of leading zeros corresponding to the current block difficulty.

There’s a huge amount of pomp and circumstance around the term “mining”, but at its core, it’s an incredibly simple and approachable idea.

Be sure to check out the VanityAddress module in my hello_bitcoin project on Github, and if this kind of thing is at all interesting to you, I highly recommend you pick up a copy of Andreas Antonopoulos’ Mastering Bitcoin.