bitcoin-s/docs/oracle/oracle-price-example.md

id	title
oracle-price-example	Price Example

Requirements for example

You need to have a fully built oracle server. You can follow this guide to do this.

You will also need a the bitcoin-s-cli command line tool to interact with the server. You can find how to build this here

After building the oracle server, you will need to start it with

./app/oracle-server/target/universal/stage/bin/bitcoin-s-oracle-server

Signing BTC/USD price

BTC/USD markets trade 24/7/365 around the world. Exchanges publish the market price for the trading pair everytime a trade is matched in their matching engine.

In this example, we will

1. Explain the createnumericannouncement and createdigitdecompannouncement rpc
2. Set up an oracle that can sign the BTC/USD price at a maturation time
3. Completing the announcement by signing the observed market price

For this example our maturation time will be

2021-02-04 00:00:00 UTC

2 RPC Options

When signing numbers, we need to use a digit decomposition announcement that can sign each digit of a number.

There are 2 different RPC options for making a digit decomposition announcement: createnumericannouncement and createdigitdecompannouncement.

createnumericannouncement is meant to be user-friendly with an easy to use api, where createdigitdecompannouncement is meant to give to be a more advanced api that gives more expressivity.

Here we will give examples of each that result in the same announcement.

createnumericannouncement rpc

The createnumericannouncement takes 6 arguments

1. the name for the announcement (bitcoin-s-price-example)
2. maturation time in ISO 8601 format ("2021-02-04T00:00:00Z")
3. minimum value (0)
4. maximum value (131071)
5. units (BTC/USD)
6. precision (base^precision * base^numdigits to get the actual outcome. This is useful for very small or large values)

createdigitdecompannouncement rpc

It takes 6 arguments

1. the name for the announcement (bitcoin-s-price-example)
2. maturation time in seconds since the epoch (1612396800)
3. base (2)
4. number of digits (17)
5. units (BTC/USD)
6. precision (base^precision * base^numdigits to get the actual outcome. This is useful for very small or large values)

Understanding createdigitdecompannouncement parameters

Most of these fields are self-explanatory, but one that might confuse new users is the usage of base and number of digits. You need to set these two parameters in such a way that your domain is contained within base^numdigits.

Our domain is BTC/USD price at 2020-02-04 00:00:00 UTC. That means we need to pick numDigits such that 2^numDigits can contain the BTC/USD price at 2020-02-04 00:00:00 UTC

For this example, we will pick numDigits=17. This means we can sign a BTC/USD price in between [0,2^17-1] or [$0-$131,071]. If the BTC/USD price is outside of your predetermined interval, you need to sign the min (0) or the max ($131,071).

Setting up the BTC/USD oracle

Given the parameters we specified above, we are ready to create our digit decompisition announcement!

 ./bitcoin-s-cli createdigitdecompannouncement "bitcoin-s-price-example" 1612396800 2 17 "BTC/USD" 0
fdd824fd02b9659e890eef1b223ba45c9993f88c7997859302fd5510ac23f4cac0d4ee8232a77ecbdf50c07f093794370e6a506a836f6b0fb54b45f1fb662e1307166d2e57030574f77305826939fa9124d19bfa8a8b2f00f000586b8c58c79ee8b77969a949fdd822fd025300114762c188048a953803f0edeeeb68c69e6cdc1d371ba8d517003accfe05afc4d6588c3ea326512bc66c26a841adffa68330b8c723da442792e731fb19fda94274a7766bb48e520f118c100bbe62dc3806a8d05a63d92e23683a04b0b8c24148cd166585a6b33b995b3d6c083523a8435b156c05100d88f449f4754310d5574d5e88aad09af1b8ba942cfd305e728044ec6360d847254453ec05b1b518a36660e2238360e02f3a004663a7f3a3534973d8b66a2646c1386779aa820672b6361b88a8696395c0add87840b460dfd8a8c0d520017efc6bf58267d4c9d2a225c5d0e5719068a7dda5d630d7432239b6c9d921d5f3842b584503460ca52612ac2e64337d299513690372e8f4770eb8a28080e8d7c29920ca32af470d65d6f916ee81e3ac15ce02684ba6d2522a9ffea1de7e202b4b699ef7ec4f089dda07f3de5b7d1f853b2c56471999be4efca82674a651c80f047ba3a2b9e6f9999f0cd4062c533d1ae29cab2a5e33cbe98728b7b4271c67f7c5cd6e12e39128b9971e08496cbd84cfa99c77c88867d33e73acef37022ba4422a5221776991d45416db71fb54bc6c104f6a8e50e8905161709215104a7e7b97e866f32cf43233ffd615cab66699832ec607cf59c85a7f56fa957aa5f5d7ec9f46d84d5d4b777122d41ad76c6f4968aeedca243f2030d4f502e58f4181130e9afb75309ac21637bcfd0717528bfb82ffe1b6c9fadee6ba70357210990539184bcc913a0ec65837a736733a2fb6172d601b3900fdd80a11000200074254432f55534400000000001117626974636f696e2d732d70726963652d6578616d706c65

