@mcchadwick/fiosdk
Version:
The Foundation for Interwallet Operability (FIO) is a consortium of leading blockchain wallets, exchanges and payments providers that seeks to accelerate blockchain adoption by reducing the risk, complexity, and inconvenience of sending and receiving cryp
350 lines (337 loc) • 22 kB
HTML
<html class="default no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>@fioprotocol/fiosdk</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
<div class="tsd-page-toolbar">
<div class="container">
<div class="table-wrap">
<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
<div class="field">
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
<input id="tsd-search-field" type="text" />
</div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li>
</ul>
<a href="index.html" class="title">@fioprotocol/fiosdk</a>
</div>
<div class="table-cell" id="tsd-widgets">
<div id="tsd-filter">
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
<div class="tsd-filter-group">
<div class="tsd-select" id="tsd-filter-visibility">
<span class="tsd-select-label">All</span>
<ul class="tsd-select-list">
<li data-value="public">Public</li>
<li data-value="protected">Public/Protected</li>
<li data-value="private" class="selected">All</li>
</ul>
</div>
<input type="checkbox" id="tsd-filter-inherited" checked />
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
<input type="checkbox" id="tsd-filter-only-exported" />
<label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label>
</div>
</div>
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
</div>
</div>
</div>
</div>
<div class="tsd-page-title">
<div class="container">
<ul class="tsd-breadcrumb">
<li>
<a href="globals.html">Globals</a>
</li>
</ul>
<h1>@fioprotocol/fiosdk</h1>
</div>
</div>
</header>
<div class="container container-main">
<div class="row">
<div class="col-8 col-content">
<div class="tsd-panel tsd-typography">
<a href="#fio-typescript-sdk" id="fio-typescript-sdk" style="color: inherit; text-decoration: none;">
<h1>FIO TypeScript SDK</h1>
</a>
<p>The Foundation for Interwallet Operability (FIO) is a consortium of leading blockchain wallets, exchanges and payments providers that seeks to accelerate blockchain adoption by reducing the risk, complexity, and inconvenience of sending and receiving cryptoassets.</p>
<p>For information on FIO, visit the <a href="https://fio.foundation">FIO website</a>.</p>
<p>For information on the FIO Chain, API, and SDKs visit the <a href="https://developers.fioprotocol.io">FIO Protocol Developer Hub</a>.</p>
<a href="#technology" id="technology" style="color: inherit; text-decoration: none;">
<h1>Technology</h1>
</a>
<p>The FIO TypeScript SDK is built using tsc, to generate the JavaScript files.</p>
<a href="#version" id="version" style="color: inherit; text-decoration: none;">
<h1>Version</h1>
</a>
<p>Visit the <a href="https://developers.fioprotocol.io">FIO Protocol Developer Hub</a> to get information on FIO SDK versions. Only use an SDK that has a major version number that matches the current FIO Protocol blockchain major version number (e.g. 1.x.x).</p>
<a href="#installing-fio-typescript-sdk-using-npm" id="installing-fio-typescript-sdk-using-npm" style="color: inherit; text-decoration: none;">
<h1>Installing FIO TypeScript SDK, using npm:</h1>
</a>
<a href="#the-npm-version-is-here" id="the-npm-version-is-here" style="color: inherit; text-decoration: none;">
<h2>The NPM Version is here:</h2>
</a>
<pre><code><span class="hljs-meta">@fioprotocol</span>/fiosdk</code></pre>
<a href="#building-the-fio-typescript-sdk-manually" id="building-the-fio-typescript-sdk-manually" style="color: inherit; text-decoration: none;">
<h1>Building The FIO TypeScript SDK, manually</h1>
</a>
<a href="#building-fio-typescript-sdk-manually" id="building-fio-typescript-sdk-manually" style="color: inherit; text-decoration: none;">
<h4>Building FIO TypeScript SDK, manually</h4>
</a>
<p>Navigate to the "fiosdk_typescript" folder, run yarn to install its dependencies, then run tsc to compile. Before running the test refer to the "Workflow for using the SDK with TestNet" section of this README.</p>
<pre><code>cd fiosdk_typescript
yarn
tsc
npm test (<span class="hljs-keyword">if</span> you would like <span class="hljs-keyword">to</span> <span class="hljs-builtin-name">run</span> the unit tests)</code></pre>
<a href="#errors-with-compiling-the-sdks" id="errors-with-compiling-the-sdks" style="color: inherit; text-decoration: none;">
<h3>Errors with compiling the SDKs</h3>
</a>
<a href="#unable-to-find-tsc" id="unable-to-find-tsc" style="color: inherit; text-decoration: none;">
<h4>Unable to find tsc</h4>
</a>
<p>Make sure to install typescript by running, this command in terminal:</p>
<pre><code>sudo npm <span class="hljs-keyword">install</span> -g typescript</code></pre>
<a href="#generating-documentation" id="generating-documentation" style="color: inherit; text-decoration: none;">
<h1>Generating Documentation</h1>
</a>
<p>TypeDoc is installed as a dev dependency. Documentation is pre-generated and included with the source code. To manually generate the documentation run: </p>
<pre><code><span class="hljs-keyword">cd</span> fiosdk_typescript
<span class="hljs-string">./build_docs.sh</span></code></pre><p>The documentation will appear in the folder "documentation" in the root of the project.</p>
<a href="#issues-installing-typedoc" id="issues-installing-typedoc" style="color: inherit; text-decoration: none;">
<h2>Issues Installing TypeDoc?</h2>
</a>
<p>If typedoc command is not found, install typedoc using the npm global command:</p>
<pre><code><span class="hljs-built_in">npm</span> install --<span class="hljs-built_in">global</span> typedoc</code></pre>
<a href="#using-the-sdk" id="using-the-sdk" style="color: inherit; text-decoration: none;">
<h1>Using the SDK</h1>
</a>
<p>The SDK uses a singleton model requiring initialization in the constructor as these parameters are referenced in subsequent SDK Calls.</p>
<a href="#base-url-for-testnet" id="base-url-for-testnet" style="color: inherit; text-decoration: none;">
<h2>Base URL for TestNet</h2>
</a>
<pre><code>http:<span class="hljs-regexp">//</span>testnet.fioprotocol.io<span class="hljs-regexp">/v1/</span></code></pre>
<a href="#testnet-monitor-tool" id="testnet-monitor-tool" style="color: inherit; text-decoration: none;">
<h2>TestNet Monitor Tool</h2>
</a>
<pre><code><span class="hljs-symbol">https:</span><span class="hljs-comment">//monitor.testnet.fioprotocol.io/</span></code></pre>
<a href="#initializing-the-sdk" id="initializing-the-sdk" style="color: inherit; text-decoration: none;">
<h2>Initializing the SDK</h2>
</a>
<pre><code>fetch = require('node-fetch')
const fetchJson = async<span class="hljs-function"> (<span class="hljs-params">uri</span>, <span class="hljs-params">opts</span> = {}) =></span> {
return fetch(uri, opts)
}
privateKey/publicKey - the wallet user's <span class="hljs-keyword">private</span>/public keys
baseURL - the base URL <span class="hljs-keyword">to</span> the FIO Protocol blockchain API (e.g., http:<span class="hljs-comment">//testnet.fioprotocol.io/v1/)</span>
fetchjson - a reference <span class="hljs-keyword">to</span> fetchJson - this is the <span class="hljs-keyword">module</span> <span class="hljs-keyword">to</span> use for http post/get calls (see above for an example)
registerMockUrl - the URL <span class="hljs-keyword">of</span> the server used <span class="hljs-keyword">to</span> auto-register FIO names for wallet users. This is only used by wallets that have deployed a central server used <span class="hljs-keyword">to</span> register names on their domain. It is used by the registerOnBehalfOfUser <span class="hljs-keyword">method</span>
constructor(
privateKey: <span class="hljs-built_in">string</span>,
publicKey: <span class="hljs-built_in">string</span>,
baseUrl: <span class="hljs-built_in">string</span>,
fetchjson: fetchJson,
registerMockUrl = '',
)</code></pre>
<a href="#using-the-sdk-1" id="using-the-sdk-1" style="color: inherit; text-decoration: none;">
<h2>Using the SDK</h2>
</a>
<a href="#example-usage-in-javascript" id="example-usage-in-javascript" style="color: inherit; text-decoration: none;">
<h3>Example Usage in JavaScript</h3>
</a>
<pre><code>const fio = require('@fioprotocol/fiosdk');
this.fioSDK = <span class="hljs-keyword">new</span> fio.<span class="hljs-constructor">FIOSDK(<span class="hljs-params">privateFioKey</span>, <span class="hljs-params">publicFioKey</span>, '<span class="hljs-params">http</span>:<span class="hljs-operator">/</span><span class="hljs-operator">/</span><span class="hljs-params">testnet</span>.<span class="hljs-params">fioprotocol</span>.<span class="hljs-params">io</span><span class="hljs-operator">/</span><span class="hljs-params">v1</span><span class="hljs-operator">/</span>', <span class="hljs-params">this</span>.<span class="hljs-params">fetchJson</span>, '')</span></code></pre>
<a href="#workflow-for-using-the-sdk-with-testnet" id="workflow-for-using-the-sdk-with-testnet" style="color: inherit; text-decoration: none;">
<h1>Workflow for using the SDK with TestNet</h1>
</a>
<p>Most Signed API calls charge fees and require a FIO address that is associated with the user making the call. </p>
<a href="#creating-a-test-account-with-fio-tokens" id="creating-a-test-account-with-fio-tokens" style="color: inherit; text-decoration: none;">
<h4>Creating a test account with FIO tokens</h4>
</a>
<p>When running a test you will want to register addresses and transfer funds. But, registering a new address for the first time requires FIO tokens. Therefore, some manual setup is required to associate FIO tokens with a FIO public key. To set up a FIO public key with FIO tokents in a test environment:</p>
<ol>
<li>Manually create two private/public FIO key pairs <ol>
<li>Navigate to the website: <a href="https://monitor.testnet.fioprotocol.io">https://monitor.testnet.fioprotocol.io</a></li>
<li>Select the 'Create Keypair' button (top left of the website)</li>
<li>Copy the keypairs and FIO Internal Account </li>
</ol>
</li>
<li>Manually register a FIO address for both of these FIO key pairs. <ol>
<li>Navigate to the website: <a href="https://monitor.testnet.fioprotocol.io">https://monitor.testnet.fioprotocol.io</a></li>
<li>Select the 'Register Address' button</li>
<li>Type in a FIO address </li>
<li>Paste in one of the public keys (created above)</li>
<li>Select the 'Create' button</li>
<li>Do this for each public key pair (twice). The created FIO address will be in this format, "mytest:fiotestnet"</li>
</ol>
</li>
<li>Manually transfer funds into these FIO addresses.<ol>
<li>Navigate to the website: <a href="https://monitor.testnet.fioprotocol.io">https://monitor.testnet.fioprotocol.io</a></li>
<li>Select the 'Faucet' button</li>
<li>Paste in one of the public keys (created above)</li>
<li>Select the 'Send Coins' button</li>
<li>Do this for each public key pair (twice)</li>
</ol>
</li>
<li>These FIO public addresses now have funds available for making Signed API calls.</li>
<li>Edit the test script to add these FIO addresses and the private/public FIO key pairs<ol>
<li>Edit the privateKey, publicKey, privateKey2, publicKey2, testFioAddressName, testFioAddressName2 variables in the testnet.spec file (/fiofoundation-io-fiosdk/tests/testnet.spec)</li>
</ol>
</li>
<li>Run the tests:
npm test</li>
</ol>
<a href="#when-calling-a-signed-api-call-that-charges-fees" id="when-calling-a-signed-api-call-that-charges-fees" style="color: inherit; text-decoration: none;">
<h4>When calling a Signed API call that charges FEES,</h4>
</a>
<p>Use the following steps to determine the fee and pass it to the signed call.</p>
<pre><code><span class="hljs-number">1.</span> Call getFee <span class="hljs-built_in">to</span> <span class="hljs-built_in">get</span> <span class="hljs-keyword">the</span> fee <span class="hljs-keyword">for</span> <span class="hljs-keyword">the</span> Signed API call
<span class="hljs-number">2.</span> Call <span class="hljs-keyword">the</span> API Signed call <span class="hljs-keyword">with</span> <span class="hljs-keyword">the</span> fee</code></pre>
<a href="#example-code" id="example-code" style="color: inherit; text-decoration: none;">
<h1>Example Code</h1>
</a>
<pre><code>Example code is located here:
\examples
For <span class="hljs-keyword">an</span> example <span class="hljs-keyword">of</span> how <span class="hljs-built_in">to</span> generate <span class="hljs-built_in">keys</span> <span class="hljs-keyword">using</span> <span class="hljs-keyword">the</span> SDK, see <span class="hljs-keyword">the</span> sample project here:
\examples
\GenerateFioKeys
For <span class="hljs-keyword">an</span> example <span class="hljs-keyword">on</span> <span class="hljs-title">how</span> <span class="hljs-title">to</span> <span class="hljs-title">instantiate</span> <span class="hljs-title">the</span> <span class="hljs-title">SDK</span>, <span class="hljs-title">and</span> <span class="hljs-title">register</span> <span class="hljs-title">a</span> <span class="hljs-title">fio</span> <span class="hljs-title">address</span>. <span class="hljs-title">See</span> <span class="hljs-title">the</span> <span class="hljs-title">sample</span> <span class="hljs-title">project</span> <span class="hljs-title">here</span>:
\examples
\RegisterFioAddress</code></pre>
<a href="#fio-privatepublic-keys" id="fio-privatepublic-keys" style="color: inherit; text-decoration: none;">
<h1>FIO Private/Public Keys?</h1>
</a>
<p>The SDK provides calls to generate FIO Private/Public Key pairs. </p>
<a href="#generating-fio-keys" id="generating-fio-keys" style="color: inherit; text-decoration: none;">
<h3>Generating FIO Keys</h3>
</a>
<p>The user's FIO private/public key can be generated by calling these methods on the sdk:</p>
<pre><code>createPrivateKeyMnemonic <span class="hljs-keyword">OR </span>createPrivateKey
<span class="hljs-keyword">AND
</span>derivedPublicKey</code></pre>
<a href="#example-usage" id="example-usage" style="color: inherit; text-decoration: none;">
<h1>Example Usage</h1>
</a>
<pre><code>For <span class="hljs-keyword">an</span> example <span class="hljs-keyword">of</span> how <span class="hljs-built_in">to</span> generate <span class="hljs-built_in">keys</span> <span class="hljs-keyword">using</span> <span class="hljs-keyword">the</span> SDK, see <span class="hljs-keyword">the</span> sample project here:
\examples
\GenerateFioKeys</code></pre>
<a href="#example-key-generation-code" id="example-key-generation-code" style="color: inherit; text-decoration: none;">
<h3>Example Key Generation Code</h3>
</a>
<pre><code>using <span class="hljs-built_in">npm</span>, create a javascript file (<span class="hljs-string">'index.js), and run "node index.js"
i.e. JavaScript code ('</span>index.js):
<span class="hljs-keyword">const</span> fio = <span class="hljs-built_in">require</span>(<span class="hljs-string">'@fioprotocol/fiosdk'</span>);
<span class="hljs-keyword">const</span> mnemonic = <span class="hljs-string">'valley alien library bread worry brother bundle hammer loyal barely dune brave'</span>
async <span class="hljs-keyword">function</span> genKeysFromMnemonic () {
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">""</span>)
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">"From This Mnemonic:"</span>)
<span class="hljs-built_in">console</span>.log(mnemonic)
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">""</span>)
<span class="hljs-keyword">const</span> privateKeyRes = await fio.FIOSDK.createPrivateKeyMnemonic(mnemonic)
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">"private key generated:"</span>)
<span class="hljs-built_in">console</span>.log((privateKeyRes.fioKey))
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">""</span>)
<span class="hljs-keyword">const</span> publicKeyRes = fio.FIOSDK.derivedPublicKey(privateKeyRes.fioKey)
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">"public key generated"</span>)
<span class="hljs-built_in">console</span>.log((publicKeyRes.publicKey))
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">""</span>)
}
genKeysFromMnemonic()</code></pre>
<a href="#manually-creating-keys-without-using-the-fio-typescript-sdk" id="manually-creating-keys-without-using-the-fio-typescript-sdk" style="color: inherit; text-decoration: none;">
<h3>Manually Creating Keys without using the FIO Typescript SDK?</h3>
</a>
<p>The following information can be used to manually generate FIO keys:</p>
<p>FIO Keys use SLIP-235 for BIP-0044.
<a href="https://github.com/satoshilabs/slips/blob/master/slip-0044.md">https://github.com/satoshilabs/slips/blob/master/slip-0044.md</a></p>
<p>Following the EOS example of private and public key generation. We replace EOS slip '194' with '235'. And 'EOS' public key prefix with 'FIO'.
<a href="https://eosio.stackexchange.com/questions/397/generate-eos-keys-from-mnemonic-seed">https://eosio.stackexchange.com/questions/397/generate-eos-keys-from-mnemonic-seed</a></p>
<a href="#fio-key-derivation-path" id="fio-key-derivation-path" style="color: inherit; text-decoration: none;">
<h2>FIO Key Derivation Path:</h2>
</a>
<p>"44'/235'/0'/0/0"</p>
<a href="#fio-key-generation-testing" id="fio-key-generation-testing" style="color: inherit; text-decoration: none;">
<h2>FIO Key Generation Testing</h2>
</a>
<p>Using this mnemonic phrase:
"valley alien library bread worry brother bundle hammer loyal barely dune brave"</p>
<p>This is the expected Private Key:
"5Kbb37EAqQgZ9vWUHoPiC2uXYhyGSFNbL6oiDp24Ea1ADxV1qnu"</p>
<p>This is the expected Public Key:
"FIO5kJKNHwctcfUM5XZyiWSqSTM5HTzznJP9F3ZdbhaQAHEVq575o"</p>
<a href="#version-102" id="version-102" style="color: inherit; text-decoration: none;">
<h2>Version 1.0.2</h2>
</a>
<p>Bug Fix to method: addPublicAddresses - TechnologyProviderId (i.e. TPID), was not being set correctly for this method.</p>
<a href="#version-101" id="version-101" style="color: inherit; text-decoration: none;">
<h2>Version 1.0.1</h2>
</a>
<p>Added method: registerOwnerFioAddress - allows a wallet to register a fio address owned by a different public key
Updated Validation Methods
Updated Documentation on FIOSDK instantiation</p>
<a href="#version-100" id="version-100" style="color: inherit; text-decoration: none;">
<h2>Version 1.0.0</h2>
</a>
<p>Added additional Unit Tests for Encryption. Comparing and Validating results across the kotlin, iOS and typescript SDKs.
No changes to the SDK code base.</p>
<a href="#version-092" id="version-092" style="color: inherit; text-decoration: none;">
<h2>Version 0.9.2</h2>
</a>
<p>Updated and cleaned up SDK code base.
Finalization of method names and parameter names and order</p>
</div>
</div>
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
<nav class="tsd-navigation primary">
<ul>
<li class="globals ">
<a href="globals.html"><em>Globals</em></a>
</li>
</ul>
</nav>
<nav class="tsd-navigation secondary menu-sticky">
<ul class="before-current">
<li class=" tsd-kind-class">
<a href="classes/fiosdk.html" class="tsd-kind-icon">FIOSDK</a>
</li>
<li class=" tsd-kind-variable">
<a href="globals.html#ecc" class="tsd-kind-icon">Ecc</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<footer class="with-border-bottom">
<div class="container">
<h2>Legend</h2>
<div class="tsd-legend-group">
<ul class="tsd-legend">
<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
</ul>
</div>
</div>
</footer>
<div class="container tsd-generator">
<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p>
</div>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
</body>
</html>