Created Herald API (markdown)

2022-10-14 10:08:41 -04:00 · 2022-10-14 10:08:41 -04:00 · 23cf89db1d
commit 23cf89db1d
parent 351843ad00
1 changed files with 239 additions and 0 deletions
--- a/Herald-API.md
+++ 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}
+   ```