Get Started

Table of Contents

[TOC]

Get Started

Install

$ yarn add incognito-js

Follow example at https://github.com/incognitochain/sdk-v2/blob/master/sample/test-node.js

Usage

Nodejs

Copy wasm binary to your root project:

cp node_modules/incognito-js/privacy.wasm .

const incognitoJs = require('incognito-js');

// Load WebAssembly:
await incognitoJs.goServices.implementGoMethodUseWasm();

Follow this step to [implement storage.](#Implement storage)

Browser

Copy wasm binary to your root project:

cp node_modules/incognito-js/privacy.wasm .

Module

import * as incognitoJs from 'incognito-js';

// Load WebAssembly:
await incognitoJs.goServices.implementGoMethodUseWasm();

Or import Javascript file to html (incognitoJs object is attached to your browser window object.)

<script src="...incognito-js/build/web/browser/index.js"></script>
<script>
	// Load WebAssembly:
	await incognitoJs.goServices.implementGoMethodUseWasm();
</script>

Follow this step to [implement storage.](#Implement storage)

React Native

Please use react-native-incognito-js for React Native and follow this step to [implement storage.](#Implement storage)

Implement storage

incognitoJs need to cache some data into storage to work correctly like coin infomation, tx history,... So please implement incognitoJs storage service:

incognitoJs.storageService.implement({
  // namespace: 'YOUR-STORAGE-NAMESPACE',
  setMethod: (key: string, value: string) {
    return new Promise((resolve, reject) => {
        // store data to storage device, for example:
        // localStorage on Browser
        // AsyncStorage on React Native

        resolve();

        if (error) {
            reject(error);
        }
    });
  },
  getMethod: (key: string) {
    return new Promise(() => {
        // get data from device storage
    });
  },
  removeMethod: (key: string) {
    return new Promise(() => {
        // remove data from device storage
    });
  },
});

API

Config

setConfig

Usage:

setConfig (
	logMethod: (message: string) => void (pass null to disable log)
	chainURL: string //
	apiURL: string
	mainnet: boolean // update this property will change apiURL & chainURL if they are not defined
	wasmPath: string // path to the binary file, the SDK will find the wasm in where it was executed
) => void

Example:

const { setConfig  } = incognitoJs;

// config incognito JS use testnet
setConfig({ mainnet: false });

// config incognito JS use log
setConfig({ logMethod: function(logMessage) {
	console.log(`LOG: ${logMessage}`);
} });

getConfig

Get current config.

History services

getTxHistoryByPublicKey

Get histories belong to an account (use account's publicKeySerialized as a key).

Usage:

getTxHistoryByPublicKey(
	publicKeySerialized: string,
	tokenId?: string
) => Promise<TxHistoryModel[]>

Example:

const { historyServices  } = incognitoJs;

// load all tx histories for native token
const histories = await historyServices.getTxHistoryByPublicKey(
	account.key.keySet.publicKeySerialized, // publicKeySerialized of the account
	null // token id or use null for native token
);

checkCachedHistories

Get update for all cached tx histories (tx histories are send/init/burn/trade/contribute transactions).

Usage:

checkCachedHistories() => Promise

Example:

const { historyServices  } = incognitoJs;

await historyServices.checkCachedHistories(); // all tx histories were up to date

// load all tx histories for native token
const updatedHistories = await account.nativeToken.getTxHistories();

Go Services

incognitoJs uses some methods implemented by Go to improve performance. Go will be built to WASM (Web Assembly) for Nodejs/browser enviroments and Gomobile for React Native.

implementGoMethodUseWasm

Used on Nodejs/browser enviroments.

Usage:

implementGoMethodUseWasm() => Promise

Example:

const { goServices  } = incognitoJs;

await goServices.implementGoMethodUseWasm();

console.log('Go methods were implemented!')

implementGoMethodManually

Implement go methods manually (for React Native). Please use react-native-incognito-js, it is a incognitoJs library wrapper, all Go methods have been implemented already.

Usage:

// define Go methods
const implementData = {
	deriveSerialNumber: (data: string) => string;
	initPrivacyTx: (data: string) => string;
	randomScalars: (data: string) => string;
	staking: (data: string) => string;
	stopAutoStaking: (data: string) => string;,
	initPrivacyTokenTx: (data: string) => string;
	withdrawDexTx: (data: string) => string;
	initPTokenTradeTx: (data: string) => string;
	initPRVTradeTx: (data: string) => string;
	initPTokenContributionTx: (data: string) => string;
	initPRVContributionTx: (data: string) => string;
	initWithdrawRewardTx: (data: string) => string;
	initBurningRequestTx: (data: string) => string;
	generateKeyFromSeed: (data: string) => string;
	scalarMultBase: (data: string) => string;
	hybridEncryptionASM: (data: string) => string;
	hybridDecryptionASM: (data: string) => string;
	generateBLSKeyPairFromSeed: (data: string) => string;
};

// implement
implementGoMethodManually(implementData) => Promise

Example:

const { goServices  } = incognitoJs;

await goServices.implementGoMethodManually({ ... });

console.log('Go methods were implemented!')

Go method name

List of Go method names.

Example:

const { goServices  } = incognitoJs;

console.log(goServices.GO_METHOD_NAMES)

Wallet services

setPrivacyUtilRandomBytesFunc

Implement random bytes function.

Usage:

setPrivacyUtilRandomBytesFunc(Function) => void

Example:

import myRandomByteFunction from '..';
const { walletServices  } = incognitoJs;

walletServices.setPrivacyUtilRandomBytesFunc(myRandomByteFunction);

Storage Services

implement

Implement storage.

Usage:

// implement data
const data = {
	setMethod(key: string, data: string) : Promise;
	getMethod(key: string) : Promise;
	removeMethod(key: string) : Promise
	namespace: string; (optional)
};

// implement
implement(data) => void

Example:

const { storageService  } = incognitoJs;

storageService.implement({ ... });

Bridge Services

removeBridgeHistory

Cancel/remove a deposit/withrawal history.

Usage:

removeBridgeHistory({
	historyId: number,
	currencyType: number,
	isDecentralized: boolean
}) => Promise

Example:

const { bridgeServices   } = incognitoJs;

bridgeServices.removeBridgeHistory({ ... });

Constant

All of constants used in the library.

Example:

const { CONSTANT } = incognitoJs;

console.log('Incognito JS constants:', CONSTANT);

WalletInstance

Public Property	Type	Description
seed	Uint8Array
entropy	number[ ]
mnemonic	string
masterAccount	MasterAccount	The main account in wallet
name	string	Wallet name

init

Init a new wallet.

Usage:

init(passPhrase: string, name?: string) => Promise<WalletInstance>

Example:

const { WalletInstance } = incognitoJs;

const wallet = new WalletInstance();
await wallet.init('my-passphrase', 'TEST-WALLET');

console.log('New wallet', wallet);

backup

Backup wallet with password.

Usage:

backup(password: string) => string

Example:

const backupWalletString = wallet.backup('backup-password');

console.log('Backed up wallet string', backupWalletString);

restore

Restore a wallet from backup.

Usage:

restore(encryptedWallet: string, password: string) => Promise<WalletInstance>

Example:

const { WalletInstance   } = incognitoJs;

const wallet = await WalletInstance.restore(backupWalletString, 'backup-password');

console.log('Restored wallet', wallet);

MasterAccount

MasterAccount is a special account, the Incognito wallet is only have one MasterAccount, this account can contain many Accounts (or AccountInstance)

Public Property	Type	Default value	Description
child	array	[ ]	Array of chilren account
key	KeyWalletModel		Key wallet

getAccounts

Get all child accounts.

Usage:

getAccounts() => <AccountInstance>[ ]

Example:

const accounts = wallet.masterAccount.getAccounts();
console.log('Account list', accounts);

addAccount

Create a child account, shardId will be randomly selected if not provided

Usage:

addAccount(name: string, shardId?: number) => Promise<AccountInstance>

Example:

// create an account with shard ID 3
const account1 = await wallet.masterAccount.addAccount('Account 1', 3);
console.log('Account with shard ID 3', account1);

// create an account with random shardID
const account2 = await wallet.masterAccount.addAccount('Account 2');
console.log('Account with random shard ID', account2);

removeAccount

Remove an account by name.

Usage:

removeAccount(name: string) => void

Example:

// remove account name "Account 1"
wallet.masterAccount.removeAccount('Account 1');

console.log('Remaining accounts', wallet.masterAccount.getAccounts());

importAccount

Import account from its private key.

Usage:

importAccount(name: string, privateKey: string) => Promise<AccountInstance>

Example:

// import account with private key "ABCDEF"
const importedAccount = await wallet.masterAccount.importAccount('Imported account', 'ABCDEF');

console.log('Imported account', importedAccount);

getBackupData

Return backup object for the account.

Usage:

getBackupData() => string

Example:

const backupObject = wallet.masterAccount.getBackupData();
console.log('Account backup', backupObject);

restoreFromBackupData

Restore from backup object for the account.

Usage:

restoreFromBackupData(backupObject) => MasterAccount

Example:

const { MasterAccount } = incognitoJs;
const masterAccount = MasterAccount.restoreFromBackupData(backupObject);

console.log('Restored master account', masterAccount);

AccountInstance

AccountInstance is child account belong to MasterAccount

Public Property	Type	Default value	Description
name	string		Account name
isImport	boolean	false	Is this account was imported or not
key	KeyWalletModel		Key wallet
nativeToken	NativeTokenInstance		Native token is PRV
privacyTokenIds	string[]		List of following PrivacyTokenInstance id

getBLSPublicKeyB58CheckEncode

Get BLS public key.

Usage:

getBLSPublicKeyB58CheckEncode() => Promise<string>

Example:

const blsPublicKey = await account.getBLSPublicKeyB58CheckEncode();

console.log('BLS Public Key', blsPublicKey);

followTokenById

Add a token id to following list of the account.

Usage:

followTokenById(tokenId: string) => void

Example:

// follow pBTC
account.followTokenById("b832e5d3b1f01a4f0623f7fe91d6673461e1f5d37d91fe78c5c2e6183ff39696");

const followingTokens = await account.getFollowingPrivacyToken();
console.log('Following tokens', followingTokens);
console.log('Following token ids', account.privacyTokenIds);

unfollowTokenById

Remove a token id from following list.

Usage:

unfollowTokenById(tokenId: string) => void

Example:

// unfollow pBTC
account.unfollowTokenById("b832e5d3b1f01a4f0623f7fe91d6673461e1f5d37d91fe78c5c2e6183ff39696");

const followingTokens = await account.getFollowingPrivacyToken();
console.log('Following tokens', followingTokens);
console.log('Following token ids', account.privacyTokenIds);

issuePrivacyToken

Issue new Incognito token.

Usage:

issuePrivacyToken({
	tokenName: string,
	tokenSymbol: string,
	supplyAmount: number,
	nativeTokenFee: number
}) => Promise<TxHistoryModel>

Example:

const history = await account.issuePrivacyToken({
	tokenName: 'test token',
	tokenSymbol: 'test',
	supplyAmount: 100000,
	nativeTokenFee: 20 // fee in nano PRV
});

console.log('Issued new token with history', history);

getFollowingPrivacyToken

Get following token(s), if tokenId is not provided, all tokens will be returned.

Usage:

getFollowingPrivacyToken(tokenId?: string)
	=> 	Promise<PrivacyTokenInstance | PrivacyTokenInstance[]>

Example:

// Get all following tokens
const tokens = await account.getFollowingPrivacyToken();
console.log('All following tokens', tokens);

// Get follow token info with ID
const token = await account.getFollowingPrivacyToken('token-id');
console.log('Token info', token);

getNodeRewards

For Node only - Get rewards.

Usage:

getNodeRewards() => Promise<object>

Example:

const rewards = await account.getNodeRewards();
console.log('All rewards', rewards);

getNodeStatus

For Node only - Get node status.

Usage:

getNodeStatus() => Promise<object>

Example:

const status = await account.getNodeStatus();
console.log('Node status', status);

NativeTokenInstance

Public Property	Type	Default value	Description
isNativeToken	boolean	true	Is native token
name	string		Token name
tokenId	string		Token ID
symbol	string		Token symbol
accountKeySet	AccountKeySetModel		Account Key set

getTotalBalance

Get total balance (including pending coins).

Usage:

getTotalBalance() => Promise<BigNumber>

Example:

const balanceBN = await account.nativeToken.getTotalBalance();
console.log('Native token total balance', balanceBN.toNumber());

getAvaiableBalance

Get available balance.

Usage:

getAvaiableBalance() => Promise<BigNumber>

Example:

const balanceBN = await account.nativeToken.getAvaiableBalance();
console.log('Native token available balance', balanceBN.toNumber());

getTxHistories

Get all transaction histories (cached on local).

Usage:

getTxHistories() => Promise<TxHistoryModel[]>

Example:

const histories = await account.nativeToken.getTxHistories();
console.log('Native token tx histories', histories);

transfer

Send native token in Incognito chain.

Usage:

transfer(paymentInfoList: PaymentInfoModel[], nativeFee: number)
	=> Promise<TxHistoryModel>

Example:

const history = await account.nativeToken.transfer(
	[
		{
			paymentAddressStr: otherAccount.key.keySet.paymentAddressKeySerialized,
			amount: 10,
			message: ''
		}
	],
	20 // fee in nano PRV
);
console.log('Native token sent with history', history);

requestStaking

[Node] Send staking request.

Usage:

requestStaking(rewardReceiverPaymentAddress: string, nativeFee: number)
	=> Promise<TxHistoryModel>

Example:

const history = await account.nativeToken.requestStaking(
	receiverAccount.key.keySet.paymentAddressKeySerialized,
	20 // fee in nano PRV
);
console.log('Native token sent stake request with history', history);

pdeContribution

[pDEX] Send PDE contribution.

Usage:

pdeContribution(
	pdeContributionPairID: string,
	contributedAmount: number,
	nativeFee: number
) => Promise<TxHistoryModel>

requestTrade

Send trade request

Usage:

requestTrade (
	tokenIdBuy: string,
	sellAmount: number,
	minimumAcceptableAmount: number,
	nativeFee: number,
	tradingFee: number
) => Promise<TxHistoryModel>

withdrawNodeReward

[Node] Withdraw reward from node.

Usage:

withdrawNodeReward() => Promise<TxHistoryModel>

PrivacyTokenInstance

Public Property	Type	Default value	Description
isPrivacyToken	boolean	true	Is privacy token
name	string		Token name
tokenId	string		Token ID
symbol	string		Token symbol in Incognito chain
accountKeySet	AccountKeySetModel		Account Key set
totalSupply	number		Total supply amount was issued
bridgeInfo	object		External infomations from other chain for this token (only tokens have the `bridgeInfo` can deposit/withdraw)

bridgeInfo

symbol: string; // symbol in other chain
pSymbol: string; // bridge token symbol
name: string; // bridge token name
decimals: number; // decimals in other chain
pDecimals: number; // decimals in Incognito chain
contractID: string;
verified: boolean; // verified by Incognito
type: number; defined in TOKEN_INFO_CONSTANT.BRIDGE_PRIVACY_TOKEN.TYPE
currencyType: number; defined in TOKEN_INFO_CONSTANT.BRIDGE_PRIVACY_TOKEN.CURRENCY_TYPE
status: number;

getTotalBalance

Get total balance (including pending coins).

Usage:

getTotalBalance() => Promise<BigNumber>

Example:

const token = await account.getFollowingPrivacyToken('token-id');
const balanceBN = await token.getTotalBalance();
console.log('Token total balance', balanceBN.toNumber());

getAvaiableBalance

Get available balance.

Usage:

getAvaiableBalance() => Promise<BigNumber>

Example:

const token = await account.getFollowingPrivacyToken('token-id');
const balanceBN = await token.getAvaiableBalance();
console.log('Token available balance', balanceBN.toNumber());

getTxHistories

Get all transaction histories (cached on local).

Usage:

getTxHistories() => Promise<TxHistoryModel[]>

Example:

const token = await account.getFollowingPrivacyToken('token-id');
const histories = await token.getTxHistories();
console.log('Token tx histories', histories);

hasExchangeRate

Is the token has valuable, if true, the token can be used for fee.

Usage:

hasExchangeRate() => Promise<boolean>

Example:

const token = await account.getFollowingPrivacyToken('token-id');
const isHasRate = await token.hasExchangeRate();

console.log(`This token ${isHasRate === true ? 'has' : 'not has'} rate`);

transfer

Send privacy token in Incognito chain.

Usage:

transfer(
	paymentInfoList: PaymentInfoModel[],
	nativeFee: number,
	privacyFee: number
) => Promise<TxHistoryModel>

Example:

const token = await account.getFollowingPrivacyToken('token-id');
const history = await token.transfer(
	[
		{
			paymentAddressStr: otherAccount.key.keySet.paymentAddressKeySerialized,
			amount: 10,
			message: ''
		}
	],
	20, // fee in nano PRV
	0 // the privacy token must has exchange rate to be fee
);
console.log('Privacy token sent with history', history);

burning

Burn the token.

Usage:

transfer(
	outchainAddress: string,
	burningAmount: number,
	nativeFee: number,
	privacyFee: number
) => Promise<TxHistoryModel>

Example:

// burning ETH
const token = await account.getFollowingPrivacyToken('peth-token-id');
const history = await token.burning(
	'ETH wallet address',
	2000, // burning amount,
	20, // fee in nano PRV
	0 // the privacy token must has exchange rate to be fee
);
console.log('Privacy token burned with history', history);

pdeContribution

[pDEX] Send PDE contribution.

Usage:

pdeContribution(
	pdeContributionPairID: string,
	contributedAmount: number,
	nativeFee: number,
	privacyFee: number
) => Promise<TxHistoryModel>

requestTrade

Send trade request.

Usage:

requestTrade (
	tokenIdBuy: string,
	sellAmount: number,
	minimumAcceptableAmount: number,
	nativeFee: number,
	privacyFee: number,
	tradingFee: number
) => Promise<TxHistoryModel>

withdrawNodeReward

[Node] Withdraw reward from node.

Usage:

withdrawNodeReward() => Promise<TxHistoryModel>

bridgeGenerateDepositAddress

Get a temporary deposit address (expired after 60 minutes).

Usage:

bridgeGenerateDepositAddress() => Promise<string>

Example:

// deposit ETH
const token = await account.getFollowingPrivacyToken('peth-token-id');
const ethDepositAddress = await token.bridgeGenerateDepositAddress();

console.log('ETH deposit address', ethDepositAddress);

bridgeWithdraw

Withdraw bridged coins (Convert privacy token to origin, your privacy token will be burned and the origin will be returned). Please notice: withdrawal uses the fee (nativeFee or privacyFee) for burning coins.

Usage:

bridgeWithdraw(
	outchainAddress: string,
	decimalAmount: number,
	nativeFee: number = 0,
	privacyFee: number = 0,
	memo?: string
) => Promise

Example:

// withdraw 0.5 pETH to Ethereum wallet address "ETH-wallett-address'
const token = await account.getFollowingPrivacyToken('peth-token-id');
await token.bridgeWithdraw(
	'ETH-wallett-address',
	0.5,
	20,
	0
);

console.log('ETH withdrew');

bridgeGetHistory

Get deposit/withdrawal history.

Usage:

bridgeGetHistory() => Promise<BridgeHistoryModel[]>

KeyWalletModel

Public Property	Type	Default value	Description
keySet	AccountKeySetModel		Account Key set

AccountKeySetModel

Public Property	Type	Description
privateKeySerialized	string	Private key
paymentAddressKeySerialized	string	Payment address
viewingKeySerialized	string	Viewing key
publicKeySerialized	string	Public key
privateKey	PrivateKeyModel	Private key byte
paymentAddress	PaymentAddressKeyModel	Payment address key byte
viewingKey	ViewingKeyModel	Viewing key byte
publicKeyCheckEncode	string
miningSeedKey	string
validatorKey	string

TxHistoryModel

Tx histories include all transaction histories, not deposit and withdraw and stored in client storage.

Public Property	Type	Description
txId	string
txType	string	Define in CONSTANT.TX_CONSTANT.TX_TYPE
lockTime	number
status	number	Define in CONSTANT.TX_CONSTANT.TX_STATUS. Call `historyServices.checkCachedHistories()` to update status.
nativeTokenInfo	object	Include native token info (fee, amount, coins, payment info)
privacyTokenInfo	object	Include privacy token info (fee, amount, coins, payment info)
meta	any
accountPublicKeySerialized	string
historyType	number	Define in CONSTANT.TX_CONSTANT.HISTORY_TYPE

PaymentInfoModel

Public Property	Type	Default value	Description
paymentAddressStr	string
amount	number
message	string

BridgeHistoryModel

Bridge histories include deposit and withdraw transactions and stored in backend.

Public Property	Type	Description
id	number
userID	number
address	string
expiredAt	string
addressType	number	defined in TOKEN_INFO_CONSTANT.BRIDGE_PRIVACY_TOKEN.ADDRESS_TYPE
status	number	defined in TOKEN_INFO_CONSTANT.BRIDGE_PRIVACY_TOKEN.HISTORY_STATUS
currencyType	number	defined in TOKEN_INFO_CONSTANT.BRIDGE_PRIVACY_TOKEN.CURRENCY_TYPE
walletAddress	string
userPaymentAddress	string
requestedAmount	string
receivedAmount	string
incognitoAmount	string
ethereumTx	string
incognitoTx	string
erc20TokenTx	string
privacyTokenAddress	string
erc20TokenAddress	string
createdAt	string
updatedAt	string
decentralized	number	0 is centralized, 1 is decentralized
outChainTx	string
inChainTx	string

Examples

NodeJS

Source file: sample/test-node.js

Command: yarn test:node

Browser

Source file: sample/index.html

Command: yarn test:browser

React Native

See the Incognito Wallet Template

Name		Name	Last commit message	Last commit date
Latest commit History 210 Commits
build		build
env		env
sample		sample
src		src
.babelrc		.babelrc
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
index.ts		index.ts
jsconfig.json		jsconfig.json
package.json		package.json
privacy.wasm		privacy.wasm
tsconfig.json		tsconfig.json
webpack.config.js		webpack.config.js
yarn.lock		yarn.lock

incognitochain/sdk-v2

Folders and files

Latest commit

History

Repository files navigation

Get Started

Install

Usage

Nodejs

Browser

React Native

Implement storage

API

Config

setConfig

getConfig

History services

getTxHistoryByPublicKey

checkCachedHistories

Go Services

implementGoMethodUseWasm

implementGoMethodManually

Go method name

Wallet services

setPrivacyUtilRandomBytesFunc

Storage Services

implement

Bridge Services

removeBridgeHistory

Constant

WalletInstance

init

backup

restore

MasterAccount

getAccounts

addAccount

removeAccount

importAccount

getBackupData

restoreFromBackupData

AccountInstance

getBLSPublicKeyB58CheckEncode

followTokenById

unfollowTokenById

issuePrivacyToken

getFollowingPrivacyToken

getNodeRewards

getNodeStatus

NativeTokenInstance

getTotalBalance

getAvaiableBalance

getTxHistories

transfer

requestStaking

pdeContribution

requestTrade

withdrawNodeReward

PrivacyTokenInstance

bridgeInfo

getTotalBalance

getAvaiableBalance

getTxHistories

hasExchangeRate

transfer

burning

pdeContribution

requestTrade

withdrawNodeReward

bridgeGenerateDepositAddress

bridgeWithdraw

bridgeGetHistory

KeyWalletModel

AccountKeySetModel

TxHistoryModel

PaymentInfoModel

BridgeHistoryModel

Examples

NodeJS

Browser

Packages