Introduction to the 21 Bitcoin Computer

Posted by Balaji S. Srinivasan

Introduction to the 21 Bitcoin Computer

Overview

This quickstart guide will introduce you to the capabilities of the 21 Command Line and the 21 Bitcoin Computer. In this tutorial, you will go through the following four steps:

  • Mine some bitcoin at 21.co using the built-in mining chip
  • Buy a digital good from 21.co - like a search query or an SMS message - using the bitcoin you just mined
  • Set up your 21 Bitcoin Computer as a file server, join the 21 Developer Community, and sell your digital file for bitcoin to another 21 developer
  • Flush your bitcoin to the blockchain, and send it to another one of your Bitcoin addresses

Once you’ve gone through those steps, you will have experienced what it is like to buy and sell a digital good for bitcoin to another user on the internet with your 21 Bitcoin Computer, and will be ready to go through the other applications.

Prerequisites

You will need the following items:

  • A 21 Bitcoin Computer, with built-in mining and software
  • The latest version of the 21 software, obtained by running 21 update

If you have followed the instructions on the setup page, you should be good to go. Let’s get started!

Step 1: Mine some Bitcoin

The 21 Bitcoin Computer includes a fast and convenient way to get bitcoin for programming purposes: the 21 mine command. Let’s see how to use it, and then we’ll explain how it works.

How to mine Bitcoin

Start by booting up your 21 Bitcoin Computer and SSHing in. We assume you have already run 21 update once. Then execute these commands one by one. Don’t paste them all in at once, but observe the output.

# Start up your Bitcoin mining chip. This will
# prompt you to create a wallet and 21.co account.
21 mine

# Look at your status - after 30-45 seconds, you should have 20,000
# satoshis (satoshis are the smallest indivisible units of one bitcoin,
# currently set at 100 million satoshis per bitcoin)
21 status

# Look at your log to see that you received the satoshis for booting
21 log

# Do a 21 flush to move your 21.co buffer to the blockchain
# This will take a little while and occur in the background.
21 flush 20000 satoshis

# See the flush taking place in your 21 status. The
# “Amount flushing from 21.co buffer to Blockchain balance”
# should be 20,000 satoshis
21 status

# Now invoke 21 mine a second time with no arguments.
# If the mining chip is already running, you will get an advance of
# 40,000 on your future mining earnings!
# Note that it will take a little while to mine.
21 mine

# Do it again just for kicks!
21 mine

# See your status again. You may also see an increment due to bitcoin
# being mined in the background by the chip.
21 status

After you’ve done those commands, your status should look something like this:

twenty@bitcoin-computer-8tml:~$ 21 status
21.co Account
    Username        : satoshi_nakamoto

Mining
        Status           : 21 mining chip running (/run/minerd.pid)
        Hashrate         : ~50 GH/s (warming up)
        Mined (all time) : 55 Satoshis

Type 21 mine --dashboard to see a detailed view. Hit q to exit.
Balance
        Your spendable buffer at 21.co [1]                        : 40055 Satoshis
        Your spendable balance on the Blockchain [2]              : 0 Satoshis
        Amount flushing from 21.co buffer to Blockchain balance  : 40000 Satoshis

        [1]: Available for bittransfers (21.co/micropayments)
        [2]: Available for on-chain (21.co/micropayments)

        To see all wallet addresses, do 21 status --detail

Use 21 buy to buy API calls for bitcoin from 21.co.
For help, do 21 buy --help.

This means you mined a total of 80,055 satoshis. Of these:

  • 40,000 came as a bonus for booting up the device and beginning the mining process, by running 21 mine the first time
  • 55 (in this example) came via background bitcoin mining over the last few seconds, started when you ran 21 mine the first time
  • 40,000 more came from your second and third invocations of 21 mine as an on demand advance against future mining proceeds

Moreover, in terms of where the bitcoin is:

  • 60,055 satoshis are in your 21.co buffer
  • 20,000 are being flushed to your blockchain balance from your 21.co buffer

How did your bitcoin get to those spots?

  • You flushed the first 20,000 satoshi (the bootup bonus) from your 21.co buffer to your blockchain balance when you did 21 flush
  • You got another 55 from background mining over the last few seconds and 40,000 from each of your two foreground mining invocations (your second and third invocations of 21 mine)

The basic idea is to allow you to mix background and foreground mining along with off-chain buffer and on-chain balance to ensure that you always have enough bitcoin for programming and micropayment purposes.

