<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#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#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#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"aria-hidden="true"class="header-anchor">#</a> Getting Started</h1><h2id="installation"><ahref="#installation"aria-hidden="true"class="header-anchor">#</a> Installation</h2><p><strong>Subspace</strong> can be used in browser, node and native script environments. To get started install the package <code>@embarklabs/subspace</code> using <code>npm</code> or <code>yarn</code> by executing this command in your project directory:</p><divclass="language-bash line-numbers-mode"
</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 (default: <code>undefined</code>. Obtains data every block).</li><li><code>disableSubscriptions</code> - <code>Subspace</code> 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 <code>HttpProvider</code>. This functionality can be disabled by passing <code>true</code> to this option. (default: <code>false</code>)tionality can be forced by passing <code>true</code> to this option. (default: <code>undefined</code>)</li></ul><h2id="reacting-to-data"><ahref="#reacting-to-data"aria-hidden="true"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="tip custom-block"><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"aria-hidden="true"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"aria-hidden="true"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><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="tip custom-block"><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> would 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></div></div><p>The subscriber will be triggered whenever the title changes</p><h2id="tracking-events"><ahref="#tracking-events"aria-hidden="true"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><spanclass="token function">eventName</span><spanclass="token punctuation">(</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>
</code></pre><divclass="line-numbers-wrapper"><spanclass="line-number">1</span><br><spanclass="line-number">2</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"aria-hidden="true"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="warning custom-block"><p>Balances are returned as a string containing the value in <em>wei</em>.</p></div><h2id="subscriptions"><ahref="#subscriptions"aria-hidden="true"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"aria-hidden="true"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"aria-hidden="true"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="warning custom-block"><pclass="custom-block-title">What about subscriptions created with our observables?</p><p>Any subscription created via the tracking methods must be unsubscribed manually (in the current version).</p></div></div><footerclass="page-edit"><!----><!----></footer><divclass="page-nav"><pclass="inner"><spanclass="prev">