Yay! The hex string returned is an oracle announcement. You can submit this on a tool like the suredbits oracle explorer so others can find your oracle.

If you are building infrastructure to automatically sign announcements, it is important to store two things

1. The oracle announcement above (fdd824fd02b9659...)
2. The timestamp that the announcement matures at (1612396800)

Now you can schedule jobs to sign the announcement when the maturation time passes.

Signing the BTC/USD price for the oracle

At the maturation time (2020-02-04 00:00:00 UTC) you need to check the BTC/USD price.

For the purposes of this example, we are going to assume the BTC/USD price was $42,069 BTC/USD.

Now let's sign the announcement. To do this, we use the signdigits rpc. It takes two parameters

1. The oracle announcement (fdd824fd02b9659...)
2. The outcome ($42,069)

./bitcoin-s-cli signdigits "bitcoin-s-price-example" 42069
fdd868fd049c17626974636f696e2d732d70726963652d6578616d706c650574f77305826939fa9124d19bfa8a8b2f00f000586b8c58c79ee8b77969a94900114762c188048a953803f0edeeeb68c69e6cdc1d371ba8d517003accfe05afc4d6c787b447aef7494301823b1570453b6a84bdadb4822cc215b057b3ef4969688f588c3ea326512bc66c26a841adffa68330b8c723da442792e731fb19fda94274f8ce423054eaccb0e3eadd81395efd9a1fe6c8c70cdb6ce5ade2515593c0306ba7766bb48e520f118c100bbe62dc3806a8d05a63d92e23683a04b0b8c24148cd2d8d787a6280d88188b85f8c1a8c2b4dc859b408e391037b27c30dd3c2fa1cbf166585a6b33b995b3d6c083523a8435b156c05100d88f449f4754310d5574d5ea403f06f5785e54e43ed84c4ecd73dcda752e0864d61bc406bd4f84495a1ce5988aad09af1b8ba942cfd305e728044ec6360d847254453ec05b1b518a36660e21e1114f3c577d8b7b954505038a9a7372b1546e04ea5c6315d3729c389faa022238360e02f3a004663a7f3a3534973d8b66a2646c1386779aa820672b6361b88b3b3e6babdf51b87edab5c22a7a017085488cb3abdabe09e780db34a8860f88ea8696395c0add87840b460dfd8a8c0d520017efc6bf58267d4c9d2a225c5d0e5ddab4419d6859eae05150160029de1065e895e434bddc6a4e0f547572dc661bb719068a7dda5d630d7432239b6c9d921d5f3842b584503460ca52612ac2e6433a694633a7914f3f155148cceb901ffb81abcb6bc244ce6d28ad6c61c8c9fdd2f7d299513690372e8f4770eb8a28080e8d7c29920ca32af470d65d6f916ee81e3bac60fa715ca02a3a801c71afd4d947c7436e05c558194ad7fdd1aeedb3e83eeac15ce02684ba6d2522a9ffea1de7e202b4b699ef7ec4f089dda07f3de5b7d1fb515a7eedb33e4d1ad111c5e2c47b36eae320d5be505293026d4c237e7eac3bf853b2c56471999be4efca82674a651c80f047ba3a2b9e6f9999f0cd4062c533dccce9f582e55e7125bb202820fa4e4ec5ffc2da14c03c3b60d53a0a990d9766b1ae29cab2a5e33cbe98728b7b4271c67f7c5cd6e12e39128b9971e08496cbd847530ec3fee05a8eeb4919569fa966b7da6960c9f2abf8d884f61c1f5f0895871cfa99c77c88867d33e73acef37022ba4422a5221776991d45416db71fb54bc6cc339855ca09a01b9a52ef520f7f328ead330803ab37155d619d8499190ed435c104f6a8e50e8905161709215104a7e7b97e866f32cf43233ffd615cab666998360d49fdec41fd2165c1c9fa8e880203034fab805b141cf22817d23ace14a0bd22ec607cf59c85a7f56fa957aa5f5d7ec9f46d84d5d4b777122d41ad76c6f49689493aba5ad6c0cb16c7d862b7cd9747418e0ffec7d3a4ec1ce394d23114bf765aeedca243f2030d4f502e58f4181130e9afb75309ac21637bcfd0717528bfb828dc8a3114da0cbb7578f57635fcd9daaf1e47cf9214b6605b9a018c1337790ccffe1b6c9fadee6ba70357210990539184bcc913a0ec65837a736733a2fb6172d581ddc2f08d27b7fd895c7fb305dddba5f3bdb923b83c3fdc3560bad5b6044a801300131013001310130013001310130013001300131013001310130013101300131

