3 Work In Progress : Workflow

SDK WORKFLOW 🏁

This section will go through the main workflow process to execute a transaction. In just a few steps you will be able to init the Ternoa SDK API and start using it.

Init the API

It's not strictly necessary but it's good practice to initialize the API as soon as possible. If this call is omitted then the first SDK call will return an exception. The default chain endpoint is: DEFAULT_CHAIN_ENDPOINT = "wss://alphanet.ternoa.com". It can be modified by passing a new endpoint as a parameter to the initializeApi() function. You can also specify the endpoint by passing the endpoint address as the first argument.

// Import
import { initializeApi } from "ternoa-js"

async function main() {
  // Construct
  await initializeApi();

  // Do something
  console.log("Api Connected");
  ...
}

How to customize the API endpoint ?

Simply pass the required endpoint to the initializeApi() function.

  ...
   //enpoint here will make the init API on the Ternoa mainnet network
   await initializeApi('wss://mainnet.ternoa.io');

   // Do something
   console.log("Api Connected on mainnet");
  ...
}

Note: Ternoa SDK provides a getRawApi() function to interact with the API init process. If the API is not connected, it will connect it directly for you on the default alphanet endpoint.

Let's Create!

Now we know how to init our SDK API, let's get directly into a feature exemple. The Ternoa-js provides the most friendly way to build on the chain and execute a transaction. Let's go into detail and see an exemple of how to create an NFT.

The automatized and friendly way:

For most of the main chain feature (we consider here our extrinsics) the SDK provides two functions. One of this is an all-in-one function that allows to go to the entire transaction workflow process: It Creates a tx, Signs the tx and Submits the tx for you in a single line function.

Going back to the NFT creation exemple: This single line createNft() function, requires a few parameters : some offchainData metadatas*, a royalty, a collectionId if you want this NFT to belong to a collection, a boolean to define its isSoulbound status, the keyring that will be used to sign and submit the transaction, and a waitUntil callback parameter, to define at which point we want to get the results of the transaction execution.

*In most cases this will be an IPFS hash that points to a JSON file which contains fields as "name", "description" or "image". In other cases this can be a link to a either a static or a dynamic file, plain text or a small JSON string. In the exemple below, we just pass a tr

// Imports
import { initializeApi } from "ternoa-js"
import { createNft } from "ternoa-js/nft"

const createMyFirstNFT = async () => {
  try {
    // We initialize the API instance
    await initializeApi()

    ... //we asume your keyring is already created and provided with CAPS to support transactions fees.  

    // Here we create, sign and submit the NFT transaction with your keyring
    const newNFT = await createNft("My first NFT", 10, undefined, false, keyring, WaitUntil.BlockInclusion)

    // Do something
    console.log(newNFT);
    ...

  } catch (e) {
    console.log(e)
  }
}

The versatile but more complex way:

Now we have seen the most friendly way to create an NFT in a signle line, with the automation of the workflow (Create => Sign => Send), we can dig a bit more. For some reasons, you will need to go manually into the whole process. This way is more complex but offer more versatilty : ex if you split the process and execute it by your self, y_ou will be able for exemple to make a batch of transactions_ (this concept is covered in the exemple section) instead of doing it one by one. It's very usefull if you want to create a large amount of NFT and avoid to sign and send them one by one.

Let's go into the detail of each steps to create an NFT manually.

Create an NFT transaction :

First of all, instead of using the createNft() function, you will use the createNftTx(). Instead of creating, signing and submiting, the transaction and get the returned events, it will just create an unsigned and unsubmitted Create-NFT Transaction Hash ready to be used and valid for 5 minutes.

// Imports
import { initializeApi } from "ternoa-js"
import { createNftTx } from "ternoa-js/nft"

const create createNFTManually = async () => {
  try {
    ...

    // STEP 1 : Here we create the transaction and get the transaction hash
    const nftTxHash = await createNftTx("My first NFT", 10, undefined, false)

    // Do something with the transaction hash
    console.log(nftTxHash);
    ...
  } catch (e) {
    console.log(e)
  }
}

Sign a transaction hash:

Now we have the txHash, we can move to the signing step. But before detailing it, it's good to know that "signing" can be directely embed in the submit function. It means that depending on the submit function you are using (see the last step below), signing your tx hash before submit might not be necessary. In case you sign manually the tx hash, you will receive a hex value of the signed transaction ready to be send. The signTxHex() function expect a keyring that will sign the transaction and the transaction hash to be signed.

const create createNFTManually = async () => {
  try {
    ...

    // STEP 2 : Here we sign the transaction hash. nftTxHash is the name of the tx hash from the function we created before.
    const signedTxHash = await signTxHex(keyring, nftTxHash)

    // Do something with the hex value. 
    console.log(nftTxHash);
    ...
  } catch (e) {
    console.log(e)
  }
}

• Add "Submit Transactions" 3 Example

How to submit a transactions?

Submiting a transaction is generally the last step of the transaction execussion process. Ternoa-js provide up to 4 ways to submit a transaction. From the raw and native way to the fully handled and most easy to use. Depending of the result format you are expecting and the specific case you want to handle (simple submit, batching some transaction (...)) you will need to go with one of the following function.

• submitTxHex - The most versatile and customizable way to submit your txHash. You can manage your self the callback function. Let's assume you are trying to transfer

  const txHex = await createTxHex(txPallets.balances, txActions.transfer, [destAccount.address, "1000000000000000"])
  const signedTxHex = await signTxHex(testAccount, txHex)
  const submittedTxHex = await submitTxHex(signedTxHex)

• submitTxBlocking - The most most convenient way to get Events and datas : This function will sign the transaction for us if we pass a keyring (one less thing to worry about) and it's blocking the execution flow until the transaction is either in a block or in a finalized block. Since submitting needs to work will all kinds of transactions, the result is an object that contains all the events that have happen (instead of only specific ones).

• submitTxNonBlocking: The most friendly way with a customizable way to submit your txHash.