Collection type shares the same identifier as another type, it will lead to data corruption for the user. In the future, the Blockstack platform will enforce unique collection names. " %}
+ {% include warning.html content="While you must specify a unique identifier, the Blockstack platform does not currently enforce uniqueness. If your Collection type shares the same identifier as another type, it will lead to data corruption for the user. In the future, the Blockstack platform will enforce unique collection names. " %}
5. Define a static `schema` constant.
This is your type's schema.
- ```js
- static schema = {
- identifier: String,
- firstName: String,
- lastName: String,
- blockstackID: String,
- email: String,
- website: String,
- address: String,
- telephone: String,
- organization: String
- }
- ```
+ ```js
+ static schema = {
+ identifier: String,
+ firstName: String,
+ lastName: String,
+ blockstackID: String,
+ email: String,
+ website: String,
+ address: String,
+ telephone: String,
+ organization: String
+ }
+ ```
6. Determine if you need to set the `singleFile` storage flag.
- By default, the `singleFile` flag is false. This setting causes every record in a collection to store in Gaia as a separate file. The default works well for larger types that describe data such as documents or photos. If your `Collection` type only has a few fields and is not expected to have a large number of records, set the `singleFile` data format flag to `true`.
+ By default, the `singleFile` flag is false. This setting causes every record in a collection to store in Gaia as a separate file. The default works well for larger types that describe data such as documents or photos. If your `Collection` type only has a few fields and is not expected to have a large number of records, set the `singleFile` data format flag to `true`.
- ```js
- static singleFile = true
- ```
+ ```js
+ static singleFile = true
+ ```
7. Define the `fromObject` and `fromData` serializaiton methods.
- These methods serialize and deserialize your `Collection` type. You can use any serialization method you want. Data encryption is handled automatically by the parent `Collection` class, so you *should not* perform any additional encryption.
+ These methods serialize and deserialize your `Collection` type. You can use any serialization method you want. Data encryption is handled automatically by the parent `Collection` class, so you _should not_ perform any additional encryption.
In the following example code, data is converted to JSON string for storage.
- ```js
- static fromObject(object: object) {
- // Create from plain Javascript object
- return new Contact(object)
- }
- static fromData(data: string) {
- // Deserialize JSON data
- return new Contact(JSON.parse(data))
- }
-
- serialize() {
- // Serialize to JSON string
- return JSON.stringify(this.attrs)
- }
- ```
+ ```js
+ static fromObject(object: object) {
+ // Create from plain Javascript object
+ return new Contact(object)
+ }
+ static fromData(data: string) {
+ // Deserialize JSON data
+ return new Contact(JSON.parse(data))
+ }
+
+ serialize() {
+ // Serialize to JSON string
+ return JSON.stringify(this.attrs)
+ }
+ ```
8. Test and iterate development of your type in your application.
9. Publish your type for others to use.
@@ -144,7 +144,7 @@ To perform additional processing of a collection, you can override the `get`, `s
## Publish your new type for others to use
-While you *can* use your collection exclusively in your application, the Collections feature is intended to enable data portability between DApps. So, you should publish your new type so other developers can make use of it.
+While you _can_ use your collection exclusively in your application, the Collections feature is intended to enable data portability between DApps. So, you should publish your new type so other developers can make use of it.
To publish your Collection type, do the following:
diff --git a/src/pages/develop/collections.md b/src/pages/develop/collections.md
index 9ded4333..c96c1a2b 100644
--- a/src/pages/develop/collections.md
+++ b/src/pages/develop/collections.md
@@ -1,8 +1,8 @@
---
-
-
---
+
# Work with Collections (Preview)
+
Collections is the feature designed to make data portable among Blockstack applications. Sharing is accomplished by storing a user's data in a standardized format at a known, Gaia storage location. Collections associate user data with a user's decentralized ID. When users move among apps, the same data is available to each application the user authorizes.
On this page, you learn what collections are and how to use them. You'll learn about the `Contact` collection in particular. The following topics are covered:
@@ -11,7 +11,7 @@ On this page, you learn what collections are and how to use them. You'll learn a
## Understand how collections work
-One of Blockstack's goals is to give users true data ownership by enabling *data portability*. Data portability allows users to login with their digital ID on any app and have access to the same data. For example, if a user adds a photo of a Hawaiian vacation in one app, that photo enters the user's data pool. Then, when the user opens a second app, that same photo is available to the second app because the user data, including the photo, is shared via the user's decentralized ID.
+One of Blockstack's goals is to give users true data ownership by enabling _data portability_. Data portability allows users to login with their digital ID on any app and have access to the same data. For example, if a user adds a photo of a Hawaiian vacation in one app, that photo enters the user's data pool. Then, when the user opens a second app, that same photo is available to the second app because the user data, including the photo, is shared via the user's decentralized ID.
How do collections work? Blockstack builds a library containing commonly used data schemes. Developers use these classes and objects instead of creating their own, unique data schemes. Using a class from the collections library guarantees class data is stored in Gaia in that format; And, when retrieved, guarantees the same format is returned. This pre-release provides the `Contact` collection. A contact schema produces this structure:
@@ -65,28 +65,28 @@ If you have `npm` installed, do the following to run the Contact Manager demo ap
7. Install the dependencies using `npm`.
- ```bash
- npm install
- ```
+ ```bash
+ npm install
+ ```
8. Start the application running.
- ```bash
- npm run start
- ```
+ ```bash
+ npm run start
+ ```
- The system starts the application and launches it in your browser at 127.0.0.1:3000
+ The system starts the application and launches it in your browser at 127.0.0.1:3000
9. Choose **Sign In with Blockstack**.
- The internet browser will display this pop-up
+ The internet browser will display this pop-up
- 
+ 
-10. Use the local browser by choosing **Open Blockstack.app**.
+10. Use the local browser by choosing **Open Blockstack.app**.
11. If you are not signed into an ID in the Blockstack Browser, choose **Create new ID** from the pop up.
- If you are already signed in, choose an ID to sign in to the Contacts Manager app with.
+ If you are already signed in, choose an ID to sign in to the Contacts Manager app with.
The system should return you to the Contact Manager demo application.
@@ -108,7 +108,6 @@ If you have `npm` installed, do the following to run the Contact Manager demo ap
-
## How to add the Contact collections to your DApp
In this section, you learn how to add `Contact` collection functionality to an existing application. Before beginning, make sure your application is using Blockstack auth and is storing data with Gaia. To start using the `Contact` collection in your Blockstack app, do the following:
@@ -116,35 +115,35 @@ In this section, you learn how to add `Contact` collection functionality to an e
1. Change to the root directory of your app project.
2. Install the preview branch of the `blockstack.js`.
- ```
- npm install blockstack@20.0.0-alpha.5
- ```
+ ```
+ npm install blockstack@20.0.0-alpha.5
+ ```
3. Add the ``blockstack-collections` package to your app.
- ```
- npm install blockstack-collections@0.1.8
- ```
+ ```
+ npm install blockstack-collections@0.1.8
+ ```
4. Edit your code to import the `Contact` collection type.
- ```
- import { Contact } from `blockstack-collections`
- ```
+ ```
+ import { Contact } from `blockstack-collections`
+ ```
5. Customize your sign in request to include the contacts collection scope `Contact.scope`.
- This scope grants your app permission to read and write to the user’s `Contact` collection.
+ This scope grants your app permission to read and write to the user’s `Contact` collection.
- ```javascript
- import { UserSession, AppConfig, makeAuthRequest } from 'blockstack'
- import { Contact } from '`blockstack-collections'
+ ```javascript
+ import { UserSession, AppConfig, makeAuthRequest } from 'blockstack';
+ import { Contact } from '`blockstack-collections';
- const scopes = ['store_write', 'publish_data', Contact.scope]
- const appConfig = new AppConfig(scopes)
- const userSession = new UserSession({appConfig: appConfig})
- userSession.redirectToSignIn()
- ```
+ const scopes = ['store_write', 'publish_data', Contact.scope];
+ const appConfig = new AppConfig(scopes);
+ const userSession = new UserSession({ appConfig: appConfig });
+ userSession.redirectToSignIn();
+ ```
## Collection storage operations
@@ -153,53 +152,50 @@ Collection storage was designed around an ORM-like interface. This approach ensu
### Example: Create and save a Contact object
```javascript
- const newContact = {
- lastName: 'Stackerson',
- firstName: 'Blocky',
- blockstackID: 'Blockstacker.id',
- email: 'blockstacker@blockstack.org',
- website: 'blockstack.org',
- telephone: '123123123'
- }
-
- var contact = new Contact(newContact)
- contact.save().then((contactID) => {
- // contact saved successfully
- })
+const newContact = {
+ lastName: 'Stackerson',
+ firstName: 'Blocky',
+ blockstackID: 'Blockstacker.id',
+ email: 'blockstacker@blockstack.org',
+ website: 'blockstack.org',
+ telephone: '123123123',
+};
+
+var contact = new Contact(newContact);
+contact.save().then(contactID => {
+ // contact saved successfully
+});
```
-
### Example: Read a Contact object
```javascript
- let contactID = 'Blocky Stackerson'
- Contact.get(contactID).then((contact) => {
- // Do something with the contact object
- console.log('Hello ${contact.firstName}')
- })
+let contactID = 'Blocky Stackerson';
+Contact.get(contactID).then(contact => {
+ // Do something with the contact object
+ console.log('Hello ${contact.firstName}');
+});
```
-
### Example: List Contact objects
```javascript
- let contacts = []
- Contact.list((contactID) => {
- // This callback is invoked for each contact identifier
- // To get the actual object you'll need to use Contact.get
- // Or you can add the IDs to an array for display
- contacts.push(contactID)
- // Return true to continue iterating, return false to stop
- return true
- })
+let contacts = [];
+Contact.list(contactID => {
+ // This callback is invoked for each contact identifier
+ // To get the actual object you'll need to use Contact.get
+ // Or you can add the IDs to an array for display
+ contacts.push(contactID);
+ // Return true to continue iterating, return false to stop
+ return true;
+});
```
-
### Example: Delete a Contact
```javascript
- var contact = new Contact(newContact)
- contact.delete().then(() => {
- // contact deleted successfully
- })
+var contact = new Contact(newContact);
+contact.delete().then(() => {
+ // contact deleted successfully
+});
```
diff --git a/src/pages/develop/connect/get-started.md b/src/pages/develop/connect/get-started.md
index 46f108e5..a7f266a0 100644
--- a/src/pages/develop/connect/get-started.md
+++ b/src/pages/develop/connect/get-started.md
@@ -1,4 +1,5 @@
# Guide to Blockstack Connect
+
## Installation
With yarn:
@@ -34,14 +35,13 @@ export interface AuthOptions {
}
```
-parameter | type | default | optional | description
----|---|---|---|---
-redirectTo | string | | false | The path in your app where users go after sign in.
-appDetails | object | | false | an object which includes `appName: string` and `appIcon: string`. This will speed up the process of loading your app's information during onboarding.
-finished | function | | false | A callback that can be invoked after authentication. This prevents having to do a whole page refresh in a new tab. One argument is passed to this callback, which is an object with `userSession` included. If included, then the `redirectTo` path is ignored, and the user will be logged in automatically.
-sendToSignIn | boolean | false | true | Whether the user should go straight to the 'sign in' flow (false) or be presented with the 'sign up' flow (true) instead.
-userSession | UserSession | | false | pass a `UserSession` instance to use for authentication. If it's not passed, `@blockstack/connect` will create one for you.
-
+| parameter | type | default | optional | description |
+| ------------ | ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| redirectTo | string | | false | The path in your app where users go after sign in. |
+| appDetails | object | | false | an object which includes `appName: string` and `appIcon: string`. This will speed up the process of loading your app's information during onboarding. |
+| finished | function | | false | A callback that can be invoked after authentication. This prevents having to do a whole page refresh in a new tab. One argument is passed to this callback, which is an object with `userSession` included. If included, then the `redirectTo` path is ignored, and the user will be logged in automatically. |
+| sendToSignIn | boolean | false | true | Whether the user should go straight to the 'sign in' flow (false) or be presented with the 'sign up' flow (true) instead. |
+| userSession | UserSession | | false | pass a `UserSession` instance to use for authentication. If it's not passed, `@blockstack/connect` will create one for you. |
### In React Apps
@@ -63,11 +63,7 @@ const authOptions = {
},
};
-const App = () => (
- UserGroup class to build a collaborative group with Radiks. In this section, you learn about this class.
## Understand the UserGroup workflow
-The key model behind a collaborative group is `UserGroup`. By default, it only has one attribute, `name`, which is encrypted. You can subclass `UserGroup` with different attributes as needed.
+The key model behind a collaborative group is `UserGroup`. By default, it only has one attribute, `name`, which is encrypted. You can subclass `UserGroup` with different attributes as needed.
The general workflow for creating a collaborative group that can share and edit encrypted models is as follows:
1. The admin of the group creates a new `UserGroup`.
This group acts as the 'hub' and controls the logic around inviting and removing users.
2. The admin invites one or more other users to a group:
- * The admin specifies the username of the user they want to invite
- * Radiks looks up the user's public key
- * Radiks creates an 'invitation' that is encrypted with the user's public key, and contains information about the `UserGroup`
+ - The admin specifies the username of the user they want to invite
+ - Radiks looks up the user's public key
+ - Radiks creates an 'invitation' that is encrypted with the user's public key, and contains information about the `UserGroup`
3. When the invited user 'activates' an invitation, they create a `GroupMembership`.
They use this membership instance to reference information (such as private keys and signing keys) related to the group.
@@ -44,7 +44,6 @@ import { UserGroup } from 'radiks';
Calling `create` on a new `UserGroup` will create the group and activate an invitation for the group's creator.
-
```javascript
const group = new UserGroup({ name: 'My Group Name' });
await group.create();
@@ -52,7 +51,6 @@ await group.create();
A group's creator is also the group's admin.
-
### Invite users to become members
Use the `makeGroupMembership` method on a `UserGroup` instance to invite a user. The only argument passed to this method is the user's `username`.
@@ -70,21 +68,20 @@ console.log(invitation._id); // the ID used to later activate an invitation
You can also create a generic invitation that any user can activate, if they are provided with randomly generated secret key, which should be used to decrypt the invitation. The key is generated when the generic invitation is being created.
-~~~javascript
+```javascript
import { GenericGroupInvitation, UserGroup } from 'radiks';
const group = await UserGroup.findById(myGroupId);
// Creating generic invitation
const genericInvitation = await GenericGroupInvitation.makeGenericInvitation(group);
console.log(genericInvitation._id); // the ID used to later activate an invitation
console.log(genericInvitation.secretCode); // the secretCode used to later activate an invitation
-~~~
-
+```
### Accept an invitation
Use the `activate` method on a `GroupInvitation` instance to activate an invitation on behalf of a user:
-```javascript
+````javascript
import { GroupInvitation, GenericGroupInvitation } from 'radiks';
// For user-specific invitation
@@ -103,7 +100,7 @@ Call `UserGroup.myGroups` to fetch all groups that the current user is a member
import { UserGroup } from 'radiks';
const groups = await UserGroup.myGroups();
-```
+````
## Find a UserGroup
diff --git a/src/pages/develop/radiks-intro.md b/src/pages/develop/radiks-intro.md
index 4a54e4de..72591cab 100644
--- a/src/pages/develop/radiks-intro.md
+++ b/src/pages/develop/radiks-intro.md
@@ -1,21 +1,18 @@
---
-
-
---
+
# Radiks the data indexer
-The Blockstack Radiks feature enables Blockstack decentralized applications (DApps) to index and store across data belonging to multiple users. Radiks works with Blockstack's Gaia Storage System. Using Radiks, you can build multi-player DApps that:
+The Blockstack Radiks feature enables Blockstack decentralized applications (DApps) to index and store across data belonging to multiple users. Radiks works with Blockstack's Gaia Storage System. Using Radiks, you can build multi-player DApps that:
- index, store, and query application data
- query a user's publicly saved data
- display real-time updates that reflect in progress changes
- support collaboration among sets of users
-
-
## Why use Radiks?
-Many applications serve data that users create to share publicly with others. Facebook, Twitter, and Instagram are examples of such applications. Decentralized applications that want to create comparable multi-user experiences must ensure that anything a user creates for public sharing is still under control of the creator in the user's Gaia storage.
+Many applications serve data that users create to share publicly with others. Facebook, Twitter, and Instagram are examples of such applications. Decentralized applications that want to create comparable multi-user experiences must ensure that anything a user creates for public sharing is still under control of the creator in the user's Gaia storage.
For example, if Twitter wanted to be a decentralized application while still having many different users creating their own tweets, those tweets would be stored in each user's own Gaia storage. In such a situation, Twitter still needs a way to keep track of everyone's tweets, display those tweets in user timelines, and perform searches across the platform. Radiks exists to support these kinds of scenarios. It allows applications to query across multiple user data using complicated queries like text search, joins, and filters.
@@ -33,9 +30,9 @@ Radiks can store both public and sensitive, non-public data since all data is en
## How Radiks authorizes writes
-Radiks must ensure that the user is writing to their own data. To ensure this, Radiks creates and manages *signing keys*. These keys sign all writes that a user performs. Radiks server-validates all signatures before performing a write. This guarantees that a user is not able to overwrite another user's data.
+Radiks must ensure that the user is writing to their own data. To ensure this, Radiks creates and manages _signing keys_. These keys sign all writes that a user performs. Radiks server-validates all signatures before performing a write. This guarantees that a user is not able to overwrite another user's data.
-A Radiks server is also built to support writes in a collaborative but private situation. For example, consider a collaborative document editing application, where users can create organizations and invite users to that organization. All users in that organization should have read and write privileges to the organization data. Thus, these organizations will have a single shared key that is used to sign and encrypt data.
+A Radiks server is also built to support writes in a collaborative but private situation. For example, consider a collaborative document editing application, where users can create organizations and invite users to that organization. All users in that organization should have read and write privileges to the organization data. Thus, these organizations will have a single shared key that is used to sign and encrypt data.
When an organization administrator needs to remove a user from the group, they are expected to revoke the previous key and create a new one. Radiks is aware of these relationships, and will only support writes that are signed with the currently active key related to an organization.
@@ -65,5 +62,5 @@ Although Radiks applications rely on a centrally-hosted database, an application
-If you are not familiar with Gaia, see
+If you are not familiar with Gaia, see
[read the Gaia documentation](({{site.baseurl}}/storage/overview.html).
diff --git a/src/pages/develop/radiks-models.md b/src/pages/develop/radiks-models.md
index 0658add2..186d22c5 100644
--- a/src/pages/develop/radiks-models.md
+++ b/src/pages/develop/radiks-models.md
@@ -1,9 +1,9 @@
---
-
-
---
+
# Create and use models
-Radiks allows you to model your client data. You can then query this data and display it for a user in multi-player applications. A social application where users want to see the comments of other users is an example of a multi-player application. This page explains how to create a model in your distributed application using Radiks.
+
+Radiks allows you to model your client data. You can then query this data and display it for a user in multi-player applications. A social application where users want to see the comments of other users is an example of a multi-player application. This page explains how to create a model in your distributed application using Radiks.
## Overview of Model class extension
@@ -13,9 +13,9 @@ Blockstack provides a `Model` class you should extend to easily create, save, an
import { Model, User } from 'radiks';
```
- Then, create a class that extends this model, and provide a schema. Refer to the Model class in the `radiks` repo to get an overview of the class functionality.
+Then, create a class that extends this model, and provide a schema. Refer to the Model class in the `radiks` repo to get an overview of the class functionality.
-Your new class must define a static `className` property. This property is used when storing and querying information. If you fail to add a `className`, Radiks defaults to the actual model's class name (`foobar.ts`) and your application will behave unpredictably.
+Your new class must define a static `className` property. This property is used when storing and querying information. If you fail to add a `className`, Radiks defaults to the actual model's class name (`foobar.ts`) and your application will behave unpredictably.
The example class code extends `Model` to create a class named `Todo`:
@@ -24,11 +24,12 @@ import { Model, User } from 'radiks';
class Todo extends Model {
static className = 'Todo';
- static schema = { // all fields are encrypted by default
+ static schema = {
+ // all fields are encrypted by default
title: String,
completed: Boolean,
- }
-};
+ };
+}
// after authentication:
const todo = new Todo({ title: 'Use Radiks in an app' });
@@ -38,8 +39,9 @@ todo.update({
});
await todo.save();
-const incompleteTodos = await Todo.fetchOwnList({ // fetch todos that this user created
- completed: false
+const incompleteTodos = await Todo.fetchOwnList({
+ // fetch todos that this user created
+ completed: false,
});
console.log(incompleteTodos.length); // 0
```
@@ -55,14 +57,15 @@ Every class must have a static `schema` property which defines the attributes of
```javascript
class Todo extends Model {
static className = 'Todo';
- static schema = { // all fields are encrypted by default
+ static schema = {
+ // all fields are encrypted by default
title: String,
completed: Boolean,
- }
-};
+ };
+}
```
-The `key` in this object is the field name and the value, for example, `String`, `Boolean`, or `Number`. In this case, the `title` is a `String` field. Alternatively, you can pass options instead of a type.
+The `key` in this object is the field name and the value, for example, `String`, `Boolean`, or `Number`. In this case, the `title` is a `String` field. Alternatively, you can pass options instead of a type.
To define options, pass an object, with a mandatory `type` field. The only supported option right now is `decrypted`. This defaults to `false`, meaning the field is encrypted before the data is stored publicly. If you specify `true`, then the field is not encrypted.
@@ -86,13 +89,13 @@ class Person extends Model {
isHuman: Boolean,
likesDogs: {
type: Boolean,
- decrypted: true // all users will know if this record likes dogs!
- }
- }
+ decrypted: true, // all users will know if this record likes dogs!
+ },
+ };
static defaults = {
- likesDogs: true
- }
+ likesDogs: true,
+ };
}
```
@@ -123,12 +126,11 @@ The default `User` model defines a `username`, but you can add a `displayName` t
In this section, you learn how to use a model you have defined.
-### About the _id attribute
+### About the \_id attribute
All model instances have an `_id` attribute. An `_id` is used as a primary key when storing data and is used for fetching a model. Radiks also creates a `createdAt` and `updatedAt` property when creating and saving models.
-If, when constructing a model's instance, you don't pass an `_id`, Radiks creates an `_id` for you automatically. This automatically created id uses the [`uuid/v4`](https://github.com/kelektiv/node-uuid) format. This automatic `_id` is returned by the constructor.
-
+If, when constructing a model's instance, you don't pass an `_id`, Radiks creates an `_id` for you automatically. This automatically created id uses the [`uuid/v4`](https://github.com/kelektiv/node-uuid) format. This automatic `_id` is returned by the constructor.
### Construct a model instance
@@ -138,19 +140,18 @@ To create an instance, pass some attributes to the constructor of that class:
const person = new Person({
name: 'Hank',
isHuman: false,
- likesDogs: false // just an example, I love dogs!
-})
+ likesDogs: false, // just an example, I love dogs!
+});
```
### Fetch an instance
-To fetch an existing instance of an instance, you need the instance's `id` property. Then, call the `findById()` method or the `fetch()` method, which returns a promise.
+To fetch an existing instance of an instance, you need the instance's `id` property. Then, call the `findById()` method or the `fetch()` method, which returns a promise.
```javascript
const person = await Person.findById('404eab3a-6ddc-4ba6-afe8-1c3fff464d44');
```
-
After calling these methods, Radiks automatically decrypts all encrypted fields.
### Access attributes
@@ -169,9 +170,9 @@ To quickly update multiple attributes of an instance, pass those attributes to t
```javascript
const newAttributes = {
likesDogs: false,
- age: 30
-}
-person.update(newAttributes)
+ age: 30,
+};
+person.update(newAttributes);
```
Important, calling `update` does **not** save the instance.
@@ -217,14 +218,14 @@ class Task extends Model {
order: {
type: Number,
decrypted: true,
- }
- }
+ },
+ };
}
const tasks = await Task.fetchList({
completed: false,
- sort: '-order'
-})
+ sort: '-order',
+});
```
You can read the [`query-to-mongo`](https://github.com/pbatey/query-to-mongo) package documentation to learn how to do complex querying, sorting, limiting, and so forth.
@@ -244,7 +245,7 @@ Use the `fetchOwnList` method to find instances that were created by the current
```javascript
const tasks = await Task.fetchOwnList({
- completed: false
+ completed: false,
});
```
@@ -276,8 +277,8 @@ Whenever you save a task, you should save a reference to the project it's in:
```javascript
const task = new Task({
name: 'Improve radiks documentation',
- projectId: project._id
-})
+ projectId: project._id,
+});
await task.save();
```
@@ -286,7 +287,7 @@ Then, later you'll want to fetch all tasks for a certain project:
```javascript
const tasks = await Task.fetchList({
projectId: project._id,
-})
+});
```
Radiks lets you define an `afterFetch` method. Use this method to automatically fetch child records when you fetch the parent instance.
@@ -294,12 +295,12 @@ Radiks lets you define an `afterFetch` method. Use this method to automatically
```javascript
class Project extends Model {
static className = 'Project';
- static schema = { name: String }
+ static schema = { name: String };
async afterFetch() {
this.tasks = await Task.fetchList({
projectId: this.id,
- })
+ });
}
}
diff --git a/src/pages/develop/radiks-server-extras.md b/src/pages/develop/radiks-server-extras.md
index 369421fe..4ecd7ca5 100644
--- a/src/pages/develop/radiks-server-extras.md
+++ b/src/pages/develop/radiks-server-extras.md
@@ -1,8 +1,8 @@
---
-
-
---
+
# Radiks server tips and tricks
+
In this section, you'll find some tips and tricks you can use to work with a Radiks server.
## Access the MongoDB collection
@@ -17,7 +17,6 @@ const mongo = await getDB(MONGODB_URL);
[See the MongoDB Collection reference](https://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html) for documentation about how you can interact with this collection.
-
## Run a custom Radiks-server
If you're using an [express.js](https://expressjs.com/) server to run your application, it's probably easiest to use the Radiks-server middleware. This way, you won't have to run a separate application server and Radiks server.
@@ -50,7 +49,6 @@ setup({
Currently, only the `mongoDBUrl` option is supported.
-
## Migrate from Firebase (or anywhere else)
Migrating data from Firebase to Radiks-server is simple and painless. You can create a script file to fetch all the Firebase data using their API. Then, you can use your `MONGOD_URI` config to use the `mongodb` npm package.
@@ -122,8 +120,8 @@ migrate()
Before you can implement the websocket function, you must configure your `Radiks-Server` with [express-ws](https://github.com/HenningM/express-ws)
```javascript
-const app = express()
-expressWS(app)
+const app = express();
+expressWS(app);
```
Here's an example for how to use the API:
@@ -131,7 +129,7 @@ Here's an example for how to use the API:
```javascript
import Task from './models/task';
-const streamCallback = (task) => {
+const streamCallback = task => {
// this callback will be called whenever a task is created or updated.
// `task` is an instance of `Task`, and all methods are defined on it.
// If the user has the necessary keys to decrypt encrypted fields on the model,
@@ -140,15 +138,15 @@ const streamCallback = (task) => {
if (task.projectId === myAppsCurrentProjectPageId) {
// update your view here with this task
}
-}
+};
-Task.addStreamListener(streamCallback)
+Task.addStreamListener(streamCallback);
// later on, you might want to remove the stream listener (if the
// user changes pages, for example). When calling `removeStreamListener`,
// you MUST provide the exact same callback that you used with `addStreamListener`.
-Task.removeStreamListener(streamCallback)
+Task.removeStreamListener(streamCallback);
```
## Saving centralized user-related data
diff --git a/src/pages/develop/radiks-setup.md b/src/pages/develop/radiks-setup.md
index 90e29673..8f8ee325 100644
--- a/src/pages/develop/radiks-setup.md
+++ b/src/pages/develop/radiks-setup.md
@@ -1,9 +1,9 @@
---
-
-
---
+
# Set-up Radiks for your DApp
-Using Radiks with your application requires a Radiks server and a client application constructed to use the server. In this article, you learn how to install, setup, and run a pre-packaged Radiks server that connects to MongoDB. You also learn how to establish your DApp application as a client for that server.
+
+Using Radiks with your application requires a Radiks server and a client application constructed to use the server. In this article, you learn how to install, setup, and run a pre-packaged Radiks server that connects to MongoDB. You also learn how to establish your DApp application as a client for that server.
## Task 1. Set up your Radiks server
@@ -17,7 +17,7 @@ In the future, Radiks-server will support various different databases, but right
1. Download and install MongoDB 3.6 or higher on your workstation.
- You can also install MongoDB using your favorite package manager; for example, Homebrew is recommended for macOS. If you are testing on a local workstation, you can use a `docker` image instead of installing locally.
+ You can also install MongoDB using your favorite package manager; for example, Homebrew is recommended for macOS. If you are testing on a local workstation, you can use a `docker` image instead of installing locally.
2. Start the MongoDB service and verify it is running.
@@ -27,34 +27,35 @@ In the future, Radiks-server will support various different databases, but right
4. Create a username/password combination with `root` privileges on your new database.
-
### Install and start the Radiks server
The easiest way to run `radiks-server` is to use the pre-packaged `node.js` server.
1. Install the `radiks-server` on a workstation or server.
- ```bash
- npm install -g radiks-server
- ```
- Or, if you prefer `yarn`:
+ ```bash
+ npm install -g radiks-server
+ ```
- ```bash
- yarn global add radiks-server
- ```
- The default port for Mongodb is `27017`; your instance may be configured differently. By default, Radiks-server will use `'mongodb://localhost:27017/radiks-server'` as the `MongoDB_URI` value. This is suitable for local testing, but in production, you'll want to change the hostname and possibly the database name.
+ Or, if you prefer `yarn`:
-3. Start the `radiks-server` in the command line to confirm your installation.
+ ```bash
+ yarn global add radiks-server
+ ```
+
+ The default port for Mongodb is `27017`; your instance may be configured differently. By default, Radiks-server will use `'mongodb://localhost:27017/radiks-server'` as the `MongoDB_URI` value. This is suitable for local testing, but in production, you'll want to change the hostname and possibly the database name.
+
+2. Start the `radiks-server` in the command line to confirm your installation.
```
$ radiks-server
(node:37750) DeprecationWarning: current Server Discovery and Monitoring engine is deprecated and will be removed in a future version. To use the new Server Discover and Monitoring engine, pass option { useUnifiedTopology: true } to the MongoClient constructor.
- radiks-server is ready on http://localhost:1260
- ```
+ radiks-server is ready on http://localhost:1260
+ ```
- The `radiks-server` defaults to running on port `1260`. To change the default port, specify the `PORT` environment variable in your environment.
+ The `radiks-server` defaults to running on port `1260`. To change the default port, specify the `PORT` environment variable in your environment.
-4. By default, the server is running at `http://localhost:1260`
+3. By default, the server is running at `http://localhost:1260`
4. Stop the `radiks` server process after you confirm it runs, and your installation was a success.
@@ -88,42 +89,42 @@ If you are using `blockstack.js` version 18 or earlier, you must use the Radiks
1. Start the mongo shell application.
- ```
- $ mongo
- MongoDB shell version v4.2.0
- connecting to: mongodb://127.0.0.1:27017/?compressors=disabled&gssapiServiceName=mongodb
- Implicit session: session { "id" : UUID("8d43cf80-490d-4cac-8bd6-40eec5c128de") }
- MongoDB server version: 4.2.0
- ....
-
- To enable free monitoring, run the following command: db.enableFreeMonitoring()
- To permanently disable this reminder, run the following command: db.disableFreeMonitoring()
- >
- ```
-
- 2. Create a new database for your application.
-
- ```
- > show dbs
- admin 0.000GB
- config 0.000GB
- local 0.000GB
- > use test1
- switched to db test1
- > show dbs
- admin 0.000GB
- config 0.000GB
- local 0.000GB
- > db.createUser({user: "admin", pwd:"foobar1",roles: ["readWrite","dbAdmin"]});
- Successfully added user: { "user" : "admin", "roles" : [ "readWrite", "dbAdmin" ] }
- ```
+ ```
+ $ mongo
+ MongoDB shell version v4.2.0
+ connecting to: mongodb://127.0.0.1:27017/?compressors=disabled&gssapiServiceName=mongodb
+ Implicit session: session { "id" : UUID("8d43cf80-490d-4cac-8bd6-40eec5c128de") }
+ MongoDB server version: 4.2.0
+ ....
+
+ To enable free monitoring, run the following command: db.enableFreeMonitoring()
+ To permanently disable this reminder, run the following command: db.disableFreeMonitoring()
+ >
+ ```
+
+2. Create a new database for your application.
+
+ ```
+ > show dbs
+ admin 0.000GB
+ config 0.000GB
+ local 0.000GB
+ > use test1
+ switched to db test1
+ > show dbs
+ admin 0.000GB
+ config 0.000GB
+ local 0.000GB
+ > db.createUser({user: "admin", pwd:"foobar1",roles: ["readWrite","dbAdmin"]});
+ Successfully added user: { "user" : "admin", "roles" : [ "readWrite", "dbAdmin" ] }
+ ```
3. Add a user with administrative rights to the database.
- ```
- > db.createUser({user: "admin", pwd:"foobar1",roles: ["readWrite","dbAdmin"]});
- Successfully added user: { "user" : "admin", "roles" : [ "readWrite", "dbAdmin" ] }
- ```
+ ```
+ > db.createUser({user: "admin", pwd:"foobar1",roles: ["readWrite","dbAdmin"]});
+ Successfully added user: { "user" : "admin", "roles" : [ "readWrite", "dbAdmin" ] }
+ ```
4. Create an `MONGODB_URI` environment variable on the same machine where you are running the `radiks-server`.
@@ -133,7 +134,6 @@ If you are using `blockstack.js` version 18 or earlier, you must use the Radiks
export MONGODB_URI="mongodb://admin:foobar1@localhost:27017/test1"
```
-
## Task 3. Add startup code and build your application
To set up radiks.js, you only need to configure the URL that your Radiks-server instance is running on. If you're using the pre-built Radiks server, this will be `http://localhost:1260`. If you're in production or are using a custom Radiks server, you'll need to specify the exact URL where it's available.
@@ -146,48 +146,47 @@ To configure your application as a `radiks` client, do the following:
1. Start your application so that a `UserSession` allows the app to both write and publish data:
- ```js
- import { UserSession, AppConfig } from 'blockstack';
- import { configure } from 'radiks';
+ ```js
+ import { UserSession, AppConfig } from 'blockstack';
+ import { configure } from 'radiks';
- const userSession = new UserSession({
- appConfig: new AppConfig(['store_write', 'publish_data'])
- })
+ const userSession = new UserSession({
+ appConfig: new AppConfig(['store_write', 'publish_data']),
+ });
- configure({
- apiServer: 'http://localhost:1260',
- userSession
- });
- ```
+ configure({
+ apiServer: 'http://localhost:1260',
+ userSession,
+ });
+ ```
- 2. Add authentication to your application
+2. Add authentication to your application
- After your user logs in with Blockstack, you'll have some code to save the user's data in your applications `localStorage`. You'll want to use the same `UserSession` you configured with Radiks, which can be fetched from the `getConfig` method.
+ After your user logs in with Blockstack, you'll have some code to save the user's data in your applications `localStorage`. You'll want to use the same `UserSession` you configured with Radiks, which can be fetched from the `getConfig` method.
- ```js
- import { User, getConfig } from 'radiks';
+ ```js
+ import { User, getConfig } from 'radiks';
- const handleSignIn = () => {
- const { userSession } = getConfig();
- if (userSession.isSignInPending()) {
- await userSession.handlePendingSignIn();
- await User.createWithCurrentUser();
- }
- }
- ```
+ const handleSignIn = () => {
+ const { userSession } = getConfig();
+ if (userSession.isSignInPending()) {
+ await userSession.handlePendingSignIn();
+ await User.createWithCurrentUser();
+ }
+ }
+ ```
- Calling `User.createWithCurrentUser` does the following:
+ Calling `User.createWithCurrentUser` does the following:
- * Fetch user data that Blockstack.js stores in `localStorage`
- * Save the user's public data (including their public key) in Radiks-server
- * Find or create a signing key that is used to authorize writes on behalf of this user
- * Cache the user's signing key (and any group-related signing keys) to make signatures and decryption happen quickly later on
+ - Fetch user data that Blockstack.js stores in `localStorage`
+ - Save the user's public data (including their public key) in Radiks-server
+ - Find or create a signing key that is used to authorize writes on behalf of this user
+ - Cache the user's signing key (and any group-related signing keys) to make signatures and decryption happen quickly later on
### Build and run your application
After you have added Radiks to your application, build and run the application. Test the application by logging in with your Blockstack ID. Create some data using the application. If you inspect the MongoDB database, you should see the encrypted data stored in the database.
-
You can specify the `mongoDBUrl` or the `maxLimit` option when initiating the Radiks server in your application.
```javascript
@@ -201,7 +200,6 @@ setup({
The `mongoDBUrl` option is the MongoDB URL for the Radiks server
The `maxLimit` option is the maximum `limit` field used inside the mongo queries. The default is 1000.
-
## Where to go next
Creating models for your application's data is where radiks truly becomes helpful. To learn how to use models, see the [Create and use models](radiks-models.html) section.
diff --git a/src/pages/develop/storage.md b/src/pages/develop/storage.md
index 99eb3eb5..d09048e5 100644
--- a/src/pages/develop/storage.md
+++ b/src/pages/develop/storage.md
@@ -1,7 +1,6 @@
---
-
-
---
+
# Guide to Blockstack Storage
The Blockstack Platform stores application data in the Gaia Storage System. Transactional metadata is stored on the Blockstack blockchain and user application data is stored in Gaia storage. Storing data off of the blockchain ensures that Blockstack applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties.
@@ -12,7 +11,6 @@ The Blockstack Platform stores application data in the Gaia Storage System. Tran
Gaia storage is a key-value store.
-
## Creating a file
You use the UserSession.putFile
@@ -82,6 +80,7 @@ var userSession = new UserSession()
```
## Reading another user's unencrypted file
+
In order for files to be publicly readable, the app must request
the `publish_data` scope during authentication.
@@ -103,7 +102,6 @@ userSession.putFile("/hello.txt", "hello world!", options)
You use the UserSession.deleteFile from the application's data store.
-
```JavaScript
var userSession = new UserSession()
@@ -115,4 +113,5 @@ var userSession = new UserSession()
```
## Related Information
+
To learn more about the guarantees provided by Gaia, see [Storage write and read]({{ site.baseurl }}/storage/write-to-read.html#)
diff --git a/src/pages/faqs/allFAQS.md b/src/pages/faqs/allFAQS.md
index b0047f3c..cba5bb32 100644
--- a/src/pages/faqs/allFAQS.md
+++ b/src/pages/faqs/allFAQS.md
@@ -1,9 +1,9 @@
---
-
-description: "Blockstack Network documentation"
+description: 'Blockstack Network documentation'
redirect_from: /org/voucherholder
---
+
# Blockstack FAQs
This is a comprehensive list of all the Blockstack FAQs.
@@ -98,10 +98,10 @@ This is a comprehensive list of all the Blockstack FAQs.
## Important disclaimer
-*The Securities and Exchange Commission (SEC) has qualified the offering statement that we have filed with the SEC under Regulation A for our offering of certain of our Stacks Tokens. The information in that offering statement is more complete than the information we are providing now, and could differ in important ways. You must read the documents filed with the SEC before investing. The offering is being made only by means of its offering statement. This document shall not constitute an offer to sell or the solicitation of an offer to buy, nor shall there be any sale of these securities in any state or jurisdiction in which such offer, solicitation or sale would be unlawful prior to registration or qualification under the securities laws of any such state or jurisdiction.*
+_The Securities and Exchange Commission (SEC) has qualified the offering statement that we have filed with the SEC under Regulation A for our offering of certain of our Stacks Tokens. The information in that offering statement is more complete than the information we are providing now, and could differ in important ways. You must read the documents filed with the SEC before investing. The offering is being made only by means of its offering statement. This document shall not constitute an offer to sell or the solicitation of an offer to buy, nor shall there be any sale of these securities in any state or jurisdiction in which such offer, solicitation or sale would be unlawful prior to registration or qualification under the securities laws of any such state or jurisdiction._
-*An indication of interest involves no obligation or commitment of any kind. Any person interested in investing in any offering of Stacks Tokens should review our disclosures and the publicly filed offering statement and the ffinal offering circular that is part of that offering statement. Blockstack is not registered, licensed or supervised as a broker dealer or investment adviser by the SEC, the Financial Industry Regulatory Authority (FINRA) or any other financial regulatory authority or licensed to provide any financial advice or services.*
+_An indication of interest involves no obligation or commitment of any kind. Any person interested in investing in any offering of Stacks Tokens should review our disclosures and the publicly filed offering statement and the ffinal offering circular that is part of that offering statement. Blockstack is not registered, licensed or supervised as a broker dealer or investment adviser by the SEC, the Financial Industry Regulatory Authority (FINRA) or any other financial regulatory authority or licensed to provide any financial advice or services._
## Forward-looking statements
-*This communication contains forward-looking statements that are based on our beliefs and assumptions and on information currently available to us. In some cases, you can identify forward-looking statements by the following words: “will,” “expect,” “would,” “intend,” “believe,” or other comparable terminology. Forward-looking statements in this document include, but are not limited to, statements about our plans for developing the platform and future utility for the Stacks Token, our Clarity smart contracting language, and potential mining operations. These statements involve risks, uncertainties, assumptions and other factors that may cause actual results or performance to be materially different. More information on the factors, risks and uncertainties that could cause or contribute to such differences is included in our filings with the SEC, including in the “Risk Factors” and “Management’s Discussion & Analysis” sections of our offering statement on Form 1-A. We cannot assure you that the forward-looking statements will prove to be accurate. These forward-looking statements speak only as of the date hereof. We disclaim any obligation to update these forward-looking statements.*
+_This communication contains forward-looking statements that are based on our beliefs and assumptions and on information currently available to us. In some cases, you can identify forward-looking statements by the following words: “will,” “expect,” “would,” “intend,” “believe,” or other comparable terminology. Forward-looking statements in this document include, but are not limited to, statements about our plans for developing the platform and future utility for the Stacks Token, our Clarity smart contracting language, and potential mining operations. These statements involve risks, uncertainties, assumptions and other factors that may cause actual results or performance to be materially different. More information on the factors, risks and uncertainties that could cause or contribute to such differences is included in our filings with the SEC, including in the “Risk Factors” and “Management’s Discussion & Analysis” sections of our offering statement on Form 1-A. We cannot assure you that the forward-looking statements will prove to be accurate. These forward-looking statements speak only as of the date hereof. We disclaim any obligation to update these forward-looking statements._
diff --git a/src/pages/ios/tutorial.md b/src/pages/ios/tutorial.md
index ec58218a..c31a4e02 100644
--- a/src/pages/ios/tutorial.md
+++ b/src/pages/ios/tutorial.md
@@ -1,9 +1,9 @@
---
-
description: How to use Blockstack on iOS Mobile
-
---
+
# iOS DApps
+
This tutorial teaches you how to create a decentralized application using
Blockstack's iOS SDK using the following content:
@@ -18,7 +18,7 @@ experienced. For best results, beginners should follow the guide as written. It
is expected that the fast or furiously brilliant will skip ahead and improvise
on this material at will. God speed one and all.
-If you want to download a complete application rather than working through a tutorial, see this *alternative* sample, the photoblock-demo.
+If you want to download a complete application rather than working through a tutorial, see this _alternative_ sample, the photoblock-demo.
## Understand the sample application flow
@@ -102,62 +102,62 @@ In this section, you build an initial React.js application called
1. Create a `hello-blockstack` directory.
- ```bash
- mkdir hello-blockstack
- ```
+ ```bash
+ mkdir hello-blockstack
+ ```
2. Change into your new directory.
- ```bash
- cd hello-blockstack
- ```
+ ```bash
+ cd hello-blockstack
+ ```
3. Create your initial `hello-world-tutorial` application.
- ```bash
- $ npx generator-blockstack --react
- npx: installed 338 in 13.792s
- create package.json
- create .gitignore
- create webpack.config.js
- create netlify.toml
- create firebase.json
- ...
- I'm all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself.
-
- > fsevents@1.2.9 install /private/tmp/testymc/node_modules/fsevents
- > node install
- added 775 packages from 455 contributors and audited 9435 packages in 20.934s
- found 0 vulnerabilities
+ ```bash
+ $ npx generator-blockstack --react
+ npx: installed 338 in 13.792s
+ create package.json
+ create .gitignore
+ create webpack.config.js
+ create netlify.toml
+ create firebase.json
+ ...
+ I'm all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself.
+
+ > fsevents@1.2.9 install /private/tmp/testymc/node_modules/fsevents
+ > node install
+ added 775 packages from 455 contributors and audited 9435 packages in 20.934s
+ found 0 vulnerabilities
- ```
+ ```
- Depending on your environment you may have some warnings with the installation. Optionally, you can fix these before continuing to the next section.
+ Depending on your environment you may have some warnings with the installation. Optionally, you can fix these before continuing to the next section.
4. Run the initial application.
- ```bash
- npm run start
-
- > hello-blockstack@0.0.0 start /Users/meepers/repos/hello-blockstack
- > webpack-dev-server
-
- Project is running at http://localhost:8080/
- webpack output is served from /
- 404s will fallback to /index.html
- Hash: 4d2312ba236a4b95dc3a
- Version: webpack 2.7.0
- Time: 2969ms
- Asset Size Chunks Chunk Names
- ....
- Child html-webpack-plugin for "index.html":
- chunk {0} index.html 541 kB [entry] [rendered]
- [0] ./~/lodash/lodash.js 540 kB {0} [built]
- [1] ./~/html-webpack-plugin/lib/loader.js!./src/index.html 533 bytes {0} [built]
- [2] (webpack)/buildin/global.js 509 bytes {0} [built]
- [3] (webpack)/buildin/module.js 517 bytes {0} [built]
- webpack: Compiled successfully.
- ```
+ ```bash
+ npm run start
+
+ > hello-blockstack@0.0.0 start /Users/meepers/repos/hello-blockstack
+ > webpack-dev-server
+
+ Project is running at http://localhost:8080/
+ webpack output is served from /
+ 404s will fallback to /index.html
+ Hash: 4d2312ba236a4b95dc3a
+ Version: webpack 2.7.0
+ Time: 2969ms
+ Asset Size Chunks Chunk Names
+ ....
+ Child html-webpack-plugin for "index.html":
+ chunk {0} index.html 541 kB [entry] [rendered]
+ [0] ./~/lodash/lodash.js 540 kB {0} [built]
+ [1] ./~/html-webpack-plugin/lib/loader.js!./src/index.html 533 bytes {0} [built]
+ [2] (webpack)/buildin/global.js 509 bytes {0} [built]
+ [3] (webpack)/buildin/module.js 517 bytes {0} [built]
+ webpack: Compiled successfully.
+ ```
At this point, the browser is running a Blockstack server on your local host.
@@ -172,18 +172,16 @@ In this section, you build an initial React.js application called
The system displays a prompt allowing you to create a new Blockstack ID or restore an existing one.
- 
+ 
7. Follow the prompts appropriate to your situation.
- If you are restoring an existing ID, you may see a prompt about your user
- being nameless, ignore it. At this point you have only a single application
- on your test server. So, you should see this single application, with your
- own `blockstack.id` display name, once you are signed in:
-
- 
-
+ If you are restoring an existing ID, you may see a prompt about your user
+ being nameless, ignore it. At this point you have only a single application
+ on your test server. So, you should see this single application, with your
+ own `blockstack.id` display name, once you are signed in:
+ 
### Add a redirect end point to your application
@@ -192,55 +190,55 @@ you want the web app to redirect the user to your iOS application. The work
you do here will allow it.
1. From the terminal command line, change directory to your web
-application directory (`hello-blockstack`).
+ application directory (`hello-blockstack`).
1. If it doesn't ext, create the `public` directory.
- ```bash
- $ mkdir public
- ```
+ ```bash
+ $ mkdir public
+ ```
-2. Use the `touch` command to add a redirect endpoint to your application.
+1. Use the `touch` command to add a redirect endpoint to your application.
This endpoint on the web version of your app will redirect iOS users back
to your mobile app.
- ```bash
- $ touch public/redirect.html
- ```
-
-3. Open `redirect.html` and add code to the endpoint.
+ ```bash
+ $ touch public/redirect.html
+ ```
- ```
-
-
-
- | Product Name | -hello-blockstack-ios |
-
|---|---|
| Organization Name | -USERNAME |
-
| User Interface | -Storyboard | -
| Product Name | +hello-blockstack-ios |
+
|---|---|
| Organization Name | +USERNAME |
+
| User Interface | +Storyboard | +
Security tip: What to share and what not to
@@ -54,7 +53,6 @@ Custody Solutions?](https://www.investopedia.com/news/what-are-cryptocurrency-custody-solutions/) is one place to start. - ## Choosing a cryptocurrency wallet You can choose among different types of cryptocurrency wallets. There are mainly diff --git a/src/pages/org/wallet-troubleshoot.md b/src/pages/org/wallet-troubleshoot.md index 9acc3ed3..a257ba95 100644 --- a/src/pages/org/wallet-troubleshoot.md +++ b/src/pages/org/wallet-troubleshoot.md @@ -1,18 +1,20 @@ --- - -description: "How to use the Blockstack Software" - +description: 'How to use the Blockstack Software' --- + # Wallet FAQs and Troubleshooting + This page contains frequently asked questions and troubleshooting related to the wallet. ## Frequently asked questions {% for faq in site.data.theFAQs.faqs %} - {% if faq.category == 'wallet' %} +{% if faq.category == 'wallet' %} + ### {{ faq.question }} + {{ faq.answer }} - {% endif %} +{% endif %} {% endfor %} ## Change from a software-only wallet to a hardware wallet @@ -26,7 +28,6 @@ To change from a software-only wallet to a hardware wallet, do the following: 5. Login into your Coinlist account. 6. Change your Stacks wallet address. - ## View or change your Stacks wallet address on Coinlist If you purchased Stacks via Coinlist during in the token sale, your Stacks address is located at this URL: @@ -47,8 +48,10 @@ To view or change your Stacks address on Coinlist, do the following: 2. Enter a URL in this format: ``` - https://sale.stackstoken.com/stacks-token-sale/YOUR_COINLIST_USERNAME/wallet_address - ``` + https://sale.stackstoken.com/stacks-token-sale/YOUR_COINLIST_USERNAME/wallet_address + ``` + +``` 3. Change your address if necessary. @@ -64,3 +67,4 @@ If you previously set up your CoinList account by logging in with your AngelList 6. Use the instructions in the recovery email to create a unique password for your CoinList account. Going forward, you can access your CoinList account by logging in with your email and new password. +``` diff --git a/src/pages/org/wallet-use.md b/src/pages/org/wallet-use.md index 714155cd..1232eadd 100644 --- a/src/pages/org/wallet-use.md +++ b/src/pages/org/wallet-use.md @@ -1,23 +1,23 @@ --- - -description: "Blockstack Network documentation" - +description: 'Blockstack Network documentation' --- + # Use the Stacks Wallet software + This page describes how to use the Stacks Wallet software to manager your Stacks (STX) tokens. This page contains the following topics: The Stacks Wallet software is installed on your computer, it is not a web application. You should have already [downloaded, verified, and installed the wallet software](wallet-install.html). ## Key concepts you should understand - You use Stacks Wallet software to manage STX tokens. Using the wallet you can: +You use Stacks Wallet software to manage STX tokens. Using the wallet you can: -* send STX from a specific STX address -* receive STX at a specific STX address -* view balances on an address -* review transaction history associated with an address +- send STX from a specific STX address +- receive STX at a specific STX address +- view balances on an address +- review transaction history associated with an address -To send STX, you need Bitcoin in your wallet. Bitcoin is the "gas" for transactions on the Stacks blockchain. A **_very small_** amount of Bitcoin is required to send STX. The gas price fluctuates like any market and is driven by the price of Bitcoin. Gas is not required to receive STX. +To send STX, you need Bitcoin in your wallet. Bitcoin is the "gas" for transactions on the Stacks blockchain. A **_very small_** amount of Bitcoin is required to send STX. The gas price fluctuates like any market and is driven by the price of Bitcoin. Gas is not required to receive STX. You can use the Stacks Wallet software by itself or together with a hardware wallet. Using with a hardware wallet is recommended but not required. @@ -30,9 +30,9 @@ You can use the Stacks Wallet software by itself or together with a hardware wal You can use any of these hardware wallets with the Stacks Wallet: -* Trezor One -* Ledger Nano S -* Ledger Blue +- Trezor One +- Ledger Nano S +- Ledger Blue {% include note.html content="Blockstack only supports the hardware wallets listed above. Other wallets, for example, the Trezor Model T, are not supported. If you have questions about wallet support, please contact Blockstack support." %} @@ -40,7 +40,7 @@ The private key on your hardware wallet is used by the Stacks Wallet software to ### Software only wallet and a seed phrase -You can use the Stacks Wallet software without a hardware device to create one or more software wallets. Each wallet has its own address which corresponds to a STX address on the Stacks blockchain. You access this address with a unique, **seed phrase**. The software generates a seed phrase for you when create a software-only wallet. The seed phrase consists of 24 words in a sequence. Both the word _and its position the sequence_ are important. +You can use the Stacks Wallet software without a hardware device to create one or more software wallets. Each wallet has its own address which corresponds to a STX address on the Stacks blockchain. You access this address with a unique, **seed phrase**. The software generates a seed phrase for you when create a software-only wallet. The seed phrase consists of 24 words in a sequence. Both the word _and its position the sequence_ are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. @@ -56,7 +56,6 @@ If you used the original, v1, version of the wallet, you should instead begin us The v2 version of the wallet required a hardware wallet to send and receive. You can connect this same hardware wallet to the v3 version of the Stacks Wallet software. If this is your situation, choose **Use existing wallet** when you first start the Stacks Wallet v3; you don't need to create a new wallet. - ## Create a new or open an existing wallet When you start the Stacks Wallet it prompts you to create a new or choose an existing wallet. You should create a new wallet if you have not previously connected a hardware device to the Stacks Wallet v3 software or if you do not have an existing 24 word seed phrase. @@ -92,7 +91,7 @@ When your hardware device is ready, do the following: 2. Double-click on the wallet software to open it. 3. Select **Create new wallet** or **Use existing wallet**. - If you connected your hardware device to an old version of the Stacks Wallet software, you choose **Create new wallet**. After you make this initial connection, the *next time* you start the wallet, you can choose **Use existing wallet**. + If you connected your hardware device to an old version of the Stacks Wallet software, you choose **Create new wallet**. After you make this initial connection, the _next time_ you start the wallet, you can choose **Use existing wallet**. The system asks if you have a hardware wallet. @@ -119,7 +118,6 @@ When your hardware device is ready, do the following: The Stacks Wallet shows the current wallet balance. - ### Software only wallet If you have an existing 24 word seed phrase from this or a previous version of the Stacks Wallet software, you don't need to create a new wallet, you can **Use existing wallet**. This procedure assumes you are creating a wallet for the first time. @@ -135,14 +133,14 @@ If you have an existing 24 word seed phrase from this or a previous version of t 4. Choose **Continue without a hardware wallet**. - The system generates a seed phrase for you and prompts you to write it down. - Don't lose your seed phrase. If you lose your seed phrase, you lose your STX tokens and can never get them back. + The system generates a seed phrase for you and prompts you to write it down. + Don't lose your seed phrase. If you lose your seed phrase, you lose your STX tokens and can never get them back. -5. Write down each word and its position, for example,` 1 - frog`. +5. Write down each word and its position, for example,`1 - frog`. 6. Store your written seed phrase in a secure location such as a safe deposit box. 7. Click **I've written down my seed phrase**. - The system prompts you to re-enter your seed phrase. The sequence numbers are out of order. For example, `5` may appear in the `1` position. Enter the corresponding `5` and `1` word as appropriate. + The system prompts you to re-enter your seed phrase. The sequence numbers are out of order. For example, `5` may appear in the `1` position. Enter the corresponding `5` and `1` word as appropriate. 8. Select **Done**. @@ -168,7 +166,6 @@ Stacks you have unlocked. The **Allocation** is the amount still locked up.  - ## Receive Stacks To receive Stacks: you give a STX address directly to a user via email or text, for @@ -180,7 +177,7 @@ example. 2. Email or text the address to the person or organization sending to you. - A Stacks address is a public addresses. Anyone with the address, can view the address balance or send money _**to**_ the address. + A Stacks address is a public addresses. Anyone with the address, can view the address balance or send money _**to**_ the address. 3. Look for the receipt transaction in your transaction history. @@ -190,8 +187,6 @@ example. Blockchain transactions take time. It may be minutes or hours before the transaction is recorded in the blockchain. When the transaction is complete, you can see a receipt for the transaction in your Stacks Wallet. The **PENDING** marker goes away once the funds are recorded on the blockchain. - - ## Add Bitcoin gas The Stacks Wallet uses very small amounts of Bitcoin to pay fees for sending transactions. You need very small fractions of Bitcoin (BTC) for gas. The cost of gas you need fluctuates with the market price of Bitcoin. @@ -206,16 +201,16 @@ If you attempt to send STX with your wallet and you do not have enough Bitcoin t  - To increase your Bitcoin for transactions, do the following: +To increase your Bitcoin for transactions, do the following: - 1. Click the - (settings icon) in the upper right corner of the wallet. +1. Click the + (settings icon) in the upper right corner of the wallet. - The system opens the **Settings** dialog. + The system opens the **Settings** dialog. -  +  - This dialog shows you how much BTC you currently have in your account. + This dialog shows you how much BTC you currently have in your account. 2. Select **Add BTC**. @@ -253,12 +248,12 @@ Sending stacks is a transaction you must authorize or sign. If you have connecte 5. Select **Continue**. - If you do not have enough Bitcoin to fuel the transaction, the system - notifies you. If you don't have enough Bitcoin, you must **Top Up**. - Otherwise, the system prompts you to connect to your hardware wallet. Your - hardware wallet will prompt you for additional information and actions. + If you do not have enough Bitcoin to fuel the transaction, the system + notifies you. If you don't have enough Bitcoin, you must **Top Up**. + Otherwise, the system prompts you to connect to your hardware wallet. Your + hardware wallet will prompt you for additional information and actions. -  +  6. Select **Continue**. @@ -278,25 +273,22 @@ Sending stacks is a transaction you must authorize or sign. If you have connecte Select **Refresh** if you don't immediately see the transaction in your history. - - ## Reset the wallet Resetting a wallet clears all your data from the Stacks Wallet and returns the wallet to its original state. -* If you entered a Stacks address, resetting clears the address from the Stacks Wallet. -* If you connected to a hardware wallet, resetting removes the connection to the hardware wallet. +- If you entered a Stacks address, resetting clears the address from the Stacks Wallet. +- If you connected to a hardware wallet, resetting removes the connection to the hardware wallet. Resetting the wallet does nothing to your addresses or their associated balances. They are maintained. -Once you reset the wallet, you have to start over from the *Terms of Use*. If +Once you reset the wallet, you have to start over from the _Terms of Use_. If you do not restart the wallet, you can simple close it. - 1. Click the - (settings icon) in the upper right corner of the wallet. + (settings icon) in the upper right corner of the wallet. The system opens the **Settings** dialog. diff --git a/src/pages/storage/amazon-s3-deploy.md b/src/pages/storage/amazon-s3-deploy.md index af27fa19..f002b917 100644 --- a/src/pages/storage/amazon-s3-deploy.md +++ b/src/pages/storage/amazon-s3-deploy.md @@ -1,9 +1,9 @@ --- - -description: "Storing user data with Blockstack" - +description: 'Storing user data with Blockstack' --- + # Configure a hub on Amazon EC2 + This teaches you how to run a Gaia hub on Amazon EC2. Amazon EC2 is an affordable and convenient cloud computing provider. This example uses Amazon EC2 instance together with an [EBS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html) disk for file storage.
@@ -20,7 +20,7 @@ This teaches you how to run a Gaia hub on Amazon EC2. Amazon EC2 is an affordabl
This procedure uses Amazon AWS to choose and configure an Amazon Machine Image
(AMI) running a Gaia service. For this reason, you should have an AWS account
on the Amazon AWS free
-tier, personal account, or corporate account. These instructions assume you
+tier, personal account, or corporate account. These instructions assume you
are using a free tier account.
These instructions assume you have already created a free
-
+7. Select **t2.micro** and choose **Next: Configure Instance Details**.
+
+ To configure instance details, do the following:
+
+ -
-
-
-
Select a VPC.
-A default VPC is created with a free tier account. You can use this - default VPC. Or you can choose another VPC. If you choose another VPC, - ensure the
-Subnetvalue is set to a subnet reachable by a public IP. -Important: If you're using a private subnet, you - should attach an elastic IP (EIP) to the VM. This EIP allows you to - reboot the instance without worrying whether the address will reset. To - attach an IP, press allocate new address and follow the - instructions to attach the EIP to your new EC2 instance. --
- -
-
Set Protect against accidental termination.
-If you terminate a Gaia instance, you lose all the data associated with it. Protection adds an extra step to terminating your Gaia instance.
-
- -
-
Open the Advanced Details.
-At this point, you are going to configure environment variables for your instance.
-
- -
-
Paste the following into the Advanced Details.
- --- { - "ignition": { "version": "2.2.0" }, - "storage": { - "files": [{ - "filesystem": "root", - "path": "/etc/environment", - "mode": 420, - "contents": { - "source": "data:application/octet-stream,API_KEY%3DKEYPHRASE%0ADOMAIN%3DNAME_OF_DOMAIN%0ASTAGING%3DSTAGING_VALUE" - } - }] - } - } -
- -
-
Replace the following values in the JSON.
-- -
-- -Value -Description -- -<KEYPHRASE>A phrase to pass when using the hub admin. For example, -hubbais a fun key phrase.- -<NAME_OF_DOMAIN>Your hub's domain name. For example, -maryhub.mlis the domain name in this example.- - -<STAGING_VALUE>- -Indicates what type of SSL to create, testing (`1`) or production (`0`). Set testing if you want to test without worrying about rate limiting. A testing cerificate is not secure.
-For this tutorial, use production (`0`).
-
- -
-
Check your Advanced Details they should look similar to the following:
- --{ - "ignition": { "version": "2.2.0" }, - "storage": { - "files": [{ - "filesystem": "root", - "path": "/etc/environment", - "mode": 420, - "contents": { - "source": "data:application/octet-stream,API_KEY%3Dhubba%0ADOMAIN%3Dmaryhub.ml%0ASTAGING%3D0" - } - }] - } - } -
-
+
At this point, you have configured your instance details.
-8. Choose **Next: Add Storage**.
+8. Choose **Next: Add Storage**.
- 
+ 
- The storage is set according to the AMI you selected.
+ The storage is set according to the AMI you selected.
9. Choose **Next: Add tags**.
10. Optionally, add the following tags:
The tags are not required, they just apply searchable labels to an instance on an EC2 console.
- * **Key** of `Purpose` with the **Value** `gaia`
- * **Key** of `Name` with the **Value** `gaia-hub`
- * **Key** of `Version` with the **Value** `2.5.3` (This value is an example, your version may be different.)
+ - **Key** of `Purpose` with the **Value** `gaia`
+ - **Key** of `Name` with the **Value** `gaia-hub`
+ - **Key** of `Version` with the **Value** `2.5.3` (This value is an example, your version may be different.)
-
-11. Choose **Next: Configure Security Group**.
-12. Create a security group with the following three types:
+11) Choose **Next: Configure Security Group**.
+12) Create a security group with the following three types:
-
+
-
+
Select a VPC.
+A default VPC is created with a free tier account. You can use this + default VPC. Or you can choose another VPC. If you choose another VPC, + ensure the
+Subnetvalue is set to a subnet reachable by a public IP. +Important: If you're using a private subnet, you + should attach an elastic IP (EIP) to the VM. This EIP allows you to + reboot the instance without worrying whether the address will reset. To + attach an IP, press allocate new address and follow the + instructions to attach the EIP to your new EC2 instance. ++
+ -
+
Set Protect against accidental termination.
+If you terminate a Gaia instance, you lose all the data associated with it. Protection adds an extra step to terminating your Gaia instance.
+
+ -
+
Open the Advanced Details.
+At this point, you are going to configure environment variables for your instance.
+
+ -
+
Paste the following into the Advanced Details.
+ ++ ++ { + "ignition": { "version": "2.2.0" }, + "storage": { + "files": [{ + "filesystem": "root", + "path": "/etc/environment", + "mode": 420, + "contents": { + "source": "data:application/octet-stream,API_KEY%3DKEYPHRASE%0ADOMAIN%3DNAME_OF_DOMAIN%0ASTAGING%3DSTAGING_VALUE" + } + }] + } + } +
+ -
+
Replace the following values in the JSON.
++ +
++ +Value +Description ++ +<KEYPHRASE>A phrase to pass when using the hub admin. For example, +hubbais a fun key phrase.+ +<NAME_OF_DOMAIN>Your hub's domain name. For example, +maryhub.mlis the domain name in this example.+ + +<STAGING_VALUE>+ +Indicates what type of SSL to create, testing (`1`) or production (`0`). Set testing if you want to test without worrying about rate limiting. A testing cerificate is not secure.
+For this tutorial, use production (`0`).
+
+ -
+
Check your Advanced Details they should look similar to the following:
+ ++ +{ + "ignition": { "version": "2.2.0" }, + "storage": { + "files": [{ + "filesystem": "root", + "path": "/etc/environment", + "mode": 420, + "contents": { + "source": "data:application/octet-stream,API_KEY%3Dhubba%0ADOMAIN%3Dmaryhub.ml%0ASTAGING%3D0" + } + }] + } + } +
+
| If the response is | -Do this... | -
|---|---|
 |
- You should see a message that your connection is not private. - Everything is fine, continue to the next step, step 8. | -
 |
-
-
|
-
| If the response is | +Do this... | +
|---|---|
|
+ You should see a message that your connection is not private. +Everything is fine, continue to the next step, step 8. | +
|
+
+
|
+
 -The token ensures the DApp has the authorization to write to the hub on the user's behalf. +The token ensures the DApp has the authorization to write to the hub on the user's behalf. diff --git a/src/pages/storage/cliDocs.md b/src/pages/storage/cliDocs.md index 509bf572..7badcbd0 100644 --- a/src/pages/storage/cliDocs.md +++ b/src/pages/storage/cliDocs.md @@ -1,8 +1,7 @@ --- - -description: "Storing user data with Blockstack" - +description: 'Storing user data with Blockstack' --- + # blockstack_cli reference {% include commandline.md %} diff --git a/src/pages/storage/config-schema.md b/src/pages/storage/config-schema.md index 40136404..e7b5550f 100644 --- a/src/pages/storage/config-schema.md +++ b/src/pages/storage/config-schema.md @@ -1,203 +1,187 @@ --- - -description: "Storing user data with Blockstack" - +description: 'Storing user data with Blockstack' --- + # Hub configuration parameters The following JSON schema details the possible parameters for a hub configuration: ```json { - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false, - "properties": { - "argsTransport": { - "additionalProperties": false, - "properties": { - "colorize": { - "default": true, - "type": "boolean" - }, - "handleExceptions": { - "default": true, - "type": "boolean" - }, - "json": { - "default": false, - "type": "boolean" - }, - "level": { - "default": "warn", - "enum": [ - "debug", - "error", - "info", - "verbose", - "warn" - ], - "type": "string" - }, - "timestamp": { - "default": true, - "type": "boolean" - } - }, - "type": "object" - }, - "authTimestampCacheSize": { - "default": 50000, - "type": "integer" - }, - "awsCredentials": { - "additionalProperties": false, - "description": "Required if `driver` is `aws`", - "properties": { - "accessKeyId": { - "type": "string" - }, - "endpoint": { - "type": "string" - }, - "secretAccessKey": { - "type": "string" - }, - "sessionToken": { - "type": "string" - } - }, - "type": "object" - }, - "azCredentials": { - "additionalProperties": false, - "description": "Required if `driver` is `azure`", - "properties": { - "accountKey": { - "type": "string" - }, - "accountName": { - "type": "string" - } - }, - "type": "object" - }, - "bucket": { - "default": "hub", - "type": "string" - }, - "cacheControl": { - "default": "public, max-age=1", - "type": "string" - }, - "diskSettings": { - "additionalProperties": false, - "description": "Required if `driver` is `disk`", - "properties": { - "storageRootDirectory": { - "type": "string" - } - }, - "type": "object" - }, - "driver": { - "enum": [ - "aws", - "azure", - "disk", - "google-cloud" - ], - "type": "string" - }, - "gcCredentials": { - "additionalProperties": false, - "description": "Required if `driver` is `google-cloud`", - "properties": { - "credentials": { - "additionalProperties": false, - "properties": { - "client_email": { - "type": "string" - }, - "private_key": { - "type": "string" - } - }, - "type": "object" - }, - "email": { - "type": "string" - }, - "keyFilename": { - "type": "string" - }, - "projectId": { - "type": "string" - } - }, - "type": "object" - }, - "maxFileUploadSize": { - "default": 20, - "description": "The maximum allowed POST body size in megabytes. \nThe content-size header is checked, and the POST body stream \nis monitoring while streaming from the client. \n[Recommended] Minimum 100KB (or approximately 0.1MB)", - "minimum": 0.1, - "type": "number" + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "argsTransport": { + "additionalProperties": false, + "properties": { + "colorize": { + "default": true, + "type": "boolean" + }, + "handleExceptions": { + "default": true, + "type": "boolean" + }, + "json": { + "default": false, + "type": "boolean" + }, + "level": { + "default": "warn", + "enum": ["debug", "error", "info", "verbose", "warn"], + "type": "string" + }, + "timestamp": { + "default": true, + "type": "boolean" + } + }, + "type": "object" + }, + "authTimestampCacheSize": { + "default": 50000, + "type": "integer" + }, + "awsCredentials": { + "additionalProperties": false, + "description": "Required if `driver` is `aws`", + "properties": { + "accessKeyId": { + "type": "string" }, - "pageSize": { - "default": 100, - "maximum": 4096, - "minimum": 1, - "type": "integer" + "endpoint": { + "type": "string" }, - "port": { - "default": 3000, - "maximum": 65535, - "minimum": 0, - "type": "integer" + "secretAccessKey": { + "type": "string" }, - "proofsConfig": { - "additionalProperties": false, - "properties": { - "proofsRequired": { - "default": 0, - "type": "integer" - } + "sessionToken": { + "type": "string" + } + }, + "type": "object" + }, + "azCredentials": { + "additionalProperties": false, + "description": "Required if `driver` is `azure`", + "properties": { + "accountKey": { + "type": "string" + }, + "accountName": { + "type": "string" + } + }, + "type": "object" + }, + "bucket": { + "default": "hub", + "type": "string" + }, + "cacheControl": { + "default": "public, max-age=1", + "type": "string" + }, + "diskSettings": { + "additionalProperties": false, + "description": "Required if `driver` is `disk`", + "properties": { + "storageRootDirectory": { + "type": "string" + } + }, + "type": "object" + }, + "driver": { + "enum": ["aws", "azure", "disk", "google-cloud"], + "type": "string" + }, + "gcCredentials": { + "additionalProperties": false, + "description": "Required if `driver` is `google-cloud`", + "properties": { + "credentials": { + "additionalProperties": false, + "properties": { + "client_email": { + "type": "string" }, - "type": "object" - }, - "readURL": { - "type": "string" + "private_key": { + "type": "string" + } + }, + "type": "object" }, - "requireCorrectHubUrl": { - "default": false, - "type": "boolean" + "email": { + "type": "string" }, - "serverName": { - "default": "gaia-0", - "description": "Domain name used for auth/signing challenges. \nIf `requireCorrectHubUrl` is true then this must match the hub url in an auth payload.", - "type": "string" + "keyFilename": { + "type": "string" }, - "validHubUrls": { - "description": "If `requireCorrectHubUrl` is true then the hub specified in an auth payload can also be\ncontained within in array.", - "items": { - "type": "string" - }, - "type": "array" - }, - "whitelist": { - "description": "List of ID addresses allowed to use this hub. Specifying this makes the hub private \nand only accessible to the specified addresses. Leaving this unspecified makes the hub \npublicly usable by any ID.", - "items": { - "type": "string" - }, - "type": "array" + "projectId": { + "type": "string" } + }, + "type": "object" }, - "required": [ - "driver", - "port" - ], - "type": "object" + "maxFileUploadSize": { + "default": 20, + "description": "The maximum allowed POST body size in megabytes. \nThe content-size header is checked, and the POST body stream \nis monitoring while streaming from the client. \n[Recommended] Minimum 100KB (or approximately 0.1MB)", + "minimum": 0.1, + "type": "number" + }, + "pageSize": { + "default": 100, + "maximum": 4096, + "minimum": 1, + "type": "integer" + }, + "port": { + "default": 3000, + "maximum": 65535, + "minimum": 0, + "type": "integer" + }, + "proofsConfig": { + "additionalProperties": false, + "properties": { + "proofsRequired": { + "default": 0, + "type": "integer" + } + }, + "type": "object" + }, + "readURL": { + "type": "string" + }, + "requireCorrectHubUrl": { + "default": false, + "type": "boolean" + }, + "serverName": { + "default": "gaia-0", + "description": "Domain name used for auth/signing challenges. \nIf `requireCorrectHubUrl` is true then this must match the hub url in an auth payload.", + "type": "string" + }, + "validHubUrls": { + "description": "If `requireCorrectHubUrl` is true then the hub specified in an auth payload can also be\ncontained within in array.", + "items": { + "type": "string" + }, + "type": "array" + }, + "whitelist": { + "description": "List of ID addresses allowed to use this hub. Specifying this makes the hub private \nand only accessible to the specified addresses. Leaving this unspecified makes the hub \npublicly usable by any ID.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": ["driver", "port"], + "type": "object" } - ``` The following is an simple example of a Gaia hub configuration: @@ -218,4 +202,4 @@ The following is an simple example of a Gaia hub configuration: } ``` -A full list of example can be found in [the Gaia repository on GitHub](https://github.com/blockstack/gaia/tree/master/hub). \ No newline at end of file +A full list of example can be found in [the Gaia repository on GitHub](https://github.com/blockstack/gaia/tree/master/hub). diff --git a/src/pages/storage/digital-ocean-deploy.md b/src/pages/storage/digital-ocean-deploy.md index b7e7271e..3d33b02b 100644 --- a/src/pages/storage/digital-ocean-deploy.md +++ b/src/pages/storage/digital-ocean-deploy.md @@ -1,9 +1,9 @@ --- - -description: "Storing user data with Blockstack" - +description: 'Storing user data with Blockstack' --- + # Configure a hub on DigitalOcean + This teaches you how to run a Gaia storage hub on DigitalOcean (DO). DigitalOcean is an affordable and convenient cloud computing provider. This example uses DigitalOcean Spaces for file storage. A space is equivalent to AWS's S3 file storage solution. DigitalOcean provides you with a compute machines known as a **Droplets** and storage called a **Spaces**. You need both to run a Gaia hub. The Gaia hub setup you create here, requires get a Digital Droplet with Docker pre-installed and a 250 GB Space. Droplets and storage each run for $5/month or a total of $10/month. @@ -19,19 +19,19 @@ DigitalOcean provides you with a compute machines known as a **Droplets** and st ## Prerequisites you need - You use DigitalOcean choose and configure assets for running droplets and spaces. To enable this, you must be sure to complete the prerequisites in this section. +You use DigitalOcean choose and configure assets for running droplets and spaces. To enable this, you must be sure to complete the prerequisites in this section. -You must create an account on DigitalOcean. DigitalOcean requires you to supply a credit card to create an account. You are only charged for the services you use the Gaia hub as of this writing should cost $10 USD a month. +You must create an account on DigitalOcean. DigitalOcean requires you to supply a credit card to create an account. You are only charged for the services you use the Gaia hub as of this writing should cost \$10 USD a month. The easiest way to interact with your droplet is the DigitalOcean Console. Users who are comfortable using the secure shell (SSH) and private keys may prefer to open a local terminal on their home machine instead. To enable this, you should ensure you have the following prerequisites completed. -* Locate an existing SSH key pair on your Mac or create a new SSH key pair. Your key should have a passphrase, do not use a key pair without one. +- Locate an existing SSH key pair on your Mac or create a new SSH key pair. Your key should have a passphrase, do not use a key pair without one. -* Add the SSH from your local machine to DigitalOcean. +- Add the SSH from your local machine to DigitalOcean. -* Create a personal access token in DigitalOcean. +- Create a personal access token in DigitalOcean. -* Install `doctl` which is the DigitalOcean command line tool. For information on installing these, see which is the DigitalOcean command line utility. Check out their [installation instructions](https://github.com/digitalocean/doctl/blob/master/README.md#installing-doctl) to see how to install it on your computer. +- Install `doctl` which is the DigitalOcean command line tool. For information on installing these, see which is the DigitalOcean command line utility. Check out their [installation instructions](https://github.com/digitalocean/doctl/blob/master/README.md#installing-doctl) to see how to install it on your computer. ## Task 1: Create a DigitalOcean space @@ -64,13 +64,12 @@ In this task you create a **Space** which is where Gaia stores your files. ## Task 2: Enable File Listing and Set a Bucket Policy - On Digital Ocean, set **Enable File Listing**: 1. Navigate to the **Spaces** tab. 2. Select your newly created space and click **Settings** -3. Set **Enable File Listing** for your space. +3. Set **Enable File Listing** for your space. 4. Press **Save**. On your local workstation, create a bucket policy to grant read permission on your space. @@ -79,28 +78,29 @@ On your local workstation, create a bucket policy to grant read permission on yo 2. Install and configure the s3cmd. 3. In the current directory, use the `touch` command to create a file called `gaiahub-policy`. - ``` - touch gaiahub-policy - ``` + ``` + touch gaiahub-policy + ``` 4. Use your favorite editor to open the file. 5. Add the following policy to the file. - ```json - { - "Version":"2012-10-17", - "Id": "read policy", - "Statement":[ - { - "Sid":"PublicRead", - "Effect":"Allow", - "Principal": "*", - "Action": "s3:GetObject", - "Resource": "arn:aws:s3:::/*" - } - ] - } - ``` + ```json + { + "Version": "2012-10-17", + "Id": "read policy", + "Statement": [ + { + "Sid": "PublicRead", + "Effect": "Allow", + "Principal": "*", + "Action": "s3:GetObject", + "Resource": "arn:aws:s3:::/*" + } + ] + } + ``` + 6. Edit the `Resource` line and replace the `` with your space name from Digital Ocean. For example, if your space is named `meepers`, after editing the line you would have: @@ -120,7 +120,7 @@ On your local workstation, create a bucket policy to grant read permission on yo Be sure to `SPACE_NAME` with the name of your space, for example: - ``` + ``` s3cmd setpolicy gaiahub-policy s3://meepers ``` @@ -128,23 +128,23 @@ On your local workstation, create a bucket policy to grant read permission on yo 1. On your local workstation, create a file called `gaiahub-cors.xml` that looks like this: - ```xml - - - GET - HEAD - * - ETag - 0 - - - ``` + ```xml + + + GET + HEAD + * + ETag + 0 + + + ``` 2. Use `s3cmd` to enact the configuration. - ``` - s3cmd setcors gaiahub-cors.xml s3:// - ``` + ``` + s3cmd setcors gaiahub-cors.xml s3:// + ``` ## Task 4: Create a DigitalOcean droplet @@ -165,9 +165,9 @@ In this task, you add a droplet to your account. The droplet is a droplet is a c 5. Select the **Docker** app from the options presented. -6. Scroll down to the **Choose a size** section and use the left arrow to display and select the **$5/mo** image. +6. Scroll down to the **Choose a size** section and use the left arrow to display and select the **\$5/mo** image. - This size gives you plenty of memory and disk space to run a personal hub. + This size gives you plenty of memory and disk space to run a personal hub. 7. Scroll down to the **Choose a datacenter region** section. @@ -181,11 +181,10 @@ In this task, you add a droplet to your account. The droplet is a droplet is a c 10. **Choose a hostname** for your droplet such as `moxie-gaiahub`. -11. Review your choices then click **Create** to start your droplet running. +11. Review your choices then click **Create** to start your droplet running. At this point, your new droplet should appear in the list of resources on your DigitalOcean dashboard. - ## Task 5: Open a console on your Droplet A droplet console emulates the access you would have if you were sitting down with a keyboard and monitor attached to the actual server. In this section, you open a console on your droplet. @@ -203,7 +202,7 @@ A droplet console emulates the access you would have if you were sitting down wi 3. Choose **Access** from the control panel. 4. Select **Reset Root Password** to have DigitalOcean send you the root password. - DigitalOcean sends a temporary password to the email attached to your account. It takes a couple of minutes to reset the root password on your droplet. + DigitalOcean sends a temporary password to the email attached to your account. It takes a couple of minutes to reset the root password on your droplet. 5. Open your email and copy the password. 6. Switch back to the droplet control panel and choose **Launch Console**. @@ -225,7 +224,7 @@ A droplet console emulates the access you would have if you were sitting down wi 10. Provide and confirm a new password. - The system logins you in and gives you a welcome message. At the conclusion of the message, you are at the console prompt. + The system logins you in and gives you a welcome message. At the conclusion of the message, you are at the console prompt. ``` Welcome to DigitalOcean's One-Click Docker Droplet. @@ -246,7 +245,6 @@ A droplet console emulates the access you would have if you were sitting down wi If you find the output from ls difficult to read, try enter the following to change the console colors from the command line: LS_COLORS="di=1;31" You can also edit your console .bashrc. file permanently, of course. - ## Task 6: Create a space key 1. In the DigitalOcean dashboard, go to the **API** page. @@ -261,13 +259,13 @@ A droplet console emulates the access you would have if you were sitting down wi 5. Press the check mark. - The system creates your key and displays both the key and its secret. + The system creates your key and displays both the key and its secret. -  +  6. Save your secret in a secure password manager. - You should never share your secret. + You should never share your secret. 7. Leave the page up with your key and secret and go to your open console. @@ -304,9 +302,9 @@ You should have the console open as `root` on your Droplet. In this section, you 3. Copy the configuration sample to a new `config.json` file. - ``` - cp config.do.sample.json config.json - ``` + ``` + cp config.do.sample.json config.json + ``` 4. Edit your new `config.json` file with `vi` or `vim`. @@ -340,18 +338,20 @@ You should have the console open as `root` on your Droplet. In this section, you "colorize": false, "json": true } - } - ``` + } + ``` + +```` - You'll find that the `driver` is set to `aws`. The DigitalOcean space API exactly mimics the S3 API. Since Gaia doesn't have a DigitalOcean driver, you can just use the `aws` driver with some special configuration. + You'll find that the `driver` is set to `aws`. The DigitalOcean space API exactly mimics the S3 API. Since Gaia doesn't have a DigitalOcean driver, you can just use the `aws` driver with some special configuration. 5. Set the `serverName` to the droplet you just created. 6. Set the `readURL` to the URL of the DigitalOcean space you just created. - If your space URL called `https://meepers-hub-space.sfo2.digitaloceanspaces.com `, the `readURL` name is `https://meepers-hub-space.sfo2.digitaloceanspaces.com`. + If your space URL called `https://meepers-hub-space.sfo2.digitaloceanspaces.com `, the `readURL` name is `https://meepers-hub-space.sfo2.digitaloceanspaces.com`. 7. Set the `bucket` to the name of the DigitalOcean space you just created. - If your space is called `meepers-hub-space`, the `bucket` value is `meepers-hub-space`. + If your space is called `meepers-hub-space`, the `bucket` value is `meepers-hub-space`. 8. Go back to your DigitalOcean dashboard open to your space key. 9. Copy the **Key** and paste it into the `accessKeyId` value in the `config.json` file. @@ -359,48 +359,48 @@ You should have the console open as `root` on your Droplet. In this section, you 11. In the DigitalOcean dashboard, choose the Spaces page. 12. Copy the section of your space URL that follows the name. -  +  - In this example, you would copy the `sfo2.digitaloceanspaces.com` section. + In this example, you would copy the `sfo2.digitaloceanspaces.com` section. 13. Paste the string you copied into the `endpoint` value. 14. Ensure the `proofsRequired` value is set to the number `0` (zero). - This will allow Blockstack user to write to your Gaia hub, without any social proofs required. You can change this later on, and do other things to lock-down this Gaia hub to just yourself, but that is outside the scope of this document. - - At this point, the `json.config` file should be completed and appear similar to the following &—; but with your values. - - ```json - { - "serverName": "moxie-gaiahub", - "port": 4000, - "driver": "aws", - "readURL": "https://meepers-hub-space.sfo2.digitaloceanspaces.com", - "proofsConfig": { - "proofsRequired": 0 - }, - "pageSize": 20, - "bucket": "meepers-hub-space", - "awsCredentials": { - "endpoint": "sfo2.digitaloceanspaces.com", - "accessKeyId": "fb3J7AT/PGMGMPOA86EFLpx8IjGZQib99eXWjVR+QK0", - "secretAccessKey": "9ac685342eaa5bc4b44c13f3ecf43b001a3bdb9e2257114d44394d410dd91f66" - }, - "argsTransport": { - "level": "debug", - "handleExceptions": true, - "stringify": true, - "timestamp": true, - "colorize": false, - "json": true - } + This will allow Blockstack user to write to your Gaia hub, without any social proofs required. You can change this later on, and do other things to lock-down this Gaia hub to just yourself, but that is outside the scope of this document. + + At this point, the `json.config` file should be completed and appear similar to the following &—; but with your values. + + ```json + { + "serverName": "moxie-gaiahub", + "port": 4000, + "driver": "aws", + "readURL": "https://meepers-hub-space.sfo2.digitaloceanspaces.com", + "proofsConfig": { + "proofsRequired": 0 + }, + "pageSize": 20, + "bucket": "meepers-hub-space", + "awsCredentials": { + "endpoint": "sfo2.digitaloceanspaces.com", + "accessKeyId": "fb3J7AT/PGMGMPOA86EFLpx8IjGZQib99eXWjVR+QK0", + "secretAccessKey": "9ac685342eaa5bc4b44c13f3ecf43b001a3bdb9e2257114d44394d410dd91f66" + }, + "argsTransport": { + "level": "debug", + "handleExceptions": true, + "stringify": true, + "timestamp": true, + "colorize": false, + "json": true } - ``` + } + ``` 15. Save your config file and close the `vim` editor. - The system returns you back to the prompt. + The system returns you back to the prompt. ## Task 8: Run the Gaia image with Docker @@ -408,38 +408,42 @@ While your console is still in the the `gaia/hub` folder, build the `gaia.hub` i 1. Enter the following `docker` command at the console command line. - ``` - docker build -t gaia.hub . - ``` - This build users the `Dockerfile` already in the `gaia/hub` folder. The output of the command is similar to the following: +```` - ``` - .... +docker build -t gaia.hub . - npm WARN gaia-hub@2.3.4 No license field. - npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.4 (node_modules/fsevents): - npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.2.4: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"}) +``` +This build users the `Dockerfile` already in the `gaia/hub` folder. The output of the command is similar to the following: - added 877 packages from 540 contributors and audited 3671 packages in 38.122s - found 0 vulnerabilities +``` - Removing intermediate container b0aef024879f - ---> 5fd126019708 - Step 5/5 : CMD ["npm", "run", "start"] - ---> Running in ae459cc0865b - Removing intermediate container ae459cc0865b - ---> b1ced6c39784 - Successfully built b1ced6c39784 - Successfully tagged gaia.hub:latest - ``` +.... + +npm WARN gaia-hub@2.3.4 No license field. +npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.4 (node_modules/fsevents): +npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.2.4: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"}) + +added 877 packages from 540 contributors and audited 3671 packages in 38.122s +found 0 vulnerabilities + +Removing intermediate container b0aef024879f +---> 5fd126019708 +Step 5/5 : CMD ["npm", "run", "start"] +---> Running in ae459cc0865b +Removing intermediate container ae459cc0865b +---> b1ced6c39784 +Successfully built b1ced6c39784 +Successfully tagged gaia.hub:latest + +```` 2. Run your Gaia hub image. - ```bash - docker run --restart=always -v ~/gaia/hub/config.json:/src/hub/config.json -p 3000:3000 -e CONFIG_PATH=/src/hub/config.json gaia.hub - ``` +```bash +docker run --restart=always -v ~/gaia/hub/config.json:/src/hub/config.json -p 3000:3000 -e CONFIG_PATH=/src/hub/config.json gaia.hub +```` - This runs your Gaia hub on port `3000`. If everything runs successfully, the last line outputted from this command should be: +This runs your Gaia hub on port `3000`. If everything runs successfully, the last line outputted from this command should be: ```bash Successfully compiled 13 files with Babel. @@ -450,11 +454,11 @@ While your console is still in the the `gaia/hub` folder, build the `gaia.hub` i 4. Run the the image again with this new command. - ``` - docker run --restart=always -v ~/gaia/hub/config.json:/src/hub/config.json -p 3000:3000 -e CONFIG_PATH=/src/hub/config.json -d gaia.hub - ``` + ``` + docker run --restart=always -v ~/gaia/hub/config.json:/src/hub/config.json -p 3000:3000 -e CONFIG_PATH=/src/hub/config.json -d gaia.hub + ``` - This command includes `-d` option to `docker run`. This runs Docker in detached mode, so that it runs in the background. You can run `docker ps` to see your running docker images, and get the `id` of your Gaia server. + This command includes `-d` option to `docker run`. This runs Docker in detached mode, so that it runs in the background. You can run `docker ps` to see your running docker images, and get the `id` of your Gaia server. ```bash @@ -471,16 +475,16 @@ In this task, you set up a simple Nginx reverse proxy to serve your Docker conta 1. Install nginx into the droplet. - ``` - sudo apt-get install nginx - ``` + ``` + sudo apt-get install nginx + ``` 2. Enter `y` to confirm the installation. 3. Edit the nginx default configuration file. - ``` - vi /etc/nginx/sites-available/default - ``` + ``` + vi /etc/nginx/sites-available/default + ``` 4. Inside the `location /` block (line 48), enter the following configuration: @@ -504,30 +508,30 @@ In this task, you set up a simple Nginx reverse proxy to serve your Docker conta } more_set_headers 'Access-Control-Allow-Origin: *'; } - ``` + ``` This simple configuration passes all requests through to your Gaia hub running at port `3000`. 5. Save and close the file. 6. Run `nginx -t` to make sure you have no syntax errors. - ``` - root@meepers:~/gaia/hub# nginx -t - nginx: the configuration file /etc/nginx/nginx.conf syntax is ok - nginx: configuration file /etc/nginx/nginx.conf test is successful - ``` + ``` + root@meepers:~/gaia/hub# nginx -t + nginx: the configuration file /etc/nginx/nginx.conf syntax is ok + nginx: configuration file /etc/nginx/nginx.conf test is successful + ``` 7. Restart `nginx` with your new configuration. - ``` - systemctl restart nginx - ``` + ``` + systemctl restart nginx + ``` 8. Allow access to your Gaia hub by exposing port 80 to the public. - ``` - ufw allow 80 - ``` + ``` + ufw allow 80 + ``` ## Task 10: Test your Gaia server @@ -541,14 +545,13 @@ Now, you are ready to test your Gaia server and make sure it is up and running. 3. Copy the IP address for it. 4. In your browser, visit the page `MY_DROPLET_IP/hub_info`. - You should see a response from your Gaia hub! + You should see a response from your Gaia hub! -  - - The `read_url_prefix` should be combine from the bucket and endpoint create - in your `config.json` file, for example, - `https://meepers-hub-space.s3.amazonaws.com/`. +  + The `read_url_prefix` should be combine from the bucket and endpoint create + in your `config.json` file, for example, + `https://meepers-hub-space.s3.amazonaws.com/`. ## Task 11: Configure a domain name @@ -578,7 +581,6 @@ These instructions assume you have already created a free - ## Using the admin service APIs You use the admin service APIs to manage the hub. Administrating a hub requires @@ -148,11 +141,10 @@ export API_KEY="hello" You may find it useful to install a JSON processor such as `jq` to process the output of the admin commands. - ### Restart the Gaia Hub (`POST /v1/admin/reload`) The admin service will make changes to the Gaia hub's config file, but the -changes will only take effect when the Gaia hub is reloaded. You can do this +changes will only take effect when the Gaia hub is reloaded. You can do this as follows: ```bash @@ -164,21 +156,21 @@ $ curl -H "Authorization: bearer $API_KEY" -X POST http://localhost:8009/v1/admi When you `POST` to this endpoint, the admin service runs the command described in the `reloadSettings` section of the config file. It attempts to spawn a subprocess from the given `reloadSettings.command` binary, and pass it the -arguments given in `reloadSettings.argv`. Note that the subprocess will *NOT* +arguments given in `reloadSettings.argv`. Note that the subprocess will _NOT_ be run in a shell. - #### Errors + If you do not supply a valid API key, this method fails with HTTP 403. -This endpoint returns HTTP 500 if the reload command fails. If this +This endpoint returns HTTP 500 if the reload command fails. If this happens, you will get back the command's exit code and possibly the signal that killed it. ### Get the hub configuration (`GET /v1/admin/config`) This endpoint is used to read and write a Gaia hub's non-driver-related -settings. These include the port it listens on, and its proof-checking +settings. These include the port it listens on, and its proof-checking settings. To read the Gaia hub settings, you would run the following: @@ -188,12 +180,11 @@ $ export API_KEY="hello" $ curl -H "Authorization: bearer $API_KEY" http://localhost:8009/v1/admin/config {"config":{"port":4000,"proofsConfig":{"proofsRequired":0}}} ``` -### Set the hub configuration (`POST /v1/admin/config`) +### Set the hub configuration (`POST /v1/admin/config`) To set Gaia hub settings, you simply `POST` the changed JSON fields to this endpoint. - ```bash $ export API_KEY="hello" $ curl -H "Authorization: bearer $API_KEY" -H 'Content-Type: application/json' -X POST --data-raw '{"port": 3001}' http://localhost:8009/v1/admin/config @@ -202,10 +193,10 @@ $ curl -H "Authorization: bearer $API_KEY" -H 'Content-Type: application/json' - If the settings were successfully applied, the method returns a message to reload your Gaia hub. You can set multiple drivers' settings with a single call. For example, you can set: -* The driver to use (`driver`) -* The Gaia's read URL endpoint (`readURL`) -* The number of items to return when listing files (`pageSize`) -* The driver-specific settings +- The driver to use (`driver`) +- The Gaia's read URL endpoint (`readURL`) +- The number of items to return when listing files (`pageSize`) +- The driver-specific settings The data accepted on `POST` must contain a valid Hub configuration, for example: @@ -264,12 +255,12 @@ const GAIA_CONFIG_SCHEMA = { The same fields are returned on `GET` within a `config` object. #### Errors + If you do not supply a valid API key, both the `GET` and `POST` method fail with HTTP 403. -Only relevant Gaia hub config fields are set. If you `POST` invalid settings +Only relevant Gaia hub config fields are set. If you `POST` invalid settings values, you get an HTTP 400 error. - ## Example: Read and write driver settings Use the `/v1/admin/config` endpoint to read and write storage driver settings. To get the current driver settings, you would run: @@ -302,14 +293,16 @@ $ curl -H "Authorization: bearer $API_KEY" http://localhost:8009/v1/admin/config {"config":{"whitelist":["15hUKXg1URbQsmaEHKFV2vP9kCeCsT8gUu"]}} ``` -To set the whitelist, you must set the *entire* whitelist. To set the list, pass a command such as the following: +To set the whitelist, you must set the _entire_ whitelist. To set the list, pass a command such as the following: {% raw %} + ```bash $ export API_KEY="hello" $ curl -H "Authorization: bearer $API_KEY" -H 'Content-Type: application/json' -X POST --data-raw '{"whitelist": ["1KDcaHsYJqD7pwHtpDn6sujCVQCY2e1ktw", "15hUKXg1URbQsmaEHKFV2vP9kCeCsT8gUu"]}' http://localhost:8009/v1/admin/config {"message":"Config updated -- you should reload your Gaia hub now."} ``` + {% endraw %} ## View logs for the hub or admin service diff --git a/src/pages/storage/hello-hub-choice.md b/src/pages/storage/hello-hub-choice.md index 9eb8ff33..dc7a745b 100644 --- a/src/pages/storage/hello-hub-choice.md +++ b/src/pages/storage/hello-hub-choice.md @@ -1,7 +1,5 @@ --- - -description: "Storing user data with Blockstack" - +description: 'Storing user data with Blockstack' --- # Hello hub choice tutorial @@ -22,23 +20,23 @@ In this section, you build an initial React.js application called `hello-hub-cho 1. Create the `hello-hub-choice` directory. - ```bash - mkdir hello-hub-choice - ``` + ```bash + mkdir hello-hub-choice + ``` 2. Change into your new directory. - ```bash - cd hello-hub-choice - ``` + ```bash + cd hello-hub-choice + ``` 3. Use Yeoman and the Blockstack application generator to create your initial `hello-hub-choice` application. - ```bash - yo blockstack - ``` + ```bash + yo blockstack + ``` - You should see several interactive prompts. + You should see several interactive prompts. {% raw %} @@ -53,15 +51,17 @@ In this section, you build an initial React.js application called `hello-hub-cho 4. Respond to the prompts to populate the initial app. - After the process completes successfully, you see a prompt similar to the following: + After the process completes successfully, you see a prompt similar to the following: - {% raw %} - ```bash - ... + {% raw %} + + ```bash + ... create public/icon-192x192.png create public/index.html create public/robots.txt create public/manifest.json + ``` Im all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself. @@ -82,19 +82,18 @@ In this section, you build an initial React.js application called `hello-hub-cho npm install blockstack@18.3.0 ``` - Depending on your environment you may have some problems with the `npm` packages. Go ahead and fix these before continuing to the next section. ## Task 2. Start the server and view the application When you start the server, it will create a Node.js server, start it locally, -and open your browser `http://localhost:5000`. From the root of your new application directory: +and open your browser `http://localhost:5000`. From the root of your new application directory: 1. Start the application server. - ```bash - npm run start - ``` + ```bash + npm run start + ``` 2. Choose **Allow**. @@ -108,7 +107,7 @@ and open your browser `http://localhost:5000`. From the root of your new applic ## Task 3: Enable hub selection -By default, the app generator assumes you want to use the default flow `redirectToSignIn()` method. In this section, you replace that method and use the `makeAuthRequest()` method instead. The `makeAuthRequest()` method takes the following parameters: +By default, the app generator assumes you want to use the default flow `redirectToSignIn()` method. In this section, you replace that method and use the `makeAuthRequest()` method instead. The `makeAuthRequest()` method takes the following parameters: @@ -150,41 +149,40 @@ To replace the default login, do the following: 3. Replace `redirectToSignIn()` method with the `blockstack.UserSession.redirectToSignInWithAuthRequest(authRequest)` method. ```javascript - var userSession = new UserSession() - userSession.redirectToSignInWithAuthRequest(authRequest) + var userSession = new UserSession(); + userSession.redirectToSignInWithAuthRequest(authRequest); ``` The `authRequest` is the authentication request generated by `makeAuthRequest()` method. 4. Immediately above the method you just added and below the `event.preventDefault()` method, construct a String `const` for the `authRequest`: - ``` - const authRequest = userSession.makeAuthRequest( - userSession.generateAndStoreTransitKey(), - 'http://localhost:5000/', - 'http://localhost:5000/manifest.json', - ['store_write', 'publish_data'], - 'http://localhost:5000/', - blockstack.nextHour().getTime(), { - solicitGaiaHubUrl: true - } // new options param - ); - ``` + ``` + const authRequest = userSession.makeAuthRequest( + userSession.generateAndStoreTransitKey(), + 'http://localhost:5000/', + 'http://localhost:5000/manifest.json', + ['store_write', 'publish_data'], + 'http://localhost:5000/', + blockstack.nextHour().getTime(), { + solicitGaiaHubUrl: true + } // new options param + ); + ``` - {% include note.html content="If your app is running a different port than 500, enter that port instead. " %} + {% include note.html content="If your app is running a different port than 500, enter that port instead. " %} The extra `solicitGaiaHubUrl` parameter of `true` will cause the Blockstack Browser to prompt new identity creators for a storage hub URL. 5. Save and close the `public/app.js` file. 6. Make sure your app rebuilds cleanly. - ## Task 4: Try the new authentication flow Try your new authentication code. 1. Refresh the client at `http://localhost:5000/`. -2. Click *Sign in with Blockstack*. +2. Click _Sign in with Blockstack_. The Blockstack Browser prompts you to sign in. I you are _not already authenticated_ with the browser, you should see the following: @@ -241,20 +239,25 @@ If you want to create specific sign-up flows for your DApp, you can pass a prese do this if you have a corporate client whose employees would all like to use your application with a company-run Gaia hub. -To suggest a Gaia hub URL, provide an additional `recommendedGaiaHubUrl` value +To suggest a Gaia hub URL, provide an additional `recommendedGaiaHubUrl` value alongside the `solicitGaiaHubUrl`, for example: ```javascript -import { - makeAuthRequest, - redirectToSignInWithAuthRequest -} from 'blockstack'; +import { makeAuthRequest, redirectToSignInWithAuthRequest } from 'blockstack'; -var userSession = new UserSession() -const authRequest = userSession.makeAuthRequest(undefined, undefined, undefined, undefined, undefined, undefined, { - solicitGaiaHubUrl: true, - recommendedGaiaHubUrl: 'https://mygaiahub.com' -}); +var userSession = new UserSession(); +const authRequest = userSession.makeAuthRequest( + undefined, + undefined, + undefined, + undefined, + undefined, + undefined, + { + solicitGaiaHubUrl: true, + recommendedGaiaHubUrl: 'https://mygaiahub.com', + } +); const authRequest = userSession.makeAuthRequest( generateAndStoreTransitKey(), @@ -262,9 +265,10 @@ const authRequest = userSession.makeAuthRequest( 'http://localhost:5000/manifest.json', ['store_write', 'publish_data'], 'http://localhost:5000/', - nextHour().getTime(), { + nextHour().getTime(), + { solicitGaiaHubUrl: true, //new options param - recommendedGaiaHubUrl: 'https://mygaiahub.com' // new options param + recommendedGaiaHubUrl: 'https://mygaiahub.com', // new options param } ); @@ -275,6 +279,6 @@ Passing these parameters changes the storage hub URL prompt to the following:  - ## Related information + [`makeAuthRequest()`](https://blockstack.github.io/blockstack.js/#makeauthrequest) method diff --git a/src/pages/storage/hub-operation.md b/src/pages/storage/hub-operation.md index e8267c1e..1f9a72b2 100644 --- a/src/pages/storage/hub-operation.md +++ b/src/pages/storage/hub-operation.md @@ -1,19 +1,19 @@ --- - -description: "Storing user data with Blockstack" +description: 'Storing user data with Blockstack' redirect_from: -- /storage/hello-hub-choice.html - + - /storage/hello-hub-choice.html --- + # Understand hub operation + This page describes the considerations hub operators must take into account when creating and operating a Gaia storage hub. ## Configuration files You should store a JSON configuration file either in the top-level directory of the hub server. Alternatively, you can specify a file location using the -`CONFIG_PATH` environment variable. The following is an example configuration file for Amazon S3: +`CONFIG_PATH` environment variable. The following is an example configuration file for Amazon S3: ```json { @@ -24,8 +24,8 @@ the hub server. Alternatively, you can specify a file location using the "pageSize": 20, "bucket": "YOUR_BUCKET_NAME", "awsCredentials": { - "accessKeyID": "YOUR_ACCESS_KEY", - "secretAccessKey": "YOUR_SECRET_KEY" + "accessKeyID": "YOUR_ACCESS_KEY", + "secretAccessKey": "YOUR_SECRET_KEY" }, "argsTransport": { "level": "debug", @@ -74,7 +74,6 @@ Past users could configure this setting as a crude spam-control mechanism. However, for the smoothest operation of your Gaia hub, set the `proofsConfig.proofsRequired` value to `0`. - ## Open or private hubs You can configure an open-membership storage hub or a private storage hub. An open-membership hub, as it sounds, allows any user to use the hub service. A private hub limits the use of the service. In this section, you learn about configuring each type. @@ -94,7 +93,7 @@ via _whitelisting_ the addresses allowed to write files. Recall that each applic support application storage, your configuration must add to the whitelist each application you wish to use. Alternatively, the user's client can use the authentication scheme and generate -an association token for each app. The user should whitelist her address, and -use her associated private key to sign each app's association token. This +an association token for each app. The user should whitelist her address, and +use her associated private key to sign each app's association token. This removes the need to whitelist each application, but with the caveat that the user needs to take care that her association tokens do not get misused. diff --git a/src/pages/storage/overview.md b/src/pages/storage/overview.md index fe165420..b8bad167 100644 --- a/src/pages/storage/overview.md +++ b/src/pages/storage/overview.md @@ -1,8 +1,7 @@ --- - -description: "Storing user data with Blockstack" - +description: 'Storing user data with Blockstack' --- + # A decentralized storage architecture The Blockstack Network stores application data using a storage system called @@ -12,7 +11,7 @@ ensures that Blockstack applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. -## Understand Gaia in the Blockstack architecture +## Understand Gaia in the Blockstack architecture The following diagram depicts the Blockstack architecture and Gaia's place in it: @@ -20,7 +19,7 @@ The following diagram depicts the Blockstack architecture and Gaia's place in it ## User control or how is Gaia decentralized? -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service +A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider.  @@ -32,8 +31,8 @@ The control of user data lies in the way that user data is accessed. When an app 1. Fetch the `zonefile` for `alice.id`. 2. Read her profile URL from her `zonefile`. 3. Fetch Alice's profile. -4. _Verify_ that the profile is signed by `alice.id`'s key -5. Read the `gaiaHubUrl` (e.g. `https://gaia.alice.org/`) out of the profile +4. _Verify_ that the profile is signed by `alice.id`'s key +5. Read the `gaiaHubUrl` (e.g. `https://gaia.alice.org/`) out of the profile 6. Fetch the file from `https://gaia.alice.org/data.txt`. Because `alice.id` has access to her zonefile, she can change where her profile is stored. For example, she may do this if the current profile's service provider or storage is compromised. To change where her profile is stored, she changes her Gaia hub URL to another Gaia hub URL. If a user has sufficient compute and storage resources, a user may run their own Gaia Storage System and bypass a commercial Gaia hub provider all together. @@ -41,7 +40,7 @@ Because `alice.id` has access to her zonefile, she can change where her profile {% include note.html content="Users with existing identities cannot yet migrate their data from one hub to another." %} -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Blockstack authentication flow](http://blockstack.github.io/blockstack.js/index.html) provides Alice's chosen application root URL to the application. This authentication flow _is also_ within Alice's control because Alice's browser _must_ generate the authentication response. +Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Blockstack authentication flow](http://blockstack.github.io/blockstack.js/index.html) provides Alice's chosen application root URL to the application. This authentication flow _is also_ within Alice's control because Alice's browser _must_ generate the authentication response. ## Understand data storage @@ -51,7 +50,7 @@ Client libraries (such as `blockstack.js`) are capable of providing these guaran ## Gaia versus other storage systems -Here's how Gaia stacks up against other decentralized storage systems. Features +Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. diff --git a/src/pages/storage/write-to-read.md b/src/pages/storage/write-to-read.md index d9f33552..87cb5f90 100644 --- a/src/pages/storage/write-to-read.md +++ b/src/pages/storage/write-to-read.md @@ -1,18 +1,16 @@ --- - -description: "Storing user data with Blockstack" - +description: 'Storing user data with Blockstack' --- + # Storage write and read Once a user authenticates and a DApp obtains authentication, the application interacts with Gaia through the blockstack.js library. There are two simple methods for working with data in Gaia hub: the `putFile()` and `getFile()` methods. This section goes into greater detail about the methods, how they interact with a hub, and how to use them. - ## Write-to and Read-from URL Guarantees Gaia is built on a driver model that supports many storage services. So, with very few lines of code, you can interact with providers on Amazon S3, Dropbox, -and so forth. The simple `getFile()` and `putFile()` interfaces are kept simple +and so forth. The simple `getFile()` and `putFile()` interfaces are kept simple because Blockstack assumes and wants to encourage a community of open-source-data-management libraries. @@ -23,7 +21,7 @@ be able to read from the `https://myreads.com/foo/bar` URL. Note that, while the prefix in the write-to url (for example,`myhub.service.org/store`) and the read-from URL (`https://myreads.com`) are different, the `foo/bar` suffixes are the same. -By default, `putFile()` encrypts information while `getFile()` decrypts it by default. Data stored in an encrypted format means only the user that stored it can view it. For applications that want other users to view data, the application should set the `encrypt` option to `false`. And, corresponding, the `decrypt` option on `getFile()` should also be `false`. +By default, `putFile()` encrypts information while `getFile()` decrypts it by default. Data stored in an encrypted format means only the user that stored it can view it. For applications that want other users to view data, the application should set the `encrypt` option to `false`. And, corresponding, the `decrypt` option on `getFile()` should also be `false`. Consistent, identical suffixes allow an application to know _exactly_ where a written file can be read from, given the read prefix. The Gaia service defines a `hub_info` endpoint to obtain that read prefix: @@ -54,7 +52,6 @@ https://myservice.org/store/1DHvWDj834zPAkwMhpXdYbCYh4PomwQfzz/0/profile.json When you use the `putFile()` method it takes the user data and POSTs it to the user's Gaia storage hub. The data POSTs directly to the hub, the blockchain is not used and no data is stored there. The limit on file upload is currently 25mb. - ## Address-based access-control Access control in a Gaia storage hub is performed on a per-address basis.](https://www.f
- If you receive another **Your connection is not private** dialogs, take the option to proceed to your domain. The *Not secure* message should no longer appear in the browser bar. If the message does appear, try waiting a few minutes for your recent changes to propagate across the net domain servers. Then, refresh the page.
+ If you receive another **Your connection is not private** dialogs, take the option to proceed to your domain. The _Not secure_ message should no longer appear in the browser bar. If the message does appear, try waiting a few minutes for your recent changes to propagate across the net domain servers. Then, refresh the page.
-9. Check the SSL certificate for your hub.
+8. Check the SSL certificate for your hub.
Each browser has its own check procedure, for example, Chrome:
@@ -354,7 +352,6 @@ These instructions assume you have already created a free <a href=){kind=link}
-
## Task 12: Set up SSL
If you've configured a domain to point to your Gaia hub, then it's highly
diff --git a/src/pages/storage/gaia-admin.md b/src/pages/storage/gaia-admin.md
index 6620aee4..bc164ffd 100644
--- a/src/pages/storage/gaia-admin.md
+++ b/src/pages/storage/gaia-admin.md
@@ -1,9 +1,9 @@
---
-
-description: ){kind=link}
-
@@ -150,41 +149,40 @@ To replace the default login, do the following:
3. Replace `redirectToSignIn()` method with the `blockstack.UserSession.redirectToSignInWithAuthRequest(authRequest)` method.
```javascript
- var userSession = new UserSession()
- userSession.redirectToSignInWithAuthRequest(authRequest)
+ var userSession = new UserSession();
+ userSession.redirectToSignInWithAuthRequest(authRequest);
```
The `authRequest` is the authentication request generated by `makeAuthRequest()` method.
4. Immediately above the method you just added and below the `event.preventDefault()` method, construct a String `const` for the `authRequest`:
- ```
- const authRequest = userSession.makeAuthRequest(
- userSession.generateAndStoreTransitKey(),
- 'http://localhost:5000/',
- 'http://localhost:5000/manifest.json',
- ['store_write', 'publish_data'],
- 'http://localhost:5000/',
- blockstack.nextHour().getTime(), {
- solicitGaiaHubUrl: true
- } // new options param
- );
- ```
+ ```
+ const authRequest = userSession.makeAuthRequest(
+ userSession.generateAndStoreTransitKey(),
+ 'http://localhost:5000/',
+ 'http://localhost:5000/manifest.json',
+ ['store_write', 'publish_data'],
+ 'http://localhost:5000/',
+ blockstack.nextHour().getTime(), {
+ solicitGaiaHubUrl: true
+ } // new options param
+ );
+ ```
- {% include note.html content="If your app is running a different port than
500, enter that port instead. " %} + {% include note.html content="If your app is running a different port than500, enter that port instead. " %} The extra `solicitGaiaHubUrl` parameter of `true` will cause the Blockstack Browser to prompt new identity creators for a storage hub URL. 5. Save and close the `public/app.js` file. 6. Make sure your app rebuilds cleanly. - ## Task 4: Try the new authentication flow Try your new authentication code. 1. Refresh the client at `http://localhost:5000/`. -2. Click *Sign in with Blockstack*. +2. Click _Sign in with Blockstack_. The Blockstack Browser prompts you to sign in. I you are _not already authenticated_ with the browser, you should see the following: @@ -241,20 +239,25 @@ If you want to create specific sign-up flows for your DApp, you can pass a prese do this if you have a corporate client whose employees would all like to use your application with a company-run Gaia hub. -To suggest a Gaia hub URL, provide an additional `recommendedGaiaHubUrl` value +To suggest a Gaia hub URL, provide an additional `recommendedGaiaHubUrl` value alongside the `solicitGaiaHubUrl`, for example: ```javascript -import { - makeAuthRequest, - redirectToSignInWithAuthRequest -} from 'blockstack'; +import { makeAuthRequest, redirectToSignInWithAuthRequest } from 'blockstack'; -var userSession = new UserSession() -const authRequest = userSession.makeAuthRequest(undefined, undefined, undefined, undefined, undefined, undefined, { - solicitGaiaHubUrl: true, - recommendedGaiaHubUrl: 'https://mygaiahub.com' -}); +var userSession = new UserSession(); +const authRequest = userSession.makeAuthRequest( + undefined, + undefined, + undefined, + undefined, + undefined, + undefined, + { + solicitGaiaHubUrl: true, + recommendedGaiaHubUrl: 'https://mygaiahub.com', + } +); const authRequest = userSession.makeAuthRequest( generateAndStoreTransitKey(), @@ -262,9 +265,10 @@ const authRequest = userSession.makeAuthRequest( 'http://localhost:5000/manifest.json', ['store_write', 'publish_data'], 'http://localhost:5000/', - nextHour().getTime(), { + nextHour().getTime(), + { solicitGaiaHubUrl: true, //new options param - recommendedGaiaHubUrl: 'https://mygaiahub.com' // new options param + recommendedGaiaHubUrl: 'https://mygaiahub.com', // new options param } ); @@ -275,6 +279,6 @@ Passing these parameters changes the storage hub URL prompt to the following:  - ## Related information + [`makeAuthRequest()`](https://blockstack.github.io/blockstack.js/#makeauthrequest) method diff --git a/src/pages/storage/hub-operation.md b/src/pages/storage/hub-operation.md index e8267c1e..1f9a72b2 100644 --- a/src/pages/storage/hub-operation.md +++ b/src/pages/storage/hub-operation.md @@ -1,19 +1,19 @@ --- - -description: "Storing user data with Blockstack" +description: 'Storing user data with Blockstack' redirect_from: -- /storage/hello-hub-choice.html - + - /storage/hello-hub-choice.html --- + # Understand hub operation + This page describes the considerations hub operators must take into account when creating and operating a Gaia storage hub. ## Configuration files You should store a JSON configuration file either in the top-level directory of the hub server. Alternatively, you can specify a file location using the -`CONFIG_PATH` environment variable. The following is an example configuration file for Amazon S3: +`CONFIG_PATH` environment variable. The following is an example configuration file for Amazon S3: ```json { @@ -24,8 +24,8 @@ the hub server. Alternatively, you can specify a file location using the "pageSize": 20, "bucket": "YOUR_BUCKET_NAME", "awsCredentials": { - "accessKeyID": "YOUR_ACCESS_KEY", - "secretAccessKey": "YOUR_SECRET_KEY" + "accessKeyID": "YOUR_ACCESS_KEY", + "secretAccessKey": "YOUR_SECRET_KEY" }, "argsTransport": { "level": "debug", @@ -74,7 +74,6 @@ Past users could configure this setting as a crude spam-control mechanism. However, for the smoothest operation of your Gaia hub, set the `proofsConfig.proofsRequired` value to `0`. - ## Open or private hubs You can configure an open-membership storage hub or a private storage hub. An open-membership hub, as it sounds, allows any user to use the hub service. A private hub limits the use of the service. In this section, you learn about configuring each type. @@ -94,7 +93,7 @@ via _whitelisting_ the addresses allowed to write files. Recall that each applic support application storage, your configuration must add to the whitelist each application you wish to use. Alternatively, the user's client can use the authentication scheme and generate -an association token for each app. The user should whitelist her address, and -use her associated private key to sign each app's association token. This +an association token for each app. The user should whitelist her address, and +use her associated private key to sign each app's association token. This removes the need to whitelist each application, but with the caveat that the user needs to take care that her association tokens do not get misused. diff --git a/src/pages/storage/overview.md b/src/pages/storage/overview.md index fe165420..b8bad167 100644 --- a/src/pages/storage/overview.md +++ b/src/pages/storage/overview.md @@ -1,8 +1,7 @@ --- - -description: "Storing user data with Blockstack" - +description: 'Storing user data with Blockstack' --- + # A decentralized storage architecture The Blockstack Network stores application data using a storage system called @@ -12,7 +11,7 @@ ensures that Blockstack applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. -## Understand Gaia in the Blockstack architecture +## Understand Gaia in the Blockstack architecture The following diagram depicts the Blockstack architecture and Gaia's place in it: @@ -20,7 +19,7 @@ The following diagram depicts the Blockstack architecture and Gaia's place in it ## User control or how is Gaia decentralized? -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service +A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider.  @@ -32,8 +31,8 @@ The control of user data lies in the way that user data is accessed. When an app 1. Fetch the `zonefile` for `alice.id`. 2. Read her profile URL from her `zonefile`. 3. Fetch Alice's profile. -4. _Verify_ that the profile is signed by `alice.id`'s key -5. Read the `gaiaHubUrl` (e.g. `https://gaia.alice.org/`) out of the profile +4. _Verify_ that the profile is signed by `alice.id`'s key +5. Read the `gaiaHubUrl` (e.g. `https://gaia.alice.org/`) out of the profile 6. Fetch the file from `https://gaia.alice.org/data.txt`. Because `alice.id` has access to her zonefile, she can change where her profile is stored. For example, she may do this if the current profile's service provider or storage is compromised. To change where her profile is stored, she changes her Gaia hub URL to another Gaia hub URL. If a user has sufficient compute and storage resources, a user may run their own Gaia Storage System and bypass a commercial Gaia hub provider all together. @@ -41,7 +40,7 @@ Because `alice.id` has access to her zonefile, she can change where her profile {% include note.html content="Users with existing identities cannot yet migrate their data from one hub to another." %} -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Blockstack authentication flow](http://blockstack.github.io/blockstack.js/index.html) provides Alice's chosen application root URL to the application. This authentication flow _is also_ within Alice's control because Alice's browser _must_ generate the authentication response. +Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Blockstack authentication flow](http://blockstack.github.io/blockstack.js/index.html) provides Alice's chosen application root URL to the application. This authentication flow _is also_ within Alice's control because Alice's browser _must_ generate the authentication response. ## Understand data storage @@ -51,7 +50,7 @@ Client libraries (such as `blockstack.js`) are capable of providing these guaran ## Gaia versus other storage systems -Here's how Gaia stacks up against other decentralized storage systems. Features +Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity.diff --git a/src/pages/storage/write-to-read.md b/src/pages/storage/write-to-read.md index d9f33552..87cb5f90 100644 --- a/src/pages/storage/write-to-read.md +++ b/src/pages/storage/write-to-read.md @@ -1,18 +1,16 @@ --- - -description: "Storing user data with Blockstack" - +description: 'Storing user data with Blockstack' --- + # Storage write and read Once a user authenticates and a DApp obtains authentication, the application interacts with Gaia through the blockstack.js library. There are two simple methods for working with data in Gaia hub: the `putFile()` and `getFile()` methods. This section goes into greater detail about the methods, how they interact with a hub, and how to use them. - ## Write-to and Read-from URL Guarantees Gaia is built on a driver model that supports many storage services. So, with very few lines of code, you can interact with providers on Amazon S3, Dropbox, -and so forth. The simple `getFile()` and `putFile()` interfaces are kept simple +and so forth. The simple `getFile()` and `putFile()` interfaces are kept simple because Blockstack assumes and wants to encourage a community of open-source-data-management libraries. @@ -23,7 +21,7 @@ be able to read from the `https://myreads.com/foo/bar` URL. Note that, while the prefix in the write-to url (for example,`myhub.service.org/store`) and the read-from URL (`https://myreads.com`) are different, the `foo/bar` suffixes are the same. -By default, `putFile()` encrypts information while `getFile()` decrypts it by default. Data stored in an encrypted format means only the user that stored it can view it. For applications that want other users to view data, the application should set the `encrypt` option to `false`. And, corresponding, the `decrypt` option on `getFile()` should also be `false`. +By default, `putFile()` encrypts information while `getFile()` decrypts it by default. Data stored in an encrypted format means only the user that stored it can view it. For applications that want other users to view data, the application should set the `encrypt` option to `false`. And, corresponding, the `decrypt` option on `getFile()` should also be `false`. Consistent, identical suffixes allow an application to know _exactly_ where a written file can be read from, given the read prefix. The Gaia service defines a `hub_info` endpoint to obtain that read prefix: @@ -54,7 +52,6 @@ https://myservice.org/store/1DHvWDj834zPAkwMhpXdYbCYh4PomwQfzz/0/profile.json When you use the `putFile()` method it takes the user data and POSTs it to the user's Gaia storage hub. The data POSTs directly to the hub, the blockchain is not used and no data is stored there. The limit on file upload is currently 25mb. - ## Address-based access-control Access control in a Gaia storage hub is performed on a per-address basis.