Skip to content
Vault Engine SDK
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
README.md

README.md

Vault Engine SDK Documentation

By integrating with Vault Engine, developers can effectively introduce a plug and play blockchain interface to your application, largely side stepping responsibility of developing, managing, and maintaining much of the essential infrastructure critical to blockchain dapp development. For a high level overview of what Vault Engine offers, checkout https://vaultwallet.io/vaultenginelandingpage/

Getting Started

These instructions will get you give you the resources needed to integrate Vault Engine into your product design roadmap, as well as begin development. The below SDK documentation is to be taken as a guide to developing your application with the Vault Engine SDK. Because the SDK is written in Kotlin natively, the specific language you are using may present some differences in coding structure (callbacks etc). To simplify and ease the learning curve, the below documentation is written to be readable and functional, not exact code snippets.

Installing Need actual bash/cmd install stepsExclude from production

-TBH

Usage in React Native - Exclude from production

Import the module(s)

import Vault from 'vault-wrapper';
import { DeviceEventEmitter } from 'react-native';

Vault Engine Primitive Concepts

User Accounts

A user account is created using a unique identifier generated by oAUTH authentication. Applications can easily on-board users with their existing Facebook/Google/etc logins. You can think of a user account as the parent to all other data. A user account associates users' public keys with human readable names, keeps track of a users' contacts and stores metadata (name, email, avatar, phone number). Mnemonics/Private keys are never stored or transmitted to Vault Services. Mnemonic are securely generated by the client side SDK and are backed up by the user. Mnemonics can be imported by the user as well. Users can create unlimited 'Wallet Accounts' of any supported blockchain from their mnemonic. When a user is deleted from the device, the SDK deletes all user data including 'wallet accounts', mnemonic, private keys, cached transaction information, etc.

Wallet Accounts

Within the Vault Engine SDK a 'wallet account' is a single public + private key pair & associated metadata. A wallet account is 'named' by user on creation. Conceptually, you can think of this as a child object of a User Account, because each wallet account is associated with a User.

  • WalletAccount is an object representing the publicAddress, type and nickname

Shared Accounts

A shared account is a wallet account that is shared by a user to another user via a 'connection'. Only the public key & nickname is shared with the other user. Private keys always remain encrypted on the user's device. Shared accounts allow users to transact with each other without external communication of public addresses which is error prone, insecure, and unacceptable UX.

  • SharedAccount is an object representing the public address, type, nickname, and otherUserId

Connections

Connections can be thought of as 'friends' or businesses 'contacts'. This feature of the SDK allows abstraction of public keys and surfacing of simple human readable account names associated definitively with users. Akin to social features, connections can be sent, received, accepted, denied and removed. Flow: User searches for another user by querying a name, email or phone number using Vault Engine. Next the user sends a connection request to the userId found. The otherUser can choose to accept or decline the connection. Finally the users can share accounts and begin transacting. Note that users include: peers, businesses, merchants etc. - anyone integrating with Vault Engine.

Market Data

Vault Engine provides real-time market data for all supported blockchains in USD. Application developers don't have to worry about other data sources. More currencies denominations to be added. (EUR, KRW etc.)

Transaction Data

Vault Engine provides rich transaction data from all supported blockchains. When a user adds a wallet account, all historical transactions associated with that account will be sent to the user. This includes supported smart contract data.

Caching Data

Vault Engine SDK automatically caches all user data very efficiently on the client device! As a result, application developers have access to all synced user data offline. This is a significant performance and user experience improvement for applications running on Vault.

Authentication

Authenticate User

Login/Create new user account by authenticating with valid oAuth JWT.

vault.authenticate(jwt)

Mnemonic

A mnemonic is a human readable list of words that generates a master seed, that in turn, generates wallet accounts for users. It is critical that a mnemonic must be backed-up by the user, as soon as it is generated. If the user's account is deleted from their device, or if the device is lost, the mnemonic is not recoverable! It is the key to accessing a user's wallet accounts. We are working on cloud-backup using the iOS/Android keystore for users with small account values. For products building reward programs or games, personal cloud backup drastically improves user experience. We do not recommend cloud-backup for high value accounts.

