mirror of https://github.com/lukechilds/docs.git
Browse Source
- Adding in images for walkthrough - Work in progress commits: copy down from review - Adding in the part 4 after usability testing Signed-off-by: Mary Anthony <mary@blockstack.com>feat/clarity-updates
Moxiegirl
6 years ago
committed by
GitHub
GitHub
50 changed files with 2208 additions and 92 deletions
|
After Width: | Height: | Size: 39 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 359 KiB |
|
After Width: | Height: | Size: 168 KiB |
|
After Width: | Height: | Size: 140 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
After Width: | Height: | Size: 23 KiB |
|
After Width: | Height: | Size: 87 KiB |
|
After Width: | Height: | Size: 3.2 MiB |
|
After Width: | Height: | Size: 138 KiB |
|
After Width: | Height: | Size: 230 KiB |
|
After Width: | Height: | Size: 37 KiB |
|
After Width: | Height: | Size: 124 KiB |
|
After Width: | Height: | Size: 76 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 250 KiB |
|
After Width: | Height: | Size: 109 KiB |
|
After Width: | Height: | Size: 70 KiB |
|
After Width: | Height: | Size: 774 KiB |
|
After Width: | Height: | Size: 65 KiB |
|
After Width: | Height: | Size: 611 KiB |
|
After Width: | Height: | Size: 109 KiB |
|
After Width: | Height: | Size: 192 KiB |
|
After Width: | Height: | Size: 7.1 MiB |
|
After Width: | Height: | Size: 472 KiB |
|
After Width: | Height: | Size: 289 KiB |
|
After Width: | Height: | Size: 352 KiB |
|
After Width: | Height: | Size: 1.2 MiB |
|
After Width: | Height: | Size: 50 KiB |
|
After Width: | Height: | Size: 335 KiB |
|
After Width: | Height: | Size: 47 KiB |
|
After Width: | Height: | Size: 69 KiB |
|
After Width: | Height: | Size: 145 KiB |
|
After Width: | Height: | Size: 14 KiB |
@ -0,0 +1,143 @@ |
|||
--- |
|||
layout: learn |
|||
permalink: /:collection/:path.html |
|||
--- |
|||
# 1 - Why Blockchain and Blockstack? |
|||
{:.no_toc} |
|||
|
|||
**Zero to DApp, 1 of 4** |
|||
|
|||
Welcome to the Blockstack Zero to DApp tutorial. The Blockstack Ecosystem has a |
|||
mission to bring a new internet where users control the access to, and use of, |
|||
their own identity and data. This tutorial is written for developers who want |
|||
to learn about how to use the Blockstack Ecosystem to develop and fund |
|||
decentralized applications (DApps). |
|||
|
|||
The tutorial has four pages, this is first of four pages. The top of each page |
|||
lists the contents. This page contains the following: |
|||
|
|||
* TOC |
|||
{:toc} |
|||
|
|||
Of course, you can skip pages if you want. Each page contains a section |
|||
describing who can/should skip and containing a link to the next tutorial page. |
|||
You can also use the menu on the left. |
|||
|
|||
<div class="uk-card uk-card-default uk-card-body"> |
|||
<h5>Can you skip this page?</h5> |
|||
<p>In this section, you learn what is a DApp, why you might want to create one, and |
|||
why you would choose the Blockstack ecosystem to do it. If you are already |
|||
familiar with how decentralized applications are different from standard |
|||
applications and you understand Blockstack’s unique value proposition, skip |
|||
this section and <a href="zero_to_dapp_2.html">move onto 2 of 4 immediately</a>.</p> |
|||
</div> |
|||
|
|||
## Blockchain applications, the new kid |
|||
|
|||
A decentralized application (DApp) uses blockchain technology for the |
|||
authentication and data storage components of an application’s platform. |
|||
Blockchain applications are decentralized applications, meaning they move data |
|||
control and identity management from central authorities and organizations to |
|||
individual users. |
|||
|
|||
Anyone who has had their identity stolen or lost money because of a data breach, |
|||
understands that centralized applications come with personal risk. Anyone who |
|||
has lived in or visited a foreign country and lost access to a site, to a |
|||
service, or to information because of government censorship also understands how |
|||
centralization impacts how people live. |
|||
|
|||
Users and businesses see DApps as valuable because they solve the the |
|||
centralization problems of traditional applications. The following table |
|||
describes the features of traditional applications and the features of |
|||
blockchain applications: |
|||
|
|||
<table class="uk-table uk-table-small uk-table-divider"> |
|||
<tr> |
|||
<th>Traditional application</th> |
|||
<th>Decentralized application</th> |
|||
</tr> |
|||
<tr> |
|||
<td>Users must create many username and password combinations for each service or application. Each combination must be managed and maintained. Also, each creation requires the user to provide,important or unique information into the care of a third-party.</td> |
|||
<td>Users create and own one or more identities. They use their identities with all applications and services. For example, a user could use the same identity for buying books online as they use for social media.</td> |
|||
</tr> |
|||
<tr> |
|||
<td>Multiple third-party applications and services store personal data from individual users in backend servers.,These backend servers are under the control of the application or service. Users leaving the application leave their data behind.</td> |
|||
<td>Personal information and data is encrypted and remains under the control of the user.,Users leaving an application leave no data behind because none was stored with the application.</td> |
|||
</tr> |
|||
<tr> |
|||
<td>Multiple accounts across many servers makes personal data subject to attack, misuse, and uncontrolled collection.</td> |
|||
<td>Users can audit access to their data and know who accessed their data and which date were accessed.</td> |
|||
</tr> |
|||
<tr> |
|||
<td>Central authorities and middlemen control network access enabling them to censor applications and/or users that use them.</td> |
|||
<td>Companies are developing blockchains that run over peer-to-peer networks.,These future networks can make shutting down or entirely blocking a decentralized application is close to impossible.</td> |
|||
</tr> |
|||
</table> |
|||
|
|||
The blockchain technology you build an DApp with determines the features available to your application. |
|||
|
|||
## How Blockstack is seeding DApp development |
|||
|
|||
Blockchain applications are a new paradigm for both application developers and |
|||
application users. New paradigms in any market, think solar power or electric |
|||
vehicles, need private and private coalitions to grow. The centralized hosting |
|||
and services known of as cloud computing were once new paradigms. It was the |
|||
investment of billions in funds and incentives from governments and private |
|||
companies that grew the cloud computing market. |
|||
|
|||
Today, these same elements are helping to the drive to the blockchain industry. |
|||
Public and private spending on developing blockchain technology is expected to |
|||
grow at a rapid rate. This investment is happening throughout the world as |
|||
reflected in a recent IDC report: |
|||
|
|||
> <img class="uk-align-center" src="images/history-cloud.jpg" alt=""> |
|||
>The IDC expects blockchain spending to grow at a robust pace throughout the |
|||
2017-2022 forecast period with a five-year compound annual growth rate (CAGR) of |
|||
73.2%. Worldwide blockchain spending is expected to be $1.5 billion in 2018, |
|||
double the amount spent in 2017. |
|||
~ <a href="https://www.idc.com/getdoc.jsp?containerId=prUS44150518" target="\_blank">IDC Blockchain Spending Guide</a> |
|||
|
|||
{% include signature_fund.md %} |
|||
|
|||
As you work through this Zero to DApp tutorial, you’ll learn more about the funding available |
|||
through the fund and how you can access it. |
|||
|
|||
## Blockchain, no pain |
|||
|
|||
Blockstack’s mission is to bring about a new internet where users control the |
|||
access to their data and how it is used. With this mission in mind, Blockstack |
|||
Public Benefit Corp. (PBC) started development of the Blockstack platform in 2017. |
|||
|
|||
The platform’s development philosophy followed two simple principles. First, |
|||
create backend services that allow decentralized applications to be both |
|||
performant and scalable. Second, provide simple, familiar development |
|||
interfaces to blockchain technology. The result of this philosophy is a |
|||
technology platform that allows you to: |
|||
|
|||
* **Build your application in any Javascript framework.** You can use the blockchain without learning a new programming language or extending your application stack. |
|||
* **Use well-defined REST endpoints that simplify and encapsulate the blockchain backend.** The Blockstack Javascript API reduces blockchain operations to familiar GET and PUT operations. |
|||
* **Access the Blockstack’s Naming System (BNS).** The system has over 90K users that can immediately start using your application. |
|||
* **Scale quickly to large, performant production systems.** Blockstack’s GAIA storage system gives fast, scalable performance on a level comparable to Amazon S3, Google Drive, or Azure. |
|||
|
|||
Using Blockstack’s technology you can start building immediately on the |
|||
blockchain with the knowledge you have today. You won’t need to spend time or |
|||
effort developing additional knowledge of specialized languages or technologies. |
|||
|
|||
In part 3 of this tutorial, you’ll build a sample DApp that leverages all the |
|||
key features of Blockstack’s platform. |
|||
|
|||
## Where to go next |
|||
{:.no_toc} |
|||
|
|||
This section introduced you to the benefits of a decentralized application |
|||
(DApp). You also learned that, similar to other new paradigms, you learned both |
|||
the public and private companies are committing serious resources to developing |
|||
blockchain tech. Finally, you learned Blockstack is designed so that you |
|||
can quickly build a DApp and enter this emerging market. |
|||
|
|||
In the next section, you learn more about the developing DApps and how they are |
|||
different from traditional applications. You’ll also learn about the resources |
|||
Blockstack provides for DApp developers that help you clarify where to put your |
|||
efforts and how to fund them. |
|||
|
|||
Continue to [2 of 4, Zero to DApp](zero_to_dapp_2.html). |
|||
@ -0,0 +1,168 @@ |
|||
--- |
|||
layout: learn |
|||
permalink: /:collection/:path.html |
|||
--- |
|||
# 2 - Discover how DApps are different |
|||
{:.no_toc} |
|||
|
|||
**Zero to DApp, 2 of 4** |
|||
|
|||
This page explains how DApp user interactions differ from interactions on web |
|||
applications. If you don't have one, you'll also create a Blockstack ID. |
|||
Finally, you'll also learn what industry experts say are fertile grounds for |
|||
DApp development. This page has the following topics: |
|||
|
|||
* TOC |
|||
{:toc} |
|||
|
|||
<div class="uk-card uk-card-default uk-card-body"> |
|||
<h5>Can you skip this page?</h5> |
|||
<p>If you are already have a good understanding of how DApps change user |
|||
interactions, have a Blockstack ID, and have a good idea of the DApp you want to develop, skip |
|||
this page and <a href="zero_to_dapp_3.html">move onto 3 of 4 immediately</a>. |
|||
</p> |
|||
</div> |
|||
|
|||
## Get the user perspective on DApps |
|||
|
|||
 |
