1051 lines
92 KiB
HTML
1051 lines
92 KiB
HTML
|
||
|
||
<!DOCTYPE html>
|
||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||
<head>
|
||
<meta charset="utf-8">
|
||
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<title>Providers API — ethers.js 3.0.0 documentation</title>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="_static/css/ethers.css" type="text/css" />
|
||
|
||
<link rel="stylesheet" href="_static/css/ethers.css" type="text/css" />
|
||
|
||
|
||
|
||
<link rel="index" title="Index"
|
||
href="genindex.html"/>
|
||
<link rel="search" title="Search" href="search.html"/>
|
||
<link rel="top" title="ethers.js 3.0.0 documentation" href="index.html"/>
|
||
<link rel="up" title="Application Programming Interface (API)" href="api.html"/>
|
||
<link rel="next" title="Contracts" href="api-contract.html"/>
|
||
<link rel="prev" title="Wallets" href="api-wallet.html"/>
|
||
|
||
|
||
<script src="_static/js/modernizr.min.js"></script>
|
||
|
||
</head>
|
||
|
||
<body class="wy-body-for-nav" role="document">
|
||
|
||
|
||
<div class="wy-grid-for-nav">
|
||
|
||
|
||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||
<div class="wy-side-scroll">
|
||
<div class="wy-side-nav-search">
|
||
|
||
|
||
|
||
<a href="index.html" class="icon icon-home"> ethers.js
|
||
|
||
|
||
|
||
</a>
|
||
|
||
|
||
|
||
|
||
<div class="version">
|
||
3.0
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<div role="search">
|
||
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
||
<input type="text" name="q" placeholder="Search docs" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
|
||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<p class="caption"><span class="caption-text">Developer Documentation</span></p>
|
||
<ul class="current">
|
||
<li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting Started</a></li>
|
||
<li class="toctree-l1 current"><a class="reference internal" href="api.html">Application Programming Interface (API)</a><ul class="current">
|
||
<li class="toctree-l2"><a class="reference internal" href="api-wallet.html">Wallets</a></li>
|
||
<li class="toctree-l2 current"><a class="current reference internal" href="#">Providers API</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="#connecting-to-ethereum">Connecting to Ethereum</a><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="#examples"><em>Examples</em></a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#prototype">Prototype</a><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="#provider">Provider</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#fallbackprovider-inherits-from-provider">FallbackProvider <sup>( inherits from Provider )</sup></a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#jsonrpcprovider-inherits-from-provider">JsonRpcProvider <sup>( inherits from Provider )</sup></a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#etherscanprovider-inherits-from-provider">EtherscanProvider <sup>( inherits from Provider )</sup></a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#infuraprovider-inherits-from-jsonrpcprovider">InfuraProvider <sup>( inherits from JsonRpcProvider )</sup></a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#web3provider-inherits-from-jsonrpcprovider">Web3Provider <sup>( inherits from JsonRpcProvider )</sup></a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#account-actions">Account Actions</a><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="#id2"><em>Examples</em></a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#blockchain-status">Blockchain Status</a><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="#id3"><em>Examples</em></a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#ethereum-name-resolution">Ethereum Name Resolution</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#contract-execution">Contract Execution</a><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="#id4"><em>Examples</em></a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#contract-state">Contract State</a><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="#id5"><em>Examples</em></a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#events">Events</a><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="#event-types">Event Types</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#waiting-for-transactions">Waiting for Transactions</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#id6"><em>Examples</em></a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#objects">Objects</a><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="#block-tag">Block Tag</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#block-responses">Block Responses</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#transaction-requests">Transaction Requests</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#transaction-response">Transaction Response</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#transaction-receipts">Transaction Receipts</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#filters">Filters</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#provider-specific-extra-api-calls">Provider Specific Extra API Calls</a><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="#etherscan">Etherscan</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="#web3provider">Web3Provider</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api-contract.html">Contracts</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api-utils.html">Utilities</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="api-advanced.html">Low-Level API</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="cookbook.html">Cookbook</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="notes.html">Notes</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
|
||
</ul>
|
||
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</nav>
|
||
|
||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||
|
||
|
||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||
|
||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||
<a href="index.html">ethers.js</a>
|
||
|
||
</nav>
|
||
|
||
|
||
|
||
<div class="wy-nav-content">
|
||
<div class="rst-content">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||
|
||
<ul class="wy-breadcrumbs">
|
||
|
||
<li><a href="index.html">Docs</a> »</li>
|
||
|
||
<li><a href="api.html">Application Programming Interface (API)</a> »</li>
|
||
|
||
<li>Providers API</li>
|
||
|
||
|
||
<li class="wy-breadcrumbs-aside">
|
||
|
||
|
||
<a href="_sources/api-providers.rst.txt" rel="nofollow"> View page source</a>
|
||
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
|
||
<hr/>
|
||
</div>
|
||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||
<div itemprop="articleBody">
|
||
|
||
<div class="section" id="providers-api">
|
||
<span id="api-provider"></span><h1>Providers API<a class="headerlink" href="#providers-api" title="Permalink to this headline">¶</a></h1>
|
||
<p>A Provider abstracts a connection to the Ethereum blockchain, for issuing queries
|
||
and sending state changing transactions.</p>
|
||
<p>Unlike the Web3 provider, there is no concept of accounts or signing entities in
|
||
an Ethers Provider. It is simply a connection to the network, and cannot unlock
|
||
accounts or sign and is unaware of your Ethereum addresses.</p>
|
||
<p>To manage state changing operations, you must use a <a class="reference internal" href="api-wallet.html#api-wallet"><span class="std std-ref">Wallet</span></a>
|
||
to sign transactions. If you pass a wallet in as a signer to
|
||
a <a class="reference internal" href="api-contract.html#api-contract"><span class="std std-ref">Contract</span></a>, this is managed for you by the contract.</p>
|
||
<hr class="docutils" />
|
||
<div class="section" id="connecting-to-ethereum">
|
||
<h2>Connecting to Ethereum<a class="headerlink" href="#connecting-to-ethereum" title="Permalink to this headline">¶</a></h2>
|
||
<p>There are several ways to connect to the Ethereum blockchain:</p>
|
||
<dl class="docutils">
|
||
<dt>new <sup>ethers . providers</sup> . EtherscanProvider( [ network ] [ , apiToken ] )</dt>
|
||
<dd><p class="first">Connect to the <a class="reference external" href="https://etherscan.io/apis">Etherscan</a> blockchain <a class="reference external" href="https://etherscan.io/apis">web service API</a>.</p>
|
||
<p class="last"><strong>default:</strong> <em>network</em>=’homestead’, <em>apiToken</em>=null</p>
|
||
</dd>
|
||
<dt>new <sup>ethers . providers</sup> . JsonRpcProvider( [ url ] [ , network ] )</dt>
|
||
<dd><p class="first">Connect to the <a class="reference external" href="https://github.com/ethereum/wiki/wiki/JSON-RPC">JSON-RPC API</a> <em>url</em> of an Ethereum node, such as <a class="reference external" href="https://ethcore.io/parity.html">Parity</a> or <a class="reference external" href="https://geth.ethereum.org">Geth</a>.</p>
|
||
<p class="last"><strong>default:</strong> <em>url</em>=”<a class="reference external" href="http://localhost:8545/">http://localhost:8545/</a>”, <em>network</em>=’homestead’</p>
|
||
</dd>
|
||
<dt>new <sup>ethers . providers</sup> . InfuraProvider( [ network ] [ , apiAccessToken ] )</dt>
|
||
<dd><p class="first">Connect to the <a class="reference external" href="https://infura.io">INFURA</a> hosted network of Ethereum nodes.</p>
|
||
<p class="last"><strong>default:</strong> <em>network</em>=’homestead’, <em>apiAccessToken</em>=null</p>
|
||
</dd>
|
||
<dt>new <sup>ethers . providers</sup> . Web3Provider( web3Provider [ , network ] )</dt>
|
||
<dd><p class="first">Connect to an existing Web3 provider (e.g. <cite>web3Instance.currentProvider</cite>).</p>
|
||
<p class="last"><strong>default:</strong> <em>network</em>=’homestead’</p>
|
||
</dd>
|
||
<dt>new <sup>ethers . providers</sup> . FallbackProvider( providers )</dt>
|
||
<dd>Improves reliability by attempting each provider in turn, falling back to the
|
||
next in the list if an error was encountered.</dd>
|
||
<dt><sup>ethers . providers</sup> . getDefaultProvider( [ network ] )</dt>
|
||
<dd><p class="first">This automatically creates a FallbackProvider backed by INFURA and Etherscan; recommended</p>
|
||
<p class="last"><strong>default:</strong> <em>network</em>=’homestead’</p>
|
||
</dd>
|
||
</dl>
|
||
<div class="section" id="examples">
|
||
<h3><em>Examples</em><a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">providers</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="s1">'ethers'</span><span class="p">)</span><span class="o">.</span><span class="n">providers</span><span class="p">;</span>
|
||
|
||
<span class="o">//</span> <span class="n">Connect</span> <span class="n">to</span> <span class="n">Ropsten</span> <span class="p">(</span><span class="n">the</span> <span class="n">test</span> <span class="n">network</span><span class="p">)</span>
|
||
|
||
<span class="o">//</span> <span class="n">You</span> <span class="n">may</span> <span class="n">specify</span> <span class="nb">any</span> <span class="n">of</span><span class="p">:</span>
|
||
<span class="o">//</span> <span class="o">-</span> <span class="n">boolean</span><span class="p">;</span> <span class="n">true</span> <span class="o">=</span> <span class="n">ropsten</span><span class="p">,</span> <span class="n">false</span> <span class="o">=</span> <span class="n">homestead</span>
|
||
<span class="o">//</span> <span class="o">-</span> <span class="nb">object</span><span class="p">;</span> <span class="p">{</span> <span class="n">name</span><span class="p">:</span> <span class="s1">'ropsten'</span><span class="p">,</span> <span class="n">chainId</span><span class="p">:</span> <span class="mi">3</span> <span class="p">}</span> <span class="p">(</span><span class="n">see</span> <span class="n">ethers</span><span class="o">.</span><span class="n">networks</span><span class="p">);</span>
|
||
<span class="o">//</span> <span class="o">-</span> <span class="n">string</span><span class="p">;</span> <span class="n">e</span><span class="o">.</span><span class="n">g</span><span class="o">.</span> <span class="s1">'homestead'</span><span class="p">,</span> <span class="s1">'ropsten'</span><span class="p">,</span> <span class="s1">'rinkeby'</span><span class="p">,</span> <span class="s1">'kovan'</span>
|
||
<span class="n">var</span> <span class="n">network</span> <span class="o">=</span> <span class="n">providers</span><span class="o">.</span><span class="n">networks</span><span class="o">.</span><span class="n">ropsten</span><span class="p">;</span>
|
||
|
||
<span class="o">//</span> <span class="n">Connect</span> <span class="n">to</span> <span class="n">INFUA</span>
|
||
<span class="n">var</span> <span class="n">infuraProvider</span> <span class="o">=</span> <span class="n">new</span> <span class="n">providers</span><span class="o">.</span><span class="n">InfuraProvider</span><span class="p">(</span><span class="n">network</span><span class="p">);</span>
|
||
|
||
<span class="o">//</span> <span class="n">Connect</span> <span class="n">to</span> <span class="n">Etherscan</span>
|
||
<span class="n">var</span> <span class="n">etherscanProvider</span> <span class="o">=</span> <span class="n">new</span> <span class="n">providers</span><span class="o">.</span><span class="n">EtherscanProvider</span><span class="p">(</span><span class="n">network</span><span class="p">);</span>
|
||
|
||
<span class="o">//</span> <span class="n">Creating</span> <span class="n">a</span> <span class="n">provider</span> <span class="n">to</span> <span class="n">automatically</span> <span class="n">fallback</span> <span class="n">onto</span> <span class="n">Etherscan</span>
|
||
<span class="o">//</span> <span class="k">if</span> <span class="n">INFURA</span> <span class="ow">is</span> <span class="n">down</span>
|
||
<span class="n">var</span> <span class="n">fallbackProvider</span> <span class="o">=</span> <span class="n">new</span> <span class="n">providers</span><span class="o">.</span><span class="n">FallbackProvider</span><span class="p">([</span>
|
||
<span class="n">infuraProvider</span><span class="p">,</span>
|
||
<span class="n">etherscanProvider</span>
|
||
<span class="p">]);</span>
|
||
|
||
<span class="o">//</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">equivalent</span> <span class="n">to</span> <span class="n">using</span> <span class="n">the</span> <span class="n">getDefaultProvider</span>
|
||
<span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">(</span><span class="n">network</span><span class="p">)</span>
|
||
|
||
<span class="o">//</span> <span class="n">Connect</span> <span class="n">to</span> <span class="n">a</span> <span class="n">local</span> <span class="n">Parity</span> <span class="n">instance</span>
|
||
<span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">new</span> <span class="n">providers</span><span class="o">.</span><span class="n">JsonRpcProvider</span><span class="p">(</span><span class="s1">'http://localhost:8545'</span><span class="p">,</span> <span class="n">network</span><span class="p">);</span>
|
||
|
||
<span class="o">//</span> <span class="n">Connect</span> <span class="n">to</span> <span class="n">an</span> <span class="n">injected</span> <span class="n">Web3</span><span class="s1">'s provider (e.g. MetaMask)</span>
|
||
<span class="n">var</span> <span class="n">web3Provider</span> <span class="o">=</span> <span class="n">new</span> <span class="n">providers</span><span class="o">.</span><span class="n">Web3Provider</span><span class="p">(</span><span class="n">web3</span><span class="o">.</span><span class="n">currentProvider</span><span class="p">,</span> <span class="n">network</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="prototype">
|
||
<h2>Prototype<a class="headerlink" href="#prototype" title="Permalink to this headline">¶</a></h2>
|
||
<p>All properties are immutable, and reflect their default value if not specified, or if
|
||
indirectly populated by child Objects.</p>
|
||
<div class="section" id="provider">
|
||
<span id="id1"></span><h3>Provider<a class="headerlink" href="#provider" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . name</dt>
|
||
<dd>The name of the network the provider is connected to (e.g. ‘homestead’, ‘ropsten’, ‘rinkeby’, ‘kovan’)</dd>
|
||
<dt><sup>prototype</sup> . chainId</dt>
|
||
<dd>The chain ID (or network ID) this provider is connected as; this is used by
|
||
signers to prevent <a class="reference external" href="https://github.com/ethereum/EIPs/issues/155">replay attacks</a> across compatible networks</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="fallbackprovider-inherits-from-provider">
|
||
<h3>FallbackProvider <sup>( inherits from Provider )</sup><a class="headerlink" href="#fallbackprovider-inherits-from-provider" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . providers</dt>
|
||
<dd>A <strong>copy</strong> of the array of providers (modifying this variable will not affect
|
||
the providers attached)</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="jsonrpcprovider-inherits-from-provider">
|
||
<h3>JsonRpcProvider <sup>( inherits from Provider )</sup><a class="headerlink" href="#jsonrpcprovider-inherits-from-provider" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . url</dt>
|
||
<dd>The JSON-RPC URL the provider is connected to</dd>
|
||
<dt><sup>prototype</sup> . send ( method , params )</dt>
|
||
<dd>Send the JSON-RPC <em>method</em> with <em>params</em>. This is useful for calling
|
||
non-standard or less common JSON-RPC methods. A <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> is
|
||
returned which will resolve to the parsed JSON result.</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="etherscanprovider-inherits-from-provider">
|
||
<h3>EtherscanProvider <sup>( inherits from Provider )</sup><a class="headerlink" href="#etherscanprovider-inherits-from-provider" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . apiToken</dt>
|
||
<dd>The Etherscan API Token (or null if not specified)</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="infuraprovider-inherits-from-jsonrpcprovider">
|
||
<h3>InfuraProvider <sup>( inherits from JsonRpcProvider )</sup><a class="headerlink" href="#infuraprovider-inherits-from-jsonrpcprovider" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . apiAccessToken</dt>
|
||
<dd>The INFURA API Access Token (or null if not specified)</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="web3provider-inherits-from-jsonrpcprovider">
|
||
<h3>Web3Provider <sup>( inherits from JsonRpcProvider )</sup><a class="headerlink" href="#web3provider-inherits-from-jsonrpcprovider" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . provider</dt>
|
||
<dd><p class="first">The underlying Web3-compatible provider from the Web3 library, for example
|
||
an <a class="reference external" href="https://github.com/ethereum/web3.js/blob/develop/lib/web3/httpprovider.js">HTTPProvider</a> or <a class="reference external" href="https://github.com/ethereum/web3.js/blob/develop/lib/web3/ipcprovider.js">IPCProvider</a>. The only required method on a Web3 provider
|
||
is:</p>
|
||
<p class="last"><em>sendAsync ( method , params , callback )</em></p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="account-actions">
|
||
<h2>Account Actions<a class="headerlink" href="#account-actions" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . getBalance ( addressOrName [ , blockTag ] )</dt>
|
||
<dd><p class="first">Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the balance (as a <a class="reference internal" href="api-utils.html#bignumber"><span class="std std-ref">BigNumber</span></a>) of
|
||
<em>addressOrName</em> at <em>blockTag</em>. (See: <a class="reference internal" href="#blocktag"><span class="std std-ref">Block Tags</span></a>)</p>
|
||
<p class="last"><strong>default:</strong> <em>blockTag</em>=”latest”</p>
|
||
</dd>
|
||
<dt><sup>prototype</sup> . getTransactionCount ( addressOrName [ , blockTag ] )</dt>
|
||
<dd><p class="first">Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the number of sent transactions (as a Number) from
|
||
<em>addressOrName</em> at <em>blockTag</em>. This is also the nonce required to send a new
|
||
transaction. (See: <a class="reference internal" href="#blocktag"><span class="std std-ref">Block Tags</span></a>)</p>
|
||
<p class="last"><strong>default:</strong> <em>blockTag</em>=”latest”</p>
|
||
</dd>
|
||
<dt><sup>prototype</sup> . lookupAddress ( address )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> which resolves to the ENS name (or null) that <em>address</em> resolves
|
||
to.</dd>
|
||
<dt><sup>prototype</sup> . resolveName ( ensName )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> which resolves to the address (or null) of that the <em>ensName</em>
|
||
resolves to.</dd>
|
||
</dl>
|
||
<div class="section" id="id2">
|
||
<h3><em>Examples</em><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">ethers</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="s1">'ethers'</span><span class="p">);</span>
|
||
<span class="n">var</span> <span class="n">providers</span> <span class="o">=</span> <span class="n">ethers</span><span class="o">.</span><span class="n">providers</span><span class="p">;</span>
|
||
|
||
<span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">(</span><span class="s1">'ropsten'</span><span class="p">);</span>
|
||
|
||
<span class="n">var</span> <span class="n">address</span> <span class="o">=</span> <span class="s2">"0x02F024e0882B310c6734703AB9066EdD3a10C6e0"</span><span class="p">;</span>
|
||
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getBalance</span><span class="p">(</span><span class="n">address</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">balance</span><span class="p">)</span> <span class="p">{</span>
|
||
|
||
<span class="o">//</span> <span class="n">balance</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">BigNumber</span> <span class="p">(</span><span class="ow">in</span> <span class="n">wei</span><span class="p">);</span> <span class="nb">format</span> <span class="ow">is</span> <span class="k">as</span> <span class="n">a</span> <span class="n">sting</span> <span class="p">(</span><span class="ow">in</span> <span class="n">ether</span><span class="p">)</span>
|
||
<span class="n">var</span> <span class="n">etherString</span> <span class="o">=</span> <span class="n">ethers</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">formatEther</span><span class="p">(</span><span class="n">balance</span><span class="p">);</span>
|
||
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">"Balance: "</span> <span class="o">+</span> <span class="n">etherString</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getTransactionCount</span><span class="p">(</span><span class="n">address</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">transactionCount</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">"Total Transactions Ever Send: "</span> <span class="o">+</span> <span class="n">transactionCount</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">resolveName</span><span class="p">(</span><span class="s2">"test.ricmoose.eth"</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">address</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">"Address: "</span> <span class="o">+</span> <span class="n">address</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="blockchain-status">
|
||
<h2>Blockchain Status<a class="headerlink" href="#blockchain-status" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . getBlockNumber ( )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the latest block number (as a Number).</dd>
|
||
<dt><sup>prototype</sup> . getGasPrice ( )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the current gas price (as a <a class="reference internal" href="api-utils.html#bignumber"><span class="std std-ref">BigNumber</span></a>).</dd>
|
||
<dt><sup>prototype</sup> . getBlock ( blockHashOrBlockNumber )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the block at <em>blockHashorBlockNumber</em>. (See: <a class="reference internal" href="#blockresponse"><span class="std std-ref">Block Responses</span></a>)</dd>
|
||
<dt><sup>prototype</sup> . getTransaction ( transactionHash )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the transaction with <em>transactionHash</em>. (See: <a class="reference internal" href="#transactionresponse"><span class="std std-ref">Transaction Responses</span></a>)</dd>
|
||
<dt><sup>prototype</sup> . getTransactionReceipt ( transactionHash )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the transaction receipt with <em>transactionHash</em>.
|
||
(See: <a class="reference internal" href="#transactionreceipt"><span class="std std-ref">Transaction Receipts</span></a>)</dd>
|
||
</dl>
|
||
<div class="section" id="id3">
|
||
<h3><em>Examples</em><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
|
||
<p><strong>Current State</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">();</span>
|
||
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getBlockNumber</span><span class="p">()</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">blockNumber</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">"Current block number: "</span> <span class="o">+</span> <span class="n">blockNumber</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getGasPrice</span><span class="p">()</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">gasPrice</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="o">//</span> <span class="n">gasPrice</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">BigNumber</span><span class="p">;</span> <span class="n">convert</span> <span class="n">it</span> <span class="n">to</span> <span class="n">a</span> <span class="n">decimal</span> <span class="n">string</span>
|
||
<span class="n">gasPriceString</span> <span class="o">=</span> <span class="n">gasPrice</span><span class="o">.</span><span class="n">toString</span><span class="p">();</span>
|
||
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">"Current gas price: "</span> <span class="o">+</span> <span class="n">gasPriceString</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>Blocks</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">();</span>
|
||
|
||
<span class="o">//</span> <span class="n">Block</span> <span class="n">Number</span>
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getBlock</span><span class="p">(</span><span class="mi">3346773</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">block</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">block</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
<span class="o">//</span> <span class="n">Block</span> <span class="n">Hash</span>
|
||
<span class="n">var</span> <span class="n">blockHash</span> <span class="o">=</span> <span class="s2">"0x7a1d0b010393c8d850200d0ec1e27c0c8a295366247b1bd6124d496cf59182ad"</span><span class="p">;</span>
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getBlock</span><span class="p">(</span><span class="n">blockHash</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">block</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">block</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>Transactions</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">();</span>
|
||
|
||
<span class="n">var</span> <span class="n">transactionHash</span> <span class="o">=</span> <span class="s2">"0x7baea23e7d77bff455d94f0c81916f938c398252fb62fce2cdb43643134ce4ed"</span><span class="p">;</span>
|
||
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getTransaction</span><span class="p">(</span><span class="n">transactionHash</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">transaction</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">transaction</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getTransactionReceipt</span><span class="p">(</span><span class="n">transactionHash</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">transactionReceipt</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">transactionReceipt</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="ethereum-name-resolution">
|
||
<h2>Ethereum Name Resolution<a class="headerlink" href="#ethereum-name-resolution" title="Permalink to this headline">¶</a></h2>
|
||
<p>The Ethereum Naming Service (ENS) allows easy to remember and use names to be
|
||
assigned to Ethereum addresses. Any provider operation which takes an address
|
||
may also take an ENS name.</p>
|
||
<p>It is often useful to resolve a name entered by a user or perform a reverse lookup
|
||
of an address to get a more human readbale name.</p>
|
||
<p><strong>Resolving Names</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">providers</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="s1">'ethers'</span><span class="p">)</span><span class="o">.</span><span class="n">providers</span><span class="p">;</span>
|
||
<span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">();</span>
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">resolveName</span><span class="p">(</span><span class="s1">'registrar.firefly.eth'</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">address</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">address</span><span class="p">);</span>
|
||
<span class="o">//</span> <span class="s1">'0x6fC21092DA55B392b045eD78F4732bff3C580e2c'</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>Looking up Addresses</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">provider</span><span class="o">.</span><span class="n">lookupAddress</span><span class="p">(</span><span class="s1">'0x6fC21092DA55B392b045eD78F4732bff3C580e2c'</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">name</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">name</span><span class="p">);</span>
|
||
<span class="o">//</span> <span class="s1">'registrar.firefly.eth'</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="contract-execution">
|
||
<h2>Contract Execution<a class="headerlink" href="#contract-execution" title="Permalink to this headline">¶</a></h2>
|
||
<p>These are relatively low-level calls. The <a class="reference internal" href="api-contract.html#api-contract"><span class="std std-ref">Contracts API</span></a> should
|
||
usually be used instead.</p>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . call ( transaction )</dt>
|
||
<dd><p class="first">Send the <strong>read-only</strong> (constant) <em>transaction</em> to a single Ethereum node and
|
||
return a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the result (as a <a class="reference internal" href="api-utils.html#hexstring"><span class="std std-ref">hex string</span></a>) of executing it.
|
||
(See <a class="reference internal" href="#transactionrequest"><span class="std std-ref">Transaction Requests</span></a>)</p>
|
||
<p class="last">This is free, since it does not change any state on the blockchain.</p>
|
||
</dd>
|
||
<dt><sup>prototype</sup> . estimateGas ( transaction )</dt>
|
||
<dd><p class="first">Send a <em>transaction</em> to a single Ethereum node and return a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the
|
||
estimated amount of gas required (as a <a class="reference internal" href="api-utils.html#bignumber"><span class="std std-ref">BigNumber</span></a>) to send it.
|
||
(See <a class="reference internal" href="#transactionrequest"><span class="std std-ref">Transaction Requests</span></a>)</p>
|
||
<p class="last">This is free, but only an estimate. Providing too little gas will result in a
|
||
transaction being rejected (while still consuming all provided gas).</p>
|
||
</dd>
|
||
<dt><sup>prototype</sup> . sendTransaction ( signedTransaction )</dt>
|
||
<dd><p class="first">Send the <em>signedTransaction</em> to the <strong>entire</strong> Ethereum network and returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a>
|
||
with the transaction hash.</p>
|
||
<p class="last"><strong>This will consume gas</strong> from the account that signed the transaction.</p>
|
||
</dd>
|
||
</dl>
|
||
<div class="section" id="id4">
|
||
<h3><em>Examples</em><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
|
||
<p><strong>Call (Constant) Functions</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">ethers</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="s1">'ethers'</span><span class="p">);</span>
|
||
<span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">ethers</span><span class="o">.</span><span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">();</span>
|
||
|
||
<span class="o">//</span> <span class="n">setup</span> <span class="n">a</span> <span class="n">transaction</span> <span class="n">to</span> <span class="n">call</span> <span class="n">the</span> <span class="n">CryptoKitties</span><span class="o">.</span><span class="n">symbol</span><span class="p">()</span> <span class="n">function</span>
|
||
<span class="o">//</span> <span class="n">CryptoKitties</span> <span class="n">contract</span> <span class="n">address</span>
|
||
<span class="n">var</span> <span class="n">address</span> <span class="o">=</span> <span class="s2">"0x06012c8cf97BEaD5deAe237070F9587f8E7A266d"</span><span class="p">;</span>
|
||
<span class="o">//</span> <span class="n">first</span> <span class="mi">8</span> <span class="n">nibbles</span> <span class="n">of</span> <span class="n">the</span> <span class="nb">hash</span> <span class="n">of</span> <span class="n">symbol</span><span class="p">()</span>
|
||
<span class="n">var</span> <span class="n">data</span> <span class="o">=</span> <span class="n">ethers</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">id</span><span class="p">(</span><span class="s1">'symbol()'</span><span class="p">)</span><span class="o">.</span><span class="n">substring</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">10</span><span class="p">);</span>
|
||
<span class="n">var</span> <span class="n">transaction</span> <span class="o">=</span> <span class="p">{</span>
|
||
<span class="n">to</span><span class="p">:</span> <span class="n">address</span><span class="p">,</span>
|
||
<span class="n">data</span><span class="p">:</span> <span class="n">data</span>
|
||
<span class="p">}</span>
|
||
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">call</span><span class="p">(</span><span class="n">transaction</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">result</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">result</span><span class="p">);</span>
|
||
<span class="o">//</span> <span class="s1">'0x000000000000000000000000000000000000000000000000000000000000002'</span><span class="o">+</span>
|
||
<span class="o">//</span> <span class="s1">'00000000000000000000000000000000000000000000000000000000000000002'</span><span class="o">+</span>
|
||
<span class="o">//</span> <span class="s1">'434b000000000000000000000000000000000000000000000000000000000000'</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>sendTransaction</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">ethers</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="s1">'ethers'</span><span class="p">);</span>
|
||
<span class="n">var</span> <span class="n">privateKey</span> <span class="o">=</span> <span class="s1">'0x0123456789012345678901234567890123456789012345678901234567890123'</span><span class="p">;</span>
|
||
<span class="n">var</span> <span class="n">wallet</span> <span class="o">=</span> <span class="n">new</span> <span class="n">ethers</span><span class="o">.</span><span class="n">Wallet</span><span class="p">(</span><span class="n">privateKey</span><span class="p">);</span>
|
||
<span class="n">wallet</span><span class="o">.</span><span class="n">provider</span> <span class="o">=</span> <span class="n">ethers</span><span class="o">.</span><span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">(</span><span class="s1">'ropsten'</span><span class="p">);</span>
|
||
|
||
<span class="n">var</span> <span class="n">transaction</span> <span class="o">=</span> <span class="p">{</span>
|
||
<span class="n">to</span><span class="p">:</span> <span class="s2">"0x88a5C2d9919e46F883EB62F7b8Dd9d0CC45bc290"</span><span class="p">,</span>
|
||
<span class="n">value</span><span class="p">:</span> <span class="n">ethers</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">parseEther</span><span class="p">(</span><span class="s2">"0.1"</span><span class="p">)</span>
|
||
<span class="p">};</span>
|
||
|
||
<span class="n">var</span> <span class="n">estimateGasPromise</span> <span class="o">=</span> <span class="n">wallet</span><span class="o">.</span><span class="n">estimateGas</span><span class="p">(</span><span class="n">transaction</span><span class="p">);</span>
|
||
|
||
<span class="n">estimateGasPromise</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">gasEstimate</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">gasEstimate</span><span class="o">.</span><span class="n">toString</span><span class="p">());</span>
|
||
<span class="n">transaction</span><span class="o">.</span><span class="n">gasLimit</span> <span class="o">=</span> <span class="n">gasEstimate</span><span class="p">;</span>
|
||
|
||
|
||
<span class="o">//</span> <span class="n">Send</span> <span class="n">the</span> <span class="n">transaction</span>
|
||
<span class="n">var</span> <span class="n">sendTransactionPromise</span> <span class="o">=</span> <span class="n">wallet</span><span class="o">.</span><span class="n">sendTransaction</span><span class="p">(</span><span class="n">transaction</span><span class="p">);</span>
|
||
|
||
<span class="n">sendTransactionPromise</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">transactionHash</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">transactionHash</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="contract-state">
|
||
<h2>Contract State<a class="headerlink" href="#contract-state" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . getCode ( addressOrName )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the bytecode (as a <a class="reference internal" href="api-utils.html#hexstring"><span class="std std-ref">hex string</span></a>)
|
||
at <em>addressOrName</em>.</dd>
|
||
<dt><sup>prototype</sup> . getStorageAt ( addressOrName , position [ , blockTag ] )</dt>
|
||
<dd><p class="first">Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the value (as a <a class="reference internal" href="api-utils.html#hexstring"><span class="std std-ref">hex string</span></a>) at
|
||
<em>addressOrName</em> in <em>position</em> at <em>blockTag</em>. (See <a class="reference internal" href="#blocktag"><span class="std std-ref">Block Tags</span></a>)</p>
|
||
<p class="last">default: <em>blockTag</em>= “latest”</p>
|
||
</dd>
|
||
<dt><sup>prototype</sup> . getLogs ( filter )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with an array (possibly empty) of the logs that
|
||
match the <em>filter</em>. (See <a class="reference internal" href="#filter"><span class="std std-ref">Filters</span></a>)</dd>
|
||
</dl>
|
||
<div class="section" id="id5">
|
||
<h3><em>Examples</em><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
|
||
<p><strong>getCode</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">ethers</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="s1">'ethers'</span><span class="p">);</span>
|
||
<span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">ethers</span><span class="o">.</span><span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">();</span>
|
||
|
||
<span class="n">var</span> <span class="n">contractAddress</span> <span class="o">=</span> <span class="s1">'0x6fC21092DA55B392b045eD78F4732bff3C580e2c'</span><span class="p">;</span>
|
||
<span class="n">var</span> <span class="n">contractEnsName</span> <span class="o">=</span> <span class="s1">'registrar.firefly.eth'</span><span class="p">;</span>
|
||
<span class="n">var</span> <span class="n">codePromise</span> <span class="o">=</span> <span class="n">provider</span><span class="o">.</span><span class="n">getCode</span><span class="p">(</span><span class="n">contractEnsName</span><span class="p">);</span>
|
||
<span class="n">codePromise</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">result</span><span class="p">){</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s1">'getCode by ENS name:'</span><span class="p">);</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">result</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
<span class="n">var</span> <span class="n">codeByAddressPromise</span> <span class="o">=</span> <span class="n">provider</span><span class="o">.</span><span class="n">getCode</span><span class="p">(</span><span class="n">contractAddress</span><span class="p">);</span>
|
||
<span class="n">codeByAddressPromise</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">result</span><span class="p">){</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s1">'getCode by contract address:'</span><span class="p">);</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">result</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>getStorageAt</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">ethers</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="s1">'ethers'</span><span class="p">);</span>
|
||
<span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">ethers</span><span class="o">.</span><span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">();</span>
|
||
|
||
<span class="n">var</span> <span class="n">contractEnsName</span> <span class="o">=</span> <span class="s1">'registrar.firefly.eth'</span><span class="p">;</span>
|
||
<span class="n">var</span> <span class="n">storagePromise</span> <span class="o">=</span> <span class="n">provider</span><span class="o">.</span><span class="n">getStorageAt</span><span class="p">(</span><span class="n">contractEnsName</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
|
||
<span class="n">storagePromise</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">result</span><span class="p">){</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">result</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>getLogs</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">ethers</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="s1">'ethers'</span><span class="p">);</span>
|
||
<span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">ethers</span><span class="o">.</span><span class="n">providers</span><span class="o">.</span><span class="n">getDefaultProvider</span><span class="p">();</span>
|
||
|
||
<span class="n">var</span> <span class="n">cryptoKittiesContractAddress</span> <span class="o">=</span> <span class="s1">'0x06012c8cf97BEaD5deAe237070F9587f8E7A266d'</span><span class="p">;</span>
|
||
<span class="n">var</span> <span class="n">topic</span> <span class="o">=</span> <span class="s1">'0x241ea03ca20251805084d27d4440371c34a0b85ff108f6bb5611248f73818b80'</span><span class="p">;</span>
|
||
<span class="n">var</span> <span class="nb">filter</span> <span class="o">=</span> <span class="p">{</span>
|
||
<span class="n">fromBlock</span><span class="p">:</span> <span class="mi">5044502</span><span class="p">,</span>
|
||
<span class="n">address</span><span class="p">:</span> <span class="n">cryptoKittiesContractAddress</span><span class="p">,</span>
|
||
<span class="n">topics</span><span class="p">:</span> <span class="p">[</span> <span class="n">topic</span> <span class="p">]</span>
|
||
<span class="p">}</span>
|
||
<span class="n">var</span> <span class="n">filterPromise</span> <span class="o">=</span> <span class="n">provider</span><span class="o">.</span><span class="n">getLogs</span><span class="p">(</span><span class="nb">filter</span><span class="p">);</span>
|
||
<span class="n">filterPromise</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">result</span><span class="p">){</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">result</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="events">
|
||
<h2>Events<a class="headerlink" href="#events" title="Permalink to this headline">¶</a></h2>
|
||
<p>These methods allow management of callbacks on certain events on the blockchain
|
||
and contracts. They are largely based on the <a class="reference external" href="https://nodejs.org/dist/latest-v6.x/docs/api/events.html">EventEmitter API</a>.</p>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . on ( eventType , callback )</dt>
|
||
<dd>Register a callback for any future <em>eventType</em>; see below for callback parameters</dd>
|
||
<dt><sup>prototype</sup> . once ( eventType , callback)</dt>
|
||
<dd>Register a callback for the next (and only next) <em>eventType</em>; see below for callback parameters</dd>
|
||
<dt><sup>prototype</sup> . removeListener ( eventType , callback )</dt>
|
||
<dd>Unregister the <em>callback</em> for <em>eventType</em>; if the same callback is registered
|
||
more than once, only the first registered instance is removed</dd>
|
||
<dt><sup>prototype</sup> . removeAllListeners ( eventType )</dt>
|
||
<dd>Unregister all callbacks for <em>eventType</em></dd>
|
||
<dt><sup>prototype</sup> . listenerCount ( [ eventType ] )</dt>
|
||
<dd>Return the number of callbacks registered for <em>eventType</em>, or if ommitted, the
|
||
total number of callbacks registered</dd>
|
||
<dt><sup>prototype</sup> . resetEventsBlock ( blockNumber )</dt>
|
||
<dd>Begin scanning for events from <em>blockNumber</em>. By default, events begin at the
|
||
block number that the provider began polling at.</dd>
|
||
</dl>
|
||
<div class="section" id="event-types">
|
||
<h3>Event Types<a class="headerlink" href="#event-types" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt>“block”</dt>
|
||
<dd><p class="first">Whenever a new block is mined</p>
|
||
<p class="last"><code class="docutils literal"><span class="pre">callback(</span> <span class="pre">blockNumber</span> <span class="pre">)</span></code></p>
|
||
</dd>
|
||
<dt>any address</dt>
|
||
<dd><p class="first">When the balance of the corresponding address changes</p>
|
||
<p class="last"><code class="docutils literal"><span class="pre">callback(</span> <span class="pre">balance</span> <span class="pre">)</span></code></p>
|
||
</dd>
|
||
<dt>any transaction hash</dt>
|
||
<dd><p class="first">When the corresponding transaction is mined; also see
|
||
<a class="reference internal" href="#waitfortransaction"><span class="std std-ref">Waiting for Transactions</span></a></p>
|
||
<p class="last"><code class="docutils literal"><span class="pre">callback(</span> <span class="pre">transaction</span> <span class="pre">)</span></code></p>
|
||
</dd>
|
||
<dt>an array of topics</dt>
|
||
<dd><p class="first">When any of the topics are triggered in a block’s logs; when using the
|
||
<a class="reference internal" href="api-contract.html#api-contract"><span class="std std-ref">Contract API</span></a>, this is automatically handled;</p>
|
||
<p class="last"><code class="docutils literal"><span class="pre">callback(</span> <span class="pre">log</span> <span class="pre">)</span></code></p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="waiting-for-transactions">
|
||
<span id="waitfortransaction"></span><h3>Waiting for Transactions<a class="headerlink" href="#waiting-for-transactions" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . waitForTransaction ( transactionHash [ , timeout ] )</dt>
|
||
<dd>Return a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> which returns the transaction once <em>transactionHash</em> is
|
||
mined, with an optional <em>timeout</em> (in milliseconds)</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="id6">
|
||
<h3><em>Examples</em><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">//</span> <span class="n">Get</span> <span class="n">notified</span> <span class="n">on</span> <span class="n">every</span> <span class="n">new</span> <span class="n">block</span>
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">on</span><span class="p">(</span><span class="s1">'block'</span><span class="p">,</span> <span class="n">function</span><span class="p">(</span><span class="n">blockNumber</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s1">'New Block: '</span> <span class="o">+</span> <span class="n">blockNumber</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
<span class="o">//</span> <span class="n">Get</span> <span class="n">notified</span> <span class="n">on</span> <span class="n">account</span> <span class="n">balance</span> <span class="n">change</span>
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">on</span><span class="p">(</span><span class="s1">'0x46Fa84b9355dB0708b6A57cd6ac222950478Be1d'</span><span class="p">,</span> <span class="n">function</span><span class="p">(</span><span class="n">balance</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s1">'New Balance: '</span> <span class="o">+</span> <span class="n">balance</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
<span class="o">//</span> <span class="n">Get</span> <span class="n">notified</span> <span class="n">when</span> <span class="n">a</span> <span class="n">transaction</span> <span class="ow">is</span> <span class="n">mined</span>
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">once</span><span class="p">(</span><span class="n">transactionHash</span><span class="p">,</span> <span class="n">function</span><span class="p">(</span><span class="n">transaction</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s1">'Transaction Minded: '</span> <span class="o">+</span> <span class="n">transaction</span><span class="o">.</span><span class="n">hash</span><span class="p">);</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">transaction</span><span class="p">);</span>
|
||
<span class="p">);</span>
|
||
|
||
<span class="o">//</span> <span class="n">OR</span> <span class="n">equivalently</span> <span class="n">the</span> <span class="n">waitForTransaction</span><span class="p">()</span> <span class="n">returns</span> <span class="n">a</span> <span class="n">Promise</span>
|
||
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">waitForTransaction</span><span class="p">(</span><span class="n">transactionHash</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">transaction</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s1">'Transaction Mined: '</span> <span class="o">+</span> <span class="n">transaction</span><span class="o">.</span><span class="n">hash</span><span class="p">);</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">transaction</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
|
||
<span class="o">//</span> <span class="n">Get</span> <span class="n">notified</span> <span class="n">when</span> <span class="n">a</span> <span class="n">contract</span> <span class="n">event</span> <span class="ow">is</span> <span class="n">logged</span>
|
||
<span class="n">var</span> <span class="n">eventTopic</span> <span class="o">=</span> <span class="s1">'0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'</span><span class="p">;</span>
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">on</span><span class="p">([</span> <span class="n">eventTopic</span> <span class="p">],</span> <span class="n">function</span><span class="p">(</span><span class="n">log</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s1">'Event Log'</span><span class="p">);</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">log</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="objects">
|
||
<h2>Objects<a class="headerlink" href="#objects" title="Permalink to this headline">¶</a></h2>
|
||
<p>There are several common objects and types that are commonly used as input parameters or
|
||
return types for various provider calls.</p>
|
||
<div class="section" id="block-tag">
|
||
<span id="blocktag"></span><h3>Block Tag<a class="headerlink" href="#block-tag" title="Permalink to this headline">¶</a></h3>
|
||
<p>A block tag is used to uniquely identify a block’s position in the blockchain:</p>
|
||
<dl class="docutils">
|
||
<dt>a Number or <a class="reference internal" href="api-utils.html#hexstring"><span class="std std-ref">hex string</span></a>:</dt>
|
||
<dd>Each block has a block number (eg. <code class="docutils literal"><span class="pre">42</span></code> or <code class="docutils literal"><span class="pre">"0x2a</span></code>.</dd>
|
||
<dt>“latest”:</dt>
|
||
<dd>The most recently mined block.</dd>
|
||
<dt>“pending”:</dt>
|
||
<dd>The block that is currently being mined.</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="block-responses">
|
||
<span id="blockresponse"></span><h3>Block Responses<a class="headerlink" href="#block-responses" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span>
|
||
<span class="n">parentHash</span><span class="p">:</span> <span class="s2">"0x3d8182d27303d92a2c9efd294a36dac878e1a9f7cb0964fa0f789fa96b5d0667"</span><span class="p">,</span>
|
||
<span class="nb">hash</span><span class="p">:</span> <span class="s2">"0x7f20ef60e9f91896b7ebb0962a18b8defb5e9074e62e1b6cde992648fe78794b"</span><span class="p">,</span>
|
||
<span class="n">number</span><span class="p">:</span> <span class="mi">3346463</span><span class="p">,</span>
|
||
|
||
<span class="n">difficulty</span><span class="p">:</span> <span class="mi">183765779077962</span><span class="p">,</span>
|
||
<span class="n">timestamp</span><span class="p">:</span> <span class="mi">1489440489</span><span class="p">,</span>
|
||
<span class="n">nonce</span><span class="p">:</span> <span class="s2">"0x17060cb000d2c714"</span><span class="p">,</span>
|
||
<span class="n">extraData</span><span class="p">:</span> <span class="s2">"0x65746865726d696e65202d20555331"</span><span class="p">,</span>
|
||
|
||
<span class="n">gasLimit</span><span class="p">:</span> <span class="n">utils</span><span class="o">.</span><span class="n">bigNumberify</span><span class="p">(</span><span class="s2">"3993225"</span><span class="p">),</span>
|
||
<span class="n">gasUsed</span><span class="p">:</span> <span class="n">utils</span><span class="o">.</span><span class="n">bigNuberify</span><span class="p">(</span><span class="s2">"3254236"</span><span class="p">),</span>
|
||
|
||
<span class="n">miner</span><span class="p">:</span> <span class="s2">"0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8"</span><span class="p">,</span>
|
||
<span class="n">transactions</span><span class="p">:</span> <span class="p">[</span>
|
||
<span class="s2">"0x125d2b846de85c4c74eafb6f1b49fdb2326e22400ae223d96a8a0b26ccb2a513"</span><span class="p">,</span>
|
||
<span class="s2">"0x948d6e8f6f8a4d30c0bd527becbe24d15b1aba796f9a9a09a758b622145fd963"</span><span class="p">,</span>
|
||
<span class="o">...</span> <span class="p">[</span> <span class="mi">49</span> <span class="n">more</span> <span class="n">transaction</span> <span class="n">hashes</span> <span class="p">]</span> <span class="o">...</span>
|
||
<span class="s2">"0xbd141969b164ed70388f95d780864210e045e7db83e71f171ab851b2fba6b730"</span>
|
||
<span class="p">]</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="transaction-requests">
|
||
<span id="transactionrequest"></span><h3>Transaction Requests<a class="headerlink" href="#transaction-requests" title="Permalink to this headline">¶</a></h3>
|
||
<p>Any property which accepts a number may also be specified as a <a class="reference internal" href="api-utils.html#bignumber"><span class="std std-ref">BigNumber</span></a>
|
||
or <a class="reference internal" href="api-utils.html#hexstring"><span class="std std-ref">hex string</span></a>.</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">//</span> <span class="n">Example</span><span class="p">:</span>
|
||
<span class="p">{</span>
|
||
<span class="o">//</span> <span class="n">Required</span> <span class="n">unless</span> <span class="n">deploying</span> <span class="n">a</span> <span class="n">contract</span> <span class="p">(</span><span class="ow">in</span> <span class="n">which</span> <span class="n">case</span> <span class="n">omit</span><span class="p">)</span>
|
||
<span class="n">to</span><span class="p">:</span> <span class="n">addressOrName</span><span class="p">,</span> <span class="o">//</span> <span class="n">the</span> <span class="n">target</span> <span class="n">address</span> <span class="ow">or</span> <span class="n">ENS</span> <span class="n">name</span>
|
||
|
||
<span class="o">//</span> <span class="n">These</span> <span class="n">are</span> <span class="n">optional</span><span class="o">/</span><span class="n">meaningless</span> <span class="k">for</span> <span class="n">call</span> <span class="ow">and</span> <span class="n">estimateGas</span>
|
||
<span class="n">nonce</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="o">//</span> <span class="n">the</span> <span class="n">transaction</span> <span class="n">nonce</span>
|
||
<span class="n">gasLimit</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="o">//</span> <span class="n">the</span> <span class="n">maximum</span> <span class="n">gas</span> <span class="n">this</span> <span class="n">transaction</span> <span class="n">may</span> <span class="n">spend</span>
|
||
<span class="n">gasPrice</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="o">//</span> <span class="n">the</span> <span class="n">price</span> <span class="p">(</span><span class="ow">in</span> <span class="n">wei</span><span class="p">)</span> <span class="n">per</span> <span class="n">unit</span> <span class="n">of</span> <span class="n">gas</span>
|
||
|
||
<span class="o">//</span> <span class="n">These</span> <span class="n">are</span> <span class="n">always</span> <span class="n">optional</span> <span class="p">(</span><span class="n">but</span> <span class="k">for</span> <span class="n">call</span><span class="p">,</span> <span class="n">data</span> <span class="ow">is</span> <span class="n">usually</span> <span class="n">specified</span><span class="p">)</span>
|
||
<span class="n">data</span><span class="p">:</span> <span class="s2">"0x"</span><span class="p">,</span> <span class="o">//</span> <span class="n">extra</span> <span class="n">data</span> <span class="k">for</span> <span class="n">the</span> <span class="n">transaction</span><span class="p">,</span> <span class="ow">or</span> <span class="nb">input</span> <span class="k">for</span> <span class="n">call</span>
|
||
<span class="n">value</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="o">//</span> <span class="n">the</span> <span class="n">amount</span> <span class="p">(</span><span class="ow">in</span> <span class="n">wei</span><span class="p">)</span> <span class="n">this</span> <span class="n">transaction</span> <span class="ow">is</span> <span class="n">sending</span>
|
||
<span class="n">chainId</span><span class="p">:</span> <span class="mi">3</span> <span class="o">//</span> <span class="n">the</span> <span class="n">network</span> <span class="n">ID</span><span class="p">;</span> <span class="n">usually</span> <span class="n">added</span> <span class="n">by</span> <span class="n">a</span> <span class="n">signer</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="transaction-response">
|
||
<span id="transactionresponse"></span><h3>Transaction Response<a class="headerlink" href="#transaction-response" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">//</span> <span class="n">Example</span><span class="p">:</span>
|
||
<span class="p">{</span>
|
||
<span class="o">//</span> <span class="n">Only</span> <span class="n">available</span> <span class="k">for</span> <span class="n">mined</span> <span class="n">transactions</span>
|
||
<span class="n">blockHash</span><span class="p">:</span> <span class="s2">"0x7f20ef60e9f91896b7ebb0962a18b8defb5e9074e62e1b6cde992648fe78794b"</span><span class="p">,</span>
|
||
<span class="n">blockNumber</span><span class="p">:</span> <span class="mi">3346463</span><span class="p">,</span>
|
||
<span class="n">transactionIndex</span><span class="p">:</span> <span class="mi">51</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">Exactly</span> <span class="n">one</span> <span class="n">of</span> <span class="n">these</span> <span class="n">will</span> <span class="n">be</span> <span class="n">present</span> <span class="p">(</span><span class="n">send</span> <span class="n">vs</span><span class="o">.</span> <span class="n">deploy</span> <span class="n">contract</span><span class="p">)</span>
|
||
<span class="n">creates</span><span class="p">:</span> <span class="n">null</span><span class="p">,</span>
|
||
<span class="n">to</span><span class="p">:</span> <span class="s2">"0xc149Be1bcDFa69a94384b46A1F91350E5f81c1AB"</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">The</span> <span class="n">transaction</span> <span class="nb">hash</span>
|
||
<span class="nb">hash</span><span class="p">:</span> <span class="s2">"0xf517872f3c466c2e1520e35ad943d833fdca5a6739cfea9e686c4c1b3ab1022e"</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">See</span> <span class="n">above</span> <span class="p">(</span><span class="n">Transaction</span> <span class="n">Requests</span><span class="p">)</span> <span class="k">for</span> <span class="n">these</span> <span class="n">explained</span>
|
||
<span class="n">data</span><span class="p">:</span> <span class="s2">"0x"</span><span class="p">,</span>
|
||
<span class="n">from</span><span class="p">:</span> <span class="s2">"0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8"</span><span class="p">,</span>
|
||
<span class="n">gasLimit</span><span class="p">:</span> <span class="n">utils</span><span class="o">.</span><span class="n">bigNumberify</span><span class="p">(</span><span class="s2">"90000"</span><span class="p">),</span>
|
||
<span class="n">gasPrice</span><span class="p">:</span> <span class="n">utils</span><span class="o">.</span><span class="n">bigNumberify</span><span class="p">(</span><span class="s2">"21488430592"</span><span class="p">),</span>
|
||
<span class="n">nonce</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
|
||
<span class="n">value</span><span class="p">:</span> <span class="n">utils</span><span class="o">.</span><span class="n">parseEther</span><span class="p">(</span><span class="mf">1.0017071732629267</span><span class="p">),</span>
|
||
|
||
<span class="o">//</span> <span class="n">The</span> <span class="n">network</span> <span class="n">ID</span> <span class="p">(</span><span class="ow">or</span> <span class="n">chain</span> <span class="n">ID</span><span class="p">);</span> <span class="mi">0</span> <span class="n">indicates</span> <span class="n">replay</span><span class="o">-</span><span class="n">attack</span> <span class="n">vulnerable</span>
|
||
<span class="o">//</span> <span class="p">(</span><span class="n">eg</span><span class="o">.</span> <span class="mi">1</span> <span class="o">=</span> <span class="n">Homestead</span> <span class="n">mainnet</span><span class="p">,</span> <span class="mi">3</span> <span class="o">=</span> <span class="n">Ropsten</span> <span class="n">testnet</span><span class="p">)</span>
|
||
<span class="n">networkId</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">The</span> <span class="n">signature</span> <span class="n">of</span> <span class="n">the</span> <span class="n">transaction</span>
|
||
<span class="n">r</span><span class="p">:</span> <span class="s2">"0x5b13ef45ce3faf69d1f40f9d15b0070cc9e2c92f3df79ad46d5b3226d7f3d1e8"</span><span class="p">,</span>
|
||
<span class="n">s</span><span class="p">:</span> <span class="s2">"0x535236e497c59e3fba93b78e124305c7c9b20db0f8531b015066725e4bb31de6"</span><span class="p">,</span>
|
||
<span class="n">v</span><span class="p">:</span> <span class="mi">37</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">The</span> <span class="n">raw</span> <span class="n">transaction</span>
|
||
<span class="n">raw</span><span class="p">:</span> <span class="s2">"0xf87083154262850500cf6e0083015f9094c149be1bcdfa69a94384b46a1f913"</span> <span class="o">+</span>
|
||
<span class="s2">"50e5f81c1ab880de6c75de74c236c8025a05b13ef45ce3faf69d1f40f9d15b0"</span> <span class="o">+</span>
|
||
<span class="s2">"070cc9e2c92f3df79ad46d5b3226d7f3d1e8a0535236e497c59e3fba93b78e1"</span> <span class="o">+</span>
|
||
<span class="s2">"24305c7c9b20db0f8531b015066725e4bb31de6"</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="transaction-receipts">
|
||
<span id="transactionreceipt"></span><h3>Transaction Receipts<a class="headerlink" href="#transaction-receipts" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">//</span> <span class="n">Example</span>
|
||
<span class="p">{</span>
|
||
<span class="n">transactionHash</span><span class="p">:</span> <span class="s2">"0x7dec07531aae8178e9d0b0abbd317ac3bb6e8e0fd37c2733b4e0d382ba34c5d2"</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">The</span> <span class="n">block</span> <span class="n">this</span> <span class="n">transaction</span> <span class="n">was</span> <span class="n">mined</span> <span class="n">into</span>
|
||
<span class="n">blockHash</span><span class="p">:</span> <span class="s2">"0xca1d4d9c4ac0b903a64cf3ae3be55cc31f25f81bf29933dd23c13e51c3711840"</span><span class="p">,</span>
|
||
<span class="n">blockNumber</span><span class="p">:</span> <span class="mi">3346629</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">The</span> <span class="n">index</span> <span class="n">into</span> <span class="n">this</span> <span class="n">block</span> <span class="n">of</span> <span class="n">the</span> <span class="n">transaction</span>
|
||
<span class="n">transactionIndex</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">The</span> <span class="n">address</span> <span class="n">of</span> <span class="n">the</span> <span class="n">contract</span> <span class="p">(</span><span class="k">if</span> <span class="n">one</span> <span class="n">was</span> <span class="n">created</span><span class="p">)</span>
|
||
<span class="n">contractAddress</span><span class="p">:</span> <span class="n">null</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">Gas</span>
|
||
<span class="n">cumulativeGasUsed</span><span class="p">:</span> <span class="n">utils</span><span class="o">.</span><span class="n">bigNumberify</span><span class="p">(</span><span class="s2">"42000"</span><span class="p">),</span>
|
||
<span class="n">gasUsed</span><span class="p">:</span> <span class="n">utils</span><span class="o">.</span><span class="n">bigNumberify</span><span class="p">(</span><span class="s2">"21000"</span><span class="p">),</span>
|
||
|
||
<span class="o">//</span> <span class="n">Logs</span>
|
||
<span class="n">log</span><span class="p">:</span> <span class="p">[</span> <span class="p">],</span>
|
||
<span class="n">logsBloom</span><span class="p">:</span> <span class="s2">"0x00"</span> <span class="o">...</span> <span class="p">[</span> <span class="mi">256</span> <span class="nb">bytes</span> <span class="n">of</span> <span class="mi">0</span> <span class="p">]</span> <span class="o">...</span> <span class="s2">"00"</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">Post</span><span class="o">-</span><span class="n">Byzantium</span> <span class="n">hard</span><span class="o">-</span><span class="n">fork</span>
|
||
<span class="n">byzantium</span><span class="p">:</span> <span class="n">false</span>
|
||
|
||
<span class="o">////////////</span>
|
||
<span class="o">//</span> <span class="n">Pre</span><span class="o">-</span><span class="n">byzantium</span> <span class="n">blocks</span> <span class="n">will</span> <span class="n">have</span> <span class="n">a</span> <span class="n">state</span> <span class="n">root</span><span class="p">:</span>
|
||
<span class="n">root</span><span class="p">:</span> <span class="s2">"0x8a27e1f7d3e92ae1a01db5cce3e4718e04954a34e9b17c1942011a5f3a942bf4"</span><span class="p">,</span>
|
||
|
||
<span class="o">////////////</span>
|
||
<span class="o">//</span> <span class="n">Post</span><span class="o">-</span><span class="n">byzantium</span> <span class="n">blocks</span> <span class="n">will</span> <span class="n">have</span> <span class="n">a</span> <span class="n">status</span> <span class="p">(</span><span class="mi">0</span> <span class="n">indicated</span> <span class="n">failure</span> <span class="n">during</span> <span class="n">execution</span><span class="p">)</span>
|
||
<span class="o">//</span> <span class="n">status</span><span class="p">:</span> <span class="mi">1</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="filters">
|
||
<span id="filter"></span><h3>Filters<a class="headerlink" href="#filters" title="Permalink to this headline">¶</a></h3>
|
||
<p>Filtering on topics supports a <a class="reference external" href="https://github.com/ethereum/wiki/wiki/JSON-RPC#a-note-on-specifying-topic-filters">somewhat complicated</a> specification, however,
|
||
for the vast majority of filters, a single topic is usually sufficient (see the example below).</p>
|
||
<p>The <em>EtherscanProvider</em> only supports a single topic.</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">//</span> <span class="n">Example</span>
|
||
<span class="p">{</span>
|
||
<span class="o">//</span> <span class="n">Optional</span><span class="p">;</span> <span class="n">The</span> <span class="nb">range</span> <span class="n">of</span> <span class="n">blocks</span> <span class="n">to</span> <span class="n">limit</span> <span class="n">querying</span> <span class="p">(</span><span class="n">See</span><span class="p">:</span> <span class="n">Block</span> <span class="n">Tags</span> <span class="n">above</span><span class="p">)</span>
|
||
<span class="n">fromBlock</span><span class="p">:</span> <span class="s2">"latest"</span><span class="p">,</span>
|
||
<span class="n">toBlock</span><span class="p">:</span> <span class="s2">"latest"</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">Optional</span><span class="p">;</span> <span class="n">An</span> <span class="n">address</span> <span class="p">(</span><span class="ow">or</span> <span class="n">ENS</span> <span class="n">name</span><span class="p">)</span> <span class="n">to</span> <span class="nb">filter</span> <span class="n">by</span>
|
||
<span class="n">address</span><span class="p">:</span> <span class="n">addressOrName</span><span class="p">,</span>
|
||
|
||
<span class="o">//</span> <span class="n">Optional</span><span class="p">;</span> <span class="n">A</span> <span class="p">(</span><span class="n">possibly</span> <span class="n">nested</span><span class="p">)</span> <span class="nb">list</span> <span class="n">of</span> <span class="n">topics</span>
|
||
<span class="n">topics</span><span class="p">:</span> <span class="p">[</span> <span class="n">topic1</span> <span class="p">]</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="provider-specific-extra-api-calls">
|
||
<h2>Provider Specific Extra API Calls<a class="headerlink" href="#provider-specific-extra-api-calls" title="Permalink to this headline">¶</a></h2>
|
||
<div class="section" id="etherscan">
|
||
<h3>Etherscan<a class="headerlink" href="#etherscan" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . getEtherPrice ( )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with the price of ether in USD.</dd>
|
||
<dt><sup>prototype</sup> . getHistory ( addressOrName [ , startBlock [ , endBlock ] ] )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with an array of <a class="reference internal" href="#transactionresponse"><span class="std std-ref">Transaction Responses</span></a>
|
||
for each transaction to or from <em>addressOrName</em> between <em>startBlock</em> and <em>endBlock</em> (inclusive).</dd>
|
||
</dl>
|
||
<p><strong>Examples</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">provider</span> <span class="o">=</span> <span class="n">new</span> <span class="n">ethers</span><span class="o">.</span><span class="n">providers</span><span class="o">.</span><span class="n">EtherscanProvider</span><span class="p">();</span>
|
||
|
||
<span class="o">//</span> <span class="n">Getting</span> <span class="n">the</span> <span class="n">current</span> <span class="n">Ethereum</span> <span class="n">price</span>
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getEtherPrice</span><span class="p">()</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">price</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">"Ether price in USD: "</span> <span class="o">+</span> <span class="n">price</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
|
||
|
||
<span class="o">//</span> <span class="n">Getting</span> <span class="n">the</span> <span class="n">transaction</span> <span class="n">history</span> <span class="n">of</span> <span class="n">an</span> <span class="n">address</span>
|
||
<span class="n">var</span> <span class="n">address</span> <span class="o">=</span> <span class="s1">'0xb2682160c482eB985EC9F3e364eEc0a904C44C23'</span><span class="p">;</span>
|
||
<span class="n">var</span> <span class="n">startBlock</span> <span class="o">=</span> <span class="mi">3135808</span><span class="p">;</span>
|
||
<span class="n">var</span> <span class="n">endBlock</span> <span class="o">=</span> <span class="mi">5091477</span><span class="p">;</span>
|
||
<span class="n">provider</span><span class="o">.</span><span class="n">getHistory</span><span class="p">(</span><span class="n">address</span><span class="p">,</span> <span class="n">startBlock</span><span class="p">,</span> <span class="n">endBlock</span><span class="p">)</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">history</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">history</span><span class="p">);</span>
|
||
<span class="o">//</span> <span class="p">[</span>
|
||
<span class="o">//</span> <span class="p">{</span>
|
||
<span class="o">//</span> <span class="nb">hash</span><span class="p">:</span> <span class="s1">'0x327632ccb6d7bb47b455383e936b2f14e6dc50dbefdc214870b446603b468675'</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="n">blockHash</span><span class="p">:</span> <span class="s1">'0x0415f0d2741de45fb748166c7dc2aad9b3ff66bcf7d0a127f42a71d3e286c36d'</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="n">blockNumber</span><span class="p">:</span> <span class="mi">3135808</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="n">transactionIndex</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="n">from</span><span class="p">:</span> <span class="s1">'0xb2682160c482eB985EC9F3e364eEc0a904C44C23'</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="n">gasPrice</span><span class="p">:</span> <span class="n">ethers</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">bigNumberify</span><span class="p">(</span><span class="s1">'0x4a817c800'</span><span class="p">),</span>
|
||
<span class="o">//</span> <span class="n">gasLimit</span><span class="p">:</span> <span class="n">ethers</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">bigNumberify</span><span class="p">(</span><span class="s1">'0x493e0'</span><span class="p">),</span>
|
||
<span class="o">//</span> <span class="n">to</span><span class="p">:</span> <span class="s1">'0xAe572713CfE65cd7033774170F029B7219Ee7f70'</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="n">value</span><span class="p">:</span> <span class="n">ethers</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">bigNumberify</span><span class="p">(</span><span class="s1">'0xd2f13f7789f0000'</span><span class="p">),</span>
|
||
<span class="o">//</span> <span class="n">nonce</span><span class="p">:</span> <span class="mi">25</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="n">data</span><span class="p">:</span> <span class="s1">'0x'</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="n">creates</span><span class="p">:</span> <span class="n">null</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="n">networkId</span><span class="p">:</span> <span class="mi">0</span>
|
||
<span class="o">//</span> <span class="p">},</span>
|
||
<span class="o">//</span> <span class="p">{</span>
|
||
<span class="o">//</span> <span class="nb">hash</span><span class="p">:</span> <span class="s1">'0x7c10f2e7125a1fa5e37b54f5fac5465e8d594f89ff97916806ca56a5744812d9'</span><span class="p">,</span>
|
||
<span class="o">//</span> <span class="o">...</span>
|
||
<span class="o">//</span> <span class="p">}</span>
|
||
<span class="o">//</span> <span class="p">]</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="web3provider">
|
||
<h3>Web3Provider<a class="headerlink" href="#web3provider" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="docutils">
|
||
<dt><sup>prototype</sup> . listAccounts ( )</dt>
|
||
<dd>Returns a <a class="reference internal" href="notes.html#promise"><span class="std std-ref">Promise</span></a> with a list of all accounts the node connected
|
||
to this Web3 controls.</dd>
|
||
<dt><sup>prototype</sup> . getSigner( [ address ] )</dt>
|
||
<dd>Returns a <a class="reference internal" href="api-contract.html#custom-signer"><span class="std std-ref">Signer</span></a> that uses an account on the node
|
||
the Web3 object is connected to. If no address is specified, the first
|
||
account on the node is used.</dd>
|
||
</dl>
|
||
<p><strong>Examples</strong></p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">web3Provider</span><span class="o">.</span><span class="n">listAccounts</span><span class="p">()</span><span class="o">.</span><span class="n">then</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">accounts</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">var</span> <span class="n">signer</span> <span class="o">=</span> <span class="n">web3Provider</span><span class="o">.</span><span class="n">getSigner</span><span class="p">(</span><span class="n">accounts</span><span class="p">[</span><span class="mi">1</span><span class="p">]);</span>
|
||
<span class="n">console</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">signer</span><span class="p">);</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<hr class="docutils" />
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
<div class="articleComments">
|
||
|
||
</div>
|
||
</div>
|
||
<footer>
|
||
|
||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||
|
||
<a href="api-contract.html" class="btn btn-neutral float-right" title="Contracts" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
|
||
|
||
|
||
<a href="api-wallet.html" class="btn btn-neutral" title="Wallets" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
|
||
|
||
</div>
|
||
|
||
|
||
<hr/>
|
||
|
||
<div role="contentinfo">
|
||
<p>
|
||
© Copyright 2016, Richard Moore <me@ricmoo.com>.
|
||
|
||
</p>
|
||
</div>
|
||
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||
|
||
</footer>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
var DOCUMENTATION_OPTIONS = {
|
||
URL_ROOT:'./',
|
||
VERSION:'3.0.0',
|
||
COLLAPSE_INDEX:false,
|
||
FILE_SUFFIX:'.html',
|
||
HAS_SOURCE: true,
|
||
SOURCELINK_SUFFIX: '.txt'
|
||
};
|
||
</script>
|
||
<script type="text/javascript" src="_static/jquery.js"></script>
|
||
<script type="text/javascript" src="_static/underscore.js"></script>
|
||
<script type="text/javascript" src="_static/doctools.js"></script>
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript" src="_static/js/theme.js"></script>
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
jQuery(function () {
|
||
SphinxRtdTheme.StickyNav.enable();
|
||
});
|
||
</script>
|
||
|
||
|
||
</body>
|
||
</html> |