or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-web3-eth-personal

Web3 module to interact with the Ethereum blockchain accounts stored in the node.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/web3-eth-personal@4.0.x

To install, run

npx @tessl/cli install tessl/npm-web3-eth-personal@4.0.0

index.mddocs/

Web3 Eth Personal

Web3 Eth Personal provides a comprehensive interface for interacting with Ethereum node accounts through the personal API. It enables management of accounts stored directly on Ethereum nodes, including creation, unlocking, transaction signing, and cryptographic operations.

Security Warning: Many functions send sensitive information like passwords. Never call these functions over unsecured Websocket or HTTP connections, as passwords will be sent in plain text.

Package Information

  • Package Name: web3-eth-personal
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install web3-eth-personal

Core Imports

import Personal from "web3-eth-personal";

Named import:

import { Personal } from "web3-eth-personal";

CommonJS:

const Personal = require("web3-eth-personal");

Basic Usage

import Personal from "web3-eth-personal";

// Initialize with provider
const personal = new Personal("http://localhost:8545");

// List accounts controlled by the node
const accounts = await personal.getAccounts();
console.log(accounts);

// Create a new account
const newAccount = await personal.newAccount("password123");
console.log(`New account: ${newAccount}`);

// Unlock account for transactions
await personal.unlockAccount(accounts[0], "password123", 600);

// Send a transaction through the management API
const txHash = await personal.sendTransaction({
  from: accounts[0],
  to: "0x3535353535353535353535353535353535353535",
  value: "1000000000000000000",
  gas: "21000",
}, "password123");

Architecture

Web3 Eth Personal is built around:

  • Personal Class: Main interface extending Web3Context<EthPersonalAPI> providing all account management methods
  • RPC Wrappers: Internal functions that handle parameter validation and formatting before making RPC calls
  • Security Model: Password-based operations with warnings about plaintext transmission
  • Provider Integration: Uses web3 provider system for Ethereum node communication

Capabilities

Account Management

Methods for managing accounts stored on the Ethereum node.

/**
 * Returns a list of accounts the node controls
 * @returns Array of addresses controlled by the node
 */
getAccounts(): Promise<Address[]>;

/**
 * Creates a new account and returns its address
 * @param password - Password to encrypt the account with
 * @returns Address of the new account
 */
newAccount(password: string): Promise<Address>;

/**
 * Unlocks an account for a given duration
 * @param address - Address of the account to unlock
 * @param password - Password of the account to unlock
 * @param unlockDuration - Duration in seconds to unlock the account for
 * @returns Success status
 */
unlockAccount(address: Address, password: string, unlockDuration: number): Promise<boolean>;

/**
 * Locks the given account
 * @param address - Address of the account to lock
 * @returns Success status
 */
lockAccount(address: Address): Promise<boolean>;

/**
 * Imports the given private key into the key store, encrypting it with the passphrase
 * @param keyData - Unencrypted private key (hex string)
 * @param passphrase - Password of the account
 * @returns Address of the new account
 */
importRawKey(keyData: HexString, passphrase: string): Promise<Address>;

Transaction Operations

Methods for sending and signing transactions through the management API.

/**
 * Sends a transaction over the management API
 * @param tx - Transaction options
 * @param passphrase - Passphrase of the current account
 * @returns Transaction hash
 */
sendTransaction(tx: Transaction, passphrase: string): Promise<HexString>;

/**
 * Signs a transaction. Account needs to be unlocked.
 * @param tx - Transaction data to sign
 * @param passphrase - Password of the from account, to sign the transaction with
 * @returns RLP encoded transaction with raw and tx properties
 */
signTransaction(tx: Transaction, passphrase: string): Promise<SignedTransactionInfoAPI>;

Cryptographic Operations

Methods for signing arbitrary data and recovering signers.

/**
 * Calculates an Ethereum specific signature with message prefix
 * sign(keccak256("\x19Ethereum Signed Message:\n" + dataToSign.length + dataToSign))
 * @param data - Data to sign
 * @param address - Address to sign with
 * @param passphrase - Passphrase to decrypt the account with
 * @returns Ethereum specific signature
 */
sign(data: HexString, address: Address, passphrase: string): Promise<HexString>;

