Oracles

Introduction

The Oracles Custom Consensus (CC) module allows a user to make off-chain data available on-chain. This enables developers to create and use software that responds to off-chain information and events.

Those who publish data to an oracle are called publishers. There is a fee-based model to serve as an incentive for publishers.

Oracles CC Module Flow

  • Create an Oracle using oraclescreate
  • Register as a data publisher for the oracle using the oraclesregister method; at this stage, the publisher indicates the fee for their data updates
    • Anyone can register as a publisher for any oracle; users subscribe only to the publishers they desire
  • The oracleslist, oraclesinfo, and oraclessamples methods allow the user to find oracles and publishers, find more information about a specific oracle and publisher, and discover samples of an existing publisher, respectively
  • Anyone can subscribe to any specific publisher of any oracle using the oraclessubscribe method
  • A publisher can publish data using oraclesdata, and thereby collect their fee from their subscribers

oraclesaddress

oraclesaddress (pubkey)

The oraclesaddress method displays the oracle address for a specific pubkey.

Arguments

Name Type Description
pubkey (string, optional) the pubkey of the requested info; by default it is the pubkey used to launch the chain

Response

Name Type Description
result (string) whether the method executed successfully
OraclesCCaddress (string) taking the contract's EVAL code as a modifier, this is the public address that corresponds to the contract's privkey
Oraclesmarker (string) the unmodified public address generated from the contract's privkey
GatewaysPubkey (string) the pubkey for the gateways cc
OraclesCCassets (string) this property is used for development purposes only and can otherwise be ignored
CCaddress (string) taking the contract's EVAL code as a modifier, this is the CC address from the pubkey of the user
myCCaddress (string) taking the contract's EVAL code as a modifier, this is the CC address from the pubkey of the user
myaddress (string) the public address of the pubkey used to launch the chain

📌 Examples

Command:

./komodo-cli -ac_name=HELLOWORLD oraclesaddress 03810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5

oraclescreate

oraclescreate name description format

The oraclescreate method creates a new oracle.

The method returns a hex value which must then be broadcast using the sendrawtransaction method.

Arguments

Name Type Description
name (string) the desired name of the oracle contract
description (string) the description of the oracle
format (string) an indication of what format of data is accepted into this contract; use the list of characters provided below for this property

The various formats of data that can be registered for an oracle and their symbols are as follows:

  • s -> char string; size < 256 bytes
  • S -> char string; size < 65536 bytes
  • d -> binary data; size < 256 bytes
  • D -> binary data; size < 65536 bytes
  • c -> 1 byte signed little endian number, 'C' if unsigned
  • t -> 2 byte signed little endian number, 'T' if unsigned
  • i -> 4 byte signed little endian number, 'I' if unsigned
  • l -> 8 byte signed little endian number, 'L' if unsigned
  • h -> 32 byte hash
  • Even though the formats S and D specify that the data size can be up to 65536 bytes, the combination of the transaction size and the data size cannot exceed the limit of 10000 bytes.
  • Although the formats d and D are for raw binary data, they are preferable to the s and S human-readable formats. This is because the s and S formats occupy twice the size of data on the blockchain, and yet their only advantage is their ability to show human-readable output in the oraclessamples method.

If data to be submitted is larger than 8KB, break it into chunks of size 8KB or lower.

Response

Name Type Description
result (string) whether the command succeeded
hex (string) a raw transaction in hex-encoded format; you must broadcast this transaction to complete the command

📌 Examples

Step 1: Create a customized oracle contract and get the hex value

./komodo-cli -ac_name=HELLOWORLD oraclescreate "NYWTHR" "Weather in NYC" "L"

Step 2: Send raw transaction / broadcast the hex value

./komodo-cli -ac_name=HELLOWORLD sendrawtransaction 010000000185b76ed0fbdb9ee2bdb5693f491b6ea23de6498f42c6e83f9f36c1eaf411dd990200000049483045022100aa198a2ae959ee191e1359df48867480bf5a1a5bd4fa76b4398481c89ff3095102205034824dcd56b312183acd65c27a002a13dae84f5d22c767f1efaae09ef63a5c01ffffffff0310270000000000002321038c1d42db6a45a57eccb8981b078fb7857b9b496293fe299d2b8d120ac5b5691aac378740a804000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5ac00000000000000001c6a1aec43064e5957544852014c0e5765617468657220696e204e594300000000
# This will output an unique txid which will be refered as oracletxid or ID of the oracle.

(Use ./komodo-cli -ac_name=HELLOWORLD getrawmempool to ensure that the transaction receives confirmation.)

Step 3: Decode raw transaction (optional to check if the values are sane)

./komodo-cli -ac_name=HELLOWORLD decoderawtransaction 010000000185b76ed0fbdb9ee2bdb5693f491b6ea23de6498f42c6e83f9f36c1eaf411dd990200000049483045022100aa198a2ae959ee191e1359df48867480bf5a1a5bd4fa76b4398481c89ff3095102205034824dcd56b312183acd65c27a002a13dae84f5d22c767f1efaae09ef63a5c01ffffffff0310270000000000002321038c1d42db6a45a57eccb8981b078fb7857b9b496293fe299d2b8d120ac5b5691aac378740a804000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5ac00000000000000001c6a1aec43064e5957544852014c0e5765617468657220696e204e594300000000

oraclesdata

oraclesdata oracletxid hexstr

The oraclesdata method publishes data to an oracle.

A publisher cannot successfully execute this command until they have at least one subscriber. A publisher may create their own subscriber account for this purpose. See oraclessubscribe.

Data is submitted using the hexstr property. The first bytes of the hexstr property must be the length of the data being submitted in hexadecimal format; this sets the string length for the rest of the data. The second portion of the hexstr property is the data itself.

The oraclesdata method returns a hex value which must then be broadcast using the sendrawtransaction method.

The sendrawtransaction method outputs a unique txid, called oraclesdatatxid, which is the unique identifier for this data sample.

The following script converts data entered in a normal-text form to a format accepted by an Oracle with the following characteristics. The oracle is of type: S, and the first two bytes of data are the length, given in Little Endian format.

Note

  • for submitting data of the types s and d, where the size is less than 256 bytes, the first byte denotes the length
  • for submitting data of the types S and D, where the size is less than 65536 bytes, the first two bytes denotes the length in Little Endian format

📌 Examples for data submission

Example A
  • The objective: to submit a 10 character string, "teststring", to an oracle of the format s
  • The data to meet this objective is as follows: 0a74657374737472696e67
    • Notice the first byte, 0a
      • This is the hexadecimal representation of the decimal number 10
      • 10 is the byte size of this 10 character string, because each character requires 1 byte of space
    • Notice the remaining bytes, 74657374737472696e67
      • Each two characters is a byte representing a character
      • 74 = t
      • 65 = e
      • 73 = s
      • 74 = t etc.
Example B
  • The objective: to submit the 10 character string, "teststring", to an oracle of the format S
  • The data to meet this objective is as follows: 0a0074657374737472696e67
    • Notice the first two bytes, 0a and 00
    • These are the hexadecimal representations of the decimal number 10, written to fill 2 bytes and in Little Endian format
    • The remaining data, 74657374737472696e67, is the same as Example A

Arguments

Name Type Description
oracletxid (string) the unique identifying transaction id of the oracle
hexstring (string) the first half of the string indicates the length of the string in bytes, the second half of the string is the data, typically provided in hex-encoded format

Response

Name Type Description
result (string) whether the command succeeded
hex (string) a raw transaction in hex-encoded format; you must broadcast this transaction to complete the command

📌 Examples

Step 1: Subscribe to a oracle plan and get the hex value

./komodo-cli -ac_name=HELLOWORLD oraclesdata 0df7c4d844f08dba08abd4bb174558739f17cfe268feb005fb6333b3761d9203 00000000ffffffff

Step 2: Send raw transaction / broadcast the hex value