|||
|
|||
This old proverb is all about how our environment shapes our thinking. As a |
|||
user, you have lived in the centralized application environment for a |
|||
long time. To develop a DApp, you have to shift your thinking to new |
|||
interaction paradigms. You must discover what you don’t know and reimagine |
|||
application interactions. |
|||
|
|||
For example, traditional applications allow users to “safely” forget their |
|||
application passwords because they can recover the password and their data |
|||
access from the a central authority. This isn’t true for a DApp. Users must be |
|||
responsible for keeping their own identity access and managing their own data. |
|||
How do you convey this to users? |
|||
|
|||
### How Dapp onboarding differs |
|||
{:.no_toc} |
|||
|
|||
Currently, users can create a Blockstack ID for free or buy their own ID. Dapps |
|||
that are submitted for app mining must include Blockstack authentication. This |
|||
authentication includes onboarding flow for users delievered through the |
|||
Blockstack Browser. The language and concepts presented by the flow are |
|||
important for you to understand before writing your own DApp. |
|||
|
|||
If you haven't already created your own Blockstack ID, do this now. As you |
|||
create an ID, consider what interactions are familiar to you and which are not. |
|||
If you already have a Blockstack ID, launch the browser and try resetting it. Or |
|||
trying logging on from a device or browser software you haven't used before. |
|||
|
|||
{% include create_id.md %} |
|||
|
|||
Once in the browser, investigate the account and locate the storage settings. |
|||
Consider the interaction as both a user and a app designer. Are these settings |
|||
what you expected or would you change them? |
|||
|
|||
### Take a user perspective |
|||
{:.no_toc} |
|||
|
|||
If you want to solve for an existing, traditional space, you must take time to |
|||
really consider what problems a DApp replacement would solve. But make sure you |
|||
also take the time to consider what challenges your new application has in |
|||
shifting user experiences. |
|||
|
|||
- What identity or data ownership features make my application unique or powerful? |
|||
- What typical expectations will users have that must be adjusted? |
|||
- How can my interaction design convey these new features to users so users can succeed? |
|||
|
|||
As a developer, your understanding of applications is vastly different from a |
|||
standard application user. Prototyping (paper or wireframes) and user testing |
|||
can help you determine if your approach is correct before you begin coding. |
|||
|
|||
1. Choose an application from the Blockstack Browser home page or from the <a href="https://app.co/" target="\_blank">list on the App.co site</a>. |
|||
|
|||
Blockstack maintains the App.co website as a central place for users and |
|||
developers to explore and review blockchain applications. This site has |
|||
application categories such as: |
|||
|
|||
- Business Tools |
|||
- Developer Tools |
|||
- Education & News |
|||
- Financial Services |
|||
- Games & Digital Assets |
|||
- Social Networking |
|||
- Health & Fitness |
|||
- Marketplaces |
|||
|
|||
2. Spend 20 minutes reviewing the application. |
|||
|
|||
- Is the application free? |
|||
- How did the application designers expose or hide decentralized features? |
|||
|
|||
3. Try logging into the same application from another device such as your phone. |
|||
|
|||
- You'll need to authenticate on this device with Blockstack too. |
|||
- How does the mobile experience differ from your desktop experience? |
|||
|
|||
Repeat this exercise with a friend or relative who is not a developer. This |
|||
should give you perspective on the problems users will encounter with your |
|||
potential application. |
|||
|
|||
## Research existing decentralized applications |
|||
|
|||
 |