Yay! Now bitcoin-s gives us an attestation that is represented by the hex string fdd868fd049...

If you submitted your announcement to the suredbits oracle explorer above you will also want to submit the attestation for your announcement so others can find it and settle their DLCs.

If you use the getannouncement rpc along the oracle announcement, you can see the announcement is now completed!

 ./bitcoin-s-cli getannouncement "bitcoin-s-price-example"
{
  "nonces": [
    "4762c188048a953803f0edeeeb68c69e6cdc1d371ba8d517003accfe05afc4d6",
    "588c3ea326512bc66c26a841adffa68330b8c723da442792e731fb19fda94274",
    "a7766bb48e520f118c100bbe62dc3806a8d05a63d92e23683a04b0b8c24148cd",
    "166585a6b33b995b3d6c083523a8435b156c05100d88f449f4754310d5574d5e",
    "88aad09af1b8ba942cfd305e728044ec6360d847254453ec05b1b518a36660e2",
    "238360e02f3a004663a7f3a3534973d8b66a2646c1386779aa820672b6361b88",
    "a8696395c0add87840b460dfd8a8c0d520017efc6bf58267d4c9d2a225c5d0e5",
    "719068a7dda5d630d7432239b6c9d921d5f3842b584503460ca52612ac2e6433",
    "7d299513690372e8f4770eb8a28080e8d7c29920ca32af470d65d6f916ee81e3",
    "ac15ce02684ba6d2522a9ffea1de7e202b4b699ef7ec4f089dda07f3de5b7d1f",
    "853b2c56471999be4efca82674a651c80f047ba3a2b9e6f9999f0cd4062c533d",
    "1ae29cab2a5e33cbe98728b7b4271c67f7c5cd6e12e39128b9971e08496cbd84",
    "cfa99c77c88867d33e73acef37022ba4422a5221776991d45416db71fb54bc6c",
    "104f6a8e50e8905161709215104a7e7b97e866f32cf43233ffd615cab6669983",
    "2ec607cf59c85a7f56fa957aa5f5d7ec9f46d84d5d4b777122d41ad76c6f4968",
    "aeedca243f2030d4f502e58f4181130e9afb75309ac21637bcfd0717528bfb82",
    "ffe1b6c9fadee6ba70357210990539184bcc913a0ec65837a736733a2fb6172d"
  ],
  "eventName": "bitcoin-s-price-example",
  "signingVersion": "DLCOracleV0SigningVersion",
  "maturationTime": "2021-02-04T00:00:00Z",
  "announcementSignature": "659e890eef1b223ba45c9993f88c7997859302fd5510ac23f4cac0d4ee8232a77ecbdf50c07f093794370e6a506a836f6b0fb54b45f1fb662e1307166d2e5703",
  "eventDescriptorTLV": "fdd80a11000200074254432f555344000000000011",
  "eventTLV": "fdd822fd025300114762c188048a953803f0edeeeb68c69e6cdc1d371ba8d517003accfe05afc4d6588c3ea326512bc66c26a841adffa68330b8c723da442792e731fb19fda94274a7766bb48e520f118c100bbe62dc3806a8d05a63d92e23683a04b0b8c24148cd166585a6b33b995b3d6c083523a8435b156c05100d88f449f4754310d5574d5e88aad09af1b8ba942cfd305e728044ec6360d847254453ec05b1b518a36660e2238360e02f3a004663a7f3a3534973d8b66a2646c1386779aa820672b6361b88a8696395c0add87840b460dfd8a8c0d520017efc6bf58267d4c9d2a225c5d0e5719068a7dda5d630d7432239b6c9d921d5f3842b584503460ca52612ac2e64337d299513690372e8f4770eb8a28080e8d7c29920ca32af470d65d6f916ee81e3ac15ce02684ba6d2522a9ffea1de7e202b4b699ef7ec4f089dda07f3de5b7d1f853b2c56471999be4efca82674a651c80f047ba3a2b9e6f9999f0cd4062c533d1ae29cab2a5e33cbe98728b7b4271c67f7c5cd6e12e39128b9971e08496cbd84cfa99c77c88867d33e73acef37022ba4422a5221776991d45416db71fb54bc6c104f6a8e50e8905161709215104a7e7b97e866f32cf43233ffd615cab66699832ec607cf59c85a7f56fa957aa5f5d7ec9f46d84d5d4b777122d41ad76c6f4968aeedca243f2030d4f502e58f4181130e9afb75309ac21637bcfd0717528bfb82ffe1b6c9fadee6ba70357210990539184bcc913a0ec65837a736733a2fb6172d601b3900fdd80a11000200074254432f55534400000000001117626974636f696e2d732d70726963652d6578616d706c65",
  "announcementTLV": "fdd824fd02b9659e890eef1b223ba45c9993f88c7997859302fd5510ac23f4cac0d4ee8232a77ecbdf50c07f093794370e6a506a836f6b0fb54b45f1fb662e1307166d2e57030574f77305826939fa9124d19bfa8a8b2f00f000586b8c58c79ee8b77969a949fdd822fd025300114762c188048a953803f0edeeeb68c69e6cdc1d371ba8d517003accfe05afc4d6588c3ea326512bc66c26a841adffa68330b8c723da442792e731fb19fda94274a7766bb48e520f118c100bbe62dc3806a8d05a63d92e23683a04b0b8c24148cd166585a6b33b995b3d6c083523a8435b156c05100d88f449f4754310d5574d5e88aad09af1b8ba942cfd305e728044ec6360d847254453ec05b1b518a36660e2238360e02f3a004663a7f3a3534973d8b66a2646c1386779aa820672b6361b88a8696395c0add87840b460dfd8a8c0d520017efc6bf58267d4c9d2a225c5d0e5719068a7dda5d630d7432239b6c9d921d5f3842b584503460ca52612ac2e64337d299513690372e8f4770eb8a28080e8d7c29920ca32af470d65d6f916ee81e3ac15ce02684ba6d2522a9ffea1de7e202b4b699ef7ec4f089dda07f3de5b7d1f853b2c56471999be4efca82674a651c80f047ba3a2b9e6f9999f0cd4062c533d1ae29cab2a5e33cbe98728b7b4271c67f7c5cd6e12e39128b9971e08496cbd84cfa99c77c88867d33e73acef37022ba4422a5221776991d45416db71fb54bc6c104f6a8e50e8905161709215104a7e7b97e866f32cf43233ffd615cab66699832ec607cf59c85a7f56fa957aa5f5d7ec9f46d84d5d4b777122d41ad76c6f4968aeedca243f2030d4f502e58f4181130e9afb75309ac21637bcfd0717528bfb82ffe1b6c9fadee6ba70357210990539184bcc913a0ec65837a736733a2fb6172d601b3900fdd80a11000200074254432f55534400000000001117626974636f696e2d732d70726963652d6578616d706c65",
  "attestations": [
    "c787b447aef7494301823b1570453b6a84bdadb4822cc215b057b3ef4969688f",
    "f8ce423054eaccb0e3eadd81395efd9a1fe6c8c70cdb6ce5ade2515593c0306b",
    "2d8d787a6280d88188b85f8c1a8c2b4dc859b408e391037b27c30dd3c2fa1cbf",
    "a403f06f5785e54e43ed84c4ecd73dcda752e0864d61bc406bd4f84495a1ce59",
    "1e1114f3c577d8b7b954505038a9a7372b1546e04ea5c6315d3729c389faa022",
    "b3b3e6babdf51b87edab5c22a7a017085488cb3abdabe09e780db34a8860f88e",
    "ddab4419d6859eae05150160029de1065e895e434bddc6a4e0f547572dc661bb",
    "a694633a7914f3f155148cceb901ffb81abcb6bc244ce6d28ad6c61c8c9fdd2f",
    "bac60fa715ca02a3a801c71afd4d947c7436e05c558194ad7fdd1aeedb3e83ee",
    "b515a7eedb33e4d1ad111c5e2c47b36eae320d5be505293026d4c237e7eac3bf",
    "ccce9f582e55e7125bb202820fa4e4ec5ffc2da14c03c3b60d53a0a990d9766b",
    "7530ec3fee05a8eeb4919569fa966b7da6960c9f2abf8d884f61c1f5f0895871",
    "c339855ca09a01b9a52ef520f7f328ead330803ab37155d619d8499190ed435c",
    "60d49fdec41fd2165c1c9fa8e880203034fab805b141cf22817d23ace14a0bd2",
    "9493aba5ad6c0cb16c7d862b7cd9747418e0ffec7d3a4ec1ce394d23114bf765",
    "8dc8a3114da0cbb7578f57635fcd9daaf1e47cf9214b6605b9a018c1337790cc",
    "581ddc2f08d27b7fd895c7fb305dddba5f3bdb923b83c3fdc3560bad5b6044a8"
  ],
  "signatures": [
    "4762c188048a953803f0edeeeb68c69e6cdc1d371ba8d517003accfe05afc4d6c787b447aef7494301823b1570453b6a84bdadb4822cc215b057b3ef4969688f",
    "588c3ea326512bc66c26a841adffa68330b8c723da442792e731fb19fda94274f8ce423054eaccb0e3eadd81395efd9a1fe6c8c70cdb6ce5ade2515593c0306b",
    "a7766bb48e520f118c100bbe62dc3806a8d05a63d92e23683a04b0b8c24148cd2d8d787a6280d88188b85f8c1a8c2b4dc859b408e391037b27c30dd3c2fa1cbf",
    "166585a6b33b995b3d6c083523a8435b156c05100d88f449f4754310d5574d5ea403f06f5785e54e43ed84c4ecd73dcda752e0864d61bc406bd4f84495a1ce59",
    "88aad09af1b8ba942cfd305e728044ec6360d847254453ec05b1b518a36660e21e1114f3c577d8b7b954505038a9a7372b1546e04ea5c6315d3729c389faa022",
    "238360e02f3a004663a7f3a3534973d8b66a2646c1386779aa820672b6361b88b3b3e6babdf51b87edab5c22a7a017085488cb3abdabe09e780db34a8860f88e",
    "a8696395c0add87840b460dfd8a8c0d520017efc6bf58267d4c9d2a225c5d0e5ddab4419d6859eae05150160029de1065e895e434bddc6a4e0f547572dc661bb",
    "719068a7dda5d630d7432239b6c9d921d5f3842b584503460ca52612ac2e6433a694633a7914f3f155148cceb901ffb81abcb6bc244ce6d28ad6c61c8c9fdd2f",
    "7d299513690372e8f4770eb8a28080e8d7c29920ca32af470d65d6f916ee81e3bac60fa715ca02a3a801c71afd4d947c7436e05c558194ad7fdd1aeedb3e83ee",
    "ac15ce02684ba6d2522a9ffea1de7e202b4b699ef7ec4f089dda07f3de5b7d1fb515a7eedb33e4d1ad111c5e2c47b36eae320d5be505293026d4c237e7eac3bf",
    "853b2c56471999be4efca82674a651c80f047ba3a2b9e6f9999f0cd4062c533dccce9f582e55e7125bb202820fa4e4ec5ffc2da14c03c3b60d53a0a990d9766b",
    "1ae29cab2a5e33cbe98728b7b4271c67f7c5cd6e12e39128b9971e08496cbd847530ec3fee05a8eeb4919569fa966b7da6960c9f2abf8d884f61c1f5f0895871",
    "cfa99c77c88867d33e73acef37022ba4422a5221776991d45416db71fb54bc6cc339855ca09a01b9a52ef520f7f328ead330803ab37155d619d8499190ed435c",
    "104f6a8e50e8905161709215104a7e7b97e866f32cf43233ffd615cab666998360d49fdec41fd2165c1c9fa8e880203034fab805b141cf22817d23ace14a0bd2",
    "2ec607cf59c85a7f56fa957aa5f5d7ec9f46d84d5d4b777122d41ad76c6f49689493aba5ad6c0cb16c7d862b7cd9747418e0ffec7d3a4ec1ce394d23114bf765",
    "aeedca243f2030d4f502e58f4181130e9afb75309ac21637bcfd0717528bfb828dc8a3114da0cbb7578f57635fcd9daaf1e47cf9214b6605b9a018c1337790cc",
    "ffe1b6c9fadee6ba70357210990539184bcc913a0ec65837a736733a2fb6172d581ddc2f08d27b7fd895c7fb305dddba5f3bdb923b83c3fdc3560bad5b6044a8"
  ],
  "outcomes": [
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    [
      "0",
      "1"
    ],
    "signedOutcome": 42069
  ]
}