./komodo-cli -ac_name=HELLOWORLD sendrawtransaction 010000000359db76b9b8e9cfaa4514dcc198c375f910b9fb7367d1c9d556cd5eb43b5f4d2d02000000484730440220645b49d6d85454b1015d82a53ec51685fc3b8bf1d092696c3c253b88cab3033a02207023511219897a374ad94951dd2af70b14d99eccbb404eaf783120f3170bd5e301ffffffff75a5881417ab6700c089a6083d71abadc8cd74018bded0cfba423e027d513c8f010000007b4c79a276a072a26ba067a5658021035933ab0bd2e2ceb712e7cab393a8c9096ba4be2e3a76f5aaeab72bce4aa61857814047697a246e4442888a3b6ffc4a8c5ae940eec7d19f72053a07b6d8a2968a260626c8001c9138e9fd0e3cfabb811ae71bd8c1c555ca8c8410cb9121ce25860507a100af038001eca10001ffffffff59db76b9b8e9cfaa4514dcc198c375f910b9fb7367d1c9d556cd5eb43b5f4d2d000000007b4c79a276a072a26ba067a565802103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b581404fa0de32bbb96b2e2f61fe823cdba4c3b9fef786ea8c65196f97653a942656812e675e91643ff0ec33853fd2481d40fc48fa51e18c9cbffb49e714c15b47babda100af038001eca10001ffffffff05c09ee60500000000302ea22c802092392e766d63f73dd7c68ff9eaf9f009f13b17c4167472e8aebb00d96be66aa68103120c008203000401cc1027000000000000302ea22c80200648c12e7e058c98f0a5cc288ac271ad08bd493e1fb7de83edeea69789338fc58103120c008203000401cc40420f0000000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5acd7bb49a204000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5ac0000000000000000706a4c6dec4403921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70d75a5881417ab6700c089a6083d71abadc8cd74018bded0cfba423e027d513c8f2103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b50800000000ffffffff00000000

Step 3: Decode raw transaction (optional to check if the values are sane)

./komodo-cli -ac_name=HELLOWORLD decoderawtransaction 010000000359db76b9b8e9cfaa4514dcc198c375f910b9fb7367d1c9d556cd5eb43b5f4d2d02000000484730440220645b49d6d85454b1015d82a53ec51685fc3b8bf1d092696c3c253b88cab3033a02207023511219897a374ad94951dd2af70b14d99eccbb404eaf783120f3170bd5e301ffffffff75a5881417ab6700c089a6083d71abadc8cd74018bded0cfba423e027d513c8f010000007b4c79a276a072a26ba067a5658021035933ab0bd2e2ceb712e7cab393a8c9096ba4be2e3a76f5aaeab72bce4aa61857814047697a246e4442888a3b6ffc4a8c5ae940eec7d19f72053a07b6d8a2968a260626c8001c9138e9fd0e3cfabb811ae71bd8c1c555ca8c8410cb9121ce25860507a100af038001eca10001ffffffff59db76b9b8e9cfaa4514dcc198c375f910b9fb7367d1c9d556cd5eb43b5f4d2d000000007b4c79a276a072a26ba067a565802103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b581404fa0de32bbb96b2e2f61fe823cdba4c3b9fef786ea8c65196f97653a942656812e675e91643ff0ec33853fd2481d40fc48fa51e18c9cbffb49e714c15b47babda100af038001eca10001ffffffff05c09ee60500000000302ea22c802092392e766d63f73dd7c68ff9eaf9f009f13b17c4167472e8aebb00d96be66aa68103120c008203000401cc1027000000000000302ea22c80200648c12e7e058c98f0a5cc288ac271ad08bd493e1fb7de83edeea69789338fc58103120c008203000401cc40420f0000000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5acd7bb49a204000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5ac0000000000000000706a4c6dec4403921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70d75a5881417ab6700c089a6083d71abadc8cd74018bded0cfba423e027d513c8f2103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b50800000000ffffffff00000000

oraclesinfo

oraclesinfo oracletxid

The oraclesinfo method displays information about a specific oracle using oracletxid.

