Javascript API for integration with PlasmaDLT using PlasmaDLT RPC API.
npm install plasmajs@beta or yarn add plasmajs@beta
Clone this repository locally then run npm run build-web or yarn build-web. The browser distribution will be located in dist-web and can be directly copied into your project repository. The dist-web folder contains minified bundles ready for production, along with source mapped versions of the library for debugging.
Importing using ES6 module syntax in the browser is supported if you have a transpiler, such as Babel.
import{Api,JsonRpc,RpcError}from'plasmajs';importJsSignatureProviderfrom'plasmajs/dist/plasmajs-jssig';// development onlyImporting using commonJS syntax is supported by NodeJS out of the box.
const{ Api, JsonRpc, RpcError }=require('plasmajs');constJsSignatureProvider=require('plasmajs/dist/plasmajs-jssig');// development onlyconstfetch=require('node-fetch');// node only; not needed in browsersconst{ TextEncoder, TextDecoder }=require('util');// node only; native TextEncoder/Decoderconst{ TextEncoder, TextDecoder }=require('text-encoding');// React Native, IE11, and Edge Browsers only- Wallet: https://plasmapay.com
constdefaultPrivateKey="5HwurBQZNFGkBbkqm3Ayh5ntrHRfQe5dsYfWjfug3BLbgsbBеаScq";// accountname1constsignatureProvider=newJsSignatureProvider([defaultPrivateKey]);Open a connection to JSON-RPC, include fetch when on NodeJS.
constrpc=newJsonRpc('http://127.0.0.1:8888',{ fetch });Include textDecoder and textEncoder when using in browser.
constapi=newApi({ rpc, signatureProvider,textDecoder: newTextDecoder(),textEncoder: newTextEncoder()});transact() is used to sign and push transactions onto the blockchain with an optional configuration object parameter. This parameter can override the default value of broadcast: true, and can be used to fill TAPOS fields given blocksBehind and expireSeconds. Given no configuration options, transactions are expected to be unpacked withfields (expiration, ref_block_num, ref_block_prefix) and will automatically be broadcast onto the chain.
(async()=>{constresult=awaitapi.transact({actions: [{account: 'plasma.token',name: 'transfer',authorization: [{actor: 'accountname1',permission: 'active',}],data: {from: 'accountname1',to: 'accountname2',quantity: '10.000000000000000000 PLASMA',memo: '',},}]},{blocksBehind: 3,expireSeconds: 30,});console.dir(result);})();use RpcError for handling RPC Errors
...
try{constresult=awaitapi.transact({
...
}catch(e){console.log('\nCaught exception: '+e);if(einstanceofRpcError)console.log(JSON.stringify(e.json,null,2));}...npm run build-web or yarn build-web
Reuse the api object for all transactions; it caches ABIs to reduce network usage. Only call new plasmajs_api.default(...) once.
<prestyle="width: 100%; height: 100%; margin:0px; "></pre><scriptsrc='dist-web/plasmajs-api.js'></script><scriptsrc='dist-web/plasmajs-jsonrpc.js'></script><scriptsrc='dist-web/plasmajs-jssig.js'></script><script>letpre=document.getElementsByTagName('pre')[0];constdefaultPrivateKey="5WaAScZK2XEp3g9gh7F8bwtPTRAkASmNrrftmx4AxDKD5K4zDke";// accountname1constrpc=newplasmajs_jsonrpc.default('http://127.0.0.1:8888');constsignatureProvider=newplasmajs_jssig.default([defaultPrivateKey]);constapi=newplasmajs_api.default({ rpc, signatureProvider });(async()=>{try{constresult=awaitapi.transact({actions: [{account: 'ion.token',name: 'transfer',authorization: [{actor: 'accountname1',permission: 'active',}],data: {from: 'useraaaaaaaa1',to: 'accountname2',quantity: '10.000000000000000000 PLASMA',memo: '',},}]},{blocksBehind: 3,expireSeconds: 30,});pre.textContent+='\n\nTransaction pushed!\n\n'+JSON.stringify(result,null,2);}catch(e){pre.textContent='\nCaught exception: '+e;if(einstanceofplasmajs_jsonrpc.RpcError)pre.textContent+='\n\n'+JSON.stringify(e.json,null,2);}})();</script>npm run test or yarn test
Run npm run build-web to build the browser distrubution then open src/tests/web.html in the browser of your choice. The file should run through 6 tests, relaying the results onto the webpage with a 2 second delay after each test. The final 2 tests should relay the exceptions being thrown onto the webpage for an invalid transaction and invalid rpc call.
If you would like readable source files for debugging, change the file reference to the -debug.js files inside dist-web/debug directory. These files should only be used for development as they are over 10 times as large as the minified versions, and importing the debug versions will increase loading times for the end user.
If you need to support IE11 or Edge you will also need to install a text-encoding polyfill as plasmajs Signing is dependent on the TextEncoder which IE11 and Edge do not provide. Pass the TextEncoder and TextDecoder to the API constructor as demonstrated in the ES 2015 example. Refer to the documentation here https://github.com/inexorabletash/text-encoding to determine the best way to include it in your project.
Reading blockchain state only requires an instance of JsonRpc connected to a node.
const{ JsonRpc }=require('plasmajs');constfetch=require('node-fetch');// node only; not needed in browsersconstrpc=newJsonRpc('http://127.0.0.1:8888',{ fetch });Get the first 10 token balances of account accountname1.
constresp=awaitrpc.get_table_rows({json: true,// Get the response as jsoncode: 'plasma.token',// Contract that we targetscope: 'accountname1'// Account that owns the datatable: 'accounts'// Table namelimit: 10,// Maximum number of rows that we want to get
reverse =false,// Optional: Get reversed data});console.log(resp.rows);Output:
{
"rows": [{
"balance": "10.000000000000000000 PLASMA"
}
],
"more": false
}constresp=awaitrpc.get_table_rows({json: true,// Get the response as jsoncode: 'contract',// Contract that we targetscope: 'contract'// Account that owns the datatable: 'profiles'// Table namelower_bound: 'accountname1'// Table primary key valuelimit: 1,// Here we limit to 1 to get only the
reverse =false,// Optional: Get reversed data
show_payer =false,// Optional: Show ram payer});console.log(resp.rows);Output:
{
"rows": [{
"user": "accountname1",
"age": 21,
"surname": "Test"
}
],
"more": false
}constresp=awaitrpc.get_table_rows({json: true,// Get the response as jsoncode: 'contract',// Contract that we targetscope: 'contract'// Account that owns the datatable: 'profiles'// Table nametable_key: 'age'// Table secondaray key namelower_bound: 21// Table secondary key valuelimit: 1,// Here we limit to 1 to get only row
reverse =false,// Optional: Get reversed data});console.log(resp.rows);Output:
{
"rows": [{
"user": "accountname1",
"age": 21,
"surname": "Test"
}
],
"more": false
}console.log(awaitrpc.get_currency_balance('plasma.token','accountname1',''));Output:
[ "10.000000000000000000 PLASMA" ]console.log(awaitrpc.get_account('accountname1'));Output:
{ "account_name": "accountname1",
"head_block_num": 2029,
"head_block_time": "2019-11-10T00:45:53.500",
"privileged": false,
"last_code_update": "1970-01-01T00:00:00.000",
"created": "2019-11-10T00:37:05.000",
"ram_usage": 1724,
"permissions":
[ { "perm_name": "active", "parent": "owner", "required_auth": [] },
{ "perm_name": "owner", "parent": "", "required_auth": [] } ],
"refund_request": null,
}console.log(awaitrpc.get_block(1));Output:
{ "timestamp": "2019-06-01T12:00:00.000",
"producer": "",
"confirmed": 1,
"previous": "0000000000000000000000000000000000000000000000000000000000000000",
"transaction_mroot": "0000000000000000000000000000000000000000000000000000000000000000",
"action_mroot": "cf057bbfb72640471fd910bcb67639c22df9f92470936cddc1ade0e2f2e7dc4f",
"schedule_version": 0,
"new_producers": null,
"header_extensions": [],
"producer_signature": "SIG_K1_111111111111111111111111111111111111111111111111111111111111111116uk5ne",
"transactions": [],
"block_extensions": [],
"id": "00000001bcf2f4433rd099685f14da76803028926af04d2607eafcf609c123d",
"block_num": 1,
"ref_block_prefix": 331719066 }