tessl/npm-polkadot--util-crypto

A collection of useful crypto utilities for Polkadot ecosystem projects

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@polkadot/util-crypto

Name: tessl/npm-polkadot--util-crypto
Author: tessl

@polkadot/util-crypto is a comprehensive cryptographic utilities library designed specifically for the Polkadot ecosystem. It provides a wide range of cryptographic functions including key management, digital signatures, hashing algorithms, address encoding/decoding, and hierarchical deterministic key derivation across multiple cryptographic schemes.

Package Information

Package Name: @polkadot/util-crypto
Package Type: npm
Language: TypeScript
Installation: npm install @polkadot/util-crypto

Core Imports

import { 
  cryptoWaitReady,
  mnemonicGenerate,
  encodeAddress,
  decodeAddress,
  sr25519PairFromSeed,
  ed25519Sign
} from "@polkadot/util-crypto";

For CommonJS:

const { 
  cryptoWaitReady,
  mnemonicGenerate,
  encodeAddress,
  decodeAddress,
  sr25519PairFromSeed,
  ed25519Sign
} = require("@polkadot/util-crypto");

Basic Usage

import { 
  cryptoWaitReady,
  mnemonicGenerate,
  mnemonicValidate,
  mnemonicToMiniSecret,
  sr25519PairFromSeed,
  encodeAddress,
  signatureVerify
} from "@polkadot/util-crypto";

// Initialize crypto before usage
await cryptoWaitReady();

// Generate and validate mnemonic
const mnemonic = mnemonicGenerate();
const isValid = mnemonicValidate(mnemonic);

// Create key pair from mnemonic
const seed = mnemonicToMiniSecret(mnemonic);
const pair = sr25519PairFromSeed(seed);

// Encode address with Polkadot prefix (0)
const address = encodeAddress(pair.publicKey, 0);

// Sign and verify message
const message = new TextEncoder().encode("Hello Polkadot");
const signature = sr25519Sign(message, pair);
const verified = signatureVerify(message, signature, address);

Architecture

@polkadot/util-crypto is organized around several key functional areas:

Address System: SS58 address encoding/decoding with multi-network support
Cryptographic Schemes: Support for sr25519, ed25519, secp256k1, and ECDSA
Key Management: Hierarchical deterministic key derivation and mnemonic handling
Hashing Algorithms: Blake2, Keccak, SHA, and xxHash implementations
Encoding Utilities: Base32, Base58, and Base64 encoding/decoding
Security Features: Password-based key derivation, encryption, and digital signatures

Capabilities

Crypto Initialization

Core initialization functions to prepare the WebAssembly crypto backend.

function cryptoWaitReady(): Promise<boolean>;
function cryptoIsReady(): boolean;

Crypto Initialization

Address Management

SS58 address encoding, decoding, and validation with support for multi-signature and derived addresses.

function encodeAddress(publicKey: Uint8Array, prefix?: number): string;
function decodeAddress(address: string, ignoreChecksum?: boolean, prefix?: number): Uint8Array;
function checkAddress(address: string, prefix?: number): [boolean, string | null];
function addressEq(a: string, b: string): boolean;

Address Management

Key Pair Generation

Key pair generation and management for sr25519, ed25519, and secp256k1 cryptographic schemes.

interface Keypair {
  publicKey: Uint8Array;
  secretKey: Uint8Array;
}

interface Seedpair {
  publicKey: Uint8Array;
  seed: Uint8Array;
}

type KeypairType = 'ed25519' | 'sr25519' | 'ecdsa' | 'ethereum';

function sr25519PairFromSeed(seed: Uint8Array): Keypair;
function ed25519PairFromSeed(seed: Uint8Array): Keypair;
function secp256k1PairFromSeed(seed: Uint8Array): Keypair;

Key Pair Generation

Digital Signatures

Signing and verification functions for multiple cryptographic schemes with signature format detection.

interface VerifyResult {
  crypto: 'none' | KeypairType;
  isValid: boolean;
  isWrapped: boolean;
  publicKey: Uint8Array;
}

function sr25519Sign(message: string | Uint8Array, keypair: Partial<Keypair>): Uint8Array;
function ed25519Sign(publicKey: Uint8Array, secretKey: Uint8Array, message: Uint8Array): Uint8Array;
function signatureVerify(message: Uint8Array, signature: Uint8Array, addressOrPublicKey: string | Uint8Array): VerifyResult;

Digital Signatures

Mnemonic Management

BIP39-compatible mnemonic generation, validation, and seed derivation.

function mnemonicGenerate(numWords?: 12 | 15 | 18 | 21 | 24, wordlist?: string[]): string;
function mnemonicValidate(mnemonic: string, wordlist?: string[]): boolean;
function mnemonicToMiniSecret(mnemonic: string, password?: string): Uint8Array;
function mnemonicToEntropy(mnemonic: string, wordlist?: string[]): Uint8Array;

Mnemonic Management

