kylefang/stacks.js
1
0
Fork 0
mirror of https://github.com/alexgo-io/stacks.js.git synced 2026-05-13 12:27:39 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
d7e66c68ea7193952ba496fb87691c8c5b008a91
stacks.js/docs/index.html
Ken d7e66c68ea Make API backward compatible with v18.
2019-02-14 15:56:05 -05:00

6452 lines
183 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html>
<head>
<meta charset='utf-8' />
<title>blockstack 19.0.0-alpha.4 | Documentation</title>
<meta name='viewport' content='width=device-width,initial-scale=1'>
<link href='assets/bass.css' type='text/css' rel='stylesheet' />
<link href='assets/style.css' type='text/css' rel='stylesheet' />
<link href='assets/github.css' type='text/css' rel='stylesheet' />
<link href='assets/split.css' type='text/css' rel='stylesheet' />
<meta name='description' content='The Blockstack Javascript library for authentication, identity, and storage.'>
</head>
<body class='documentation m0'>
<div class='flex'>
<div id='split-left' class='overflow-auto fs0 height-viewport-100'>
<div class='py1 px2'>
<h3 class='mb0 no-anchor'>blockstack</h3>
<div class='mb1'><code>19.0.0-alpha.4</code></div>
<input
placeholder='Filter'
id='filter-input'
class='col12 block input'
type='text' />
<div id='toc'>
<ul class='list-reset h5 py1-ul'>
<li><a
href='#authentication'
class="h5 bold black caps">
Authentication
</a>
</li>
<li><a
href='#appconfig'
class=" toggle-sibling">
AppConfig
<span class='icon'>▸</span>
</a>
<div class='toggle-target display-none'>
<ul class='list-reset py1-ul pl1'>
<li class='h5'><span>Instance members</span></li>
<li><a
href='#appconfigappdomain'
class='regular pre-open'>
#appDomain
</a></li>
<li><a
href='#appconfigscopes'
class='regular pre-open'>
#scopes
</a></li>
<li><a
href='#appconfigredirectpath'
class='regular pre-open'>
#redirectPath
</a></li>
<li><a
href='#appconfigmanifestpath'
class='regular pre-open'>
#manifestPath
</a></li>
<li><a
href='#appconfigcorenode'
class='regular pre-open'>
#coreNode
</a></li>
<li><a
href='#appconfigauthenticatorurl'
class='regular pre-open'>
#authenticatorURL
</a></li>
<li><a
href='#appconfigredirecturi'
class='regular pre-open'>
#redirectURI
</a></li>
<li><a
href='#appconfigmanifesturi'
class='regular pre-open'>
#manifestURI
</a></li>
</ul>
</div>
</li>
<li><a
href='#usersession'
class=" toggle-sibling">
UserSession
<span class='icon'>▸</span>
</a>
<div class='toggle-target display-none'>
<ul class='list-reset py1-ul pl1'>
<li class='h5'><span>Instance members</span></li>
<li><a
href='#usersessionredirecttosignin'
class='regular pre-open'>
#redirectToSignIn
</a></li>
<li><a
href='#usersessionredirecttosigninwithauthrequest'
class='regular pre-open'>
#redirectToSignInWithAuthRequest
</a></li>
<li><a
href='#usersessiongenerateandstoretransitkey'
class='regular pre-open'>
#generateAndStoreTransitKey
</a></li>
<li><a
href='#usersessiongetauthresponsetoken'
class='regular pre-open'>
#getAuthResponseToken
</a></li>
<li><a
href='#usersessionissigninpending'
class='regular pre-open'>
#isSignInPending
</a></li>
<li><a
href='#usersessionisusersignedin'
class='regular pre-open'>
#isUserSignedIn
</a></li>
<li><a
href='#usersessionhandlependingsignin'
class='regular pre-open'>
#handlePendingSignIn
</a></li>
<li><a
href='#usersessionloaduserdata'
class='regular pre-open'>
#loadUserData
</a></li>
<li><a
href='#usersessionsignuserout'
class='regular pre-open'>
#signUserOut
</a></li>
<li><a
href='#usersessionencryptcontent'
class='regular pre-open'>
#encryptContent
</a></li>
<li><a
href='#usersessiondecryptcontent'
class='regular pre-open'>
#decryptContent
</a></li>
<li><a
href='#usersessionputfile'
class='regular pre-open'>
#putFile
</a></li>
<li><a
href='#usersessiongetfile'
class='regular pre-open'>
#getFile
</a></li>
<li><a
href='#usersessionlistfiles'
class='regular pre-open'>
#listFiles
</a></li>
</ul>
</div>
</li>
<li><a
href='#sessiondatastore'
class="">
SessionDataStore
</a>
</li>
<li><a
href='#instancedatastore'
class="">
InstanceDataStore
</a>
</li>
<li><a
href='#localstoragestore'
class="">
LocalStorageStore
</a>
</li>
<li><a
href='#isusersignedin'
class="">
isUserSignedIn
</a>
</li>
<li><a
href='#redirecttosignin'
class="">
redirectToSignIn
</a>
</li>
<li><a
href='#redirecttosigninwithauthrequest'
class="">
redirectToSignInWithAuthRequest
</a>
</li>
<li><a
href='#issigninpending'
class="">
isSignInPending
</a>
</li>
<li><a
href='#handlependingsignin'
class="">
handlePendingSignIn
</a>
</li>
<li><a
href='#loaduserdata'
class="">
loadUserData
</a>
</li>
<li><a
href='#signuserout'
class="">
signUserOut
</a>
</li>
<li><a
href='#profiles'
class="h5 bold black caps">
Profiles
</a>
</li>
<li><a
href='#extractprofile'
class="">
extractProfile
</a>
</li>
<li><a
href='#wrapprofiletoken'
class="">
wrapProfileToken
</a>
</li>
<li><a
href='#signprofiletoken'
class="">
signProfileToken
</a>
</li>
<li><a
href='#verifyprofiletoken'
class="">
verifyProfileToken
</a>
</li>
<li><a
href='#validateproofs'
class="">
validateProofs
</a>
</li>
<li><a
href='#lookupprofile'
class="">
lookupProfile
</a>
</li>
<li><a
href='#storage'
class="h5 bold black caps">
Storage
</a>
</li>
<li><a
href='#getappbucketurl'
class="">
getAppBucketUrl
</a>
</li>
<li><a
href='#getuserappfileurl'
class="">
getUserAppFileUrl
</a>
</li>
<li><a
href='#getfile'
class="">
getFile
</a>
</li>
<li><a
href='#putfile'
class="">
putFile
</a>
</li>
<li><a
href='#encryptcontent'
class="">
encryptContent
</a>
</li>
<li><a
href='#decryptcontent'
class="">
decryptContent
</a>
</li>
<li><a
href='#listfiles'
class="">
listFiles
</a>
</li>
<li><a
href='#getauthresponsetoken'
class="">
getAuthResponseToken
</a>
</li>
<li><a
href='#getnameprice'
class="">
getNamePrice
</a>
</li>
<li><a
href='#getnamespaceprice'
class="">
getNamespacePrice
</a>
</li>
<li><a
href='#getgraceperiod'
class="">
getGracePeriod
</a>
</li>
<li><a
href='#getnamesowned'
class="">
getNamesOwned
</a>
</li>
<li><a
href='#getnamespaceburnaddress'
class="">
getNamespaceBurnAddress
</a>
</li>
<li><a
href='#getnameinfo'
class="">
getNameInfo
</a>
</li>
<li><a
href='#getnamespaceinfo'
class="">
getNamespaceInfo
</a>
</li>
<li><a
href='#getzonefile'
class="">
getZonefile
</a>
</li>
<li><a
href='#getaccountstatus'
class="">
getAccountStatus
</a>
</li>
<li><a
href='#getaccounthistorypage'
class="">
getAccountHistoryPage
</a>
</li>
<li><a
href='#getaccountat'
class="">
getAccountAt
</a>
</li>
<li><a
href='#getaccounttokens'
class="">
getAccountTokens
</a>
</li>
<li><a
href='#getaccountbalance'
class="">
getAccountBalance
</a>
</li>
<li><a
href='#estimatetokentransfer'
class="">
estimateTokenTransfer
</a>
</li>
</ul>
</div>
<div class='mt1 h6 quiet'>
<a href='https://documentation.js.org/reading-documentation.html'>Need help reading this?</a>
</div>
</div>
</div>
<div id='split-right' class='relative overflow-auto height-viewport-100'>
<div class='keyline-top-not py2'>
<section class='py2 clearfix'>
<h2 id='authentication' class='mt0'>
Authentication
</h2>
<p>Blockstack Authentication provides single sign on and authentication without third parties or remote servers. Blockstack Authentication is a bearer token-based authentication system. From an app user's perspective, it functions similar to legacy third-party authentication techniques that they're familiar with. For an app developer, the flow is a bit different from the typical client-server flow of centralized sign in services (e.g., OAuth). Rather, with Blockstack, the authentication flow happens entirely client-side.</p>
<h2>Quickstart</h2>
<p>1) Install <code>blockstack.js</code>:</p>
<pre class='hljs'>npm install blockstack --save</pre>
<p>2) Import Blockstack into your project</p>
<pre class='hljs'><span class="hljs-keyword">import</span> * <span class="hljs-keyword">as</span> blockstack <span class="hljs-keyword">from</span> <span class="hljs-string">'blockstack'</span></pre>
<p>3) Wire up a sign in button</p>
<pre class='hljs'><span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'signin-button'</span>).addEventListener(<span class="hljs-string">'click'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
blockstack.redirectToSignIn()
})</pre>
<p>4) Wire up a sign out button</p>
<pre class='hljs'><span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'signout-button'</span>).addEventListener(<span class="hljs-string">'click'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
blockstack.signUserOut(<span class="hljs-built_in">window</span>.location.origin)
})</pre>
<p>5) Include the logic to (a) load user data (b) handle the auth response</p>
<pre class='hljs'><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">showProfile</span>(<span class="hljs-params">profile</span>) </span>{
<span class="hljs-keyword">var</span> person = <span class="hljs-keyword">new</span> blockstack.Person(profile)
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'heading-name'</span>).innerHTML = person.name()
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'avatar-image'</span>).setAttribute(<span class="hljs-string">'src'</span>, person.avatarUrl())
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'section-1'</span>).style.display = <span class="hljs-string">'none'</span>
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'section-2'</span>).style.display = <span class="hljs-string">'block'</span>
}
<span class="hljs-keyword">if</span> (blockstack.isUserSignedIn()) {
 <span class="hljs-keyword">const</span> userData = blockstack.loadUserData()
showProfile(userData.profile)
} <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (blockstack.isSignInPending()) {
blockstack.handlePendingSignIn()
.then(<span class="hljs-function"><span class="hljs-params">userData</span> =&gt;</span> {
showProfile(userData.profile)
})
}</pre>
<p>6) Create a <code>manifest.json</code> file</p>
<pre class='hljs'>{
<span class="hljs-attr">"name"</span>: <span class="hljs-string">"Hello, Blockstack"</span>,
<span class="hljs-attr">"start_url"</span>: <span class="hljs-string">"localhost:5000"</span>,
<span class="hljs-attr">"description"</span>: <span class="hljs-string">"A simple demo of Blockstack Auth"</span>,
<span class="hljs-attr">"icons"</span>: [{
<span class="hljs-attr">"src"</span>: <span class="hljs-string">"https://helloblockstack.com/icon-192x192.png"</span>,
<span class="hljs-attr">"sizes"</span>: <span class="hljs-string">"192x192"</span>,
<span class="hljs-attr">"type"</span>: <span class="hljs-string">"image/png"</span>
}]
}</pre>
<p>Make sure your <code>manifest.json</code> file has appropriate CORS headers so that it can
be fetched via an http <code>GET</code> from any origin.</p>
<p>7) Serve your application</p>
<h2>User flow</h2>
<p>What follows is a walk through of the experience of a user, Alice, signing in to your app with Blockstack.</p>
<p>First, Alice clicks the "Sign in with Blockstack" button on your app. She is redirected to her copy of the Blockstack Browser. The Blockstack Browser shows Alice an approval dialog with information about your app including:</p>
<ul>
<li>The origin your app was served from</li>
<li>Your app's name</li>
<li>Your app's logo</li>
<li>The types of permissions and data your app is requesting</li>
</ul>
<p>Alice can choose to authenticate as one of her Blockstack IDs by selecting the ID and clicking the Approve button.</p>
<p>When she clicks approve, she's redirected back to your app. Your app gets cryptographic proof that she is who she claims to be, access to a dedicated bucket in her Gaia storage hub for your app to read and write its own data along with public information she's stored in her profile.</p>
<h2>Manifest file</h2>
<p>Blockstack apps have a manifest file based on the <a href="https://w3c.github.io/manifest/">W3C web app manifest specification</a>. The Blockstack Browser retrieves the manifest file from the app during the authentication process and displays some of the information in it such as the app name and icon to the user. The location of the app manifest file is specific in the authentication request token and <em>MUST</em> be on the same origin as the app requesting authentication.</p>
<p>Below is an example of a manifest file:</p>
<pre><code>{
"name": "Todo App",
"start_url": "http://blockstack-todos.appartisan.com",
"description": "A simple todo app build on blockstack",
"icons": [{
"src": "http://blockstack-todos.appartisan.com/logo.png",
"sizes": "400x400",
"type": "image/png"
}]
}
</code></pre>
<p>The manifest file <em>MUST</em> have <a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Cross-origin resource sharing (CORS) headers</a> that allow the manifest file to be fetched from any arbitrary source. This usually means returning:</p>
<pre><code>Access-Control-Allow-Origin: *
</code></pre>
<h2>Key pairs</h2>
<p>Blockstack Authentication makes extensive use of public key cryptography. As mentioned above, we use ECDSA with the secp256k1 curve. What follows is a description of the various public-private key pairs used in the authentication process including how they're generated, where they're used and to whom the private key is disclosed.</p>
<h3>Transit private key</h3>
<p>The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the Blockstack Browser to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. The public key that corresponds to the transit private key is stored in a single element array in the <code>public_keys</code> key of the authentication request token. The Blockstack Browser encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request.</p>
<h3>Blockstack ID Identity address private key</h3>
<p>The identity address private key is derived from the user's keychain phrase and is the private key of the Blockstack ID that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the Blockstack browser. This private key signs the authentication response token for an app to indicate that the user approves sign in to that app.</p>
<h3>App private key</h3>
<p>The app private key is an app-specific private key that is generated from the user's identity address private key using the <code>domain_name</code> as input. It is deterministic in that for a given Blockstack ID and <code>domain_name</code>, the same private key will be generated each time. The app private key is securely shared with the app on each authentication, encrypted by the Blockstack browser with the transit public key.</p>
<p>The app private key serves three functions.</p>
<ul>
<li>It is used to create the credentials that give an app access to the gaia hub storage bucket for that specific app.</li>
<li>It is used in the end-to-end encryption of files stored for the app on the user's gaia hub.</li>
<li>It serves as a cryptographic secret that apps can use to perform other cryptographic functions.</li>
</ul>
<h2>Scopes</h2>
<p>Scopes define the information and permissions an app requests from the
user during authentication. Requested scopes may be any of the following:</p>
<ul>
<li>
<p><code>store_write</code> - read and write data to the user's Gaia hub in an app-specific storage bucket</p>
</li>
<li>
<p><code>publish_data</code> - publish data so that other users of the app can discover and interact with the user</p>
</li>
<li>
<p><code>email</code> - requests the user's email if available</p>
<p> If no <code>scopes</code> array is provided to the <code>redirectToSignIn</code> or
<code>makeAuthRequest</code> functions, the default is to request <code>['store_write']</code>.</p>
</li>
</ul>
<h2>Authentication tokens</h2>
<p>The app and the Blockstack Browser communicate during the authentication flow by passing back and forth two tokens:</p>
<p>The requesting application sends the Blockstack Browser an authRequest token.
Once a user approves a sign in, the Blockstack Browser responds to the application with an authResponse token.</p>
<p>These tokens are <a href="https://jwt.io/">JSON Web Tokens</a>, and they are passed via URL query strings.</p>
<h3>JSON Web Token signatures</h3>
<p>Blockstack's authentication tokens are based on the <a href="https://tools.ietf.org/html/rfc7519">RFC 7519 OAuth JSON Web Token (JWT)</a> with additional support for the secp256k1 curve used by bitcoin and many other cryptocurrencies.</p>
<p>This signature algorithm is indicated by specifying <code>ES256K</code> in the token's <code>alg</code> key, specifying that the JWT signature uses ECDSA with the secp256k1 curve. We provide both <a href="https://github.com/blockstack/jsontokens-js">JavaScript</a> and <a href="https://github.com/blockstack/ruby-jwt-blockstack/tree/ruby-jwt-blockstack">Ruby</a> JWT libraries with support for this signing algorithm.</p>
<h3>Authentication request payload schema</h3>
<pre class='hljs'><span class="hljs-keyword">const</span> requestPayload = {
jti, <span class="hljs-comment">// UUID</span>
iat, <span class="hljs-comment">// JWT creation time in seconds</span>
exp, <span class="hljs-comment">// JWT expiration time in seconds</span>
iss, <span class="hljs-comment">// legacy decentralized identifier generated from transit key</span>
public_keys, <span class="hljs-comment">// single entry array with public key of transit key</span>
domain_name, <span class="hljs-comment">// app origin</span>
manifest_uri, <span class="hljs-comment">// url to manifest file - must be hosted on app origin</span>
redirect_uri, <span class="hljs-comment">// url to which browser redirects user on auth approval - must be hosted on app origin</span>
version, <span class="hljs-comment">// version tuple</span>
do_not_include_profile, <span class="hljs-comment">// a boolean flag asking browser to send profile url instead of profile object</span>
supports_hub_url, <span class="hljs-comment">// a boolean flag indicating gaia hub support</span>
scopes <span class="hljs-comment">// an array of string values indicating scopes requested by the app</span>
}</pre>
<h3>Authentication response payload schema</h3>
<pre class='hljs'> <span class="hljs-keyword">const</span> responsePayload = {
jti, <span class="hljs-comment">// UUID</span>
iat, <span class="hljs-comment">// JWT creation time in seconds</span>
exp, <span class="hljs-comment">// JWT expiration time in seconds</span>
iss, <span class="hljs-comment">// legacy decentralized identifier (string prefix + identity address) - this uniquely identifies the user</span>
private_key, <span class="hljs-comment">// encrypted private key payload</span>
public_keys, <span class="hljs-comment">// single entry array with public key</span>
profile, <span class="hljs-comment">// profile object or null if passed by profile_url</span>
username, <span class="hljs-comment">// blockstack id username (if any)</span>
core_token, <span class="hljs-comment">// encrypted core token payload</span>
email, <span class="hljs-comment">// email if email scope is requested &amp; email available</span>
profile_url, <span class="hljs-comment">// url to signed profile token</span>
hubUrl, <span class="hljs-comment">// url pointing to user's gaia hub</span>
version <span class="hljs-comment">// version tuple</span>
}</pre>
<h2><code>blockstack:</code> custom protocol handler</h2>
<p>The <code>blockstack:</code> custom protocol handler is how Blockstack apps send their authentication requests to the Blockstack Browser. When the Blockstack Browser is installed on a user's computer, it registers itself as the handler for the <code>blockstack:</code> customer protocol.</p>
<p>When an application calls <a href="http://blockstack.github.io/blockstack.js/index.html#redirecttosignin"><code>redirectToSignIn</code></a> or <a href="http://blockstack.github.io/blockstack.js/index.html#redirecttosigninwithauthrequest"><code>redirectToSignInWithAuthRequest</code></a>, blockstack.js checks if a blockstack: protocol handler is installed and, if so, redirects the user to <code>blockstack:&#x3C;authRequestToken></code>. This passes the authentication request token from the app to the Blockstack Browser, which will in turn validate the request and display an authentication dialog.</p>
<h2>Adding Blockstack Authentication to your app</h2>
<p>The way you can add Blockstack Authentication to you app depends on whether your app is a modern decentralized Blockstack App where code runs client-side without trusted servers or a legacy client-server app where a server is trusted.</p>
<h3>Authentication in Client-side apps</h3>
<p>This method is appropriate for decentralized client-side apps where the user's zone of trust - the parts of the app that the user is trusting - begins and ends with the code running on their own computer. In apps like these, any code the app interacts with that's not on their own computer such as external servers does not need to know who she is.</p>
<p><a href="https://github.com/blockstack/blockstack.js">Blockstack.js</a> provides API methods that help you to implement Blockstack Authentication in your client-side app.</p>
<h4>Standard flow</h4>
<p>The preferred way to implement authentication in these apps is to use the standard flow. This flow hides much of the process behind a few easy function calls and makes it very fast to get up and running.</p>
<p>In this process you'll use these four functions:</p>
<ul>
<li><code>redirectToSignIn</code></li>
<li><code>isSignInPending</code></li>
<li><code>handlePendingSignIn</code></li>
<li><code>loadUserData</code></li>
</ul>
<h5>Starting the sign in process</h5>
<p>When your app wants to start the sign in process, typically when the user clicks a "Sign in with Blockstack" button, your app will call the <a href="http://blockstack.github.io/blockstack.js/index.html#redirecttosignin"><code>redirectToSignIn</code></a> method of <a href="https://github.com/blockstack/blockstack.js">blockstack.js</a>.</p>
<p>This creates an ephemeral transit key, stores it in the web browser's <code>localStorage</code>, uses it to create an authentication request token and finally redirects the user to the Blockstack browser to approve the sign in request.</p>
<h5>Handling an authentication response</h5>
<p>When a user approves a sign in request, the Blockstack Browser will return the signed authentication response token to the <code>redirectURI</code> specified in <code>redirectToSignIn</code>.</p>
<p>To check for the presence of this token, your app should call <code>isSignInPending</code>. If this returns <code>true</code>, the app should then call <code>handlePendingSignIn</code>. This decodes the token, returns the signed-in-user's data, and simultaneously storing it to <code>localStorage</code> so that it can be retrieved later with <code>loadUserData</code>.</p>
<pre class='hljs'><span class="hljs-keyword">import</span> * <span class="hljs-keyword">as</span> blockstack <span class="hljs-keyword">from</span> <span class="hljs-string">'blockstack'</span>
<span class="hljs-keyword">if</span> (blockstack.isSignInPending()) {
blockstack.handlePendingSignIn()
.then(<span class="hljs-function"><span class="hljs-params">userData</span> =&gt;</span> {
<span class="hljs-keyword">const</span> profile = userData.profile
})
}</pre>
<h4>Manual flow</h4>
<p>Alternatively, you can manually generate your own transit private key and/or authentication request token. This gives you more control over the experience.</p>
<p>For example, you could use the following code to generate an authentication request on <code>https://alice.example.com</code> or <code>https://bob.example.com</code> for an app running on origin <code>https://example.com</code>.</p>
<pre class='hljs'><span class="hljs-keyword">const</span> transitPrivateKey = generateAndStoreTransitKey()
<span class="hljs-keyword">const</span> redirectURI = <span class="hljs-string">'https://example.com/authLandingPage'</span>
<span class="hljs-keyword">const</span> manifestURI = <span class="hljs-string">'https://example.com/manifest.json'</span>
<span class="hljs-keyword">const</span> scopes = [<span class="hljs-string">'scope_write'</span>, <span class="hljs-string">'publish_data'</span>]
<span class="hljs-keyword">const</span> appDomain = <span class="hljs-string">'https://example.com'</span>
<span class="hljs-keyword">const</span> authRequest = makeAuthRequest(transitPrivateKey, redirectURI, manifestURI, scopes, appDomain)
redirectToSignInWithAuthRequest(authRequest)</pre>
<h3>Authentication in client-server apps</h3>
<p><em>Note: Client-server authentication requires using a library written in the language of your server app. There are private methods in blockstack.js that can be accomplish this on node.js server apps, but they are not currently part of our public, supported API.</em></p>
<p>Using Blockstack Authentication in client-server apps is very similar to client-side apps. You generate the authentication request using the same code in the client as described above.</p>
<p>The main difference is that you need to verify the authentication response token on the server after the user approves sign in to your app.</p>
<p>For an example of how verification can be done server side, take a look at the <a href="https://github.com/blockstack/blockstack-ruby#to-verify-an-auth-response">blockstack-ruby</a> library.</p>
</section>
</div>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='authentication'>
Authentication
</h3>
</div>
<p>Blockstack Authentication provides single sign on and authentication without third parties or remote servers. Blockstack Authentication is a bearer token-based authentication system. From an app user's perspective, it functions similar to legacy third-party authentication techniques that they're familiar with. For an app developer, the flow is a bit different from the typical client-server flow of centralized sign in services (e.g., OAuth). Rather, with Blockstack, the authentication flow happens entirely client-side.</p>
<h2>Quickstart</h2>
<p>1) Install <code>blockstack.js</code>:</p>
<pre class='hljs'>npm install blockstack --save</pre>
<p>2) Import Blockstack into your project</p>
<pre class='hljs'><span class="hljs-keyword">import</span> * <span class="hljs-keyword">as</span> blockstack <span class="hljs-keyword">from</span> <span class="hljs-string">'blockstack'</span></pre>
<p>3) Wire up a sign in button</p>
<pre class='hljs'><span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'signin-button'</span>).addEventListener(<span class="hljs-string">'click'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
blockstack.redirectToSignIn()
})</pre>
<p>4) Wire up a sign out button</p>
<pre class='hljs'><span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'signout-button'</span>).addEventListener(<span class="hljs-string">'click'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
blockstack.signUserOut(<span class="hljs-built_in">window</span>.location.origin)
})</pre>
<p>5) Include the logic to (a) load user data (b) handle the auth response</p>
<pre class='hljs'><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">showProfile</span>(<span class="hljs-params">profile</span>) </span>{
<span class="hljs-keyword">var</span> person = <span class="hljs-keyword">new</span> blockstack.Person(profile)
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'heading-name'</span>).innerHTML = person.name()
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'avatar-image'</span>).setAttribute(<span class="hljs-string">'src'</span>, person.avatarUrl())
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'section-1'</span>).style.display = <span class="hljs-string">'none'</span>
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'section-2'</span>).style.display = <span class="hljs-string">'block'</span>
}
<span class="hljs-keyword">if</span> (blockstack.isUserSignedIn()) {
 <span class="hljs-keyword">const</span> userData = blockstack.loadUserData()
showProfile(userData.profile)
} <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (blockstack.isSignInPending()) {
blockstack.handlePendingSignIn()
.then(<span class="hljs-function"><span class="hljs-params">userData</span> =&gt;</span> {
showProfile(userData.profile)
})
}</pre>
<p>6) Create a <code>manifest.json</code> file</p>
<pre class='hljs'>{
<span class="hljs-attr">"name"</span>: <span class="hljs-string">"Hello, Blockstack"</span>,
<span class="hljs-attr">"start_url"</span>: <span class="hljs-string">"localhost:5000"</span>,
<span class="hljs-attr">"description"</span>: <span class="hljs-string">"A simple demo of Blockstack Auth"</span>,
<span class="hljs-attr">"icons"</span>: [{
<span class="hljs-attr">"src"</span>: <span class="hljs-string">"https://helloblockstack.com/icon-192x192.png"</span>,
<span class="hljs-attr">"sizes"</span>: <span class="hljs-string">"192x192"</span>,
<span class="hljs-attr">"type"</span>: <span class="hljs-string">"image/png"</span>
}]
}</pre>
<p>Make sure your <code>manifest.json</code> file has appropriate CORS headers so that it can
be fetched via an http <code>GET</code> from any origin.</p>
<p>7) Serve your application</p>
<h2>User flow</h2>
<p>What follows is a walk through of the experience of a user, Alice, signing in to your app with Blockstack.</p>
<p>First, Alice clicks the "Sign in with Blockstack" button on your app. She is redirected to her copy of the Blockstack Browser. The Blockstack Browser shows Alice an approval dialog with information about your app including:</p>
<ul>
<li>The origin your app was served from</li>
<li>Your app's name</li>
<li>Your app's logo</li>
<li>The types of permissions and data your app is requesting</li>
</ul>
<p>Alice can choose to authenticate as one of her Blockstack IDs by selecting the ID and clicking the Approve button.</p>
<p>When she clicks approve, she's redirected back to your app. Your app gets cryptographic proof that she is who she claims to be, access to a dedicated bucket in her Gaia storage hub for your app to read and write its own data along with public information she's stored in her profile.</p>
<h2>Manifest file</h2>
<p>Blockstack apps have a manifest file based on the <a href="https://w3c.github.io/manifest/">W3C web app manifest specification</a>. The Blockstack Browser retrieves the manifest file from the app during the authentication process and displays some of the information in it such as the app name and icon to the user. The location of the app manifest file is specific in the authentication request token and <em>MUST</em> be on the same origin as the app requesting authentication.</p>
<p>Below is an example of a manifest file:</p>
<pre><code>{
"name": "Todo App",
"start_url": "http://blockstack-todos.appartisan.com",
"description": "A simple todo app build on blockstack",
"icons": [{
"src": "http://blockstack-todos.appartisan.com/logo.png",
"sizes": "400x400",
"type": "image/png"
}]
}
</code></pre>
<p>The manifest file <em>MUST</em> have <a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Cross-origin resource sharing (CORS) headers</a> that allow the manifest file to be fetched from any arbitrary source. This usually means returning:</p>
<pre><code>Access-Control-Allow-Origin: *
</code></pre>
<h2>Key pairs</h2>
<p>Blockstack Authentication makes extensive use of public key cryptography. As mentioned above, we use ECDSA with the secp256k1 curve. What follows is a description of the various public-private key pairs used in the authentication process including how they're generated, where they're used and to whom the private key is disclosed.</p>
<h3>Transit private key</h3>
<p>The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the Blockstack Browser to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. The public key that corresponds to the transit private key is stored in a single element array in the <code>public_keys</code> key of the authentication request token. The Blockstack Browser encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request.</p>
<h3>Blockstack ID Identity address private key</h3>
<p>The identity address private key is derived from the user's keychain phrase and is the private key of the Blockstack ID that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the Blockstack browser. This private key signs the authentication response token for an app to indicate that the user approves sign in to that app.</p>
<h3>App private key</h3>
<p>The app private key is an app-specific private key that is generated from the user's identity address private key using the <code>domain_name</code> as input. It is deterministic in that for a given Blockstack ID and <code>domain_name</code>, the same private key will be generated each time. The app private key is securely shared with the app on each authentication, encrypted by the Blockstack browser with the transit public key.</p>
<p>The app private key serves three functions.</p>
<ul>
<li>It is used to create the credentials that give an app access to the gaia hub storage bucket for that specific app.</li>
<li>It is used in the end-to-end encryption of files stored for the app on the user's gaia hub.</li>
<li>It serves as a cryptographic secret that apps can use to perform other cryptographic functions.</li>
</ul>
<h2>Scopes</h2>
<p>Scopes define the information and permissions an app requests from the
user during authentication. Requested scopes may be any of the following:</p>
<ul>
<li>
<p><code>store_write</code> - read and write data to the user's Gaia hub in an app-specific storage bucket</p>
</li>
<li>
<p><code>publish_data</code> - publish data so that other users of the app can discover and interact with the user</p>
</li>
<li>
<p><code>email</code> - requests the user's email if available</p>
<p> If no <code>scopes</code> array is provided to the <code>redirectToSignIn</code> or
<code>makeAuthRequest</code> functions, the default is to request <code>['store_write']</code>.</p>
</li>
</ul>
<h2>Authentication tokens</h2>
<p>The app and the Blockstack Browser communicate during the authentication flow by passing back and forth two tokens:</p>
<p>The requesting application sends the Blockstack Browser an authRequest token.
Once a user approves a sign in, the Blockstack Browser responds to the application with an authResponse token.</p>
<p>These tokens are <a href="https://jwt.io/">JSON Web Tokens</a>, and they are passed via URL query strings.</p>
<h3>JSON Web Token signatures</h3>
<p>Blockstack's authentication tokens are based on the <a href="https://tools.ietf.org/html/rfc7519">RFC 7519 OAuth JSON Web Token (JWT)</a> with additional support for the secp256k1 curve used by bitcoin and many other cryptocurrencies.</p>
<p>This signature algorithm is indicated by specifying <code>ES256K</code> in the token's <code>alg</code> key, specifying that the JWT signature uses ECDSA with the secp256k1 curve. We provide both <a href="https://github.com/blockstack/jsontokens-js">JavaScript</a> and <a href="https://github.com/blockstack/ruby-jwt-blockstack/tree/ruby-jwt-blockstack">Ruby</a> JWT libraries with support for this signing algorithm.</p>
<h3>Authentication request payload schema</h3>
<pre class='hljs'><span class="hljs-keyword">const</span> requestPayload = {
jti, <span class="hljs-comment">// UUID</span>
iat, <span class="hljs-comment">// JWT creation time in seconds</span>
exp, <span class="hljs-comment">// JWT expiration time in seconds</span>
iss, <span class="hljs-comment">// legacy decentralized identifier generated from transit key</span>
public_keys, <span class="hljs-comment">// single entry array with public key of transit key</span>
domain_name, <span class="hljs-comment">// app origin</span>
manifest_uri, <span class="hljs-comment">// url to manifest file - must be hosted on app origin</span>
redirect_uri, <span class="hljs-comment">// url to which browser redirects user on auth approval - must be hosted on app origin</span>
version, <span class="hljs-comment">// version tuple</span>
do_not_include_profile, <span class="hljs-comment">// a boolean flag asking browser to send profile url instead of profile object</span>
supports_hub_url, <span class="hljs-comment">// a boolean flag indicating gaia hub support</span>
scopes <span class="hljs-comment">// an array of string values indicating scopes requested by the app</span>
}</pre>
<h3>Authentication response payload schema</h3>
<pre class='hljs'> <span class="hljs-keyword">const</span> responsePayload = {
jti, <span class="hljs-comment">// UUID</span>
iat, <span class="hljs-comment">// JWT creation time in seconds</span>
exp, <span class="hljs-comment">// JWT expiration time in seconds</span>
iss, <span class="hljs-comment">// legacy decentralized identifier (string prefix + identity address) - this uniquely identifies the user</span>
private_key, <span class="hljs-comment">// encrypted private key payload</span>
public_keys, <span class="hljs-comment">// single entry array with public key</span>
profile, <span class="hljs-comment">// profile object or null if passed by profile_url</span>
username, <span class="hljs-comment">// blockstack id username (if any)</span>
core_token, <span class="hljs-comment">// encrypted core token payload</span>
email, <span class="hljs-comment">// email if email scope is requested &amp; email available</span>
profile_url, <span class="hljs-comment">// url to signed profile token</span>
hubUrl, <span class="hljs-comment">// url pointing to user's gaia hub</span>
version <span class="hljs-comment">// version tuple</span>
}</pre>
<h2><code>blockstack:</code> custom protocol handler</h2>
<p>The <code>blockstack:</code> custom protocol handler is how Blockstack apps send their authentication requests to the Blockstack Browser. When the Blockstack Browser is installed on a user's computer, it registers itself as the handler for the <code>blockstack:</code> customer protocol.</p>
<p>When an application calls <a href="http://blockstack.github.io/blockstack.js/index.html#redirecttosignin"><code>redirectToSignIn</code></a> or <a href="http://blockstack.github.io/blockstack.js/index.html#redirecttosigninwithauthrequest"><code>redirectToSignInWithAuthRequest</code></a>, blockstack.js checks if a blockstack: protocol handler is installed and, if so, redirects the user to <code>blockstack:&#x3C;authRequestToken></code>. This passes the authentication request token from the app to the Blockstack Browser, which will in turn validate the request and display an authentication dialog.</p>
<h2>Adding Blockstack Authentication to your app</h2>
<p>The way you can add Blockstack Authentication to you app depends on whether your app is a modern decentralized Blockstack App where code runs client-side without trusted servers or a legacy client-server app where a server is trusted.</p>
<h3>Authentication in Client-side apps</h3>
<p>This method is appropriate for decentralized client-side apps where the user's zone of trust - the parts of the app that the user is trusting - begins and ends with the code running on their own computer. In apps like these, any code the app interacts with that's not on their own computer such as external servers does not need to know who she is.</p>
<p><a href="https://github.com/blockstack/blockstack.js">Blockstack.js</a> provides API methods that help you to implement Blockstack Authentication in your client-side app.</p>
<h4>Standard flow</h4>
<p>The preferred way to implement authentication in these apps is to use the standard flow. This flow hides much of the process behind a few easy function calls and makes it very fast to get up and running.</p>
<p>In this process you'll use these four functions:</p>
<ul>
<li><code>redirectToSignIn</code></li>
<li><code>isSignInPending</code></li>
<li><code>handlePendingSignIn</code></li>
<li><code>loadUserData</code></li>
</ul>
<h5>Starting the sign in process</h5>
<p>When your app wants to start the sign in process, typically when the user clicks a "Sign in with Blockstack" button, your app will call the <a href="http://blockstack.github.io/blockstack.js/index.html#redirecttosignin"><code>redirectToSignIn</code></a> method of <a href="https://github.com/blockstack/blockstack.js">blockstack.js</a>.</p>
<p>This creates an ephemeral transit key, stores it in the web browser's <code>localStorage</code>, uses it to create an authentication request token and finally redirects the user to the Blockstack browser to approve the sign in request.</p>
<h5>Handling an authentication response</h5>
<p>When a user approves a sign in request, the Blockstack Browser will return the signed authentication response token to the <code>redirectURI</code> specified in <code>redirectToSignIn</code>.</p>
<p>To check for the presence of this token, your app should call <code>isSignInPending</code>. If this returns <code>true</code>, the app should then call <code>handlePendingSignIn</code>. This decodes the token, returns the signed-in-user's data, and simultaneously storing it to <code>localStorage</code> so that it can be retrieved later with <code>loadUserData</code>.</p>
<pre class='hljs'><span class="hljs-keyword">import</span> * <span class="hljs-keyword">as</span> blockstack <span class="hljs-keyword">from</span> <span class="hljs-string">'blockstack'</span>
<span class="hljs-keyword">if</span> (blockstack.isSignInPending()) {
blockstack.handlePendingSignIn()
.then(<span class="hljs-function"><span class="hljs-params">userData</span> =&gt;</span> {
<span class="hljs-keyword">const</span> profile = userData.profile
})
}</pre>
<h4>Manual flow</h4>
<p>Alternatively, you can manually generate your own transit private key and/or authentication request token. This gives you more control over the experience.</p>
<p>For example, you could use the following code to generate an authentication request on <code>https://alice.example.com</code> or <code>https://bob.example.com</code> for an app running on origin <code>https://example.com</code>.</p>
<pre class='hljs'><span class="hljs-keyword">const</span> transitPrivateKey = generateAndStoreTransitKey()
<span class="hljs-keyword">const</span> redirectURI = <span class="hljs-string">'https://example.com/authLandingPage'</span>
<span class="hljs-keyword">const</span> manifestURI = <span class="hljs-string">'https://example.com/manifest.json'</span>
<span class="hljs-keyword">const</span> scopes = [<span class="hljs-string">'scope_write'</span>, <span class="hljs-string">'publish_data'</span>]
<span class="hljs-keyword">const</span> appDomain = <span class="hljs-string">'https://example.com'</span>
<span class="hljs-keyword">const</span> authRequest = makeAuthRequest(transitPrivateKey, redirectURI, manifestURI, scopes, appDomain)
redirectToSignInWithAuthRequest(authRequest)</pre>
<h3>Authentication in client-server apps</h3>
<p><em>Note: Client-server authentication requires using a library written in the language of your server app. There are private methods in blockstack.js that can be accomplish this on node.js server apps, but they are not currently part of our public, supported API.</em></p>
<p>Using Blockstack Authentication in client-server apps is very similar to client-side apps. You generate the authentication request using the same code in the client as described above.</p>
<p>The main difference is that you need to verify the authentication response token on the server after the user approves sign in to your app.</p>
<p>For an example of how verification can be done server side, take a look at the <a href="https://github.com/blockstack/blockstack-ruby#to-verify-an-auth-response">blockstack-ruby</a> library.</p>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='appconfig'>
AppConfig
</h3>
</div>
<p>Configuration data for the current app.</p>
<p>On browser platforms, creating an instance of this
class without any arguments will use
<code>window.location.origin</code> as the app domain.
On non-browser platforms, you need to
specify an app domain as the first argument.</p>
<div class='pre p1 fill-light mt0'>new AppConfig(scopes: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>>, appDomain: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, redirectPath: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, manifestPath: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, coreNode: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, authenticatorURL: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)</div>
<p>
Type:
<a href="#appconfig">AppConfig</a>
</p>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>scopes</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>>
= <code>DEFAULT_SCOPE.slice()</code>)</code>
permissions this app is requesting
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>appDomain</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
= <code>window.location.origin</code>)</code>
the app domain
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>redirectPath</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
= <code>&#39;&#39;</code>)</code>
path on app domain to redirect users to after authentication
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>manifestPath</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
= <code>&#39;/manifest.json&#39;</code>)</code>
path relative to app domain of app's manifest file
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>coreNode</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
= <code>null</code>)</code>
override the default or user selected core node
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>authenticatorURL</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
= <code>DEFAULT_BLOCKSTACK_HOST</code>)</code>
the web-based fall back authenticator
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Instance Members</div>
<div class="clearfix">
<div class='border-bottom' id='appconfigappdomain'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>appDomain</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Blockstack apps are uniquely identified by their app domain.</p>
<div class='pre p1 fill-light mt0'>appDomain</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigscopes'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>scopes</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>An array of string representing permissions requested by the app.</p>
<div class='pre p1 fill-light mt0'>scopes</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigredirectpath'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>redirectPath</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Path on app domain to redirect users to after authentication. The
authentication response token will be postpended in a query.</p>
<div class='pre p1 fill-light mt0'>redirectPath</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigmanifestpath'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>manifestPath</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Path relative to app domain of app's manifest file.</p>
<p>This file needs to have CORS headers set so that it can be fetched
from any origin. Typically this means return the header <code>Access-Control-Allow-Origin: *</code>.</p>
<div class='pre p1 fill-light mt0'>manifestPath</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigcorenode'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>coreNode</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>The URL of Blockstack core node to use for this app. If this is
<code>null</code>, the core node specified by the user or default core node
will be used.</p>
<div class='pre p1 fill-light mt0'>coreNode</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigauthenticatorurl'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>authenticatorURL</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>The URL of a web-based Blockstack Authenticator to use in the event
the user doesn't have Blockstack installed on their machine. If this
is not specified, the current default in this library will be used.</p>
<div class='pre p1 fill-light mt0'>authenticatorURL</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigredirecturi'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>redirectURI()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>The location to which the authenticator should
redirect the user.</p>
<div class='pre p1 fill-light mt0'>redirectURI(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code>:
URI
</section>
</div>
</div>
<div class='border-bottom' id='appconfigmanifesturi'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>manifestURI()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>The location of the app's manifest file.</p>
<div class='pre p1 fill-light mt0'>manifestURI(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code>:
URI
</section>
</div>
</div>
</div>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='usersession'>
UserSession
</h3>
</div>
<p>Represents an instance of a signed in user for a particular app.</p>
<p>A signed in user has access to two major pieces of information
about the user, the user's private key for that app and the location
of the user's gaia storage bucket for the app.</p>
<p>A user can be signed in either directly through the interactive
sign in process or by directly providing the app private key.</p>
<div class='pre p1 fill-light mt0'>new UserSession(options: {appConfig: <a href="#appconfig">AppConfig</a>?, sessionStore: <a href="#sessiondatastore">SessionDataStore</a>?, sessionOptions: SessionOptions?})</div>
<p>
Type:
<a href="#usersession">UserSession</a>
</p>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>({appConfig: <a href="#appconfig">AppConfig</a>?, sessionStore: <a href="#sessiondatastore">SessionDataStore</a>?, sessionOptions: SessionOptions?})</code>
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Instance Members</div>
<div class="clearfix">
<div class='border-bottom' id='usersessionredirecttosignin'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>redirectToSignIn()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Generates an authentication request and redirects the user to the Blockstack
browser to approve the sign in request.</p>
<p>Please note that this requires that the web browser properly handles the
<code>blockstack:</code> URL protocol handler.</p>
<p>Most applications should use this
method for sign in unless they require more fine grained control over how the
authentication request is generated. If your app falls into this category,
use <code>generateAndStoreTransitKey</code>, <code>makeAuthRequest</code>,
and <code>redirectToSignInWithAuthRequest</code> to build your own sign in process.</p>
<div class='pre p1 fill-light mt0'>redirectToSignIn(): void</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>void</code>:
</section>
</div>
</div>
<div class='border-bottom' id='usersessionredirecttosigninwithauthrequest'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>redirectToSignInWithAuthRequest(authRequest)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Redirects the user to the Blockstack browser to approve the sign in request
given.</p>
<p>The user is redirected to the authenticator URL specified in the <code>AppConfig</code>
if the <code>blockstack:</code> protocol handler is not detected.
Please note that the protocol handler detection
does not work on all browsers.</p>
<div class='pre p1 fill-light mt0'>redirectToSignInWithAuthRequest(authRequest: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): void</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>authRequest</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the authentication request generated by
<code>makeAuthRequest</code>
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>void</code>:
</section>
</div>
</div>
<div class='border-bottom' id='usersessiongenerateandstoretransitkey'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>generateAndStoreTransitKey()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Generates a ECDSA keypair to
use as the ephemeral app transit private key
and store in the session</p>
<div class='pre p1 fill-light mt0'>generateAndStoreTransitKey(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>:
the hex encoded private key
</section>
</div>
</div>
<div class='border-bottom' id='usersessiongetauthresponsetoken'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>getAuthResponseToken()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Retrieve the authentication token from the URL query</p>
<div class='pre p1 fill-light mt0'>getAuthResponseToken(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>:
the authentication token if it exists otherwise
<code>null</code>
</section>
</div>
</div>
<div class='border-bottom' id='usersessionissigninpending'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>isSignInPending()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Check if there is a authentication request that hasn't been handled.</p>
<div class='pre p1 fill-light mt0'>isSignInPending(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>:
<code>true</code>
if there is a pending sign in, otherwise
<code>false</code>
</section>
</div>
</div>
<div class='border-bottom' id='usersessionisusersignedin'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>isUserSignedIn()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Check if a user is currently signed in.</p>
<div class='pre p1 fill-light mt0'>isUserSignedIn(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>:
<code>true</code>
if the user is signed in,
<code>false</code>
if not.
</section>
</div>
</div>
<div class='border-bottom' id='usersessionhandlependingsignin'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>handlePendingSignIn(authResponseToken)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Try to process any pending sign in request by returning a <code>Promise</code> that resolves
to the user data object if the sign in succeeds.</p>
<div class='pre p1 fill-light mt0'>handlePendingSignIn(authResponseToken: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>authResponseToken</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>this.getAuthResponseToken()</code>)</code>
the signed authentication response token
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to the user data object if successful and rejects
if handling the sign in request fails or there was no pending sign in request.
</section>
</div>
</div>
<div class='border-bottom' id='usersessionloaduserdata'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>loadUserData()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Retrieves the user data object. The user's profile is stored in the key <code>profile</code>.</p>
<div class='pre p1 fill-light mt0'>loadUserData(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
User data object.
</section>
</div>
</div>
<div class='border-bottom' id='usersessionsignuserout'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>signUserOut()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Sign the user out</p>
<div class='pre p1 fill-light mt0'>signUserOut(): void</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>void</code>:
</section>
</div>
</div>
<div class='border-bottom' id='usersessionencryptcontent'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>encryptContent(content, options)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Encrypts the data provided with the app public key.</p>
<div class='pre p1 fill-light mt0'>encryptContent(content: (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>), options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>content</span> <code class='quiet'>((<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>))</code>
data to encrypt
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.publicKey</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the hex string of the ECDSA public
key to use for encryption. If not provided, will use user's appPrivateKey.
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>:
Stringified ciphertext object
</section>
</div>
</div>
<div class='border-bottom' id='usersessiondecryptcontent'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>decryptContent(content, options)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Decrypts data encrypted with <code>encryptContent</code> with the
transit private key.</p>
<div class='pre p1 fill-light mt0'>decryptContent(content: (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>), options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>)</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>content</span> <code class='quiet'>((<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>))</code>
encrypted content.
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.privateKey</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the hex string of the ECDSA private
key to use for decryption. If not provided, will use user's appPrivateKey.
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>)</code>:
decrypted content.
</section>
</div>
</div>
<div class='border-bottom' id='usersessionputfile'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>putFile(path, content, options)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Stores the data provided in the app's data store to to the file specified.</p>
<div class='pre p1 fill-light mt0'>putFile(path: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, content: (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>), options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>path</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the path to store the data in
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>content</span> <code class='quiet'>((<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>))</code>
the data to store in the file
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.encrypt</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
(default <code>true</code>)
</td>
<td class='break-word'><span>encrypt the data with the app private key
or the provided public key
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.sign</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>false</code>)
</td>
<td class='break-word'><span>sign the data using ECDSA on SHA256 hashes with
the app private key
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves if the operation succeed and rejects
if it failed
</section>
</div>
</div>
<div class='border-bottom' id='usersessiongetfile'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>getFile(path, options)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Retrieves the specified file from the app's data store.</p>
<div class='pre p1 fill-light mt0'>getFile(path: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>path</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the path to the file to read
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.decrypt</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>true</code>)
</td>
<td class='break-word'><span>try to decrypt the data with the app private key
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.username</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the Blockstack ID to lookup for multi-player storage
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.verify</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
</td>
<td class='break-word'><span>Whether the content should be verified, only to be used
when
<code>putFile</code>
was set to
<code>sign = true</code>
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.app</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the app to lookup for multi-player storage -
defaults to current origin
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.zoneFileLookupURL</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
(default <code>null</code>)
</td>
<td class='break-word'><span>The URL
to use for zonefile lookup. If falsey, this will use the
blockstack.js's getNameInfo function instead.
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to the raw data in the file
or rejects with an error
</section>
</div>
</div>
<div class='border-bottom' id='usersessionlistfiles'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>listFiles(callback)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>List the set of files in this application's Gaia storage bucket.</p>
<div class='pre p1 fill-light mt0'>listFiles(callback: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">function</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>callback</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">function</a>)</code>
a callback to invoke on each named file that
returns
<code>true</code>
to continue the listing operation or
<code>false</code>
to end it
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to the number of files listed
</section>
</div>
</div>
</div>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='sessiondatastore'>
SessionDataStore
</h3>
</div>
<p>An abstract class representing the SessionDataStore interface.</p>
<div class='pre p1 fill-light mt0'>new SessionDataStore(sessionOptions: SessionOptions)</div>
<p>
Type:
SessionData
</p>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>sessionOptions</span> <code class='quiet'>(SessionOptions)</code>
</div>
</div>
</div>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='instancedatastore'>
InstanceDataStore
</h3>
</div>
<p>Stores session data in the instance of this class.</p>
<div class='pre p1 fill-light mt0'>new InstanceDataStore(sessionOptions: SessionOptions)</div>
<p>
Type:
<a href="#instancedatastore">InstanceDataStore</a>
</p>
<p>
Extends
<a href="#sessiondatastore">SessionDataStore</a>
</p>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>sessionOptions</span> <code class='quiet'>(SessionOptions)</code>
</div>
</div>
</div>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='localstoragestore'>
LocalStorageStore
</h3>
</div>
<p>Stores session data in browser a localStorage entry.</p>
<div class='pre p1 fill-light mt0'>new LocalStorageStore(sessionOptions: SessionOptions)</div>
<p>
Type:
<a href="#localstoragestore">LocalStorageStore</a>
</p>
<p>
Extends
<a href="#sessiondatastore">SessionDataStore</a>
</p>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>sessionOptions</span> <code class='quiet'>(SessionOptions)</code>
</div>
</div>
</div>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='isusersignedin'>
isUserSignedIn
</h3>
</div>
<p>Check if a user is currently signed in.</p>
<div class='pre p1 fill-light mt0'>isUserSignedIn(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>:
<code>true</code>
if the user is signed in,
<code>false</code>
if not.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='redirecttosignin'>
redirectToSignIn
</h3>
</div>
<p>Generates an authentication request and redirects the user to the Blockstack
browser to approve the sign in request.</p>
<p>Please note that this requires that the web browser properly handles the
<code>blockstack:</code> URL protocol handler.</p>
<p>Most applications should use this
method for sign in unless they require more fine grained control over how the
authentication request is generated. If your app falls into this category,
use <code>makeAuthRequest</code> and <code>redirectToSignInWithAuthRequest</code> to build your own sign in process.</p>
<div class='pre p1 fill-light mt0'>redirectToSignIn(redirectURI: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, manifestURI: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, scopes: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>): void</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>redirectURI</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>`${window.location.origin}/`</code>)</code>
The location to which the identity provider will redirect the user after
the user approves sign in.
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>manifestURI</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>`${window.location.origin}/manifest.json`</code>)</code>
Location of the manifest file.
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>scopes</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>
= <code>DEFAULT_SCOPE</code>)</code>
Defaults to requesting write access to
this app's data store.
An array of strings indicating which permissions this app is requesting.
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>void</code>:
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='redirecttosigninwithauthrequest'>
redirectToSignInWithAuthRequest
</h3>
</div>
<p>Redirects the user to the Blockstack browser to approve the sign in request
given.</p>
<p>The user is redirected to the <code>blockstackIDHost</code> if the <code>blockstack:</code>
protocol handler is not detected. Please note that the protocol handler detection
does not work on all browsers.</p>
<div class='pre p1 fill-light mt0'>redirectToSignInWithAuthRequest(authRequest: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, blockstackIDHost: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): void</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>authRequest</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the authentication request generated by
<code>makeAuthRequest</code>
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>blockstackIDHost</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>DEFAULT_BLOCKSTACK_HOST</code>)</code>
the URL to redirect the user to if the blockstack
protocol handler is not detected
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>void</code>:
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='issigninpending'>
isSignInPending
</h3>
</div>
<p>Check if there is a authentication request that hasn't been handled.</p>
<div class='pre p1 fill-light mt0'>isSignInPending(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>:
<code>true</code>
if there is a pending sign in, otherwise
<code>false</code>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='handlependingsignin'>
handlePendingSignIn
</h3>
</div>
<p>Try to process any pending sign in request by returning a <code>Promise</code> that resolves
to the user data object if the sign in succeeds.</p>
<div class='pre p1 fill-light mt0'>handlePendingSignIn(nameLookupURL: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, authResponseToken: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, transitKey: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>nameLookupURL</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>&#39;&#39;</code>)</code>
the endpoint against which to verify public
keys match claimed username
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>authResponseToken</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>getAuthResponseToken()</code>)</code>
the signed authentication response token
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>transitKey</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>&#39;&#39;</code>)</code>
the transit private key that corresponds to the transit public key
that was provided in the authentication request
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to the user data object if successful and rejects
if handling the sign in request fails or there was no pending sign in request.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='loaduserdata'>
loadUserData
</h3>
</div>
<p>Retrieves the user data object. The user's profile is stored in the key <code>profile</code>.</p>
<div class='pre p1 fill-light mt0'>loadUserData(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
User data object.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='signuserout'>
signUserOut
</h3>
</div>
<p>Sign the user out and optionally redirect to given location.</p>
<div class='pre p1 fill-light mt0'>signUserOut(redirectURL: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): void</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>redirectURL</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>null</code>)</code>
Location to redirect user to after sign out.
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>void</code>:
</section>
<div class='keyline-top-not py2'>
<section class='py2 clearfix'>
<h2 id='profiles' class='mt0'>
Profiles
</h2>
<p>Follow these steps to create and register a profile for a Blockchain ID:</p>
<ol>
<li>Create a JSON profile object</li>
<li>Split up the profile into tokens, sign the tokens, and put them in a token file</li>
<li>Create a zone file that points to the web location of the profile token file</li>
</ol>
<h3>Create a profile</h3>
<pre class='hljs'>const profileOfNaval = {
"@context": "http://schema.org/",
"@type": "Person",
"name": "Naval Ravikant",
"description": "Co-founder of AngelList"
}</pre>
<h3>Sign a profile as a single token</h3>
<pre class='hljs'>import { makeECPrivateKey, wrapProfileToken, Person } from 'blockstack'
const privateKey = makeECPrivateKey()
const person = new Person(profileOfNaval)
const token = person.toToken(privateKey)
const tokenFile = [wrapProfileToken(token)]</pre>
<h3>Verify an individual token</h3>
<pre class='hljs'><span class="hljs-keyword">import</span> { verifyProfileToken } <span class="hljs-keyword">from</span> <span class="hljs-string">'blockstack'</span>
<span class="hljs-keyword">try</span> {
<span class="hljs-keyword">const</span> decodedToken = verifyProfileToken(tokenFile[<span class="hljs-number">0</span>].token, publicKey)
} <span class="hljs-keyword">catch</span>(e) {
<span class="hljs-built_in">console</span>.log(e)
}</pre>
<h3>Recover a profile from a token file</h3>
<pre class='hljs'><span class="hljs-keyword">const</span> recoveredProfile = Person.fromToken(tokenFile, publicKey)</pre>
<h3>Validate profile schema</h3>
<pre class='hljs'><span class="hljs-keyword">const</span> validationResults = Person.validateSchema(recoveredProfile)</pre>
<h3>Where profile data is stored</h3>
<p>Profile data is stored using Gaia on the user's selected storage provider.</p>
<p>An example of a profile.json file URL using Blockstack provided storage:
<code>https://gaia.blockstack.org/hub/1EeZtGNdFrVB2AgLFsZbyBCF7UTZcEWhHk/profile.json</code></p>
<h3>Validate a proof</h3>
<pre class='hljs'>import { validateProofs } from 'blockstack'
const domainName = "naval.id"
validateProofs(profile, domainName).then((proofs) =&gt; {
console.log(proofs)
})</pre>
<h3>How proofs are validated</h3>
<p>The <code>validateProofs</code> function checks each of the proofs listed in the
profile by fetching the proof URL and verifying the proof message.</p>
<p>The proof message must be of the form:</p>
<pre><code>Verifying my Blockstack ID is secured with the address
1EeZtGNdFrVB2AgLFsZbyBCF7UTZcEWhHk
</code></pre>
<p>The proof message also must appear in the required location on the
proof page specific to each type of social media account.</p>
<p>The account from which the proof message is posted must match exactly
the account identifier/username claimed in the user profile. The
<code>validateProofs</code> function will check this in the body of the proof or
in the proof URL depending on the service.</p>
<h3>Adding additional social account validation services</h3>
<p>The <code>Service</code> class can be extended to provide proof validation service
to additional social account types. You will need to override the
<code>getProofStatement(searchText: string)</code> method which parses the proof
body and returns the proof message text. Additionally, the identifier
claimed should be verified in the proof URL or in the body by implementing
<code>getProofIdentity(searchText: string)</code> and setting <code>shouldValidateIdentityInBody()</code>
to return true.</p>
<p>The following snippet uses the meta tags in the proof page to retrieve the proof message.</p>
<pre class='hljs'><span class="hljs-keyword">static</span> getProofStatement(searchText: string) {
<span class="hljs-keyword">const</span> $ = cheerio.load(searchText)
<span class="hljs-keyword">const</span> statement = $(<span class="hljs-string">'meta[property="og:description"]'</span>)
.attr(<span class="hljs-string">'content'</span>)
<span class="hljs-keyword">if</span> (statement !== <span class="hljs-literal">undefined</span> &amp;&amp; statement.split(<span class="hljs-string">':'</span>).length &gt; <span class="hljs-number">1</span>) {
<span class="hljs-keyword">return</span> statement.split(<span class="hljs-string">':'</span>)[<span class="hljs-number">1</span>].trim().replace(<span class="hljs-string">'“'</span>, <span class="hljs-string">''</span>).replace(<span class="hljs-string">'”'</span>, <span class="hljs-string">''</span>)
} <span class="hljs-keyword">else</span> {
<span class="hljs-keyword">return</span> <span class="hljs-string">''</span>
}
}</pre>
<h3>Currently supported proof validation services</h3>
<ul>
<li>Facebook</li>
<li>Twitter</li>
<li>Instagram</li>
<li>LinkedIn</li>
<li>Hacker News</li>
<li>GitHub</li>
</ul>
<h3>Profile proof schema</h3>
<p>Proofs are stored under the <code>account</code> key in the user's profile data</p>
<pre class='hljs'><span class="hljs-string">"account"</span>: [
{
<span class="hljs-string">"@type"</span>: <span class="hljs-string">"Account"</span>,
<span class="hljs-string">"service"</span>: <span class="hljs-string">"twitter"</span>,
<span class="hljs-string">"identifier"</span>: <span class="hljs-string">"naval"</span>,
<span class="hljs-string">"proofType"</span>: <span class="hljs-string">"http"</span>,
<span class="hljs-string">"proofUrl"</span>: <span class="hljs-string">"https://twitter.com/naval/status/12345678901234567890"</span>
}
]</pre>
</section>
</div>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='profiles'>
Profiles
</h3>
</div>
<p>Follow these steps to create and register a profile for a Blockchain ID:</p>
<ol>
<li>Create a JSON profile object</li>
<li>Split up the profile into tokens, sign the tokens, and put them in a token file</li>
<li>Create a zone file that points to the web location of the profile token file</li>
</ol>
<h3>Create a profile</h3>
<pre class='hljs'>const profileOfNaval = {
"@context": "http://schema.org/",
"@type": "Person",
"name": "Naval Ravikant",
"description": "Co-founder of AngelList"
}</pre>
<h3>Sign a profile as a single token</h3>
<pre class='hljs'>import { makeECPrivateKey, wrapProfileToken, Person } from 'blockstack'
const privateKey = makeECPrivateKey()
const person = new Person(profileOfNaval)
const token = person.toToken(privateKey)
const tokenFile = [wrapProfileToken(token)]</pre>
<h3>Verify an individual token</h3>
<pre class='hljs'><span class="hljs-keyword">import</span> { verifyProfileToken } <span class="hljs-keyword">from</span> <span class="hljs-string">'blockstack'</span>
<span class="hljs-keyword">try</span> {
<span class="hljs-keyword">const</span> decodedToken = verifyProfileToken(tokenFile[<span class="hljs-number">0</span>].token, publicKey)
} <span class="hljs-keyword">catch</span>(e) {
<span class="hljs-built_in">console</span>.log(e)
}</pre>
<h3>Recover a profile from a token file</h3>
<pre class='hljs'><span class="hljs-keyword">const</span> recoveredProfile = Person.fromToken(tokenFile, publicKey)</pre>
<h3>Validate profile schema</h3>
<pre class='hljs'><span class="hljs-keyword">const</span> validationResults = Person.validateSchema(recoveredProfile)</pre>
<h3>Where profile data is stored</h3>
<p>Profile data is stored using Gaia on the user's selected storage provider.</p>
<p>An example of a profile.json file URL using Blockstack provided storage:
<code>https://gaia.blockstack.org/hub/1EeZtGNdFrVB2AgLFsZbyBCF7UTZcEWhHk/profile.json</code></p>
<h3>Validate a proof</h3>
<pre class='hljs'>import { validateProofs } from 'blockstack'
const domainName = "naval.id"
validateProofs(profile, domainName).then((proofs) =&gt; {
console.log(proofs)
})</pre>
<h3>How proofs are validated</h3>
<p>The <code>validateProofs</code> function checks each of the proofs listed in the
profile by fetching the proof URL and verifying the proof message.</p>
<p>The proof message must be of the form:</p>
<pre><code>Verifying my Blockstack ID is secured with the address
1EeZtGNdFrVB2AgLFsZbyBCF7UTZcEWhHk
</code></pre>
<p>The proof message also must appear in the required location on the
proof page specific to each type of social media account.</p>
<p>The account from which the proof message is posted must match exactly
the account identifier/username claimed in the user profile. The
<code>validateProofs</code> function will check this in the body of the proof or
in the proof URL depending on the service.</p>
<h3>Adding additional social account validation services</h3>
<p>The <code>Service</code> class can be extended to provide proof validation service
to additional social account types. You will need to override the
<code>getProofStatement(searchText: string)</code> method which parses the proof
body and returns the proof message text. Additionally, the identifier
claimed should be verified in the proof URL or in the body by implementing
<code>getProofIdentity(searchText: string)</code> and setting <code>shouldValidateIdentityInBody()</code>
to return true.</p>
<p>The following snippet uses the meta tags in the proof page to retrieve the proof message.</p>
<pre class='hljs'><span class="hljs-keyword">static</span> getProofStatement(searchText: string) {
<span class="hljs-keyword">const</span> $ = cheerio.load(searchText)
<span class="hljs-keyword">const</span> statement = $(<span class="hljs-string">'meta[property="og:description"]'</span>)
.attr(<span class="hljs-string">'content'</span>)
<span class="hljs-keyword">if</span> (statement !== <span class="hljs-literal">undefined</span> &amp;&amp; statement.split(<span class="hljs-string">':'</span>).length &gt; <span class="hljs-number">1</span>) {
<span class="hljs-keyword">return</span> statement.split(<span class="hljs-string">':'</span>)[<span class="hljs-number">1</span>].trim().replace(<span class="hljs-string">'“'</span>, <span class="hljs-string">''</span>).replace(<span class="hljs-string">'”'</span>, <span class="hljs-string">''</span>)
} <span class="hljs-keyword">else</span> {
<span class="hljs-keyword">return</span> <span class="hljs-string">''</span>
}
}</pre>
<h3>Currently supported proof validation services</h3>
<ul>
<li>Facebook</li>
<li>Twitter</li>
<li>Instagram</li>
<li>LinkedIn</li>
<li>Hacker News</li>
<li>GitHub</li>
</ul>
<h3>Profile proof schema</h3>
<p>Proofs are stored under the <code>account</code> key in the user's profile data</p>
<pre class='hljs'><span class="hljs-string">"account"</span>: [
{
<span class="hljs-string">"@type"</span>: <span class="hljs-string">"Account"</span>,
<span class="hljs-string">"service"</span>: <span class="hljs-string">"twitter"</span>,
<span class="hljs-string">"identifier"</span>: <span class="hljs-string">"naval"</span>,
<span class="hljs-string">"proofType"</span>: <span class="hljs-string">"http"</span>,
<span class="hljs-string">"proofUrl"</span>: <span class="hljs-string">"https://twitter.com/naval/status/12345678901234567890"</span>
}
]</pre>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='extractprofile'>
extractProfile
</h3>
</div>
<p>Extracts a profile from an encoded token and optionally verifies it,
if <code>publicKeyOrAddress</code> is provided.</p>
<div class='pre p1 fill-light mt0'>extractProfile(token: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, publicKeyOrAddress: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>token</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the token to be extracted
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>publicKeyOrAddress</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>null</code>)</code>
the public key or address of the
keypair that is thought to have signed the token
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
the profile extracted from the encoded token
<div class='py1 quiet mt1 prose-big'>Throws</div>
<ul>
<li><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a>: if the token isn't signed by the provided
<code>publicKeyOrAddress</code>
</li>
</ul>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='wrapprofiletoken'>
wrapProfileToken
</h3>
</div>
<p>Wraps a token for a profile token file</p>
<div class='pre p1 fill-light mt0'>wrapProfileToken(token: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>token</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the token to be wrapped
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
including
<code>token</code>
and
<code>decodedToken</code>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='signprofiletoken'>
signProfileToken
</h3>
</div>
<p>Signs a profile token</p>
<div class='pre p1 fill-light mt0'>signProfileToken(profile: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, privateKey: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, subject: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, issuer: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, signingAlgorithm: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, issuedAt: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a>, expiresAt: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>profile</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
the JSON of the profile to be signed
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>privateKey</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the signing private key
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>subject</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
the entity that the information is about
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>issuer</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
the entity that is issuing the token
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>signingAlgorithm</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>&#39;ES256K&#39;</code>)</code>
the signing algorithm to use
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>issuedAt</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a>
= <code>new Date()</code>)</code>
the time of issuance of the token
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>expiresAt</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a>
= <code>nextYear()</code>)</code>
the time of expiration of the token
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
the signed profile token
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='verifyprofiletoken'>
verifyProfileToken
</h3>
</div>
<p>Verifies a profile token</p>
<div class='pre p1 fill-light mt0'>verifyProfileToken(token: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, publicKeyOrAddress: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>token</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the token to be verified
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>publicKeyOrAddress</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the public key or address of the
keypair that is thought to have signed the token
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
the verified, decoded profile token
<div class='py1 quiet mt1 prose-big'>Throws</div>
<ul>
<li><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a>: throws an error if token verification fails
</li>
</ul>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='validateproofs'>
validateProofs
</h3>
</div>
<p>Validates the social proofs in a user's profile. Currently supports validation of
Facebook, Twitter, GitHub, Instagram, LinkedIn and HackerNews accounts.</p>
<div class='pre p1 fill-light mt0'>validateProofs(profile: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, ownerAddress: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, name: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>profile</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
The JSON of the profile to be validated
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>ownerAddress</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)</code>
The owner bitcoin address to be validated
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>name</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
= <code>null</code>)</code>
The Blockstack name to be validated
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to an array of validated proof objects
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='lookupprofile'>
lookupProfile
</h3>
</div>
<p>Look up a user profile by blockstack ID</p>
<div class='pre p1 fill-light mt0'>lookupProfile(username: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, zoneFileLookupURL: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>username</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)</code>
The Blockstack ID of the profile to look up
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>zoneFileLookupURL</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
= <code>null</code>)</code>
The URL
to use for zonefile lookup. If falsey, lookupProfile will use the
blockstack.js getNameInfo function.
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to a profile object
</section>
<div class='keyline-top-not py2'>
<section class='py2 clearfix'>
<h2 id='storage' class='mt0'>
Storage
</h2>
<blockquote>
<p><strong>Notes</strong>:</p>
<p>1) Blockstack Gaia Storage APIs and on-disk format will change in
upcoming pre-releases breaking backward compatibility. File encryption is currently
opt-in on a file by file basis.</p>
<p>2) Certain storage features such as and collections are not implemented in the current
version. These features will be rolled out in future updates.</p>
</blockquote>
<h2>Creating a file</h2>
<pre class='hljs'> blockstack.putFile(<span class="hljs-string">"/hello.txt"</span>, <span class="hljs-string">"hello world!"</span>)
.then(<span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
<span class="hljs-comment">// /hello.txt exists now, and has the contents "hello world!".</span>
})</pre>
<h2>Reading a file</h2>
<pre class='hljs'> blockstack.getFile(<span class="hljs-string">"/hello.txt"</span>)
.then(<span class="hljs-function">(<span class="hljs-params">fileContents</span>) =&gt;</span> {
<span class="hljs-comment">// get the contents of the file /hello.txt</span>
assert(fileContents === <span class="hljs-string">"hello world!"</span>)
});</pre>
<h2>Creating an encrypted file</h2>
<pre class='hljs'> <span class="hljs-keyword">let</span> options = {
<span class="hljs-attr">encrypt</span>: <span class="hljs-literal">true</span>
}
blockstack.putFile(<span class="hljs-string">"/message.txt"</span>, <span class="hljs-string">"Secret hello!"</span>, options)
.then(<span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
<span class="hljs-comment">// message.txt exists now, and has the contents "hello world!".</span>
})</pre>
<h2>Reading an encrypted file</h2>
<pre class='hljs'> <span class="hljs-keyword">let</span> options = {
<span class="hljs-attr">decrypt</span>: <span class="hljs-literal">true</span>
}
blockstack.getFile(<span class="hljs-string">"/message.txt"</span>, options)
.then(<span class="hljs-function">(<span class="hljs-params">fileContents</span>) =&gt;</span> {
<span class="hljs-comment">// get &amp; decrypt the contents of the file /message.txt</span>
assert(fileContents === <span class="hljs-string">"Secret hello!"</span>)
});</pre>
<h2>Reading another user's unencrypted file</h2>
<p>In order for files to be publicly readable, the app must request
the <code>publish_data</code> scope during authentication.</p>
<pre class='hljs'> <span class="hljs-keyword">let</span> options = {
<span class="hljs-attr">user</span>: <span class="hljs-string">'ryan.id'</span>, <span class="hljs-comment">// the Blockstack ID of the user for which to lookup the file</span>
app: <span class="hljs-string">'http://BlockstackApp.com'</span> <span class="hljs-comment">// origin of the app this file is stored for</span>
}
blockstack.getFile(<span class="hljs-string">"/message.txt"</span>, options)
.then(<span class="hljs-function">(<span class="hljs-params">fileContents</span>) =&gt;</span> {
<span class="hljs-comment">// get the contents of the file /message.txt</span>
assert(fileContents === <span class="hljs-string">"hello world!"</span>)
});</pre>
<h2>Deleting a file</h2>
<p><em>Note: deleteFile is currently not implemented. For now, we recommend
writing an empty file to wipe data</em></p>
<pre class='hljs'> blockstack.deleteFile(<span class="hljs-string">"/hello.txt"</span>)
.then(<span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
<span class="hljs-comment">// /hello.txt is now removed.</span>
})</pre>
</section>
</div>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='storage'>
Storage
</h3>
</div>
<blockquote>
<p><strong>Notes</strong>:</p>
<p>1) Blockstack Gaia Storage APIs and on-disk format will change in
upcoming pre-releases breaking backward compatibility. File encryption is currently
opt-in on a file by file basis.</p>
<p>2) Certain storage features such as and collections are not implemented in the current
version. These features will be rolled out in future updates.</p>
</blockquote>
<h2>Creating a file</h2>
<pre class='hljs'> blockstack.putFile(<span class="hljs-string">"/hello.txt"</span>, <span class="hljs-string">"hello world!"</span>)
.then(<span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
<span class="hljs-comment">// /hello.txt exists now, and has the contents "hello world!".</span>
})</pre>
<h2>Reading a file</h2>
<pre class='hljs'> blockstack.getFile(<span class="hljs-string">"/hello.txt"</span>)
.then(<span class="hljs-function">(<span class="hljs-params">fileContents</span>) =&gt;</span> {
<span class="hljs-comment">// get the contents of the file /hello.txt</span>
assert(fileContents === <span class="hljs-string">"hello world!"</span>)
});</pre>
<h2>Creating an encrypted file</h2>
<pre class='hljs'> <span class="hljs-keyword">let</span> options = {
<span class="hljs-attr">encrypt</span>: <span class="hljs-literal">true</span>
}
blockstack.putFile(<span class="hljs-string">"/message.txt"</span>, <span class="hljs-string">"Secret hello!"</span>, options)
.then(<span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
<span class="hljs-comment">// message.txt exists now, and has the contents "hello world!".</span>
})</pre>
<h2>Reading an encrypted file</h2>
<pre class='hljs'> <span class="hljs-keyword">let</span> options = {
<span class="hljs-attr">decrypt</span>: <span class="hljs-literal">true</span>
}
blockstack.getFile(<span class="hljs-string">"/message.txt"</span>, options)
.then(<span class="hljs-function">(<span class="hljs-params">fileContents</span>) =&gt;</span> {
<span class="hljs-comment">// get &amp; decrypt the contents of the file /message.txt</span>
assert(fileContents === <span class="hljs-string">"Secret hello!"</span>)
});</pre>
<h2>Reading another user's unencrypted file</h2>
<p>In order for files to be publicly readable, the app must request
the <code>publish_data</code> scope during authentication.</p>
<pre class='hljs'> <span class="hljs-keyword">let</span> options = {
<span class="hljs-attr">user</span>: <span class="hljs-string">'ryan.id'</span>, <span class="hljs-comment">// the Blockstack ID of the user for which to lookup the file</span>
app: <span class="hljs-string">'http://BlockstackApp.com'</span> <span class="hljs-comment">// origin of the app this file is stored for</span>
}
blockstack.getFile(<span class="hljs-string">"/message.txt"</span>, options)
.then(<span class="hljs-function">(<span class="hljs-params">fileContents</span>) =&gt;</span> {
<span class="hljs-comment">// get the contents of the file /message.txt</span>
assert(fileContents === <span class="hljs-string">"hello world!"</span>)
});</pre>
<h2>Deleting a file</h2>
<p><em>Note: deleteFile is currently not implemented. For now, we recommend
writing an empty file to wipe data</em></p>
<pre class='hljs'> blockstack.deleteFile(<span class="hljs-string">"/hello.txt"</span>)
.then(<span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
<span class="hljs-comment">// /hello.txt is now removed.</span>
})</pre>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getappbucketurl'>
getAppBucketUrl
</h3>
</div>
<p>Get the app storage bucket URL</p>
<div class='pre p1 fill-light mt0'>getAppBucketUrl(gaiaHubUrl: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, appPrivateKey: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>gaiaHubUrl</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the gaia hub URL
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>appPrivateKey</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the app private key used to generate the app address
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
That resolves to the URL of the app index file
or rejects if it fails
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getuserappfileurl'>
getUserAppFileUrl
</h3>
</div>
<p>Fetch the public read URL of a user file for the specified app.</p>
<div class='pre p1 fill-light mt0'>getUserAppFileUrl(path: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, username: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, appOrigin: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, zoneFileLookupURL: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>path</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the path to the file to read
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>username</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
The Blockstack ID of the user to look up
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>appOrigin</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
The app origin
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>zoneFileLookupURL</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>null</code>)</code>
The URL
to use for zonefile lookup. If falsey, this will use the
blockstack.js's getNameInfo function instead.
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to the public read URL of the file
or rejects with an error
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getfile'>
getFile
</h3>
</div>
<p>Retrieves the specified file from the app's data store.</p>
<div class='pre p1 fill-light mt0'>getFile(path: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>path</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the path to the file to read
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.decrypt</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>true</code>)
</td>
<td class='break-word'><span>try to decrypt the data with the app private key
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.username</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the Blockstack ID to lookup for multi-player storage
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.verify</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
</td>
<td class='break-word'><span>Whether the content should be verified, only to be used
when
<code>putFile</code>
was set to
<code>sign = true</code>
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.app</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the app to lookup for multi-player storage -
defaults to current origin
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.zoneFileLookupURL</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
(default <code>null</code>)
</td>
<td class='break-word'><span>The URL
to use for zonefile lookup. If falsey, this will use the
blockstack.js's getNameInfo function instead.
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to the raw data in the file
or rejects with an error
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='putfile'>
putFile
</h3>
</div>
<p>Stores the data provided in the app's data store to to the file specified.</p>
<div class='pre p1 fill-light mt0'>putFile(path: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, content: (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>), options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>path</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the path to store the data in
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>content</span> <code class='quiet'>((<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>))</code>
the data to store in the file
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.encrypt</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
(default <code>true</code>)
</td>
<td class='break-word'><span>encrypt the data with the app public key
or the provided public key
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.sign</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>false</code>)
</td>
<td class='break-word'><span>sign the data using ECDSA on SHA256 hashes with
the app private key
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.contentType</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
(default <code>&#39;&#39;</code>)
</td>
<td class='break-word'><span>set a Content-Type header for unencrypted data
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves if the operation succeed and rejects
if it failed
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='encryptcontent'>
encryptContent
</h3>
</div>
<p>Encrypts the data provided with the app public key.</p>
<div class='pre p1 fill-light mt0'>encryptContent(content: (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>), options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>content</span> <code class='quiet'>((<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>))</code>
data to encrypt
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.publicKey</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the hex string of the ECDSA public
key to use for encryption. If not provided, will use user's appPublicKey.
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>:
Stringified ciphertext object
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='decryptcontent'>
decryptContent
</h3>
</div>
<p>Decrypts data encrypted with <code>encryptContent</code> with the
transit private key.</p>
<div class='pre p1 fill-light mt0'>decryptContent(content: (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>), options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>)</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>content</span> <code class='quiet'>((<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>))</code>
encrypted content.
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.privateKey</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the hex string of the ECDSA private
key to use for decryption. If not provided, will use user's appPrivateKey.
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>)</code>:
decrypted content.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='listfiles'>
listFiles
</h3>
</div>
<p>List the set of files in this application's Gaia storage bucket.</p>
<div class='pre p1 fill-light mt0'>listFiles(callback: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">function</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>callback</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">function</a>)</code>
a callback to invoke on each named file that
returns
<code>true</code>
to continue the listing operation or
<code>false</code>
to end it
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to the number of files listed
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getauthresponsetoken'>
getAuthResponseToken
</h3>
</div>
<p>Retrieve the authentication token from the URL query</p>
<div class='pre p1 fill-light mt0'>getAuthResponseToken(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>:
the authentication token if it exists otherwise
<code>null</code>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getnameprice'>
getNamePrice
</h3>
</div>
<p>Get the price of a name.</p>
<div class='pre p1 fill-light mt0'>getNamePrice(fullyQualifiedName: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>fullyQualifiedName</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the name to query
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise to an Object with { units: String, amount: BigInteger }, where
.units encodes the cryptocurrency units to pay (e.g. BTC, STACKS), and
.amount encodes the number of units, in the smallest denominiated amount
(e.g. if .units is BTC, .amount will be satoshis; if .units is STACKS,
.amount will be microStacks)
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getnamespaceprice'>
getNamespacePrice
</h3>
</div>
<p>Get the price of a namespace</p>
<div class='pre p1 fill-light mt0'>getNamespacePrice(namespaceID: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>namespaceID</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the namespace to query
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise to an Object with { units: String, amount: BigInteger }, where
.units encodes the cryptocurrency units to pay (e.g. BTC, STACKS), and
.amount encodes the number of units, in the smallest denominiated amount
(e.g. if .units is BTC, .amount will be satoshis; if .units is STACKS,
.amount will be microStacks)
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getgraceperiod'>
getGracePeriod
</h3>
</div>
<p>How many blocks can pass between a name expiring and the name being able to be
re-registered by a different owner?</p>
<div class='pre p1 fill-light mt0'>getGracePeriod(): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise to the number of blocks
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getnamesowned'>
getNamesOwned
</h3>
</div>
<p>Get the names -- both on-chain and off-chain -- owned by an address.</p>
<div class='pre p1 fill-light mt0'>getNamesOwned(address: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>address</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the blockchain address (the hash of the owner public key)
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to a list of names (Strings)
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getnamespaceburnaddress'>
getNamespaceBurnAddress
</h3>
</div>
<p>Get the blockchain address to which a name's registration fee must be sent
(the address will depend on the namespace in which it is registered.)</p>
<div class='pre p1 fill-light mt0'>getNamespaceBurnAddress(namespace: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>namespace</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the namespace ID
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to an address (String)
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getnameinfo'>
getNameInfo
</h3>
</div>
<p>Get WHOIS-like information for a name, including the address that owns it,
the block at which it expires, and the zone file anchored to it (if available).</p>
<div class='pre p1 fill-light mt0'>getNameInfo(fullyQualifiedName: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>fullyQualifiedName</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the name to query. Can be on-chain of off-chain.
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to the WHOIS-like information
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getnamespaceinfo'>
getNamespaceInfo
</h3>
</div>
<p>Get the pricing parameters and creation history of a namespace.</p>
<div class='pre p1 fill-light mt0'>getNamespaceInfo(namespaceID: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>namespaceID</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the namespace to query
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to the namespace information.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getzonefile'>
getZonefile
</h3>
</div>
<p>Get a zone file, given its hash. Throws an exception if the zone file
obtained does not match the hash.</p>
<div class='pre p1 fill-light mt0'>getZonefile(zonefileHash: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>zonefileHash</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the ripemd160(sha256) hash of the zone file
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to the zone file's text
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getaccountstatus'>
getAccountStatus
</h3>
</div>
<p>Get the status of an account for a particular token holding. This includes its total number of
expenditures and credits, lockup times, last txid, and so on.</p>
<div class='pre p1 fill-light mt0'>getAccountStatus(address: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, tokenType: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>address</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the account
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>tokenType</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the token type to query
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to an object representing the state of the account
for this token
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getaccounthistorypage'>
getAccountHistoryPage
</h3>
</div>
<p>Get a page of an account's transaction history.</p>
<div class='pre p1 fill-light mt0'>getAccountHistoryPage(address: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, page: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>address</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the account's address
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>page</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code>
the page number. Page 0 is the most recent transactions
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to an Array of Objects, where each Object encodes
states of the account at various block heights (e.g. prior balances, txids, etc)
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getaccountat'>
getAccountAt
</h3>
</div>
<p>Get the state(s) of an account at a particular block height. This includes the state of the
account beginning with this block's transactions, as well as all of the states the account
passed through when this block was processed (if any).</p>
<div class='pre p1 fill-light mt0'>getAccountAt(address: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, blockHeight: Integer): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>address</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the account's address
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>blockHeight</span> <code class='quiet'>(Integer)</code>
the block to query
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to an Array of Objects, where each Object encodes
states of the account at this block.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getaccounttokens'>
getAccountTokens
</h3>
</div>
<p>Get the set of token types that this account owns</p>
<div class='pre p1 fill-light mt0'>getAccountTokens(address: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>address</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the account's address
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to an Array of Strings, where each item encodes the
type of token this account holds (excluding the underlying blockchain's tokens)
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getaccountbalance'>
getAccountBalance
</h3>
</div>
<p>Get the number of tokens owned by an account. If the account does not exist or has no
tokens of this type, then 0 will be returned.</p>
<div class='pre p1 fill-light mt0'>getAccountBalance(address: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, tokenType: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>address</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the account's address
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>tokenType</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the type of token to query.
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise that resolves to a BigInteger that encodes the number of tokens
held by this account.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='estimatetokentransfer'>
estimateTokenTransfer
</h3>
</div>
<p>Estimates the cost of a token-transfer transaction</p>
<div class='pre p1 fill-light mt0'>estimateTokenTransfer(recipientAddress: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, tokenType: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, tokenAmount: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, scratchArea: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, senderUtxos: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>, additionalOutputs: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>recipientAddress</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the recipient of the tokens
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>tokenType</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the type of token to spend
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>tokenAmount</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
a 64-bit unsigned BigInteger encoding the number of tokens
to spend
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>scratchArea</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
an arbitrary string to store with the transaction
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>senderUtxos</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>
= <code>1</code>)</code>
the number of utxos we expect will
be required from the importer address
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>additionalOutputs</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>
= <code>1</code>)</code>
the number of outputs we expect to add beyond
just the recipient output (default = 1, if the token owner is also the bitcoin funder)
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
a promise which resolves to the satoshi cost to
fund this token-transfer transaction
</section>
</div>
</div>
<script src='assets/anchor.js'></script>
<script src='assets/split.js'></script>
<script src='assets/site.js'></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink