"On Demand" Consensus Data

End consumer of consensus data dictates how it is validated and verified

Bitcoin Oracle produces the consensus data based on the computation from the off-chain engines, but the validation and verification of such consensus data can be implemented by the end consumer as they see fit.

For example, wallet integrating Bitcoin Oracle may implement a client-side verification of the consensus data, instead of relying on an on-chain validation.

A website that wants to display users' BRC20 balances, but do not need to verify the consensus data, may simply use the data without verification.

A BRC20 trading dapp on an EVM-compatible Bitcoin L2 may implement their own smart contract written in Solidity to validate the consensus data, before initiating other smart contract interactions.

So how can one fetch the consensus data from Bitcoin Oracle?

Summary data

If you need only the summary data, without its associated consensus data, you can use the following endpoints at https://api.alexgo.io.

GET/v1/brc20/bitcoin-tx-indexed
Query parameters
Response

Successfully returning bitcoin tx indexed

Body
from*string

from address

Example: "0xbc1pngxflzuqe5vevtc8fgmxzl69pw74x36dc9pmv5rye6nhwty0c0hsh5tyr3"
to*string

to address

Example: "0xbc1p06r44ervnukj3kxnqt863sz9hly5m7f80k7l94aplnd6z2tnrzvstdkzsq"
amt*string

amount of assets

Example: "10000000000000000000000000000"
tick*string

asset id

Example: "sats"
Request
const response = await fetch('/v1/brc20/bitcoin-tx-indexed', {
    method: 'GET',
    headers: {},
});
const data = await response.json();
Response
{
  "from": "0xbc1pngxflzuqe5vevtc8fgmxzl69pw74x36dc9pmv5rye6nhwty0c0hsh5tyr3",
  "to": "0xbc1p06r44ervnukj3kxnqt863sz9hly5m7f80k7l94aplnd6z2tnrzvstdkzsq",
  "amt": "10000000000000000000000000000",
  "tick": "sats"
}

Examples

curl --location 'https://api.alexgo.io/v1/brc20/user-balance?tick=ORMM&user=bc1p06r44ervnukj3kxnqt863sz9hly5m7f80k7l94aplnd6z2tnrzvstdkzsq' \
--header 'Accept: application/json'

Response

{
    "balance": "962959356579080000000000",
    "up-to-block": "825995"
}

Full consensus data

If you need the full consensus data, you can use the following endpoint at https://api.bitcoin-oracle.network.

The endpoint performs a match against an array where each item represents a distinct condition. If multiple query parameters are specified, such as from and height, the returned transactions must satisfy all the given conditions.

The endpoint supports query conditions for addresses in two formats: Bech32 and PKScript.

How to validate the consensus data

With the consensus data, you can

  1. determine if a minimum threshold you require was reached among data providers

  2. (for Stacks smart contracts) determine whether or not the relevant Bitcoin transaction was indeed mined

Validation of off-chain computation

order_hash is the sha256 hash of the following tuple:

{ 
    bitcoin-tx: (buff 8192), 
    output: uint, 
    offset: uint, 
    tick: (string-utf8 4), 
    amt: uint, 
    from: (buff 128), 
    to: (buff 128), 
    from-bal: uint, 
    to-bal: uint, 
    decimals: uint
}

Each data provider then creates and signs a sha256 hash of a concatenation of

  1. Structured data prefix: 0x534950303138

  2. Message domain: 0x6d11cd301d11961e7cfeabd61e3f4da17f42f3d627362c8878aa9cbb5c532be2

  3. order_hash

The addition of the structured data prefix and the message domain mitigates the message replay risk.

The signatures and public keys of the data providers, who validated the event, are available under signatures and signer_pubkeys, respectively, together with signer_types indicating which implementation or type each signer uses (for example, for BRC20, there are three types - bis, hiro and uinsat).

End consumer of this consensus data can then use these data to verify that each signer validated this particular BRC20 transfer.

Verification of Bitcoin transaction (Stacks only)

The consensus data provides additional information to allow smart contracts on Stacks to verify that the relevant Bitcoin transaction is indeed mined, which enhances the security and lessens its dependence on the off-chain data provider.

For more information, please refer to https://explorer.hiro.so/txid/SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.clarity-bitcoin-v1-06?chain=mainnet.

Examples

curl --location --request POST 'https://api.bitcoin-oracle.network/v1/brc20' \
--header 'x-service-type: INDEXER' \
--header 'x-version: 0.0.1' \
--data-raw '{
    "type": "tx_id",
    "tx_id":"9778d139d55f3dca60e4d45942cf6c0ab97e23fd24771696b9ecdfba52303b01",
    "output": 0,
    "offset": 0
}'

Response

{
    "data": [
        {
            "tx_hash": "020000000001022f119e4f00a1ea91771cd8dfc8e459cf98b7aac138aef6f4ff9394f53ab28faf0000000000fdffffff3f90f44767460ec0a742fe5320238cd05d8fbd3d292768ea5d5b38b29c7744760100000000fdffffff0322020000000000002251207e875ae46c9f2d28d8d302cfa8c045bfc94df9277dbdf2d7a1fcdba1297318998e0902000000000016001412c625feb11e662805f4923b289a15d6be803ed70000000000000000386a360c0000000204646573740100000000000000000000000000000000047573657205166f4c0cb79258561dddf49ad4b91479324935b0dd01403a09be942697dc269ae4766a2a885911fd477306cd3d5dfad03cad5377d887a7b59c0bf78734df40cd6d44940a20f5f02896911a43231e81b7ee864311cd8cd202473044022035237c80120014629af1b1f1db73f6ed74e748a5afd398e05ce35a81e56130f902204ef75df72cce7fc124ce4696cb8155b5dfad16950eea1c7de0eedc761ffa7ff00121025ce5bd977e990a1e653519333c35fa2d7531a1b5cc6737e2057165ff148aca5b00000000",
            "order_hash": "337d20f2431441591a46f8c65569e5e8bea98c70e0d6fa243ed19c4b40c3f9b7",
            "amt": "3700000000000000000000000",
            "bitcoin_tx": "00000020e7f505d8d9098cca86d39b4889f4ae4d2514929e16b0030000000000000000008d1d3bbee8ca41c87cea86e0d1eef44789a34051b3b48c68c4f358d488e75de8948e9f6569d80317921bb034",
            "decimals": "18",
            "from": {
                "pkscript": "5120aa9145519b90c95b6b41044bd7c63ea661bdb6c0bdbda590a4cb759f9978915b",
                "address": "bc1p42g525vmjry4k66pq39a03375esmmdkqhk76ty9yed6elxtcj9ds9pm7dt"
            },
            "from_bal": "0",
            "offset": "0",
            "output": "0",
            "tick": "ORMM",
            "to": {
                "pkscript": "51207e875ae46c9f2d28d8d302cfa8c045bfc94df9277dbdf2d7a1fcdba129731899",
                "address": "bc1p06r44ervnukj3kxnqt863sz9hly5m7f80k7l94aplnd6z2tnrzvstdkzsq"
            },
            "to_bal": "612741501250300100000000000",
            "tx_id": "9778d139d55f3dca60e4d45942cf6c0ab97e23fd24771696b9ecdfba52303b01",
            "proof_hashes": [
                "0048801e960dbf63c4602968259b23efc84d01b56f765c748d02b7387fda083c",
                "c2ad185f79ab5e04def0b4ae8a1b971f03d738501c999be7b04d453f115d0c99",
                "dde8ca635a80f4978049d95e53621f85b81a109e739c8a17e3a87589baff3378",
                "3f0a3723a1141af85387d1180c5d25fd5c0ba1de9d140d46b608511659d146e1",
                "02c2fe271149f95e3b2ce44441158c0e6459df5a75297df6d3e4733d78ee5577",
                "223866a29166b32436d84381dea03193a1fddcabe93d5752a05d42539c754641",
                "b58fd40d5861a7a1407315f2d91e328442fa25f4a9f2dc7a937aff2e05fb0c24",
                "f2d8b750b230ea7a05ab8c8f9c607410bfa8c85b1066128be835cd7f3fe3e787",
                "190320c66700b5bf8decea0a29491b5c3a0f53692823107dbe01b99af615c263",
                "fa3e58599aa6573f3702bf0d53bd306f57713a642b696142131b6e009257d600",
                "ecf791c893b78c40c2aad6125aea4ee5dd39d92a4ecbd421a9b38c90433dd3d3",
                "2c202c28b430c7b7b726b006c55a661af87fdcb349ded3becc5d563baa39cf8a"
            ],
            "tx_index": "2049",
            "tree_depth": "12",
            "height": "825254",
            "signers": [
                "SP1B0DHZV858RCBC8WG1YN5W9R491MJK88QPPC217",
                "SP35D14R1JB3KHE4D55MMN646GFZJ198B7FMBG5PD",
                "SP3ZCGVGSQWT6TJAXZRXHCYA6SWGNSNGKHSYA1F2Q"
            ],
            "signer_pubkeys": [
                "02883d08893252a59cf25aafffe1417bf74a7526621665a4bc0060e4aa95405891",
                "0255966348dacd748595af0439e0a1cc947b2e3dc090acd8f90c32c30c3099b0a0",
                "03c1a83abd5a199cb502818a110e2d55f67aae0e894f776c189b9f73556f8402a9"
            ],            
            "signer_types": [
                "bis",
                "hiro",
                "unisat"
            ],
            "signatures": [
                "0fc66c9a7fe85ce78740fcc07f60ac47d5a05c469b2ca5f1ee16f5cc4b6eda1e41367bd67b03e7fbc6e4ba883c6fad1551373bd786f59afefbed268d08e59fd500",
                "cd63d0ffae136ca1ffe1681ec4b062ada335b002b96b2a6153cea0a1f3ed94f14b601202ac2c8ecb229168c1264d0fad3475307df5a493ad98b9fae431f5138401",
                "f7045fca2269e91d632f4a259eb47cc9f3ebb17dd64f7b8f4dfc8aa2ecfb2e716bfcce5f3c8ec6be0987c6f620d8c4205cd8d0c9728ee73c8892768ffca211c101"
            ],
            "created_at": 1704970783160,
            "updated_at": 1704970783160
        }
    ]
}

PreviousWhy Bitcoin Oracle - BRC20NextThreshold-based Consensus

Last updated