@pezkuwi/keyring 14.0.22 → 14.0.23

package/build-deno/bundle.ts

@@ -0,0 +1,10 @@
+
+export { decodeAddress, encodeAddress, setSS58Format } from 'https://deno.land/x/pezkuwi/util-crypto/mod.ts';
+
+export { Keyring } from './keyring.ts';
+export { packageInfo } from './packageInfo.ts';
+export { createPair } from './pair/index.ts';
+export { createTestKeyring } from './testing.ts';
+export { createTestPairs } from './testingPairs.ts';
+
+export * from './defaults.ts';

package/build-deno/defaults.ts

@@ -0,0 +1,4 @@
+
+export const DEV_PHRASE = 'bottom drive obey lake curtain smoke basket hold race lonely fit walk';
+
+export const DEV_SEED = '0xfac7959dbfe72f052e5a0c3c8d6530f202b02fd8f9f5ca3580ec8deb7797479e';

package/build-deno/index.ts

@@ -0,0 +1,8 @@
+
+import './packageDetect.ts';
+
+import { Keyring } from './bundle.ts';
+
+export * from './bundle.ts';
+
+export default Keyring;

package/build-deno/keyring.ts

@@ -0,0 +1,305 @@
+
+import type { EncryptedJsonEncoding, Keypair, KeypairType } from 'https://deno.land/x/pezkuwi/util-crypto/types.ts';
+import type { KeyringInstance, KeyringOptions, KeyringPair, KeyringPair$Json, KeyringPair$Meta } from './types.ts';
+
+import { hexToU8a, isHex, stringToU8a } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+import { base64Decode, decodeAddress, ed25519PairFromSeed as ed25519FromSeed, encodeAddress, ethereumEncode, hdEthereum, keyExtractSuri, keyFromPath, mnemonicToLegacySeed, mnemonicToMiniSecret, secp256k1PairFromSeed as secp256k1FromSeed, sr25519PairFromSeed as sr25519FromSeed } from 'https://deno.land/x/pezkuwi/util-crypto/mod.ts';
+
+import { createPair } from './pair/index.ts';
+import { DEV_PHRASE } from './defaults.ts';
+import { Pairs } from './pairs.ts';
+
+const PairFromSeed = {
+  ecdsa: (seed: Uint8Array): Keypair => secp256k1FromSeed(seed),
+  ed25519: (seed: Uint8Array): Keypair => ed25519FromSeed(seed),
+  ethereum: (seed: Uint8Array): Keypair => secp256k1FromSeed(seed),
+  sr25519: (seed: Uint8Array): Keypair => sr25519FromSeed(seed)
+};
+
+function pairToPublic ({ publicKey }: KeyringPair): Uint8Array {
+  return publicKey;
+}
+
+/**
+ * # @pezkuwi/keyring
+ *
+ * ## Overview
+ *
+ * @name Keyring
+ * @summary Keyring management of user accounts
+ * @description Allows generation of keyring pairs from a variety of input combinations, such as
+ * json object containing account address or public key, account metadata, and account encoded using
+ * `addFromJson`, or by providing those values as arguments separately to `addFromAddress`,
+ * or by providing the mnemonic (seed phrase) and account metadata as arguments to `addFromMnemonic`.
+ * Stores the keyring pairs in a keyring pair dictionary. Removal of the keyring pairs from the keyring pair
+ * dictionary is achieved using `removePair`. Retrieval of all the stored pairs via `getPairs` or perform
+ * lookup of a pair for a given account address or public key using `getPair`. JSON metadata associated with
+ * an account may be obtained using `toJson` accompanied by the account passphrase.
+ */
+export class Keyring implements KeyringInstance {
+  readonly #pairs: Pairs;
+
+  readonly #type: KeypairType;
+
+  #ss58?: number | undefined;
+
+  public decodeAddress = decodeAddress;
+
+  constructor (options: KeyringOptions = {}) {
+    options.type = options.type || 'ed25519';
+
+    if (!['ecdsa', 'ethereum', 'ed25519', 'sr25519'].includes(options.type || 'undefined')) {
+      throw new Error(`Expected a keyring type of either 'ed25519', 'sr25519', 'ethereum' or 'ecdsa', found '${options.type || 'unknown'}`);
+    }
+
+    this.#pairs = new Pairs();
+    this.#ss58 = options.ss58Format;
+    this.#type = options.type;
+  }
+
+  /**
+   * @description retrieve the pairs (alias for getPairs)
+   */
+  public get pairs (): KeyringPair[] {
+    return this.getPairs();
+  }
+
+  /**
+   * @description retrieve the publicKeys (alias for getPublicKeys)
+   */
+  public get publicKeys (): Uint8Array[] {
+    return this.getPublicKeys();
+  }
+
+  /**
+   * @description Returns the type of the keyring, ed25519, sr25519 or ecdsa
+   */
+  public get type (): KeypairType {
+    return this.#type;
+  }
+
+  /**
+   * @name addPair
+   * @summary Stores an account, given a keyring pair, as a Key/Value (public key, pair) in Keyring Pair Dictionary
+   */
+  public addPair (pair: KeyringPair): KeyringPair {
+    return this.#pairs.add(pair);
+  }
+
+  /**
+   * @name addFromAddress
+   * @summary Stores an account, given an account address, as a Key/Value (public key, pair) in Keyring Pair Dictionary
+   * @description Allows user to explicitly provide separate inputs including account address or public key, and optionally
+   * the associated account metadata, and the default encoded value as arguments (that may be obtained from the json file
+   * of an account backup), and then generates a keyring pair from them that it passes to
+   * `addPair` to stores in a keyring pair dictionary the public key of the generated pair as a key and the pair as the associated value.
+   */
+  public addFromAddress (address: string | Uint8Array, meta: KeyringPair$Meta = {}, encoded: Uint8Array | null = null, type: KeypairType = this.type, ignoreChecksum?: boolean, encType?: EncryptedJsonEncoding[]): KeyringPair {
+    const publicKey = this.decodeAddress(address, ignoreChecksum);
+
+    return this.addPair(createPair({ toSS58: this.encodeAddress, type }, { publicKey, secretKey: new Uint8Array() }, meta, encoded, encType));
+  }
+
+  /**
+   * @name addFromJson
+   * @summary Stores an account, given JSON data, as a Key/Value (public key, pair) in Keyring Pair Dictionary
+   * @description Allows user to provide a json object argument that contains account information (that may be obtained from the json file
+   * of an account backup), and then generates a keyring pair from it that it passes to
+   * `addPair` to stores in a keyring pair dictionary the public key of the generated pair as a key and the pair as the associated value.
+   */
+  public addFromJson (json: KeyringPair$Json, ignoreChecksum?: boolean): KeyringPair {
+    return this.addPair(this.createFromJson(json, ignoreChecksum));
+  }
+
+  /**
+   * @name addFromMnemonic
+   * @summary Stores an account, given a mnemonic, as a Key/Value (public key, pair) in Keyring Pair Dictionary
+   * @description Allows user to provide a mnemonic (seed phrase that is provided when account is originally created)
+   * argument and a metadata argument that contains account information (that may be obtained from the json file
+   * of an account backup), and then generates a keyring pair from it that it passes to
+   * `addPair` to stores in a keyring pair dictionary the public key of the generated pair as a key and the pair as the associated value.
+   */
+  public addFromMnemonic (mnemonic: string, meta: KeyringPair$Meta = {}, type: KeypairType = this.type, wordlist?: string[]): KeyringPair {
+    return this.addFromUri(mnemonic, meta, type, wordlist);
+  }
+
+  /**
+   * @name addFromPair
+   * @summary Stores an account created from an explicit publicKey/secreteKey combination
+   */
+  public addFromPair (pair: Keypair, meta: KeyringPair$Meta = {}, type: KeypairType = this.type): KeyringPair {
+    return this.addPair(
+      this.createFromPair(pair, meta, type)
+    );
+  }
+
+  /**
+   * @name addFromSeed
+   * @summary Stores an account, given seed data, as a Key/Value (public key, pair) in Keyring Pair Dictionary
+   * @description Stores in a keyring pair dictionary the public key of the pair as a key and the pair as the associated value.
+   * Allows user to provide the account seed as an argument, and then generates a keyring pair from it that it passes to
+   * `addPair` to store in a keyring pair dictionary the public key of the generated pair as a key and the pair as the associated value.
+   */
+  public addFromSeed (seed: Uint8Array, meta: KeyringPair$Meta = {}, type: KeypairType = this.type): KeyringPair {
+    return this.addPair(
+      createPair({ toSS58: this.encodeAddress, type }, PairFromSeed[type](seed), meta, null)
+    );
+  }
+
+  /**
+   * @name addFromUri
+   * @summary Creates an account via an suri
+   * @description Extracts the phrase, path and password from a SURI format for specifying secret keys `<secret>/<soft-key>//<hard-key>///<password>` (the `///password` may be omitted, and `/<soft-key>` and `//<hard-key>` maybe repeated and mixed). The secret can be a hex string, mnemonic phrase or a string (to be padded)
+   */
+  public addFromUri (suri: string, meta: KeyringPair$Meta = {}, type: KeypairType = this.type, wordlist?: string[]): KeyringPair {
+    return this.addPair(
+      this.createFromUri(suri, meta, type, wordlist)
+    );
+  }
+
+  /**
+   * @name createFromJson
+   * @description Creates a pair from a JSON keyfile
+   */
+  public createFromJson ({ address, encoded, encoding: { content, type, version }, meta }: KeyringPair$Json, ignoreChecksum?: boolean): KeyringPair {
+    if (version === '3' && content[0] !== 'pkcs8') {
+      throw new Error(`Unable to decode non-pkcs8 type, [${content.join(',')}] found}`);
+    }
+
+    const cryptoType = version === '0' || !Array.isArray(content)
+      ? this.type
+      : content[1];
+    const encType = !Array.isArray(type)
+      ? [type]
+      : type;
+
+    if (!['ed25519', 'sr25519', 'ecdsa', 'ethereum'].includes(cryptoType)) {
+      throw new Error(`Unknown crypto type ${cryptoType}`);
+    }
+
+    // Here the address and publicKey are 32 bytes and isomorphic. This is why the address field needs to be the public key for ethereum type pairs
+    const publicKey = isHex(address)
+      ? hexToU8a(address)
+      : this.decodeAddress(address, ignoreChecksum);
+    const decoded = isHex(encoded)
+      ? hexToU8a(encoded)
+      : base64Decode(encoded);
+
+    return createPair({ toSS58: this.encodeAddress, type: cryptoType as KeypairType }, { publicKey, secretKey: new Uint8Array() }, meta, decoded, encType);
+  }
+
+  /**
+   * @name createFromPair
+   * @summary Creates a pair from an explicit publicKey/secreteKey combination
+   */
+  public createFromPair (pair: Keypair, meta: KeyringPair$Meta = {}, type: KeypairType = this.type): KeyringPair {
+    return createPair({ toSS58: this.encodeAddress, type }, pair, meta, null);
+  }
+
+  /**
+   * @name createFromUri
+   * @summary Creates a Keypair from an suri
+   * @description This creates a pair from the suri, but does not add it to the keyring
+   */
+  public createFromUri (_suri: string, meta: KeyringPair$Meta = {}, type: KeypairType = this.type, wordlist?: string[]): KeyringPair {
+    // here we only aut-add the dev phrase if we have a hard-derived path
+    const suri = _suri.startsWith('//')
+      ? `${DEV_PHRASE}${_suri}`
+      : _suri;
+    const { derivePath, password, path, phrase } = keyExtractSuri(suri);
+    let seed: Uint8Array;
+    const isPhraseHex = isHex(phrase, 256);
+
+    if (isPhraseHex) {
+      seed = hexToU8a(phrase);
+    } else {
+      const parts = phrase.split(' ');
+
+      if ([12, 15, 18, 21, 24].includes(parts.length)) {
+        seed = type === 'ethereum'
+          ? mnemonicToLegacySeed(phrase, '', false, 64)
+          : mnemonicToMiniSecret(phrase, password, wordlist);
+      } else {
+        if (phrase.length > 32) {
+          throw new Error('specified phrase is not a valid mnemonic and is invalid as a raw seed at > 32 bytes');
+        }
+
+        seed = stringToU8a(phrase.padEnd(32));
+      }
+    }
+
+    const derived = type === 'ethereum'
+      ? isPhraseHex
+        ? PairFromSeed[type](seed) // for eth, if the private key is provided as suri, it must be derived only once
+        : hdEthereum(seed, derivePath.substring(1))
+      : keyFromPath(PairFromSeed[type](seed), path, type);
+
+    return createPair({ toSS58: this.encodeAddress, type }, derived, meta, null);
+  }
+
+  /**
+   * @name encodeAddress
+   * @description Encodes the input into an ss58 representation
+   */
+  public encodeAddress = (address: Uint8Array | string, ss58Format?: number): string => {
+    return this.type === 'ethereum'
+      ? ethereumEncode(address)
+      : encodeAddress(address, ss58Format ?? this.#ss58);
+  };
+
+  /**
+   * @name getPair
+   * @summary Retrieves an account keyring pair from the Keyring Pair Dictionary, given an account address
+   * @description Returns a keyring pair value from the keyring pair dictionary by performing
+   * a key lookup using the provided account address or public key (after decoding it).
+   */
+  public getPair (address: string | Uint8Array): KeyringPair {
+    return this.#pairs.get(address);
+  }
+
+  /**
+   * @name getPairs
+   * @summary Retrieves all account keyring pairs from the Keyring Pair Dictionary
+   * @description Returns an array list of all the keyring pair values that are stored in the keyring pair dictionary.
+   */
+  public getPairs (): KeyringPair[] {
+    return this.#pairs.all();
+  }
+
+  /**
+   * @name getPublicKeys
+   * @summary Retrieves Public Keys of all Keyring Pairs stored in the Keyring Pair Dictionary
+   * @description Returns an array list of all the public keys associated with each of the keyring pair values that are stored in the keyring pair dictionary.
+   */
+  public getPublicKeys (): Uint8Array[] {
+    return this.#pairs.all().map(pairToPublic);
+  }
+
+  /**
+   * @name removePair
+   * @description Deletes the provided input address or public key from the stored Keyring Pair Dictionary.
+   */
+  public removePair (address: string | Uint8Array): void {
+    this.#pairs.remove(address);
+  }
+
+  /**
+   * @name setSS58Format;
+   * @description Sets the ss58 format for the keyring
+   */
+  public setSS58Format (ss58: number): void {
+    this.#ss58 = ss58;
+  }
+
+  /**
+   * @name toJson
+   * @summary Returns a JSON object associated with the input argument that contains metadata assocated with an account
+   * @description Returns a JSON object containing the metadata associated with an account
+   * when valid address or public key and when the account passphrase is provided if the account secret
+   * is not already unlocked and available in memory. Note that in [Polkadot-JS Apps](https://github.com/polkadot-js/apps) the user
+   * may backup their account to a JSON file that contains this information.
+   */
+  public toJson (address: string | Uint8Array, passphrase?: string): KeyringPair$Json {
+    return this.#pairs.get(address).toJson(passphrase);
+  }
+}

package/build-deno/mod.ts

@@ -0,0 +1,2 @@
+
+export * from './index.ts';

package/build-deno/packageDetect.ts

@@ -0,0 +1,9 @@
+
+
+import { detectPackage } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+import { packageInfo as utilInfo } from 'https://deno.land/x/pezkuwi/util/packageInfo.ts';
+import { packageInfo as cryptoInfo } from 'https://deno.land/x/pezkuwi/util-crypto/packageInfo.ts';
+
+import { packageInfo } from './packageInfo.ts';
+
+detectPackage(packageInfo, null, [cryptoInfo, utilInfo]);

package/build-deno/packageInfo.ts

@@ -0,0 +1,3 @@
+
+
+export const packageInfo = { name: '@pezkuwi/keyring', path: new URL(import.meta.url).pathname, type: 'deno', version: '14.0.23' };

package/build-deno/pair/decode.ts

@@ -0,0 +1,54 @@
+
+import type { EncryptedJsonEncoding } from 'https://deno.land/x/pezkuwi/util-crypto/types.ts';
+
+import { u8aEq } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+import { jsonDecryptData } from 'https://deno.land/x/pezkuwi/util-crypto/mod.ts';
+
+import { PAIR_DIV, PAIR_HDR, PUB_LENGTH, SEC_LENGTH, SEED_LENGTH } from './defaults.ts';
+
+const SEED_OFFSET = PAIR_HDR.length;
+
+/**
+ * Decode a pair, taking into account the generation-specific formats and headers
+ *
+ * For divisor/headers, don't rely on the magic being static. These will
+ * change between generations, aka with the long-awaited 4th generation
+ * of the format. The external decode interface is the only way to use and decode these.
+ **/
+export function decodePair (passphrase?: string, encrypted?: Uint8Array | null, _encType?: EncryptedJsonEncoding | EncryptedJsonEncoding[]): { publicKey: Uint8Array; secretKey: Uint8Array } {
+  const encType = Array.isArray(_encType) || _encType === undefined
+    ? _encType
+    : [_encType];
+  const decrypted = jsonDecryptData(encrypted, passphrase, encType);
+  const header = decrypted.subarray(0, PAIR_HDR.length);
+
+  // check the start header (generations 1-3)
+  if (!u8aEq(header, PAIR_HDR)) {
+    throw new Error('Invalid encoding header found in body');
+  }
+
+  // setup for generation 3 format
+  let secretKey = decrypted.subarray(SEED_OFFSET, SEED_OFFSET + SEC_LENGTH);
+  let divOffset = SEED_OFFSET + SEC_LENGTH;
+  let divider = decrypted.subarray(divOffset, divOffset + PAIR_DIV.length);
+
+  // old-style (generation 1 & 2), we have the seed here
+  if (!u8aEq(divider, PAIR_DIV)) {
+    divOffset = SEED_OFFSET + SEED_LENGTH;
+    secretKey = decrypted.subarray(SEED_OFFSET, divOffset);
+    divider = decrypted.subarray(divOffset, divOffset + PAIR_DIV.length);
+
+    // check the divisior at this point (already checked for generation 3)
+    if (!u8aEq(divider, PAIR_DIV)) {
+      throw new Error('Invalid encoding divider found in body');
+    }
+  }
+
+  const pubOffset = divOffset + PAIR_DIV.length;
+  const publicKey = decrypted.subarray(pubOffset, pubOffset + PUB_LENGTH);
+
+  return {
+    publicKey,
+    secretKey
+  };
+}

package/build-deno/pair/defaults.ts

@@ -0,0 +1,18 @@
+
+/** public/secret section divider (generation 1-3, will change in 4, don't rely on value) */
+export const PAIR_DIV = new Uint8Array([161, 35, 3, 33, 0]);
+
+/** public/secret start block (generation 1-3, will change in 4, don't rely on value) */
+export const PAIR_HDR = new Uint8Array([48, 83, 2, 1, 1, 48, 5, 6, 3, 43, 101, 112, 4, 34, 4, 32]);
+
+/** length of a public key */
+export const PUB_LENGTH = 32;
+
+/** length of a salt */
+export const SALT_LENGTH = 32;
+
+/** length of a secret key */
+export const SEC_LENGTH = 64;
+
+/** length of a user-input seed */
+export const SEED_LENGTH = 32;

package/build-deno/pair/encode.ts

@@ -0,0 +1,28 @@
+
+import type { PairInfo } from './types.ts';
+
+import { u8aConcat } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+import { naclEncrypt, scryptEncode, scryptToU8a } from 'https://deno.land/x/pezkuwi/util-crypto/mod.ts';
+
+import { PAIR_DIV, PAIR_HDR } from './defaults.ts';
+
+/**
+ * Encode a pair with the latest generation format (generation 3)
+ **/
+export function encodePair ({ publicKey, secretKey }: PairInfo, passphrase?: string): Uint8Array {
+  if (!secretKey) {
+    throw new Error('Expected a valid secretKey to be passed to encode');
+  }
+
+  const encoded = u8aConcat(PAIR_HDR, secretKey, PAIR_DIV, publicKey);
+
+  if (!passphrase) {
+    return encoded;
+  }
+
+  // this is only for generation 3 (previous generations are only handled in decoding)
+  const { params, password, salt } = scryptEncode(passphrase);
+  const { encrypted, nonce } = naclEncrypt(encoded, password.subarray(0, 32));
+
+  return u8aConcat(scryptToU8a(salt, params), nonce, encrypted);
+}

package/build-deno/pair/index.ts

@@ -0,0 +1,218 @@
+
+import type { EncryptedJsonEncoding, Keypair, KeypairType } from 'https://deno.land/x/pezkuwi/util-crypto/types.ts';
+import type { KeyringPair, KeyringPair$Json, KeyringPair$Meta, SignOptions } from '../types.ts';
+import type { PairInfo } from './types.ts';
+
+import { objectSpread, u8aConcat, u8aEmpty, u8aEq, u8aToHex, u8aToU8a } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+import { blake2AsU8a, ed25519PairFromSeed as ed25519FromSeed, ed25519Sign, ethereumEncode, keccakAsU8a, keyExtractPath, keyFromPath, secp256k1Compress, secp256k1Expand, secp256k1PairFromSeed as secp256k1FromSeed, secp256k1Sign, signatureVerify, sr25519PairFromSeed as sr25519FromSeed, sr25519Sign, sr25519VrfSign, sr25519VrfVerify } from 'https://deno.land/x/pezkuwi/util-crypto/mod.ts';
+
+import { decodePair } from './decode.ts';
+import { encodePair } from './encode.ts';
+import { pairToJson } from './toJson.ts';
+
+interface Setup {
+  toSS58: (publicKey: Uint8Array) => string;
+  type: KeypairType;
+}
+
+const SIG_TYPE_NONE = new Uint8Array();
+
+const TYPE_FROM_SEED = {
+  ecdsa: secp256k1FromSeed,
+  ed25519: ed25519FromSeed,
+  ethereum: secp256k1FromSeed,
+  sr25519: sr25519FromSeed
+};
+
+const TYPE_PREFIX = {
+  ecdsa: new Uint8Array([2]),
+  ed25519: new Uint8Array([0]),
+  ethereum: new Uint8Array([2]),
+  sr25519: new Uint8Array([1])
+};
+
+const TYPE_SIGNATURE = {
+  ecdsa: (m: Uint8Array, p: Partial<Keypair>) => secp256k1Sign(m, p, 'blake2'),
+  ed25519: ed25519Sign,
+  ethereum: (m: Uint8Array, p: Partial<Keypair>) => secp256k1Sign(m, p, 'keccak'),
+  sr25519: sr25519Sign
+};
+
+const TYPE_ADDRESS = {
+  ecdsa: (p: Uint8Array) => p.length > 32 ? blake2AsU8a(p) : p,
+  ed25519: (p: Uint8Array) => p,
+  ethereum: (p: Uint8Array) => p.length === 20 ? p : keccakAsU8a(secp256k1Expand(p)),
+  sr25519: (p: Uint8Array) => p
+};
+
+function isLocked (secretKey?: Uint8Array): secretKey is undefined {
+  return !secretKey || u8aEmpty(secretKey);
+}
+
+function vrfHash (proof: Uint8Array, context?: string | Uint8Array, extra?: string | Uint8Array): Uint8Array {
+  return blake2AsU8a(u8aConcat(context || '', extra || '', proof));
+}
+
+/**
+ * @name createPair
+ * @summary Creates a keyring pair object
+ * @description Creates a keyring pair object with provided account public key, metadata, and encoded arguments.
+ * The keyring pair stores the account state including the encoded address and associated metadata.
+ *
+ * It has properties whose values are functions that may be called to perform account actions:
+ *
+ * - `address` function retrieves the address associated with the account.
+ * - `decodedPkcs8` function is called with the account passphrase and account encoded public key.
+ * It decodes the encoded public key using the passphrase provided to obtain the decoded account public key
+ * and associated secret key that are then available in memory, and changes the account address stored in the
+ * state of the pair to correspond to the address of the decoded public key.
+ * - `encodePkcs8` function when provided with the correct passphrase associated with the account pair
+ * and when the secret key is in memory (when the account pair is not locked) it returns an encoded
+ * public key of the account.
+ * - `meta` is the metadata that is stored in the state of the pair, either when it was originally
+ * created or set via `setMeta`.
+ * - `publicKey` returns the public key stored in memory for the pair.
+ * - `sign` may be used to return a signature by signing a provided message with the secret
+ * key (if it is in memory) using Nacl.
+ * - `toJson` calls another `toJson` function and provides the state of the pair,
+ * it generates arguments to be passed to the other `toJson` function including an encoded public key of the account
+ * that it generates using the secret key from memory (if it has been made available in memory)
+ * and the optionally provided passphrase argument. It passes a third boolean argument to `toJson`
+ * indicating whether the public key has been encoded or not (if a passphrase argument was provided then it is encoded).
+ * The `toJson` function that it calls returns a JSON object with properties including the `address`
+ * and `meta` that are assigned with the values stored in the corresponding state variables of the account pair,
+ * an `encoded` property that is assigned with the encoded public key in hex format, and an `encoding`
+ * property that indicates whether the public key value of the `encoded` property is encoded or not.
+ */
+export function createPair ({ toSS58, type }: Setup, { publicKey, secretKey }: PairInfo, meta: KeyringPair$Meta = {}, encoded: Uint8Array | null = null, encTypes?: EncryptedJsonEncoding[]): KeyringPair {
+  const decodePkcs8 = (passphrase?: string, userEncoded?: Uint8Array | null): void => {
+    const decoded = decodePair(passphrase, userEncoded || encoded, encTypes);
+
+    if (decoded.secretKey.length === 64) {
+      publicKey = decoded.publicKey;
+      secretKey = decoded.secretKey;
+    } else {
+      const pair = TYPE_FROM_SEED[type](decoded.secretKey);
+
+      publicKey = pair.publicKey;
+      secretKey = pair.secretKey;
+    }
+  };
+
+  const recode = (passphrase?: string): Uint8Array => {
+    isLocked(secretKey) && encoded && decodePkcs8(passphrase, encoded);
+
+    encoded = encodePair({ publicKey, secretKey }, passphrase); // re-encode, latest version
+    encTypes = undefined; // swap to defaults, latest version follows
+
+    return encoded;
+  };
+
+  const encodeAddress = (): string => {
+    const raw = TYPE_ADDRESS[type](publicKey);
+
+    return type === 'ethereum'
+      ? ethereumEncode(raw)
+      : toSS58(raw);
+  };
+
+  return {
+    get address (): string {
+      return encodeAddress();
+    },
+    get addressRaw (): Uint8Array {
+      const raw = TYPE_ADDRESS[type](publicKey);
+
+      return type === 'ethereum'
+        ? raw.slice(-20)
+        : raw;
+    },
+    get isLocked (): boolean {
+      return isLocked(secretKey);
+    },
+    get meta (): KeyringPair$Meta {
+      return meta;
+    },
+    get publicKey (): Uint8Array {
+      return publicKey;
+    },
+    get type (): KeypairType {
+      return type;
+    },
+    // eslint-disable-next-line sort-keys
+    decodePkcs8,
+    derive: (suri: string, meta?: KeyringPair$Meta): KeyringPair => {
+      if (type === 'ethereum') {
+        throw new Error('Unable to derive on this keypair');
+      } else if (isLocked(secretKey)) {
+        throw new Error('Cannot derive on a locked keypair');
+      }
+
+      const { path } = keyExtractPath(suri);
+      const derived = keyFromPath({ publicKey, secretKey }, path, type);
+
+      return createPair({ toSS58, type }, derived, meta, null);
+    },
+    encodePkcs8: (passphrase?: string): Uint8Array => {
+      return recode(passphrase);
+    },
+    lock: (): void => {
+      secretKey = new Uint8Array();
+    },
+    setMeta: (additional: KeyringPair$Meta): void => {
+      meta = objectSpread({}, meta, additional);
+    },
+    sign: (message: string | Uint8Array, options: SignOptions = {}): Uint8Array => {
+      if (isLocked(secretKey)) {
+        throw new Error('Cannot sign with a locked key pair');
+      }
+
+      return u8aConcat(
+        options.withType
+          ? TYPE_PREFIX[type]
+          : SIG_TYPE_NONE,
+        TYPE_SIGNATURE[type](u8aToU8a(message), { publicKey, secretKey })
+      );
+    },
+    toJson: (passphrase?: string): KeyringPair$Json => {
+      // NOTE: For ecdsa and ethereum, the publicKey cannot be extracted from the address. For these
+      // pass the hex-encoded publicKey through to the address portion of the JSON (before decoding)
+      // unless the publicKey is already an address
+      const address = ['ecdsa', 'ethereum'].includes(type)
+        ? publicKey.length === 20
+          ? u8aToHex(publicKey)
+          : u8aToHex(secp256k1Compress(publicKey))
+        : encodeAddress();
+
+      return pairToJson(type, { address, meta }, recode(passphrase), !!passphrase);
+    },
+    unlock: (passphrase?: string): void => {
+      return decodePkcs8(passphrase);
+    },
+    verify: (message: string | Uint8Array, signature: string | Uint8Array, signerPublic: string | Uint8Array): boolean => {
+      return signatureVerify(message, signature, TYPE_ADDRESS[type](u8aToU8a(signerPublic))).isValid;
+    },
+    vrfSign: (message: string | Uint8Array, context?: string | Uint8Array, extra?: string | Uint8Array): Uint8Array => {
+      if (isLocked(secretKey)) {
+        throw new Error('Cannot sign with a locked key pair');
+      }
+
+      if (type === 'sr25519') {
+        return sr25519VrfSign(message, { secretKey }, context, extra);
+      }
+
+      const proof = TYPE_SIGNATURE[type](u8aToU8a(message), { publicKey, secretKey });
+
+      return u8aConcat(vrfHash(proof, context, extra), proof);
+    },
+    vrfVerify: (message: string | Uint8Array, vrfResult: Uint8Array, signerPublic: Uint8Array | string, context?: string | Uint8Array, extra?: string | Uint8Array): boolean => {
+      if (type === 'sr25519') {
+        return sr25519VrfVerify(message, vrfResult, publicKey, context, extra);
+      }
+
+      const result = signatureVerify(message, u8aConcat(TYPE_PREFIX[type], vrfResult.subarray(32)), TYPE_ADDRESS[type](u8aToU8a(signerPublic)));
+
+      return result.isValid && u8aEq(vrfResult.subarray(0, 32), vrfHash(vrfResult.subarray(32), context, extra));
+    }
+  };
+}