From 9ced732cefeabec1691c84fc3105a5ecf7b347fb Mon Sep 17 00:00:00 2001 From: "Andreas M. Antonopoulos" Date: Mon, 14 May 2018 13:18:06 +0200 Subject: [PATCH] Moved web3 tutorial into main, for merge as appendix --- ...act-basic-interaction-async-await.asciidoc | 163 ++++++++++++++ web3-contract-basic-interaction.asciidoc | 206 ++++++++++++++++++ 2 files changed, 369 insertions(+) create mode 100644 web3-contract-basic-interaction-async-await.asciidoc create mode 100644 web3-contract-basic-interaction.asciidoc diff --git a/web3-contract-basic-interaction-async-await.asciidoc b/web3-contract-basic-interaction-async-await.asciidoc new file mode 100644 index 000000000..ec17e7fb6 --- /dev/null +++ b/web3-contract-basic-interaction-async-await.asciidoc @@ -0,0 +1,163 @@ +== web3.js contract basic interaction (async/await) as if they were synchronous functions + +=== Description +This script is for educational use and is based on web3@1.0.0-beta.29 web3.js version. + +It should be see as an introduction to web3.js. + +The web3.js library is a collection of modules which contain specific functionality for the Ethereum ecosystem. + +The web3.js object is an umbrella package to house all Ethereum related modules. + +This is the Ethereum compatible JavaScript API which implements the Generic JSON RPC spec. + +It run in a blocked (async/await) mode to move the reader away from the hell of the Promises as long as their version of nodejs or javascript allows it. + +The most remarkable thing about this script is that you don’t need to run your own local node to use it, because it use the https://infura.io[Infura services]. + +=== Prepare the environment +To see this script in action you should follow this simple steps. + +==== Check you have a valid npm version +---- +$ npm -v +5.6.0 +---- + +==== If you don't have already done, initialize your package +---- +$ npm init +---- + +==== Install basic dependences +---- +npm i web3 +npm i node-rest-client-promise +---- + +This will update your package.json cofiguracion file with your new dependences. + +==== Node.js script execution + +Execution example; +---- +code/web3js/./web3-contract-basic-interaction-async-await.js +---- + +== What the hell this script do? +This script try to introduce to the basic use of web3.js using async/await (less Code), as if they were synchronous functions that return values ​​directly instead of promises. + +=== web3 provider +We use web3.js Web3 object to obtain a basic web3 provider. + +---- +var web3 = new Web3(infura_host); +---- + +=== Let's do some basic interactions at web3 level +Let's get the Protocol Version. + +---- +var protocolVersion = await web3.eth.getProtocolVersion(); +---- + +Now I'm curious about the current gas price. + +---- +var gasPrice = await web3.eth.getGasPrice(); +---- + +And, Whats the last mined block in my chain? + +---- +var blockNumber = await web3.eth.getBlockNumber(); +---- + +=== Now let's dive into some basics actions with a contract +We will use the contract at; +https://kovan.etherscan.io/address/0xd0a1e359811322d97991e03f863a0c30c2cf029c#code + +First things first, let's initialize our contract address. + +---- +var our_contract_address = "0xd0A1E359811322d97991E03f863a0C30C2cF029C"; +---- + +Let's get its balance. + +---- +var balance = await web3.eth.getBalance(our_contract_address); +---- + +Now let's get its byte code. + +---- +var code = await web3.eth.getCode(our_contract_address); +---- + +=== Now we are going to deal with the contract +We prepare our environment to interact with the Etherescan explorer API. + +Let's initialize our contract url in the Etherescan explorer API for the Kovan chain. + +---- +var etherescan_url = `http://kovan.etherscan.io/api?module=contract&action=getabi&address=${our_contract_address}` +---- + +And now get a rest client to operate with. + +---- +var client = require('node-rest-client-promise').Client(); +---- + +Let's get the client response. + +---- +var etherescan_response = await client.getPromise(etherescan_url) +---- + +Now we get here our contract ABI from the client response (from the Etherescan explorer). + +---- +our_contract_abi = JSON.parse(etherescan_response.data.result); +---- + +Let's instantiate our contract object + +---- +var our_contract = await new web3.eth.Contract(our_contract_abi, our_contract_address); +---- + +Let's see our contract address. +---- +console.log(`Our Contract address: ${our_contract._address}`); +---- + +or in this other way. +---- +console.log(`Our Contract address in other way: ${our_contract.options.address}`); +---- + +Now our contract abi. +---- +console.log("Our contract abi: " + JSON.stringify(our_contract.options.jsonInterface)); +---- + +=== This is turning more interesting, let's see what's going on with our contract +Now let's get our contract total supply. + +---- +var totalSupply = await our_contract.methods.totalSupply().call(); +---- + +Now let's get our contract public variable name. + +---- +var name = await our_contract.methods.name().call(); +---- + +Now let's get our contract public variable symbol. + +---- +var symbol = await our_contract.methods.symbol().call(); +---- diff --git a/web3-contract-basic-interaction.asciidoc b/web3-contract-basic-interaction.asciidoc new file mode 100644 index 000000000..fba4ef120 --- /dev/null +++ b/web3-contract-basic-interaction.asciidoc @@ -0,0 +1,206 @@ +== web3.js Contract basic interaction in a non-blocked (async) fashion + +=== Description +This script is for educational use and is based on web3@1.0.0-beta.29 web3.js version. + +It should be see as an introduction to web3.js. + +The web3.js library is a collection of modules which contain specific functionality for the Ethereum ecosystem. + +The web3.js object is an umbrella package to house all Ethereum related modules. + +This is the Ethereum compatible JavaScript API which implements the Generic JSON RPC spec. + +It run in a non-blocked (async) mode to accommodate in many of the methods provided by web3.js + +The most remarkable thing about this script is that you don’t need to run your own local node to use it, because it use the https://infura.io[Infura services]. + +Anyway, I could adapt this script to be used with a local running node if it seems interesting. + +=== Prepare the environment +To see this script in action you should follow this simple steps. + +==== Check you have a valid npm version +---- +$ npm -v +5.6.0 +---- + +==== If you don't have already done, initialize your package +---- +$ npm init +---- + +==== Install basic dependences +---- +npm i command-line-args +npm i web3 +npm i node-rest-client-promise +---- + +This will update your package.json cofiguracion file with your new dependences. + +==== Node.js script execution + +Basic execution +---- +code/web3js/web3-contract-basic-interaction.js +---- + +Use your own Infura Token +---- +code/web3js/web3-contract-basic-interaction.js --infuraFileToken /path/to/file/with/infura_token + +or + +code/web3js/web3-contract-basic-interaction.js /path/to/file/with/infura_token +---- + +== What the hell this script do? +This script try to introduce to the basic use of web3.js + +Despite some utilities provided by the script what it really do is ... + +=== web3 provider +We use web3.js Web3 object to obtain a basic web3 provider. + +---- +var web3 = new Web3(infura_host); +---- + +=== Let's do some basic interactions at web3 level +Let's see the Protocol Version. + +---- +web3.eth.getProtocolVersion().then(function(protocolVersion) { + console.log(`Protocol Version: ${protocolVersion}`); + }) +---- + +Now I'm curious about the current gas price. + +---- +web3.eth.getGasPrice().then(function(gasPrice) { + console.log(`Gas Price: ${gasPrice}`); + }) +---- + +And, Whats the last mined block in my chain? + +---- +web3.eth.getBlockNumber().then(function(blockNumber) { + console.log(`Block Number: ${blockNumber}`); + }) +---- + +=== Now let's dive into some basics actions with a contract +We will use the contract at; +https://kovan.etherscan.io/address/0xd0a1e359811322d97991e03f863a0c30c2cf029c#code + +First things first, let's initialize our contract address. + +---- +var our_contract_address = "0xd0A1E359811322d97991E03f863a0C30C2cF029C"; +---- + +Let's see its balance. + +---- +web3.eth.getBalance(our_contract_address).then(function(balance) { + console.log(`Balance of ${our_contract_address}: ${balance}`); +}) +---- + +Now let's see its byte code. + +---- +web3.eth.getCode(our_contract_address).then(function(code) { + console.log(code); +}) +---- + +=== Now we are going to deal with the contract +We prepare our environment to interact with the Etherescan explorer API. + +Let's initialize our contract url in the Etherescan explorer API for the Kovan chain. + +---- +var etherescan_url = `http://kovan.etherscan.io/api?module=contract&action=getabi&address=${our_contract_address}` +---- + +And now get a rest client to operate with. + +---- +var client = require('node-rest-client-promise').Client(); +---- + +Let's get a client promise. + +---- +client.getPromise(etherescan_url) +---- + +And once we got a valid client promise, then we can use it. + +Now we get here our contract ABI from the client promise (from the Etherescan explorer). +---- +.then((client_promise) => { + our_contract_abi = JSON.parse(client_promise.data.result); +---- + +And now we create our contract object as a promise to consume later. +---- + return new Promise((resolve, reject) => { + var our_contract = new web3.eth.Contract(our_contract_abi, our_contract_address); + try { + // If all goes well + resolve(our_contract); + } catch (ex) { + // If something goes wrong + reject(ex); + } + }); +}) +---- + +If our contract promise return well let's consume it. +---- +.then((our_contract) => { +---- + +Let's see our contract address. +---- +console.log(`Our Contract address: ${our_contract._address}`); +---- + +or in this other way. +---- +console.log(`Our Contract address in other way: ${our_contract.options.address}`); +---- + +Now our contract abi. +---- +console.log("Our contract abi: " + JSON.stringify(our_contract.options.jsonInterface)); +---- + +=== This is turning more interesting, let's see what's going on with our contract +Now let's see our contract total supply in a callback fashion; + +---- +our_contract.methods.totalSupply().call(function(err, totalSupply) { + if (!err) { + console.log(`Total Supply with a callback: ${totalSupply}`); + } else { + console.log(err); + } +}); +---- + +Or you can use the returned Promise instead of passing in the callback; +---- +our_contract.methods.totalSupply().call().then(function(totalSupply){ + console.log(`Total Supply with a promise: ${totalSupply}`); +}).catch(function(err) { + console.log(err); +}); +----