1. General description
Tokium is a SDK that allows to develop blockchain based apps easily without a big technical knowledge of blockchain. Tokium uses a private blockchain hosted on AWS and hosts all assets inside this network.
At this moment, Tokium supports these features:
- Create new accounts.
- Create new assets.
- Create new wallets.
- Secure wallet keys inside secure storage.
- Make transactions.
On this guide, we will all Tokium current features. If you need help with our SDK you can contact us on hello@tokium.one.
1.1 User Dashboard - Create Asset
The first step to use Tokium SDK is create an account and a new asset. You can create a new Tokium account on our User Dashboard. Click Sign Up and create a new account. All account are limited to create only one new asset. If you need to extend your quota, you can contact with us on hello@tokium.one.
With your account registered, you can create your first asset. You only have to go to New Asset and insert your Asset Name, the amount of asset that you will create (you can create more in the feature), and a URL to the background image of your asset card. When you click on Create, you will receive your Address and Private key. Save them on a safe place. You won't recover Private key and you need it to create more assets in the future and make transactions from your wallet.
You can see now your new wallet on My Wallets section.
1.2 Environment
Tokium has been developed to be compatible with React and React Native. You can use the SDK with more platforms, but we don't guarantee the correct behavior. We will integrate Tokium on more platforms in the future.
To integrate Tokium SDK on your project you need to start a new React / React Native app. You can check React / React Native documentation on the next links:
- https://github.com/facebook/create-react-app
- https://github.com/react-community/create-react-native-app
- https://expo.io/learn
Then, you need to install Tokium SDK:
npm i --save @tokiumcoins/sdk-node
or
yarn add @tokiumcoins/sdk-node
With NPM dependency installed, you can start to use Tokium SDK on your React / React Native app:
import Tokium from 'sdk-node';
const currentUser = Tokium.currentUser;
currentUser.login('email@email.com', 'password').then(() => {
console.info(profile);
}).catch(err => {
console.error(err);
});
1.3 Tokium SDK features
1.3.1 Create new account
import Tokium from 'sdk-node';
const profile = new Tokium.Profile();
profile.signup('email@email.com', 'password').then(() => {
console.info(profile);
}).catch(err => {
console.error(err);
});
1.3.2 Login
import Tokium from 'sdk-node';
const currentUser = Tokium.currentUser;
currentUser.login('email@email.com', 'password').then(() => {
console.info(currentUser);
}).catch(err => {
console.error(err);
});
1.3.3 Logout
import Tokium from 'sdk-node';
const currentUser = Tokium.currentUser;
currentUser.logout().then(() => {
console.info(currentUser);
}).catch(err => {
console.error(err);
});
1.3.4 Get your wallets
import Tokium from 'sdk-node';
const currentUser = Tokium.currentUser;
console.info(currentUser.wallets);
1.3.5 Create new wallet
import Tokium from 'sdk-node';
const wallet = new Tokium.Wallet();
wallet.create('your-asset-name', '').then(() => {
console.info(wallet);
}).catch(err => {
console.error(err);
});
Result:
Wallet {
walletPin: Int(),
privateKey: String(),
address: String(),
asset: Asset(),
balance: Int(),
status: String()
}
IMPORTANT: Private Key is not saved on our systems, it's your responsibility to save it on a safe place. You can save it on your local storage with Secure wallet keys inside secure storage
Tokium SDK Feature. You can read about it on the next point.
1.3.6 Secure wallet keys inside secure storage
This feature allows you to save private keys on a safe place inside your mobile. Your keys will be saved locally. If you change your mobile, you need to transfer the keys to the new device.
When you create a new wallet, privateKey value is defined and is the best moment to execute this feature.
Save key
wallet.savePrivateKey(wallet.privateKey).then(() => {
console.info(wallet);
}).catch(err => {
console.error(err);
});
Get key
Only works if you have saved privateKey before.
wallet.savePrivateKey().then(() => {
console.info(wallet);
}).catch(err => {
console.error(err);
});
Technical details
Tokium SDK tries to save privateKey on the safest place disponible. The default places where Tokium tries to save your keys are:
- SecureStorage: Keychain on iOS or encrypted storage on Android. This storage will be used if you use Expo (React Native).
- AsyncStorage: React Native basic storage. Unencrypted, asynchronous and persistent.
- LocalStorage: React Web storage. Unencrypted, asynchronous and persistent.
If you want to use an alternative storage you can overwrite global.storageController
object with the next class example:
class StorageMock {
constructor() {};
setItem(key, data) {
return new Promise((resolve) => {
resolve();
});
};
getItem(key) {
return new Promise((resolve) => {
const examplePrivKey = 'fake_priv_key';
resolve(examplePrivKey);
});
};
removeItem(key) {
return new Promise((resolve) => {
resolve();
});
};
}
1.3.7 Make transactions
Transactions are composed of two steps. The first step is to report the transaction to our systems. The second step is to sign the transaction.
This two steps can be done from different devices. One user can request a payment and other can sign and complete it.
import Tokium from 'sdk-node';
const transaction = new Tokium.Transaction()
const fromWallet = {
address: '<from_wallet_address>',
privateKey: '<from_wallet_private_key>',
walletPin: ''
};
const txData = {
amount = 100,
assetName: '<wallet_asset_name>',
fromAddress: fromWallet.address,
toAddress: '<to_wallet_address>'
}
transaction.init(txData).then(() => {
transaction.initTransaction(fromWallet, true).then(() => {
console.info('Transaction completed!');
}).catch(err => {
console.error('Error signing transaction', err);
});
}).catch(err => {
console.error('Error initializing transaction', err);
});
1.3.8 Generate pkpass of new wallet
From Node.js:
import Tokium from 'sdk-node';
const wallet = new Tokium.Wallet();
wallet.create('your-asset-name', '').then(() => {
wallet.getPassbook(path).then(() => {
// Passbook saved
})
}).catch(err => {
console.error(err);
});
Direct download:
- GET: https://api.tokium.one/test/wallet/passbook/[your-asset-name]/[wallet-address]
- Header: authtoken [firebase-auth-token]
2 Advanced documentation
Profile
import Tokium from 'sdk-node';
const profile = new Tokium.Profile();
Profile Data Model
Profile {
uid: String(),
email: String(),
allowedAssets: Int(),
wallets: [ Wallet(), Wallet(), ... ],
status: String(),
listeners: [ Object(), Object(), ... ]
}
Flow
Status | Meaning |
---|---|
needlogin | Need to do login(). |
loggedin | Loggued in, you can call logout(), and other methods. |
Methods
Login
profile.login('email@email.com', 'password').then(() => {
console.info(profile);
}).catch(err => {
console.error(err);
});
Logout
profile.logout().then(() => {
console.info(profile);
}).catch(err => {
console.error(err);
});
Is logged in
let isLoggedIn = profile.isLoggedIn(); // True or false
Get Wallets
profile.getWallets().then(() => {
console.info(profile.wallets);
}).catch(err => {
console.error(err);
});
Get Transactions
profile.getTransactions(type, limit).then(transactions => { // type = 'from' or 'to'
console.info(transactions); // [ Transaction(), Transaction(), ... ]
}).catch(err => {
console.error(err);
});
Events
wallets-changed
import Tokium from 'sdk-node';
Tokium.on('wallets-changed', profile => {
console.info(profile); // Profile()
});
waiting-transactions-changed
import Tokium from 'sdk-node';
Tokium.on('waiting-transactions-changed', transactions => {
console.info(transactions); // [ Transaction(), Transaction(), ... ]
})
profile-changed
import Tokium from 'sdk-node';
Tokium.on('profile-changed', profile => {
console.info(profile); // Profile()
})
Asset
import Tokium from 'sdk-node';
const asset = new Tokium.Asset();
Asset Data Model
Asset {
assetName: String(),
amount: Int(),
enabled: Boolean(),
image: String(),
owner: String(),
server: String(),
status: String()
}
Flow
Status | Meaning |
---|---|
needinit | Need to do init(). |
notexists | Asset doesn't exist on database. Need to do create(). |
exists | Asset exists on database. You can use it to create wallets and do transactions. |
Methods
init()
asset.init(assetData).then(() => {
console.info(asset);
}).catch(err => {
console.error(err);
});
- assetData:
let assetData = {
assetName: String(), // Required
amount: Int(), // Optional (will be overwritten if asset exists)
image: 'http://...' // Optional (will be overwritten if asset exists)
}
- Note:
If assetName exists, its properties will be loaded and status will be exists
. If it doesn't exist, status will be notexists
and you can create it with asset.create()
.
create()
asset.amount = Int(); // Required
asset.image = 'http://...'; // Required
asset.create().then(() => {
console.info(asset);
}).catch(err => {
console.error(err);
});
Transaction
import Tokium from 'sdk-node';
const transaction = new Tokium.Transaction();
Transaction Data Model
Transaction {
amount: Int(),
assetName: String(),
fromAddress: String(),
toAddress: String(),
transactionKey: String(),
txHex: String(),
status: String()
}
Flow
Status | Meaning |
---|---|
needinit | Need to do init(). |
local | Transaction doesn't exist on database and is local. Need to do requestTransaction() or initTransaction(). |
waiting | Transaction exists on database but it is waiting to be sent completed. Need to do initTransaction() with signOnline = true . |
completed | Transaction is completed. Nothing more to do. |
Methods
init()
transaction.init(txData).then(() => {
console.info(transaction);
}).catch(err => {
console.error(err);
});
- txData - DM 1
txData = {
transactionKey: String()
}
Allows to recover a transaction from database.
- txData - DM 2
txData = {
amount: Int(),
assetName: String(),
fromAddress: String(),
toAddress: String()
}
Allows to start a new transaction.
requestTransaction()
transaction.requestTransaction().then(() => {
console.info(transaction);
}).catch(err => {
console.error(err);
});
Register the transaction on database but it isn't sended to blockchain. Very usefull to request transactions to other users.
initTransaction()
transaction.initTransaction(wallet, signOnline).then(() => {
console.info(transaction);
}).catch(err => {
console.error(err);
});
- wallet
let wallet = {
address: String(),
privateKey: String(),
walletPin: String()
};
or
let wallet = new Tokium.Wallet();
- signOnline
If true
, the transaction will be signed online with wallet.privateKey
and wallet.walletPin
. If false
, transaction.txHex
need to be signed offline and be sent later.
NOTE: For the moment, only true
is supported.
Wallet
import Tokium from 'sdk-node';
const wallet = new Tokium.Wallet();
Wallet Data Model
Wallet {
walletPin: Int(),
privateKey: String(),
address: String(),
asset: Asset(),
balance: Int(),
status: String()
}
Flow
Status | Meaning |
---|---|
needlogin | Need to do init() or create(). |
initiated | Wallet is initiated and you can use it. |
Methods
init()
wallet.init(walletData).then(() => {
console.info(wallet);
}).catch(err => {
console.error(err);
});
- walletData
walletData = {
walletPin: String(), // Required
privateKey: String(), // Required
address: String(), // Required
assetName: String() // Required
}
or
walletData = {
walletPin: String(), // Required
privateKey: String(), // Required
address: String(), // Required
asset: Asset() // Required
}
create()
wallet.create(assetName, walletPin).then(() => {
console.info(wallet);
}).catch(err => {
console.error(err);
});
update()
wallet.update().then(() => {
console.info(wallet);
}).catch(err => {
console.error(err);
});