improve the readme

Author: Alex Vlasov

.gitignore

@@ -66,3 +66,4 @@ fastlane/Preview.html
 fastlane/screenshots
 fastlane/test_output
 API_keys.plist
+web3swiftTests/key.json

README.md

@@ -129,55 +129,63 @@ $ pod install
 Here you can see a few examples of use of our library
 ### Initializing Ethereum address
 ```bash
-let coldWalletAddress = EthereumAddress("0x6394b37Cf80A7358b38068f0CA4760ad49983a1B")!
-let constractAddress = EthereumAddress("0x45245bc59219eeaaf6cd3f382e078a461ff9de7b")!
+let coldWalletAddress = EthereumAddress("0x6394b37Cf80A7358b38068f0CA4760ad49983a1B")
+let constractAddress = EthereumAddress("0x45245bc59219eeaaf6cd3f382e078a461ff9de7b")
 ```
+Ethereum addresses are checksum checked if they are not lowercased and always length checked
 
+
+### Setting options
+```bash
+var options = Web3Options.defaultOptions()
+    // public var to: EthereumAddress? = nil - to what address transaction is aimed
+    // public var from: EthereumAddress? = nil - form what address it should be sent (either signed locally or on the node)
+    // public var gasLimit: BigUInt? = BigUInt(90000) - default gas limit
+    // public var gasPrice: BigUInt? = BigUInt(5000000000) - default gas price, quite small
+    // public var value: BigUInt? = BigUInt(0) - amount of WEI sent along the transaction
+options.gasPrice = gasPrice
+options.gasLimit = gasLimit
+options.from = EthereumAddress("0xE6877A4d8806e9A9F12eB2e8561EA6c1db19978d")
+```
+### Getting ETH balance
+```bash
+let address = EthereumAddress("0xE6877A4d8806e9A9F12eB2e8561EA6c1db19978d")!
+let web3Main = Web3.InfuraMainnetWeb3()
+let balanceResult = web3Main.eth.getBalance(address)
+guard case .success(let balance) = balanceResult else {return}
+```
 ### Getting gas price
 ```bash
 let web3Main = Web3.InfuraMainnetWeb3()
 let gasPriceResult = web3Main.eth.getGasPrice()
 guard case .success(let gasPrice) = gasPriceResult else {return}
 ```
-### Setting options
-```bash
-var options = Web3Options.defaultOptions()
-options.gasPrice = gasPrice
-options.from = EthereumAddress("0xE6877A4d8806e9A9F12eB2e8561EA6c1db19978d")!
-let parameters = [] as [AnyObject]
-```
-
-### Getting balance
+### Getting ERC20 token balance
 ```bash
-guard let bkxBalanceResult = contract.method("balanceOf", parameters: [coldWalletAddress] as [AnyObject], options: options)?.call(options: nil) else {return}
-guard case .success(let bkxBalance) = bkxBalanceResult, let bal = bkxBalance["0"] as? BigUInt else {return}
+let contractAddress = EthereumAddress("0x45245bc59219eeaaf6cd3f382e078a461ff9de7b")! // BKX token on Ethereum mainnet
+let contract = web3.contract(Web3.Utils.erc20ABI, at: contractAddress, abiVersion: 2)! // utilize precompiled ERC20 ABI for your concenience
+guard let bkxBalanceResult = contract.method("balanceOf", parameters: [coldWalletAddress] as [AnyObject], options: options)?.call(options: nil) else {return} // encode parameters for transaction
+guard case .success(let bkxBalance) = bkxBalanceResult, let bal = bkxBalance["0"] as? BigUInt else {return} // bkxBalance is [String: Any], and parameters are enumerated as "0", "1", etc in order of being returned. If returned parameter has a name in ABI, it is also duplicated
 print("BKX token balance = " + String(bal))
 ```
 
 ### Sending ETH
 ```bash
 let web3Rinkeby = Web3.InfuraRinkebyWeb3()
-
-web3Rinkeby.addKeystoreManager(bip32keystoreManager)
-options.from = bip32ks?.addresses?.first!
+web3Rinkeby.addKeystoreManager(bip32keystoreManager) // attach a keystore if you want to sign locally. Otherwise unsigned request will be sent to remote node
+options.from = bip32ks?.addresses?.first! // specify from what address you want to send it
 intermediateSend = web3Rinkeby.contract(coldWalletABI, at: coldWalletAddress, abiVersion: 2)!.method(options: options)!
 let sendResultBip32 = intermediateSend.send(password: "BANKEXFOUNDATION")
-switch sendResultBip32 {
-    case .success(let r):
-        print(r)
-    case .failure(let err):
-        print(err)
-}
 ```
 
 ### Sending ERC20
 ```bash
 var convenienceTransferOptions = Web3Options.defaultOptions()
 convenienceTransferOptions.gasPrice = gasPriceRinkeby
-let convenienceTokenTransfer = web3Rinkeby.eth.sendERC20tokensWithNaturalUnits(tokenAddress: EthereumAddress("0xa407dd0cbc9f9d20cdbd557686625e586c85b20a")!, from: (ks?.addresses?.first!)!, to: EthereumAddress("0x6394b37Cf80A7358b38068f0CA4760ad49983a1B")!, amount: "0.0001", options: convenienceTransferOptions)
-let gasEstimateResult2 = convenienceTokenTransfer!.estimateGas(options: nil)
-guard case .success(let gasEstimate2) = gasEstimateResult2 else {return}
-convenienceTransferOptions.gasLimit = gasEstimate2
+let convenienceTokenTransfer = web3Rinkeby.eth.sendERC20tokensWithNaturalUnits(tokenAddress: EthereumAddress("0xa407dd0cbc9f9d20cdbd557686625e586c85b20a")!, from: (ks?.addresses?.first!)!, to: EthereumAddress("0x6394b37Cf80A7358b38068f0CA4760ad49983a1B")!, amount: "0.0001", options: convenienceTransferOptions) // there are also convenience functions to send ETH and ERC20 under the .eth structure
+let gasEstimateResult = convenienceTokenTransfer!.estimateGas(options: nil)
+guard case .success(let gasEstimate) = gasEstimateResult else {return}
+convenienceTransferOptions.gasLimit = gasEstimate
 let convenienceTransferResult = convenienceTokenTransfer!.send(password: "BANKEXFOUNDATION", options: convenienceTransferOptions)
 switch convenienceTransferResult {
     case .success(let res):