diff --git a/documents/protocols.md b/documents/protocols.md index ba4b823..3f25cd7 100644 --- a/documents/protocols.md +++ b/documents/protocols.md @@ -3,6 +3,24 @@ title: Protocols description: Understand how LBRY works low level and build your own implementations. --- +- [Blockchain P2P Protocol](/protocols/blockchain-p2p) + +- [Blockchain RPC Protocol](/protocols/blockchain-rpc) + + - [Content Protocol](/protocols/content) + + - [DHT Protocol](/protocols/dht) + + +- [Hub Protocol](/protocols/hub) +- [Hub Ping Protocol](/protocols/hub-ping) + + +- [Media Streaming Protocol](/protocols/media-streaming) + +- [Media RPC Protocol](/protocols/media-rpc) + + - [Reflector Protocol](/protocols/reflector) diff --git a/documents/protocols/blockchain-p2p.md b/documents/protocols/blockchain-p2p.md new file mode 100644 index 0000000..e09e048 --- /dev/null +++ b/documents/protocols/blockchain-p2p.md @@ -0,0 +1,10 @@ +--- +title: Blockchain P2P Protocol +description: The protocol used between blockchain nodes. +--- + +This protocol is used between blockchain nodes to communicate between each other. + +- **Port:** 9246/TCP + +See: [https://developer.bitcoin.org/reference/p2p_networking.html](Bitcoin.org P2P Network) diff --git a/documents/protocols/blockchain-rpc.md b/documents/protocols/blockchain-rpc.md new file mode 100644 index 0000000..4745412 --- /dev/null +++ b/documents/protocols/blockchain-rpc.md @@ -0,0 +1,10 @@ +--- +title: Blockchain RPC Protocol +description: The protocol used to query the blockchain. +--- + +This protocol is used to query information from the blockchain. For example, the LBRY hub uses this protocol to check for new blocks and to advance it into its own database. + +- **Port:** 9245/TCP + +See: [https://developer.bitcoin.org/reference/rpc/index.html](Bitcoin.org RPC API Reference) and [https://lbry.tech/api/blockchain](LBRY Blockchain API) diff --git a/documents/protocols/content.md b/documents/protocols/content.md index 070f650..2854ecd 100644 --- a/documents/protocols/content.md +++ b/documents/protocols/content.md @@ -9,7 +9,7 @@ This protocol provides a way to pull a blob from a specific node. The protocol u - **Port:** 4444/TCP (distributed peer) - **Port:** 5567/TCP (fixed peer) -### Availability +## Availability This request will check what blobs are available on the peer. It takes the sent list of blob hashes from `requested_blobs`, checks everyone of them, and returns a list of available blobs in `available_blobs`. Also, the request contains `lbrycrd_address`, which is a boolean property. In the response the `lbrycrd_address` property is a string containing an address. However, the use of `lbrycrd_address` for paying for blob data is not implemented yet. @@ -29,7 +29,7 @@ This request will check what blobs are available on the peer. It takes the sent {"lbrycrd_address":"bJxKvpD96kaJLriqVajZ7SaQTsWWyrGQct","requested_blobs":[]} ``` -### Payment Rate +## Payment Rate The reason behind this request is unknown at this moment. The request contains the `blob_data_payment_rate` property with a float. The result is always `RATE_ACCEPTED`, unless the float is below zero. Then the server will respond with `RATE_TOO_LOW`. At this moment, `RATE_UNSET` is not used. @@ -45,7 +45,7 @@ The reason behind this request is unknown at this moment. The request contains t {"blob_data_payment_rate":"RATE_UNSET"} ``` -### Blob +## Blob This request will get the blob itself. The hash will be sent using `requested_blob`. The server then reacts with an `incoming_blob`. If everything is correct, the `incoming_blob` contains a `blob_hash` property and a `length` property. The blob data directly follows after the JSON block response. If an error occurs, the `incoming_blob` contains an `error` property (and `blob_hash` is empty and `length` is zero). diff --git a/documents/protocols/dht.md b/documents/protocols/dht.md index 3311699..8840da6 100644 --- a/documents/protocols/dht.md +++ b/documents/protocols/dht.md @@ -17,7 +17,7 @@ The root dictionary can hold 5 properties: `0`, `1`, `2`, `3` and `4`. Note: Ben When a node wants to send an error back (it doesn't need to in every case), then the error message looks like the response message. However, the `3` property now contains the error type and optionally, `4` contains more information. -### Ping +## Ping The request has a property `3` with value `ping`. @@ -28,7 +28,7 @@ In protocol version `1`, there is 1 request argument: In both versions, the response has a property `3` with value `pong`. -### Find Node +## Find Node The request has a property `3` with value `findNode`. @@ -41,7 +41,7 @@ In protocol version `1`, there are 2 request arguments: In both versions, the response has a property `3` with a list as value. Every item in the list is a tuple (another list), containing the node ID as 48-byte string, the IP as string and the port as integer. -### Find Value +## Find Value The request has a property `3` with value `findValue`. @@ -58,11 +58,11 @@ In both versions, the response has a property `3` with a dictionary as value: - If the key is known by the node, `contacts` isn't required, but allowed to be present. The response now at least has a property with the same 48 byte long name as the key in the request. This property is a list, where every item in the list is a compact address. This compact address contains information on where the blob can be downloaded. - The optional `p` property is an integer with the amount of pages of download locations. If there are no download locations, the `p` value is integer `0`. If the `p` property is set in the request, the `contacts` property is absent. -#### Compact Address +### Compact Address The compact address is a value of 54 bytes. The first 4 bytes are the binary format of the IPv4 address. The next 2 bytes are the TCP port where the blob can be downloaded. The remanining 48 bytes are the node id of the associated DHT peer. -### Store +## Store The request has a property `3` with value `store`. diff --git a/documents/protocols/hub-ping.md b/documents/protocols/hub-ping.md new file mode 100644 index 0000000..9ff180f --- /dev/null +++ b/documents/protocols/hub-ping.md @@ -0,0 +1,8 @@ +--- +title: Hub Ping Protocol +description: The protocol used to ping a hub server to check if it is running. +--- + +This protocol is used to ping a hub server to check if it is running. If it is, the hub server also returns some additional information that can be used to determine if the hub server is a good fit for that client. + +- **Port:** 50001/UDP diff --git a/documents/protocols/hub.md b/documents/protocols/hub.md new file mode 100644 index 0000000..0f4fe65 --- /dev/null +++ b/documents/protocols/hub.md @@ -0,0 +1,17 @@ +--- +title: Hub Protocol +description: The protocol used to search and resolve claims, manage wallets, and quickly find blockchain information. +--- + +This protocol is used to search and resolve claims, manage wallets, and quickly find blockchain information. It is based on Bitcoin's BIP40, with some LBRY-specific additions, like Claimtrie methods. + +- **Port:** 50001/TCP +- **Port:** 50002/TCP (SSL/TLS) + +## Method: `blockchain.claimtrie.resolve` + +This method resolves specific LBRY claims and returns more information. + +## Method: `blockchain.claimtrie.search` + +This method search for LBRY claims by a set of keywords and some filters. diff --git a/documents/protocols/media-rpc.md b/documents/protocols/media-rpc.md new file mode 100644 index 0000000..6aa864f --- /dev/null +++ b/documents/protocols/media-rpc.md @@ -0,0 +1,10 @@ +--- +title: Media RPC Protocol +description: The protocol used to query the media server. +--- + +This protocol is used to query information from the media server. + +- **Port:** 5279/TCP + +See: [https://lbry.tech/api/sdk](LBRY SDK API) diff --git a/documents/protocols/media-streaming.md b/documents/protocols/media-streaming.md new file mode 100644 index 0000000..2366b5f --- /dev/null +++ b/documents/protocols/media-streaming.md @@ -0,0 +1,8 @@ +--- +title: Media Streaming Protocol +description: The protocol used to stream content from the media server. +--- + +This protocol is used to stream content from the media server. + +- **Port:** 5280/TCP diff --git a/documents/protocols/reflector.md b/documents/protocols/reflector.md index 0458463..e15388a 100644 --- a/documents/protocols/reflector.md +++ b/documents/protocols/reflector.md @@ -7,7 +7,7 @@ This protocol provides a way to actively push blobs to the network, instead of w - **Port:** 5566/TCP -### Handshake +## Handshake Before doing anything with blobs, the handshake should be sent. The `version` property is required and should be an integer valued `0` or `1`. If the server supports that version, it will send back an JSON block where the `version` property has the same value. If the `value` property contains an invalid protocol number or a protocol number that isn't supported, the server throws an error and closes the connection. @@ -23,7 +23,7 @@ Before doing anything with blobs, the handshake should be sent. The `version` pr {"version":1} ``` -### Blob Hash and Blob Size +## Blob Hash and Blob Size After the handshake, blobs can be received. First, the server wants to know more about the blob itself, before it wants to receive the blob data itself. The clients needs to send a JSON block with the blob hash and the blob size. It is important to note that this request is different for normal blobs and SD (Stream Descriptor) blobs. The properties `blob_hash` and `blob_size` are required OR the properties `sd_blob_hash` and `sd_blob_size` are required. The hash cannot be empty and the size cannot be zero or exceed the maximum blob size. @@ -53,7 +53,7 @@ Then, the server will check if it wants to receive the blob. It can do several c {"send_sd_blob":true,"needed_blobs":["aabbcc","ddeeff"]} // if version>=1 ``` -### Blob Data +## Blob Data If the server wants the blob, it will read exactly the amount of bytes that were stated in the blob information. If there goes something wrong with sending the blob data (e.g. there was a socket timeout or the blob hash calculation didn't match the blob hash from the blob information), the server will send a message that it didn't receive the blob. This will be a JSON block with the `received_blob` property for normal blobs and a JSON block with `received_sd_blob` for SD blobs. After this message, the client can send information about another blob.