diff --git a/Gemfile b/Gemfile index 4a90445c..827cdc36 100644 --- a/Gemfile +++ b/Gemfile @@ -9,7 +9,7 @@ ruby RUBY_VERSION # # This will help ensure the proper Jekyll version is running. # Happy Jekylling! -gem "jekyll", "3.5" +gem "jekyll", "3.6.3" # This is the default theme for new Jekyll sites. You may change this to anything you like. # gem "minima", "~> 2.0" diff --git a/Gemfile.lock b/Gemfile.lock index 57056118..9eb9db3c 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -13,16 +13,16 @@ GEM ffi (1.9.25) forwardable-extended (2.6.0) http_parser.rb (0.6.0) - jekyll (3.5.0) + jekyll (3.6.3) addressable (~> 2.4) colorator (~> 1.0) jekyll-sass-converter (~> 1.0) jekyll-watch (~> 1.1) - kramdown (~> 1.3) + kramdown (~> 1.14) liquid (~> 4.0) mercenary (~> 0.3.3) pathutil (~> 0.9) - rouge (~> 1.7) + rouge (>= 1.7, < 3) safe_yaml (~> 1.0) jekyll-avatar (0.6.0) jekyll (~> 3.0) @@ -43,7 +43,7 @@ GEM jekyll-watch (1.5.1) listen (~> 3.0) kramdown (1.17.0) - liquid (4.0.0) + liquid (4.0.1) listen (3.1.5) rb-fsevent (~> 0.9, >= 0.9.4) rb-inotify (~> 0.9, >= 0.9.7) @@ -58,10 +58,10 @@ GEM rb-fsevent (0.10.3) rb-inotify (0.9.10) ffi (>= 0.5.0, < 2) - rouge (1.11.1) + rouge (2.2.1) ruby_dep (1.5.0) safe_yaml (1.0.4) - sass (3.5.7) + sass (3.6.0) sass-listen (~> 4.0.0) sass-listen (4.0.0) rb-fsevent (~> 0.9, >= 0.9.4) @@ -74,7 +74,7 @@ PLATFORMS ruby DEPENDENCIES - jekyll (= 3.5) + jekyll (= 3.6.3) jekyll-avatar jekyll-feed (~> 0.6) jekyll-gist diff --git a/README.md b/README.md index cef5c5f1..f8251f74 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,9 @@ -## Docs site +# README for the documentation site + + +## Building after a fork + +## Run locally To run locally: @@ -34,3 +39,7 @@ To deploy to Netlify: ``` git push -f origin ``` + +# Writing content + +## Constructing links diff --git a/_common/mining_faq.md b/_common/mining_faq.md new file mode 100644 index 00000000..a374c893 --- /dev/null +++ b/_common/mining_faq.md @@ -0,0 +1,5 @@ +--- +layout: externalurl +redirect_url: https://app.co/mining#faq +title: "Mining FAQ" +--- diff --git a/_config.yml b/_config.yml index 3f779cde..2e0e1ccd 100644 --- a/_config.yml +++ b/_config.yml @@ -151,6 +151,9 @@ collections: core: output: true basepath: "blockstack/blockstack-core/blob/master/docs" + develop: + output: true + basepath: "moxiegirl/docs.blockstack" storage: output: true basepath: "blockstack/gaia/blob/master/docs" diff --git a/_data/navigation_learn.yml b/_data/navigation_learn.yml index bb9603b3..86216560 100644 --- a/_data/navigation_learn.yml +++ b/_data/navigation_learn.yml @@ -1,3 +1,7 @@ +- title: Introduction +- docs: + - develop/dapp_principles + - title: Try a tutorial docs: - browser/hello-blockstack @@ -9,7 +13,14 @@ - android/tutorial - ios/tutorial +- title: Application mining + docs: + - develop/mining_intro + - develop/mining_enroll + - title: Reference docs: - core/faq_developer + - common/mining_faq - common/javascript_ref + - common/core_ref diff --git a/_develop/dapp_principles.md b/_develop/dapp_principles.md new file mode 100644 index 00000000..3b717c8e --- /dev/null +++ b/_develop/dapp_principles.md @@ -0,0 +1,127 @@ +--- +layout: learn +permalink: /:collection/:path.html +--- +# Principles of Blockstack applications +{:.no_toc} + +There are as many perspectives on what makes a decentralized app (DApp) as there +are DApp developers. This section defines the principles that Blockstack +advocates for DApps operating within its platform. + +* TOC +{:toc} + + +## Blockstack DApp principles + +An application is considered a Blockstack DApp if it adheres to three +principles. + +### I. Users own their data + +DApps do not store or replicate user data. Users own their application +data independent of and *outside of* the application. A Blockstack application +is only considered decentralized if its users control where their data is +hosted and can prove that they created the data. + +Blockstack applications meet this principle if they use the Gaia storage system. +Users may sign and/or encrypt their data in Gaia end-to-end. All files in Gaia +are addressed by a user identifier, an application's hostname, and a filename. +Through Gaia, users can prove data ownership and restrict access. + +In the future, users will be able to choose on an app-by-app basis which Gaia +hub serves their application data. + +### II. Users own their identities + +Users are the sole administer of their own independent and unique +identifiers. Within an applications, users must be distinguishable by unique +identifiers. The DApp cannot mask or take away a user's identifier, and a user +must be able to bind their identifier to the data they create. + +Blockstack DApps anticipate that each user can own one or more IDs. In turn, +these IDs are owned by a private key under the user's control. The IDs are +acquired through the Blockstack naming system. First time users that log into +the Blockstack application get a free `blockstack.id` in the Blockstack namespace. + +Blockstack IDs are replicated to all peers via a blockchain, this means +Blockstack cannot hide IDs. Blockstack IDs each have a public key assigned to +them via the blockchain records that encode their operational history. This +public key allows users to bind data to their Blockstack IDs through +cryptographic signatures. + +### III. Users have free choice of clients + +Identities and _data_ are application independent. An application cannot be +considered a DApp unless it allows users to interact with their identities and +data such that the user can later do so via a different DApp. + +For example, a user that creates data in client 'X' must be able access that +data from a different client, 'Y', provided the client allows compatible +mechanisms. Ultimately, the user has the freedom to write their own client that +interacts with their own data. + +Blockstack's APIs and SDKs make it easy to build applications that adhere to +this principle. Existing Blockstack applications have this property today simply +because they don't have any irreplaceable server-side logic. + +In the future, Blockstack applications must continue to meet the first two +principles but need not meet this one. For example, an application could +encrypt data in-transit between the application's client and the user's chosen +storage provider. Unless the app divulges the encryption key to the user, then +the user does not have free choice of clients; they can only use clients that +the app's servers choose to interact with. + +## Non-Principles + +You'll notice the Blockstack principles avoid adherence to a particular network +topology or architecture. Many DApps have defining characteristics that are +implementation-specific rather than expressions of overall DApp design goals. +These aspects are mentioned here as specific non-goals of Blockstack +applications. + +### DApps have smart contracts + +Decentralized apps pre-date blockchains and smart contracts, and even today +there are popular DApps that do not need them. Examples include pre-Microsoft +Skype (which was peer-topeer), Mastadon, IRC, and email. + +Another word for "smart contract" is "replicated state machine." Some DApps +need each peer to execute the same sequence of operations in order to fulfill +their business needs (in which case a smart contract would be appropriate), +but many do not. + +Blockstack DApps do not use smart contracts at all. + +### DApps have tokens and/or non-fungible assets + +Similar to smart contracts, DApps pre-date tokens and non-fungible assets. +While having a crypto token or asset can help incentivize DApp deployment and +usage, they are not strictly necessary for their operation. + +### DApps use a blockchain + +Blockchains are a new tool for DApp developers to help coordinate peers, but +they are just that -- a tool. Sometimes blockchains are the right tool for the +job, and sometimes they are not. + + +## Dapps serve users + +Fundamentally, DApps should serve users by preserving user autonomy. Developers +should not profit from abusive features or neglectful designs. +Blockstack principles seek to prevent developers from profiting by either (a) building +abusive features into DApps like ad networks, or (b) neglecting users by failing +to build vital safety features like shadowbans. + +Because Blockstack applications allow users to own their identity and data and +gives them free choice of clients, any user can simply stop or avoid using bad DApps +with near-zero switching cost. + +This isn't to say that DApps can't be profitable. DApps can still make money for +their developers, such as by offering content subscriptions or paid-for add-ons. +They can broker with third parties on behalf of their users to watch ads or +share data in exchange for tokens. diff --git a/_develop/images/decaying.png b/_develop/images/decaying.png new file mode 100644 index 00000000..7d2a5d51 Binary files /dev/null and b/_develop/images/decaying.png differ diff --git a/_develop/images/mining-image.png b/_develop/images/mining-image.png new file mode 100644 index 00000000..1e27446e Binary files /dev/null and b/_develop/images/mining-image.png differ diff --git a/_develop/images/model.png b/_develop/images/model.png new file mode 100644 index 00000000..93f22c96 Binary files /dev/null and b/_develop/images/model.png differ diff --git a/_develop/mining_enroll.md b/_develop/mining_enroll.md new file mode 100644 index 00000000..98068d7a --- /dev/null +++ b/_develop/mining_enroll.md @@ -0,0 +1,31 @@ +--- +layout: learn +permalink: /:collection/:path.html +--- +# How to enroll + +Application mining pays developers for building decentralized applications +(Dapps). Enrolling in app mining also makes your application eligible for +rewards. + +After you enroll, Blockstack verifies your information and your Dapp appears in +the list of registered apps. You must enroll by the end of each month to be +eligible for the following month. + +To apply, do the following: + +1. Integrate Blockstack Auth into your app. + +2. Add your app to App.co. + + Make sure you choose Blockstack from the Authentication list on the form. + +3. Email with the domain you used to register for your app. + + Blockstack will respond via email with a set of verification materials. + +4. Fill out and return the completed verification materials. + + Be sure you provide us with the BTC address for receipt of mining and rewards funds. + +Once your enrollment is received, you appear in the enrollment list. For more information, see the frequently asked questions [on the App.co site](https://app.co/mining#faq). diff --git a/_develop/mining_intro.md b/_develop/mining_intro.md new file mode 100644 index 00000000..400e82b1 --- /dev/null +++ b/_develop/mining_intro.md @@ -0,0 +1,115 @@ +--- +layout: learn +permalink: /:collection/:path.html +--- +# Understand app mining + +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. + +![](images/mining-image.png) + +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. + + +## How apps are reviewed + +Blockstack worked with a team of Ph.D. game theorist and economists from +Princeton and NYU to put together a ranking algorithm which is fair and +resistant to abuse. Blockstack partnered with two different third-party +reviewers, Product Hunt and Democracy.earth. These reviewers are independent, +and generally rely on their own proprietary data and insights to generate +rankings. + +### Product Hunt + +Product Hunt is the place to find the best new products in tech. They have a +massive trove of user data (upvotes, comments, etc), that they use for ranking. +Product Hunt comes up with two different scores for each app — a “community” +score and a “team” score. + +Their community score is determined only by the number of upvotes an app +received on Product Hunt, relative to other apps that are registered. For +example, if an app got more upvotes than any other app in a cohort, their +community score would be 100. If a different app got 60% as many upvotes, they’d +get a score of 60. + +Their team score is determined by internal team members conducting reviews on +different aspects of an app. They judge based on a few criteria, like execution, +uniqueness, and desirability. Each app gets ranked 1-10 on each criterion, and +their final score is the average of each criterion. Finally, this average is +multiplied by 10, so the highest score you can get is 100. + +Once each app has a community and team score, Blockstack converts these scores into +_z-scores_, more about z-scores below. + +### Democracy Earth + +Democracy Earth is a platform for borderless peer-to-peer democracy. They’ve +built a platform that anyone can use to gather votes in a trust-less, +decentralized way. + +Democracy Earth has built a platform for Stacks token holders to vote on how +apps should be ranked. Each token holder gets a certain number of votes, and +they can distribute those votes however they want. It’s possible to give all of +your votes to a single app, and you can also “downvote” an app with one of your +votes. + +After a voting period, each app has a certain amount of upvotes and downvotes. +First, Blockstack calculates the percentage of total votes that are upvotes. If +you got 90 upvotes and 10 downvotes, you’d get a “likability score” of 90. +Secondly, Blockstack calculates a “traction score”, which ranks how many total +votes (including downvotes) an app received, relative to other apps. + +## Reaching the final scores + +Once the reviewer-partners generate reviews, each app has 4 raw scores between 0 +and 100 for the following: + +* Product Hunt community score +* Product Hunt team score +* Democracy Earth likability score +* Democracy Earth traction score + +First Blockstack's determine a ‘z-score’ for each ranking category community, +team, likability, and traction. This is a statistical technique to account for +different distributions of scores within categories. Second, Blockstack computes +the average and standard deviation of each category. Finally, for each app’s +score in that category, Blockstack determines how many standard deviations it is +away from the average score in that category. + +For example, let’s say a category has an average score of 60, with a standard +deviation of 15. A score of 90 would get a z-score of 2, because it’s 2 standard +deviations higher than the average. + +Once each app has a calculated a z-score in every category, the average of those +4 z-scores results in a final number. A higher number is better than a lower +one, and so apps are ranked from highest to lowest. + +## Determining how much an app is paid + +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: + +![](images/decaying.png) + +This first release of App Mining uses the initial version of our ranking and +payout mechanism. Blockstack has taken care to be thoughtful and fair, but +things may change as we learn more and get feedback from the community. Please +let us know what you think by commenting in our forum or by emailing us at ! diff --git a/_develop/mining_review.md b/_develop/mining_review.md new file mode 100644 index 00000000..89221283 --- /dev/null +++ b/_develop/mining_review.md @@ -0,0 +1,38 @@ +--- +layout: learn +permalink: /:collection/:path.html +--- +# App reviewer instructions + +Reviewers submit their app rankings to Blockstack every month. The first day of +the month Blockstack will email reviewers a spreadsheet on which to record rankings. + +To submit app rankings, please complete the following steps: + +1. Download the spreadsheet for that month. + + The spreadsheet is sent to the email address Blocksack has on file for you. The sheet lists all apps eligible for ranking. + +2. Record your rankings on the spreadsheet. + + Place a the rank value in the **Ranking** column next to each app you would + like to rank. You can rank only those apps you want and omit ranking others. + Rank each application numerically where 1 (one) is the highest. For reviewer + partners, rank apps for the month using the methodology of your + organization. + + Please avoid modifying the spreadsheet in apart from adding your rankings. + The `App ID` column, in particular, must be preserved to process your rankings + accurately. + +3. Return your rankings by the 15th of each month to . + + {% include important.html content="Blockstack must receive your rankings by the 15th of the month or they won't be considered!" %} + +4. Attach your completed spreadsheet to your return email. + + Include in the email a brief explanation summarizing your methodology or + thoughts when ranking. Please mention any app you want to highlight for the + month. + +After receiving the rankings from the reviews, Blockstack will calculated each applications final z-scores. diff --git a/_includes/footer.html b/_includes/footer.html index 0fab5536..90ded464 100644 --- a/_includes/footer.html +++ b/_includes/footer.html @@ -25,7 +25,7 @@ {% include social-networks.html %} --> -
Blockstack® and Stacks™ are trademarks of Blockstack Public Benefit Corp. © {{ page.date | date: "%Y" }} {{ site.footer.copyright }}
+
Blockstack® and Stacks™ are trademarks of Blockstack Public Benefit Corp.
© {{ page.date | date: "%Y" }} {{ site.footer.copyright }}
diff --git a/_includes/important.html b/_includes/important.html new file mode 100644 index 00000000..f7dcd2c8 --- /dev/null +++ b/_includes/important.html @@ -0,0 +1 @@ +
Important: {{include.content}}
diff --git a/_includes/note.html b/_includes/note.html new file mode 100644 index 00000000..6ea620fe --- /dev/null +++ b/_includes/note.html @@ -0,0 +1 @@ +
Note: {{include.content}}
diff --git a/_includes/warning.html b/_includes/warning.html new file mode 100644 index 00000000..de79383d --- /dev/null +++ b/_includes/warning.html @@ -0,0 +1 @@ +
Warning: {{include.content}}
diff --git a/_layouts/auth.html b/_layouts/auth.html index 85fd20fd..34e84a48 100644 --- a/_layouts/auth.html +++ b/_layouts/auth.html @@ -50,6 +50,7 @@ layout: default
{{ content }} {% include share.html %} + {% include footer.html %}
diff --git a/_layouts/core.html b/_layouts/core.html index cac8a56b..fa06b033 100644 --- a/_layouts/core.html +++ b/_layouts/core.html @@ -50,6 +50,7 @@ layout: default
{{ content }} {% include share.html %} + {% include footer.html %}
diff --git a/_layouts/default.html b/_layouts/default.html index 3faffbb7..f4a819a2 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -15,10 +15,6 @@ {% include offcanvas.html %} - {% if page.layout != 'doc' %} - {% include footer.html %} - {% endif %} - {% if page.hero %} {% include search-hero.html %} {% else %} diff --git a/_layouts/evaluate.html b/_layouts/evaluate.html index dde91ea3..15d200c0 100644 --- a/_layouts/evaluate.html +++ b/_layouts/evaluate.html @@ -50,6 +50,7 @@ layout: default
{{ content }} {% include share.html %} + {% include footer.html %}
diff --git a/_layouts/gaia.html b/_layouts/gaia.html index cb080533..7df0d3c0 100644 --- a/_layouts/gaia.html +++ b/_layouts/gaia.html @@ -45,6 +45,7 @@ layout: default
{{ content }} {% include share.html %} + {% include footer.html %}
diff --git a/_layouts/home.html b/_layouts/home.html index 5e722e3b..90643078 100644 --- a/_layouts/home.html +++ b/_layouts/home.html @@ -100,3 +100,5 @@ layout: default {% endif %} + +{% include footer.html %} diff --git a/_layouts/learn.html b/_layouts/learn.html index 933ee1dc..6cf681e4 100644 --- a/_layouts/learn.html +++ b/_layouts/learn.html @@ -50,6 +50,7 @@ layout: default
{{ content }} {% include share.html %} + {% include footer.html %}
diff --git a/_layouts/post.html b/_layouts/post.html index d4a98cde..cb4c9590 100644 --- a/_layouts/post.html +++ b/_layouts/post.html @@ -15,6 +15,7 @@ layout: default
{{ content }} {% include share.html %} + {% include footer.html %}
diff --git a/_layouts/usenew.html b/_layouts/usenew.html index 4fdf3714..29115ae8 100644 --- a/_layouts/usenew.html +++ b/_layouts/usenew.html @@ -50,6 +50,7 @@ layout: default
{{ content }} {% include share.html %} + {% include footer.html %}
diff --git a/_site/2017/05/25/post63.html b/_site/2017/05/25/post63.html index c83b48e7..e8958834 100644 --- a/_site/2017/05/25/post63.html +++ b/_site/2017/05/25/post63.html @@ -7,7 +7,7 @@ Site tags | Blockstack - + @@ -19,7 +19,7 @@ +{"url":"https://docs.blockstack.org/2017/05/25/post63.html","headline":"Site tags","dateModified":"2017-05-25T00:00:00-07:00","datePublished":"2017-05-25T00:00:00-07:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://docs.blockstack.org/2017/05/25/post63.html"},"author":{"@type":"Person","name":"John Black"},"description":"Site tags","@type":"BlogPosting","@context":"http://schema.org"} @@ -161,7 +161,7 @@