For a list of all oracletxid's available on the asset chain, see the oracleslist method.

Arguments

Name Type Description
oracletxid (string) the unique identifying transaction id of the oracle

Response

Name Type Description
result (string) whether the command executed successfully
txid (string) the unique txid, or oracletxid, that identifies the oracle
name (string) the name of the oracle contract
description (string) the description of the oracle contract
format (string) a string that identifies the data type accepted for the oracle contract (see oraclescreate)
marker (string) the unmodified public address generated from the oracle contract's privkey
registered: (array)
publisher (string) the unique identifier for the publisher (see oraclesregister)
baton (string) the baton address of the publisher, which is a CC address (based on the pubkey of the publisher and the EVAL code of the oracle contract)
batontxid (string) the most recent baton utxo sent to the baton address; this is the tip of the linked list that connects all data samples for the publisher
lifetime (number) the length of time since publisher's inception
funds (number) the funds committed by subscribers to the publisher's account, and which are used for payouts
datafee (number) the amount a subscriber pays for each data upload

📌 Examples

Command:

./komodo-cli -ac_name=HELLOWORLD oraclesinfo 0df7c4d844f08dba08abd4bb174558739f17cfe268feb005fb6333b3761d9203

oraclelist

oracleslist

The oraclelist method lists all available oracle contracts on the asset chain.

Arguments

Name Type Description
(none)

Response

Name Type Description
oracletxid (array of strings) the unique identifying oracletxid(s)

📌 Examples

Command:

./komodo-cli -ac_name=HELLOWORLD oracleslist

oraclesregister

oraclesregister oracletxid datafee

A user executes the oraclesregister method to register as a data publisher for an existing oracle contract.

The datafee property is set in satoshis, and should be >= the chain's default transaction fee.

The method returns a hex value which must then be broadcast using the sendrawtransaction method.

Use ./komodo-cli -ac_name=YOURNAME getrawmempool to verify the transaction is confirmed.

After the transaction confirms, use oraclesinfo to output registration information about your oracles plan

Arguments

Name Type Description
oracletxid (string) the unique identifying transaction id of the oracle
datafee (numbers) the fee required of a subscriber for each data point the publisher publishes in this oracle

Response

Name Type Description
result: (string) whether the command succeeded
hex: (string) a raw transaction in hex-encoded format; you must broadcast this transaction to complete the command

📌 Examples

Step 1: Set your parameters to create a raw transaction and get the hex value

./komodo-cli -ac_name=HELLOWORLD oraclesregister 0df7c4d844f08dba08abd4bb174558739f17cfe268feb005fb6333b3761d9203 1000000

Step 2: Send/broadcast the raw transaction hex

./komodo-cli -ac_name=HELLOWORLD sendrawtransaction 010000000103921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70d010000004847304402207241f313ef2fb65d9eb1f870068ceba436f14996ce79d16ff85f2937c75357ee022025f0b888e742546469ad0b7fae9b85cf7c89cddf307170bbcf794e5e90ae28b101ffffffff04102700000000000023210203921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70dac1027000000000000302ea22c80200648c12e7e058c98f0a5cc288ac271ad08bd493e1fb7de83edeea69789338fc58103120c008203000401cc071240a804000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5ac00000000000000004f6a4c4cec5203921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70d2103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b540420f000000000000000000

Step 3: Decode raw transaction (optional to check if the values are sane)

./komodo-cli -ac_name=HELLOWORLD decoderawtransaction 010000000103921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70d010000004847304402207241f313ef2fb65d9eb1f870068ceba436f14996ce79d16ff85f2937c75357ee022025f0b888e742546469ad0b7fae9b85cf7c89cddf307170bbcf794e5e90ae28b101ffffffff04102700000000000023210203921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70dac1027000000000000302ea22c80200648c12e7e058c98f0a5cc288ac271ad08bd493e1fb7de83edeea69789338fc58103120c008203000401cc071240a804000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5ac00000000000000004f6a4c4cec5203921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70d2103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b540420f000000000000000000