Your 21.co buffer and your Blockchain balance

The reason there are two amounts is that mining bitcoin is slow under the best of circumstances, and not fast enough to permit rapid acquisition of bitcoin for programming purposes. As such, we have implemented something we call "buffered pooled mining" to speed up the process. The short version is that we’ve extended the concept of pooled mining to buffer against several sources of randomness and delay:

  • You do not need to wait for a block to be mined. Instead, as soon as your chip connects to our pool we begin streaming you a pro-rata share of your mined Bitcoin.

  • You do not need to pay transaction fees on each of these small awards of Bitcoin. Instead, we buffer the amount for you at 21.co. You can use this to buy digital goods from other 21 developers, and you can also do 21 flush to move the buffer to the blockchain at any time where you control the private keys.

  • You do not need to wait for 100 blocks before accessing your mined bitcoin.

  • Finally, you do not need to send N hashes to the server before getting N hashes worth of mined bitcoin. That is, by invoking 21 mine your 21 Bitcoin Computer receives bitcoin in advance of future mining at the expense of a small asymptotic slowdown in the rate of bitcoin streamed to your device.

The basic idea is that this is a new way of getting bitcoin: not by buying large quantities slowly for investment purposes on an exchange, but by mining tiny quantities on demand for programming purposes at the command line, rate-limited by a mining chip.

The net result is that you now have 60,000+ satoshis in your 21.co buffer, with 20,000 more in the middle of flushing to the blockchain. You can get more satoshis by running 21 mine. If you run it too many times in a row you will be rate-limited by a difficult hashing problem sent to your chip, so don’t abuse it!

Step 2: Buy a digital good with mined bitcoin

Buying with off-chain transactions (BitTransfers)

Now that you have some bitcoin, what can you do with it? Let's buy a digital good. Try executing the following commands:

21 status
21 buy "https://mkt.21.co/21dotco/zip_code_data/zipdata/collect?zip_code=94109" --maxprice 2750
21 status

What you did there was pay 21.co a tiny amount of bitcoin at a bitcoin-payable endpoint to execute a location search query. After doing it, you should have seen your 21.co buffer drop after the search query. Several things are happening under the hood here.

  • First these prices can be carefully chosen to reflect the cost of the underlying APIs, and they could vary in realtime to track the USD/BTC exchange rate.

  • Second, no per-service signup or API keys were needed to call these APIs. Your bitcoin wallet is essentially acting as the login provider and billing provider for these APIs, though the details differ depending on which micropayments method you are using (more on that below). In future work we will be extending this such that so long as you have bitcoin, you should not need to sign up for many popular APIs again.

  • Third, the reason the micropayment executed so quickly is that the default mode of operation for 21 buy uses a form of off-chain transaction we call BitTransfers, one of three micropayment methods we support. Essentially what happens is that we ask your machine wallet to sign a message. Only a user with your wallet private key can move your 21.co buffer around, either in the form of buying a digital good from 21.co (like you just did), buying from another 21 user, or flushing your buffer to the blockchain.

The upside of BitTransfers is that they are fast and operate at the speed of the internet rather than the blockchain. However, though signed with your wallet private key, each transaction is not registered in the blockchain -- and indeed the blockchain is not directly involved until you do a 21 flush. In many respects this is advantageous, as it reduces the traffic on the blockchain (which is currently very slow).

Buying with on-chain transactions

For those of you who want to see everything in the blockchain, the 21 Bitcoin Computer supports two other forms of micropayment right now (on-chain transactions).

Here is how you would execute an on-chain transaction in practice with a 21 Bitcoin Computer if you already have a nonzero blockchain balance:

21 status
21 buy -p onchain --info "https://mkt.21.co/21dotco/expand_url/short_url/expand?short_url=http://bit.ly/1WNmMH7"
21 buy -p onchain "https://mkt.21.co/21dotco/expand_url/short_url/expand?short_url=http://bit.ly/1WNmMH7" --maxprice 5000
21 status

This probably will not work right away, because you will need to wait for the 21 flush you started earlier to complete in order to get a confirmed on-blockchain balance. If it does work, it will be using unconfirmed inputs to complete the transaction, which currently won't show up in the balance for your 21 status. This feature is coming, but in the meantime you can do 21 status --detail to see all wallet addresses.

