Added basic documentation.

2016-07-16 00:34:40 -04:00 · 2016-07-16 00:34:40 -04:00 · 6b18675274
commit 6b18675274
parent 907e65a359
1 changed files with 147 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,147 @@
+ethers-wallet
+=============
+
+Complete Ethereum wallet implementation in JavaScript.
+
+Features
+- Keep your private keys in the browser
+- Small (~155kb compressed; hopefully under 100kb soon)
+- MIT licensed (with a few exceptions, 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.*
+
+
+Wallet API
+----------
+
+```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 address
+console.log(wallet.address)
+/// "0x7357589f8e367c2C31F51242fB77B350A11830F3"
+
+// ICAP Addresses 
+Wallet.getIcapAddress(wallet.address)
+/// "XE39DH16QOXYG5JY9BYY6JGZW8ORUPBX71V"
+
+Wallet.getIcapAddress("XE39DH16QOXYG5JY9BYY6JGZW8ORUPBX71V")
+/// "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')
+/// Error: invalid checksum address
+
+// Sign transactions
+wallet.sign({
+    to: "0x06B5955A67D827CDF91823E3bB8F069e6c89c1D6",
+    gasLimit: 3000000,
+    gasPrice: "0x1000",
+    value: "0x1000"
+})
+
+```
+
+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 ether with a state-changing call, or custom gasLimit or gasPrice
+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);
+});
+
+```
+
+
+License
+-------
+
+MIT Licensed, with the exceptions:
+- The Solidity encoder/decoder (LGPL)
+- RLP (MPL-2.0)
+
+We are working on our own implementations so we can move off of them and have a completely MIT licensed implementation in the near future.
+
+Stay tuned!