mirror of https://github.com/status-im/specs.git
2 lines
21 KiB
HTML
2 lines
21 KiB
HTML
<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <title>14/Dapp browser API usage - Status Specification</title> <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"> <link rel="stylesheet" href="/assets/css/just-the-docs-default.css"> <script type="text/javascript" src="/assets/js/vendor/lunr.min.js"></script> <script type="text/javascript" src="/assets/js/just-the-docs.js"></script> <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Begin Jekyll SEO tag v2.7.1 --> <title>14/Dapp browser API usage | Status Specification</title> <meta name="generator" content="Jekyll v4.2.1" /> <meta property="og:title" content="14/Dapp browser API usage" /> <meta property="og:locale" content="en_US" /> <link rel="canonical" href="https://specs.status.im/draft/14" /> <meta property="og:url" content="https://specs.status.im/draft/14" /> <meta property="og:site_name" content="Status Specification" /> <meta name="twitter:card" content="summary" /> <meta property="twitter:title" content="14/Dapp browser API usage" /> <script type="application/ld+json"> {"@type":"WebPage","url":"https://specs.status.im/draft/14","headline":"14/Dapp browser API usage","@context":"https://schema.org"}</script> <!-- End Jekyll SEO tag --> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-link" viewBox="0 0 24 24"> <title>Link</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"> <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path> </svg> </symbol> <symbol id="svg-search" viewBox="0 0 24 24"> <title>Search</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search"> <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-doc" viewBox="0 0 24 24"> <title>Document</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file"> <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline> </svg> </symbol> </svg> <div class="side-bar"> <div class="site-header"> <a href="https://specs.status.im/" class="site-title lh-tight"> Status Specification </a> <a href="#" id="menu-button" class="site-button"> <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg> </a> </div> <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav"> <ul class="nav-list"><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/spec/" class="nav-list-link">Stable specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/spec/1" class="nav-list-link">1/CLIENT</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/10" class="nav-list-link">10/WAKU-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/11" class="nav-list-link">11/WAKU-MAILSERVER</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/15" class="nav-list-link">15/NOTIFICATIONS</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/2" class="nav-list-link">2/ACCOUNT</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/3" class="nav-list-link">3/WHISPER-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/4" class="nav-list-link">4/WHISPER-MAILSERVER</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/5" class="nav-list-link">5/SECURE-TRANSPORT</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/6" class="nav-list-link">6/PAYLOADS</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/8" class="nav-list-link">8/EIPS</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/9" class="nav-list-link">9/ETHEREUM-USAGE</a></li></ul></li><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/draft/" class="nav-list-link">Draft specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/draft/12" class="nav-list-link">12/IPFS gateway for Sticker Pack</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/13" class="nav-list-link">13/3RD-PARTY-USAGE</a></li><li class="nav-list-item active"><a href="https://specs.status.im/draft/14" class="nav-list-link active">14/Dapp browser API usage</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/16" class="nav-list-link">16/Keycard Usage for Wallet and Chat Keys</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/3" class="nav-list-link">3/WHISPER-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/6" class="nav-list-link">6/PAYLOADS</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/7" class="nav-list-link">7/GROUP-CHAT</a></li></ul></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/raw/" class="nav-list-link">Raw specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/raw/16" class="nav-list-link">16/PUSH-NOTIFICATION-SERVER</a></li></ul></li><li class="nav-list-item"><a href="https://specs.status.im/development" class="nav-list-link">DEVELOPMENT</a></li><li class="nav-list-item"><a href="https://specs.status.im/style-guideline" class="nav-list-link">STYLE-GUIDELINE</a></li></ul> </nav> <footer class="site-footer"> This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. </footer> </div> <div class="main" id="top"> <div id="main-header" class="main-header"> <div class="search"> <div class="search-input-wrap"> <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search Status Specification" aria-label="Search Status Specification" autocomplete="off"> <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label> </div> <div id="search-results" class="search-results"></div> </div> </div> <div id="main-content-wrap" class="main-content-wrap"> <nav aria-label="Breadcrumb" class="breadcrumb-nav"> <ol class="breadcrumb-nav-list"> <li class="breadcrumb-nav-list-item"><a href="https://specs.status.im/draft/">Draft specs</a></li> <li class="breadcrumb-nav-list-item"><span>14/Dapp browser API usage</span></li> </ol> </nav> <div id="main-content" class="main-content" role="main"> <h1 id="dapp-browser-api-usage"> <a href="#dapp-browser-api-usage" class="anchor-heading" aria-labelledby="dapp-browser-api-usage"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Dapp browser API usage </h1> <h2 id="table-of-contents"> <a href="#table-of-contents" class="anchor-heading" aria-labelledby="table-of-contents"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Table of Contents </h2> <ol> <li><a href="#abstract">Abstract</a></li> <li><a href="#definitions">Definitions</a></li> <li><a href="#overview">Overview</a></li> <li><a href="#usage">Usage</a> <ul> <li><a href="#properties">Properties</a> <ul> <li><a href="#isStatus"><code class="language-plaintext highlighter-rouge">isStatus</code></a></li> <li><a href="#status"><code class="language-plaintext highlighter-rouge">status</code></a></li> </ul> </li> <li><a href="#methods">Methods</a> <ul> <li><a href="#isConnected"><code class="language-plaintext highlighter-rouge">isConnected</code></a></li> <li><a href="#request"><code class="language-plaintext highlighter-rouge">request</code></a></li> <li><a href="#scanQRCode"><code class="language-plaintext highlighter-rouge">scanQRCode</code></a></li> </ul> </li> <li><a href="#unused">Unused</a> <ul> <li><a href="#enable"><code class="language-plaintext highlighter-rouge">enable</code></a></li> <li><a href="#send"><code class="language-plaintext highlighter-rouge">send</code></a></li> <li><a href="#sendAsync"><code class="language-plaintext highlighter-rouge">sendAsync</code></a></li> <li><a href="#sendSync"><code class="language-plaintext highlighter-rouge">sendSync</code></a></li> </ul> </li> </ul> </li> <li><a href="#implementation">Implementation</a></li> <li><a href="#compatibility">Compatibility</a></li> <li><a href="#changelog">Changelog</a></li> <li><a href="#copyright">Copyright</a></li> </ol> <h2 id="abstract"> <a href="#abstract" class="anchor-heading" aria-labelledby="abstract"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Abstract </h2> <p>This document describes requirements that an application must fulfill in order to provide a proper environment for Dapps running inside a browser. A description of the Status Dapp API is provided, along with an overview of bidirectional communication underlying the API implementation. The document also includes a list of EIPs that this API implements.</p> <h2 id="definitions"> <a href="#definitions" class="anchor-heading" aria-labelledby="definitions"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Definitions </h2> <div class="table-wrapper"><table> <thead> <tr> <th>Term</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><strong>Webview</strong></td> <td>Platform-specific browser core implementation.</td> </tr> <tr> <td><strong>Ethereum Provider</strong></td> <td>A JS object (<code class="language-plaintext highlighter-rouge">window.ethereum</code>) injected into each web page opened in the browser providing web3 compatible provider.</td> </tr> <tr> <td><strong>Bridge</strong></td> <td>A set of facilities allow bidirectional communication between JS code and the application.</td> </tr> </tbody> </table></div> <h2 id="overview"> <a href="#overview" class="anchor-heading" aria-labelledby="overview"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Overview </h2> <p>The application should expose an Ethereum Provider object (<code class="language-plaintext highlighter-rouge">window.ethereum</code>) to JS code running inside the browser. It is important to have the <code class="language-plaintext highlighter-rouge">window.ethereum</code> object available before the page loads, otherwise Dapps might not work correctly.</p> <p>Additionally, the browser component should also provide bidirectional communication between JS code and the application.</p> <h2 id="usage-in-dapps"> <a href="#usage-in-dapps" class="anchor-heading" aria-labelledby="usage-in-dapps"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Usage in Dapps </h2> <p>Dapps can use the below properties and methods of <code class="language-plaintext highlighter-rouge">window.ethereum</code> object.</p> <h3 id="properties"> <a href="#properties" class="anchor-heading" aria-labelledby="properties"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Properties </h3> <h4 id="isstatus"> <a href="#isstatus" class="anchor-heading" aria-labelledby="isstatus"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">isStatus</code> </h4> <p>Returns true. Can be used by the Dapp to find out whether it’s running inside Status.</p> <h4 id="status"> <a href="#status" class="anchor-heading" aria-labelledby="status"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">status</code> </h4> <p>Returns a <code class="language-plaintext highlighter-rouge">StatusAPI</code> object. For now it supports one method: <code class="language-plaintext highlighter-rouge">getContactCode</code> that sends a <code class="language-plaintext highlighter-rouge">contact-code</code> request to Status.</p> <h3 id="methods"> <a href="#methods" class="anchor-heading" aria-labelledby="methods"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Methods </h3> <h4 id="isconnected"> <a href="#isconnected" class="anchor-heading" aria-labelledby="isconnected"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">isConnected</code> </h4> <p>Similarly to Ethereum JS API <a href="https://github.com/ethereum/wiki/wiki/JavaScript-API#web3isconnected">docs</a>, it should be called to check if connection to a node exists. On Status, this fn always returns true, as once Status is up and running, node is automatically started.</p> <h4 id="scanqrcode"> <a href="#scanqrcode" class="anchor-heading" aria-labelledby="scanqrcode"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">scanQRCode</code> </h4> <p>Sends a <code class="language-plaintext highlighter-rouge">qr-code</code> Status API request.</p> <h4 id="request"> <a href="#request" class="anchor-heading" aria-labelledby="request"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">request</code> </h4> <p><code class="language-plaintext highlighter-rouge">request</code> method as defined by EIP-1193.</p> <h3 id="unused"> <a href="#unused" class="anchor-heading" aria-labelledby="unused"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Unused </h3> <p>Below are some legacy methods that some Dapps might still use.</p> <h4 id="enable-deprecated"> <a href="#enable-deprecated" class="anchor-heading" aria-labelledby="enable-deprecated"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">enable</code> (DEPRECATED) </h4> <p>Sends a <code class="language-plaintext highlighter-rouge">web3</code> Status API request. It returns a first entry in the list of available accounts.</p> <p>Legacy <code class="language-plaintext highlighter-rouge">enable</code> method as defined by <a href="https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1102.md">EIP1102</a>.</p> <h4 id="send-deprecated"> <a href="#send-deprecated" class="anchor-heading" aria-labelledby="send-deprecated"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">send</code> (DEPRECATED) </h4> <p>Legacy <code class="language-plaintext highlighter-rouge">send</code> method as defined by <a href="https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1193.md">EIP1193</a>.</p> <h4 id="sendasync-deprecated"> <a href="#sendasync-deprecated" class="anchor-heading" aria-labelledby="sendasync-deprecated"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">sendAsync</code> (DEPRECATED) </h4> <p>Legacy <code class="language-plaintext highlighter-rouge">sendAsync</code> method as defined by <a href="https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1193.md">EIP1193</a>.</p> <h4 id="sendsync-deprecated"> <a href="#sendsync-deprecated" class="anchor-heading" aria-labelledby="sendsync-deprecated"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">sendSync</code> (DEPRECATED) </h4> <p>Legacy <code class="language-plaintext highlighter-rouge">send</code> method.</p> <h2 id="implementation"> <a href="#implementation" class="anchor-heading" aria-labelledby="implementation"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Implementation </h2> <p>Status uses a <a href="https://github.com/status-im/react-native-webview">forked version</a> of <a href="https://github.com/react-native-community/react-native-webview">react-native-webview</a> to display web or dapps content. The fork provides an Android implementation of JS injection before page load. It is required in order to properly inject Ethereum Provider object.</p> <p>Status injects two JS scripts:</p> <ul> <li><a href="https://github.com/status-im/status-react/blob/develop/resources/js/provider.js">provider.js</a>: <code class="language-plaintext highlighter-rouge">window.ethereum</code> object</li> <li><a href="https://github.com/status-im/status-react/blob/develop/resources/js/webview.js">webview.js</a>: override for <code class="language-plaintext highlighter-rouge">history.pushState</code> used internally</li> </ul> <p>Dapps running inside a browser communicate with Status Ethereum node by means of a <em>bridge</em> provided by react-native-webview library. The bridge allows for bidirectional communication between browser and Status. In order to do so, it injects a special <code class="language-plaintext highlighter-rouge">ReactNativeWebview</code> object into each page it loads.</p> <p>On Status (React Native) end, <code class="language-plaintext highlighter-rouge">react-native-webview</code> library provides <code class="language-plaintext highlighter-rouge">WebView.injectJavascript</code> function on a webview component that allows to execute arbitrary code inside the webview. Thus it is possible to inject a function call passing Status node response back to the Dapp.</p> <p>Below is the table briefly describing what functions/properties are used. More details available in package <a href="https://github.com/react-native-community/react-native-webview/blob/master/docs/Guide.md#communicating-between-js-and-native">docs</a>.</p> <div class="table-wrapper"><table> <thead> <tr> <th>Direction</th> <th>Side</th> <th>Method</th> </tr> </thead> <tbody> <tr> <td>Browser->Status</td> <td>JS</td> <td><code class="language-plaintext highlighter-rouge">ReactNativeWebView.postMessage()</code></td> </tr> <tr> <td>Browser->Status</td> <td>RN</td> <td><code class="language-plaintext highlighter-rouge">WebView.onMessage()</code></td> </tr> <tr> <td>Status->Browser</td> <td>JS</td> <td><code class="language-plaintext highlighter-rouge">ReactNativeWebView.onMessage()</code></td> </tr> <tr> <td>Status->Browser</td> <td>RN</td> <td><code class="language-plaintext highlighter-rouge">WebView.injectJavascript()</code></td> </tr> </tbody> </table></div> <h2 id="compatibility"> <a href="#compatibility" class="anchor-heading" aria-labelledby="compatibility"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Compatibility </h2> <p>Status browser supports the following EIPs:</p> <ul> <li><a href="https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1102.md">EIP1102</a>: <code class="language-plaintext highlighter-rouge">eth_requestAccounts</code> support</li> <li><a href="https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1193.md">EIP1193</a>: <code class="language-plaintext highlighter-rouge">connect</code>, <code class="language-plaintext highlighter-rouge">disconnect</code>, <code class="language-plaintext highlighter-rouge">chainChanged</code>, and <code class="language-plaintext highlighter-rouge">accountsChanged</code> event support is not implemented</li> </ul> <h2 id="changelog"> <a href="#changelog" class="anchor-heading" aria-labelledby="changelog"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Changelog </h2> <div class="table-wrapper"><table> <thead> <tr> <th style="text-align: center">Version</th> <th>Comment</th> </tr> </thead> <tbody> <tr> <td style="text-align: center"><a href="https://github.com/specs/...">0.1.0</a></td> <td>Initial Release</td> </tr> </tbody> </table></div> <h2 id="copyright"> <a href="#copyright" class="anchor-heading" aria-labelledby="copyright"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Copyright </h2> <p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p> </div> </div> <div class="search-overlay"></div> </div> </body> </html>
|