Right now flushing your buffer to the blockchain can be fairly slow due to several factors:

  • First, on the server-side we queue flushes into a batch every 10 minutes so as not to overload the blockchain with transactions. This means at most ~144 flushes per day.

  • Second, once a flush begins it takes on average at least 10 minutes to mine the flushing transaction into a single block. Not all blocks will include your transactions, and some blocks are mined empty due to SPV mining.

  • Third, many bitcoin nodes and block explorers do not work well with unconfirmed transactions, so you may need to wait for at least one confirmation (or another ~10+ minutes) to spend your flushed balance.

While we are working on performance improvements for flushing, this is the status quo right now. In addition, aside from flushing, on-chain transactions in their own right have another limitation: you can't do too many in a 24 hour period as the blockchain itself can only handle a maximum of a few hundred thousand transactions per day given the 1MB block size limit.

The main advantage of on-chain transactions is that they are simple to understand and require no prior setup. However, in order to provide the maximum number of alternatives we also have a third micropayments method, micropayment channels.

Micropayment channels

Micropayment channels allow a customer and a merchant to create a secure transaction which can be updated over time. The transaction starts with the customer paying the merchant 0 satoshis; as purchases are made, the customer sends updated versions of the transaction to the merchant with higher and higher values, up to the maximum set when the channel was created.

Channels have expiration times. The merchant can convert the channel into an on-chain transaction at any point up until the expiration time and wait for it to confirm. If the channel hasn't closed by the expiration time, the customer can close it and reclaim all satoshis (except transaction fees) paid into the channel.

Here's how to use channels if you already have at least 163,000 satoshis in your on-chain balance. (If you don't have that many yet, run 21 mine repeatedly until you get at least 163,000 satoshis, run 21 flush to move them to your on-chain balance, and then wait for them to finish flushing as shown by 21 status.)

21 status
21 buy -p channel --info https://mkt.21.co/21dotco/zip_code_data/zipdata/collect?zip_code=94109
21 buy -p channel https://mkt.21.co/21dotco/zip_code_data/zipdata/collect?zip_code=94109
21 status

Buying digital goods programmatically

Now that we understand the three micropayment methods implemented by the 21 Bitcoin Computer, let's implement them programmatically. Open up a text editor on the 21 Bitcoin Computer and type the following into a file titled search-client.py:

#!/usr/bin/env python3
import json
from two1.wallet import Wallet
from two1.bitrequests import BitTransferRequests

# Set up a BitTransfer. The wallet's private key
# is used to sign transactions, confirming that the
# buffer is spendable by the given 21 username.
wallet = Wallet()
requests = BitTransferRequests(wallet)

# Determine the price of a given endpoint, in satoshis
url = 'https://mkt.21.co/21dotco/zip_code_data/zipdata/collect?zip_code=94109'
info = requests.get_402_info(url=url)
print(info)

# Buy the endpoint
results = requests.get(url=url)
print(json.loads(results.text))

You can execute this with

python3 search-client.py

Assuming you have a nonzero 21.co buffer, the last two steps in that code will do the same thing as executing the 21 buy command above, though it will print the JSON to the CLI in an unformatted way. Here is how the same code would work with on-chain payments:

#!/usr/bin/env python3
import json
from two1.wallet import Wallet
from two1.bitrequests import OnChainRequests

# Set up an on-chain transaction. The wallet is
# used to provide bitcoin for the request.
wallet = Wallet()
requests = OnChainRequests(wallet)

# Determine the price of a given endpoint, in satoshis
url = 'https://mkt.21.co/21dotco/expand_url/short_url/expand?short_url=http://bit.ly/1WNmMH7'
info = requests.get_402_info(url=url)
print(info)

# Buy the endpoint
results = requests.get(url=url)
print(json.loads(results.text))

And here is how it works with micropayment channels:

#!/usr/bin/env python3
from time import sleep
from two1.wallet import Wallet
from two1.bitrequests import ChannelRequests
from two1.channels.paymentchannel import NotReadyError

# Set up a micropayment channel. The wallet is used
# to provide bitcoin and create the multisig deposit tx.
wallet = Wallet()
requests = ChannelRequests(wallet)

# Determine the price of a given endpoint, in satoshis
# Also give channel status
url = "https://mkt.21.co/21dotco/zip_code_data/zipdata/collect"
info = requests.get_402_info(url=url)
server_url = info.get('bitcoin-payment-channel-server')

for key, val in info.items():
    print('{}: {}'.format(key, val))

