diff --git a/Herald-API.md b/Herald-API.md new file mode 100644 index 0000000..16e2e56 --- /dev/null +++ b/Herald-API.md @@ -0,0 +1,239 @@ +Herald API Specification +=============================== + +Herald uses the stratum protocol used by bitcoin. Over stratum it provides many of the electrum APIs common to other blockchains as well as some LBRY specific ones. + + +**Format** +------ + +Stratum protocol is based on [JSON-RPC 2.0](http://www.jsonrpc.org/specification) (although it doesn't +include "jsonrpc" information in every message). Each +message has to end with a line end character (\n). + +A typical request looks like this: + +``` + { "id": 0, "method":"some.stratum.method", "params": [] } +``` +- id begins at 0 and every message has its unique id number +- list and description of possible methods is below +- params is an array, e.g.: [ "1myfirstaddress", "1mysecondaddress", "1andonemoreaddress" ] + + +Responses are similar: + +``` + { "id": 0, "result": "616be06545e5dd7daec52338858b6674d29ee6234ff1d50120f060f79630543c"} +``` +- id is copied from the request message (this way client can pair each + response to one of his requests) +- result can be: + + - null + - a string (as shown above) + - a hash map, e.g.: + + ``` + { "nonce": 1122273605, "timestamp": 1407651121, "version": 2, "bits": 406305378 } + ``` + - an array of hash maps, e.g.: + ``` + [ { "tx_hash: + "b87bc42725143f37558a0b41a664786d9e991ba89d43a53844ed7b3752545d4f", + "height": 314847 }, { "tx_hash": + "616be06545e5dd7daec52338858b6674d29ee6234ff1d50120f060f79630543c", + "height": 314853 } ] + ``` + - a base64 encoded protobuf (string) + + +**Subscriptions** +------ +These +- `blockchain.address.subscribe` +- `blockchain.address.unsubscribe` +- `blockchain.scripthash.subscribe` +- `blockchain.scripthash.unsubscribe` +- `blockchain.headers.subscribe` +- `server.peers.subscribe` + + +**Methods** +------ +- `blockchain.address.get_history` + ```shell + echo -e -n '{ "id": 0, "method":"blockchain.address.get_history", "params": ["bEaiqayiRLt4A1m423LRWJW42CtPzSLVox"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1 + ``` + ```json + {"jsonrpc":"2.0","result":[{"tx_hash":"d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6","height":682018}],"id":0} + ``` +- `blockchain.address.get_mempool` + ```shell + echo -e -n '{ "id": 0, "method":"blockchain.address.get_mempool", "params": ["bEaiqayiRLt4A1m423LRWJW42CtPzSLVox"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1 + ``` + ```json + ``` +- `blockchain.address.listunspent` + ```shell + echo -e -n '{ "id": 0, "method":"blockchain.address.listunspent", "params": ["bEaiqayiRLt4A1m423LRWJW42CtPzSLVox"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1 + ``` + ```json + {"jsonrpc":"2.0","result":[{"tx_hash":"d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6","tx_pos":1,"height":682018,"value":383600}],"id":0} + ``` +- `blockchain.address.getbalance` + ```shell + echo -e -n '{ "id": 0, "method":"blockchain.address.getbalance", "params": ["bEaiqayiRLt4A1m423LRWJW42CtPzSLVox"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1 + ``` + ```json + {"jsonrpc":"2.0","result":{"confirmed":383600,"unconfirmed":0},"id":0} + ``` +- `blockchain.scripthash.get_history` + ```shell + ``` + ```json + ``` +- `blockchain.scripthash.get_mempool` + ```shell + ``` + ```json + ``` +- `blockchain.scripthash.get_balance` + ```shell + ``` + ```json + ``` +- `blockchain.scripthash.listunspent` + ```shell + ``` + ```json + ``` +- `blockchain.block.get_chunk` + ```shell + ``` + ```json + ``` +- `blockchain.block.get_header` + ```shell + ``` + ```json + ``` +- `blockchain.block.headers` + ```shell + ``` + ```json + ``` +- `blockchain.block.get_server_height` + ```shell + ``` + ```json + ``` +- `blockchain.claimtrie.search` + Returns an `Outputs` protobuf result + + ```shell + ``` + ```json + ``` +- `blockchain.claimtrie.resolve` + Returns an `Outputs` protobuf result + + ```shell + echo -e -n '{ "id": 0, "method":"blockchain.claimtrie.resolve", "params": ["lbry://@lbrytech:19/hubba-hubba:6"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1 + ``` + ```json + {"jsonrpc":"2.0","result":"CqABCiBiN5OmXDN7dwLrwYVmDswlflCvI6ZsjO5C9XeUH79u9xjy4kc6eAomCiAUuKn9XeBuKaZUKHdxSKPEcUEr3L5u5Y7+XfEVFMCbvRjdv0IaDWh1YmJhLWh1YmJhIzYiGkBsYnJ5dGVjaCMxOS9odWJiYS1odWJiYSM2KAEw6eFHOOnhR0Dy4kdI8ovIAVgIoAHXuMDU\/A6oAZe0g9T8DhJnCiAUuKn9XeBuKaZUKHdxSKPEcUEr3L5u5Y7+XfEVFMCbvRjdv0I6PxoMQGxicnl0ZWNoIzE5IgxAbGJyeXRlY2gjMTkoATC4kSw42YwsQN2\/Qkjd6MIBUBWgAcD4s\/ITqAHAlpGqEg==","id":0} + ``` +- `blockchain.claimtrie.getclaimbyid` + Returns an `Outputs` protobuf result + + ```shell + echo -e -n '{ "id": 0, "method":"blockchain.claimtrie.getclaimbyid", "params": ["6b38744341412a6abcf5cf3ac215ade64907905b"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1 + ``` + ```json + {"jsonrpc":"2.0","result":"CqABCiBiN5OmXDN7dwLrwYVmDswlflCvI6ZsjO5C9XeUH79u9xjy4kc6eAomCiAUuKn9XeBuKaZUKHdxSKPEcUEr3L5u5Y7+XfEVFMCbvRjdv0IaDWh1YmJhLWh1YmJhIzYiGkBsYnJ5dGVjaCMxOS9odWJiYS1odWJiYSM2KAEw6eFHOOnhR0Dy4kdI8ovIAVgIoAHXuMDU\/A6oAZe0g9T8DhJnCiAUuKn9XeBuKaZUKHdxSKPEcUEr3L5u5Y7+XfEVFMCbvRjdv0I6PxoMQGxicnl0ZWNoIzE5IgxAbGJyeXRlY2gjMTkoATC4kSw42YwsQN2\/Qkjd6MIBUBWgAcD4s\/ITqAHAlpGqEg==","id":0} + ``` +- `blockchain.transaction.broadcast` + ```shell + ``` + ```json + ``` +- `blockchain.transaction.get` + ```shell + ``` + ```json + ``` +- `blockchain.transaction.get_batch` + ```shell + echo -e -n '{ "id": 0, "method":"blockchain.transaction.get_batch", "params": ["d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1 + ``` + ```json + {"jsonrpc":"2.0","result":{"d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6":["010000000282a2750b0a78cb74f427438dfe569aad05020caaad0d1aa58e8c01ccaf25bcfa000000006a47304402207dc3309ae0be9078e1363d76b23533b8c6ff0f15853d98d7162359dce29c6ec4022074837d3f402edb83f004e4ce8bd6cf57aacf3b2e485f2bbba426293fd65cab0701210268b787a2cd3fbdd5c3b1fc9daa9fecd0c5e7cad7490a83a62d2adf3a75d96fc6ffffffffa5d4d2f2633876a48889d64810028b7e33cf157977f5872706baaf264814d2ca010000006b483045022100ba04f06c15330fc3cdc06475f99094833c27d931d917ecb24a7782c6e3271658022040a77d504c198128e125a9b5e5c6432b36967bbd91667184b170eda4cf94632501210255d29e1ec9c61c2c42d4c5419e1ae96121edaa380ec1bc763d2f402d50fe59c1ffffffff024054890000000000fd5c01b705406c627279141af0d12eeeb2b95f2298e3dfeeacfa926a83da3f4d22010012ba010a583056301006072a8648ce3d020106052b8104000a03420004bf069ae512dcfc6aca2c04b983dbc983be0e3111e3d15366851a5938f509a13936d15822e89839397acf0634eecf755bf0525c2516c68b91c5ca15b887296bbf120e68656c6c6f406c6272792e636f6d1a1068747470733a2f2f6c6272792e636f6d223c2a3a68747470733a2f2f737065652e63682f342f36386631613839612d623664662d343634662d613438312d3038383562333466666161352e6a706742044c425259523c2a3a68747470733a2f2f737065652e63682f382f38356239343635342d646263332d346635342d623035342d6631633538373337396637352e706e675a044c4252595a044e6577735a0a626c6f636b636861696e5a0663727970746f6d6d76a914fadd6786cb77bd115a3fc9a10f9dd2a81bdb3a7288ac70da0500000000001976a914145254f61071e77c6802b1bc6c08648ceb7cd34688ac00000000",{"block_height":682018,"merkle":["1c76ac5c97d2d00deb4b891065a7cbfe0c405801e9a0035d4c4c7c9179ad3431","ef69ca48645347096b3b3b6f25c926756e88aad0d3a4b125cd081ebb4e8c197d","5e5951947cb31c33f053361d149b26c59f598af01c24b21af580987023425497","7e4e2684427205f5623f41325ed21279685b909125e21f7cb4f7e417b2857d89","212d7086b78968f4052175bee267d6c2f9942f3153edc5ca5162315387f85fde","0bd91a08621bc471afe73f5d6b41a74569c9f2c800718c22c2f7c4e9402a35ba"],"pos":48}]},"id":0} + ``` +- `blockchain.transaction.info` + ```shell + echo -e -n '{ "id": 0, "method":"blockchain.transaction.info", "params": ["d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1 + ``` + ```json + {"jsonrpc":"2.0","result":["010000000282a2750b0a78cb74f427438dfe569aad05020caaad0d1aa58e8c01ccaf25bcfa000000006a47304402207dc3309ae0be9078e1363d76b23533b8c6ff0f15853d98d7162359dce29c6ec4022074837d3f402edb83f004e4ce8bd6cf57aacf3b2e485f2bbba426293fd65cab0701210268b787a2cd3fbdd5c3b1fc9daa9fecd0c5e7cad7490a83a62d2adf3a75d96fc6ffffffffa5d4d2f2633876a48889d64810028b7e33cf157977f5872706baaf264814d2ca010000006b483045022100ba04f06c15330fc3cdc06475f99094833c27d931d917ecb24a7782c6e3271658022040a77d504c198128e125a9b5e5c6432b36967bbd91667184b170eda4cf94632501210255d29e1ec9c61c2c42d4c5419e1ae96121edaa380ec1bc763d2f402d50fe59c1ffffffff024054890000000000fd5c01b705406c627279141af0d12eeeb2b95f2298e3dfeeacfa926a83da3f4d22010012ba010a583056301006072a8648ce3d020106052b8104000a03420004bf069ae512dcfc6aca2c04b983dbc983be0e3111e3d15366851a5938f509a13936d15822e89839397acf0634eecf755bf0525c2516c68b91c5ca15b887296bbf120e68656c6c6f406c6272792e636f6d1a1068747470733a2f2f6c6272792e636f6d223c2a3a68747470733a2f2f737065652e63682f342f36386631613839612d623664662d343634662d613438312d3038383562333466666161352e6a706742044c425259523c2a3a68747470733a2f2f737065652e63682f382f38356239343635342d646263332d346635342d623035342d6631633538373337396637352e706e675a044c4252595a044e6577735a0a626c6f636b636861696e5a0663727970746f6d6d76a914fadd6786cb77bd115a3fc9a10f9dd2a81bdb3a7288ac70da0500000000001976a914145254f61071e77c6802b1bc6c08648ceb7cd34688ac00000000",{"block_height":682018,"merkle":["1c76ac5c97d2d00deb4b891065a7cbfe0c405801e9a0035d4c4c7c9179ad3431","ef69ca48645347096b3b3b6f25c926756e88aad0d3a4b125cd081ebb4e8c197d","5e5951947cb31c33f053361d149b26c59f598af01c24b21af580987023425497","7e4e2684427205f5623f41325ed21279685b909125e21f7cb4f7e417b2857d89","212d7086b78968f4052175bee267d6c2f9942f3153edc5ca5162315387f85fde","0bd91a08621bc471afe73f5d6b41a74569c9f2c800718c22c2f7c4e9402a35ba"],"pos":48}],"id":0} + ``` +- `blockchain.transaction.get_merkle` + ```shell + ``` + ```json + ``` +- `blockchain.transaction.get_height` + ```shell + echo -e -n '{ "id": 0, "method":"blockchain.transaction.get_height", "params": ["d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1 + ``` + ```json + ``` +- `blockchain.estimatefee` + ```shell + ``` + ```json + ``` +- `blockchain.relayfee` + ```shell + ``` + ```json + ``` +- `mempool.get_fee_histogram` + ```shell + ``` + ```json + ``` +- `server.ping` + ```shell + ``` + ```json + ``` +- `server.banner` + ```shell + ``` + ```json + ``` +- `server.payment_address` + ```shell + ``` + ```json + ``` +- `server.donation_address` + ```shell + ``` + ```json + ``` +- `server.features` + ``` + echo -e -n '{ "id": 0, "method":"server.features", "params": []}\n' | timeout 2 nc spv19.lbry.com 50001 -i 1 + ``` + ``` + {"jsonrpc":"2.0","result":{"hosts":{},"pruning":null,"server_version":"0.107.0","protocol_min":"0.54.0","protocol_max":"0.199.0","genesis_hash":"9c89283ba0f3227f6c03b70216b9f665f0118d5e0fa729cedf4fb34d6a34f463","description":"","payment_address":"","donation_address":"","daily_fee":"0","hash_function":"sha256","trending_algorithm":"fast_ar"},"id":0} + ``` +- `server.version` + ``` + echo -e -n '{ "id": 0, "method":"server.version", "params": []}\n' | timeout 2 nc spv19.lbry.com 50001 -i 1 + ``` + ``` + {"jsonrpc":"2.0","result":["0.107.0","0.54.0"],"id":0} + ```