0
# Web3 Eth Personal
1

2
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.
3

4
**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.
5

6
## Package Information
7

8
- **Package Name**: web3-eth-personal
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install web3-eth-personal`
12

13
## Core Imports
14

15
```typescript
16
import Personal from "web3-eth-personal";
17
```
18

19
Named import:
20

21
```typescript
22
import { Personal } from "web3-eth-personal";
23
```
24

25
CommonJS:
26

27
```javascript
28
const Personal = require("web3-eth-personal");
29
```
30

31
## Basic Usage
32

33
```typescript
34
import Personal from "web3-eth-personal";
35

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

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

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

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

50
// Send a transaction through the management API
51
const txHash = await personal.sendTransaction({
52
  from: accounts[0],
53
  to: "0x3535353535353535353535353535353535353535",
54
  value: "1000000000000000000",
55
  gas: "21000",
56
}, "password123");
57
```
58

59
## Architecture
60

61
Web3 Eth Personal is built around:
62

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

68
## Capabilities
69

70
### Account Management
71

72
Methods for managing accounts stored on the Ethereum node.
73

74
```typescript { .api }
75
/**
76
 * Returns a list of accounts the node controls
77
 * @returns Array of addresses controlled by the node
78
 */
79
getAccounts(): Promise<Address[]>;
80

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

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

97
/**
98
 * Locks the given account
99
 * @param address - Address of the account to lock
100
 * @returns Success status
101
 */
102
lockAccount(address: Address): Promise<boolean>;
103

104
/**
105
 * Imports the given private key into the key store, encrypting it with the passphrase
106
 * @param keyData - Unencrypted private key (hex string)
107
 * @param passphrase - Password of the account
108
 * @returns Address of the new account
109
 */
110
importRawKey(keyData: HexString, passphrase: string): Promise<Address>;
111
```
112

113
### Transaction Operations
114

115
Methods for sending and signing transactions through the management API.
116

117
```typescript { .api }
118
/**
119
 * Sends a transaction over the management API
120
 * @param tx - Transaction options
121
 * @param passphrase - Passphrase of the current account
122
 * @returns Transaction hash
123
 */
124
sendTransaction(tx: Transaction, passphrase: string): Promise<HexString>;
125

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

135
### Cryptographic Operations
136

137
Methods for signing arbitrary data and recovering signers.
138

139
```typescript { .api }
140
/**
141
 * Calculates an Ethereum specific signature with message prefix
142
 * sign(keccak256("\x19Ethereum Signed Message:\n" + dataToSign.length + dataToSign))
143
 * @param data - Data to sign
144
 * @param address - Address to sign with
145
 * @param passphrase - Passphrase to decrypt the account with
146
 * @returns Ethereum specific signature
147
 */
148
sign(data: HexString, address: Address, passphrase: string): Promise<HexString>;
149

150
/**
151
 * Recovers the account that signed the data
152
 * @param signedData - Data that was signed (will be converted using utf8ToHex if string)
153
 * @param signature - The signature
154
 * @returns Address of the account that signed the data
155
 */
156
ecRecover(signedData: HexString, signature: string): Promise<Address>;
157
```
158

159
## Types
160

161
```typescript { .api }
162
// Core class extending Web3Context
163
class Personal extends Web3Context<EthPersonalAPI> {
164
  constructor(provider?: string | SupportedProviders<EthPersonalAPI>);
165
}
166

167
// Key types from web3-types
168
type Address = string;
169
type HexString = string;
170

171
interface Transaction {
172
  from?: Address;
173
  to?: Address;
174
  value?: string;
175
  gas?: string;
176
  gasPrice?: string;
177
  data?: HexString;
178
  nonce?: number;
179
  maxFeePerGas?: string;
180
  maxPriorityFeePerGas?: string;
181
}
182

183
interface SignedTransactionInfoAPI {
184
  raw: HexString;
185
  tx: {
186
    type: HexString;
187
    nonce: HexString;
188
    gasPrice?: HexString;
189
    maxPriorityFeePerGas?: HexString;
190
    maxFeePerGas?: HexString;
191
    gas: HexString;
192
    value: HexString;
193
    input: HexString;
194
    v: HexString;
195
    r: HexString;
196
    s: HexString;
197
    to?: Address;
198
    hash: HexString;
199
  };
200
}
201
```
202

203
## Usage Examples
204

205
### Account Creation and Management
206

207
```typescript
208
import Personal from "web3-eth-personal";
209

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

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

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

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

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

232
### Transaction Sending
233

234
```typescript
235
import Personal from "web3-eth-personal";
236

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

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

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

250
// Sign a transaction without sending
251
const signedTx = await personal.signTransaction({
252
  from: "0x0d4aa485ecbc499c70860feb7e5aaeaf5fd8172e",
253
  to: "0x3535353535353535353535353535353535353535",
254
  value: "1000000000000000000",
255
  gas: "21000",
256
  gasPrice: "20000000000"
257
}, "accountPassword");
258

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

263
### Message Signing and Recovery
264

265
```typescript
266
import Personal from "web3-eth-personal";
267

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

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

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

282
## Security Considerations
283

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

290
## Error Handling
291

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

294
```typescript
295
try {
296
  await personal.newAccount(""); // Invalid empty password
297
} catch (error) {
298
  console.error("Validation error:", error.message);
299
}
300

301
try {
302
  await personal.unlockAccount("invalid-address", "password", 600);
303
} catch (error) {
304
  console.error("Invalid address format:", error.message);
305
}
306
```