293 lines
9.5 KiB
Markdown
293 lines
9.5 KiB
Markdown
ethers-wallet
|
|
=============
|
|
|
|
Complete Ethereum wallet implementation in JavaScript.
|
|
|
|
Features
|
|
- Keep your private keys in the browser
|
|
- Import and export JSON wallets (geth and crowdsale)
|
|
- Generate JavaScript bindings for any contract ABI
|
|
- Small (~100kb compressed; 290kb uncompressed)
|
|
- MIT licensed (with one exception, which we are migrating off of; see below)
|
|
|
|
**NOTE: This is still very beta; please only use it on the testnet for now, or with VERY small amounts of ether on the livenet that you are willing to lose due to bugs.**
|
|
|
|
|
|
API
|
|
---
|
|
|
|
|
|
### Wallet API
|
|
|
|
An *Ethereum* wallet wraps a cryptographic private key, which is used to sign transactions and control the ether located at the wallet's address. These transactions can then be broadcast to the *Ethereum* network.
|
|
|
|
```javascript
|
|
// A private key can be specified as a 32 byte buffer or hexidecimal string
|
|
var privateKey = new Wallet.utils.Buffer([
|
|
0x31, 0x41, 0x59, 0x26, 0x53, 0x58, 0x97, 0x93,
|
|
0x23, 0x84, 0x62, 0x64, 0x33, 0x83, 0x27, 0x95,
|
|
0x02, 0x88, 0x41, 0x97, 0x16, 0x93, 0x99, 0x37,
|
|
0x51, 0x05, 0x82, 0x09, 0x74, 0x94, 0x45, 0x92
|
|
])
|
|
|
|
// or equivalently:
|
|
var privateKey = '0x3141592653589793238462643383279502884197169399375105820974944592'
|
|
|
|
// Create a wallet object
|
|
var wallet = new Wallet(privateKey)
|
|
|
|
// Wallet privateKey
|
|
console.log(wallet.privateKey)
|
|
/// "0x3141592653589793238462643383279502884197169399375105820974944592"
|
|
|
|
// Wallet address
|
|
console.log(wallet.address)
|
|
/// "0x7357589f8e367c2C31F51242fB77B350A11830F3"
|
|
|
|
// Sign transactions
|
|
wallet.sign({
|
|
to: "0x06B5955A67D827CDF91823E3bB8F069e6c89c1D6",
|
|
gasLimit: 3000000,
|
|
gasPrice: "0x1000",
|
|
value: "0x1000"
|
|
})
|
|
```
|
|
|
|
|
|
### Converting addresses
|
|
|
|
Addresses come in various forms, and it is often useful to convert between them. You can pass any valid address into any function, and the library will convert it internally as needed. The address types are:
|
|
- **hexidecimal** - 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef (all letters must be either lower case or uppercase; no mixed case, as this implies a checksum address)
|
|
- **ICAP** - XE49Q0EPSW7XTS5PRIE9226HRPOO69XRVU7 (uses the International Bank Account Number format)
|
|
- **checksummed** - 0xDeaDbeefdEAdbeefdEadbEEFdeadbeEFdEaDbeeF (notice the case is adjusted encoding checkum information)
|
|
|
|
```javascript
|
|
// ICAP Addresses
|
|
Wallet.getIcapAddress(wallet.address)
|
|
/// "XE39DH16QOXYG5JY9BYY6JGZW8ORUPBX71V"
|
|
|
|
// Get checksummed address (from ICAP)
|
|
Wallet.getAddress("XE39DH16QOXYG5JY9BYY6JGZW8ORUPBX71V")
|
|
/// "0x7357589f8e367c2C31F51242fB77B350A11830F3"
|
|
|
|
// Get checksummed addresses (from unchecksumed)
|
|
Wallet.getAddress("0x7357589f8e367c2c31f51242fb77b350a11830f3")
|
|
/// "0x7357589f8e367c2C31F51242fB77B350A11830F3"
|
|
|
|
// Detect address checksum errors (notice the last "f" should be lowercase)
|
|
Wallet.getAddress('0x7357589f8e367c2c31f51242fb77b350a11830F3')
|
|
/// throws Error: invalid checksum address
|
|
```
|
|
|
|
|
|
### Crowdsale JSON Wallets
|
|
|
|
During the crowdsale, the Ethereum Project sold ether by generating *crowdsale JSON wallet*. These functions allow you to decrypt those files and retreive the private key.
|
|
|
|
```javascript
|
|
|
|
// See the test-wallets directory samples (the variable should be a string)
|
|
var json = "... see the test-wallets directory for samples ...";
|
|
|
|
// Detect crowdsale JSON wallets
|
|
Wallet.isCrowdsaleWallet(json)
|
|
|
|
// Get a wallet from a crowdsale JSON wallet
|
|
var wallet = Wallet.decryptCrowdsaleWallet(json, password);
|
|
console.log(wallet.address)
|
|
console.log(wallet.privateKey)
|
|
```
|
|
|
|
|
|
### Secret Storage JSON Wallet
|
|
|
|
This API allows you to decrypt and encrypt the [Secret Storage](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) format used by *Geth* and many other wallet platforms (such as *ethers.io*).
|
|
|
|
The Secret Storage JSON Wallet format uses an algorithm called *scrypt*, which is intentionally CPU-intensive, which ensures that an attacker would need to tie up considerable resources to attempt to brute-force guess your password. It aslo means it may take some time (10-30 seconds) to decrypt or encrypt a wallet. So, these API calls use a callback to provide progress feedback as well as the opportunity to cancel the process.
|
|
|
|
The callback should look like `function(error, result, progress)` where progress is a Number between 0 and 1 (inclusive) and if the function returns `true`, then the process will be cancelled, calling the callback once more with `callback(new Error('cancelled')`.
|
|
|
|
#### Wallet.decrypt(json, password, callback);
|
|
|
|
```javascript
|
|
|
|
// See the test-wallets directory samples (the variable should be a string)
|
|
var json = "... see the test-wallets directory for samples ...";
|
|
|
|
// Decrypt a Secret Storage JSON wallet
|
|
var shouldCancelDecrypt = false;
|
|
Wallet.decrypt(json, password, function(error, wallet, progress) {
|
|
if (error) {
|
|
if (error.message === 'invalid password') {
|
|
// Wrong password
|
|
} else if (error.message === 'cancelled') {
|
|
// The decryption was cancelled
|
|
} else {
|
|
}
|
|
|
|
} else if (wallet) {
|
|
// The wallet was successfully decrypted
|
|
|
|
} else {
|
|
// The wallet is still being decrypted
|
|
console.log('The wallet is ' + parseInt(100 * progress) + '% decrypted');
|
|
}
|
|
|
|
// Optionally return true to stop this decryption; this callback will get
|
|
// called once more with callback(new Error("cancelled"))
|
|
return shouldCancelDecrypt;
|
|
});
|
|
```
|
|
|
|
#### Wallet.prototype.encrypt(password[, options], callback);
|
|
|
|
```javascript
|
|
|
|
// Encrypt a wallet into a Secret Storage JSON Wallet (all options are optional)
|
|
var bytes16 = '0xdeadbeef1deadbeef2deadbeef301234';
|
|
var options = {
|
|
salt: bytes16, // hex string or Buffer, any length
|
|
iv: bytes16, // hex string or Buffer, 16 bytes
|
|
uuid: bytes16, // hex string or Buffer, 16 bytes
|
|
scrypt: {
|
|
N: (1 << 17), // Number, power of 2 greater than 2
|
|
p: 8, // Number
|
|
r: 1 // Number
|
|
}
|
|
}
|
|
|
|
var wallet = new Wallet(privateKey);
|
|
wallet.encrypt(password, options, function(error, json, progress) {
|
|
if (error) {
|
|
if (error.message === 'invalid password') {
|
|
// Wrong password
|
|
}
|
|
|
|
} else if (json) {
|
|
// The wallet was successfully encrypted
|
|
|
|
} else {
|
|
// The wallet is still being encrypted
|
|
console.log('The wallet is ' + parseInt(100 * progress) + '% encrypted');
|
|
|
|
}
|
|
|
|
// Optionally return true to stop this decryption; this callback will get
|
|
// called once more with callback(new Error("cancelled"))
|
|
return shouldCancelDecrypt;
|
|
});
|
|
```
|
|
|
|
|
|
Contract API
|
|
------------
|
|
|
|
```javascript
|
|
// Load a normal web3 object (you need a local RPC-enabled ethereum node running)
|
|
var web3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545'))
|
|
|
|
// Create your wallet
|
|
var wallet = new Wallet('0x3141592653589793238462643383279502884197169399375105820974944592')
|
|
|
|
console.log(wallet.address);
|
|
/// "0x7357589f8e367c2C31F51242fB77B350A11830F3"
|
|
|
|
// Find an existing contract address and ABI
|
|
// See: https://gist.github.com/ricmoo/e78709e075ff8082a86c875ac062c3c3
|
|
var simpleStorageAddress = '0xdfaf84077cF4bCECA4F79d167F47041Ed3006D5b'
|
|
var simpleStorageAbi = [
|
|
{
|
|
"constant":true,
|
|
"inputs":[],
|
|
"name":"getValue",
|
|
"outputs":[{"name":"","type":"string"}],
|
|
"type":"function"
|
|
}, {
|
|
"constant":false,
|
|
"inputs":[{"name":"value","type":"string"}],
|
|
"name":"setValue",
|
|
"outputs":[],
|
|
"type":"function"
|
|
}, {
|
|
"anonymous":false,
|
|
"inputs":[
|
|
{"indexed":false,"name":"oldValue","type":"string"},
|
|
{"indexed":false,"name":"newValue","type":"string"}
|
|
],
|
|
"name":"valueChanged",
|
|
"type":"event"
|
|
}
|
|
];
|
|
|
|
// Get the contract
|
|
var contract = wallet.getContract(web3, simpleStorageAddress, simpleStorageAbi)
|
|
|
|
// Set up events
|
|
contract.onvaluechanged = function(oldValue, newValue) {
|
|
console.log('Value Changed from "' + oldValue + '" to "' + newValue + '".')
|
|
}
|
|
|
|
// Call constant methods, which don't alter state (free).
|
|
// Returns a promise.
|
|
contract.getValue().then(function(value) {
|
|
console.log('Value is "' + value + '".')
|
|
})
|
|
|
|
// Call state-changing methods (which will cost you ether, so use testnet to test!)
|
|
// Returns a promise.
|
|
contract.setValue("Hello World").then(function(txid) {
|
|
console.log('txid: ' + txid);
|
|
});
|
|
|
|
// Include custom parameters with a state-changing call
|
|
var options = {
|
|
gasPrice: 1000 // in wei (default: from network)
|
|
gasLimit: 3000000, // is gas (default: 3000000)
|
|
value: 1000 // in wei (default: 0)
|
|
}
|
|
contract.setValue("Hello World", options).then(function(txid) {
|
|
console.log('txid: ' + txid);
|
|
});
|
|
|
|
```
|
|
|
|
|
|
Testing
|
|
-------
|
|
|
|
A lot of the test cases are performed by comparing against known working implementations of many of the features of this library. To run the test suite, you must use `npm install` (without the `--production` flag, which would skip the development dependencies.)
|
|
|
|
To run the test suite,
|
|
|
|
```
|
|
/Users/ethers> npm test
|
|
|
|
> ethers-wallet@0.0.1 test /Users/ricmoo/Development/ethers/ethers-wallet
|
|
> nodeunit test.js
|
|
|
|
|
|
test.js
|
|
+ testSecretStorage
|
|
+ testCoderParams
|
|
+ testContract
|
|
+ testChecksumAddress
|
|
+ testIcapAddress
|
|
+ testAddress
|
|
+ testTransaction
|
|
|
|
OK: 85128 assertions (66646ms)
|
|
```
|
|
|
|
There are also some test JSON wallets available in the [test-wallets](https://github.com/ethers-io/ethers-wallet/tree/master/test-wallets) directory.
|
|
|
|
|
|
License
|
|
-------
|
|
|
|
MIT Licensed, with the exceptions:
|
|
- RLP (MPL-2.0)
|
|
|
|
We are working on our own implementations and will have the library 100% MIT in the near future.
|
|
|
|
Stay tuned!
|