Get Work

If you are familiar with the theory behind the pool search effort, you know about the big search space the pool has to cope with. You can decide if you want to fly the client in "autopilot" mode, or if you'd like to perform some manual stunts. The most important parameters for defining where and how your client searches are:

  --cpus <num>
    Set the number of CPUs to delegate address generation to. By
    default only one CPU is used. If you set 0 here, the number of
    CPUs to use is set to half of all found, which should get only
    physical cores.

  --loop <num>
    Will keep asking server for work  times. For one run, give
    0 or 1. Default: infinite

  --pages <from>-<to>|'auto'
    Give the interval to work on. If 'auto' is given, the optimal
    chunk to work on is fetched.

  --time <duration>
    Time constraint in case client is in pages 'auto' mode. This
    puts an upper limit on the client runtime. Format is h:m You are
    free to enter '60' for an hour instead of '1:0' If you specify a
    pages interval, this option has no effect.

Auto Mode

If you want to simply throw your clients searching capacity on whatever the pool deems fit and let it work, the defaults are set to achieve exactly that:

./LBC

does implicitly the same as

./LBC -c 0 -p auto -t 10 -l
  999999999

which means "Use all the autodetected physical cores to work on whatever search space the pool assigns to us for an indefinite amout of time, split into chunks of 10 minutes worth of work."

The output of the client will look like this:

    $ ./LBC
    Will use 4 CPUs.
    Ask for work... got blocks [34919186-34920529] (1409 Mkeys)
    oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
    Ask for work... got blocks [34938482-34939825] (1409 Mkeys)
    oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
    Ask for work... got blocks [34948146-34949489] (1409 Mkeys)
    oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo

What you see is the client requesting work from the server, obtaining the interval from 34919186 to 34920529, which are (34920529-34919186+1)*2²⁰ keys, or rounded 1409 Mega-Keys. It got this interval, because given the number of CPUs assigned to this task and their speed (benchmarked on 1st invocation of the generator) this represents "10 minutes worth of work".

In each iteration, you see 84 'o's each of which represents 16*2²⁰ private key search space. So 1344*2²⁰ or 1409286144 keys - roughly 1409 Mkeys. The machine in this particular example can search about 8.4 Gigakeys per hour.

Manual Mode

If you have some special search place in mind, you can go there. Either by specifying a page range directly e.g. -p 1000-2000 would search every key in the range 1000 to 2000 including, or by giving a starting point.

Before we dig into all the possible search space definitions, we need to get some nomenclature defined:

pages/blocks
The parameter is called "pages", for historic reasons. A page (sometimes also called a "block") contains 2²⁰ (1048576) private keys. The history of LBC dates back to directory.io, where 128 private keys are listed on one page. As our "pages" do have 1048576 keys and therefore each represents "8192 directory.io pages", we started to call pages blocks. You remember: pages=blocks

fat blocks
When better generators became available, it didn't make sense to look at just 2²⁰ private keys at once, so the blocks became bigger: 2²⁴ private keys each, which is 16777216 keys and therefore 16 times bigger than a "block". You will not hear often about "fat blocks", but you should be aware that whenever you see an 'o' in the LBC output, your generator has inspected a "fat block", i.e. the equivalent to 16 blocks.

key/private key
The smallest unit of account here. There are really lots of them - almost 2²⁵⁶ to be precise. This number is even bigger than the amount of shoes your girlfriend has. So if you ever saw your girlfriend seaching for some special pair of shoes - we do a similar thing here. You can give key numbers to -p by using the '#'-prefix.

hex/bin/dec
You know dec from school and you are probably comfortable with it, if you still have 10 fingers. If you only had b10 fingers because you lost 8, you would feel more comfortable with bin. And if you like mixing numbers and characters, you like hex.

So, finally you can:

• search pages 1000 to 1100 -p 1000-1100
• search pages 1000 to 1100 -p b1111101000-b10001001100
• search pages 1000 to 1100 -p x3E8-x44C
• search privkeys given in hex -p '#xFFFFFFFF-#x1FFFFFFFF'