Hierarchical Key Derivation

Hierarchical deterministic key derivation supporting both hard and soft derivation paths.

function keyFromPath(pair: Keypair, path: string, type: KeypairType): Keypair;
function keyExtractPath(path: string): { path: string; password?: string };
function hdEthereum(seed: Uint8Array, path?: string): Keypair;
function hdLedger(mnemonic: string, path: string, rounds?: number): Keypair;

Hierarchical Key Derivation

Hashing Algorithms

Comprehensive hashing functions including Blake2, Keccak, SHA, and xxHash.

function blake2AsU8a(data: Uint8Array, bitLength?: 64 | 128 | 256 | 512, key?: Uint8Array): Uint8Array;
function keccakAsU8a(value: Uint8Array, bitLength?: 256 | 512): Uint8Array;
function sha256AsU8a(value: Uint8Array): Uint8Array;
function xxhashAsU8a(data: Uint8Array, bitLength?: 64 | 128 | 256): Uint8Array;

Hashing Algorithms

Base Encoding

Encoding and decoding utilities for Base32, Base58, and Base64 formats.

function base58Encode(value: Uint8Array, ipfsCompat?: boolean): string;
function base58Decode(value: string, ipfsCompat?: boolean): Uint8Array;
function base64Encode(value: Uint8Array): string;
function base64Decode(value: string): Uint8Array;

Base Encoding

Password-Based Key Derivation

PBKDF2 and Scrypt implementations for password-based key derivation.

function pbkdf2Encode(passphrase: string, salt?: Uint8Array, rounds?: number, length?: number): Uint8Array;
function scryptEncode(passphrase: string, salt?: Uint8Array, N?: number, r?: number, p?: number, dkLen?: number): Uint8Array;

Password-Based Key Derivation

JSON Encryption

Secure JSON encryption and decryption with password protection.

interface EncryptedJson {
  encoded: string;
  encoding: EncryptedJsonDescriptor;
}

interface EncryptedJsonDescriptor {
  content: string[];
  type: EncryptedJsonEncoding | EncryptedJsonEncoding[];
  version: EncryptedJsonVersion;
}

function jsonEncrypt(data: Uint8Array, contentType: string[], passphrase: string): EncryptedJson;
function jsonDecrypt(json: EncryptedJson, passphrase: string): Uint8Array;

JSON Encryption

Random Number Generation

Cryptographically secure random number generation in various formats.

function randomAsU8a(bitLength?: number): Uint8Array;
function randomAsHex(bitLength?: number): string;
function randomAsNumber(bitLength?: number): number;

Random Number Generation

Ethereum Compatibility

Ethereum address handling and compatibility utilities.

function ethereumEncode(addressOrPublic: string | Uint8Array): string;
function isEthereumAddress(address: string): boolean;
function addressToEvm(address: string): Uint8Array;
function evmToAddress(evmAddress: Uint8Array, prefix?: number, hashType?: 'blake2' | 'keccak'): string;

Ethereum Compatibility

NaCl Secret-key Encryption

NaCl secretbox encryption and decryption for authenticated symmetric encryption.

interface NaclEncrypted {
  encrypted: Uint8Array;
  nonce: Uint8Array;
}

function naclEncrypt(message: Uint8Array, secret: Uint8Array, nonce?: Uint8Array): NaclEncrypted;
function naclDecrypt(encrypted: Uint8Array, nonce: Uint8Array, secret: Uint8Array): Uint8Array | null;

Network Constants

Network configuration constants for multi-chain support across Polkadot ecosystem.

const allNetworks: Network[];
const availableNetworks: Network[];
const selectableNetworks: Network[];

Core Types

interface Keypair {
  /** The publicKey for this pair */
  publicKey: Uint8Array;
  /** The secretKey for this pair */
  secretKey: Uint8Array;
}

interface Seedpair {
  /** The publicKey for this pair */
  publicKey: Uint8Array;
  /** The seed used to construct the pair */
  seed: Uint8Array;
}

/** The supported types of pairs */
type KeypairType = 'ed25519' | 'sr25519' | 'ecdsa' | 'ethereum';

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 <Bytes>...</Bytes> */
  isWrapped: boolean;
  /** The extracted publicKey */
  publicKey: Uint8Array;
}

interface DeriveJunction {
  /** Chain code for derivation */
  readonly chainCode: Uint8Array;
  /** Whether this is a hard derivation */
  readonly isHard: boolean;
  /** Whether this is a soft derivation */
  readonly isSoft: boolean;
}

interface ExtractResult {
  derivePath: string;
  password?: string;
  path: DeriveJunction[];
  phrase: string;
}

interface NaclEncrypted {
  encrypted: Uint8Array;
  nonce: Uint8Array;
}

type EncryptedJsonVersion = '0' | '1' | '2' | '3';
type EncryptedJsonEncoding = 'none' | 'scrypt' | 'xsalsa20-poly1305';
type Prefix = number;