guijun / btc-oracle

An oracle that posts data about recent Bitcoin payments into Byteball database

BTC Oracle

This oracle posts data about recent Bitcoin payments into Byteball database. It parses the recent blocks that got at least 2 (configurable) confirmations, collects all outputs into a Merkle tree and posts its Merkle root as Byteball data feed.

To get a proof that a particular Bitcoin address did receive a particular payment, a user chats with the oracle bot, sends the Bitcoin address and the bot responds with a Merkle proof that this Bitcoin address did receive a payment. The user then copies and pastes this Merkle proof into the wallet in order to unlock funds from a smart contract.

This data can be used for trustless (except the trust to this oracle) exchange of bitcoins against bytes or any other Byteball asset, including private assets such as blackbytes. The seller of bytes sends them to a smart contract that can be unlocked:

• by the buyer, if he provides a Merkle proof (obtained from this oracle) that he sent the required amount of bitcoins to the seller's Bitcoin address
• by the seller, after expiry period

The Merkle proofs provided by this oracle are reproducible -- they can be generated by anyone running the same algorithm.

Install

Install bitcore and create new bitcore node:

bitcore create -d ~/.bitcore/data byteball-btc-oracle

(add --testnet to work on testnet). Here ~/.bitcore/data is the location of your data directory where full Bitcoin bockchain will be stored, byteball-btc-oracle is the name of your node. cd to your node folder:

cd byteball-btc-oracle

Install btc-oracle service:

npm install btc-oracle

Edit your bitcore-node.json to add btc-oracle service and remove web service. The file should look like this:

{
  "network": "livenet",
  "port": 3001,
  "services": [
    "bitcoind",
    "btc-oracle"
  ],
  "servicesConfig": {
    "bitcoind": {
      "spawn": {
        "datadir": "/home/YourUserName/.bitcore/data",
        "exec": "/usr/lib/node_modules/bitcore/node_modules/bitcore-node/bin/bitcoind"
      }
    }
  }
}

Start your node (which automatically starts the btc-oracle service):

bitcored

After you start it for the first time, it will exit immediately complaining about missing admin_email conf setting. This is the email where you will receive important notifications from your node. Edit your ~/.config/bitcore/conf.json, it should look like this:

{
	"deviceName": "BTC Oracle",
	"admin_email": "[email protected]",
	"from_email": "[email protected]",
	"hub": "byteball.org/bb",
	"bWantNewPeers": false,
	"bSingleAddress": true,
	"MIN_CONFIRMATIONS": 2,
	"MIN_AVAILABLE_POSTINGS": 100,
	"socksHost": "127.0.0.1",
	"socksPort": 9050,
	"socksLocalDNS": false,
	"control_addresses": ["DEVICE ADDRESS OF YOUR GUI WALLET"],
	"payout_address": "YOUR BYTEBALL ADDRESS WHERE IT IS ALLOWED TO WITHDRAW FUNDS TO",
	"permanent_paring_secret": "0000"
}

The socks* settings are recommended to run your node through TOR. Since you are trusted to post true and accurate data, you don't want potential attackers to know your IP address, and TOR is a good way to hide it (see below). MIN_CONFIRMATIONS is the minimum number of confirmations before a bitcoin transaction is considered final and posted by the oracle. MIN_AVAILABLE_POSTINGS is the minimum number of unspent outputs, the script will try to split large outputs if this number drops below minimum. See the documentation of headless wallet and core library to learn about other settings in conf.json.

After editing your conf.json, start the node again. It will take some time to sync with both Byteball and Bitcoin networks.

Every time your node starts, it prints its pairing code:

====== my device pubkey: A9bg4s0ZI36PcTp4p8sNywZ+DGeFm9dP75TcACI22Byz
====== my pairing code: [email protected]/bb#0000

Put this code on your site so that your customers are able to start dialog with the bot by clicking a link:

<a href="byteball:[email protected]/bb#0000">start a chat with the oracle chatbot</a>

If you open this link in your control device (specified in control_addresses), you have access to admin functions, see the documentation for headless wallet. Type address to see the oracle's address and refill its balance so that it is able to pay for the fees.

Security

Since you are trusted to post true and accurate data about recent Bitcoin transactions, your oracle is a lucrative target for attackers. Fortunately, the oracle is running in chat interface, which makes it unnecessary to accept incoming connections and have publicly known IP addresses. This means that in addition to standard security measures, you can also completely hide the IP address of your server from potential attackers so that it won't be easy for them to learn what server to attack in the first place.

Although your node doesn't have to accept incoming connections, it still has to establish outgoing connections, at least with the hubs, which can leak your IP address. To avoid that, run your node through TOR by setting socksHost, socksPort, and socksLocalDNS in your conf.json. Also, configure your bitcoin node to run through TOR by adding

proxy=127.0.0.1:9050

in your bitcoin.conf.