Account Management

/**
 * Create a new account with random private key
 * @returns Web3Account with address, private key, and signing methods
 */
create(): Web3Account;

/**
 * Create account from existing private key
 * @param privateKey - Private key as hex string or Uint8Array
 * @returns Web3Account instance
 */
privateKeyToAccount(privateKey: Uint8Array | string): Web3Account;

/**
 * Extract address from private key
 * @param privateKey - Private key as hex string or Uint8Array
 * @returns Ethereum address
 */
privateKeyToAddress(privateKey: Bytes): string;

/**
 * Extract public key from private key
 * @param privateKey - Private key as hex string or Uint8Array
 * @param isCompressed - Whether to return compressed public key
 * @returns Public key as hex string
 */
privateKeyToPublicKey(privateKey: Bytes, isCompressed: boolean): string;

// Create new random account
const account = web3.eth.accounts.create();
console.log('Address:', account.address);
console.log('Private Key:', account.privateKey);

// Create account from existing private key
const privateKey = '0x4f3edf983ac636a65a842ce7c78d9aa706d3b113bce9c46f30d7d21715b23b1d';
const account = web3.eth.accounts.privateKeyToAccount(privateKey);

// Get address from private key
const address = web3.eth.accounts.privateKeyToAddress(privateKey);

// Get public key from private key
const publicKey = web3.eth.accounts.privateKeyToPublicKey(privateKey, false);

/**
 * Sign a transaction with private key
 * @param transaction - Transaction object to sign
 * @param privateKey - Private key for signing
 * @returns Signed transaction object
 */
signTransaction(
  transaction: Transaction,
  privateKey: Bytes
): Promise<SignedTransactionInfoAPI>;

/**
 * Recover transaction sender from signed transaction
 * @param rawTransaction - Raw signed transaction data
 * @returns Address of transaction sender
 */
recoverTransaction(rawTransaction: Bytes): string;

// Sign a transaction
const transaction = {
  to: '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984',
  value: web3.utils.toWei('0.1', 'ether'),
  gas: 21000,
  gasPrice: web3.utils.toWei('20', 'gwei'),
  nonce: 0
};

const signedTx = await web3.eth.accounts.signTransaction(transaction, privateKey);
console.log('Signed transaction:', signedTx.rawTransaction);

// Send signed transaction
const receipt = await web3.eth.sendSignedTransaction(signedTx.rawTransaction);

// Recover sender from signed transaction
const senderAddress = web3.eth.accounts.recoverTransaction(signedTx.rawTransaction);

/**
 * Sign a message with private key
 * @param message - Message to sign
 * @param privateKey - Private key for signing
 * @returns Signature object with message hash and signature
 */
sign(message: string, privateKey: Bytes): SignResult;

/**
 * Recover signer address from message and signature
 * @param signatureObject - Signature object or signature string
 * @param message - Original message (if signature is string)
 * @returns Address of message signer
 */
recover(signatureObject: SignatureObject): string;
recover(signature: string, message: string): string;

/**
 * Hash a message using Ethereum signed message format
 * @param message - Message to hash
 * @returns Message hash
 */
hashMessage(message: string): string;

// Sign a message
const message = 'Hello, Web3!';
const signature = web3.eth.accounts.sign(message, privateKey);
console.log('Signature:', signature.signature);
console.log('Message hash:', signature.messageHash);

// Recover signer address
const signerAddress = web3.eth.accounts.recover(signature);
console.log('Signer:', signerAddress);

// Alternative recovery with signature string
const recoveredAddress = web3.eth.accounts.recover(signature.signature, message);

// Hash message manually
const messageHash = web3.eth.accounts.hashMessage(message);

/**
 * Encrypt an account's private key to create keystore
 * @param privateKey - Private key to encrypt
 * @param password - Password for encryption
 * @param options - Encryption options
 * @returns Encrypted keystore object
 */
encrypt(privateKey: Bytes, password: string, options?: EncryptOptions): Promise<KeyStore>;

/**
 * Decrypt keystore to recover account
 * @param keystore - Keystore object or JSON string
 * @param password - Password for decryption
 * @param options - Decryption options
 * @returns Decrypted Web3Account
 */
decrypt(
  keystore: KeyStore | string,
  password: string,
  options?: DecryptOptions
): Promise<Web3Account>;

// Encrypt account
const keystore = await web3.eth.accounts.encrypt(privateKey, 'mySecretPassword');
console.log('Keystore:', JSON.stringify(keystore, null, 2));

// Decrypt keystore
const decryptedAccount = await web3.eth.accounts.decrypt(keystore, 'mySecretPassword');
console.log('Decrypted address:', decryptedAccount.address);

