Wallet Management

/**
 * A wallet implementation that supports hierarchical deterministic key derivation
 * using BIP39 mnemonics and secp256k1 elliptic curve cryptography
 */
class DirectSecp256k1HdWallet implements OfflineDirectSigner {
  /**
   * Creates a wallet from a BIP39 mnemonic
   * @param mnemonic - BIP39 mnemonic phrase (12, 15, 18, 21, or 24 words)
   * @param options - Optional configuration for the wallet
   * @returns Promise resolving to DirectSecp256k1HdWallet instance
   */
  static fromMnemonic(
    mnemonic: string,
    options?: Partial<DirectSecp256k1HdWalletOptions>
  ): Promise<DirectSecp256k1HdWallet>;

  /**
   * Generates a new wallet with a random mnemonic
   * @param length - Mnemonic length in words (12, 15, 18, 21, or 24). Defaults to 12
   * @param options - Optional configuration for the wallet
   * @returns Promise resolving to DirectSecp256k1HdWallet instance
   */
  static generate(
    length?: 12 | 15 | 18 | 21 | 24,
    options?: Partial<DirectSecp256k1HdWalletOptions>
  ): Promise<DirectSecp256k1HdWallet>;

  /**
   * Deserializes an encrypted wallet from string format
   * @param serialization - Encrypted wallet serialization string
   * @param password - Password used for decryption
   * @returns Promise resolving to DirectSecp256k1HdWallet instance
   */
  static deserialize(
    serialization: string,
    password: string
  ): Promise<DirectSecp256k1HdWallet>;

  /**
   * Deserializes an encrypted wallet using a specific encryption key
   * @param serialization - Encrypted wallet serialization string
   * @param encryptionKey - Encryption key for decryption
   * @returns Promise resolving to DirectSecp256k1HdWallet instance
   */
  static deserializeWithEncryptionKey(
    serialization: string,
    encryptionKey: Uint8Array
  ): Promise<DirectSecp256k1HdWallet>;

  /**
   * Gets the mnemonic phrase for this wallet
   * @returns The BIP39 mnemonic phrase
   */
  get mnemonic(): string;

  /**
   * Gets all accounts derived from the wallet's mnemonic
   * @returns Promise resolving to array of account data
   */
  getAccounts(): Promise<readonly AccountData[]>;

  /**
   * Signs a transaction using direct signing mode
   * @param signerAddress - The address of the signer
   * @param signDoc - The signing document to sign
   * @returns Promise resolving to the signing response
   */
  signDirect(signerAddress: string, signDoc: SignDoc): Promise<DirectSignResponse>;

  /**
   * Serializes the wallet with password encryption
   * @param password - Password for encryption
   * @returns Promise resolving to encrypted serialization string
   */
  serialize(password: string): Promise<string>;

  /**
   * Serializes the wallet with a specific encryption key
   * @param encryptionKey - Encryption key for serialization
   * @param kdfConfiguration - KDF configuration for encryption
   * @returns Promise resolving to encrypted serialization string
   */
  serializeWithEncryptionKey(
    encryptionKey: Uint8Array,
    kdfConfiguration: KdfConfiguration
  ): Promise<string>;
}

interface DirectSecp256k1HdWalletOptions {
  /** Optional BIP39 passphrase for additional security */
  bip39Password?: string;
  /** Custom HD derivation paths. Defaults to [makeCosmoshubPath(0)] */
  hdPaths?: readonly HdPath[];
  /** Address prefix for bech32 encoding. Defaults to "cosmos" */
  prefix?: string;
}

import { DirectSecp256k1HdWallet, makeCosmoshubPath } from "@cosmjs/proto-signing";

// Create from existing mnemonic
const wallet = await DirectSecp256k1HdWallet.fromMnemonic(
  "surround miss nominee dream gap cross assault thank captain prosper drop duty group candy wealth weather scale put",
  {
    prefix: "cosmos",
    hdPaths: [makeCosmoshubPath(0), makeCosmoshubPath(1)], // Multiple accounts
  }
);

