Javascript API for integration with the WAX Cloud Wallet.
Check the WAX developer portal for full instructions
Grab the waxjs.js minified bundle in the dist-web folder of this repo, or build it yourself (see below). Check the demo code to see how to use it.
npm install @waxio/waxjsyarn add @waxio/waxjsReact style apps using npm or yarn can import the library via:
import * as waxjs from "@waxio/waxjs/dist";Instantiate the waxjs object with the WAX RPC server you wish to connect to.
const wax = new waxjs.WaxJS({
rpcEndpoint: 'https://wax.greymass.com'
});The library can also be instantiated with the user account and the public keys. Due to the library contains the user information, the login step can be avoided.
const wax = new waxjs.WaxJS({
rpcEndpoint: 'https://wax.greymass.com',
userAccount: 'user1',
pubKeys: ['EOS7rC8jFvFrPYDqp3Nh3HdRfL79h11B1JhPEXy85enF5wwYzF3Hk']
});If you want to handle the auto-login on your side with the isAutoLoginAvailable function (to avoid waiting for the user to click a button), you can disable the auto-login function in the constructor (so it won't get called twice).
const wax = new waxjs.WaxJS({
rpcEndpoint: 'https://wax.greymass.com',
tryAutoLogin: false
});Log your user in so as to access their wax account name for creating transactions.
const userAccount = await wax.login();Successful login will return the userAccount. It will also be available as the userAccount member on the wax instance. You can now use the eosjs api member...
Utilize the eosjs api and rpc members available on the wax instance. They are instances of the regular eosjs objects, Api, and JsonRpc, so you can do anything with them that eosjs already provides. Check the eosjs docs and repo for more info.
The api method will not be initialized until you login your user, and remember that the user's account name is available as the userAccount member on the wax instance.
const result = await wax.api.transact({
actions: [{
account: 'eosio.token',
name: 'transfer',
authorization: [{
actor: wax.userAccount,
permission: 'active',
}],
data: {
from: wax.userAccount,
to: 'eosio',
quantity: '0.00000001 WAX',
memo: '',
},
}]
}, {
blocksBehind: 3,
expireSeconds: 1200,
});- rpcEndpoint: The WAX public node API endpoint URL you wish to connect to. Required
- tryAutoLogin: Always attempt to autologin when your dapp starts up. Default true
- userAccount: User account to start up with. Optional
- pubKeys: Public keys for the userAccount manually specified above. Optional.
- apiSigner: Custom signing logic. Note that free bandwidth will not be provided to custom signers. Default Optional
- eosApiArgs: Custom eosjs constructor arguments to use when instantiating eosjs. Optional
- freeBandwidth: Request bandwidth management from WAX. Default true
- feeFallback: Add wax fee action if user exhausted their own bandwidth, the free boost. Default true
- verifyTx: Verification function that you can override to confirm that your transactions received from WAX are only modified with bandwidth management actions, and that your transaction is otherwise unaltered. The function signature is
(userAccount: string, originalTx: any, augmentedTx: any) => void. WhereuserAccountis the account being signed for,originalTxis the tx generated by your dapp, andaugmentedTxis the potentially bandwidth-managed altered tx you will receive from WAX. The default verifier does this for you, and you should check this to be confident that the verifier is sufficiently rigorous. Optional - metricsUrl: used by WAXIO to gather metrics about failed transaction, times it takes to load a transaction. Default Optional
- returnTempAccounts: using this flag will return temporary accounts or accounts that have signed up for a cloud wallet but not paid the introduction fee to get a blockchain account created. When this is set to true, using the doLogin function will return blockchain account name that may not exist in the blockchain but it will also return an extra boolean flag called isTemp. If this flag is true it is a temporary account, it does not exist in the blockchain yet. If this constructor option is false then only accounts which have been activated and have a blockchain account will be returned.
Temporary accounts are users that have signed up for a wallet account, but have not paid the entry fee to get the blockchain account created.
We allow waxjs to return accounts using the returnTempAccounts contructor argument, by then dapps can create an account on behalf of the user or have a custom signup flow if they want.
For example:
returnTempAccounts = true, User with temporary account can login and try out the dApp without using any blockchain function
returnTempAccounts = false, this means the waxjs library will only return accounts for users who have a block chain account. People who have already paid the creation fee
After the wax.login() call you can check if an account is temporary using wax.isTemp(), remember this will only ever can be true if allowTemporaryAccounts is set to true, or else waxjs will never return temporary accounts.
To create blockchain account on behalf of the user, dApp owners can send 5 WAXP( get the latest value from here ) to newuser.wax with the MEMO = userAccount.
There is a refund system in place if you pay more than the account creation fee, the extra amount will be refunded to the newly created account. eg: you send 8 WAXP to newuser.wax for a new account named: new.wam after the new account new.wam is created it will get 3 WAXP refunded. There is a maximum amount that will be refunded, it can be found here
If you want to get the latest account creation fee from the blockchain you can get it from waxjs. After the user has logged in you can call waxjs.createInfo this will return an object like this :
{
"contract": "eosio.token",
"message": "Create the user's blockchain account ds.k.wam by sending 5 WAX to newuser.wax with the memo as the one mentioned below.",
"amount": "5.00000000 WAX",
"memo": "dsDOTkDOTwam"
}
This is only be returned if the account is temporary so check that the account is temporary using waxjs.isTemp before you call waxjs.createInfo
For example:
User login with temporary account, and their userAccount = hfhf.wam
Dapps can send 5 WAXP (current account creation fee) to newuser.wax , with MEMO = hfhf.wam
Then the blockchain account of the user would be created, and they can start using all the blockchain features.
So long as waxjs is initialized with freeBandwidth = true (this is the default), your dapp will take advantage of freebandwidth provided by WAX, up to 5ms of CPU and 5K words per user per 24 hours, and tentatively 50s per contract per 24 hrs.
Dapps that require more bandwidth will be able to register their own bandwidth via the bandwidth registration contract. More info on registering for extra bandwidth management can be found here.
So long as waxjs is initialized with feeFallback = true (this is the default), Wallet automatically add action to transfer WAXP as fee for that transaction if user has enough balance. Transaction fee is calculated by formula:
waxFee = cpu_usage_us*CPU_FEE_RATIO + net_usage_words*NET_FEE_RATIO + FEE_CONSTANT;
By default CPU_FEE_RATIO=NET_FEE_RATIO=0.001, FEE_CONSTANT=0.01;
npm run docs
npm run serve
Note - run the demo app first (as above), and then run the tests suite:
npm run test
npm run build
npm run build-web
When making a pull request, please make sure to run npm run prettier to make sure your code is as formatted as possible. Also, make sure npm run lint runs without errors, since that is the final check before a new version is published to npm.