Generate a Mnemonic seed

Step 1 - Generate Mnemonic and display it to user so they can back it up. Step 2 - Use import function below to hardware encrypt the mnemonic and store it locally on the device.

var generatedMnemonicSeed = vault.generateSeed(wordSize)
  • wordSize - Word Size can be 16, 20, 24, 28 or 32, larger is more secure.

Import from seed (or generate).

This function takes the generated mnemonic from above or an user input mnemonic, hardware encrypts it, and stores on the device. In addition, this function will automatically create the first wallet account for the user of the specified blockchain type (ethereum, aion, bitcoin). The keyAlias maps to the created mnemonic. The keyAlias is not a password and can stored in application memory.

var keyAlias = vault.importMnemonic(menmonicString, type, addressIndex = 0)
  • mnemonicString - 16, 20, 24, 28 or 32 word string
  • addressIndex - set to 0 (address index zero)
  • keyAlias - key that maps to mnemonic
  • type - blockchain type

Show Mnemonic

Show mnemonic to user to allow them re-backup. User biometric authentication is required to decrypt the mnemonic. CryptoObject is used in conjunction with the SE/TEE to validate user biometric authentication.

var mnemonicSeed = vault.showMnemonic(keyAlias, cryptoObject, callback)
  • keyAlias - key generated when the user securely stored the mnemonic
  • cryptoObject - biometric authentication directed by Android/iOS operating system.

Cloud backup

Easy backup for low value accounts. - Work in progress -

vault.cloudBackup(keyAlias, cryptoObject, callback)
  • keyAlias - key that maps to mnemonic
  • cryptoObject - biometric authentication directed by Android/iOS operating system.

Import cloud backup

var keyAlias = vault.importCloud()

Generate wallet account from a mnemonic

Generate a wallet account using stored mnemonic. After account generation, the wallet account is added to the user's account.

var publicAddress = vault.createAndAddWalletAccount(keyAlias, nickname, addressIndex = 0, type, cryptoObject)
  • keyAlias - key that maps to mnemonic
  • nickname - human readable name for wallet
  • addressIndex - index used to generate wallet
  • cryptoObject - biometric authentication directed by Android/iOS operating system.
  • type - blockchain type

Wallet Account Management

Add/Update Account

Create an 'Wallet Account' after importing or creating a public-private key pair. This adds the wallet account to the user's account.

var accountAdded = vault.addAccount(nickname, publicAddress)
  • nickname - human readable name for wallet
  • publicAddress - public address of the account being added

Remove Account

Deletes wallet account and all associated data from the local device. This includes private keys. Wallet account can be regenerated from mnemonic.

var accountRemoved = vault.removeAccount(publicAddress)

Check If Account Exists

Check if a account exists on the local device.

var hasAccount = vault.hasAccount(publicAddress) 

Get all Wallet Accounts

Retrieve a list of wallet accounts associated of the current user.

vault.getWalletAccounts((walletAccounts) => { 
  console.log(walletAccounts)
})
  • walletAccounts - Array of wallet accounts

Get Wallet Account from KeyAlias

Wallet accounts have a keyAlias that can be used to retrieve wallet account object.

val walletAccount = vault.getWalletAccount(keyAlias)
  • keyAlias - public address of account

Connections and Connection Management

Find a connection

Query the vault wallet server for a particular user based on the searchQuery string.

vault.findConnection(searchQuery, callbackWithIds)
  • searchQuery - String containing search query ex. John Smith

Add a connection

Add a connection to your local connection list and send a connection request to the corrosponding user (think friend request).

vault.addConnection(userId)
  • userId - user ID recieved from the findConnection(...) call

Accept a connection request

Accept a currently pending connection request

