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
) => voidExample:
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() => PromiseExample:
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() => PromiseExample:
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) => PromiseExample:
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) => voidExample:
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) => voidExample:
const { storageService } = incognitoJs;
storageService.implement({ ... });Bridge Services
removeBridgeHistory
Cancel/remove a deposit/withrawal history.
Usage:
removeBridgeHistory({
historyId: number,
currencyType: number,
isDecentralized: boolean
}) => PromiseExample:
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 | Default value | 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) => stringExample:
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) => voidExample:
// 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() => stringExample:
const backupObject = wallet.masterAccount.getBackupData();
console.log('Account backup', backupObject);restoreFromBackupData
Restore from backup object for the account.
Usage:
restoreFromBackupData(backupObject) => MasterAccountExample:
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) => voidExample:
// 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) => voidExample:
// 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
) => PromiseExample:
// 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 | Default value | 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 | Default value | 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 | Default value | 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