// Generate new wallet
const newWallet = await DirectSecp256k1HdWallet.generate(12, { prefix: "osmo" });

// Get accounts
const accounts = await wallet.getAccounts();
console.log(accounts[0].address); // cosmos1...

// Serialize for storage
const serialized = await wallet.serialize("password123");
const restored = await DirectSecp256k1HdWallet.deserialize(serialized, "password123");

/**
 * A wallet that holds a single secp256k1 keypair
 * If you want to work with BIP39 mnemonics and multiple accounts, use DirectSecp256k1HdWallet
 */
class DirectSecp256k1Wallet implements OfflineDirectSigner {
  /**
   * Creates a DirectSecp256k1Wallet from a private key
   * @param privkey - The private key as Uint8Array
   * @param prefix - The bech32 address prefix. Defaults to "cosmos"
   * @returns Promise resolving to DirectSecp256k1Wallet instance
   */
  static fromKey(privkey: Uint8Array, prefix?: string): Promise<DirectSecp256k1Wallet>;

  /**
   * Gets the single account for this wallet
   * @returns Promise resolving to array containing one account
   */
  getAccounts(): Promise<readonly AccountData[]>;

  /**
   * Signs a transaction using direct signing mode
   * @param address - The signer address (must match this wallet's address)
   * @param signDoc - The signing document to sign
   * @returns Promise resolving to the signing response
   */
  signDirect(address: string, signDoc: SignDoc): Promise<DirectSignResponse>;
}

import { DirectSecp256k1Wallet } from "@cosmjs/proto-signing";
import { Random } from "@cosmjs/crypto";

// Create from existing private key
const privateKey = new Uint8Array([
  // 32 bytes of private key data
]);
const wallet = await DirectSecp256k1Wallet.fromKey(privateKey, "cosmos");

// Generate random wallet
const randomPrivkey = Random.getBytes(32);
const randomWallet = await DirectSecp256k1Wallet.fromKey(randomPrivkey, "osmo");

// Get account
const accounts = await wallet.getAccounts();
const signerAddress = accounts[0].address;

/**
 * Extracts KDF configuration from a serialized wallet
 * @param serialization - Serialized wallet string
 * @returns KDF configuration object
 */
function extractKdfConfiguration(serialization: string): KdfConfiguration;

/**
 * Creates a Cosmos Hub derivation path
 * @param accountIndex - Zero-based account index
 * @returns HD path in format m/44'/118'/0'/0/accountIndex
 */
function makeCosmoshubPath(accountIndex: number): HdPath;

/**
 * Type guard to check if a signer supports direct signing
 * @param signer - The signer to check
 * @returns True if signer is an OfflineDirectSigner
 */
function isOfflineDirectSigner(signer: OfflineSigner): signer is OfflineDirectSigner;

/**
 * Executes a key derivation function (KDF) to derive an encryption key from a password
 * @param password - The password to derive the key from
 * @param configuration - KDF configuration specifying algorithm and parameters
 * @returns Promise resolving to derived encryption key
 */
function executeKdf(password: string, configuration: KdfConfiguration): Promise<Uint8Array>;

interface AccountData {
  /** A printable address (typically bech32 encoded) */
  readonly address: string;
  readonly algo: Algo;
  readonly pubkey: Uint8Array;
}

interface DirectSignResponse {
  /**
   * The sign doc that was signed.
   * This may be different from the input signDoc when the signer modifies it as part of the signing process.
   */
  readonly signed: SignDoc;
  readonly signature: StdSignature;
}

interface OfflineDirectSigner {
  readonly getAccounts: () => Promise<readonly AccountData[]>;
  readonly signDirect: (signerAddress: string, signDoc: SignDoc) => Promise<DirectSignResponse>;
}

type Algo = "secp256k1" | "ed25519" | "sr25519";
type OfflineSigner = OfflineAminoSigner | OfflineDirectSigner;

interface KdfConfiguration {
  /** An algorithm identifier, such as "argon2id" */
  readonly algorithm: string;
  /** A map of algorithm-specific parameters */
  readonly params: Record<string, unknown>;
}