From 1da5703f10bc57e3bb3cb224041f3d00618d29b0 Mon Sep 17 00:00:00 2001 From: Jeremy Kauffman Date: Tue, 19 Feb 2019 20:11:04 -0500 Subject: [PATCH] builders guide --- app/components/resources-link-grid.js | 15 ++- documents/build.md | 129 ++++++++++++++++++-------- 2 files changed, 98 insertions(+), 46 deletions(-) diff --git a/app/components/resources-link-grid.js b/app/components/resources-link-grid.js index 5949b92..526a894 100644 --- a/app/components/resources-link-grid.js +++ b/app/components/resources-link-grid.js @@ -15,11 +15,6 @@ export default () => linkGrid([{ destination: "/spec", label: "Study the Spec", title: "LBRY Specification" -}, { - description: "Can you code, design, write or test? Join us!", - destination: "/contribute", - label: "Read the Guide", - title: "Contributor's Guide" }, { description: "Method signatures and examples for lbry-sdk, the most common way to build on LBRY.", destination: "/api/sdk", @@ -30,4 +25,14 @@ export default () => linkGrid([{ destination: "/api/blockchain", label: "Blockchain APIs", title: "Blockchain APIs" +}, { + description: "Can you code, design, write or test? Join us!", + destination: "/contribute", + label: "Learn To Contribute", + title: "Contributor's Guide" +}, { + description: "Want to build your own dApp or auxiliary service? Start here! ", + destination: "/build", + label: "Build An App", + title: "Builder's Guide" }]); diff --git a/documents/build.md b/documents/build.md index e369cd2..4900156 100644 --- a/documents/build.md +++ b/documents/build.md @@ -31,7 +31,7 @@ This section will guide you through creating a basic [Electron](https://electron Electron is nice because it allows you to easily create web apps that don't rely on any centralized web servers, but you can absolutely use any tooling or language you would like. -### Let's Build It +### The Steps _These steps require [npm](https://www.npmjs.com/). Learn how to install it [here](https://www.npmjs.com/get-npm)._ @@ -48,9 +48,8 @@ _These steps require [npm](https://www.npmjs.com/). Learn how to install it [her #### 2. Verify the app works -Type a word into the text input and click the button to [resove](https://lbry.tech/api/sdk#resolve) it. This performs a [[claim]] lookup, which retrieves metadata the title, thumbnail, and file type from the LBRY blockchain. +Type a word into the text input and click the button to [resolve](https://lbry.tech/api/sdk#resolve) it. This performs a [[claim]] lookup, which retrieves metadata the title, thumbnail, and file type from the LBRY blockchain. - Try resolving `lbry://bitconnect`. Try resolving `lbry://doitlive`. #### 3. Modify the code @@ -74,7 +73,7 @@ Type a word into the text input and click the button to [resove](https://lbry.te }); ``` - This is the code that actually downloads a file. There are more robust ways to handle the download progress, but this will work fine for images. After you added that code back, try `get`ing `lbry://bitconnect`. + This is the code that actually downloads a file. There are more robust ways to handle the download progress, but this will work fine for images. After you added that code back, try `get`ing `lbry://doitlive`. ### You Did It! @@ -86,9 +85,9 @@ Unfortunately, most users will want more functionality in an app than typing int You can build many types of apps. Your app doesn't have to use Electron, nor does it have to be targeted at consumers, use a UI, or even fetch digital content at all! In this section, we'll look into the different types of apps you could build, and the different components needed to build anything you want. -Most applications will use [lbry-sdk](https://github.com/lbryio/lbry) as a way of accessing and communicating with the LBRY network. A look at the [APIs](/api/sdk) provided by the SDK will help you understand what it can and can't do. +Most applications will use the [LBRY SDK](#sdk) as a way of accessing and communicating with the LBRY network. A look at the [APIs](/api/sdk) provided by the SDK will help you understand what it can and can't do. -Some applications do not need to access content available on the network (e.g. a wallet-only app, or a blockchain visualizer). These applications might use [lbrycrd](https://github.com/lbryio/lbrycrd), the full-node blockchain daemon, or [chainquery](https://github.com/lbryio/chainquery), which parses blockchain data into SQL. +Some applications do not need to access content available on the network (e.g. a wallet-only app, or a blockchain visualizer). These applications might use [lbrycrd](#lbrycrd), the full-node blockchain daemon, or [chainquery](#chainquery), which parses blockchain data into SQL. Let's look at some specific types of applications and the basic design for each. @@ -98,41 +97,51 @@ Let's look at some specific types of applications and the basic design for each. By full web application, we mean a centrally-hosted web application that uses most or all of the suite of capabilities the LBRY protocol provides. -To do this, we need [lbry-sdk](https://github.com/lbryio/lbry). You can download the latest version from the [releases page](https://github.com/lbryio/lbry/releases). Once that is downloaded, there are really only two steps to get it integrated into your app. +For an example of a full web application that uses LBRY, check out the [spee.ch codebase](https://github.com/lbryio/spee.ch). -1. Run `lbrynet start` in the directory you downloaded the SDK. This starts the API server and connects to the LBRY network. +To create a full web application follow the typical steps you follow to create a basic application. Then, [follow the steps to interact with the LBRY SDK](#sdk). -1. Setup an API wrapper to talk to the SDK. +Full web applications can may also benefit from using [chainquery](#chainquery), which provides an SQL interface to blockchain data. - There are a number of very simple [api wrappers](https://lbry.tech/resources/api-wrappers) available in several different languages. Most of these have been created by community members! These allow you to easily send commands to the SDK in the language of your choice. If a wrapper for the language you would like to use doesn't exist, contact [someone?]. (All of the bounties we have on https://lbry.io/bounty/lbry-binding are claimed, should this be linked at all?) +If your web application will utilize user accounts, a common design pattern is to simply associate user IDs with common LBRY types like files, claims, and channels. -That's all it takes! Now you can read and write data to the LBRY network from your app. :) +If your web application will utilize per-user funds, we recommend using the account functionality provided by the SDK to give each user an account (wallet). This will allow you to keep funds cleanly separated with a single SDK instance. + +That's all it takes! #### Blockchain Applications -Sometimes you don't need the [SDK](https://github.com/lbryio/lbry). For applications that only need blockchain data, such as a block explorer, check out [lbrycrd](#lbrycrd) and [Chainquery](#Chainquery). +By blockchain applications, we mean applications that don't utilize the data network and digital content distribution capabilities of the LBRY protocol. + +For an example of a blockchain application that uses LBRY, check out the [block-explorer codebase](https://github.com/lbryio/block-explorer). + +Whether your blockchain application is a web application, desktop application, or a mobile application, the steps will be similar to those of full applications. + +In each case, you'll follow the typical steps to build a basic application. Then, if your app is reading data from the blockchain and presenting it to users, you'll want to [follow the steps for using chainquery](#chainquery). + +If your application needs to send funds, you'll want to [follow the steps for using lbrycrd](#lbrycrd). Note that it is also possible to move funds by using the [LBRY SDK](#sdk), but the SDK does not provide a full blockchain node, only an [[SPV]] wallet. #### Other Web Applications It is also possible to create a browser extension similar to Joule and Metamask. Generally there are two ways to do this: -1. Have the user run [lbry-sdk](https://github.com/lbryio/lbry) on their computer and send commands from the browser that interact with the user's personal wallet. +1. Have the user run a local copy of the [SDK](#sdk) on their computer and send commands from the browser that interact with the user's personal wallet. -2. Run [lbry-sdk](https://github.com/lbryio/lbry) on a centrally hosted server and manage keys or funds for each user. +2. Run the [SDK](#sdk) on a centrally hosted server and manage keys or funds for each user. If you're doing this, you'll want to read [Full Web Applications](#full-web-applications). -Going through a centralized server can be safer (with added authentication), but it also comes with more responsibility to keep your user's funds secure. +Going through a centralized server makes it easier on users, but comes with more responsibility to keep your user's funds secure. It also requires creating business logic on your server to associate user accounts with common types like claims and files. #### Desktop Applications -Desktop app's can offer greater anonyminity, better performance, and features that aren't possible with a regular web app. +Desktop applications can offer greater anonymity, better performance, and features that aren't possible with a regular web app. -You will still need to do steps 1 and 2 in the [Full Web Applications] section to get the SDK running. Once that is done you can begin building an app that allows users to be fully in control of their data. They won't have to rely on third party services keeping anything secure, and they can choose to help strengthen LBRY network through seeding. +Regardless of the type of desktop app, you'll want to follow the steps for [using the SDK](#sdk). Once that is done you can begin building an app that allows users to be fully in control of their data. They won't have to rely on third party services keeping anything secure, and they can choose to help strengthen LBRY network through seeding. ##### Electron Apps -The [official LBRY desktop app](https://github.com/lbryio/lbry-desktop) is built with electron. It is very easy to build with, and allows web developers to easily start creating "native" desktop applications. You can use a plain html document with a `