All intervals given are "inclusive", that is including the block/key numbers given. You can mix number systems and block/keys in the -p parameter as you like, as long as you make sure the "from" is smaller than the "to". Searching like this is perfectly valid:

    $ ./LBC -p '#b100000000100000000100000000-x1F4'

    Loop off! Work on blocks [64-500] (458 Mkeys)
    etc.

Just be aware, that when using '#', it is necessary to put the range in quotes to prevent the shell to interpret it as a comment. I have no idea why you should need that weird flexibility, but it's there.

Pulsed Operation

If you don't want to (or can't) operate LBC in continuous mode, you can specify periods when LBC will sleep (in seconds) with the -delay parameter. See this screenshot of AWS EC2 monitoring for a t2.micro instance: It's the result of calling LBC with these parameters:

    $ ./LBC -c 1 -t 10 -delay 5400

The free t2.micro instance has only a limited CPU credit which slowly regenerates, therefore after 10 minutes of operation, a sleep period of 5400 seconds follows before the next 10 minutes of operation etc.

Of course, you could use the pulsed operation mode also for firing up LBC only at night time when your machine is unused otherwise. Let's say you want LBC to operate only from midnight to 5 a.m. then you start it up at midnight with these parameters:

    $ ./LBC -c 4 -t 300 -delay 68400

Eternal Run

Sometimes, you have a machine running somewhere (mostly idle) and you would like to use some of its capacity for LBC. You do not intend to look after LBC. "Fire and forget" should be the mode of operation. On the other hand, you would like to make sure this unattended instance a) will be up-to-date all the time and b) inform you in case something is found. You can do so now. For the 1st part, new versions of LBC create a file called eternal_run which is a very simple bash script like this:

#!/bin/bash

while true
do
  ./LBC -u
  ./LBC -t 30 -l 48
done

This script will basically let LBC auto-update (itself, generators, BLF file), then let LBC run for about a day and repeat ad infinitum. If you want to make sure reboots of the server are covered also, let this script be called upon startup depending on your distribution startup procedures. (boot.local etc.)

For the notification part, please see the Hooks section below.

Client Identity and Security

Identity

You can set your own id with the -id command line parameter. String may be any of the 63 "word characters" (a-zA-Z0-9_) - no space - and must be between 8 and 32 (inclusive) characters in length. valid id examples:

__rico666__
Colliders_Inc
Elliptic_Epilepsy

invalid id examples:

hello
.-=1337=-.
something_really_long_more_than32

With this, you will be able to start your LBC clients on different machines under the same id and therefore contribute "as one" to the stats. If you PM me with the MD5 ids you had so far and you'd like to aggregate, I will move their contributed GKeys to your desired id in the DB.

Of course, the automatic issued md5-id will continue to work, so if you do not want to set an id, just don't. You can - of course - set some arbitrary md5 id 

I hope, you are aware this feature gives you some freedom that could be abused, so should there be some profanities appearing in the stats or anything shady I have not taken into account yet, I reserve the right to modify the ids and in severe (recurring) cases to ditch them. If you have to have an own id, try to be unique, try to be funny or just keep some inconspicuous md5 and impress by the #Gkeys next to it.

Security

By setting an id you could assume an arbitrary identity and with such obtain information that's not meant for you (e.g. now with -q "query") or hijack foreign accounts that have some BTC address attached to them (and change it).

So it makes sense to protect your id by a password, which is done by the --secret [oldpwd:]pwd command line parameter. It certainly makes sense to set a password right when setting an id. e.g. like this:

$ LBC -id Hoolakawoola -s x:somesecret
Server message: secret set.
...And from here on you know it...

From then on, you use LBC as you did so far, only you have to use the -id and -s parameters in addition, else

$ LBC -id Hoolakawoola -s wrongsecret -q
Server answer to 'query' is:
{
"nil" : "wrong secret"
}

