Docs update, getting started (#219)

* Docs update, getting started * Typos * Cleanups, linking * Update with additional packages
2026-04-22 05:37:58 +00:00 · 2019-10-16 12:35:34 +02:00
parent b1c1f108e7
commit c58835059d
12 changed files with 367 additions and 11 deletions
@@ -7,7 +7,7 @@

 # @polkadot/ui

-Basic browser and UI components for creating apps using the polkadot{.js} libraries
+Basic browser and framework agnostic UI components for creating apps using the polkadot{.js} libraries

 ## overview

@@ -18,7 +18,7 @@ The following UI components are currently available -
 - [vue-identicon](packages/vue-identicon/) Vue identity icon generator with address as input
 - [react-qr](packages/react-qr/) QR code generator/reader for [uos](https://github.com/maciejhirsz/uos) (Substrate/Polkadot only)

-Additionally some shared libraries -
+Additionally some shared libraries, that is not dependent on any framework -

 - [ui-assets](packages/ui-assets/) Static assets, images and others, shared accross projects
 - [ui-keyring](packages/ui-keyring/) A browser-specific wrapper around the base [@polkadot/util-keyring](https://github.com/polkadot-js/util/) library
@@ -30,4 +30,5 @@ Additionally some shared libraries -
 In addition to the above packages, there are examples available for intergation  of `ui-keyring`, `ui-settings` & the relevant `*-identicon` package. These are

 - [example-react](packages/example-react) - start with `yarn example:react` and view on `http://localhost:8080`
+- [example-reactnative](packages/exampleReactNative) - start with `yarn example:rn:packager` to start the packager service and then either `yarn example:rn:android` or `yarn example:rn:ios` in another terminal
 - [example-vue](packages/example-vue) - start with `yarn example:vue` and view on `http://localhost:8080`
@@ -22,6 +22,21 @@ module.exports = {
    ],
    search: false,
    sidebar: [
+      {
+        title: 'Getting started',
+        path: '/start/',
+        collapsable: false,
+        sidebarDepth: 0,
+        children: [
+          ['start/packages.md', 'Available packages'],
+          ['start/keyring.md', 'Keyring'],
+          ['start/keyring.accounts.md', 'Keyring accounts'],
+          ['start/keyring.derivation.md', 'Account derivation'],
+          ['start/keyring.retrieve.md', 'Account retrieval'],
+          ['start/keyring.other.md', 'Other addresses'],
+          ['start/FAQ.md', 'FAQ']
+        ]
+      },
      ['/react-identicon/', '@polkadot/react-identicon'],
      ['/react-qr/', '@polkadot/react-qr'],
      ['/reactnative-identicon/', '@polkadot/reactnative-identicon'],
@@ -6,29 +6,30 @@ tagline:
 # actionText: Repository Overview
 # actionLink: /REPOS.md
 features:
+- title: Frameworks
+  details: We support multiple UI frameworks, including React, React Native and Vue.
 - title: Identicon
  details: A flexible identity icon generator supporting a number of display styles based on theme.
 - title: Keyring
  details: An extension to the base keyring that allows for additions such as browser storage.
- title: Utilities
-  details: Utilities for formatting and working with settings inside any browser-based application.

 footer: Apache-2 Licensed | Copyright © 2017-2019 polkadot-js authors and contributors
 ---

 ## Welcome

-This is a collection of UI libraries, utlities and classes that allows for easier use of the Polkadot JS infrastructure inside your apps.
+This is a collection of UI libraries, utilities and classes that allows for easier use of the Polkadot JS infrastructure inside your apps.

-::: tip Examples
-In a rush and just want examples? [Jump right in](react-identicon/README.md) and get a handle the libraries in your projects.
+::: tip Getting started
+For those new to these repose, we provide a [getting started](start/README.md) guide to take you from the tame to the insane.
 :::

 ## Available packages

 This repository split up into a number of internal packages, namely -

- [React Identicon](react-identicon/README.md) Display of identity icons based on theme, also availble for [React Native](reactnative-identicon/README.md) and [Vue](vue-identicon/README.md)
+- Examples take a short dive into some functionality, either for [React](example-react/README.md), [React Native](exampleReactNative) and [Vue](example-vue/README.md).
+- Identicons display identity icons based on theme, available for [React](react-identicon/README.md) also availble for [React Native](reactnative-identicon/README.md) and [Vue](vue-identicon/README.md)
 - [keyring](ui-keyring/README.md) A keyring with browser-specific extensions
 - [settings](ui-settings/README.md) Setting management and defaults

@@ -0,0 +1,11 @@
+# FAQ
+
+The list will be updated/expanded as questions come up, dealing with some common issues that users find.
+
+## I have a crypto has not been initialized error
+
+When using the keyring, make sure that you are [initializing the keyring](keyring.md#initialization) before attempting to use it. Generally you would hook this into the async API creation (which transparently caters for the WASM load).
+
+## My React Native build runs out of memory
+
+When using the keyring packages with RN, due to a lack of support, an [asm.js fallback](https://github.com/polkadot-js/wasm/issues/19) is provided. This does however all some memory load to the application build process (and is by no means fast), ensure that you adjust your build flags to include `NODE_OPTIONS=--max_old_space_size=8192`, for instance doing `NODE_OPTIONS=--max_old_space_size=8192 yarn run ios`
@@ -0,0 +1,15 @@
+# Getting started
+
+These sections should provide you with all the information needed to install any packages in this repo, understand the structure of the interfaces and allow you to start using it. It really focusses on the general packages with any framework-specific packages such as icons as detailed in their own section.
+
+## What this is not
+
+This is not line-by-line documentation of all the existing function calls available, nor it is tied to a specific framework that you may end up using. We have users using frameworks such as Angular, Electron, React, React Native, Next.js and Vue and even support direct environments such as browser extensions, Electron apps in addition to the normal web applications you may be used to. There will be some things in the libraries that are probably not covered, which brings us to the next point...
+
+## Help us help others
+
+If you spot gaps in the information provided, or are uncertain about any specific area, please do [log an issue](https://github.com/polkadot-js/ui/issues) or if you are that way inclined, make a pull-request. We really want to have good documentation in these areas and allow people to be productive right from the start.
+
+## Ready? Steady? Go!
+
+If you already have a good grasp on the API and are just looking for a specific answer, you may want to take a look at the [Frequently Asked Questions](FAQ.md). With all that said, let's get started... [What are all these things and what can I do with it](packages.md)
@@ -0,0 +1,49 @@
+# Keyring accounts
+
+With our keyring setup completed in the previous section, and all available accounts loaded, we are ready to proceed. However we have not actually loaded any accounts yet, since well, we have not created or stored any previously. So let's change that.
+
+## Adding accounts
+
+The keyring has a number of ways to add accounts, but in 99% of the cases, you should need only a single method to add an account to the keyring - `addUri(suri: string, password?: string, meta: KeyringPair$Meta = {}, type?: KeypairType)`. Let's jump in with some explicit examples -
+
+```js
+import { mnemonicGenerate } from '@polkadot/util-crypto';
+
+...
+// generate a random mnemonic, 12 words in length
+const mnemonic = mnemonicGenerate(12);
+
+// add the account, encrypt the stored JSON with an account-specific password
+const { pair, json } = keyring.addUri(mnemonic, 'myStr0ngP@ssworD', { name: 'mnemonic acc' });
+```
+
+The above example is relatively straight-forward. Create an account with the specified mnemonic, encrypt the account (as stored) with the password and attach some metadata to the account. It returns a pair instance (we will work with these later) as well as the encrypted json as is saved to the store.
+
+Metadata is free form, with any indicators that you would find useful in your application. Some fields that are known to be used in (and also exists other keyring entries such as contacts & contracts) includes -
+
+- `genesisHash` - a hex value of the genesis this accounts belong to. If specified, the account will only be loaded when the same genesisHash is available in the keyring options
+
+- `name` - a human-readable description for the account
+
+## Non-mnemonic accounts
+
+Generally, we would encourage all wallets and users to only support mnemonic phrases - these are portable between crypto implementations, has built-in checksums and is a standard across the blockchain environment.
+
+In some cases however, either due to the need to provide backwards compatibility or for closed environments, other seed types may be used. The `addUri` will detect the type of input, i.e. if a hex-encoded value is provided, it will treat it as a raw seed. With this in mind, we can rewrite our example above to generate a random raw seed -
+
+```js
+import { randomAsHex } from '@polkadot/util-crypto';
+
+...
+// generate a random hex raw seed, this needs to be 32 bytes in length
+const seed = randomAsHex(32);
+
+// add the account, encrypting it, override to ed25519
+const { pair, json } = keyring.addUri(seed, 'weakpass', { name: 'hex seed acc' }, 'ed25519');
+```
+
+In addition to creating the account in the same fashion as in the preceding section, we are overriding the type of the account created here. Assuming we created the keyring with the `type: 'sr25519'` option, the first mnemonic account was created with an `sr25519` type. Here we specify the type of crypto explicitly, and therefore create a non-default (for this keyring instance) `ed25519` type.
+
+## Deriving accounts
+
+In the next section, we will expand our account creation capabilities and take a look at [account derivation and passing suri options](keyring.derivation.md).
@@ -0,0 +1,29 @@
+# Account derivation
+
+[Secret URIs](https://github.com/paritytech/substrate/wiki/Secret-URI-Test-Vectors) are a way of describing the phrase/seed along with derivation paths. This explains the naming of the default add as `addUri(...)`, it can handle mnemonics, seeds and apply suri derivations on these.
+
+## Diving in
+
+As a follow-up on what we have done in the preceding section, we take a dive into expanding our account addition with derivation, in this case we are applying two hard paths, `hard` followed by `derivation` -
+
+```js
+...
+// add the account with hard derivation paths
+keyring.addUri(`${mnemonic}//hard//derivation`, 'donotcare', { name: 'testing derive' });
+```
+
+This format is standard across the `@polkadot/keyring`, `@polkadot/ui-keyring` as well as [Substrate subkey](https://github.com/paritytech/substrate/tree/master/subkey), so it is a Polkadot/Substrate specific way of defining derivation paths.
+
+## Understanding paths
+
+To build a suri, you paths, the format is always `<mnemonic or seed>[//hard][/soft][///password]` and it is  passed as-is to the `addUri(...)` function. the derivation types are -
+
+- Soft derivation, i.e `/<soft path>` - Here a single slash, `/`, denotes a soft derivation. Please note that any pair with an `ed25519` type does not support soft derivations, these are only applicable to `sr25519` types.
+
+- Hard derivation, i.e. `//<hard path>` - Here two slashes, `//`, denoted a hard derivation. This  is available to both `sr25519` and `ed25519` pairs. Underlying it will apply a hashing function on the secret, generating a new secret for the remainder of the derivations.
+
+- Password, i.e. `///<password>` - Here three slashed, `///`, denoted the (optional) password. Unlike hard and soft derivations that can be mixed, only a single password should be specified. The password here applies to the actual uri, not be be confused by the JSON encryption password. It is an additional security layer - if your full mnemonic and all paths do leak without the password, a bad actor would still not be able to generate a compatible secret to access funds without the password.
+
+## Retrieving accounts
+
+With a fim grasp on adding accounts, next we will take a look at [retrieving account and account subscriptions](keyring.retrieve.md).
@@ -0,0 +1,104 @@
+# Keyring
+
+The [@polkadot/ui-keyring](https://www.npmjs.com/package/@polkadot/ui-keyring) package provides a wrapper around the [@polkadot/keyring](https://www.npmjs.com/package/@polkadot/keyring) package, specifically for use in browser environments. The `ui-keyring` only extends the `keyring`, but does not replace it. All underlying account management functions are provided by the base keyring, the browser-specific extensions allows for transparent management of account state in storage.
+
+Additionally where the base keyring is focussed on accounts, the `ui-keyring` extends this to cater for an address-book, contracts and allows for accounts to be tied to a specific chain. Since UIs are typically split into different parts, it also allows for subscriptions on accounts, so notifications are available when accounts are added or removed.
+
+## Installation
+
+If you already use the [@polkadot/api](https://www.npmjs.com/package/@polkadot/api) in your project (which is true in most cases), you don't need anything more than `yarn add @polkadot/ui-keyring`.
+
+If however you use the `ui-keyring` independently (i.e. in an address generator, like the examples) you would need the `keyring` dependency as well, `yarn add @polkadot/keyring @polkadot/ui-keyring`. (In the first case the `@polkadot/api` already comes bundled with the base keyring, so no additional dependencies are needed).
+
+## Initialization
+
+To understand the initialization process, some background on the underlying libraries are required. For the [Schnorrkel sr25519](https://github.com/w3f/schnorrkel) a WASM library is used. This means that before `sr25519` can be used, the WASM libraries needs to be loaded and initialized. This is not an issue when the keyring only uses `ed25519`.
+
+With this in mind, we take care of the  initialization as before we load our keyring, yielding -
+
+```js
+import keyring from '@polkadot/ui-keyring';
+import { cryptoWaitReady } from '@polkadot/util-crypto';
+
+cryptoWaitReady().then(() => {
+  // load all available addresses and accounts
+  keyring.loadAll({ ss58Format: 42, type: 'sr25519' });
+
+  // additional initialization here, including rendering
+});
+```
+
+The `cryptoWaitReady()` promise resolves as soon as the underlying WASM libraries have been made available. This is followed by `keyring.loadAll(...)` which is the main initialization for the keyring, which
+
+- initializes the underlying `@polkadot/keyring`
+- loads all available accounts, addresses band contracts previously stored
+- sets up the default address format with `42` (This is the substrate development default. When not specified, this defaults to `42`)
+- defaults to `sr25519` accounts (We can still add `ed25519` accounts, more on this later. When not specified this defaults to `ed25519`)
+
+Since you would generally want the keyring available before rendering the UI (although it can be done elsewhere, showing some info while loading), the following pattern is used in our examples, both React and Vue shown here -
+
+```js
+...
+cryptoWaitReady().then(() => {
+  keyring.loadAll({ ... });
+
+  // mount React and render
+  ReactDOM.render(<App />, document.getElementById('app'));
+});
+```
+
+```js
+...
+cryptoWaitReady().then(() => {
+  keyring.loadAll({ ... });
+
+  // mount Vue and render
+  new Vue({ render: (h) => h(App) }).$mount('#app');
+});
+```
+
+When using the keyring together with the Polkadot-js API, the above would be adapted since the API itself already has a check for the WASM availability. In this case, we can adapt the interface to follow the following pattern -
+
+```js
+import { ApiPromise } from '@polkadot/api';
+import keyring from '@polkadot/ui-keyring';
+
+...
+ApiPromise.create({ ... }).then(() => {
+  keyring.loadAll({ ... });
+
+  // additional initialization here, including rendering
+});
+```
+
+The above pattern is how initialization is done in some applications such as the [polkadot-js apps UI](https://polkadot.js.org/apps/).
+
+## Additional create options
+
+In addition to the `ss58Format` and `type` options (both optional), the following additional configuration options are available to the `loadAll(...)` call -
+
+- `filter?: (json: KeyringJson) => boolean` - An optional filter that is executed on account loading. This allows us to check the loaded account and apply rules on it before including it in the keyring. Generally this would be used for advanced cases, any account that is filtered with `false` won't appear.
+
+- `genesisHash?: Hash` - The `genesisHash` of accounts to should be loaded. The meta property of the account _may_ contain a `genesisHash`, when both are available and non-matching, the account will not be included. To populate this option, the easiest way is to pass the `api.genesisHash` property.
+
+- `isDevelopment?: boolean` - This flag, when set to `true` loads the keyring in development mode. This means that the default development accounts such as "Alice", "Bob", ..., "Ferdie" are included in the keyring. Generally you would only specify this when  actually connected to a development chain.
+
+- `store?: KeyringStore` - An optional store to be used. By default the `ui-keyring` will user browser localStorage, but with a specific store this behavior can be adjusted. For instance, for an extension we would default to the extension store (although localStorage is available) and for Electron apps, we may want to default to file storage.
+
+```js
+import { ExtensionStore } from '@polkadot/ui-keyring/stores';
+
+// For file storage where available, e.g. in Electron environments.
+// This takes an path in the constructor, new FileStore('~./keyring-data')
+// import { FileStore } from '@polkadot/ui-keyring/stores';
+
+// When the store is not specified, it defaults to new BrowserStore()
+// import { BrowserStore } from '@polkadot/ui-keyring/stores';
+
+...
+keyring.loadAll({ store: new ExtensionStore(), ... });
+```
+
+## Managing accounts
+
+With the keyring installed and ready for use, [next we will dive into adding and managing accounts](keyring.accounts.md).
@@ -0,0 +1,41 @@
+# Other addresses
+
+As mentioned in previous sections, the keyring not only has the ability to manage accounts (i.e. keypairs), but also allows you to add addresses/contacts as well as contracts to the keyring. This is very useful in the case where you are developing a wallet and want to save external addresses to interact with.
+
+Here we will give an overview of working with addresses, the same concepts can be expanded to work with contracts.
+
+## Adding an address
+
+For accounts, we have the `addUri(...)` endpoint that allows us to create and save an account. For addresses, we the keyring exposes `saveAddress (address: string, meta: KeyringPair$Meta)`, which we can use to save any address -
+
+```js
+...
+// add the address
+const FAUCET_ADDR = 'FvnazYM5KAetYpXoVDfqt9WFcJogKbekXVJ3Fz5oW2Dv82P';
+const json = keyring.saveAddress(FAUCET_ADDR, { name: 'Alex faucet' });
+
+// the faucet will now be in the list of available addresses
+keyring.getAddresses().forEach(...)
+```
+
+From this point forward, the address is in your keyring and can be retrieved via the `getAddresses()` interface. The same call can be used to update the meta for the address, for instance if we wish to change the name above, we can do -
+
+```js
+...
+const json = keyring.saveAddress(FAUCET_ADDR, { name: 'Alexander Faucet' });
+```
+
+And the already-saved address will be updated with the new metadata.
+
+## Removing an address
+
+To clear and address and remove it from the keyring, we can use the `forgetAddress(address: string)` call, this mirrors the `forgetAccount(address: string)` and `forgetContract(address: string)` calls. For instance -
+
+```js
+...
+// remove the specific address
+keyring.forgetAddress(FAUCET_ADDR);
+
+/// the faucet will not be in the list of addresses anymore
+keyring.getAddresses().forEach(...)
+```
@@ -0,0 +1,57 @@
+# Account retrieval
+
+Adding accounts is good. Having access to these accounts when added via `const { pair } = keyring.addUr(...)` is better, but being able to access these to iterate over at a later point (even after reload), is magic. Here we will try to add some magic to your experience, allowing you to retrieve accounts as well as subscribe to changes as they happen.
+
+## Loading all available
+
+As we've seen in the keyring init section, when we can `loadAll`, it loads all added added - this includes those added via `addUri(...)` which transparently saves to the provided storage. Loading means it is available in the keyring, to get a list of the accounts, we can then do -
+
+```js
+import { u8aToHex } from '@polkadot/util';
+
+...
+const accounts = keyring.getAccounts();
+
+accounts.forEach(({ address, meta, publicKey }) =>
+  console.log(address, JSON.stringify(meta), u8aToHex(publicKey));
+);
+```
+
+The above interface was probably not quite what you have been expecting, rather you would have expected to get back a list of the pairs, but rather you received a list of the account descriptors. Some rationale for this approach - since we have `getAccounts()`, `getAddresses()` (for contacts) and `getContracts()` the consistent interface here is applicable. Instead based on an address, you can then retrieve a specific pair -
+
+```js
+accounts.forEach(({ address }) => {
+  // retrieve via address or publicKey
+  const pair = getPair(address);
+
+  // display the locked account status
+  console.log(address, pair.isLocked);
+});
+```
+
+Similarly we have a `getPairs()` that mirrors `getAccounts()`, but retrieves the list of available pairs - which is the output you probably expected from the initial `getAccounts()` call.
+
+## Subscriptions (Optional)
+
+In addition to the retrieving of accounts on demand, we can actually subscribe to accounts for the keyring. This subscription returns a list of all accounts as they are updated, i.e. when a new account is added it will callback with a list of all the account, including the new one, when an account is removed, it will callback with a list of accounts, excluding the removed member.
+
+```js
+...
+// create a subscription to all available accounts, updated real-time
+const sub = keyring.accounts.subject.subscribe((accounts) => {
+  accounts.forEach(({ json, option }) =>
+    // json is the stored data, including address
+    // option is a { name: meta.name, value: address }
+  );
+});
+
+...
+// at some point  when we are not interested anymore, we can unsubscribe
+sub.unsubscribe();
+```
+
+As with the `get{Accounts|Addresses|Contracts}()` functions, similarly we have in addition to `keyring.accounts.subject` the `keyring.addresses.subject` and `keyring.contracts.subject` subscriptions available, with the same generic result set.
+
+## Other address types
+
+We have been referencing contacts and contracts and number of times up till now, up next we will take a look at [how to store other addresses, be if for an address book or contract](keyring.other.md).
@@ -0,0 +1,35 @@
+# Available Packages
+
+Let's take a slightly deeper diver into the available packages that we provide. While we won't (yet) cover the specifics of Frameworks-specifics (suck as React, React Native or Vue), we will also take a slight detour from the rest of the  getting started sections, just allowing a comprehensive overview of everything provided... including the framework-specifics.
+
+## Organization
+
+Before we get to the available packages, just a note on the organization of the available items. We have a number of types of packages, with the following prefixes -
+
+- `@polkadot/example-*` - These are very basic examples that shows how to actually use the libraries in your own applications. for instance the `@polkadot/example-vue` shows step-by-step how to build a simple key generator with the keyring and the Vue-specific icons. (The `@polkadot/example-react` is equivalent... and we would love to see the same for React Native...)
+
+- `@polkadot/ui-*` - These packages are all framework agnostic. It doesn't matter if you use Angular, React or Vue - these packages are designed to be framework independent and should work in any environment that has the intent of being displayed in a browser window, yes, including Electron.
+
+- `@polkadot/react-*` - As the name suggests, these packages are meant for use with React. In some cases (e.g. UOS support), these may be slightly ahead of other frameworks. However where an equivalent package exists, we always aim for feature parity.
+
+- `@polkadot/reactnative-*` - Specifically for React Native applications.
+
+- `@polkadot/vue-*` - Specifically for Vue applications.
+
+With the above in mind, let's take an initial tour through the various generic implementations.
+
+##  Generic UI libraries
+
+As indicated, all of the `@polkadot/ui-*` packages are meant to be framework independent. The only common thread between these are that they are designed for use inside a browser, with no requirement for using a development framework.
+
+The first package we will look at is the [@polkadot/ui-assets package](https://www.npmjs.com/package/@polkadot/ui-assets). It really is just a collection of images that are available for various chains & nodes and makes no assumption about how you are including it in your app, or rather which packager you use.
+
+Up next is a critical component of any non-trivial app that also manages accounts, [@polkadot/ui-keyring](https://www.npmjs.com/package/@polkadot/ui-keyring). It is a browser-specific wrapper around the [@polkadot/keyring pcakge](https://www.npmjs.com/package/@polkadot/keyring) that transparently handles access to accounts, addresses, contracts and storage (saving accounts between use) all while allowing for swapable storage depending on your environment, be it browser, extension or Electron.
+
+[@polkadot/ui-settings](https://www.npmjs.com/package/@polkadot/ui-settings) provides a set of default settings, UI end network related, that could be useful to application developers in certain circumstances. The relates to settings such are ss58 formats, network endpoints and other.
+
+Last-up is the [@polkadot/ui-shared](https://www.npmjs.com/package/@polkadot/ui-shared) package. It is not deemed as generally useful to building apps, but rather contains shared code that is used within other packages, for instance in the generation of icons.
+
+## Diving in
+
+Now that we have some bearing of where we are, it is time to take a dive in, [let's start with the keyring and see what we can do](keyring.md).
@@ -38,8 +38,6 @@
    "@ledgerhq/hw-transport-node-hid": "^4.72.1"
  },
  "peerDependencies": {
-    "@polkadot/keyring": "*",
-    "@polkadot/types": "*",
-    "@polkadot/util": "*"
+    "@polkadot/keyring": "*"
  }
 }