Knowing Bitquery helps form a mental map of what is being written to the bitcoin blockchain. Some maps need a legend.
The purpose of this repo is to document specific queries that would be useful for real applications using the various bitcoin protocols. It is not intended to be a general guide to learning bitquery.
Nevertheless, we begin with some background materials for getting up to speed with bitquery.
Bitquery is the language of bitdb and bitsocket from unwriter. It is based on the mongo db query over documents.
The structure of the bitcoin transactions are called tna - as documented here.
The following links are useful to discover more query examples.
Bitquery playlist
More Bitsocket Examples
More Bitdb Examples
Genesis is starting point for all queries.
https://genesis.bitdb.network/
Explorer Endpoint:
https://genesis.bitdb.network/query/1FnauZ9aUH2Bex6JzdcV4eNX7oLSSEbxtN/<query>
API Endpoint:
https://genesis.bitdb.network/q/1FnauZ9aUH2Bex6JzdcV4eNX7oLSSEbxtN/<query>
A few queries not specific to any protocol can be helpful for debugging or building apps on bitcoin.
Find specific transaction by txid. When you just created a transaction and you want to see how bitdb shreaded the transaction.
Try it
{
"v": 3,
"q": {
"find": {"tx.h": "6f7147a7a6656139a1a3fb1e45c266c2534c8827fba9f0e71c07e2b45276265f"}
}
}
Find transactions going to an address. When your app needs to find out when it is being called.
Important! Genesis uses original bitcoin format for addresses. Make sure you are querying for the correct address format.
{
"v": 3,
"q": {
"find": {
"out.e.a": "19fhPw9rheNT9kT4BcLsNCyZhjo1QRivd8"
}
}
}
Use Raw Stream for BitSocket only to live stream all transactions when you just want to look at something. Makes for great Saturday night entertainment.
{
"v": 3,
"q": { "find": {} }
}
Get random transactions. Might useful for your SPV wallet to obfuscate your address monitoring in case someone is watching you.
Try it
{
"v": 3,
"q": {
"db": ["c"],
"aggregate": [{ "$sample": { "size": 10 } }]
}
}
| Protocol | Docs |
|---|---|
| memo | memo docs |
| matter | matter docs |
| blockpress | blockpress docs |
| tokenized | tokenized docs |
| bitcoin token | bitcointoken docs |
| SLP | SLP docs |
| bitcoinfiles | bitcoinfiles docs |
Example: Find memo posts.
{
"v": 3,
"q": {
"find": {
"out.b0": { "op": 106 },
"out.h1": "6d02"
},
"limit": 10
}
}
Example: Find memo posts and posts with topics.
{
"v": 3,
"q": {
"find": {
"out.b0": { "op": 106 },
"out.h1": { "$in": ["6d02", "6d0c"] }
},
"limit": 10
}
}
Tokenized is a plethora of smart contract definitions where all the use cases have been carefully analyzed.
Tokenized protocol is implemented as a fixed width message with a prefix 00000020
Example: Find tokenized data. This example is great because it shows how to transform the transactions to just select the outs with the data that you want.
{
"v": 3,
"q": {
"db": ["c"],
"find": {
"out.b0": { "op": 106 },
"out.str": { "$regex": "^OP_RETURN 00000020" }
},
"limit": 3,
"project": { "tx": 1, "out": 1, "_id": 0 }
},
"r": {
"f": "[ .[] | (.out[] | select(.b0.op==106)) as $outWithData | {tx: .tx.h, msg: $outWithData.s1}]"
}
}
bitcointoken site
bitcointoken docs
BitcoinToken is interesting because the project is working on the concept of data ownership, data that is "updatable" on the blockchain by the data owner and can be "shared" with other co-owners.
Data stored in this way comes with a very strong guaranty: only the person in possession of the private key for 0x03a70e0e5f7... can spend the output containing the data. We call that user the owner of the data. By default the user to issue the command is the owner, to designate a different owner, pass in that users public key as the second argument. Multiple public keys can be passed in to model co-ownership of data.
Also, check out how they are storing json on the blockchain (i.e. key-value pairs).
const outputId = await db.put({
text: 'Lorem ipsum',
author: 'Alice'
})
The above json encoded on the blockchain.
4 0x74657874 OP_DROP // text
11 0x4c6f72656d20697073756d OP_DROP // Lorem ipsum
6 0x617574686f72 OP_DROP // author
13 0x416c69636520616e6420426f62 OP_DROP // Alice and Bob
Example: Find all posts.
{
"v": 3,
"q": {
"find": {
"out.b0": { "op": 106 },
"out.h1": "9d02"
},
"limit": 10
}
}
Example: Find blockpress posts.
{
"v": 3,
"q": {
"find": {
"out.b0": { "op": 106 },
"out.h1": "8d02"
},
"limit": 10
}
}