<svgxmlns="http://www.w3.org/2000/svg"aria-hidden="true"x="0px"y="0px"viewBox="0 0 100 100"width="15"height="15"class="icon outbound"><pathfill="currentColor"d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygonfill="currentColor"points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div><!----></nav><ulclass="sidebar-links"><li><ahref="/"class="sidebar-link">Home</a></li><li><ahref="/how-it-works.html"class="sidebar-link">How it works?</a><ulclass="sidebar-sub-headers"></ul></li><li><ahref="/getting-started.html"class="active sidebar-link">Getting Started</a><ulclass="sidebar-sub-headers"><liclass="sidebar-sub-header"><ahref="/getting-started.html#installation"class="sidebar-link">Installation</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#importing-the-library"class="sidebar-link">Importing the library</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#connecting-to-a-web3-provider"class="sidebar-link">Connecting to a web3 provider</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#enhancing-your-contract-objects"class="sidebar-link">Enhancing your contract objects</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#reacting-to-data"class="sidebar-link">Reacting to data</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#tracking-state"class="sidebar-link">Tracking state</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#tracking-events"class="sidebar-link">Tracking events</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#tracking-balances"class="sidebar-link">Tracking balances</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#getting-block-data-gas-prices-and-block-time"class="sidebar-link">Getting block data, gas prices and block time</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#subscriptions"class="sidebar-link">Subscriptions</a></li><liclass="sidebar-sub-header"><ahref="/getting-started.html#cleanup"class="sidebar-link">Cleanup</a></li></ul></li><li><sectionclass="sidebar-group depth-0"><pclass="sidebar-heading"><span>Integrations</span><!----></p><ulclass="sidebar-links sidebar-group-items"><li><ahref="/integrations-overview.html"class="sidebar-link">Overview</a></li><li><ahref="/react.html"class="sidebar-link">React</a><ulclass="sidebar-sub-headers"></ul></li><li><ahref="/vue.html"class="sidebar-link">Vue</a><ulclass="sidebar-sub-headers"></ul></li><li><sectionclass="sidebar-group is-sub-group depth-1"><pclass="sidebar-heading"><span>Redux</span><!----></p><ulclass="sidebar-links sidebar-group-items"><li><ahref="/redux.html"class="sidebar-link">redux</a><ulclass="sidebar-sub-headers"></ul></li><li><ahref="/redux-observable.html"class="sidebar-link">redux-observable</a></li></ul></section></li><li><ahref="/reactive-graphql.html"class="sidebar-link">reactive-graphql</a><ulclass="sidebar-sub-headers"></ul></li><li><ahref="/apollo-client.html"class="sidebar-link">apollo-client</a><ulclass="sidebar-sub-headers"></ul></li></ul></section></li><li><ahref="/tutorial.html"class="sidebar-link">Tutorial</a></li><li><ahref="/api.html"class="sidebar-link">API</a><ulclass="sidebar-sub-headers"><liclass="sidebar-sub-header"><ahref="/api.html#general"class="sidebar-link">General</a></li><liclass="sidebar-sub-header"><ahref="/api.html#contract-methods"class="sidebar-link">Contract methods</a></li><liclass="sidebar-sub-header"><ahref="/api.html#blocks-gas-price-and-block-time"class="sidebar-link">Blocks, gas price and block time</a></li><liclass="sidebar-sub-header"><ahref="/api.html#low-level-api-for-data-tracking"class="sidebar-link">Low level API for data tracking</a></li></ul></li></ul></aside><mainclass="page"><divclass="theme-default-content content__default"><h1id="getting-started"><ahref="#getting-started"
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br><spanclass="line-number">4</span><br><spanclass="line-number">5</span><br></div></div><h2id="connecting-to-a-web3-provider"><ahref="#connecting-to-a-web3-provider"class="header-anchor">#</a> Connecting to a web3 provider</h2><p>To interact with the EVM, <strong>Subspace</strong> requires a valid Web3 object, connected to a provider</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code><spanclass="token keyword">const</span> subspace <spanclass="token operator">=</span><spanclass="token keyword">new</span><spanclass="token class-name">Subspace</span><spanclass="token punctuation">(</span>web3<spanclass="token punctuation">)</span><spanclass="token punctuation">;</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br></div></div><p>In addition to the provider, <code>Subspace</code> also accepts an <code>options</code> object with settings that can change its behavior:</p><ul><li><code>dbFilename</code> - Name of the database where the information will be stored (default <code>'subspace.db'</code>)</li><li><code>callInterval</code> - Interval of time in milliseconds to query a contract/address to determine changes in state or balance. It's only used with HttpProviders (default: <code>undefined</code>. Obtains data every block using the average block time as an interval).</li><li><code>refreshLastNBlocks</code> - Ignores last N blocks (from current block), stored in the local db and refresh them via a web3 subscription. Useful for possible reorgs (default: 12),</li><li><code>disableSubscriptions</code> - Subspace by default will attempt to use websocket subscriptions if the current provider supports them, otherwise it will use polling because it asumes the provider is an HttpProvider. This functionality can be disabled by passing true to this option. (default: <code>undefined</code>)</li></ul><h2id="enhancing-your-contract-objects"><ahref="#enhancing-your-contract-objects"class="header-anchor">#</a> Enhancing your contract objects</h2><p>Subspace provides a method to enhance your web3 Contract objects: <code>subspace.contract(instance|{abi,address})</code>. Calling this method will return a new contract object decorated with a <code>.track()</code> method for your contract view functions and events.</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code><spanclass="token keyword">const</span> myRxContract <spanclass="token operator">=</span> subspace<spanclass="token punctuation">.</span><spanclass="token function">contract</span><spanclass="token punctuation">(</span>myContractInstance<spanclass="token punctuation">)</span><spanclass="token punctuation">;</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br></div></div><p>You can also instantiate a contract directly by passing the contract ABI and its address:</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code><spanclass="token keyword">const</span> myRXContract <spanclass="token operator">=</span> subspace<spanclass="token punctuation">.</span><spanclass="token function">contract</span><spanclass="token punctuation">(</span><spanclass="token punctuation">{</span>abi<spanclass="token operator">:</span><spanclass="token operator">...</span><spanclass="token punctuation">.</span><spanclass="token punctuation">,</span> address<spanclass="token operator">:</span><spanclass="token string">'0x1234...CDEF'</span><spanclass="token punctuation">}</span><spanclass="token punctuation">)</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br></div></div><h2id="reacting-to-data"><ahref="#reacting-to-data"class="header-anchor">#</a> Reacting to data</h2><p>Once it's initialized, you can use <strong>Subspace</strong>'s methods to track the contract state, events and balances. These functions return RxJS Observables which you can subscribe to, and obtain and transform the observed data via operators.</p><divclass="custom-block tip"><pclass="custom-block-title">What is an Observable?</p><p>The <code>Observable</code> type can be used to model push-based data sources such as DOM events, timer intervals, and sockets. In addition, observables are:</p><ul><li>Compositional: Observables can be composed with higher-order combinators.</li><li>Lazy: Observables do not start emitting data until an observer has subscribed.</li></ul></div><h4id="further-read"><ahref="#further-read"class="header-anchor">#</a> Further read</h4><ul><li><ahref="https://rxjs-dev.firebaseapp.com/guide/observable"target="_blank"rel="noopener noreferrer">RxJS Observables<svgxmlns="http://www.w3.org/2000/svg"aria-hidden="true"x="0px"y="0px"viewBox="0 0 100 100"width="15"height="15"class="icon outbound"><pathfill="currentColor"d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygonfill="currentColor"points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></li></ul><h2id="tracking-state"><ahref="#tracking-state"class="header-anchor">#</a> Tracking state</h2><p>You can track changes to a contract state variable, by specifying the view function and arguments to call and query the contract.</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code><spanclass="token keyword">const</span> stateObservable$ <spanclass="token operator">=</span> Contract<spanclass="token punctuation">.</span>methods<spanclass="token punctuation">.</span><spanclass="token function">functionName</span><spanclass="token punctuation">(</span>functionArgs<spanclass="token punctuation">)</span><spanclass="token punctuation">.</span><spanclass="token function">track</span><spanclass="token punctuation">(</span><spanclass="token punctuation">)</span><spanclass="token punctuation">;</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br></div></div><divclass="custom-block tip"><pclass="custom-block-title">Tracking the public variables of a contract</p><p>State variables implicity create a <code>view</code> function when they're defined as <code>public</code>. The <code>functionName</code> would be the same as the variable name, and <code>functionArgs</code> will have a value when the type is a <code>mapping</code> or <code>array</code> (since these require an index value to query them).</p></div><p>Example:</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code><spanclass="token keyword">const</span> productTitle$ <spanclass="token operator">=</span> ProductList<spanclass="token punctuation">.</span>methods<spanclass="token punctuation">.</span><spanclass="token function">products</span><spanclass="token punctuation">(</span><spanclass="token number">0</span><spanclass="token punctuation">)</span><spanclass="token punctuation">.</span><spanclass="token function">track</span><spanclass="token punctuation">(</span><spanclass="token punctuation">)</span><spanclass="token punctuation">.</span><spanclass="token function">map</span><spanclass="token punctuation">(</span><spanclass="token string">"title"</span><spanclass="token punctuation">)</span><spanclass="token punctuation">;</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br><spanclass="line-number">4</span><br><spanclass="line-number">5</span><br><spanclass="line-number">6</span><br><spanclass="line-number">7</span><br></div></div><p>The subscription will be triggered whenever the title changes</p><h2id="tracking-events"><ahref="#tracking-events"class="header-anchor">#</a> Tracking events</h2><p>You can track events and react to their returned values.</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code><spanclass="token keyword">const</span> eventObservable$ <spanclass="token operator">=</span> Contract<spanclass="token punctuation">.</span>event<spanclass="token punctuation">.</span>eventName<spanclass="token punctuation">.</span><spanclass="token function">track</span><spanclass="token punctuation">(</span><spanclass="token punctuation">)</span><spanclass="token punctuation">;</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br><spanclass="line-number">4</span><br><spanclass="line-number">5</span><br><spanclass="line-number">6</span><br><spanclass="line-number">7</span><br></div></div><p><strong>Event Sourcing</strong></p><p>You can easily do event sourcing with subspace.</p><p>For e.g: if you needed to get the average rating of the last 5 events:</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code><spanclass="token keyword">import</span><spanclass="token punctuation">{</span> $average<spanclass="token punctuation">,</span> $latest <spanclass="token punctuation">}</span><spanclass="token keyword">from</span><spanclass="token string">"@embarklabs/subspace"</span><spanclass="token punctuation">;</span>
console<spanclass="token punctuation">.</span><spanclass="token function">log</span><spanclass="token punctuation">(</span><spanclass="token string">"average rating of the last 5 events is "</span><spanclass="token operator">+</span> rating<spanclass="token punctuation">)</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br><spanclass="line-number">4</span><br><spanclass="line-number">5</span><br><spanclass="line-number">6</span><br><spanclass="line-number">7</span><br></div></div><h2id="tracking-balances"><ahref="#tracking-balances"class="header-anchor">#</a> Tracking balances</h2><p>You can also track changes in both ETH and ERC20 token balances for each mined block or time interval depending on the <code>callInterval</code> configured.</p><p>Tracking ETH balance in an address:</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code><spanclass="token keyword">const</span> address <spanclass="token operator">=</span><spanclass="token string">"0x0001020304050607080900010203040506070809"</span><spanclass="token punctuation">;</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br></div></div><divclass="custom-block warning"><p>Balances are returned as a string containing the value in <em>wei</em>.</p></div><h2id="getting-block-data-gas-prices-and-block-time"><ahref="#getting-block-data-gas-prices-and-block-time"class="header-anchor">#</a> Getting block data, gas prices and block time</h2><p>Subspace also provides a way to always receive the latest block object:</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code>subspace<spanclass="token punctuation">.</span><spanclass="token function">trackBlock</span><spanclass="token punctuation">(</span><spanclass="token punctuation">)</span><spanclass="token punctuation">.</span><spanclass="token function">subscribe</span><spanclass="token punctuation">(</span><spanclass="token parameter">block</span><spanclass="token operator">=></span><spanclass="token punctuation">{</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br></div></div><p>If you don't need all the block information, but just the block number, you can use instead:</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code>subspace<spanclass="token punctuation">.</span><spanclass="token function">trackBlockNumber</span><spanclass="token punctuation">(</span><spanclass="token punctuation">)</span><spanclass="token punctuation">.</span><spanclass="token function">subscribe</span><spanclass="token punctuation">(</span><spanclass="token parameter">blockNumber</span><spanclass="token operator">=></span><spanclass="token punctuation">{</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br></div></div><p>You can also access the average block time. This takes in account only the last 10 blocks:</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code>subspace<spanclass="token punctuation">.</span><spanclass="token function">trackAverageBlocktime</span><spanclass="token punctuation">(</span><spanclass="token punctuation">)</span><spanclass="token punctuation">.</span><spanclass="token function">subscribe</span><spanclass="token punctuation">(</span><spanclass="token parameter">blocktimeMS</span><spanclass="token operator">=></span><spanclass="token punctuation">{</span>
console<spanclass="token punctuation">.</span><spanclass="token function">log</span><spanclass="token punctuation">(</span><spanclass="token string">"The average block time in milliseconds is: "</span><spanclass="token punctuation">,</span> blocktimeMS<spanclass="token punctuation">)</span><spanclass="token punctuation">;</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br></div></div><p>Finally, if you want to obtain the most up to date median gas price:</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code>subspace<spanclass="token punctuation">.</span><spanclass="token function">trackGasPrice</span><spanclass="token punctuation">(</span><spanclass="token punctuation">)</span><spanclass="token punctuation">.</span><spanclass="token function">subscribe</span><spanclass="token punctuation">(</span><spanclass="token parameter">gasPrice</span><spanclass="token operator">=></span><spanclass="token punctuation">{</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br></div></div><h2id="subscriptions"><ahref="#subscriptions"class="header-anchor">#</a> Subscriptions</h2><p>Once you have an <code>Observable</code>, you may receive a stream of data by creating a subscription. Subscriptions are triggered each time an observable emits a new value. These subscription receive a callback that must have a parameter which represents the value received from the observable (a contract state variable, an event, or the balance of an address); and they return an object representing the subscription.</p><p>Subscriptions can be disposed by executing the method <code>unsubscribe()</code> liberating the resource held by it:</p><divclass="language-js line-numbers-mode"><preclass="language-js"><code><spanclass="token keyword">const</span> myBalanceObservable$ <spanclass="token operator">=</span> subspace<spanclass="token punctuation">.</span><spanclass="token function">trackBalance</span><spanclass="token punctuation">(</span>address<spanclass="token punctuation">,</span> tokenAddress<spanclass="token punctuation">)</span><spanclass="token punctuation">;</span>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</span><br><spanclass="line-number">3</span><br><spanclass="line-number">4</span><br><spanclass="line-number">5</span><br><spanclass="line-number">6</span><br><spanclass="line-number">7</span><br><spanclass="line-number">8</span><br></div></div><h4id="further-read-2"><ahref="#further-read-2"class="header-anchor">#</a> Further read</h4><ul><li><ahref="https://rxjs-dev.firebaseapp.com/guide/subscription"target="_blank"rel="noopener noreferrer">RxJS Subscriptions<svgxmlns="http://www.w3.org/2000/svg"aria-hidden="true"x="0px"y="0px"viewBox="0 0 100 100"width="15"height="15"class="icon outbound"><pathfill="currentColor"d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygonfill="currentColor"points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></li></ul><h2id="cleanup"><ahref="#cleanup"class="header-anchor">#</a> Cleanup</h2><p>If <strong>Subspace</strong> is not needed anymore, you need can invoke <code>close()</code> to dispose and perform the cleanup necessary to remove the internal subscriptions and interval timers created by <strong>Subspace</strong> during its normal execution, thus avoiding any potential memory leak.</p><divclass="language- line-numbers-mode"><preclass="language-text"><code>subspace.close();
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br></div></div><divclass="custom-block warning"><pclass="custom-block-title">What about subscriptions created with our observables?</p><p><code>close()</code> will dispose any web3 subscription created when using a Subspace tracking method, however any subscription to an observable must still be unsubscribed manually. The npm package <code>subsink</code> can be used to clear all the observables' subscriptions at once.</p></div></div><footerclass="page-edit"><!----><!----></footer><divclass="page-nav"><pclass="inner"><spanclass="prev">
