* add new type in api - settings in order to support different types of 'urls' - json-rpc and substrate-connect; This makes the previous used apiURL deprecated
* Alter name from apiTypeUrl to apiType
* export types of possible endpoints
* minor fix on sequence of vars
* Fix lint error concerning imports
* Fix lint error concerning imports
* Fix PR comments: import types instead of import; seperate types from settings
* fix lint error
* Update packages/ui-settings/src/types.ts
Co-authored-by: Jaco <jacogr@gmail.com>
Co-authored-by: Jaco <jacogr@gmail.com>
@@ -30,5 +30,4 @@ Additionally some shared libraries, that is not dependent on any framework -
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`
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)
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).
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`
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)
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 -
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
constseed=randomAsHex(32);
// add the account, encrypting it, override to 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).
[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` -
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).
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 -
// 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 -
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';
importkeyringfrom'@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.
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 -
// 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 -
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
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 -
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
constpair=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
// 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).
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).
For iOS, make sure that Xcode and [CocoaPods](https://cocoapods.org/) are installed.
For Android, make sure that Android Studio and a JDK are installed.
At the repo root, run the bundler `yarn example:rn:packager` and, in a new terminal, `yarn example:rn:ios` or `yarn example:rn:android`.
If the iOS run complains about a missing simulator, use `yarn ios --simulator="iPhone 11"`, where `iPhone 11` is replaced with an installed simulator (see `xcrun simctl list devices`)
The first time metro bundles the package, it will hang at 98% and take about 10 minutes to finish. Just refresh the simulator when it finishes.
# Packages
Native packages need to be added to `nohoist` in the `package.json`. There is no need to link them, but `cd ios && pod install` must be run after yarn adds the package.
Non-native packages can be yarn added as usual.
Replacements for node builtin packages can be added in the `extraNodeModules` section of `metro.config.js`. Some node packages will expect global variables to be set, these are set in `nodeGlobalsShim.js`
# Yarn Workspaces
Metro will watch the build dirs of the packages in `packages/*` for changes, as well as use the `node_modules` of the root folder. However, packages that depend on the `nohoist`ed `react-native` , such as `reactnative-identicon`, must be copied to the local `node_modules` folder. See `metro.config.js` and `package.json`'s scripts for details.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.