From da6efc821e7c1cc84a83f21650b28aa7a19af5e9 Mon Sep 17 00:00:00 2001 From: Jaco Date: Wed, 30 Aug 2023 11:25:10 +0300 Subject: [PATCH] Add additional comments on type interfaces (#1875) --- packages/keyring/src/types.ts | 12 +++--------- packages/networks/src/types.ts | 7 +++++++ packages/util-crypto/src/json/types.ts | 5 +++++ packages/util-crypto/src/key/extractPath.ts | 2 +- packages/util-crypto/src/key/extractSuri.ts | 2 +- packages/util-crypto/src/scrypt/defaults.ts | 4 +++- packages/util-crypto/src/scrypt/encode.ts | 4 ++-- packages/util-crypto/src/scrypt/fromU8a.ts | 11 ++++++----- packages/util-crypto/src/scrypt/toU8a.ts | 4 ++-- packages/util-crypto/src/scrypt/types.ts | 3 ++- packages/util-crypto/src/types.ts | 9 +++++++++ packages/util/src/types.ts | 13 ++++--------- 12 files changed, 45 insertions(+), 31 deletions(-) diff --git a/packages/keyring/src/types.ts b/packages/keyring/src/types.ts index 0a7a01a3f61..73cef4af247 100644 --- a/packages/keyring/src/types.ts +++ b/packages/keyring/src/types.ts @@ -5,13 +5,9 @@ import type { HexString } from '@polkadot/util/types'; import type { EncryptedJson, Keypair, KeypairType, Prefix } from '@polkadot/util-crypto/types'; export interface KeyringOptions { - /** - * @description The ss58Format to use for address encoding (defaults to 42) - */ + /** The ss58Format to use for address encoding (defaults to 42) */ ss58Format?: Prefix; - /** - * @description The type of keyring to create (defaults to ed25519) - */ + /** The type of keyring to create (defaults to ed25519) */ type?: KeypairType; } @@ -76,9 +72,7 @@ export interface KeyringPair$Json extends EncryptedJson { } export interface SignOptions { - /** - * @description Create a MultiSignature-compatible output with an indicator type - **/ + /** Create a MultiSignature-compatible output with an indicator type */ withType?: boolean; } diff --git a/packages/networks/src/types.ts b/packages/networks/src/types.ts index ff812944e4a..0e9b5e2938b 100644 --- a/packages/networks/src/types.ts +++ b/packages/networks/src/types.ts @@ -17,15 +17,22 @@ export type KnownSubstrate = RegistryEntry; export type KnownTestnet = Record; export interface SubstrateNetwork extends KnownSubstrate { + /** The genesisHash for the chain */ genesisHash: HexString[]; + /** Does the chain has support for Ledger devices */ hasLedgerSupport: boolean; + /** The IdentityIcon to use for the chain */ icon: Icon; + /** Flag set when we don't include this chain */ isIgnored: boolean; + /** Flag to indicate a testnet */ isTestnet: boolean; + /** The Ledger-specific/required slip44 for the chain */ slip44?: number | null; } export interface Network extends SubstrateNetwork { + /** The network assigned to this chain */ network: string; } diff --git a/packages/util-crypto/src/json/types.ts b/packages/util-crypto/src/json/types.ts index 45a3e4681db..87918f65c05 100644 --- a/packages/util-crypto/src/json/types.ts +++ b/packages/util-crypto/src/json/types.ts @@ -6,12 +6,17 @@ export type EncryptedJsonVersion = '0' | '1' | '2' | '3'; export type EncryptedJsonEncoding = 'none' | 'scrypt' | 'xsalsa20-poly1305'; export interface EncryptedJsonDescriptor { + /** Descriptor for the content */ content: string[]; + /** The encoding (in current/latest versions this is always an array) */ type: EncryptedJsonEncoding | EncryptedJsonEncoding[]; + /** The version of encoding applied */ version: EncryptedJsonVersion; } export interface EncryptedJson { + /** The encoded string */ encoded: string; + /** The encoding used */ encoding: EncryptedJsonDescriptor; } diff --git a/packages/util-crypto/src/key/extractPath.ts b/packages/util-crypto/src/key/extractPath.ts index ddfe2d04a90..7d8c70d5f8d 100644 --- a/packages/util-crypto/src/key/extractPath.ts +++ b/packages/util-crypto/src/key/extractPath.ts @@ -6,7 +6,7 @@ import { DeriveJunction } from './DeriveJunction.js'; const RE_JUNCTION = /\/(\/?)([^/]+)/g; export interface ExtractResult { - parts: null | string[]; + parts: string[] | null; path: DeriveJunction[]; } diff --git a/packages/util-crypto/src/key/extractSuri.ts b/packages/util-crypto/src/key/extractSuri.ts index cf0ca66a291..76f76ed08bc 100644 --- a/packages/util-crypto/src/key/extractSuri.ts +++ b/packages/util-crypto/src/key/extractSuri.ts @@ -25,7 +25,7 @@ export function keyExtractSuri (suri: string): ExtractResult { throw new Error('Unable to match provided value to a secret URI'); } - const [, phrase, , derivePath, , , password] = matches as string[]; + const [, phrase, , derivePath, , , password] = matches; const { path } = keyExtractPath(derivePath); return { diff --git a/packages/util-crypto/src/scrypt/defaults.ts b/packages/util-crypto/src/scrypt/defaults.ts index 8906e419952..c86285a3931 100644 --- a/packages/util-crypto/src/scrypt/defaults.ts +++ b/packages/util-crypto/src/scrypt/defaults.ts @@ -1,7 +1,9 @@ // Copyright 2017-2023 @polkadot/util-crypto authors & contributors // SPDX-License-Identifier: Apache-2.0 -export const DEFAULT_PARAMS = { +import type { ScryptParams } from './types.js'; + +export const DEFAULT_PARAMS: ScryptParams = { N: 1 << 15, p: 1, r: 8 diff --git a/packages/util-crypto/src/scrypt/encode.ts b/packages/util-crypto/src/scrypt/encode.ts index e79b78de15d..a8c529f202b 100644 --- a/packages/util-crypto/src/scrypt/encode.ts +++ b/packages/util-crypto/src/scrypt/encode.ts @@ -1,7 +1,7 @@ // Copyright 2017-2023 @polkadot/util-crypto authors & contributors // SPDX-License-Identifier: Apache-2.0 -import type { Params } from './types.js'; +import type { ScryptParams } from './types.js'; import { scrypt as scryptJs } from '@noble/hashes/scrypt'; @@ -12,7 +12,7 @@ import { randomAsU8a } from '../random/asU8a.js'; import { DEFAULT_PARAMS } from './defaults.js'; interface Result { - params: Params, + params: ScryptParams, password: Uint8Array; salt: Uint8Array; } diff --git a/packages/util-crypto/src/scrypt/fromU8a.ts b/packages/util-crypto/src/scrypt/fromU8a.ts index 9e6be41503f..f773fae5150 100644 --- a/packages/util-crypto/src/scrypt/fromU8a.ts +++ b/packages/util-crypto/src/scrypt/fromU8a.ts @@ -1,7 +1,7 @@ // Copyright 2017-2023 @polkadot/util-crypto authors & contributors // SPDX-License-Identifier: Apache-2.0 -import type { Params } from './types.js'; +import type { ScryptParams } from './types.js'; import { u8aToBn } from '@polkadot/util'; @@ -9,7 +9,7 @@ import { BN_LE_OPTS } from '../bn.js'; import { DEFAULT_PARAMS } from './defaults.js'; interface Result { - params: Params, + params: ScryptParams, salt: Uint8Array; } @@ -19,9 +19,10 @@ export function scryptFromU8a (data: Uint8Array): Result { const p = u8aToBn(data.subarray(32 + 4, 32 + 8), BN_LE_OPTS).toNumber(); const r = u8aToBn(data.subarray(32 + 8, 32 + 12), BN_LE_OPTS).toNumber(); - // FIXME At this moment we assume these to be fixed params, this is not a great idea since we lose flexibility - // and updates for greater security. However we need some protection against carefully-crafted params that can - // eat up CPU since these are user inputs. So we need to get very clever here, but atm we only allow the defaults + // FIXME At this moment we assume these to be fixed params, this is not a great idea + // since we lose flexibility and updates for greater security. However we need some + // protection against carefully-crafted params that can eat up CPU since these are user + // inputs. So we need to get very clever here, but atm we only allow the defaults // and if no match, bail out if (N !== DEFAULT_PARAMS.N || p !== DEFAULT_PARAMS.p || r !== DEFAULT_PARAMS.r) { throw new Error('Invalid injected scrypt params found'); diff --git a/packages/util-crypto/src/scrypt/toU8a.ts b/packages/util-crypto/src/scrypt/toU8a.ts index bf956d218e1..80e5020970d 100644 --- a/packages/util-crypto/src/scrypt/toU8a.ts +++ b/packages/util-crypto/src/scrypt/toU8a.ts @@ -1,13 +1,13 @@ // Copyright 2017-2023 @polkadot/util-crypto authors & contributors // SPDX-License-Identifier: Apache-2.0 -import type { Params } from './types.js'; +import type { ScryptParams } from './types.js'; import { bnToU8a, u8aConcat } from '@polkadot/util'; import { BN_LE_32_OPTS } from '../bn.js'; -export function scryptToU8a (salt: Uint8Array, { N, p, r }: Params): Uint8Array { +export function scryptToU8a (salt: Uint8Array, { N, p, r }: ScryptParams): Uint8Array { return u8aConcat( salt, bnToU8a(N, BN_LE_32_OPTS), diff --git a/packages/util-crypto/src/scrypt/types.ts b/packages/util-crypto/src/scrypt/types.ts index 81b65eaf2b2..60cb9a3c646 100644 --- a/packages/util-crypto/src/scrypt/types.ts +++ b/packages/util-crypto/src/scrypt/types.ts @@ -1,7 +1,8 @@ // Copyright 2017-2023 @polkadot/util-crypto authors & contributors // SPDX-License-Identifier: Apache-2.0 -export interface Params { +/** The params that control scrypt generation */ +export interface ScryptParams { N: number; p: number; r: number; diff --git a/packages/util-crypto/src/types.ts b/packages/util-crypto/src/types.ts index 8a5f366d00d..da415ae249e 100644 --- a/packages/util-crypto/src/types.ts +++ b/packages/util-crypto/src/types.ts @@ -5,20 +5,29 @@ export * from './address/types.js'; export * from './json/types.js'; export interface Keypair { + /** The publicKey for this pair */ publicKey: Uint8Array; + /** The secretKey for this pair */ secretKey: Uint8Array; } export interface Seedpair { + /** The publicKey for this pair */ publicKey: Uint8Array; + /** The seed used to construct the pair */ seed: Uint8Array; } +/** The supported types of pairs */ export type KeypairType = 'ed25519' | 'sr25519' | 'ecdsa' | 'ethereum'; export interface VerifyResult { + /** The detected crypto interface, or 'none' if not detected */ crypto: 'none' | KeypairType; + /** The validity for this result, false if invalid */ isValid: boolean; + /** Flag to indicate if the passed data was wrapped in ... */ isWrapped: boolean; + /** The extracted publicKey */ publicKey: Uint8Array; } diff --git a/packages/util/src/types.ts b/packages/util/src/types.ts index 43322103993..a29d3665a80 100644 --- a/packages/util/src/types.ts +++ b/packages/util/src/types.ts @@ -5,6 +5,7 @@ import type { BN } from './bn/bn.js'; /* eslint-disable @typescript-eslint/no-explicit-any */ +/** An interface that defines an actual JS class */ export interface Class { prototype: T; @@ -40,20 +41,14 @@ export interface Logger { } export interface ToBnOptions { - /** - * @description Convert in LE format - */ + /** Convert in LE format */ isLe?: boolean; - /** - * @description Number is signed, apply two's complement - */ + /** Number is signed, apply two's complement */ isNegative?: boolean; } export interface NumberOptions extends ToBnOptions { - /** - * @description Limit to the specified bitLength, despite input length - */ + /** Limit to the specified bitLength, despite input length */ bitLength?: number; }