Fixed grammatical usage, typos, punctuation, and other errors

This commit is contained in:
michizhou 2018-10-20 15:13:10 -04:00
parent 5a24d118ef
commit b613105947
8 changed files with 69 additions and 69 deletions

View file

@ -1,8 +1,8 @@
# API wrappers for the LBRY blockchain and protocol # API wrappers for the LBRY blockchain and protocol
This document contains a comprehensive list of all available API wrappers for the LBRY protocol and blockchain. API wrappers allow easier integration of the LBRY APIs into your codebase. They still require you to run either the [LBRY protocol](https://github.com/lbryio/lbry) and/or the [LBRY blockchain](https://github.com/lbryio/lbrycrd). This document contains a comprehensive list of all available API wrappers for the LBRY protocol and blockchain. API wrappers allow for easier integration of the LBRY APIs into your codebase. They still require you to run either the [LBRY protocol](https://github.com/lbryio/lbry) or the [LBRY blockchain](https://github.com/lbryio/lbrycrd).
Interested in creating one for a language not shown below, see our [bounties page](https://lbry.io/bounty/lbry-binding) for details. Interested in creating one for a language not shown below? See our [bounties page](https://lbry.io/bounty/lbry-binding) for details.
## List of API wrapper resources ## List of API wrapper resources
| Language | Creator/Contact | GitHub Repository / Other Links | Status | | Language | Creator/Contact | GitHub Repository / Other Links | Status |

View file

@ -2,19 +2,19 @@
How the data structure that organizes claims by names works, how proofs are generated/verified and how consensus on the state of the trie is represented. How the data structure that organizes claims by names works, how proofs are generated/verified and how consensus on the state of the trie is represented.
For looking into how claims end up in the trie, [read that instead](https://lbry.io/faq/claimtrie-implementation). For looking into how claims end up in the trie, [read this instead](https://lbry.io/faq/claimtrie-implementation).
## The Trie ## The Trie
A Trie is an ordered tree data structure. Think of it as a hash map or dictionary where the keys are ordered and organized in prefixes. It's used for storing claims by name and looks (a bit) like that: A Trie is an ordered tree data structure. Think of it as a hash map or dictionary where the keys are ordered and organized in prefixes. It's used for storing claims by name and looks (a bit) like this:
![Wikipedia claimtrie](https://upload.wikimedia.org/wikipedia/commons/thumb/b/be/Trie_example.svg/400px-Trie_example.svg.png) ![Wikipedia claimtrie](https://upload.wikimedia.org/wikipedia/commons/thumb/b/be/Trie_example.svg/400px-Trie_example.svg.png)
You can read more on it [here](https://en.wikipedia.org/wiki/Trie), but for understanding the claimtrie let's just think of it as a mapping of names and claims where you can easily find which character of a name preffix forms a collision. Like the first `t` for `{to, tea, ted, ten}` and the `e` in `te` for `{tea, ted, ten}`. You can read more on it [here](https://en.wikipedia.org/wiki/Trie), but for understanding the ClaimTrie let's just think of it as a mapping of names and claims where you can easily find which character of a name prefix forms a collision. Like the first `t` for `{to, tea, ted, ten}` and the `e` in `te` for `{tea, ted, ten}`.
## Consensus ## Consensus
Each block header holds an extra 256 bits value calculated out of the root node of the claim trie at that block height. It's called `nameclaimroot` and is influenced by all children nodes as we will see next. If a blockchain network peer disagrees that a claim name was accepted or who is the winner of each name, its `nameclaimroot` will differ and the block won't form the same chain as the ones that accepted the official rules. This is the same for the traditional Merkle Root, which is the root of the [Merkle Tree](https://bitcoin.org/en/glossary/merkle-tree), formed by transactions in a block. Each block header holds an extra 256 bits value calculated out of the root node of the claim trie at that block height. It's called `nameclaimroot` and is influenced by all children nodes as we will see next. If a blockchain network peer disagrees that a claim name was accepted or who is the winner of each name, its `nameclaimroot` will differ and the block won't form the same chain as the ones that accepted the official rules. This is the same for the traditional Merkle root, which is the root of the [Merkle tree](https://bitcoin.org/en/glossary/merkle-tree), formed by transactions in a block.
## What's in a leaf? ## What's in a leaf?
The leaf currently holds the winner of that name. Its formed by the transaction hash, output number of the claim in that transaction and the height it was accepted. The leaf currently holds the winner of that name. Its formed by the transaction hash, output number of the claim in that transaction and the height it was accepted.
@ -22,8 +22,8 @@ The leaf currently holds the winner of that name. Its formed by the transaction
### Generating the leaf hash ### Generating the leaf hash
So, let's suppose that the winner claim of `mindblown` name was made at transaction output `1` of the transaction hash `67ad533eb2676c9d36bfa100092af5358de747e08ef928c0c54a8b3891c2b76b` and included in the Trie at height `102`. So, let's suppose that the winner claim of `mindblown` name was made at transaction output `1` of the transaction hash `67ad533eb2676c9d36bfa100092af5358de747e08ef928c0c54a8b3891c2b76b` and included in the Trie at height `102`.
1. The transaction hash is converted from [RPC byte order](https://bitcoin.org/en/glossary/rpc-byte-order) to [internal byte order](https://bitcoin.org/en/glossary/internal-byte-order). 1. The transaction hash is converted from [RPC byte order](https://bitcoin.org/en/glossary/rpc-byte-order) to [internal byte order](https://bitcoin.org/en/glossary/internal-byte-order).
2. The output number as a simple string. 2. The output number becomes a simple string.
3. The height as a big endian 64 bits value. 3. The height becomes a big endian 64 bits value.
4. The node hash is calculated as the double sha-256 hash of the double sha-256 hash of the internal byte order representation of the transaction hash concatenated with the double sha-256 hash of the output number representation concatenated with the double sha-256 hash of the height. 4. The node hash is calculated as the double sha-256 hash of the double sha-256 hash of the internal byte order representation of the transaction hash concatenated with the double sha-256 hash of the output number representation concatenated with the double sha-256 hash of the height.
This is better represented in the simple python script below: This is better represented in the simple python script below:
@ -46,10 +46,10 @@ def hash_leaf(tx, nout, height):
print("leaf hash is {}".format(hexlify(hash_leaf(tx, nout, at_height)[::-1]))) print("leaf hash is {}".format(hexlify(hash_leaf(tx, nout, at_height)[::-1])))
``` ```
## How the root hash is calculated? ## How is the root hash calculated?
Let's start with a Claim Trie holding a single claim. Let's start with a ClaimTrie holding a single claim.
The claim is named `mindblown` and was included at block 102 with the same details as the last section. It's actually a real claim as [you can see in the block explorer](https://explorer.lbry.io/blocks/102). This block has the first claim ever, so the claimtrie was the simple case being explained in here. The claim is named `mindblown` and was included at block 102 with the same details as the last section. It's actually a real claim as [you can see in the block explorer](https://explorer.lbry.io/blocks/102). This block has the first claim ever, so the ClaimTrie was the simple case being explained in here.
We start with the leaf hash: We start with the leaf hash:
1. Hash the leaf hash using double sha-256. 1. Hash the leaf hash using double sha-256.
2. For each character of the name (nodes of the trie), the hash of a node is the double sha-256 of the node's character concatenated with the children hash. 2. For each character of the name (nodes of the trie), the hash of a node is the double sha-256 of the node's character concatenated with the children hash.
@ -67,5 +67,5 @@ print("root hash is {}".format(hexlify(hash_single_claim_trie(name, tx, nout, at
## What if there are more leafs? ## What if there are more leafs?
Just concatenate the node character with the childrens hashes sha256d(character + leftmost child hash + ... + rightmost child hash ). Just concatenate the node character with the childrens hashes sha256d(character + leftmost child hash + ... + rightmost child hash ).
TO BE IMPROVED TO BE IMPROVED

View file

@ -1,4 +1,4 @@
# How To Dowload Content Using the LBRY Protocol # How To Download Content Using the LBRY Protocol
## Getting Started ## Getting Started
@ -22,7 +22,7 @@ For this example, we will use claimID `d9317ac7842f88ba442fee749c4f834353c24206`
- dht gets you **peers** for the sd hash - dht gets you **peers** for the sd hash
- blob exchange gets **sd blob** from peers - blob exchange gets **sd blob** from peers
- sd blob is parsed to get **content hashes** - sd blob is parsed to get **content hashes**
- dht then blob exchange get you the **content blobs** - dht and then blob exchange get you the **content blobs**
- blobs are decrypted and assembled to create the **file** - blobs are decrypted and assembled to create the **file**
@ -77,7 +77,7 @@ The SD blob is JSON-formatted text. It contains a dictionary with the following
} }
``` ```
All string field are hex-encoded. All string fields are hex-encoded.
To download the content blobs, repeat the steps we took for the SD hash, but instead use the `blob_hash` value for each blob. Look up the blob_hash in the DHT to find hosts, then download the blob from those hosts. To download the content blobs, repeat the steps we took for the SD hash, but instead use the `blob_hash` value for each blob. Look up the blob_hash in the DHT to find hosts, then download the blob from those hosts.

View file

@ -1,8 +1,8 @@
# LBRY Claimtrie # LBRY ClaimTrie
This document describes the implementation detail of the ClaimTrie in LBRY. The ClaimTrie is the data structure which LBRY uses to store claims to names. It uses a [Trie](https://en.wikipedia.org/wiki/Trie) to efficiently store all claimed names, which can then be hashed the same way a [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree) is hashed. The root hash of the ClaimTrie is stored in the blockheader of each LBRY block, enabling nodes in the LBRY network to efficiently and securely validate the state of the ClaimTrie. This document describes the implementation detail of the ClaimTrie in LBRY. The ClaimTrie is the data structure which LBRY uses to store claims to names. It uses a [Trie](https://en.wikipedia.org/wiki/Trie) to efficiently store all claimed names, which can then be hashed the same way a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) is hashed. The root hash of the ClaimTrie is stored in the blockheader of each LBRY block, enabling nodes in the LBRY network to efficiently and securely validate the state of the ClaimTrie.
Bids to claim a name must win out against other claims for the same name before they can be inserted into the ClaimTrie. The short summary is that the bid with the most LBRY credits assigned to it will win the right to claim a name, but the implementation detail is more involved and, this is what we aim to cover in this document. Bids to claim a name have four properties tied to it : Bids to claim a name must win out against other claims for the same name before they can be inserted into the ClaimTrie. The short summary is that the bid with the most LBRY credits assigned to it will win the right to claim a name, but the implementation detail is more involved and this is what we aim to cover in this document. Bids to claim a name have four properties tied to it :
1. *Name* : The name is a human-readable address and is the property that the bids compete to obtain. 1. *Name* : The name is a human-readable address and is the property that the bids compete to obtain.
2. *Value* : The value is the data that is attached to the name. 2. *Value* : The value is the data that is attached to the name.
@ -11,7 +11,7 @@ Bids to claim a name must win out against other claims for the same name before
There are also three different bid types: claim, update, and support. There are also three different bid types: claim, update, and support.
1. *Claim*: A claim represent new bids for a name. If a user wants to make a claim to a brand new name, or submit a competing claim to an existing name, this bid type is used. 1. *Claim*: A claim represents new bids for a name. If a user wants to make a claim to a brand new name, or submit a competing claim to an existing name, this bid type is used.
2. *Support*: A support adds to the total quantity of credits assigned to any bid by referring to a bid's Claim Id. A support bid can be made by anyone on any bid. It does not have its own Value or its own Claim Id, but it does contain the Claim Id of the bid that it is supporting. 2. *Support*: A support adds to the total quantity of credits assigned to any bid by referring to a bid's Claim Id. A support bid can be made by anyone on any bid. It does not have its own Value or its own Claim Id, but it does contain the Claim Id of the bid that it is supporting.
3. *Update*: An update can modify the value and the quantity for a pre-existing claim without changing the Claim Id or the name that it is bidding on. Since the Claim Id of the original bid is not changed, an updated bid will still retain all the supports attached to the original bid. 3. *Update*: An update can modify the value and the quantity for a pre-existing claim without changing the Claim Id or the name that it is bidding on. Since the Claim Id of the original bid is not changed, an updated bid will still retain all the supports attached to the original bid.
@ -29,7 +29,7 @@ This section describes how bids are processed by the ClaimTrie in order to deter
* HeightA = the most recent height at which the bid controlling the name changed * HeightA = the most recent height at which the bid controlling the name changed
* HeightB = the current height * HeightB = the current height
* Maximum delay is 7 days of blocks at 2.5 min/block (or 4032 blocks). Thus maximum delay can be reached in 224 (7x32) days. * Maximum delay is 7 days of blocks at 2.5 min/block (or 4032 blocks). Thus maximum delay can be reached in 224 (7x32) days.
* The bid's Claim Id matches the Claim Id of the bid which was the controlling bid immediately before the block containing this bid was included in the blockchain. In other words, it is either an update to the previous controlling bid or update to update to the previous controlling bid if the bid was updated twice in this block, etc. * The bid's Claim Id matches the Claim Id of the bid which was the controlling bid immediately before the block containing this bid was included in the blockchain. In other words, it is either an update to the previous controlling bid or an update to an update to the previous controlling bid if the bid was updated twice in this block, etc.
4. *Controlling*: This bid currently controls the name. When clients ask which bid controls the name as of the current block, this is the bid that will be returned. Must be in the "active" state and only one bid for any name may be in this state. A support cannot be in the "controlling" state. To determine which "active" bid is the "controlling" bid for each name: 4. *Controlling*: This bid currently controls the name. When clients ask which bid controls the name as of the current block, this is the bid that will be returned. Must be in the "active" state and only one bid for any name may be in this state. A support cannot be in the "controlling" state. To determine which "active" bid is the "controlling" bid for each name:
* Add the quantity of each 'active' bid to the quantity of all 'active' supports for that bid, and take whichever is greatest. If two bids have the same quantity, older bids take precedence over newer bids. * Add the quantity of each 'active' bid to the quantity of all 'active' supports for that bid, and take whichever is greatest. If two bids have the same quantity, older bids take precedence over newer bids.
* If the bid with the greatest amount does not have the same claimID as the bid which was 'controlling' prior to including the current block, change the delay for the name as of the current block to 0, redetermine which bids and supports should be active, and then perform the previous calculation again. * If the bid with the greatest amount does not have the same claimID as the bid which was 'controlling' prior to including the current block, change the delay for the name as of the current block to 0, redetermine which bids and supports should be active, and then perform the previous calculation again.
@ -47,7 +47,7 @@ OP_CLAIM_NAME <Name> <Value> OP_2DROP OP_DROP [script pubkey]
OP_UPDATE_CLAIM <Name> <ClaimId> <Value> OP_2DROP OP_2DROP [script pubkey] OP_UPDATE_CLAIM <Name> <ClaimId> <Value> OP_2DROP OP_2DROP [script pubkey]
OP_SUPPORT_CLAIM <Name> <ClaimId> OP_2DROP OP_DROP [script pubkey] OP_SUPPORT_CLAIM <Name> <ClaimId> OP_2DROP OP_DROP [script pubkey]
``` ```
[script pubkey] can be any valid Bitcoin payout script, thus it can be something like a standard "pay to pubkey" script to a user controlled address. Also note that the zero pushed onto the stack by the ClaimTrie op codes, and the ClaimTrie vectors, are all dropped by the preceding OP_2DROP and OP_DROP. This means that ClaimTrie transactions exist as prefixes to Bitcoin payout scripts and can be spent in the same way as is expected in Bitcoin. [script pubkey] can be any valid Bitcoin payout script. Thus it can be something like a standard "pay to pubkey" script to a user controlled address. Also note that the zero pushed onto the stack by the ClaimTrie op codes, and the ClaimTrie vectors, are all dropped by the preceding OP_2DROP and OP_DROP. This means that ClaimTrie transactions exist as prefixes to Bitcoin payout scripts and can be spent in the same way as is expected in Bitcoin.
For example, a claim transaction using a pay to pubkey script will have the below full payout script. Let's also say that this claim is for the name "Fruit" to be set to value "Apple". For example, a claim transaction using a pay to pubkey script will have the below full payout script. Let's also say that this claim is for the name "Fruit" to be set to value "Apple".
@ -61,7 +61,7 @@ Like any standard Bitcoin transaction output script, it will be associated with
OP_SUPPORT_CLAIM <Fruit> <X> OP_2DROP OP_DROP OP_DUP OP_HASH160 <LBRY_Address_B> OP_EQUALVERIFY OP_CHECKSIG OP_SUPPORT_CLAIM <Fruit> <X> OP_2DROP OP_DROP OP_DUP OP_HASH160 <LBRY_Address_B> OP_EQUALVERIFY OP_CHECKSIG
``` ```
And now let's say we want to update the original claim to change the value to "Banana". An update transaction has a special requirement that it must spend the existing claim that it wishes to update in its redeem script. Otherwise, it will be considered invalid and will not make it into the ClaimTrie. Thus it will have the below redeem script to spend the claim created to set name "Fruit" to "Apple". Note that this is identical to the standard way of redeeming a "pay to pubkey" script in Bitcoin. And now let's say we want to update the original claim to change the value to "Banana". An update transaction has a special requirement in that it must spend the existing claim that it wishes to update in its redeem script. Otherwise, it will be considered invalid and will not make it into the ClaimTrie. Thus it will have the below redeem script to spend the claim created to set name "Fruit" to "Apple". Note that this is identical to the standard way of redeeming a "pay to pubkey" script in Bitcoin.
```python ```python
<Signature> <Public_key_for_LBRY_Address_A> <Signature> <Public_key_for_LBRY_Address_A>

View file

@ -1,7 +1,7 @@
# Regtest Setup # Regtest Setup
## Why use a regtest server ## Why use a regtest server
A regtest server provides for a way to instantly generate blocks so that transactions can be instantaneous, so ultimately no waiting for confirmations from the blockchain. Also, no problem if you accidentally corrupt your wallet, since no real funds are lost! Delete the files and setup a new one. A regtest server provides for a way to instantly generate blocks so that transactions can be instantaneous, which ultimately means no waiting for confirmations from the blockchain. Also, its not a problem if you accidentally corrupt your wallet, since no real funds are lost! Delete the files and setup a new one.
## Setup ## Setup
@ -20,7 +20,7 @@ To enter the environment, run:
### lbrycrd ### lbrycrd
You need to download a build of `lbrycrd` from [here](https://github.com/lbryio/lbrycrd/releases/), no installation required. To configure `lbrycrd` you need to create a file at `~/.lbrycrd/lbrycrd.conf`, You need to download a build of `lbrycrd` from [here](https://github.com/lbryio/lbrycrd/releases/), no installation required. To configure `lbrycrd` you need to create a file at `~/.lbrycrd/lbrycrd.conf`,
containing the following. containing the following:
```ini ```ini
rpcuser=test rpcuser=test
rpcpassword=test rpcpassword=test
@ -35,7 +35,7 @@ discover=0
### lbryum-server ### lbryum-server
To install lbryum-server, you first need to install the package `leveldb`. After that, download the source from [here](https://github.com/lbryio/lbryum-server/releases), and run the following _not_ inside the environment. To install lbryum-server, you first need to install the package `leveldb`. After that, download the source from [here](https://github.com/lbryio/lbryum-server/releases), and run the following _not_ inside the environment:
```bash ```bash
cd lbryum-server cd lbryum-server
sudo pip2 install -r requirements.txt sudo pip2 install -r requirements.txt
@ -47,12 +47,12 @@ If you're not running debian/\*buntu or a derivative of those, you need to edit
sudo ./configure sudo ./configure
sudo python2 setup.py install sudo python2 setup.py install
``` ```
The `sudo ./configure` command creates a new user in the system by the name "lbryum", which is the user through which we'll be the running the server. lbryum-server also need W/R access to `/var/lbryum-server` The `sudo ./configure` command creates a new user in the system by the name "lbryum", which is the user through which we'll be running the server. lbryum-server also needs W/R access to `/var/lbryum-server`.
To do that run: To do that run:
```bash ```bash
sudo chown -R lbryum /var/lbryum-server sudo chown -R lbryum /var/lbryum-server
``` ```
When installed, append/use the following config options to the `/etc/lbryum.conf` file. When installed, append/use the following config options to the `/etc/lbryum.conf` file:
```ini ```ini
[lbrycrdd] [lbrycrdd]
lbrycrdd_host = localhost lbrycrdd_host = localhost
@ -67,7 +67,7 @@ type=lbrycrd_regtest
### lbryum ### lbryum
To install lbryum, first, download the source from [here](https://github.com/lbryio/lbryum/releases). To install it, run the following inside the virtual environment. To install lbryum, first download the source from [here](https://github.com/lbryio/lbryum/releases). To install it, run the following inside the virtual environment:
```bash ```bash
cd lbryum cd lbryum
pip2 install -r requirements.txt pip2 install -r requirements.txt
@ -94,7 +94,7 @@ Alternatively, you can create a file `touch ~/.lbryum/config` and paste the foll
### lbry ### lbry
Download source from [here](https://github.com/lbryio/lbry/releases), and run the following inside the environment. Download source from [here](https://github.com/lbryio/lbry/releases), and run the following inside the environment:
```bash ```bash
cd lbry cd lbry
pip2 install -r requirements.txt pip2 install -r requirements.txt
@ -103,7 +103,7 @@ mkdir ~/.lbrynet
touch ~/.lbrynet/daemon_settings.yml touch ~/.lbrynet/daemon_settings.yml
``` ```
Append the following in the newly created `~/.lbrynet/daemon_settings.yml` file Append the following in the newly created `~/.lbrynet/daemon_settings.yml` file:
```yml ```yml
blockchain_name: lbrycrd_regtest blockchain_name: lbrycrd_regtest
lbryum_servers: lbryum_servers:
@ -124,21 +124,21 @@ This is to ensure that `lbrynet-daemon` uses the correct wallet.
### Wallet backup ### Wallet backup
To start off, if you've already used LBRY on your machine, you need to backup the wallet by copying the folders `~/.lbrynet` and `~/.lbryum`, then delete them to start from fresh. Run To start off, if you've already used LBRY on your machine, you need to backup the wallet by copying the folders `~/.lbrynet` and `~/.lbryum` and then deleting them to start from fresh. Run
`mkdir ~/.lbryum` `mkdir ~/.lbryum`
Now it should be all set-up, just execute the commands in the following order, and the regtest server should be good to go. Now it should be all set-up. Just execute the commands in the following order, and the regtest server should be good to go.
### 1) lbrycrd ### 1) lbrycrd
To run the `lbrycrd` daemon, run the following in the `lbrycrd` folder. To run the `lbrycrd` daemon, run the following in the `lbrycrd` folder:
`./lbrycrdd` `./lbrycrdd`
To generate blocks, run `./lbrycrd-cli generate <num_of_blocks>` To generate blocks, run `./lbrycrd-cli generate <num_of_blocks>`
You'll need to generate some blocks to get the network going. Start off by generating at least 100. You'll need to generate some blocks to get the network going. Start off by generating at least 100.
`./lbrycrd-cli generate 173` `./lbrycrd-cli generate 173`
If you'd prefer a more verbose output from lbrycrdd, run lbrycrd using If you'd prefer a more verbose output from lbrycrdd, run lbrycrd using:
`./lbrycrdd -printtoconsole` `./lbrycrdd -printtoconsole`
### 2) lbryum-server ### 2) lbryum-server
@ -170,7 +170,7 @@ You can now run `lbrynet-daemon`, and it should connect to the `lbryum`. Now you
To stop the network, run `lbrynet-cli daemon_stop`, `lbryum daemon stop`, and kill the `lbryum-server` process and stop lbrycrd by `lbrycrdd-cli stop`. If you want to use your wallet and the official servers again, backup the new regtest wallet, and replace it with your own. To stop the network, run `lbrynet-cli daemon_stop`, `lbryum daemon stop`, and kill the `lbryum-server` process and stop lbrycrd by `lbrycrdd-cli stop`. If you want to use your wallet and the official servers again, backup the new regtest wallet, and replace it with your own.
## Note 1 ## Note 1
You need to generate a few blocks everytime you make a new transaction in the form of send, receive, claim, update, publish, support, tip etc. for it to show up in the daemon and lbryum etc. You need to generate a few blocks every time you make a new transaction in the form of send, receive, claim, update, publish, support, tip, etc. for it to show up in the daemon and lbryum, etc.
## Note 2 ## Note 2
If something goes wrong and you get a "Block not found" error, remember to delete `/var/lbryum-server` before trying again. If something goes wrong and you get a "Block not found" error, remember to delete `/var/lbryum-server` before trying again.

View file

@ -4,7 +4,7 @@ This document outlines the standards for all public, open-source repositories us
The goal of this document is to ensure that LBRY documentation is welcoming, informative, comprehensive, and well-written. The goal of this document is to ensure that LBRY documentation is welcoming, informative, comprehensive, and well-written.
Each codebase should include the following documents, committed as markdown files at the top level of the repository. Each codebase should include the following documents committed as markdown files at the top level of the repository:
## README.md ## README.md
@ -14,46 +14,46 @@ This document exists to introduce a project to a new visitor. It may also serve
* The title (name) of the project at the top as an h1 * The title (name) of the project at the top as an h1
* Any build status badges as appropriate immediately below the title * Any build status badges as appropriate immediately below the title
* A one or two sentence description of the project, below the title or status badges. The description should mention the language, and any key frameworks (e.g. "lbry" should mention it uses both Python and Twisted) * A one or two sentence description of the project, below the title or status badges. The description should mention the language and any key frameworks (e.g. "lbry" should mention it uses both Python and Twisted)
* A screenshot, image or gif of the project below the description (host it on spee.ch!) * A screenshot, image, or gif of the project below the description (host it on spee.ch!)
* A table of contents if the document is long (can be one line of links to sections). * A table of contents if the document is long (can be one line of links to sections)
### Installation ### Installation
* A single header labeled "Install" should be the next header as an h2 * A single header labeled "Install" should be the next header as an h2
* Installation means installation for users. It should cover how to have the software on their computer in a user-friendly fashion, not how to run from source. E.g. it should link binaries if they exist. * Installation means installation for users. It should cover how to have the software on their computer in a user-friendly fashion, not how to run from source (e.g. it should link binaries if they exist)
* If the project is a library only intended to be used in other projects, it should still exist but can be extremely succinct (e.g. pip install lbryschema) * If the project is a library only intended to be used in other projects, it should still exist but can be extremely succinct (e.g. pip install lbryschema)
* If the project is not designed to be installed directly or used as a library in other projects, it should state as such, e.g. "This project is not designed to be installed directly. Continue reading below to learn how to use this project." * If the project is not designed to be installed directly or used as a library in other projects, it should state as such (e.g. "This project is not designed to be installed directly. Continue reading below to learn how to use this project.”)
### Usage ### Usage
* A single header labeled "Usage" should be the next header as an h2 * A single header labeled "Usage" should be the next header as an h2
* The Usage section should explain how to run or launch the project if applicable. * The Usage section should explain how to run or launch the project if applicable
* The Usage section should include examples of some basic commands, if applicable. * The Usage section should include examples of some basic commands if applicable
* In the case of a library, it should provide a few basic examples of how the library would be used. * In the case of a library, it should provide a few basic examples of how the library would be used
* Usage should always be included, even if very simple. For example, "Double click the installed application to browse with the LBRY network." * Usage should always be included, even if its very simple (e.g. "Double click the installed application to browse with the LBRY network.”)
### Running from Source ### Running from Source
* This section covers how to run the project from source and/or with the intent of working directly on it. * This section covers how to run the project from source and/or with the intent of working directly on it
* It can have a Prerequisites section for what is required to run from source. * It can have a Prerequisites section for what is required to run from source
* It is okay to assume some basic assumptions about what people know about the language or tools the project uses. However, its good when possible to assume very little, and provide links to the user for how to get the prerequisites. * It is okay to assume some basic assumptions about what people know about the language or tools the project uses. However, its good whenever possible to assume very little and provide links to the user for how to get the prerequisites
* For prerequisites that it is not safe to assume knowledge of, the project should list the explicit command to add the prerequisite, or link to instructions on how to add the prerequisite. * For prerequisites for which it is not safe to assume knowledge of, the project should list the explicit command to add the prerequisite, or link to instructions on how to add the prerequisite
* If there are operating system specific instructions, these should be broken out into separate headings for each operating system. * If there are operating system specific instructions, these should be broken out into separate headings for each operating system
* It is okay to assume Linux and Unix are "first class citizens". While we want to support all OSes, Windows instructions and considerations can be secondary. * It is okay to assume Linux and Unix are "first class citizens". While we want to support all OSs, Windows instructions and considerations can be secondary
* Include a step that explains how to verify you are running from source directly. * Include a step that explains how to verify you are running from source directly
* It is okay to point to a INSTALL.md file if the installation steps are relatively lenghty, which should reside in the root folder. * It is okay to point to a INSTALL.md file (which should reside in the root folder) if the installation steps are relatively lengthy
### Contributing ### Contributing
* A single header labeled "Contributing" should appear as an h2 * A single header labeled "Contributing" should appear as an h2
* This should be the same copy: "Contributions to this project are welcome, encouraged, and compensated. For more details, see [CONTRIBUTING.md](*CONTRIBUTING.md*)" * This should be the same message: "Contributions to this project are welcome, encouraged, and compensated. For more details, see [CONTRIBUTING.md](*CONTRIBUTING.md*)
* If CONTRIBUTING.md does not exist in the project, it should link to [https://lbry.io/faq/contributing](https://lbry.io/faq/contributing) (soon to be lbry.tech/contributing) * If CONTRIBUTING.md does not exist in the project, it should link to [https://lbry.io/faq/contributing](https://lbry.io/faq/contributing) (soon to be lbry.tech/contributing)
### (Additional Headings) ### (Additional Headings)
* Additional headings as appropriate will typically exist after the above and below the subsequent areas. * Additional headings as appropriate will typically exist after the above and below the subsequent areas
* These areas should cover anything else appropriate or helpful to introduce a project to a new user. * These areas should cover anything else appropriate or helpful to introduce a project to a new user
### License ### License
@ -67,12 +67,12 @@ This document exists to introduce a project to a new visitor. It may also serve
### Contact ### Contact
* A single header labeled "Contact" should appear as an h2 * A single header labeled "Contact" should appear as an h2
* This should be the same or similar copy: "The primary contact for this project is [@XXX](https://github.com/@XXX) ([xxx@lbry.io](mailto:xxx@lbry.io))" * This should be the same or a similar message to the following: "The primary contact for this project is [@XXX](https://github.com/@XXX) ([xxx@lbry.io](mailto:xxx@lbry.io))"
### Additional Info and Links ### Additional Info and Links
* (optional) * (optional)
* References to any additional documentation, such as generated API docs. * References to any additional documentation, such as generated API docs
## CONTRIBUTING.md ## CONTRIBUTING.md
@ -80,11 +80,11 @@ This document explains anything a visitor would need to know to contribute to th
This document should cover the following: This document should cover the following:
* First, it should contain a single sentence: "This project follows the global contributing standards for all LBRY projects, to read those go < here >". * First, it should contain a single sentence: "This project follows the global contributing standards for all LBRY projects, to read those go < here >.
* A "Code Overview" section explaining some basic design choices and how to begin stepping through the code. An example would be explaining that Daemon.py is the primary entry point for the daemon code, and one can begin to trace through the code by looking for jsonrpc_xxx, where xxx is one of the api calls listed [here](https://lbry.io/api). * A "Code Overview" section explaining some basic design choices and how to begin stepping through the code. An example would be explaining that Daemon.py is the primary entry point for the daemon code, and one can begin to trace through the code by looking for jsonrpc_xxx, where xxx is one of the api calls listed [here](https://lbry.io/api)
* A "Testing" section, explaining how to run tests, and that tests are necessary. * A "Testing" section explaining how to run tests and stating that tests are necessary
* Information on how to submit pull requests, and what to expect afterwards. (e.g. a link to our [branching doc](https://github.com/lbryio/lbry/wiki/Branching-and-Merging), commands to run before submitting PR, tests must pass, changelog entry, etc). If you find this gets repetitive, it may be best to link to a global doc. * Information on how to submit pull requests, and what to expect afterwards (e.g. a link to our [branching doc](https://github.com/lbryio/lbry/wiki/Branching-and-Merging), commands to run before submitting PR, tests must pass, changelog entry, etc). If you find this gets repetitive, it may be best to link to a global doc
* Anything else a new visitor to a repository should know about contributing to that specific repository (linting, generating documentation, etc). * Anything else a new visitor to a repository should know about contributing to that specific repository (linting, generating documentation, etc)
## LICENSE ## LICENSE

View file

@ -9,7 +9,7 @@ The schema defines the structure of the data that is stored in claims in the LBR
## [Claim](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/claim.proto) ## [Claim](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/claim.proto)
A `Claim` is the toplevel schema for everything that is published to the blockchain. A `Claim` is the top level schema for everything that is published to the blockchain.
```protobuf ```protobuf
message Claim { message Claim {
@ -168,7 +168,7 @@ message Certificate {
### [Signature](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/signature.proto) ### [Signature](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/signature.proto)
Publishing a claim to a channels simply means that the claim is signed using the private key for a channel. This is done by including a Signature field in a Claim: Publishing a claim to a channel simply means that the claim is signed using the private key for a channel. This is done by including a Signature field in a Claim:
```protobuf ```protobuf
message Signature { message Signature {

View file

@ -44,7 +44,7 @@ Names may contain English letters (upper and lower case), numbers, and hyphens.
### Content Name ### Content Name
`content_name` is the name of piece of content. `content_name` is the name of a piece of content.
### Channel Name ### Channel Name
@ -60,13 +60,13 @@ Only one modifier is allowed at a time.
`claim_id` is a hex string identifying a claim. `claim_id` is a hex string identifying a claim.
A claim id is prefixed with the CLAIM_ID_CHAR. A claim id is prefixed with the CLAIM_ID_CHAR.
Partial claim ids are allowed (same is git hashes), and Partial claim ids are allowed (same is git hashes), and
will resolve to the oldest claim who's id starts with the given characters. will resolve to the oldest claim whose id starts with the given characters.
### Claim Sequence ### Claim Sequence
`claim_sequence` is a positive integer (>= 1) that resolves to the Nth claim for a given name. `claim_sequence` is a positive integer (>= 1) that resolves to the Nth claim for a given name.
A claim sequence is prefixed with the CLAIM_SEQUENCE_CHAR. A claim sequence is prefixed with the CLAIM_SEQUENCE_CHAR.
All valid claims are considered, in the order that they appear in the blockchain. All valid claims are considered in the order that they appear in the blockchain.
Nonwinning claims are included. Nonwinning claims are included.
For example, `lbry://@chan:1` resolves to the oldest valid claim for `@chan`, even if that claim is no longer the winning claim for `@chan`. For example, `lbry://@chan:1` resolves to the oldest valid claim for `@chan`, even if that claim is no longer the winning claim for `@chan`.
@ -93,7 +93,7 @@ A path is prefixed with PATH_CHAR.
Only paths one level deep are currently supported. Only paths one level deep are currently supported.
Only channel claims may have a path. Only channel claims may have a path.
For example, `lbry://@chan/snaps_from_last_night` resolves to the claim for `snaps_from_last_night` that is signed by `@chan` For example, `lbry://@chan/snaps_from_last_night` resolves to the claim for `snaps_from_last_night` that is signed by `@chan`.
## Query Params ## Query Params