// Decrypt from JSON string
const keystoreJson = JSON.stringify(keystore);
const account = await web3.eth.accounts.decrypt(keystoreJson, 'mySecretPassword');

interface Wallet extends Array<Web3Account> {
  /**
   * Create and add new account to wallet
   * @param entropy - Optional entropy for key generation
   * @returns Created Web3Account
   */
  create(entropy?: string): Web3Account;
  
  /**
   * Add account to wallet from private key
   * @param privateKey - Private key or Web3Account
   * @returns Added Web3Account
   */
  add(privateKey: string | Web3Account): Web3Account;
  
  /**
   * Remove account from wallet
   * @param addressOrIndex - Account address or index
   * @returns Boolean indicating success
   */
  remove(addressOrIndex: string | number): boolean;
  
  /**
   * Clear all accounts from wallet
   * @returns Wallet instance
   */
  clear(): Wallet;
  
  /**
   * Encrypt all accounts in wallet
   * @param password - Password for encryption
   * @returns Array of encrypted keystores
   */
  encrypt(password: string): Promise<KeyStore[]>;
  
  /**
   * Decrypt and load accounts from keystores
   * @param keystores - Array of keystores
   * @param password - Password for decryption
   * @returns Wallet instance
   */
  decrypt(keystores: KeyStore[], password: string): Promise<Wallet>;
  
  /**
   * Save wallet to local storage (browser only)
   * @param password - Password for encryption
   * @param keyName - Local storage key name
   * @returns Boolean indicating success
   */
  save(password: string, keyName?: string): boolean;
  
  /**
   * Load wallet from local storage (browser only)
   * @param password - Password for decryption
   * @param keyName - Local storage key name
   * @returns Wallet instance
   */
  load(password: string, keyName?: string): Wallet;
}

/**
 * Wallet instance for managing multiple accounts
 */
wallet: Wallet;

// Create accounts in wallet
web3.eth.accounts.wallet.create(2); // Create 2 accounts
console.log('Wallet size:', web3.eth.accounts.wallet.length);

// Add existing account
web3.eth.accounts.wallet.add(privateKey);

// Access accounts
const firstAccount = web3.eth.accounts.wallet[0];
const accountByAddress = web3.eth.accounts.wallet['0x742C1382...'];

// Remove account
web3.eth.accounts.wallet.remove(0); // Remove by index
web3.eth.accounts.wallet.remove('0x742C1382...'); // Remove by address

// Encrypt entire wallet
const keystores = await web3.eth.accounts.wallet.encrypt('myPassword');

// Clear and decrypt wallet
web3.eth.accounts.wallet.clear();
await web3.eth.accounts.wallet.decrypt(keystores, 'myPassword');

// Browser storage (if available)
web3.eth.accounts.wallet.save('myPassword', 'myWallet');
web3.eth.accounts.wallet.load('myPassword', 'myWallet');

/**
 * Parse and validate private key format
 * @param data - Private key data
 * @param ignoreLength - Whether to ignore key length validation
 * @returns Validated private key as Uint8Array
 */
parseAndValidatePrivateKey(data: Bytes, ignoreLength?: boolean): Uint8Array;

interface Web3Account {
  address: string;
  privateKey: string;
  
  /**
   * Sign transaction with this account
   * @param transaction - Transaction to sign
   * @returns Signed transaction info
   */
  signTransaction(transaction: Transaction): Promise<SignedTransactionInfoAPI>;
  
  /**
   * Sign message with this account
   * @param data - Message to sign
   * @returns Signature result
   */
  sign(data: string): SignResult;
  
  /**
   * Encrypt this account
   * @param password - Password for encryption
   * @returns Encrypted keystore
   */
  encrypt(password: string): Promise<KeyStore>;
}

interface SignResult {
  message: string;
  messageHash: string;
  v: string;
  r: string;
  s: string;
  signature: string;
}

interface SignatureObject {
  messageHash: string;
  v: string;
  r: string;
  s: string;
  signature: string;
}

interface SignedTransactionInfoAPI {
  messageHash: string;
  v: string;
  r: string;
  s: string;
  rawTransaction: string;
  transactionHash: string;
}

interface KeyStore {
  version: number;
  id: string;
  address: string;
  crypto: {
    ciphertext: string;
    cipherparams: { iv: string };
    cipher: string;
    kdf: string;
    kdfparams: {
      dklen: number;
      salt: string;
      n: number;
      r: number;
      p: number;
    };
    mac: string;
  };
}

interface EncryptOptions {
  salt?: Uint8Array;
  iv?: Uint8Array;
  kdfparams?: {
    dklen?: number;
    salt?: string;
    n?: number;
    r?: number;
    p?: number;
  };
}

interface DecryptOptions {
  nonStrict?: boolean;
}

type Bytes = string | Uint8Array;