oraclessamples

oraclessamples oracletxid batonutxo num

The oraclessample method fetches data samples from a publisher.

The user indicates the desired publisher by inserting the batonutxo by the publisher. Use oraclesinfo to find a list of publishers and their current batonutxo's.

Arguments

Name Type Description
oracletxid (string) the unique identifying transaction id of the oracle contract
batonutxo (string) the baton transaction id, which can be found using the oraclesinfo method
num (number) the number of sample data points required

Response

Name Type Description
result (string) whether the command executed successfully
samples: (array of strings)
"XXXXXXXXXXX" (string) a sample data point

📌 Examples

Command:

./komodo-cli -ac_name=HELLOWORLD oraclessamples 0df7c4d844f08dba08abd4bb174558739f17cfe268feb005fb6333b3761d9203 abb4fc6d7fbff88c09b35fc40d96e3a04a891fbf3a2f21e8b8536acbd95d75d7 2

oraclessubscribe

oraclessubscribe oracletxid publisher amount

The user executes oraclessubscribe to subscribe to a publisher of an oracle plan.

Every publisher must have at least one subscriber before the oraclesdata can successfully execute.

The method returns a hex value which must then be broadcast using the sendrawtransaction method.

The sendrawtransaction method then returns a unique txid, also called the oraclesubscribtiontxid, or the id of the oracle subscription transaction. This can be used for further development purposes.

If the datafee is 10 COINS and the amount submitted is 1000 COINS, the publisher can publish data 100 times based on this amount.

Arguments

Name Type Description
oracletxid (string) the unique identifying transaction id of the oracle
publisher (string) the unique publisher id, which can be found using the oraclesinfo method
amount (number) the total amount of funds the subscriber commits to pay for data upload by the publisher; this amount is immediately withdrawn from the user's wallet

Response

Name Type Description
result (string) whether the command succeeded
hex (string) a raw transaction in hex-encoded format; you must broadcast this transaction to complete the command

📌 Examples

Step 1: Subscribe to an oracle plan and get the hex value:

./komodo-cli -ac_name=HELLOWORLD oraclessubscribe 0df7c4d844f08dba08abd4bb174558739f17cfe268feb005fb6333b3761d9203 03810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5 1

Step 2: Send raw transaction / broadcast the hex value

./komodo-cli -ac_name=HELLOWORLD sendrawtransaction 010000000175a5881417ab6700c089a6083d71abadc8cd74018bded0cfba423e027d513c8f0200000048473044022006449e2f324ba8c262ca73eea4642f77ccf906fee5bab4fdc85bcc8c350ce81b022047d76840076f6e02aebe77ffb59b052974badb8747c7b435fd77351fcfbee95e01ffffffff0400e1f50500000000302ea22c802092392e766d63f73dd7c68ff9eaf9f009f13b17c4167472e8aebb00d96be66aa68103120c008203000401cc102700000000000023210203921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70dace7e249a204000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5ac00000000000000004f6a4c4cec5303921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70d2103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b500e1f5050000000000000000

Step 3: Decode raw transaction (optional to check if the values are sane)

./komodo-cli -ac_name=HELLOWORLD decoderawtransaction 010000000175a5881417ab6700c089a6083d71abadc8cd74018bded0cfba423e027d513c8f0200000048473044022006449e2f324ba8c262ca73eea4642f77ccf906fee5bab4fdc85bcc8c350ce81b022047d76840076f6e02aebe77ffb59b052974badb8747c7b435fd77351fcfbee95e01ffffffff0400e1f50500000000302ea22c802092392e766d63f73dd7c68ff9eaf9f009f13b17c4167472e8aebb00d96be66aa68103120c008203000401cc102700000000000023210203921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70dace7e249a204000000232103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b5ac00000000000000004f6a4c4cec5303921d76b33363fb05b0fe68e2cf179f73584517bbd4ab08ba8df044d8c4f70d2103810d28146f60a42090991b044fe630d1664f3f8f46286c61e7420523318047b500e1f5050000000000000000