Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/byteball/btc-oracle

An oracle that posts data about recent Bitcoin payments into Obyte distributed ledger
https://github.com/byteball/btc-oracle

bitcoin defi oracle smart-contracts

Last synced: about 1 year ago
JSON representation

An oracle that posts data about recent Bitcoin payments into Obyte distributed ledger

Awesome Lists containing this project

README 

          
# BTC Oracle



This oracle posts data about recent Bitcoin payments into Obyte 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 Obyte 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 Obyte 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](https://bitcore.io/guides/full-node/) and create new bitcore node:

```

bitcore create -d ~/.bitcore/data obyte-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, `obyte-btc-oracle` is the name of your node.  `cd` to your node folder:

```

cd obyte-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": "admin@yourdomain.com",

	"from_email": "btc-oracle-alerts@yourdomain.com",

	"hub": "obyte.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 OBYTE ADDRESS WHERE IT IS ALLOWED TO WITHDRAW FUNDS TO",

	"permanent_paring_secret": "*"

}

```

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](../../../headless-obyte) and [core library](../../../ocore) 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 Obyte and Bitcoin networks.



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

```

====== my device pubkey: A9bg4s0ZI36PcTp4p8sNywZ+DGeFm9dP75TcACI22Byz

====== my pairing code: A9bg4s0ZI36PcTp4p8sNywZ+DGeFm9dP75TcACI22Byz@obyte.org/bb#0000

```

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

```

start a chat with the oracle chatbot

```

You could also take them staight to merkle proof by adding the Bitcoin address as pairing code:

```

get merkle proof from BTC oracle

```

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](../../../headless-obyte).  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`.