@pezkuwi/ui-keyring 3.16.6

package/README.md

@@ -0,0 +1,136 @@
+# @pezkuwi/ui-keyring
+
+A wrapper extending the base @pezkuwi/keyring interface for usage in the browser:
+Key management of user accounts including generation and retrieval of keyring pairs from a variety of input combinations.
+
+## Usage Examples
+
+All module methods are exposed through a single default export.
+
+### Regular
+
+```js
+import keyring from @pezkuwi/ui-keyring
+
+render () {
+  // encode publicKey to ss58 address
+  const address = keyring.encodeAddress(publicKey);
+
+  // get keyring pair from ss58 address
+  const pair = keyring.getPair(address);
+
+  // ask questions about that particular keyring pair
+  const isLocked = pair.isLocked;
+  const meta = pair.meta;
+
+  // save account from pair
+  keyring.saveAccount(pair, password);
+
+  // save address without unlocking it
+  keyring.saveAddress(address, { ...meta });
+}
+```
+
+## Observables
+
+Option 1: Declarative subscribe/unsubscribe w/ react-with-observable (recommended 'React' way)
+
+```js
+import accountObservable from '@pezkuwi/ui-keyring/observable/accounts';
+import { SingleAddress, SubjectInfo } from '@pezkuwi/ui-keyring/observable/types';
+import React from 'react';
+import { Subscribe } from 'react-with-observable';
+import { map } from 'rxjs';
+
+class MyReactComponent extends React.PureComponent {
+  render () {
+    <Subscribe>
+      {accountObservable.subject.pipe(
+        map((allAccounts: SubjectInfo) =>
+          !allAccounts
+            ? this.renderEmpty()
+            : Object.values(allAccounts).map((account: SingleAddress) =>
+                // Your component goes here
+                console.log(account.json.address)
+            )
+        ))}
+    </Subscribe>
+  }
+
+  renderEmpty () {
+    return (
+      <div> no accounts to display ... </div>
+    );
+  }
+}
+
+```
+
+Option 2: Imperative subscribe/unsubscribe
+
+```js
+import accountObservable from '@pezkuwi/ui-keyring/observable/accounts';
+import { SingleAddress, SubjectInfo } from '@pezkuwi/ui-keyring/observable/types';
+import React from 'react';
+import { Subscription } from 'rxjs';
+
+type State = {
+  allAccounts?: SubjectInfo,
+  subscriptions?: [Subscription]
+}
+
+class MyReactComponent extends React.PureComponent<State> {
+  componentDidMount () {
+    const accountSubscription = accountObservable.subject.subscribe((observedAccounts) => {
+      this.setState({
+        accounts: observedAccounts
+      });
+    })
+
+    this.setState({
+      subscriptions: [accountSubscription]
+    });
+  }
+
+  componentWillUnmount () {
+    const { subscriptions } = this.state;
+
+    for (s in subscriptions) {
+      s.subject.unsubscribe();
+    }
+  }
+
+  render () {
+    const { accounts } = this.state;
+
+    return (
+      <h1>All Accounts</h1>
+      {
+        Object.keys(accounts).map((address: SingleAddress) => {
+          return <p> {address} </p>;
+        })
+      }
+    )
+  }
+}
+```
+
+## FAQ
+
+- Difference between Keyring Accounts and Addresses?
+  - From the perspective of the keyring, it saves a particular user's unlocked identities as an account, a la keyring.saveAccount(pair, password). So with these accounts you are able to send and sign transactions.
+  - To save addresses without unlocking them (i.e. because a user might want to have easy access to addresses they frequently transact with), use keyring.saveAddress(address, meta)
+- What are 'external' accounts, i.e. when to set the `isExternal` meta key to true?
+  - An external account is one where the keys are not managed by keyring, e.g. in Parity Signer or Ledger Nano.
+- SS58 Encode / Decode?
+  -  SS58 is a simple address format designed for Substrate based chains. You can read about its specification in more detail in the [Substrate Documentation](https://docs.substrate.io/reference/address-formats/).
+
+**If you have any unanswered/undocumented questions, please raise an issue [here](https://github.com/pezkuwichain/ui/issues).**
+
+
+## Users
+
+Keyring is core to many polkadot/substrate apps.
+
+* [pezkuwichain/apps](https://github.com/pezkuwichain/apps)
+* [paritytech/substrate-light-ui](https://github.com/paritytech/substrate-light-ui)

package/build/Base.d.ts

@@ -0,0 +1,30 @@
+import type { KeyringInstance, KeyringPair } from '@pezkuwi/keyring/types';
+import type { HexString } from '@pezkuwi/util/types';
+import type { Prefix } from '@pezkuwi/util-crypto/address/types';
+import type { AddressSubject } from './observable/types.js';
+import type { KeyringOptions, KeyringStore } from './types.js';
+export declare class Base {
+    #private;
+    protected _store: KeyringStore;
+    protected _genesisHash?: HexString | undefined;
+    protected _genesisHashAdd: HexString[];
+    constructor();
+    get accounts(): AddressSubject;
+    get addresses(): AddressSubject;
+    get contracts(): AddressSubject;
+    get isEthereum(): boolean;
+    get keyring(): KeyringInstance;
+    get genesisHash(): HexString | undefined;
+    get genesisHashes(): HexString[];
+    decodeAddress: (key: string | Uint8Array, ignoreChecksum?: boolean, ss58Format?: Prefix) => Uint8Array;
+    encodeAddress: (key: string | Uint8Array, ss58Format?: Prefix) => string;
+    getPair(address: string | Uint8Array): KeyringPair;
+    getPairs(): KeyringPair[];
+    isAvailable(_address: Uint8Array | string): boolean;
+    isPassValid(password: string): boolean;
+    setSS58Format(ss58Format?: Prefix): void;
+    setDevMode(isDevelopment: boolean): void;
+    protected initKeyring(options: KeyringOptions): void;
+    protected addAccountPairs(): void;
+    protected addTimestamp(pair: KeyringPair): void;
+}

package/build/Base.js

@@ -0,0 +1,109 @@
+import { createTestKeyring } from '@pezkuwi/keyring';
+import { isBoolean, isNumber, isString } from '@pezkuwi/util';
+import { accounts } from './observable/accounts.js';
+import { addresses } from './observable/addresses.js';
+import { contracts } from './observable/contracts.js';
+import { env } from './observable/env.js';
+import { BrowserStore } from './stores/Browser.js'; // direct import (skip index with all)
+export class Base {
+    #accounts;
+    #addresses;
+    #contracts;
+    #isEthereum;
+    #keyring;
+    _store;
+    _genesisHash;
+    _genesisHashAdd = [];
+    constructor() {
+        this.#accounts = accounts;
+        this.#addresses = addresses;
+        this.#contracts = contracts;
+        this.#isEthereum = false;
+        this._store = new BrowserStore();
+    }
+    get accounts() {
+        return this.#accounts;
+    }
+    get addresses() {
+        return this.#addresses;
+    }
+    get contracts() {
+        return this.#contracts;
+    }
+    get isEthereum() {
+        return this.#isEthereum;
+    }
+    get keyring() {
+        if (this.#keyring) {
+            return this.#keyring;
+        }
+        throw new Error('Keyring should be initialised via \'loadAll\' before use');
+    }
+    get genesisHash() {
+        return this._genesisHash;
+    }
+    get genesisHashes() {
+        return this._genesisHash
+            ? [this._genesisHash, ...this._genesisHashAdd]
+            : [...this._genesisHashAdd];
+    }
+    decodeAddress = (key, ignoreChecksum, ss58Format) => {
+        return this.keyring.decodeAddress(key, ignoreChecksum, ss58Format);
+    };
+    encodeAddress = (key, ss58Format) => {
+        return this.keyring.encodeAddress(key, ss58Format);
+    };
+    getPair(address) {
+        return this.keyring.getPair(address);
+    }
+    getPairs() {
+        return this.keyring.getPairs().filter((pair) => env.isDevelopment() || pair.meta.isTesting !== true);
+    }
+    isAvailable(_address) {
+        const accountsValue = this.accounts.subject.getValue();
+        const addressesValue = this.addresses.subject.getValue();
+        const contractsValue = this.contracts.subject.getValue();
+        const address = isString(_address)
+            ? _address
+            : this.encodeAddress(_address);
+        return !accountsValue[address] && !addressesValue[address] && !contractsValue[address];
+    }
+    isPassValid(password) {
+        return password.length > 0;
+    }
+    setSS58Format(ss58Format) {
+        if (this.#keyring && isNumber(ss58Format)) {
+            this.#keyring.setSS58Format(ss58Format);
+        }
+    }
+    setDevMode(isDevelopment) {
+        env.set(isDevelopment);
+    }
+    initKeyring(options) {
+        const keyring = createTestKeyring(options, true);
+        if (isBoolean(options.isDevelopment)) {
+            this.setDevMode(options.isDevelopment);
+        }
+        // set Ethereum state
+        this.#isEthereum = keyring.type === 'ethereum';
+        this.#keyring = keyring;
+        this._genesisHash = options.genesisHash && (isString(options.genesisHash)
+            ? options.genesisHash.toString()
+            : options.genesisHash.toHex());
+        this._genesisHashAdd = options.genesisHashAdd || [];
+        this._store = options.store || this._store;
+        this.addAccountPairs();
+    }
+    addAccountPairs() {
+        this.keyring
+            .getPairs()
+            .forEach(({ address, meta }) => {
+            this.accounts.add(this._store, address, { address, meta });
+        });
+    }
+    addTimestamp(pair) {
+        if (!pair.meta.whenCreated) {
+            pair.setMeta({ whenCreated: Date.now() });
+        }
+    }
+}

package/build/Keyring.d.ts

@@ -0,0 +1,49 @@
+import type { KeyringPair, KeyringPair$Json, KeyringPair$Meta } from '@pezkuwi/keyring/types';
+import type { BN } from '@pezkuwi/util';
+import type { EncryptedJson } from '@pezkuwi/util-crypto/json/types';
+import type { KeypairType } from '@pezkuwi/util-crypto/types';
+import type { SingleAddress } from './observable/types.js';
+import type { CreateResult, KeyringAddress, KeyringAddressType, KeyringItemType, KeyringJson$Meta, KeyringOptions, KeyringPairs$Json, KeyringStruct } from './types.js';
+import { KeyringOption } from './options/index.js';
+import { Base } from './Base.js';
+export declare class Keyring extends Base implements KeyringStruct {
+    #private;
+    readonly keyringOption: KeyringOption;
+    addExternal(address: string | Uint8Array, meta?: KeyringPair$Meta): CreateResult;
+    addHardware(address: string | Uint8Array, hardwareType: string, meta?: KeyringPair$Meta): CreateResult;
+    addMultisig(addresses: (string | Uint8Array)[], threshold: bigint | BN | number, meta?: KeyringPair$Meta): CreateResult;
+    addPair(pair: KeyringPair, password: string): CreateResult;
+    addUri(suri: string, password?: string, meta?: KeyringPair$Meta, type?: KeypairType): CreateResult;
+    backupAccount(pair: KeyringPair, password: string): KeyringPair$Json;
+    backupAccounts(addresses: string[], password: string): Promise<KeyringPairs$Json>;
+    createFromJson(json: KeyringPair$Json, meta?: KeyringPair$Meta): KeyringPair;
+    createFromUri(suri: string, meta?: KeyringPair$Meta, type?: KeypairType): KeyringPair;
+    encryptAccount(pair: KeyringPair, password: string): void;
+    forgetAccount(address: string): void;
+    forgetAddress(address: string): void;
+    forgetContract(address: string): void;
+    getAccount(address: string | Uint8Array): KeyringAddress | undefined;
+    getAccounts(): KeyringAddress[];
+    getAddress(_address: string | Uint8Array, type?: KeyringItemType | null): KeyringAddress | undefined;
+    getAddresses(): KeyringAddress[];
+    getContract(address: string | Uint8Array): KeyringAddress | undefined;
+    getContracts(): KeyringAddress[];
+    private rewriteKey;
+    private loadAccount;
+    private loadAddress;
+    private loadContract;
+    private loadInjected;
+    private allowGenesis;
+    loadAll(options: KeyringOptions, injected?: {
+        address: string;
+        meta: KeyringJson$Meta;
+        type?: KeypairType;
+    }[]): void;
+    restoreAccount(json: KeyringPair$Json, password: string): KeyringPair;
+    restoreAccounts(json: EncryptedJson, password: string): void;
+    saveAccount(pair: KeyringPair, password?: string): KeyringPair$Json;
+    saveAccountMeta(pair: KeyringPair, meta: KeyringPair$Meta): void;
+    saveAddress(address: string, meta: KeyringPair$Meta, type?: KeyringAddressType): KeyringPair$Json;
+    saveContract(address: string, meta: KeyringPair$Meta): KeyringPair$Json;
+    saveRecent(address: string): SingleAddress;
+}

package/build/Keyring.js

@@ -0,0 +1,304 @@
+import { createPair } from '@pezkuwi/keyring';
+import { chains } from '@pezkuwi/ui-settings';
+import { bnToBn, hexToU8a, isFunction, isHex, isString, objectSpread, stringify, stringToU8a, u8aSorted, u8aToString } from '@pezkuwi/util';
+import { base64Decode, createKeyMulti, jsonDecrypt, jsonEncrypt } from '@pezkuwi/util-crypto';
+import { env } from './observable/env.js';
+import { KeyringOption } from './options/index.js';
+import { Base } from './Base.js';
+import { accountKey, accountRegex, addressKey, addressRegex, contractKey, contractRegex } from './defaults.js';
+const RECENT_EXPIRY = 24 * 60 * 60;
+export class Keyring extends Base {
+    keyringOption = new KeyringOption();
+    #stores = {
+        account: () => this.accounts,
+        address: () => this.addresses,
+        contract: () => this.contracts
+    };
+    addExternal(address, meta = {}) {
+        const pair = this.keyring.addFromAddress(address, objectSpread({}, meta, { isExternal: true }), null, meta?.type);
+        return {
+            json: this.saveAccount(pair),
+            pair
+        };
+    }
+    addHardware(address, hardwareType, meta = {}) {
+        return this.addExternal(address, objectSpread({}, meta, { hardwareType, isHardware: true }));
+    }
+    addMultisig(addresses, threshold, meta = {}) {
+        let address = createKeyMulti(addresses, threshold);
+        // For Ethereum chains, the first 20 bytes of the hash indicates the actual address
+        // Testcases via creation and on-chain events:
+        // -  input: 0x7a1671a0224c8927b08f978027d586ab6868de0d31bb5bc956b625ced2ab18c4
+        // - output: 0x7a1671a0224c8927b08f978027d586ab6868de0d
+        if (this.isEthereum) {
+            address = address.slice(0, 20);
+        }
+        // we could use `sortAddresses`, but rather use internal encode/decode so we are 100%
+        const who = u8aSorted(addresses.map((who) => this.decodeAddress(who))).map((who) => this.encodeAddress(who));
+        return this.addExternal(address, objectSpread({}, meta, { isMultisig: true, threshold: bnToBn(threshold).toNumber(), who }));
+    }
+    addPair(pair, password) {
+        this.keyring.addPair(pair);
+        return {
+            json: this.saveAccount(pair, password),
+            pair
+        };
+    }
+    addUri(suri, password, meta = {}, type) {
+        const pair = this.keyring.addFromUri(suri, meta, type);
+        return {
+            json: this.saveAccount(pair, password),
+            pair
+        };
+    }
+    backupAccount(pair, password) {
+        if (!pair.isLocked) {
+            pair.lock();
+        }
+        pair.decodePkcs8(password);
+        return pair.toJson(password);
+    }
+    async backupAccounts(addresses, password) {
+        const accountPromises = addresses.map((address) => {
+            return new Promise((resolve) => {
+                this._store.get(accountKey(address), resolve);
+            });
+        });
+        const accounts = await Promise.all(accountPromises);
+        return objectSpread({}, jsonEncrypt(stringToU8a(JSON.stringify(accounts)), ['batch-pkcs8'], password), {
+            accounts: accounts.map((account) => ({
+                address: account.address,
+                meta: account.meta
+            }))
+        });
+    }
+    createFromJson(json, meta = {}) {
+        return this.keyring.createFromJson(objectSpread({}, json, {
+            meta: objectSpread({}, json.meta, meta)
+        }));
+    }
+    createFromUri(suri, meta = {}, type) {
+        return this.keyring.createFromUri(suri, meta, type);
+    }
+    encryptAccount(pair, password) {
+        const json = pair.toJson(password);
+        json.meta.whenEdited = Date.now();
+        this.keyring.addFromJson(json);
+        this.accounts.add(this._store, pair.address, json, pair.type);
+    }
+    forgetAccount(address) {
+        this.keyring.removePair(address);
+        this.accounts.remove(this._store, address);
+    }
+    forgetAddress(address) {
+        this.addresses.remove(this._store, address);
+    }
+    forgetContract(address) {
+        this.contracts.remove(this._store, address);
+    }
+    getAccount(address) {
+        return this.getAddress(address, 'account');
+    }
+    getAccounts() {
+        const available = this.accounts.subject.getValue();
+        return Object
+            .keys(available)
+            .map((address) => this.getAddress(address, 'account'))
+            .filter((account) => !!account &&
+            (env.isDevelopment() ||
+                account.meta.isTesting !== true));
+    }
+    getAddress(_address, type = null) {
+        const address = isString(_address)
+            ? _address
+            : this.encodeAddress(_address);
+        const publicKey = this.decodeAddress(address);
+        const stores = type
+            ? [this.#stores[type]]
+            : Object.values(this.#stores);
+        const info = stores.reduce((lastInfo, store) => (store().subject.getValue()[address] || lastInfo), undefined);
+        return info && {
+            address,
+            meta: info.json.meta,
+            publicKey
+        };
+    }
+    getAddresses() {
+        const available = this.addresses.subject.getValue();
+        return Object
+            .keys(available)
+            .map((address) => this.getAddress(address))
+            .filter((account) => !!account);
+    }
+    getContract(address) {
+        return this.getAddress(address, 'contract');
+    }
+    getContracts() {
+        const available = this.contracts.subject.getValue();
+        return Object
+            .entries(available)
+            .filter(([, { json: { meta: { contract } } }]) => !!contract && contract.genesisHash === this.genesisHash)
+            .map(([address]) => this.getContract(address))
+            .filter((account) => !!account);
+    }
+    rewriteKey(json, key, hexAddr, creator) {
+        if (hexAddr.startsWith('0x')) {
+            return;
+        }
+        this._store.remove(key);
+        this._store.set(creator(hexAddr), json);
+    }
+    loadAccount(json, key) {
+        if (!json.meta.isTesting && json.encoded) {
+            const pair = this.keyring.addFromJson(json, true);
+            this.accounts.add(this._store, pair.address, json, pair.type);
+        }
+        const [, hexAddr] = key.split(':');
+        this.rewriteKey(json, key, hexAddr.trim(), accountKey);
+    }
+    loadAddress(json, key) {
+        const { isRecent, whenCreated = 0 } = json.meta;
+        if (isRecent && (Date.now() - whenCreated) > RECENT_EXPIRY) {
+            this._store.remove(key);
+            return;
+        }
+        // We assume anything hex that is not 32bytes (64 + 2 bytes hex) is an Ethereum-like address
+        // (this caters for both H160 addresses as well as full or compressed publicKeys) - in the case
+        // of both ecdsa and ethereum, we keep it as-is
+        const address = isHex(json.address) && json.address.length !== 66
+            ? json.address
+            : this.encodeAddress(isHex(json.address)
+                ? hexToU8a(json.address)
+                // FIXME Just for the transition period (ignoreChecksum)
+                : this.decodeAddress(json.address, true));
+        const [, hexAddr] = key.split(':');
+        this.addresses.add(this._store, address, json);
+        this.rewriteKey(json, key, hexAddr, addressKey);
+    }
+    loadContract(json, key) {
+        const address = this.encodeAddress(this.decodeAddress(json.address));
+        const [, hexAddr] = key.split(':');
+        // move genesisHash to top-level (TODO Remove from contracts section?)
+        json.meta.genesisHash = json.meta.genesisHash || (json.meta.contract?.genesisHash);
+        this.contracts.add(this._store, address, json);
+        this.rewriteKey(json, key, hexAddr, contractKey);
+    }
+    loadInjected(address, meta, type) {
+        const json = {
+            address,
+            meta: objectSpread({}, meta, { isInjected: true })
+        };
+        const pair = this.keyring.addFromAddress(address, json.meta, null, type);
+        this.accounts.add(this._store, pair.address, json, pair.type);
+    }
+    allowGenesis(json) {
+        if (json?.meta && this.genesisHash) {
+            const hashes = Object.values(chains).find((hashes) => hashes.includes(this.genesisHash || '')) || [this.genesisHash];
+            if (json.meta.genesisHash) {
+                return hashes.includes(json.meta.genesisHash) || this.genesisHashes.includes(json.meta.genesisHash);
+            }
+            else if (json.meta.contract) {
+                return hashes.includes(json.meta.contract.genesisHash);
+            }
+        }
+        return true;
+    }
+    loadAll(options, injected = []) {
+        super.initKeyring(options);
+        this._store.all((key, json) => {
+            if (!isFunction(options.filter) || options.filter(json)) {
+                try {
+                    if (this.allowGenesis(json)) {
+                        if (accountRegex.test(key)) {
+                            this.loadAccount(json, key);
+                        }
+                        else if (addressRegex.test(key)) {
+                            this.loadAddress(json, key);
+                        }
+                        else if (contractRegex.test(key)) {
+                            this.loadContract(json, key);
+                        }
+                    }
+                }
+                catch {
+                    console.warn(`Keyring: Unable to load ${key}:${stringify(json)}`);
+                }
+            }
+        });
+        injected.forEach((account) => {
+            if (this.allowGenesis(account)) {
+                try {
+                    this.loadInjected(account.address, account.meta, account.type);
+                }
+                catch {
+                    console.warn(`Keyring: Unable to inject ${stringify(account)}`);
+                }
+            }
+        });
+        this.keyringOption.init(this);
+    }
+    restoreAccount(json, password) {
+        const cryptoType = Array.isArray(json.encoding.content) ? json.encoding.content[1] : 'ed25519';
+        const encType = Array.isArray(json.encoding.type) ? json.encoding.type : [json.encoding.type];
+        const pair = createPair({ toSS58: this.encodeAddress, type: cryptoType }, { publicKey: this.decodeAddress(json.address, true) }, json.meta, isHex(json.encoded) ? hexToU8a(json.encoded) : base64Decode(json.encoded), encType);
+        // unlock, save account and then lock (locking cleans secretKey, so needs to be last)
+        pair.decodePkcs8(password);
+        this.addPair(pair, password);
+        pair.lock();
+        return pair;
+    }
+    restoreAccounts(json, password) {
+        const accounts = JSON.parse(u8aToString(jsonDecrypt(json, password)));
+        accounts.forEach((account) => {
+            this.loadAccount(account, accountKey(account.address));
+        });
+    }
+    saveAccount(pair, password) {
+        this.addTimestamp(pair);
+        const json = pair.toJson(password);
+        this.keyring.addFromJson(json);
+        this.accounts.add(this._store, pair.address, json, pair.type);
+        return json;
+    }
+    saveAccountMeta(pair, meta) {
+        const address = pair.address;
+        this._store.get(accountKey(address), (json) => {
+            pair.setMeta(meta);
+            json.meta = pair.meta;
+            this.accounts.add(this._store, address, json, pair.type);
+        });
+    }
+    saveAddress(address, meta, type = 'address') {
+        const available = this.addresses.subject.getValue();
+        const json = available[address]?.json || {
+            address,
+            meta: {
+                isRecent: undefined,
+                whenCreated: Date.now()
+            }
+        };
+        Object.keys(meta).forEach((key) => {
+            json.meta[key] = meta[key];
+        });
+        delete json.meta.isRecent;
+        this.#stores[type]().add(this._store, address, json);
+        return json;
+    }
+    saveContract(address, meta) {
+        return this.saveAddress(address, meta, 'contract');
+    }
+    saveRecent(address) {
+        const available = this.addresses.subject.getValue();
+        if (!available[address]) {
+            this.addresses.add(this._store, address, {
+                address,
+                meta: {
+                    genesisHash: this.genesisHash,
+                    isRecent: true,
+                    whenCreated: Date.now()
+                }
+            });
+        }
+        return this.addresses.subject.getValue()[address];
+    }
+}