# Make many requests in the channel and print balance
queries = ("94109", "08015", "07728")
for ii in range(3):
    while True:
        try:
            results = requests.get(url=url, params=dict(zip_code=queries[ii]))
            channel_url = requests._channelclient.list(server_url)[0]
            print('Balance remaining in channel: {}'.format(requests._channelclient.status(channel_url).balance))
            break
        except NotReadyError:
            print("Channel not open yet.  Checking again in 60 seconds")
            sleep(60)

Each version of this script does essentially the same thing as 21 buy at the command line, except in code. This gives a framework for how you would programmatically buy things with bitcoin.

Step 3: Sell a digital good for Bitcoin

You’ve now learned about the three micropayment methods supported by the 21 Bitcoin Computer (BitTransfer, On-chain, and Micropayment Channels) and seen how they work both at the command line in code. You've also bought a few digital goods using bitcoin.

Now you're going to do something a little more sophisticated: you're going to sell digital goods for bitcoin. You will do this by changing your password, joining a global peer-to-peer network of other 21 Bitcoin Computers, setting up an machine-payable endpoint, posting that endpoint for purchase in the 21 Developer Community at slack.21.co, and then getting another developer to buy the endpoint. Let's get started.

Change your password

While connected to your 21 Bitcoin Computer as the user twenty, change the password from the default of "one" with the following command:

# Then execute this on your 21 Bitcoin Computer
passwd

Make it something highly secure and very difficult to guess. Make sure to do this or your computer may be broken into when it connects to the network!

Join the peer-to-peer network

After you have changed your password, execute the following command to join the 21 Network:

21 market join

That command will make your device join the 21 peer-to-peer network and will print out something like this:

twenty@bitcoin-computer-8tml:~$ 21 market join
You might need to enter superuser password.
Warning: Unit file of zerotier-one.service changed on disk, 'systemctl daemon-reload' recommended.
Joined network 21market

Don't worry about the warning, though you can do sudo systemctl daemon-reload if you want to. The main point is the last line - Joined network 21market. You are now part of a virtual private marketplace that allows other computers on the 21 network to buy and sell files with you directly.

Note: You are now on a private network with a virtual IP. The main difference from the internet is that every virtual IP on this network is running 21 or a 21 Bitcoin Computer, and therefore has a bitcoin wallet plus the ability to buy and sell digital goods for bitcoin. We hope that all of the other computers on this network will be friendly -- but we cannot guarantee it. So we hope you did change your password!

Note 2: Please also note that if you went through this step before version 2.0.1 of the 21, you will need to rejoin the network by doing 21 market join and then restart any machine-payable endpoints you had up.

Set up a machine-payable endpoint

Now we're going to set up your Bitcoin computer as a server with two endpoints: one vanilla HTTP endpoint and one machine-payable endpoint, where we will sell some files for bitcoin. It’s basically your own personal iTunes store. First, install the following library on your 21 BC:

sudo pip3 install flask

Create a directory with a few files to sell on your 21 BC. These are for illustrative purposes only!

mkdir sellfiles
cd sellfiles
wget https://bitcoin.org/bitcoin.pdf
wget https://en.bitcoin.it/w/images/en/2/29/BC_Logo_.png
cd ..

Now download the following fileserver.py file. Take a look at it and then execute it as follows:

wget https://21.co/learn/introduction-to-the-21-bitcoin-computer/fileserver.py
python3 fileserver.py

You should now be running a simple bitcoin-enabled server!

Test the endpoint by buying from yourself

We’re going to test out this endpoint by opening a second terminal window. If you use a 21 Bitcoin Computer, ssh into it:

## Only necessary if you use a 21 Bitcoin Computer
ssh twenty@IP_ADDRESS

Now you should have two terminals open. While in the second terminal, execute the following commands to hit both endpoints:

# This should give a list of files
curl -g -6 http://[::1]:5000/files

# Now let’s download a client
wget https://21.co/learn/introduction-to-the-21-bitcoin-computer/fileclient.py

# Run the client, point it locally, and buy a file
# The trailing slash is important
python3 fileclient.py 'http://[::1]:5000/'

If those commands work, both of your endpoints are up and working - both your vanilla HTTP endpoint and your machine-payable endpoint. Moreover you just bought from yourself via an off-chain transaction! You can see the purchase in your log by running 21 log.

Here's roughly what you would see if you ran 21 log as the local user, with your 21.co username as joe_twenty_client:

21 Bitcoin Computer Activity Log.

2015-11-06 06:08:43 : -2360 Satoshis from your 21.co buffer
Description: You bought http://[::1]:5000/buy?selection=2&payout_address=1DVHWEU8oHucBDzJQjynL1EohcLjmxm3mx from joe_twenty