Example Of Code Block

In accumsan lacus ac neque maximus dictum. Phasellus eleifend leo id mattis bibendum. Curabitur et purus turpis. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae;

-
<head>
+
<head>
   <meta charset="utf-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -169,8 +169,7 @@
   <link rel="shortcut icon" type="image/png" href="/assets/img/favicon.png" >
   <script src="/assets/js/main.js"></script>
 </head>
-

-

+

Text and Quote

Cras at dolor eget urna varius faucibus tempus in elit. Cras a dui imperdiet, tempus metus quis, pharetra turpis. Phasellus at massa sit amet ante semper fermentum sed eget lectus. Quisque id dictum magna turpis.

@@ -187,6 +186,71 @@ +
+
+ + +
Blockstack® and Stacks™ are trademarks of Blockstack Public Benefit Corp.
© 2017 Blockstack Public Benefits Corp.
+ +
+
+
@@ -278,74 +342,6 @@ -
-
- - -
Blockstack® and Stacks™ are trademarks of Blockstack Public Benefit Corp. © 2017 Blockstack Public Benefits Corp.
- -
-
- - - - +{"url":"https://docs.blockstack.org/android/tutorial.html","headline":"Android SDK Tutorial (Pre-release)","dateModified":"2018-10-26T14:02:20-07:00","datePublished":"2018-10-26T14:02:20-07:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://docs.blockstack.org/android/tutorial.html"},"author":{"@type":"Person","name":"Blockstack"},"description":"Android SDK Tutorial (Pre-release)","@type":"BlogPosting","@context":"http://schema.org"} @@ -116,6 +116,23 @@ +
Introduction
+ +
    + +
+ + + + +
Try a tutorial
    @@ -155,6 +172,23 @@
+
Application mining
+ + + +
Reference
@@ -195,13 +239,13 @@ -