|||
|
|||
This quote from Gene Luen Yang a Genius Grant recipient and comic book artist |
|||
has a good point. Have you researched what other top industry thinkers have said about |
|||
potential applications of blockchain technology? For example, EY developed a five-point |
|||
test to help determine if a blockchain solution would help for a problem: |
|||
|
|||
<div class="uk-card uk-card-default uk-card-body"> |
|||
<ul> <li>Are there multiple parties in this ecosystem? |
|||
Blockchains are fundamentally multiparty collaboration systems.</li> |
|||
<li>Is establishing trust between all parties an issue? |
|||
Blockchains improve trust between participants by having multiple points of verification.</li> |
|||
<li>Is it critical to have a detailed transactional record of activity? |
|||
If everyone agreed on everything, you wouldn't need a blockchain to verify who did what and when it was done.</li> |
|||
<li>Are we securing the ownership or management of a finite source? |
|||
Core logic in the blockchain system is designed to prevent double-counting of assets and to record ownership and transfers.</li> |
|||
<li>Does the network of partners benefit from increased transparency across the ecosystem? Blockchains are transparent by design.</li></ul> |
|||
|
|||
<p>From <a href="http://go.galegroup.com/ps/i.do?p=AONE&u=plan_smcl&id=GALE|A547075763&v=2.1&it=r&sid=AONE&asid=f2f8ee00" target="\_blank">Maslova, Natalia. "BLOCKCHAIN: DISRUPTION AND OPPORTUNITY." Strategic Finance, July 2018</a></p> |
|||
</div> |
|||
|
|||
The EY test is a general test about the domains that blockchain application can disrupt. You can also consider more specific behaviors a DApp should mee. Blockstack defines three principles that Blockstack applications should meet: |
|||
|
|||
* Users own their own data |
|||
* Users own their identities |
|||
* Users have free choice of clients |
|||
|
|||
If you haven't read it, read the full article <a href="http://127.0.0.1:4000/develop/dapp_principles.html" target="\_blank">on principles of Blockstack applications</a>. |
|||
|
|||
### Tips for coming up with application ideas |
|||
{:.no_toc} |
|||
|
|||
Before developing a DApp, research the blockchain space and engage with the Blockstack community. |
|||
|
|||
* Visit <a href="https://forum.blockstack.org/" target="\_blank">the Blockstack forum</a> |
|||
This is a valuable resource to learn about the questions that other developers have now or have had in the past. |
|||
* Visit the <a href="https://community.blockstack.org/" target="\_blank">Blockstack Community website</a> to learn about events that may be coming to your area. |
|||
* Join the Blockstack <a href="https://slofile.com/slack/blockstack" target="\_blank"> Slack channel</a> which you can join. |
|||
|
|||
When coming up with ideas for an application, you can try some thought experiments. |
|||
|
|||
- Imagine if an identity acted as an internet phone number? Could a service pre-screen email so that only those identities that showed an interaction on the blockchain could communicate? |
|||
- How could you use the blockchain to verify reviewers in an application like Yelp? What kind of features would you allow unverified reviewers? |
|||
- How could you use the blockchain to make online dating safer? |
|||
|
|||
A fun game is to use Google to combine the word blockchain with some word you |
|||
think might be unrelated such as juice or zoo. This kind of play can result in |
|||
some surprising finds and interesting ideas. |
|||
|
|||
|
|||
## Where to go next |
|||
{:.no_toc} |
|||
|
|||
In this section, you learned important areas for consideration and tips for |
|||
where to research. You learned some techniques for formulating and solidifying |
|||
your development efforts. Of course, building an app is a great way to generate |
|||
ideas. |
|||
|
|||
In the next section, you dive into the features of the Blockstack technology by |
|||
developing a sample application. Continue to [Zero to DApp, 3 of 4](zero_to_dapp_3.html). |
|||
@ -0,0 +1,832 @@ |
|||
--- |
|||
layout: learn |
|||
permalink: /:collection/:path.html |
|||
--- |
|||
# 3 - Build an Animal Kingdom DApp |
|||
{:.no_toc} |
|||
|
|||
**Zero to DAPP 3 of 4** |
|||
|
|||
In this page, you follow a tutorial which builds, runs, modifies, and deploys a |
|||
DApp called Animal Kingdom. Through this exercise, you'll learn about the |
|||
components of a Blockstack Dapp. You'll also learn about the technical |
|||
requirements for submitting a DApp for App.co. This page contains the following |
|||
topics |
|||
|
|||
* TOC |
|||
{:toc} |
|||
|
|||
<div class="uk-card uk-card-default uk-card-body"> |
|||
<h5>Can you skip this page?</h5> |
|||
<p>It isn't a good idea to skip this page, requirements for DApps that participate in App Mining are covered. So, everyone should at least skim through this page. |
|||
</p> |
|||
</div> |
|||
|
|||
|
|||
### Skills you need to build Animal Kingdom |
|||
|
|||
This tutorial is designed for a wide audience. Anyone with access to a Windows, |
|||
Mac, or Linux computer and some familiarity with a command line can build the |
|||
Animal Kingdom DApp. |
|||
|
|||
If you are good at following directions, chances are you can complete this |
|||
tutorial even if you have no programming experience. Knowledgeable developers |
|||
should easily be able to complete the tutorial within an hour by following |
|||
along. |
|||
|
|||
If you are a developer super hero, you may want to skip ahead or move |
|||
quickly and that's fine too. |
|||
|
|||
## Get prerequisites and set up environment |
|||
|
|||
To follow this tutorial, you need the following: |
|||
|
|||
* A Blockstack ID (identity) to test your Animal Kingdom. |
|||
* Access to the Mac terminal window and some familiarity with the command line it provides. |
|||
* An installation of the XCode command-line tools to support Node Package Manager (`npm`) |
|||
* The Node Package Manager package manager. |
|||
|
|||
Follow the procedures in this section to install these components. |
|||
|
|||
### Confirm or get a Blockstack ID |
|||
{:.no_toc} |
|||
|
|||
Confirm you have a Blockstack ID also known as an identity; `joe.id.blockstack` |
|||
is an example of an identity. |
|||
|
|||
* If you have an existing ID, log into the <a href="https://browser.blockstack.org/" target="\_blank">Blockstack Browser</a> in your browser. |
|||
|
|||
The Blockstack Browser is itself a DApp. Logging in confirms you have a valid |
|||
ID with the required _secret recovery key_ or _magic recovery code_. The |
|||
secret recovery key is a 12 or 24 word phrase you recorded when you created |
|||
the ID. The magic recovery code is a string of characters Blockstack emailed |
|||
to you when you created the your identity. You can confirm your identity with either. |
|||
|
|||
* If you do not yet have a Blockstack ID, <a href="https://browser.blockstack.org/" target="\_blank">create one through the Blockstack Browser</a> . |
|||
|
|||
Instructions for creating an ID are <a href="{{ site.baseurl |
|||
}}/browser/ids-introduction.html#create-an-initial-blockstack-id" |
|||
target="\_blank">available in this documentation</a>. |
|||
|
|||
|
|||
### Ensure command-line access |
|||
{:.no_toc} |
|||
|
|||
If you are using a Mac, you can find the **terminal** in the **Application > |
|||
Launchpad > Other** folder. |
|||
|
|||
<img src="images/terminal.png" alt=""> |
|||
|
|||
If you don't often use the command line, take a moment to test some common commands. |
|||
|
|||
<table class="uk-table uk-table-small uk-table-divider"> |
|||
<tr> |
|||
<th>Command</th> |
|||
<th>What it does</th> |
|||
</tr> |
|||
<tr> |
|||
<td><code>ls</code></td> |
|||
<td>Lists the files and directories in the current directory.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>cd</code></td> |
|||
<td>Change directory to navigate to locations in your file system.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>pwd</code></td> |
|||
<td>Print the working directory, the location you are working in.</td> |
|||
</tr> |
|||
</table> |
|||
|
|||
### Install XCode Command Line tools |
|||
{:.no_toc} |
|||
|
|||
The Command Line Tool package gives Mac terminal users many commonly used tools, |
|||
utilities, and compilers. Some of the contents installed by NPM require XCode. |
|||
|
|||
1. Open a terminal window on your system. |
|||
2. Enter the `xcode-select` command string: |
|||
|
|||
```bash |
|||
$ xcode-select --install |
|||
``` |
|||
|
|||
<img src="images/install-command-line-tools-os-x.jpg" alt=""> |
|||
|
|||
A software update dialog displays: |
|||
|
|||
<img src="images/confirm-install-command-line-tools-mac-os-x.jpg" alt=""> |
|||
|
|||
3. Click **Install** to confirm. |
|||
|
|||
You are prompted to agree to the terms of service. |
|||
|
|||
4. Agree to the terms of services. |
|||
|
|||
The tools are installed. This is fairly quick depending on your connection speed. |
|||
|
|||
|
|||
### Install Node Package Manager (NPM) |
|||
{:.no_toc} |
|||
|
|||
Open source developers from every continent use NPM to share software components |
|||
called packages. The Animal Kingdom uses React, Babel, and many other |
|||
components. You'll use the `npm` command to install these packaged components. |
|||
|
|||
1. Open a terminal window on your system. |
|||
2. Verify you have installed `npm` using the `which` command. |
|||
|
|||
<img src="images/command-line.png" alt=""> |
|||
|
|||
If `npm` is installed, `which` returns the command's location in your environment. |
|||
|
|||
3. If the `npm` command is not in your system, <a href="https://www.npmjs.com/get-npm" target="\_blank">install it using the instructions for your operating system</a>. |
|||
|
|||
Installing the NPM tool can take a several minutes depending on your connection speed. |
|||
|
|||
|
|||
## Overview of the Animal Kingdom DApp |
|||
|
|||
You are going to build a DApp called AnimalKingdom. Animal Kingdom is a DApp for |
|||
the web. Users log into it and create a animal persona that rules over a a |
|||
specific territory. The combination of persona and territory is a kingdom. Once |
|||
you create a kingdom, you can add subjects from other kingdoms. |
|||
|
|||
The Animal Kingdom interacts with two Blockstack services, the Blockstack |
|||
Browser (https://browser.blockstack.org) and the Gaia data storage hub |
|||
(https://hub.blockstack.org/). The Blockstack Browser is itself |
|||
a DApp. The storage hub is purely a service without user facing functionality. |
|||
|
|||
The following table describes the key interactions and screens in the DApp. |
|||
|
|||
<table class="uk-table uk-table-striped"> |
|||
<tr> |
|||
<th>Click to enlarge</th> |
|||
<th> Description</th> |
|||
</tr> |
|||
<tr> |
|||
<td><div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-enter.png" data-caption="Users must login with a Blockstack identity."> |
|||
<img src="images/kingdom-enter.png" alt=""> |
|||
</a> |
|||
</div> |
|||
</td> |
|||
<td><p>Users log in (authenticate) with a Blockstack identity. By authenticating, the user gives the application the ability to get and put data in the user's Gaia storage hub.</p></td> |
|||
</tr> |
|||
<tr> |
|||
<td><div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-signin.png" data-caption="Blockstack login dialogs."> |
|||
<img src="images/kingdom-signin.png" alt=""> |
|||
</a> |
|||
</div> |
|||
</td> |
|||
<td><p>The Blockstack login dialogs are part of the Blockstack Browser which is itself |
|||
a DApp. Once a user authenticates, the DApp code automatically |
|||
returns them to the Kingdom they were attempting to enter.</p></td> |
|||
</tr> |
|||
<tr> |
|||
<td><div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-new.png" data-caption="Choose a persona and territory."> |
|||
<img src="images/kingdom-new.png" alt=""> |
|||
</a> |
|||
</div></td> |
|||
<td><p>First-time visitors to a kingdom are prompted to create an animal persona and |
|||
a territory to rule. Once they make a selection, users click <strong>Done</strong> to create a |
|||
kingdom to rule. Behind the scenes, the data about the user's selection is stored in the user's GAIA hub. |
|||
</p> |
|||
</td> |
|||
</tr> |
|||
<tr> |
|||
<td> <div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-choices.gif" data-caption="Choose a persona and territory."> |
|||
<img src="images/kingdom-choices.gif" alt=""> |
|||
</a> |
|||
</div></td> |
|||
<td><p>Each kingdom has animals and territories. Users can edit their original persona/animal combination. You'll learn how to modify the Animal Kingdom code to add new animals and territories.</p></td> |
|||
</tr> |
|||
<tr> |
|||
<td><div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-subjects.gif" data-caption="Adding subjects"> |
|||
<img src="images/kingdom-subjects.gif" alt=""> |
|||
</a> |
|||
</div></td> |
|||
<td> |
|||
<p>Users can add subjects from territories in their own Animal Kingdom. The DApp updates the user's GAI hub each time the user addss a subect. Users can also visit other Animal Kingdom installations and add subjects from these as well. You'll learn how to modify the <b>Other Kingdoms</b> available in your installation. |
|||
</p> |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
|
|||
|
|||
## Get the Animal Kingdom code |
|||
|
|||
In this section, you copy the code for Animal Kingdom to your workstation. |
|||
|
|||
1. In your browser (Chrome, Safari, etc), <a href="https://github.com/blockstack/animal-kingdom" target="\_blank">open the Animal Kingdom code repository</a>. |
|||
|
|||
The AnimalKingdom code is kept in a public GitHub repository. |
|||
|
|||
2. Click the **Clone or download** button. |
|||
|
|||
If you have a GitHub account you can choose to clone the original repository |
|||
or fork it and then clone it. These instructions assume you are downloading |
|||
the code. |
|||
|
|||
3. Choose the **Download ZIP** for Animal Kingdom. |
|||
|
|||
<img src="images/kingdom-copy.png" alt=""> |
|||
|
|||
3. Check your download directory for the `animal-kingdom-master.zip` file. |
|||
4. Copy the download zip file to a directory where you keep code projects. |
|||
4. Unzip the file. |
|||
|
|||
<img src="images/kingdom-download.png" alt=""> |
|||
|
|||
After unzipping the file you should have a `animal-kingdom-master` directory. |
|||
|
|||
5. In your terminal change directory into top of the directory by entering: |
|||
|
|||
```bash |
|||
$ cd animal-kingdom-master |
|||
``` |
|||
|
|||
Use the `pwd` command to confirm which directory you are in. |
|||
|
|||
```bash |
|||
$ pwd |
|||
/Users/manthony/animal-kingdom-master |
|||
``` |
|||
|
|||
6. Take a minute review the files and subdirectories in your Animal Kingdom project. |
|||
|
|||
Use the `ls` command to list directory contents. |
|||
|
|||
<table class="uk-table uk-table-striped"> |
|||
<tr> |
|||
<th><b>Name</b> </th> |
|||
<th><b>Description</b></th> |
|||
</tr> |
|||
<tr> |
|||
<td><code>README.md</code></td> |
|||
<td>Contains a quick reference for building and running Animal Kingdom. </td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>package.json</code></td> |
|||
<td>An NPM project file.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>config</code></td> |
|||
<td>Environment configuration files written in Javascript.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>public</code></td> |
|||
<td>Files that are copied into the root of the site you are building.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>scripts</code></td> |
|||
<td>NPM scripts used to do common tasks in the project.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>src</code></td> |
|||
<td>Vue.js code source code for the site. This contains configuration files.</td> |
|||
</tr> |
|||
</table> |
|||
|
|||
## Build and run the sample in development mode |
|||
|
|||
You can build and run the Animal Kingdom on your local workstation. Before you |
|||
can run the program you use NPM to get all the dependent packages. |
|||
|
|||
1. Make sure you are in the root directory of the project. |
|||
|
|||
```bash |
|||
cd ~/animal-kingdom-master |
|||
pwd |
|||
/Users/manthony/animal-kingdom-master |
|||
``` |
|||
|
|||
2. Enter `npm install` to get the software components Animal Kingdom needs. |
|||
|
|||
```bash |
|||
$ npm install |
|||
|
|||
> fsevents@1.2.4 install /Users/manthony/animal-kingdom-master/node_modules/fsevents |
|||
> node install |
|||
|
|||
node-pre-gyp WARN Tried to download(404): https://fsevents-binaries.s3-us-west-2.amazonaws.com/v1.2.4/fse-v1.2.4-node-v67-darwin-x64.tar.gz |
|||
node-pre-gyp WARN Pre-built binaries not found for fsevents@1.2.4 and node@11.1.0 (node-v67 ABI, unknown) (falling back to source compile with node-gyp) |
|||
SOLINK_MODULE(target) Release/.node |
|||
CXX(target) Release/obj.target/fse/fsevents.o |
|||
In file included from ../fsevents.cc:6: |
|||
|
|||
... |
|||
|
|||
added 1390 packages from 766 contributors and audited 15238 packages in 16.11s |
|||
found 1 high severity vulnerability |
|||
run `npm audit fix` to fix them, or `npm audit` for details |
|||
$ |
|||
``` |
|||
|
|||
This command creates a `node_modules` subdirectory to your project code and |
|||
installs all the code libraries you need for your Animal Kingdom project. |
|||
|
|||
3. Enter the `ls` command to list the contents of your project directory to verify `npm` installed correctly. |
|||
|
|||
``` |
|||
$ ls |
|||
``` |
|||
|
|||
The `node_modules`directory contains many core libraries used by Animal |
|||
Kingdom. For example, the Blockstack Javascript library is in the |
|||
`nodule_modules/blockstack/lib` subdirectory. |
|||
|
|||
4. Start the Animal Kingdom DApp running on your workstation by entering: |
|||
|
|||
```bash |
|||
npm start |
|||
``` |
|||
|
|||
The `npm` program compiles the Animal Kingdom code. Once the code compiles, |
|||
the DApp opens Animal Kingdom running at the `http://localhost:3000` URL in |
|||
your browser. |
|||
|
|||
4. From the initial Animal Kingdom screen, choose an animal person and a territory. |
|||
5. Press **Done** at the bottom of the page. |
|||
|
|||
The Animal Kingdom makes a call to the Gaia hub to store your selection. |
|||
After a brief pause, the DApp returns you to the **Your Kingdom** page. If |
|||
you have problems, refresh the page and click **Your Kingdom** in the |
|||
menu. |
|||
|
|||
<img src="images/kingdom-ruler.png" alt=""> |
|||
|
|||
6. Spend a little time exploring the application. |
|||
|
|||
For example, you could edit your animal or visit the other pages such as **Animals** or **Territories**. |
|||
|
|||
7. Go back to your terminal where you started you application is running. |
|||
8. Press `CTRL-C` to stop the application. |
|||
|
|||
<img src="images/kingdom-stop.png" alt=""> |
|||
|
|||
You can start it again with `npm start` as you will later in this tutorial. |
|||
|
|||
|
|||
## Understand the application code |
|||
|
|||
The application has two major components, React and Blockstack. React is used to |
|||
build all the web components and interactions. You could replace React with any |
|||
framework that you like; Blockstack is web framework agnostic. This section does |
|||
not explain the React in any detail; The discussion focuses on the Blockstack |
|||
Javascript library the DApp instead. |
|||
|
|||
The <a href="https://blockstack.github.io/blockstack.js/" |
|||
target="\_blank">Blockstack Javascript library is all a developer needs to |
|||
create a DApp. It grants</a> the application the ability to authenticate a |
|||
Blockstack identity and to read and write to the user's data stored in a Gaia |
|||
hub. |
|||
|
|||
### Authenticating user identity |
|||
{:.no_toc} |
|||
|
|||
The `src/App.js` file creates a Blockstack `UserSession` and uses that session's |
|||
`isUserSignedIn()` method to determine if the user is signed in or out of the |
|||
application. Depending on the result of this method. The application redirects |
|||
to the `src/SignedIn` page or to the `src/Landing.js` page. |
|||
|
|||
```js |
|||
import React, { Component } from 'react' |
|||
import './App.css' |
|||
import { UserSession } from 'blockstack' |
|||
|
|||
import Landing from './Landing' |
|||
import SignedIn from './SignedIn' |
|||
|
|||
class App extends Component { |
|||
|
|||
constructor() { |
|||
super() |
|||
this.userSession = new UserSession() |
|||
} |
|||
|
|||
componentWillMount() { |
|||
const session = this.userSession |
|||
if(!session.isUserSignedIn() && session.isSignInPending()) { |
|||
session.handlePendingSignIn() |
|||
.then((userData) => { |
|||
if(!userData.username) { |
|||
throw new Error('This app requires a username.') |
|||
} |
|||
window.location = `/kingdom/${userData.username}` |
|||
}) |
|||
} |
|||
} |
|||
|
|||
render() { |
|||
return ( |
|||
<main role="main"> |
|||
{this.userSession.isUserSignedIn() ? |
|||
<SignedIn /> |
|||
: |
|||
<Landing /> |
|||
} |
|||
</main> |
|||
); |
|||
} |
|||
} |
|||
|
|||
export default App |
|||
``` |
|||
|
|||
The first time you start the application, this code determines if the user has |
|||
signed into the DApp previously. If not, it opens the `Landing.js` page. This |
|||
page offers the user an opportunity to **Sign in to Blockstack**. |
|||
|
|||
Clicking the button ends up calling the `redirectToSignIn()` method which generates an |
|||
authentication request and redirects the user to the Blockstack browser to |
|||
approve the sign in request. The actual Blockstack sign-in dialog depends on |
|||
whether the user already has an existing session in the Blockstack Browser. |
|||
|
|||
<img src="images/kingdom_notin.png" alt=""> |
|||
|
|||
Signing in with an identity is the means by which the user grants the DApp |
|||
access. Access means the DApp can read the user profile and read/write user data |
|||
for the DApp. Data is encrypted at a unique URL on a GAI storage hub. |
|||
|
|||
<div class="uk-card uk-card-default uk-card-body"> |
|||
<h5>App Mining Requirement: Blockstack Authentication</h5> |
|||
<p>To participate in application mining, your application must integrate Blockstack authentication. |
|||
</p> |
|||
</div> |
|||
|
|||
### Get and put user data to a GAIA Hub |
|||
{:.no_toc} |
|||
|
|||
GAI is the Blockstack data storage hub (https://hub.blockstack.org). Once a user |
|||
authenticates, the application can get and put application data in the user's |
|||
storage. After a user signs in, the `SignedIn.js` code checks the user's GAI |
|||
profile by running the `loadMe()` method. |
|||
|
|||
```js |
|||
loadMe() { |
|||
const options = { decrypt: false } |
|||
this.userSession.getFile(ME_FILENAME, options) |
|||
.then((content) => { |
|||
if(content) { |
|||
const me = JSON.parse(content) |
|||
this.setState({me, redirectToMe: false}) |
|||
} else { |
|||
const me = null |
|||
|
|||
this.setState({me, redirectToMe: true}) |
|||
} |
|||
}) |
|||
} |
|||
``` |
|||
|
|||
The `loadMe()` code uses the Blockstack's `getFile()` method to get the |
|||
specified file from the applications data store. If the users' data store on |
|||
GAIA does not have the data, which is the case for a new users, the Gaia hub |
|||
responds with HTTP `404` code and the `getFile` promise resolves to null. If you |
|||
are using a Chrome Developer Tools with the DApp, you'll see these errors in a |
|||
browser's developer **Console**. |
|||
|
|||
<img src="images/kingdom-errors.png" alt=""> |
|||
|
|||
After a user choses an animal persona and a territory, the user presses **Done** |
|||
and the application stores the user data on GAIA. |
|||
|
|||
```js |
|||
saveMe(me) { |
|||
this.setState({me, savingMe: true}) |
|||
const options = { encrypt: false } |
|||
this.userSession.putFile(ME_FILENAME, JSON.stringify(me), options) |
|||
.finally(() => { |
|||
this.setState({savingMe: false}) |
|||
}) |
|||
} |
|||
``` |
|||
|
|||
The Blockstack <a href="https://blockstack.github.io/blockstack.js/#putfile" |
|||
target="\_blank"><code>putFile()</code></a> stores the data provided in the |
|||
user's DApp data store. You can view the URL for the data store from a user's |
|||
profile. If you tested your Animal Kingdom, you can see this on your profile. |
|||
To see your profile, go to the Blockstack explorer and search for your ID: |
|||
|
|||
<img src="images/explorer.png" alt=""> |
|||
|
|||
In the next section, you extend your Kingdom's configuration. |
|||
|
|||
<div class="uk-card uk-card-default uk-card-body"> |
|||
<h5>App Mining Requirement: Gaia Storage</h5> |
|||
<p>To participate in application mining, your application must make use of Gaia storage. |
|||
</p> |
|||
</div> |
|||
|
|||
## Expand your kingdom |
|||
|
|||
Your DApp contains three pages **Animals**, **Territories**, and **Other |
|||
Kingdoms** that are derived from three code elements: |
|||
|
|||
* The `src/constants.js` file defines the application's data profile. |
|||
* The `public/animals` directory which contains images. |
|||
* The `public/territories` directory which contains images. |
|||
|
|||
In this section, you learn how to add another kingdom to the available **Other |
|||
Kingdoms** and how to add another territory. |
|||
|
|||
### Add a territory |
|||
{:.no_toc} |
|||
|
|||
If your application is still running in localhost stop it with a `CTRL-C` from |
|||
your keyboard. |
|||
|
|||
1. Decide what kind of territory to add &emdash; desert, ocean, or city! |
|||
|
|||
This example adds Westeros, a fictional territory. |
|||
|
|||
2. Search for an image to represent your new territory. |
|||
|
|||
Google images is a good place to find <a href="images/westeros.jpg" target="\_blank">a JPEG image of Westeros</a>. |
|||
|
|||
3. Save the image to the `public/territories` folder in your Animal Kingdom project code. |
|||
|
|||
{% include warning.html content="The territory filename must be all lower case and have a <code>.jpg</code> extension. |
|||
For this example, the territory image is saved in the <code>westeros.jpg</code> file." %} |
|||
|
|||
4. Use the `ls` command to confirm your file appears in `territories` directory and has the correct name. |
|||
|
|||
```bash |
|||
ls public/territories/ |
|||
forest.jpg tundra.jpg westeros.jpg |
|||
``` |
|||
|
|||
4. Open the `src/constant.js` file in your favorite editor. |
|||
5. Scroll down to the section that defines the **Territories**. |
|||
|
|||
```js |
|||
export const TERRITORIES = [ |
|||
{ |
|||
id: 'forest', |
|||
name: 'Forest', |
|||
superpower: 'Trees!' |
|||
}, |
|||
{ |
|||
id: 'tundra', |
|||
name: 'Tundra', |
|||
superpower: 'Let it snow!' |
|||
} |
|||
] |
|||
``` |
|||
|
|||
6. Add your new territory. |
|||
|
|||
```js |
|||
export const TERRITORIES = [ |
|||
{ |
|||
id: 'forest', |
|||
name: 'Forest', |
|||
superpower: 'Trees!' |
|||
}, |
|||
{ |
|||
id: 'tundra', |
|||
name: 'Tundra', |
|||
superpower: 'Let it snow!' |
|||
}, |
|||
{ |
|||
id: 'westeros', |
|||
name: 'Westeros', |
|||
superpower: 'The Iron Throne!' |
|||
} |
|||
] |
|||
``` |
|||
7. Save and close the `contstant.js` file. |
|||
8. Back in a terminal window, restart your application. |
|||
|
|||
```bash |
|||
$ npm start |
|||
``` |
|||
9. After the application starts, navigate to the **Territories** page and look for your `Westeros` territory. |
|||
|
|||
<img src="images/kingdom-throne.png" alt=""> |
|||
|
|||
### Add the Blockstack kingdom |
|||
{:.no_toc} |
|||
|
|||
Your Animal Kingdom has only recognizes two **Other Kingdoms**. In this section, |
|||
you add a third, the Blockstack kingdom (`https://animalkingdoms.netlify.com`). |
|||
|
|||
1. Open the `src/constant.js` file in your favorite editor. |
|||
|
|||
On Mac you can use TextEdit or Vim. |
|||
|
|||
2. Scroll down to the section that defines the **Other Kingdoms** |
|||
|
|||
```js |
|||
export const OTHER_KINGDOMS = [ |
|||
{ |
|||
app: 'https://animal-kingdom-1.firebaseapp.com', |
|||
ruler: 'larry.id' |
|||
}, |
|||
{ |
|||
app: 'http://localhost:3001', |
|||
ruler: 'larz.id' |
|||
} |
|||
] |
|||
``` |
|||
|
|||
To add a kingdom, you need its URL and the ID of its owner. |
|||
|
|||
3. Edit the file and add the `https://animalkingdoms.netlify.com` which is owned by `moxiegirl.id.blockstack`. |
|||
|
|||
When you are done the file will look like this. |
|||
|
|||
|
|||
```js |
|||
export const OTHER_KINGDOMS = [ |
|||
{ |
|||
app: 'https://animal-kingdom-1.firebaseapp.com', |
|||
ruler: 'larry.id' |
|||
}, |
|||
{ |
|||
app: 'http://localhost:3001', |
|||
ruler: 'larz.id' |
|||
}, |
|||
{ |
|||
app: 'https://animalkingdoms.netlify.com', |
|||
ruler: 'moxiegirl.id.blockstack' |
|||
} |
|||
] |
|||
``` |
|||
|
|||
4. Save and close the `constants.js` file. |
|||
5. Back in your browser, navigate to the **Other Kingdoms** page. |
|||
|
|||
<img src="images/kingdom-moxiegirl.png" alt=""> |
|||
|
|||
7. Got to the `moxiegirl` kingdom by clicking on her kingdom. |
|||
8. Try adding a subject from Moxiegirl's kingdom to yours. |
|||
|
|||
|
|||
## Go live on the Internet |
|||
|
|||
In this section you use a free Netlify account and a free GitHub account to take |
|||
your kingdom live on the internet. Netlify provides hosting and serverless |
|||
backend services for static websites. GitHub is a code hosting site. |
|||
|
|||
<div class="uk-card uk-card-default uk-card-body uk-section-muted"> |
|||
<h5>App Mining Requirement: Review Accessibility</h5> |
|||
<p>To participate in application mining, your application must be available for review. Open source projects must provide the URL to their code. Projects with private repositories can provides their application in a package form. |
|||
</p> |
|||
</div> |
|||
|
|||
### Run your Kingdom on the internet |
|||
{:.no_toc} |
|||
|
|||
So far, you've been running the application locally. This means you are the only |
|||
person that can use it to create a kingdom. You can make your application |
|||
available to others by hosting it out on the internet. You can do this for free |
|||
with a Netlify account. |
|||
|
|||
Before you begin, you need to build a site that is ready to deploy. |
|||
|
|||
1. In your terminal, press `CTRL-C` on your keyboard to stop your `npm start` build. |
|||
2. Build a website from your code by entering the `npm run build` command: |
|||
|
|||
```bash |
|||
npm run build |
|||
``` |
|||
|
|||
<img src="images/run-build.png" alt=""> |
|||
|
|||
When the command completes, you should have a new `build` subdirectory in your project. |
|||
|
|||
3. Open your project in the Finder. |
|||
4. Locate the newly created `build` subfolder. |
|||
|
|||
<img src="images/finder-build.png" alt=""> |
|||
|
|||
5. <a href="https://app.netlify.com/signup" target="\_blank">Sign up for a free Netlify account</a> |
|||
|
|||
This example assumes you create an account by providing an email and password. |
|||
|
|||
<img src="images/netlify-account.gif" alt=""> |
|||
|
|||
6. In your email inbox, find Netlify's welcome email and verify your account. |
|||
|
|||
<img src="images/netlify-verify.png" alt=""> |
|||
|
|||
7. Log into Netlify and go to the **Overview** page in your browser. |
|||
8. Drag your `build` subdirectory from the Finder into the drop zone in Netlify. |
|||
|
|||
<img src="images/netlify-deploy.gif" alt=""> |
|||
|
|||
After a moment, Netlify builds your code and displays the location of your new webiste. |
|||
|
|||
<img src="images/kingdom-build.png" alt=""> |
|||
|
|||
9. Click on your website name to display the website. |
|||
|
|||
You are prompted to sign into this new site with your Blockstack ID. |
|||
|
|||
10. Click **Sign in with Blockstack**. |
|||
|
|||
After you sign in, your website presents you with this message: |
|||
|
|||
<img src="images/kingdom-failed.png" alt=""> |
|||
|
|||
You get this message because, when you authenticates, your DApp at one URL |
|||
requested a resource (an identity) from another DApp, the Blockstack |
|||
Browser. A request for a resource outside of the origin (your new website) |
|||
is called as a _cross-origin request_(CORs). Getting data in this manner can |
|||
be risky, so you must configure your website security to allow interactions |
|||
across origins. |
|||
|
|||
<div class="uk-inline"> |
|||
<button class="uk-button uk-button-primary" enter="button">Click me to learn how CORS is like borrowing a ladder.</button> |
|||
<div uk-dropdown> |
|||
You can think of CORS interactions as an apartment building with Security. |
|||
For example, if you need to borrow a ladder, you could ask a neighbor in |
|||
your building who has one. Security would likely not have a problem with |
|||
this request (i.e., same-origin, your building). If you needed a particular |
|||
tool, however, and you ordered it delivered from an online hardware store |
|||
(i.e., cross-origin, another site), Security may request identificatin |
|||
before allowing the delivery man into the apartment building. |
|||
<br> |
|||
Credit: <a href="https://www.codecademy.com/articles/what-is-cors" target="\_blank">Codecademy</a> |
|||
</div> |
|||
</div> |
|||
|
|||
The way you configure CORs depends on which company is serving your website. |
|||
You are using Netlify for this example. |
|||
|
|||
11. Locate the `cors/_headers` and `cors/_redirects` files in your project. |
|||
|
|||
You can use the Finder or the `ls` command. |
|||
|
|||
<img src="images/finder.png" alt=""> |
|||
|
|||
12. Copy them into your `public` directory. |
|||
|
|||
To copy them with the `ls` command, enter the following in the root of the `animal-kingdom-master` project. |
|||
|
|||
```bash |
|||
cp cors/_headers public |
|||
cp cors/_redirects public |
|||
``` |
|||
|
|||
The name of each file, with the underscore, is essential. |
|||
|
|||
13. Make sure you are in the `animal-kingdom-master` directory, run the `npm run build` command again. |
|||
15. Drag the `build` file back into the Netlify drop zone. |
|||
|
|||
After a moment, Netlify publishes your site. Check the published location, it may have changed. |
|||
|
|||
16. Click on the link and log into your Animal Kingdom. |
|||
17. Recreate your animal person and territory. |
|||
|
|||
The Animal Kingdom is identified by its location on the Internet, remember? |
|||
So, the animal kingdom you created on your local workstation is different |
|||
than the one you create on Netlify. |
|||
|
|||
### Add your Kingdom to our Clan |
|||
{:.no_toc} |
|||
|
|||
At this point, your kingdom is isolated. If you know another kingdom, you can |
|||
add subjects from that kingdom but other kingdoms can access your subjects. In |
|||
this section, you use a free GitHub account to add your kingdom to the |
|||
Blockstack kingdom. |
|||
|
|||
1. If you have a GitHub account, go to step 2 otherwise go to GitHub <a href="https://github.com/" target="\_blank">site and create a new account</a>. |
|||
2. Go to the <a href="https://github.com/blockstack/animal-kingdom/issues" target="\_blank">https://github.com/blockstack/animal-kingdom/issues</a> repository on Github. |
|||
2. Click **New Issue**. |
|||
|
|||
The new issue dialog appears. |
|||
|
|||
3. Fill out the issue with the URL from Netlify and your Blockstack id. |
|||
|
|||
When you are done, your issue will look like the following: |
|||
|
|||
<img src="images/kingdom-issue.png" alt=""> |
|||
|
|||
4. Press **Submit new issue**. |
|||
|
|||
The Blockstack team will add your Netlify kingdom to ours. When we do that, we will notify you on the issue and you'll also get an email. |
|||
|
|||
5. When you receive the email, login into the Blockstack Animal kingdom to see your kingdom under **Other Kingdoms**. |
|||
|
|||
|
|||
## Next Steps |
|||
{:.no_toc} |
|||
|
|||
Well, you have produced your very first DApp. Congratulations! If you have a |
|||
twitter account, why not tell some folks? |
|||
|
|||
<a href="https://twitter.com/share?ref_src=twsrc%5Etfw" |
|||
class="twitter-share-button" data-size="large" data-text="I just built a DApp |
|||
using @blockstack's Zero to DApp tutorial! " data-hashtags="blockstack, |
|||
blockchain, blockchainnopain, blockchainnopainblockstack" |
|||
data-show-count="true">Tweet your work!</a><script async |
|||
src="https://platform.twitter.com/widgets.js" charset="utf-8"></script> |
|||
|
|||
In the next section, you learn how you can participate in App Mining by submitting a [DApp to App.co — the Universal App store](zero_to_dapp_4.html). |
|||
@ -0,0 +1,803 @@ |
|||
--- |
|||
layout: learn |
|||
permalink: /:collection/:path.html |
|||
--- |
|||
# 3. Build an Animal Kingdom DApp |
|||
{:.no_toc} |
|||
|
|||
**Zero to DAPP 3 of 4** |
|||
|
|||
In this part, you follow a tutorial which builds, runs, and modifies a DAPP |
|||
called Animal Kingdom. Through this exercise, you'll learn about the |
|||
interactions between a Blockstack identity and a DApp. You'll also learn about |
|||
the Blockstack Javascript calls in a typical DApp. |
|||
|
|||
* TOC |
|||
{:toc} |
|||
|
|||
### Skills you need to build Animal Kingdom |
|||
|
|||
This tutorial is designed for a wide audience. Anyone with access to a Windows, |
|||
Mac, or Linux computer and some familiarity with a command line can build the |
|||
Animal Kingdom DApp. |
|||
|
|||
If you are good at following directions, chances are you can complete this |
|||
tutorial even if you have no programming experience. Knowledgeable developers |
|||
should easily be able to complete the tutorial within an hour by following |
|||
along. |
|||
|
|||
If you are a developer super hero, you may want to skip ahead or move |
|||
quickly and that's fine too. |
|||
|
|||
## Get prerequisites and set up environment |
|||
|
|||
To follow this tutorial, you need the following: |
|||
|
|||
* A Blockstack ID (identity) to test your Animal Kingdom. |
|||
* Access to the Mac terminal window and some familiarity with the command line it provides. |
|||
* An installation of the XCode command-line tools to support Node Package Manager (`npm`) |
|||
* The Node Package Manager package manager. |
|||
|
|||
Follow the procedures in this section to install these components. |
|||
|
|||
### Confirm or get a Blockstack ID |
|||
{:.no_toc} |
|||
|
|||
Confirm you have a Blockstack ID also known as an identity; `joe.id.blockstack` |
|||
is an example of an identity. |
|||
|
|||
* If you have an existing ID, log into the <a href="https://browser.blockstack.org/" target="\_blank">Blockstack Browser</a> in your browser. |
|||
|
|||
The Blockstack Browser is itself a DApp. Logging in confirms you have a valid |
|||
ID with the required _secret recovery key_ or _magic recovery code_. The |
|||
secret recovery key is a 12 or 24 word phrase you recorded when you created |
|||
the ID. The magic recovery code is a string of characters Blockstack emailed |
|||
to you when you created the your identity. You can confirm your identity with either. |
|||
|
|||
* If you do not yet have a Blockstack ID, <a href="https://browser.blockstack.org/" target="\_blank">create one through the Blockstack Browser</a> . |
|||
|
|||
Instructions for creating an ID are <a href="{{ site.baseurl |
|||
}}/browser/ids-introduction.html#create-an-initial-blockstack-id" |
|||
target="\_blank">available in this documentation</a>. |
|||
|
|||
|
|||
### Ensure command-line access |
|||
{:.no_toc} |
|||
|
|||
If you are using a Mac, you can find the **terminal** in the **Application > |
|||
Launchpad > Other** folder. |
|||
|
|||
<img src="images/terminal.png" alt=""> |
|||
|
|||
If you don't often use the command line, take a moment to test some common commands. |
|||
|
|||
<table class="uk-table uk-table-small uk-table-divider"> |
|||
<tr> |
|||
<th>Command</th> |
|||
<th>What it does</th> |
|||
</tr> |
|||
<tr> |
|||
<td><code>ls</code></td> |
|||
<td>Lists the files and directories in the current directory.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>cd</code></td> |
|||
<td>Change directory to navigate to locations in your file system.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>pwd</code></td> |
|||
<td>Print the working directory, the location you are working in.</td> |
|||
</tr> |
|||
</table> |
|||
|
|||
### Install XCode Command Line tools |
|||
{:.no_toc} |
|||
|
|||
The Command Line Tool package gives Mac terminal users many commonly used tools, |
|||
utilities, and compilers. Some of the contents installed by NPM require XCode. |
|||
|
|||
1. Open a terminal window on your system. |
|||
2. Enter the `xcode-select` command string: |
|||
|
|||
```bash |
|||
$ xcode-select --install |
|||
``` |
|||
|
|||
<img src="images/install-command-line-tools-os-x.jpg" alt=""> |
|||
|
|||
A software update dialog displays: |
|||
|
|||
<img src="images/confirm-install-command-line-tools-mac-os-x.jpg" alt=""> |
|||
|
|||
3. Click **Install** to confirm. |
|||
|
|||
You are prompted to agree to the terms of service. |
|||
|
|||
4. Agree to the terms of services. |
|||
|
|||
The tools are installed. This is fairly quick depending on your connection speed. |
|||
|
|||
|
|||
### Install Node Package Manager (NPM) |
|||
{:.no_toc} |
|||
|
|||
Open source developers from every continent use NPM to share software components |
|||
called packages. The Animal Kingdom uses React, Babel, and many other |
|||
components. You'll use the `npm` command to install these packaged components. |
|||
|
|||
|
|||
1. Verify you have installed `npm` using the `which` command. |
|||
|
|||
<img src="images/command-line.png" alt=""> |
|||
|
|||
If `npm` is installed, `which` returns the command's location in your environment. |
|||
|
|||
3. If the `npm` command is not in your system, <a href="https://www.npmjs.com/get-npm" target="\_blank">install it</a>. |
|||
|
|||
Installing the NPM tool can take a several minutes depending on your connection speed. |
|||
|
|||
|
|||
## Overview of the Animal Kingdom DApp |
|||
|
|||
You are going to build a DApp called AnimalKingdom. Animal Kingdom is a DApp for |
|||
the web. Users log into it and create a animal persona that rules over a a |
|||
specific territory. The combination of persona and territory is a kingdom. Once |
|||
you create a kingdom, you can add subjects from other kingdoms. |
|||
|
|||
The Animal Kingdom interacts with two Blockstack services, the Blockstack |
|||
Browser (https://browser.blockstack.org) and the Gaia data storage hub |
|||
(https://hub.blockstack.org/). The Blockstack Browser is itself |
|||
a DApp. The storage hub is purely a service without user facing functionality. |
|||
|
|||
The following table describes the key interactions and screens in the DApp. |
|||
|
|||
<table class="uk-table uk-table-striped"> |
|||
<tr> |
|||
<th>Click to enlarge</th> |
|||
<th> Description</th> |
|||
</tr> |
|||
<tr> |
|||
<td><div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-enter.png" data-caption="Users must login with a Blockstack identity."> |
|||
<img src="images/kingdom-enter.png" alt=""> |
|||
</a> |
|||
</div> |
|||
</td> |
|||
<td><p>Users log in (authenticate) with a Blockstack identity. By authenticating, the user gives the application the ability to get and put data in the user's Gaia storage hub.</p></td> |
|||
</tr> |
|||
<tr> |
|||
<td><div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-signin.png" data-caption="Blockstack login dialogs."> |
|||
<img src="images/kingdom-signin.png" alt=""> |
|||
</a> |
|||
</div> |
|||
</td> |
|||
<td><p>The Blockstack login dialogs are part of the Blockstack Browser which is itself |
|||
a DApp. Once a user authenticates, the DApp code automatically |
|||
returns them to the Kingdom they were attempting to enter.</p></td> |
|||
</tr> |
|||
<tr> |
|||
<td><div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-new.png" data-caption="Choose a persona and territory."> |
|||
<img src="images/kingdom-new.png" alt=""> |
|||
</a> |
|||
</div></td> |
|||
<td><p>First-time visitors to a kingdom are prompted to create an animal persona and |
|||
a territory to rule. Once they make a selection, users click <strong>Done</strong> to create a |
|||
kingdom to rule. Behind the scenes, the data about the user's selection is stored in the user's GAIA hub. |
|||
</p> |
|||
</td> |
|||
</tr> |
|||
<tr> |
|||
<td> <div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-choices.gif" data-caption="Choose a persona and territory."> |
|||
<img src="images/kingdom-choices.gif" alt=""> |
|||
</a> |
|||
</div></td> |
|||
<td><p>Each kingdom has animals and territories. Users can edit their original persona/animal combination. You'll learn how to modify the Animal Kingdom code to add new animals and territories.</p></td> |
|||
</tr> |
|||
<tr> |
|||
<td><div uk-lightbox="animation: slide"> |
|||
<a class="uk-inline" href="images/kingdom-subjects.gif" data-caption="Adding subjects"> |
|||
<img src="images/kingdom-subjects.gif" alt=""> |
|||
</a> |
|||
</div></td> |
|||
<td> |
|||
<p>Users can add subjects from territories in their own Animal Kingdom. The DApp updates the user's GAI hub each time the user addss a subect. Users can also visit other Animal Kingdom installations and add subjects from these as well. You'll learn how to modify the <b>Other Kingdoms</b> available in your installation. |
|||
</p> |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
|
|||
|
|||
## Get the Animal Kingdom code |
|||
|
|||
In this section, you copy the code for Animal Kingdom to your workstation. |
|||
|
|||
1. In your browser (Chrome, Safari, etc), <a href="https://github.com/blockstack/animal-kingdom" target="\_blank">open the Animal Kingdom code repository</a>. |
|||
|
|||
The AnimalKingdom code is kept in a public GitHub repository. |
|||
|
|||
2. Click the **Clone or download** button. |
|||
|
|||
If you have a GitHub account you can choose to clone the original repository |
|||
or fork it and then clone it. These instructions assume you are downloading |
|||
the code. |
|||
|
|||
3. Choose the **Download ZIP** for Animal Kingdom. |
|||
|
|||
<img src="images/kingdom-copy.png" alt=""> |
|||
|
|||
3. Check your download directory for the `animal-kingdom-master.zip` file. |
|||
4. Copy the download zip file to a directory where you keep code projects. |
|||
4. Unzip the file. |
|||
|
|||
<img src="images/kingdom-download.png" alt=""> |
|||
|
|||
After unzipping the file you should have a `animal-kingdom-master` directory. |
|||
|
|||
5. In your terminal change directory into top of the directory by entering: |
|||
|
|||
```bash |
|||
$ cd animal-kingdom-master |
|||
``` |
|||
|
|||
Use the `pwd` command to confirm which directory you are in. |
|||
|
|||
```bash |
|||
$ pwd |
|||
/Users/manthony/animal-kingdom-master |
|||
``` |
|||
|
|||
6. Take a minute review the files and subdirectories in your Animal Kingdom project. |
|||
|
|||
Use the `ls` command to list directory contents. |
|||
|
|||
<table class="uk-table uk-table-striped"> |
|||
<tr> |
|||
<th><b>Name</b> </th> |
|||
<th><b>Description</b></th> |
|||
</tr> |
|||
<tr> |
|||
<td><code>README.md</code></td> |
|||
<td>Contains a quick reference for building and running Animal Kingdom. </td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>package.json</code></td> |
|||
<td>An NPM project file.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>config</code></td> |
|||
<td>Environment configuration files written in Javascript.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>public</code></td> |
|||
<td>Files that are copied into the root of the site you are building.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>scripts</code></td> |
|||
<td>NPM scripts used to do common tasks in the project.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><code>src</code></td> |
|||
<td>Vue.js code source code for the site. This contains configuration files.</td> |
|||
</tr> |
|||
</table> |
|||
|
|||
## Build and run the sample in development mode |
|||
|
|||
You can build and run the Animal Kingdom on your local workstation. Before you |
|||
can run the program you use NPM to get all the dependent packages. |
|||
|
|||
1. Make sure you are in the root directory of the project. |
|||
|
|||
```bash |
|||
cd ~/animal-kingdom-master |
|||
pwd |
|||
/Users/manthony/animal-kingdom-master |
|||
``` |
|||
|
|||
2. Enter `npm install` to get the software components Animal Kingdom needs. |
|||
|
|||
```bash |
|||
$ npm install |
|||
|
|||
> fsevents@1.2.4 install /Users/manthony/animal-kingdom-master/node_modules/fsevents |
|||
> node install |
|||
|
|||
node-pre-gyp WARN Tried to download(404): https://fsevents-binaries.s3-us-west-2.amazonaws.com/v1.2.4/fse-v1.2.4-node-v67-darwin-x64.tar.gz |
|||
node-pre-gyp WARN Pre-built binaries not found for fsevents@1.2.4 and node@11.1.0 (node-v67 ABI, unknown) (falling back to source compile with node-gyp) |
|||
SOLINK_MODULE(target) Release/.node |
|||
CXX(target) Release/obj.target/fse/fsevents.o |
|||
In file included from ../fsevents.cc:6: |
|||
|
|||
... |
|||
|
|||
added 1390 packages from 766 contributors and audited 15238 packages in 16.11s |
|||
found 1 high severity vulnerability |
|||
run `npm audit fix` to fix them, or `npm audit` for details |
|||
$ |
|||
``` |
|||
|
|||
This command creates a `node_modules` subdirectory to your project code and |
|||
installs all the code libraries you need for your Animal Kingdom project. |
|||
|
|||
3. Enter the `ls` command to list the contents of your project directory to verify `npm` installed correctly. |
|||
|
|||
``` |
|||
$ ls |
|||
``` |
|||
|
|||
The `node_modules`directory contains many core libraries used by Animal |
|||
Kingdom. For example, the Blockstack Javascript library is in the |
|||
`nodule_modules/blockstack/lib` subdirectory. |
|||
|
|||
4. Start the Animal Kingdom DApp running on your workstation by entering: |
|||
|
|||
```bash |
|||
npm start |
|||
``` |
|||
|
|||
The `npm` program compiles the Animal Kingdom code. Once the code compiles, |
|||
the DApp opens Animal Kingdom running at the `http://localhost:3000` URL in |
|||
your browser. |
|||
|
|||
4. From the initial Animal Kingdom screen, choose an animal person and a territory. |
|||
5. Press **Done** at the bottom of the page. |
|||
|
|||
The Animal Kingdom makes a call to the Gaia hub to store your selection. |
|||
After a brief pause, the DApp returns you to the **Your Kingdom** page. If |
|||
you have problems, refresh the page and click **Your Kingdom** in the |
|||
menu. |
|||
|
|||
<img src="images/kingdom-ruler.png" alt=""> |
|||
|
|||
6. Spend a little time exploring the application. |
|||
|
|||
For example, you could edit your animal or visit the other pages such as **Animals** or **Territories**. |
|||
|
|||
7. Go back to your terminal where you started you application is running. |
|||
8. Press `CTRL-C` to stop the application. |
|||
|
|||
<img src="images/kingdom-stop.png" alt=""> |
|||
|
|||
You can start it again with `npm start` as you will later in this tutorial. |
|||
|
|||
|
|||
## Understand the application code |
|||
|
|||
The application has two major components, React and Blockstack. React is used to |
|||
build all the web components and interactions. You could replace React with any |
|||
framework that you like; Blockstack is web framework agnostic. This section does |
|||
not explain the React in any detail; The discussion focuses on the Blockstack |
|||
Javascript library the DApp instead. |
|||
|
|||
The <a href="https://blockstack.github.io/blockstack.js/" |
|||
target="\_blank">Blockstack Javascript library is all a developer needs to |
|||
create a DApp. It grants</a> the application the ability to authenticate a |
|||
Blockstack identity and to read and write to the user's data stored in a Gaia |
|||
hub. |
|||
|
|||
### Authenticating user identity |
|||
{:.no_toc} |
|||
|
|||
The `src/App.js` file creates a Blockstack `UserSession` and uses that session's |
|||
`isUserSignedIn()` method to determine if the user is signed in or out of the |
|||
application. Depending on the result of this method. The application redirects |
|||
to the `src/SignedIn` page or to the `src/Landing.js` page. |
|||
|
|||
```js |
|||
import React, { Component } from 'react' |
|||
import './App.css' |
|||
import { UserSession } from 'blockstack' |
|||
|
|||
import Landing from './Landing' |
|||
import SignedIn from './SignedIn' |
|||
|
|||
class App extends Component { |
|||
|
|||
constructor() { |
|||
super() |
|||
this.userSession = new UserSession() |
|||
} |
|||
|
|||
componentWillMount() { |
|||
const session = this.userSession |
|||
if(!session.isUserSignedIn() && session.isSignInPending()) { |
|||
session.handlePendingSignIn() |
|||
.then((userData) => { |
|||
if(!userData.username) { |
|||
throw new Error('This app requires a username.') |
|||
} |
|||
window.location = `/kingdom/${userData.username}` |
|||
}) |
|||
} |
|||
} |
|||
|
|||
render() { |
|||
return ( |
|||
<main role="main"> |
|||
{this.userSession.isUserSignedIn() ? |
|||
<SignedIn /> |
|||
: |
|||
<Landing /> |
|||
} |
|||
</main> |
|||
); |
|||
} |
|||
} |
|||
|
|||
export default App |
|||
``` |
|||
|
|||
The first time you start the application, this code determines if the user has |
|||
signed into the DApp previously. If not, it opens the `Landing.js` page. This |
|||
page offers the user an opportunity to **Sign in to Blockstack**. |
|||
|
|||
Clicking the button ends up calling the `redirectToSignIn()` method which generates an |
|||
authentication request and redirects the user to the Blockstack browser to |
|||
approve the sign in request. The actual Blockstack sign-in dialog depends on |
|||
whether the user already has an existing session in the Blockstack Browser. |
|||
|
|||
<img src="images/kingdom_notin.png" alt=""> |
|||
|
|||
Signing in with an identity is the means by which the user grants the DApp |
|||
access. Access means the DApp can read the user profile and read/write user data |
|||
for the DApp. Data is encrypted at a unique URL on a GAI storage hub. |
|||
|
|||
### Get and put user data to a GAIA Hub |
|||
{:.no_toc} |
|||
|
|||
GAI is the Blockstack data storage hub (https://hub.blockstack.org). Once a user |
|||
authenticates, the application can get and put application data in the user's |
|||
storage. After a user signs in, the `SignedIn.js` code checks the user's GAI |
|||
profile by running the `loadMe()` method. |
|||
|
|||
```js |
|||
loadMe() { |
|||
const options = { decrypt: false } |
|||
this.userSession.getFile(ME_FILENAME, options) |
|||
.then((content) => { |
|||
if(content) { |
|||
const me = JSON.parse(content) |
|||
this.setState({me, redirectToMe: false}) |
|||
} else { |
|||
const me = null |
|||
|
|||
this.setState({me, redirectToMe: true}) |
|||
} |
|||
}) |
|||
} |
|||
``` |
|||
|
|||
The `loadMe()` code uses the Blockstack's `getFile()` method to get the |
|||
specified file from the applications data store. If the users' data store on |
|||
GAIA does not have the data, which is the case for a new users, the Gaia hub |
|||
responds with HTTP `404` code and the `getFile` promise resolves to null. If you |
|||
are using a Chrome Developer Tools with the DApp, you'll see these errors in a |
|||
browser's developer **Console**. |
|||
|
|||
<img src="images/kingdom-errors.png" alt=""> |
|||
|
|||
After a user choses an animal persona and a territory, the user presses **Done** |
|||
and the application stores the user data on GAIA. |
|||
|
|||
```js |
|||
saveMe(me) { |
|||
this.setState({me, savingMe: true}) |
|||
const options = { encrypt: false } |
|||
this.userSession.putFile(ME_FILENAME, JSON.stringify(me), options) |
|||
.finally(() => { |
|||
this.setState({savingMe: false}) |
|||
}) |
|||
} |
|||
``` |
|||
|
|||
The Blockstack <a href="https://blockstack.github.io/blockstack.js/#putfile" |
|||
target="\_blank"><code>putFile()</code></a> stores the data provided in the |
|||
user's DApp data store. You can view the URL for the data store from a user's |
|||
profile. If you tested your Animal Kingdom, you can see this on your profile. |
|||
To see your profile, go to the Blockstack explorer and search for your ID: |
|||
|
|||
<img src="images/explorer.png" alt=""> |
|||
|
|||
In the next section, you extend your Kingdom's configuration. |
|||
|
|||
## Expand your kingdom |
|||
|
|||
Your DApp contains three pages **Animals**, **Territories**, and **Other |
|||
Kingdoms** that are derived from three code elements: |
|||
|
|||
* The `src/constants.js` file defines the application's data profile. |
|||
* The `public/animals` directory which contains images. |
|||
* The `public/territories` directory which contains images. |
|||
|
|||
In this section, you learn how to add another kingdom to the available **Other |
|||
Kingdoms** and how to add another territory. |
|||
|
|||
### Add a territory |
|||
{:.no_toc} |
|||
|
|||
If your application is still running in localhost stop it with a `CTRL-C` from |
|||
your keyboard. |
|||
|
|||
1. Decide what kind of territory to add &emdash; desert, ocean, or city! |
|||
|
|||
This example adds Westeros, a fictional territory. |
|||
|
|||
2. Search for an image to represent your new territory. |
|||
|
|||
Google images is a good place to find <a href="images/westeros.jpg" target="\_blank">a JPEG image of Westeros</a>. |
|||
|
|||
3. Save the image to the `public/territories` folder in your Animal Kingdom project code. |
|||
|
|||
{% include warning.html content="The territory filename must be all lower case and have a <code>.jpg</code> extension. |
|||
For this example, the territory image is saved in the <code>westeros.jpg</code> file." %} |
|||
|
|||
4. Use the `ls` command to confirm your file appears in `territories` directory and has the correct name. |
|||
|
|||
```bash |
|||
ls public/territories/ |
|||
forest.jpg tundra.jpg westeros.jpg |
|||
``` |
|||
|
|||
4. Open the `src/constant.js` file in your favorite editor. |
|||
5. Scroll down to the section that defines the **Territories**. |
|||
|
|||
```js |
|||
export const TERRITORIES = [ |
|||
{ |
|||
id: 'forest', |
|||
name: 'Forest', |
|||
superpower: 'Trees!' |
|||
}, |
|||
{ |
|||
id: 'tundra', |
|||
name: 'Tundra', |
|||
superpower: 'Let it snow!' |
|||
} |
|||
] |
|||
``` |
|||
|
|||
6. Add your new territory. |
|||
|
|||
```js |
|||
export const TERRITORIES = [ |
|||
{ |
|||
id: 'forest', |
|||
name: 'Forest', |
|||
superpower: 'Trees!' |
|||
}, |
|||
{ |
|||
id: 'tundra', |
|||
name: 'Tundra', |
|||
superpower: 'Let it snow!' |
|||
}, |
|||
{ |
|||
id: 'westeros', |
|||
name: 'Westeros', |
|||
superpower: 'The Iron Throne!' |
|||
} |
|||
] |
|||
``` |
|||
7. Save and close the `contstant.js` file. |
|||
8. Back in a terminal window, restart your application. |
|||
|
|||
```bash |
|||
$ npm start |
|||
``` |
|||
9. After the application starts, navigate to the **Territories** page and look for your `Westeros` territory. |
|||
|
|||
<img src="images/kingdom-throne.png" alt=""> |
|||
|
|||
### Add the Blockstack kingdom |
|||
{:.no_toc} |
|||
|
|||
Your Animal Kingdom has only recognizes two **Other Kingdoms**. In this section, |
|||
you add a third, the Blockstack kingdom (`https://animalkingdoms.netlify.com`). |
|||
|
|||
1. Open the `src/constant.js` file in your favorite editor. |
|||
|
|||
On Mac you can use TextEdit or Vim. |
|||
|
|||
2. Scroll down to the section that defines the **Other Kingdoms** |
|||
|
|||
```js |
|||
export const OTHER_KINGDOMS = [ |
|||
{ |
|||
app: 'https://animal-kingdom-1.firebaseapp.com', |
|||
ruler: 'larry.id' |
|||
}, |
|||
{ |
|||
app: 'http://localhost:3001', |
|||
ruler: 'larz.id' |
|||
} |
|||
] |
|||
``` |
|||
|
|||
To add a kingdom, you need its URL and the ID of its owner. |
|||
|
|||
3. Edit the file and add the `https://animalkingdoms.netlify.com` which is owned by `moxiegirl.id.blockstack`. |
|||
|
|||
When you are done the file will look like this. |
|||
|
|||
|
|||
```js |
|||
export const OTHER_KINGDOMS = [ |
|||
{ |
|||
app: 'https://animal-kingdom-1.firebaseapp.com', |
|||
ruler: 'larry.id' |
|||
}, |
|||
{ |
|||
app: 'http://localhost:3001', |
|||
ruler: 'larz.id' |
|||
}, |
|||
{ |
|||
app: 'https://animalkingdoms.netlify.com', |
|||
ruler: 'moxiegirl.id.blockstack' |
|||
} |
|||
] |
|||
``` |
|||
|
|||
4. Save and close the `constants.js` file. |
|||
5. Back in your browser, navigate to the **Other Kingdoms** page. |
|||
|
|||
<img src="images/kingdom-moxiegirl.png" alt=""> |
|||
|
|||
7. Got to the `moxiegirl` kingdom by clicking on her kingdom. |
|||
8. Try adding a subject from Moxiegirl's kingdom to yours. |
|||
|
|||
|
|||
## Go live on the Internet |
|||
|
|||
In this section you use a free Netlify account and a free GitHub account to take |
|||
your kingdom live on the internet. Netlify provides hosting and serverless |
|||
backend services for static websites. GitHub is a code hosting site. |
|||
|
|||
### Run your Kingdom on the internet |
|||
{:.no_toc} |
|||
|
|||
So far, you've been running the application locally. This means you are the only |
|||
person that can use it to create a kingdom. You can make your application |
|||
available to others by hosting it out on the internet. You can do this for free |
|||
with a Netlify account. |
|||
|
|||
Before you begin, you need to build a site that is ready to deploy. |
|||
|
|||
1. In your terminal, press `CTRL-C` on your keyboard to stop your `npm start` build. |
|||
2. Build a website from your code by entering the `npm run build` command: |
|||
|
|||
```bash |
|||
npm run build |
|||
``` |
|||
|
|||
<img src="images/run-build.png" alt=""> |
|||
|
|||
When the command completes, you should have a new `build` subdirectory in your project. |
|||
|
|||
3. Open your project in the Finder. |
|||
4. Locate the newly created `build` subfolder. |
|||
|
|||
<img src="images/finder-build.png" alt=""> |
|||
|
|||
5. <a href="https://app.netlify.com/signup" target="\_blank">Sign up for a free Netlify account</a> |
|||
|
|||
<img src="images/netlify-account.gif" alt=""> |
|||
|
|||
6. In your email inbox, find Netlify's welcome email and verify your account. |
|||
|
|||
<img src="images/netlify-verify.png" alt=""> |
|||
|
|||
7. Log into Netlify and go to the **Overview** page in your browser. |
|||
8. Drag your `build` subdirectory from the Finder into the drop zone in Netlify. |
|||
|
|||
<img src="images/netlify-deploy.gif" alt=""> |
|||
|
|||
After a moment, Netlify builds your code and displays the location of your new webiste. |
|||
|
|||
<img src="images/kingdom-build.png" alt=""> |
|||
|
|||
9. Click on your website name to display the website. |
|||
|
|||
You are prompted to sign into this new site with your Blockstack ID. |
|||
|
|||
10. Click **Sign in with Blockstack**. |
|||
|
|||
After you sign in, your website presents you with this message: |
|||
|
|||
<img src="images/kingdom-failed.png" alt=""> |
|||
|
|||
You get this message because, when you authenticates, your DApp at one URL |
|||
requested a resource (an identity) from another DApp, the Blockstack |
|||
Browser. A request for a resource outside of the origin (your new website) |
|||
is called as a _cross-origin request_(CORs). Getting data in this manner can |
|||
be risky, so you must configure your website security to allow interactions |
|||
across origins. |
|||
|
|||
<div class="uk-inline"> |
|||
<button class="uk-button uk-button-primary" enter="button">Read a bit more, fun, explanation of CORS</button> |
|||
<div uk-dropdown> |
|||
You can think of CORS interactions as an apartment building with Security. |
|||
For example, if you need to borrow a ladder, you could ask a neighbor in |
|||
your building who has one. Security would likely not have a problem with |
|||
this request (i.e., same-origin, your building). If you needed a particular |
|||
tool, however, and you ordered it delivered from an online hardware store |
|||
(i.e., cross-origin, another site), Security may request identificatin |
|||
before allowing the delivery man into the apartment building. |
|||
<br> |
|||
Credit: <a href="https://www.codecademy.com/articles/what-is-cors" target="\_blank">Codecademy</a> |
|||
</div> |
|||
</div> |
|||
|
|||
The way you configure CORs depends on which company is serving your website. |
|||
You are using Netlify for this example. |
|||
|
|||
11. Locate the `cors/_headers` and `cors/_redirects` in your project. |
|||
|
|||
You can use the Finder or the `ls` command. |
|||
|
|||
|
|||
12. Copy them into your `public` directory. |
|||
|
|||
To copy them with the `ls` command, enter the following in the root of the `animal-kingdom-master` project. |
|||
|
|||
```bash |
|||
cp cors/_headers public |
|||
cp cors/_redirects public |
|||
``` |
|||
|
|||
The name of each file, with the underscore, is essential. |
|||
|
|||
13. Make sure you are in the `animal-kingdom-master` directory, run the `npm run build` command again. |
|||
15. Drag the `build` file back into the Netlify drop zone. |
|||
|
|||
After a moment, Netlify publishes your site. Check the published location, it may have changed. |
|||
|
|||
16. Click on the link and log into your Animal Kingdom. |
|||
17. Recreate your animal person and territory. |
|||
|
|||
The Animal Kingdom is identified by its location on the Internet, remember? |
|||
So, the animal kingdom you created on your local workstation is different |
|||
than the one you create on Netlify. |
|||
|
|||
### Add your Kingdom to our Clan |
|||
{:.no_toc} |
|||
|
|||
At this point, your kingdom is isolated. If you know another kingdom, you can |
|||
add subjects from that kingdom but other kingdoms can access your subjects. In |
|||
this section, you use a free GitHub account to add your kingdom to the |
|||
Blockstack kingdom. |
|||
|
|||
1. If you have a GitHub account, go to step 2 otherwise go to GitHub <a href="https://github.com/" target="\_blank">site and create a new account</a>. |
|||
2. Go to the <a href="https://github.com/blockstack/animal-kingdom/issues" target="\_blank">https://github.com/blockstack/animal-kingdom/issues</a> repository on Github. |
|||
2. Click **New Issue**. |
|||
|
|||
The new issue dialog appears. |
|||
|
|||
3. Fill out the issue with the URL from Netlify and your Blockstack id. |
|||
|
|||
When you are done, your issue will look like the following: |
|||
|
|||
<img src="images/kingdom-issue.png" alt=""> |
|||
|
|||
4. Press **Submit new issue**. |
|||
|
|||
The Blockstack team will add your Netlify kingdom to ours. When we do that, we will notify you on the issue and you'll also get an email. |
|||
|
|||
5. When you receive the email, login into the Blockstack Animal kingdom to see your kingdom under **Other Kingdoms**. |
|||
|
|||
|
|||
## Next Steps |
|||
{:.no_toc} |
|||
|
|||
Well, you have produced your very first DApp. Congratulations! If you have a |
|||
twitter account, why not tell some folks? |
|||
|
|||
<a href="https://twitter.com/share?ref_src=twsrc%5Etfw" |
|||
class="twitter-share-button" data-size="large" data-text="I just built a DApp |
|||
using @blockstacks's Zero to DApp tutorial! " data-hashtags="blockstack, |
|||
blockchain, blockchainnopain, blockchainnopainblockstack" |
|||
data-show-count="false">Tweet your work!</a><script async |
|||
src="https://platform.twitter.com/widgets.js" charset="utf-8"></script> | |
|||
|
|||
In the next section, you submit your [DApp to our listings on App.co](#). |
|||
@ -0,0 +1,153 @@ |
|||
--- |
|||
layout: learn |
|||
permalink: /:collection/:path.html |
|||
--- |
|||
# 4 - Participate in App Mining |
|||
{:.no_toc} |
|||
|
|||
**Zero to DAPP 4 of 4** |
|||
|
|||
On this page, you learn about application mining as a funding source for your |
|||
new DApp efforts. You'll submit your sample Animal Kingdom to to App.co, the |
|||
Universal DApp store and earn a t-shirt. You'll also learn about other ways |
|||
Blockstack helps your development efforts. This page contains the following topics: |
|||
|
|||
* TOC |
|||
{:toc} |
|||
|
|||
|
|||
<div class="uk-card uk-card-default uk-card-body"> |
|||
<h5>Can you skip this page?</h5> |
|||
<p>This is the final page, so please don't skip it. You don't miss your chance to get this cool t-shirt! |
|||
</p> |
|||
<p><img class="uk-align-center" src="images/tshirt-blank.png" alt=""></p> |
|||
</div> |
|||
|
|||
|
|||
## Funding your DApp with application mining |
|||
|
|||
App.co accepts submissions from all decentralized protocols such as Ethereum, |
|||
Blockstack, and many others. Only applications that integrate Blockstack |
|||
authentication, use GAI storage, and which are accessible to review can |
|||
participate in application mining. |
|||
|
|||
{% include intro-appmining.md %} |
|||
|
|||
|
|||
{% include payout-appmining.md %} |
|||
|
|||
You area going to make a practice submission using the Animal Kingdom sample. |
|||
|
|||
|
|||
## Submit your Animal Kingdom to App.co |
|||
|
|||
In this section, you submit your Animal Kingdom to the **Blockstack Sample |
|||
Application** on App.co. Apps in this category aren't eligible for app mining, |
|||
but they do earn a limited edition a Zero to DApp t-shirt. Only submit your |
|||
sample application if you have deployed the application on the internet. This |
|||
allows us to confirm you completed the tutorial. |
|||
|
|||
{% include note.html content="You can submit more |
|||
than one example, only your first submission receives a t-shirt." %} |
|||
|
|||
1. In your browser, navigate to <a href="https://app.co/" target="\_blank">the App.co website</a>. |
|||
2. Choose **Add your app** option from the menu. |
|||
|
|||
The system opens the submit your App form. |
|||
|
|||
<img src="images/submit-app.png" alt=""> |
|||
|
|||
3. Complete the following fields. |
|||
|
|||
<table class="uk-table uk-table-small"> |
|||
<tr> |
|||
<th><strong>Field</strong></th> |
|||
<th>Description</th> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Dapp Name</strong></td> |
|||
<td>Name of your sample. Animal Kingdom or, if you renamed it, the name you gave your application.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Short description</strong></td> |
|||
<td>Describe your application. </td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Webiste</strong></td> |
|||
<td>The URL of the website where you deployed your application. </td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Contact Email</strong></td> |
|||
<td>A valid email address. This is the email where we will send you instructions for getting your Zero to Dapp t-shirt.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Image URL</strong></td> |
|||
<td>You can leave this blank for a sample application.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Open Source URL</strong></td> |
|||
<td>You can leave this blank for a sample application. </td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Twitter Handle</strong></td> |
|||
<td>Optionally enter a Twitter handle if you have one.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Registration is open to all users</strong></td> |
|||
<td>Leave this unchecked.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Category</strong></td> |
|||
<td>Sample Blockstack Apps &mdash; make sure you choose this category.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Blockchain</strong></td> |
|||
<td>Leave this as is/</td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Storage</strong></td> |
|||
<td>Choose Gaia.</td> |
|||
</tr> |
|||
<tr> |
|||
<td><strong>Authentication</strong></td> |
|||
<td>Choose Blockstack</td> |
|||
</tr> |
|||
</table> |
|||
|
|||
4. Press the **Submit** button. |
|||
|
|||
The Blockstack team will email you information about how to obtain your |
|||
limited edition t-shirt at our store. |
|||
|
|||
|
|||
## Marketing your DApp |
|||
|
|||
Blockstack reviews each submission to app mining. Through this contact, Blockstack helps |
|||
developers refine business models and facilitating interactions with investors. |
|||
Two areas that Blockstack assists are pre-funding and pitching. |
|||
|
|||
* **Pre-funding.** Directed toward developers that have a proof of concept of either a blockchain application or an integration with Blockstack’s techology. Blockstack helps with sourcing of developers and designers. We can also help with direct access to our core team members that can help you refine or optimize your product. |
|||
* **Pitching investors.** Blockstack can help you with access to an extensive investor community. Prior to arranging meetings we can give you resources to refine and craft your pitch for the blockchain market. |
|||
|
|||
In addition to app mining, Blockstack offers both a community reward program. |
|||
Community rewards give users the ability to earn tokens for accomplishing tasks. |
|||
For example, some of the latest ways user can earn money include: |
|||
|
|||
- Organize a Blockstack Hackathon |
|||
- Message of the founders of `stealthy.im` with feedback and ideas |
|||
- Use graphite to write a message about the problems decentralization solves |
|||
|
|||
Learn more about <a href="https://blockstack.org/blog/blockstack-community-rewards-program/" target="\_blank">participating in community rewards</a>. |
|||
|
|||
## Congratulations |
|||
{:.no_toc} |
|||
|
|||
You've completed the Zero to DApp tutorial and have joined the growing |
|||
DApp developer community on Blockstack. We hope you've taken the extra |
|||
step of submitting your Animal Kingdom application to the App.co site. |
|||
|
|||
<a href="https://twitter.com/share?ref_src=twsrc%5Etfw" |
|||
class="twitter-share-button" data-size="large" data-text="I'm the rule of my Animal Kingdom. Just submitted my Blockstack sample DApp to App.co @TheDappStore! Dapp on people." data-hashtags="blockstack, |
|||
blockchain, blockchainnopain, blockchainnopainblockstack" |
|||
data-show-count="true">Tweet your work!</a><script async |
|||
src="https://platform.twitter.com/widgets.js" charset="utf-8"></script> |
|||
@ -0,0 +1,49 @@ |
|||
To create an initial Blockstack ID, do the following: |
|||
|
|||
1. Open the <a href="https://browser.blockstack.org/sign-up?redirect=%2F" target="\_blank">Blockstack web application in your browser</a>. |
|||
|
|||
The application prompts you for an email address. |
|||
|
|||
 |
|||
|
|||
Blockstack uses this email address to send you recovery information. |
|||
|
|||
2. Enter an email address and press **Next**. |
|||
|
|||
The application prompts you to enter a password. Blockstack users this |
|||
password to encrypt your recovery code. You must record and save this |
|||
initial password. |
|||
|
|||
**NOTE**:The Blockstack team cannot restore your password for you. |
|||
|
|||
3. Enter a password, confirm it, and press **Next**. |
|||
|
|||
 |
|||
|
|||
The browser prompts you to register a unique username in the `id.blockstack` |
|||
domain. This is your identity in the decentralized internet. The format of the id |
|||
is: |
|||
|
|||
_`username`_`.id.blockstack` |
|||
|
|||
You'll use this initial ID to access the Blockstack Browser. |
|||
|
|||
3. Enter a unique username and press **Check Availability**. |
|||
|
|||
 |
|||
|
|||
When you choose an ID that is available, the system responds with the following: |
|||
|
|||
 |
|||
|
|||
4. Press **Continue**. |
|||
|
|||
The system prompts you to save your **recovery code**. A recovery code is a |
|||
sequence of words. These words allow you to recover an `id.blockstack` |
|||
that you've created. You should store the words along with their order, for |
|||
example, `#1 applied` and so forth. |
|||
|
|||
5. Click **I have written down all the words** when you are done. |
|||
|
|||
The system places you in the Blockstack browser. You can begin exploring and |
|||
using Dapps. |
|||
@ -0,0 +1,13 @@ |
|||
Traditionally the term _mining_ in cryptocurrency refers to the process of |
|||
contributing compute resources to the network and earning a reward. On the |
|||
Blockstack network, however, instead of just mining through computation, |
|||
developers can mine by contributing apps to the ecosystem and making |
|||
applications the community wants. |
|||
|
|||
 |
|||
|
|||
Founders that build apps using Blockstack developer tools like Blockstack Auth |
|||
get paid each month, in amounts proportional to that month’s app quality |
|||
ranking. Blockstack PBC, in cooperation with App.co, currently administers the |
|||
payouts. A set of independent _App reviewers_ determines the monthly ranking |
|||
during the pilot phase. |
|||
@ -0,0 +1,12 @@ |
|||
For each app mining cohort, there is determined a “pot” of total earnings that will |
|||
get paid to apps. For the Alpha run, Blockstack paid a total of $25,000 USD. Starting in |
|||
December 2018, Blockstack will pay $100,000 USD and the awards will be paid out in Bitcoin. |
|||
|
|||
The top app gets paid 20% of the total pot. So, for a pot of $100k, the top app |
|||
receives $20,000 USD. The next app gets paid 20% of the remaining pot. The |
|||
remaining pot is $80k, and 20% of that is $16,000. This process continues until |
|||
every app has been paid. |
|||
|
|||
Here is a chart that visualizes the decay in rewards, depending on rank: |
|||
|
|||
 |
|||
@ -0,0 +1,15 @@ |
|||
In 2017 Blockstack announced the Blockstack Signature Fund. The Signature Fund |
|||
is aimed at growing an ecosystem of decentralized applications on Blockstack. |
|||
The fund releases funds through a Signature Bounty program. This is a global |
|||
bounty program using a contest model. Teams from all over the world submit |
|||
products and a set of judges determine who wins the prize for the best product. |
|||
|
|||
In addition to the bounty program, Blockstack supports an application mining |
|||
program. This is an early stage program for developers. In this program, |
|||
application developers register their application on App.co. Then, each month, |
|||
application developers get paid each month depending on their application |
|||
quality ranking. The ranking is determined by a set of application reviewers. |
|||
|
|||
Application mining differs from the venture model or the app studio model |
|||
because the rewards are in cryptocurrency. Blockstack PBC administrates both the |
|||
review and delivery of these monthly payments. |
|||
Loading…
Reference in new issue