2015-11-06 06:08:43 : +2360 Satoshis to your 21.co buffer
Description: You sold http://[::1]:5000/buy?selection=2&payout_address=1DVHWEU8oHucBDzJQjynL1EohcLjmxm3mx to joe_twenty

That's pretty cool! Your 21 Bitcoin Computer is now acting as a server to sell digital goods and services for bitcoin. And at least locally, you were able to see that the user could buy digital goods from itself for satoshis.

Step 4: Flush your Bitcoin to the Blockchain

By this point, you've mined some bitcoin, used it to buy digital goods, and seen how to receive it from someone else to sell digital goods. But it's not truly bitcoin unless you can see it on the blockchain. Go ahead and run the following command:

21 status
21 log

You will see the bitcoin you made by selling to others. Now you want to pull out your earned bitcoin and send it to someone. These commands will do it for you:

21 flush
# Wait quite a while, at least 10-20 minutes and more like 60+
# Then perform the following command.
wallet sendto 1BtjAzWGLyAavUkbw3QsyzzNDKdtPXk95D --satoshis 1000 --use-unconfirmed

Note a few points:

  1. The wallet sendto command will typically only work after your buffer is not only flushed, but confirmed, which can take some time.
  2. We have overriden that by adding the --use-unconfirmed flag
  3. Note also that the wallet sendto uses values in bitcoin by default, not satoshis, but this default is deprecated and will be removed soon. Thus, you should use the --satoshis or -s flag to specify the amount in satoshis, which in this case is 0.00005 BTC.
  4. There is a known issue where your 21 status may show a spendable balance on the blockchain even if you don't have confirmed UTXOs. Without confirmed UTXOs, wallet sendto (and the 21 send wrapper) won't let you send bitcoin even if it's on its way. For now, you can work around this by using the --use-unconfirmed option above. This issue mainly arises with heavy recent use of on-chain transactions (and should be obviated in the next 21 update).

As written, the last command sends 5000 satoshis to the Apache Foundation -- but you can obviously substitute your own Bitcoin address of choice.

Next Steps

To recap, this introductory tutorial gave you a good idea of what the 21 Bitcoin Computer can do. You mined some bitcoin, used it to buy a digital good, sold a digital good to others for bitcoin, and then flushed your earnings to the blockchain. Moreover, you joined a new community of Bitcoin developers at slack.21.co. You are now among the very first people on the internet to buy and sell digital goods directly between yourselves for bitcoin.

Applications

Depending on your interests, you can now investigate several other bitcoin-powered applications:

Each of these applications uses the same basic concepts described in this article. However, three words of caution.

Performance

First, the code in these demos is very much meant to show what can be done with the platform. It isn't yet "production" grade; there are many performance improvements that can increase the throughput to many requests per second, enough to support nontrivial bitcoin-denominated revenue on a daily basis. We'll be updating the demos in the near future to improve their out-of-the-box performance; in the meantime, take a look at this and this article.

Security

Second, direct peer-to-peer networking of individual servers that each have Bitcoin wallets into something like the 21 Network is a relatively new phenomenon. These servers aren't just communicating with each other over the standard Bitcoin 8333 ports; they are now buying and selling digital goods from each other for bitcoin. If what we're doing works, it means an increase in bitcoin transaction activity, and there will no doubt be novel security issues that arise in this context. A silver lining is that satoshi-scale quantities of money for micropayments do not provide a huge incentive for malicious actors. With that said, please use secure passwords and do report any security issues to us at security@21.co.

Limitations

Third, by analogy to the early internet, the Bitcoin network itself is still very much in its 28.8k modem era. As you write programs to buy and sell digital goods and services from other people for bitcoin, you likely will run into one or more of the following issues:

  • Flushing your buffer to the blockchain from 21.co can take a while to mine into a block
  • Spending a flushed balance on the blockchain can require at least one confirmation
  • Transaction fees are not completely trivial for on-chain micropayments
  • There's a global limit on number of transactions that can be sent per day, set by the block size

Many of these things have technical workarounds of one form or another. For example, using off-chain transactions ("BitTransfers") or Micropayment Channels ameliorates many of these issues in the short term. In general, the slow part of any bitcoin-related system is usually the interface with the blockchain itself. With that said, at the end of the day the blockchain is also what provides the global internet-accessible distributed ledger that makes bitcoin special.