or

$ LBC -id Hoolakawoola -s wrongsecret -c 1 -t 1
Ask for work... Server doesn't like us. Answer: wrong secret.

Yes, the password is stored salted + SHA256 hashed on the server. Should you forget it, all I can do is to remove it or set another one, I can't bring it back (yet :-)).

BTC Rewards

You can set a BTC address for the id you own any time/as often as you want, but only the last value is valid. You can check the BTC address set via query (-q). And you can do both in one step:

$ LBC -q -a 1DoofusZqKv2wDhUAvKRjUPVQsyZw3NKCw
Server answer to 'query' is:
{
"done" : 18075470,
"btcadr" : "1DoofusZqKv2wDhUAvKRjUPVQsyZw3NKCw",
"ips" : {
...
},
"lastsee" : ...
}
'done' means we have delivered  18953.504 valid Gkeys.

From then on, the given BTC address is attached to your id and whatever reward - relevant to your client - the pool will issue, will be paid to this BTC address (or whichever is active at time of payout - as you can change them as often as you want).

Wait - what reward?!

When the pool started, i planted some small bounties in the search space for any client to find. Some may remember 1AKKm1J8hZ9HjNqjknSCAfkLR4GgvCAPjq and 1TinnSyfYkFG8KC3gZ72KpYxBXsxSadD8. While this is some fun and I plan doing so again, it's more of a "the winner takes it all" game and that's not what pools are about - is it? So there will be another incentive, but this time - with a BTC address attached to an id - the pool can reward clients proportionately.

Let's say - and this is just a thought experiment / example - I put out a 1 BTC reward to be distributed among all ids in the top30 (except __rico666__ - of course) proportionately to their delivered GKeys, with this in place I can do so.
Or let's say the pool does find something and no one claims ownership - we can use this for distribution of the find.
Or let's say the pool does find something, the rightful owner does claim (and prove) ownership and we can distribute a finders fee among the clients... or ... or ...

GPU

LBC has some support for GPU acceleration which can give you around 3 times the key generation rate of your CPU-only generators. As of now, the GPU serves as a hash160 co-processor, the process being.

• The CPU computes 4096 uncompressed public keys and moves them to GPU
• The GPU computes 4096 hash160 of this and 4096 hash160 of the compressed equivalents
• The 8192 hashes are moved back to the CPU which performs a bloom filter search on them.

This process is repeated 4096 times before you see a 'o' on your screen, which takes around 8 seconds on modern CPU/GPU combinations. Depending on the speed of the GPU, its load may be low - e.g. just 10% per CPU core.

In order to use the GPU acceleration, some prerequisites have to be met.

