pezkuwichain/pezkuwi-ui
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-ui.git synced 2026-04-22 05:37:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Bump dev (#377)

Browse Source
This commit is contained in:
Jaco Greeff
2020-10-07 14:15:34 +02:00
committed by GitHub
parent 33ef29361f
commit 35dd0b2561
19 changed files with 694 additions and 7098 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.nojekyll
View File
docs/.vuepress/config.js
-50
View File
@@ -1,50 +0,0 @@
module.exports = {
base: '/ui/',
title: 'polkadot-js/ui',
description: 'UI utilities, libraries and React components in use across @polkadot projects',
markdown: {
lineNumbers: true
},
themeConfig: {
displayAllHeaders: true,
nav: [
{ text: 'Polkadot/Substrate Apps', link: 'https://polkadot.js.org/apps/' },
{ text: 'Project family', link: 'https://polkadot.js.org/' },
{
text: 'Documentation',
items: [
{ text: 'API Reference', link: 'https://polkadot.js.org/api/' },
{ text: 'Utility Reference', link: 'https://polkadot.js.org/common/' },
{ text: 'UI Libs Reference (this)', link: 'https://polkadot.js.org/ui/' },
]
},
{ text: 'GitHub', link: 'https://github.com/polkadot-js/ui' }
],
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'],
['/ui-keyring/', '@polkadot/ui-keyring'],
['/ui-settings/', '@polkadot/ui-settings'],
['/ui-shared/', '@polkadot/ui-shared'],
['/vue-identicon/', '@polkadot/vue-identicon'],
'/CONTRIBUTING.md'
]
}
};
docs/.vuepress/styles/palette.styl
-9
View File
@@ -1,9 +0,0 @@
$accentColor = #fd8824
$textColor = #2c3e50
.home .hero .description,
.home .feature h2,
.home .feature p {
color: $textColor
opacity: 0.75
}
docs/README.md
-52
View File
@@ -1,52 +0,0 @@
---
home: true
heroText:
tagline:
# Bringing JavaScript to the Polkadot world.
# 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.
footer: Apache-2 Licensed | Copyright © 2017-2019 polkadot-js authors and contributors
---
## Welcome
This is a collection of UI libraries, utilities and classes that allows for easier use of the Polkadot JS infrastructure inside your apps.
::: 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 -
- 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
## The Polkadot Project
You can read more about the Polkadot Network at [https://polkadot.network/](https://polkadot.network/) and more about the polkadot-js projects at [https://polkadot.js.org](https://polkadot.js.org)
## Github repositories
You can find the Polkadot repositories at:
- [https://github.com/polkadot-js](https://github.com/polkadot-js)
- [https://github.com/paritytech/polkadot](https://github.com/paritytech/polkadot)
- [https://github.com/paritytech/substrate](https://github.com/paritytech/substrate)
This documentation is generated from [https://github.com/polkadot-js/ui](https://github.com/polkadot-js/ui)
## Contributing
Contribution to the Polkadot JS projects are more than welcome. You can [report issues](https://github.com/polkadot-js/ui/issues/new) and [log feature requests](https://github.com/polkadot-js/ui/issues/new).
docs/start/FAQ.md
-11
View File
@@ -1,11 +0,0 @@
# 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`
docs/start/README.md
-15
View File
@@ -1,15 +0,0 @@
# 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)
docs/start/keyring.accounts.md
-49
View File
@@ -1,49 +0,0 @@
# 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).
docs/start/keyring.derivation.md
-29
View File
@@ -1,29 +0,0 @@
# 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).
docs/start/keyring.md
-104
View File
@@ -1,104 +0,0 @@
# 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).
docs/start/keyring.other.md
-41
View File
@@ -1,41 +0,0 @@
# 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(...)
```
docs/start/keyring.retrieve.md
-57
View File
@@ -1,57 +0,0 @@
# 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).
docs/start/packages.md
-35
View File
@@ -1,35 +0,0 @@
# 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 (such 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).