/**
 * Recovers the account that signed the data
 * @param signedData - Data that was signed (will be converted using utf8ToHex if string)
 * @param signature - The signature
 * @returns Address of the account that signed the data
 */
ecRecover(signedData: HexString, signature: string): Promise<Address>;

Types

// Core class extending Web3Context
class Personal extends Web3Context<EthPersonalAPI> {
  constructor(provider?: string | SupportedProviders<EthPersonalAPI>);
}

// Key types from web3-types
type Address = string;
type HexString = string;

interface Transaction {
  from?: Address;
  to?: Address;
  value?: string;
  gas?: string;
  gasPrice?: string;
  data?: HexString;
  nonce?: number;
  maxFeePerGas?: string;
  maxPriorityFeePerGas?: string;
}

interface SignedTransactionInfoAPI {
  raw: HexString;
  tx: {
    type: HexString;
    nonce: HexString;
    gasPrice?: HexString;
    maxPriorityFeePerGas?: HexString;
    maxFeePerGas?: HexString;
    gas: HexString;
    value: HexString;
    input: HexString;
    v: HexString;
    r: HexString;
    s: HexString;
    to?: Address;
    hash: HexString;
  };
}

Usage Examples

Account Creation and Management

import Personal from "web3-eth-personal";

const personal = new Personal("http://localhost:8545");

// Create a new account
const newAccount = await personal.newAccount("securePassword123");
console.log(`Created account: ${newAccount}`);

// Import an existing private key
const importedAccount = await personal.importRawKey(
  "abe40cb08850da918ee951b237fa87946499b2d8643e4aa12b0610b050c731f6",
  "importPassword123"
);
console.log(`Imported account: ${importedAccount}`);

// List all accounts
const accounts = await personal.getAccounts();
console.log("Available accounts:", accounts);

// Unlock account for 10 minutes (600 seconds)
await personal.unlockAccount(accounts[0], "securePassword123", 600);
console.log("Account unlocked successfully");

Transaction Sending

import Personal from "web3-eth-personal";

const personal = new Personal("http://localhost:8545");

// Send a transaction through the management API
const txHash = await personal.sendTransaction({
  from: "0x0d4aa485ecbc499c70860feb7e5aaeaf5fd8172e",
  to: "0x3535353535353535353535353535353535353535",
  value: "1000000000000000000", // 1 ETH in Wei
  gas: "21000",
  gasPrice: "20000000000"
}, "accountPassword");

console.log(`Transaction sent: ${txHash}`);

// Sign a transaction without sending
const signedTx = await personal.signTransaction({
  from: "0x0d4aa485ecbc499c70860feb7e5aaeaf5fd8172e",
  to: "0x3535353535353535353535353535353535353535",
  value: "1000000000000000000",
  gas: "21000",
  gasPrice: "20000000000"
}, "accountPassword");

console.log("Signed transaction:", signedTx);
// Use signedTx.raw to send via web3.eth.sendSignedTransaction

Message Signing and Recovery

import Personal from "web3-eth-personal";

const personal = new Personal("http://localhost:8545");

// Sign a message
const message = "Hello, Web3!";
const account = "0x0d4aa485ecbc499c70860feb7e5aaeaf5fd8172e";
const signature = await personal.sign(message, account, "accountPassword");
console.log(`Signature: ${signature}`);

// Recover the signer
const recoveredAddress = await personal.ecRecover(message, signature);
console.log(`Recovered address: ${recoveredAddress}`);
console.log(`Addresses match: ${recoveredAddress.toLowerCase() === account.toLowerCase()}`);

Security Considerations

  • Never use over unsecured connections: All password-based operations transmit passwords in plain text
  • Development and testing only: Primarily intended for development environments and private networks
  • Account security: Node-controlled accounts are stored on the Ethereum node, not locally
  • Unlock duration: Keep unlock durations as short as possible to minimize security exposure
  • Production usage: Requires secure connection protocols (HTTPS/WSS) if used in production

Error Handling

All methods include input validation using web3-validator and may throw validation errors for invalid parameters:

try {
  await personal.newAccount(""); // Invalid empty password
} catch (error) {
  console.error("Validation error:", error.message);
}

try {
  await personal.unlockAccount("invalid-address", "password", 600);
} catch (error) {
  console.error("Invalid address format:", error.message);
}