vault.acceptConnectionRequest(userIdOrSearchResultId)
  • userIdOrSearchResultID - user ID recieved from the findConnection(...) call SAME THING?????

Decline a connection request

Decline a currently pending connection request

vault.declineConnectionRequest(userIdOrSearchResultId)

Get a pending connection request

Get a list of all currently pending connection requests

var pendingRequests = vault.getPendingRequests()

Get all connections

Retrieve a list of the existing connections associated with the current user.

var connections = vault.getConnections()

Start/Stop Observing Pending Connection Requests

Listen for state changes on currently pending connection requests.

vault.startObservingConnectionsRequests(callback)
...
vault.stopObservingConnectionRequests(callback)

Start/Stop Observing connections changes

Place a listener on connections. For example, I wish to know when another user x has accepted my connection request.

vault.startObservingConnections(callback)
...
vault.stopObservingConnections(callback)

Shared Accounts

Share a wallet account with user

Shared account public account & nickname with another user. You can only share with an existing connection.

vault.shareAccount(userId, walletAccount)
  • userId - other userId
  • walletAccount - public address of account

Unshare a wallet account with user

Remove visibility of a shared account from a specified user on the service.

vault.unshareAccount(userId, walletAccount)
  • userId - other userId
  • walletAccount - public address of account

Get all shared wallet accounts relationships for a user

Retrieve a list of all of the users's shared accounts with other user and other user's shared accounts with user

var sharedAccounts = vault.getSharedAccounts(otherUserId)

Observing shared accounts

Place a listener on a shared account such that you will be notified when there is activity. If a connection shares/unshares an account with user, listener will notify via callback.

vault.startObservingSharedAccounts(callback)
...
vault.stopObservingSharedAccounts(callback)

Transactions

Get Transactions for a specific wallet account

Transactions include ERC20 tokens for ethereum. We can add ERC20 tokens as required by customers.

var transactions = vault.getTransactions(walletAccount, type)
  • walletAccount - public address of account
  • type - ethereum, bitcoin, aion

Get only ERC20/ERC721 Transactions from a specific wallet account

We can add ERC20 token support as required by customers.

var transactions = vault.getContractTransactions(walletAccount, type, contractAddress)
  • walletAccount - public address of account
  • type - ethereum, bitcoin, aion
  • contractAddress - address of ERC20 contract.

Get Balance of a specific wallet account

var transactions = vault.getBalance(walletAccount, type)
  • walletAccount - public address of account
  • type - ethereum, bitcoin, aion

Observe for new transactions for all wallet accounts

After an account is added using vault.addAccount(nickname, publicAddress), observe will trigger a callback for all new transactions from those accounts. This includes ERC20 tokens supported by Vault. We can add ERC20s as required by customers.

vault.startObservingTransactions(callback)
...
vault.stopObservingTransactions(callback)

Send Transaction

Sign and send a transaction to the blockchain

vault.postTransaction(accountFromkeyAlias, toAddress, value, type, cyrptoObject, callback)
  • accountFromKeyAlias - public address of user's from account
  • toAddress - public address
  • value -
  • cryptoObject - biometric authentication directed by Android/iOS operating system
  • type - ethereum, bitcoin, aion

Market Values

Observe market values for specific blockchain

vault.startObservingMarketValues( type, callback )
...
vault.stopObservingMarketValues( type, callback )
  • type - ethereum, bitcoin, aion

Realtime Connectivity Status

Get current connected state

If you need to check if the wallet is currently connected to the blockchain through Vault Wallets backend servers use the following call.

vault.isConnected(
  (connected) => {
    console.log("Connected: " + connected)
  }
);

Observing connected state

Listener will notify if the Wallet is connected or disconnected to the internet.

DeviceEventEmitter.addListener('connectionChange', function(e: Event) {
    console.log("Connected: " + e.connected)
})

Authors

License

To procure a licence to use the Vaule Engine SDK, please visit VaultWallet.io and drop us a line.

You can’t perform that action at this time.