Ecanna Platform JS Library
npm install ecannayarn:
yarn add ecanna
yarn build
js
const ecanna = require("ecanna")
`
Or into your TypeScript project like this:
`js
import { Ecanna } from "ecanna"
`
$3
`js
import { Ecanna, BinTools, BN, Buffer } from "ecanna"
const bintools = BinTools.getInstance()
`
The above lines import the libraries used in the tutorials. The libraries include:
* Ecanna: Our javascript module.
* BinTools: A singleton built into EcannaJS that is used for dealing with binary data.
* BN: A bignumber module use by EcannaJS.
* Buffer: A Buffer library.
Example 1 — Managing TKN-Chain Keys
EcannaJS comes with its own TKNVM Keychain. This KeyChain is used in the functions of the API, enabling them to sign using keys it's registered. The first step in this process is to create an instance of EcannaJS connected to our Ecanna Platform endpoint of choice.
`js
import { Ecanna, BinTools, Buffer, BN } from "ecanna"
const bintools = BinTools.getInstance()
const myNetworkID = 12345 //default is 1, we want to override that for our local network
const ecanna = new Ecanna("localhost", 9650, "http", myNetworkID)
const tknchain = ecanna.TKNChain() //returns a reference to the TKN-Chain used by EcannaJS
`
$3
The KeyChain is accessed through the TKN-Chain and can be referenced directly or through a reference variable.
`js
const myKeychain = tknchain.keyChain()
`
This exposes the instance of the class TKNVMKeyChain which is created when the TKN-Chain API is created. At present, this supports secp256k1 curve for ECDSA key pairs.
$3
The KeyChain has the ability to create new KeyPairs for you and return the address associated with the key pair.
`js
const newAddress1 = myKeychain.makeKey() // returns an instance of the KeyPair class
`
You may also import your existing private key into the KeyChain using either a Buffer...
`js
const mypk = bintools.cb58Decode(
"JaCCSxdoWfo3ao5KwenXrJjJR7cBTQ287G1C5qpv2hr2tCCdb"
) // returns a Buffer
const newAddress2 = myKeychain.importKey(mypk) // returns an instance of the KeyPair class
`
... or an CB58 string works, too:
`js
const mypk = "PrivateKey-JaCCSxdoWfo3ao5KwenXrJjJR7cBTQ287G1C5qpv2hr2tCCdb"
const newAddress2 = myKeychain.importKey(mypk) // returns an instance of the KeyPair class
`
$3
The TKN-Chains's KeyChain has standardized key management capabilities. The following functions are available on any KeyChain that implements this interface.
`js
const addresses = myKeychain.getAddresses() // returns an array of Buffers for the addresses
const addressStrings = myKeychain.getAddressStrings() // returns an array of strings for the addresses
const exists = myKeychain.hasKey(addresses[0]) // returns true if the address is managed
const keypair = myKeychain.getKey(addresses[0]) // returns the KeyPair class
`
$3
The TKN-Chain's KeyPair has standardized KeyPair functionality. The following operations are available on any KeyPair that implements this interface.
`js
const address = keypair.getAddress() // returns Buffer
const addressString = keypair.getAddressString() // returns string
const pubk = keypair.getPublicKey() // returns Buffer
const pubkstr = keypair.getPublicKeyString() // returns a CB58 encoded string
const privk = keypair.getPrivateKey() //returns Buffer
const privkstr = keypair.getPrivateKeyString() //returns a CB58 encoded string
keypair.generateKey() // creates a new random KeyPair
const mypk = bintools.cb58Decode(
"24jUJ9vZexUM6expyMcT48LBx27k1m7xpraoV62oSQAHdziao5"
)
const successful = keypair.importKey(mypk) // returns boolean if private key imported successfully
const message = Buffer.from("Through consensus to the stars")
const signature = keypair.sign(message) // returns a Buffer with the signature
const signerPubk = keypair.recover(message, signature) // returns a Buffer
const isValid = keypair.verify(message, signature) // returns a boolean
`
Example 2 — Creating An Asset
This example creates an asset in the TKN-Chain and publishes it to the Ecanna Platform. The first step in this process is to create an instance of EcannaJS connected to our Ecanna Platform endpoint of choice.
`js
import { Ecanna, BinTools, Buffer, BN } from "ecanna"
import { InitialStates, SECPTransferOutput } from "ecanna/dist/apis/tknvm"
const myNetworkID = 12345 // default is 1, we want to override that for our local network
const ecanna = new Ecanna("localhost", 9650, "http", myNetworkID)
const tknchain = ecanna.TKNChain() // returns a reference to the TKN-Chain used by EcannaJS
`
$3
The first steps in creating a new asset using EcannaJS is to determine the qualities of the asset. We will give the asset a name, a ticker symbol, as well as a denomination.
`js
// Name our new coin and give it a symbol
const name = "TeamRocket"
const symbol = "ROKT"
// Where is the decimal point indicate what 1 asset is and where fractional assets begin
// Ex: 1 ECNA is denomination 9, so the smallest unit of ECNA is nanoECNA (nECNA) at 10^-9 ECNA
const denomination = 9
`
$3
We want to mint an asset with 400 coins to all of our managed keys, 500 to the second address we know of, and 600 to the second and third address. This sets up the state that will result from the Create Asset transaction.
_Note: This example assumes we have the keys already managed in our TKN-Chain's Keychain._
`js
const addresses = tknchain.keyChain().getAddresses()
// Create outputs for the asset's initial state
const secpOutput1 = new SECPTransferOutput(
new BN(400),
new BN(400),
1,
addresses
)
const secpOutput2 = new SECPTransferOutput(new BN(500), new BN(400), 1, [
addresses[1],
])
const secpOutput3 = new SECPTransferOutput(new BN(600), new BN(400), 1, [
addresses[1],
addresses[2],
])
// Populate the initialStates with the outputs
const initialState = new InitialStates()
initialState.addOutput(secpOutput1)
initialState.addOutput(secpOutput2)
initialState.addOutput(secpOutput3)
`
$3
Now that we know what we want an asset to look like, we create an output to send to the network. There is an TKNVM helper function buildCreateAssetTx() which does just that.
`js
// Fetch the UTXOSet for our addresses
const utxos = await tknchain.getUTXOs(addresses)
// Make an unsigned Create Asset transaction from the data compiled earlier
const unsigned = await tknchain.buildCreateAssetTx(
utxos, // the UTXOSet containing the UTXOs we're going to spend
addresses, // the addresses which will pay the fees
addresses, // the addresses which recieve the change from the spent UTXOs
initialState, // the initial state to be created for this new asset
name, // the full name of the asset
symbol, // a short ticker symbol for the asset
denomination // the asse's denomination
)
const signed = unsigned.sign(tknchain) // returns a Tx class
`
$3
Now that we have a signed transaction ready to send to the network, let's issue it!
Using the EcannaJS TKN-Chain API, we going to call the issueTx function. This function can take either the Tx class returned in the previous step, a CB58 representation of the transaction, or a raw Buffer class with the data for the transaction. Examples of each are below:
`js
// using the Tx class
const txid = await tknchain.issueTx(signed) // returns a CB58 serialized string for the TxID
`
`js
// using the base-58 representation
const txid = await tknchain.issueTx(signed.toString()) // returns a CB58 serialized string for the TxID
`
`js
// using the transaction Buffer
const txid = await tknchain.issueTx(signed.toBuffer()) // returns a CB58 serialized string for the TxID
`
We assume ONE of those methods are used to issue the transaction.
$3
Now that we sent the transaction to the network, it takes a few seconds to determine if the transaction has gone through. We can get an updated status on the transaction using the TxID through the TKNVM API.
`js
// returns one of: "Accepted", "Processing", "Unknown", and "Rejected"
const status = await tknchain.getTxStatus(txid)
`
The statuses can be one of "Accepted", "Processing", "Unknown", and "Rejected":
* "Accepted" indicates that the transaction has been accepted as valid by the network and executed
* "Processing" indicates that the transaction is being voted on.
* "Unknown" indicates that node knows nothing about the transaction, indicating the node doesn't have it
* "Rejected" indicates the node knows about the transaction, but it conflicted with an accepted transaction
$3
The TKN-Chain uses the TxID of the transaction which created the asset as the unique identifier for the asset. This unique identifier is henceforth known as the "AssetID" of the asset. When assets are traded around the TKN-Chain, they always reference the AssetID that they represent.
Example 3 — Sending An Asset
This example sends an asset in the TKN-Chain to a single recipient. The first step in this process is to create an instance of Ecanna connected to our Ecanna Platform endpoint of choice.
`js
import { Ecanna, BinTools, Buffer, BN } from "ecanna"
const myNetworkID = 12345 // default is 1, we want to override that for our local network
const ecanna = new ecanna.Ecanna(
"localhost",
9650,
"http",
myNetworkID
)
const tknchain = ecanna.TKNChain() // returns a reference to the TKN-Chain used by EcannaJS
`
We're also assuming that the keystore contains a list of addresses used in this transaction.
$3
The TKN-Chain stores all available balances in a datastore called Unspent Transaction Outputs (UTXOs). A UTXO Set is the unique list of outputs produced by transactions, addresses that can spend those outputs, and other variables such as lockout times (a timestamp after which the output can be spent) and thresholds (how many signers are required to spend the output).
For the case of this example, we're going to create a simple transaction that spends an amount of available coins and sends it to a single address without any restrictions. The management of the UTXOs will mostly be abstracted away.
However, we do need to get the UTXO Set for the addresses we're managing.
`js
const myAddresses = tknchain.keyChain().getAddresses() // returns an array of addresses the KeyChain manages as buffers
const addressStrings = tknchain.keyChain().getAddressStrings() // returns an array of addresses the KeyChain manages as strings
const u = await tknchain.getUTXOs(myAddresses)
const utxos = u.utxos
`
$3
The buildBaseTx() helper function sends a single asset type. We have a particular assetID whose coins we want to send to a recipient address. This is an imaginary asset for this example which we believe to have 400 coins. Let's verify that we have the funds available for the transaction.
`js
const assetID = "8pfG5CTyL5KBVaKrEnCvNJR95dUWAKc1hrffcVxfgi8qGhqjm" // cb58 string
const mybalance = utxos.getBalance(myAddresses, assetID) // returns 400 as a BN
`
We have 400 coins! We're going to now send 100 of those coins to our friend's address.
`js
const sendAmount = new BN(100) // amounts are in BN format
const friendsAddress = "TKN-ecna1k26jvfdzyukms95puxcceyzsa3lzwf5ftt0fjk" // address format is Bech32
// The below returns a UnsignedTx
// Parameters sent are (in order of appearance):
// * The UTXO Set
// * The amount being sent as a BN
// * An array of addresses to send the funds
// * An array of addresses sending the funds
// * An array of addresses any leftover funds are sent
// * The AssetID of the funds being sent
const unsignedTx = await tknchain.buildBaseTx(
utxos,
sendAmount,
[friendsAddress],
addressStrings,
addressStrings,
assetID
)
const signedTx = tknchain.signTx(unsignedTx)
const txid = await tknchain.issueTx(signedTx)
`
And the transaction is sent!
$3
Now that we sent the transaction to the network, it takes a few seconds to determine if the transaction has gone through. We can get an updated status on the transaction using the TxID through the TKN-Chain.
`js
// returns one of: "Accepted", "Processing", "Unknown", and "Rejected"
const status = await tknchain.getTxStatus(txid)
`
The statuses can be one of "Accepted", "Processing", "Unknown", and "Rejected":
* "Accepted" indicates that the transaction has been accepted as valid by the network and executed
* "Processing" indicates that the transaction is being voted on.
* "Unknown" indicates that node knows nothing about the transaction, indicating the node doesn't have it
* "Rejected" indicates the node knows about the transaction, but it conflicted with an accepted transaction
$3
The transaction finally came back as "Accepted", now let's update the UTXOSet and verify that the transaction balance is as we expected.
Note: In a real network the balance isn't guaranteed to match this scenario. Transaction fees or additional spends may vary the balance. For the purpose of this example, we assume neither of those cases.
`js
const updatedU = await tknchain.getUTXOs()
const updatedUTXOs = updatedU.utxos
const newBalance = updatedUTXOs.getBalance(myAddresses, assetID)
if (newBalance.toNumber() != mybalance.sub(sendAmount).toNumber()) {
throw Error("heyyy these should equal!")
}
`
$3
Dependabot will make pull requests against the development branch. If all tests pass, it is safe to merge into development, but for redundancy you want to try to build it locally.
`zsh
git fetch origin
git checkout -b
git merge development
yarn build && yarn test
`
If the E2E check does not pass, go into the 'checks' section of the PR.
https://github.com/ecannacoins/ecannajs/pull/
* Click on the > E2E` tab on the left