SLPJS
SLPJS is a JavaScript Library for building Simple Ledger Protocol (SLP) token transactions.
GENESIS, MINT, and SEND transaction functions are currently supported.
Installation
For node.js
npm install slpjs
For browser
<script src='https://unpkg.com/slpjs'></script>
Example Usage
The following examples show how this library should be used.
NOTE: The BigNumber.js library is used to avoid precision issues with numbers having more than 15 significant digits.
Get Balances
// Install BITBOX-SDK v3.0.2+ instance for blockchain access// For more information visit: https://www.npmjs.com/package/bitbox-sdkconst BITBOXSDK = defaultconst slpjs = slpjs; // FOR TESTNET UNCOMMENTlet addr = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l";const BITBOX = restURL: 'https://trest.bitcoin.com/v2/' ; // FOR MAINNET UNCOMMENT// let addr = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu";// const BITBOX = new BITBOXSDK({ restURL: 'https://rest.bitcoin.com/v2/' }); const slpValidator = BITBOX BITBOXRawTransactionsgetRawTransaction;const bitboxNetwork = BITBOX slpValidator; let balances; { balances = await bitboxNetwork; console;}; // RETURNS ALL BALANCES & UTXOs: // { satoshis_available_bch: 190889,// satoshis_locked_in_slp_baton: 546,// satoshis_locked_in_slp_token: 1092,// satoshis_in_invalid_token_dag: 0,// satoshis_in_invalid_baton_dag: 0,// slpTokenBalances: {// '1cda254d0a995c713b7955298ed246822bee487458cd9747a91d9e81d9d28125': BigNumber { s: 1, e: 3, c: [ 1000 ] },// '047918c612e94cce03876f1ad2bd6c9da43b586026811d9b0d02c3c3e910f972': BigNumber { s: 1, e: 2, c: [ 100 ] } // },// slpTokenUtxos: [ ... ],// slpBatonUtxos: [ ... ],// invalidTokenUtxos: [ ... ],// invalidBatonUtxos: [ ... ],// nonSlpUtxos: [ ... ]// }
GENESIS - Creating a new token
GENESIS is the most simple type of SLP transaction since no special inputs are required.
// Install BITBOX-SDK v3.0.2+ instance for blockchain access// For more information visit: https://www.npmjs.com/package/bitbox-sdkconst BITBOXSDK = defaultconst BigNumber = ;const slpjs = slpjs; // FOR TESTNET UNCOMMENTconst BITBOX = restURL: 'https://trest.bitcoin.com/v2/' ;const fundingAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l";const fundingWif = "cVjzvdHGfQDtBEq7oddDRcpzpYuvNtPbWdi8tKQLcZae65G4zGgy";const tokenReceiverAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l";const batonReceiverAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l";const bchChangeReceiverAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l"; // FOR MAINNET UNCOMMENT// const BITBOX = new BITBOXSDK({ restURL: 'https://rest.bitcoin.com/v2/' });// const fundingAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu"; // <-- must be simpleledger format// const fundingWif = "L3gngkDg1HW5P9v5GdWWiCi3DWwvw5XnzjSPwNwVPN5DSck3AaiF"; // <-- compressed WIF format// const tokenReceiverAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu"; // <-- must be simpleledger format// const batonReceiverAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu";// const bchChangeReceiverAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu"; // <-- cashAddr or slpAddr format const slpValidator = BITBOX BITBOXRawTransactionsgetRawTransaction;const bitboxNetwork = BITBOX slpValidator; // 1) Get all balances at the funding address.let balances; { balances = await bitboxNetwork; console; console;}; // WAIT FOR NETWORK RESPONSE... // 2) Select decimal precision for this new tokenlet decimals = 2;let name = "Awesome SLPJS README Token";let ticker = "SLPJS";let documentUri = "info@simpleledger.io";let documentHash = nulllet initialTokenQty = 1000000 // 3) Calculate the token quantity with decimal precision includedinitialTokenQty = initialTokenQty; // 4) Set private keysbalancesnonSlpUtxos // 5) Use "simpleTokenGenesis()" helper methodlet genesisTxid;{ genesisTxid = await bitboxNetwork console};
MINT - Create more tokens
Adding additional tokens for a token that already exists is possible if you are in control of the minting "baton". This minting baton is a special UTXO that gives authority to add to the token's circulating supply.
// Install BITBOX-SDK v3.0.2+ instance for blockchain access// For more information visit: https://www.npmjs.com/package/bitbox-sdkconst BITBOXSDK = defaultconst BigNumber = ;const slpjs = slpjs; // FOR TESTNET UNCOMMENTconst BITBOX = restURL: 'https://trest.bitcoin.com/v2/' ;const fundingAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l";const fundingWif = "cVjzvdHGfQDtBEq7oddDRcpzpYuvNtPbWdi8tKQLcZae65G4zGgy";const tokenReceiverAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l";const batonReceiverAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l";const bchChangeReceiverAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l";const tokenIdHexToMint = "a67e2abb2fcfaa605c6a3b0dfb642cc830b63138d85b5e95eee523fdbded4d74";let additionalTokenQty = 1000 // FOR MAINNET UNCOMMENT// const BITBOX = new BITBOXSDK({ restURL: 'https://rest.bitcoin.com/v2/' });// const fundingAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu"; // <-- must be simpleledger format// const fundingWif = "L3gngkDg1HW5P9v5GdWWiCi3DWwvw5XnzjSPwNwVPN5DSck3AaiF"; // <-- compressed WIF format// const tokenReceiverAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu"; // <-- must be simpleledger format// const batonReceiverAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu";// const bchChangeReceiverAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu"; // <-- cashAddr or slpAddr format// const tokenIdHexToMint = "495322b37d6b2eae81f045eda612b95870a0c2b6069c58f70cf8ef4e6a9fd43a";// let additionalTokenQty = 1000 const slpValidator = BITBOX BITBOXRawTransactionsgetRawTransaction;const bitboxNetwork = BITBOX slpValidator; // 1) Get all balances at the funding address.let balances; { balances = await bitboxNetwork; console; ifbalancesslpBatonUtxostokenIdHexToMint console; else throw Error"You don't have the minting baton for this token";}; // 2) Fetch critical token decimals information using bitdblet tokenDecimals; { const tokenInfo = await bitboxNetwork; tokenDecimals = tokenInfodecimals; console;}; // WAIT FOR ASYNC METHOD TO COMPLETE // 3) Multiply the specified token quantity by 10^(token decimal precision)let mintQty = additionalTokenQty // 4) Filter the list to choose ONLY the baton of interest // NOTE: (spending other batons for other tokens will result in losing ability to mint those tokens)let inputUtxos = balancesslpBatonUtxostokenIdHexToMint // 5) Simply sweep our BCH (non-SLP) utxos to fuel the transactioninputUtxos = inputUtxos; // 6) Set the proper private key for each UtxoinputUtxos // 7) MINT token using simple functionlet mintTxid; { mintTxid = await bitboxNetwork console;};
SEND - Send tokens
This example shows the general workflow for sending an existing token.
// Install BITBOX-SDK v3.0.2+ instance for blockchain access// For more information visit: https://www.npmjs.com/package/bitbox-sdkconst BITBOXSDK = defaultconst BigNumber = ;const slpjs = slpjs; // FOR MAINNET UNCOMMENT// const BITBOX = new BITBOXSDK({ restURL: 'https://rest.bitcoin.com/v2/' });// const fundingAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu"; // <-- must be slpAddr format// const fundingWif = "L3gngkDg1HW5P9v5GdWWiCi3DWwvw5XnzjSPwNwVPN5DSck3AaiF"; // <-- compressed WIF format// const tokenReceiverAddress = "simpleledger:qqr3a3c9wsdqljmwvy58rvp0yd25qmk3gqyrendudw"; // <-- must be slpAddr format// const bchChangeReceiverAddress = "simpleledger:qrhvcy5xlegs858fjqf8ssl6a4f7wpstaqnt0wauwu"; // <-- cashAddr or slpAddr format// let tokenId = "495322b37d6b2eae81f045eda612b95870a0c2b6069c58f70cf8ef4e6a9fd43a";// let sendAmount = 10; // FOR TESTNET UNCOMMENTconst BITBOX = restURL: 'https://trest.bitcoin.com/v2/' ;const fundingAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l"; // <-- must be slpAddr formatconst fundingWif = "cVjzvdHGfQDtBEq7oddDRcpzpYuvNtPbWdi8tKQLcZae65G4zGgy"; // <-- compressed WIF formatconst tokenReceiverAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l"; // <-- must be slpAddr formatconst bchChangeReceiverAddress = "slptest:qpwyc9jnwckntlpuslg7ncmhe2n423304ueqcyw80l"; // <-- cashAddr or slpAddr formatlet tokenId = "a67e2abb2fcfaa605c6a3b0dfb642cc830b63138d85b5e95eee523fdbded4d74";let sendAmount = 10; const slpValidator = BITBOX BITBOXRawTransactionsgetRawTransaction;const bitboxNetwork = BITBOX slpValidator; // 1) Fetch critical token informationlet tokenDecimals; { const tokenInfo = await bitboxNetwork; tokenDecimals = tokenInfodecimals; console;}; // 2) Check that token balance is greater than our desired sendAmountlet balances; { balances = await bitboxNetwork; console; console}; // Wait for network responses... // 3) Calculate send amount in "Token Satoshis". In this example we want to just send 1 token unit to someone...sendAmount = sendAmount; // Don't forget to account for token precision // 4) Get all of our token's UTXOslet inputUtxos = balancesslpTokenUtxostokenId // 5) Simply sweep our BCH utxos to fuel the transactioninputUtxos = inputUtxos; // 6) Set the proper private key for each UtxoinputUtxos // 7) Send tokenlet sendTxid;{ sendTxid = await bitboxNetwork console;};
SLP Address Conversion
let Utils = slpjsUtils; let slpAddr = Utils;console;// simpleledger:qzkpdhw8xwe2x2dt7mqtxwjrpfnlrclkwqvhlgwxy8 let cashAddr = Utils;console;// bitcoincash:qzat5lfxt86mtph2fdmp96stxdmmw8hchyxrcmuhqf
Caveats
- All SLPJS methods require token quantities to be expressed in the smallest possible unit of account for the token (i.e., token satoshis). This requires the token's precision to be used to calculate the quantity. For example, token having a decimal precision of 9 sending an amount of 1.01 tokens would need to first calculate the sending amount using
1.01 x 10^9 => 1010000000
.
Building & Testing
Building this project creates lib/*.js files and then creates browserified versions in the dist folder.
Requirements
Running the unit tests require node.js v8.15+.
Build
npm run build
Test
npm run test