• You put the --gpu flag on command line (if you don't it will still use the regular CPU generator)
• Your OpenCL environment is installed and working properly
• You have the GPU-authorized flag set

Your LBC client has to be authorized for the GPU mode. You can either query this (./LBC -q should show a "gpuauth" : 1), or when calling LBC with --gpu the 1st time, you should see

$ ./LBC --gpu
OpenCL diagnostics written.
GPU authorized: yes

which also indicates your OpenCL environment is probably working. If there is a file called diagnostics-OpenCL.txt and it's non-empty, keep it. In this case, calling LBC with the --gpu parameter will yield just

  $ ./LBC --gpu
GPU authorized: yes

GPU Options

Since 1.174, LBC offers a better handling of different GPU environments. The -gopt option allows you to configure GPU behavior in multiple ways. We'll give some examples how to use it:
GPU devices You can define a comma-separated list or an interval of devices to use. dev=1-4 (use GPUs 1 to 4) or dev=1,2,3,4 but the former is shorter, dev=1,3,5 (use GPUs 1, 3 and 5)
GPU worksize Normally you do not need to touch this parameter, but sometimes (e.g. Amazon Web Services) a GPU claims to be able to take more data than it can chew. With this, you can reduce its workload.

If you have only 1 GPU in your system, you do not need to give any gopt parameter, because -gopt dev=1 is the default.

Ideal command line parameters for Amazon p2.8xlarge:

./LBC -c 32 -g -gopt dev=1-8:lws=512

The 32 vCPUs will be distributed on the 8 available GPUs and the worksize is reduced manually to 512 (the regular worksize - about 1024 - leads to a "CL_OUT_OF_RESOURCES" error.

Distribute your 16 CPUs only on the cards 1,3,5,7:

./LBC -c 16 -g -gopt dev=1,3,5,7

GPU Authorized?

You can use the GPU client when you brought some merit to the pool. You could be an early contributor, in which case you probably are or were in the top30 already. You could pay 0.1 BTC for that privilege (which would be distributed among the pool members proportionally), deliver 3000 Gkeys or you could have made other significant contributions to the pool like helping with the development efforts, propagating the pool, newbie support etc.

Defaults

Having to enter all the parameters on command line can become tedious. Also, putting a password on the command line is not good practice in multi-user systems (as othe rusers may see it when looking at the running processes). That's why LBC offers you a way to define your specific defaults. For this, you can create a JSON file called lbc.json in the LBC directory and enter your default values there. From then on, you do not need to enter them on command line.

The format of the file can be as follows:

{
    "cpus":   4,
    "id":     "SomeIdYouHaveChosen",
    "secret": "verysecret",
    "time":   15
}

From then on, instead of having to enter

$ ./LBC -c 4 -t 15 -id SomeIdYouHaveChosen -s verysecret

a mere ./LBC will do.

All command line options presented in the help (-h) can be put into the lbc.json default file, in their full length (contrary to the command line, where you may abreviate them). The command line still has precedence, so let's say you would like to use all the values from the default file above, but use only two CPUs instead, you would invoke the collider like ./LBC -c 2

Found!

Finding a private key is a rare event. Your machine could have spent months (or more) without hitting anything, but you should be aware, that if your machine is checking hundreds of thousands - or millions - of keys per second, when it hits something - it's really immediate. How does a find look like? You have seen it, when you were testing LBC:

2d17543d32448acc7a1c43c5f72cd5be459ab302:u:priv:0000000000000000000000000000000000000000000000000000000000000001 + 0x5e
02e62151191a931d51cdc513a86d4bf5694f4e51:c:priv:0000000000000000000000000000000000000000000000000000000000000001 + 0x65
9d74ffdb31068ca2a1feb8e34830635c0647d714:u:priv:00000000000000000000000000000000000000000000000000000000000f9001 + 0xf8c
3d6871076780446bd46fc564b0c443e1fd415beb:c:priv:00000000000000000000000000000000000000000000000000000000000f9001 + 0xf8c

These are 4 hash160 that have been planted into the BLF file for testing purposes. The printout shows the hash160 value, if it is based on an uncompressed (u) or compressed (c) public key and finally the private key. The '+' sign denotes really just a simple addition, both numbers being hexadecimal so 1 + 0x5e is 0x5f, 1 + 0x65 is 0x66, 0xf9001 + 0xf8c is 0xf9f8d.

This is printed on the screen, but don't worry: As you will not sit in front of the machine all the time, this information is also written to a file named FOUND.txt in the directory where LBC resides. So if you check the directory for such a file and it's there, it will also contain the found private keys. You also do not have to worry that in the very very rare case your LBC client should find more than one private key in your absence that the former information would be overwritten. LBC appends the keys found to the file.

Once you have this information, there are tools like e.g. bitcoin-tool that allow you to convert the hex private key to some WIF (wallet import format):

  ./bitcoin-tool --output-format base58check --public-key-compression (un)compressed --network bitcoin --input-type private-key --input-format hex --output-type private-key-wif --input 

Please be aware, that this is only the technical information what you can do with a found private key. As for what you should do when your client found a private key, see the FAQ (like moving the funds to a custodial address and announcing your find publicly).

Hooks

LBC has some hooks defined which - if found in the LBC directory - are executed on certain events. These are:

• hook-start This will be called upon regular LBC startup.
• hook-end This will be called upon regular LBC termination.
• hook-error This will be called if LBC terminates because of an error.
• hook-find This will be called if LBC finds a private key.

Obviously, these hooks are useful to implement specific actions you want to be done automatically and without delay. You can have your own way to notify you (mail, console beeping, whatever) in the case of an error (hook-error) or if your LBC client finds something (hook-find). This should allow you to be able to react quicker if any of these events happens instead of seeing "what went wrong" the next day.

The start/end hooks allow you e.g. monitor when LBC returned from a scheduled number of loops (hook-end - see --loop parameter) or to shut down/halt other tasks before LBC puts load to the machine (hook-start).

Arbitrary scripts (Shell, Python, Perl,...) or binaries are supported, as long as they are executable.

Email Notification

If you would like to be informed in case of a find via email, you can do so using the hook-find script. For this, make sure

• your local mail infrastructure is at least working for sending mail (you have a working ssmtp, exim or postfix mail server nearby or accepting your mail to send)
• You have a working way to send mail via command line (see below)

Chances are, that your local Linux admin has done a mail server setup already. If you are on your own, for a setup of a mail server please see one of these HowTos:

• https://www.linux.com/learn/install-and-configure-postfix-mail-server
• https://www.youtube.com/watch?v=uQ2tQuiJmxs
• http://www.linuxhomenetworking.com/wiki/index.php/Quick_HOWTO_:_Ch21_:_Configuring_Linux_Mail_Servers

As mentioned, you only need to be able to send mail, not receive it which makes configuration way simpler. So as soon as you know your machine can send mail, set up a command line doing so. You can use various tools:

Mutt is a full text mail client, which als allows to be called from command line. So the command

mutt -s 'LBC - FOUND!!!' -- "name\@domain.tld" < FOUND.txt

would make sure the contents of the file FOUND.txt are sent to the email name@domain.tld. A possible alternative is the unix "mail" command, very similar in syntax:

mail -s 'LBC - FOUND!!!' name@domain.tld < FOUND.txt

Whichever of these commands you use, make sure your hook-find file is executable and looks like this:

#!/bin/bash

mutt -s 'LBC - FOUND!!!' -- "name\@domain.tld" < FOUND.txt

Then, you should be automatically informed via email in case of a find.

HTTP Request Notification

Unfortunately some ISP-providers block TCP port 25 (email) on virtual/rented hosts to fight spammers. If LBC runs on such a server, the mail notification is blocked and you still need to be informed about a find, you could do so via a HTTP request. It's very unlikely TCP port 80 (HTTP) is blocked also. This may even be the easier way of notification. For this to work, make sure

• You have set up a HTTP server (apache, nginx, ...) on some machine where you have access to the log files.
• You should have wget installed (command line tool for HTTP requests) and you probably have already.

Again, you want hook-find to be this simple executable bash script:

#!/bin/bash

wget http://your-httpd-server-ip-or-domain/LBC/$1

hook-find is given the found line as 1st argument on command line when LBC executes it. Therefore, in case of a find, wget will try to get a page from your HTTPD server under a specific URL (which does not exist, but it does not matter). Part of this HTTP request will be the private key! With this, you can basically monitor an indefinite number of LBC clients.

All that is left for you to do is to perform a grep on your httpd log file for "LBC" from time to time...

Pushbullet Notification

If neither email, nor HTTP notification is for you, you can try Pushbullet. You need to create an account with their website and get an API key (it's free) from pushbullet.com/account. hook-find setup as follows:

$ sudo pip install pushbullet-cli
$ pb set-key 
$ pb push "Hello world!" (just a test - you should get this on your devices)
  

Now set up a very simple hook-find script in your collider directory:

#!/bin/bash

pb push "Your client found a private key $1"
  

Done!