Outsystems Low Code and eos.io Blockchain Forge Component Tutorial

Over the last couple of weeks, I've been playing around integrating eosio based blockchains with the OutSystems Low Code platform.

I published my result to the Outsystems Forge. In its current state it is between a framework and an integration library. It features flexibel Key management, server actions for building and serializing transactions, querying contract tables and transaction signing.

eos.io is the most performant blockchain platform available. The eos.io platform can be provisioned as public, private, and permissioned or permissionless blockchain infrastructure. It has a unique transaction fee and resource model which means that blockchain transactions are feeless on the public MainNet.

Besides the “official” public MainNet EOS there are multiple other eos.io based public blockchains (e.g., WAX io wax.io — The King of Non-Fungible Tokens), including TestNet's for development. You can also install your own single-node or multi-node private blockchain. With or without the resource model.

Before you start building your first eos.io Application with Outsystems and the eosio Forge Component you should familiarize with the key concepts and principles of the eos.io platform. Visit the eos.io Training Portal and take at least the following two courses:

  • Introduction to EOSIO — Non-technical
  • Introduction to EOSIO — Technical

After you have taken the courses, you should have a good understanding of

and how these topics relate to each other. The eos.io Developer Portal provides additional information and technical details.

Tutorial

In this simple walkthrough we will

  • Install and configure the forge component
  • Register the block.one TestNet in our environment
  • Create a keyring (a storage bound to a single chain holding keys) for our application.
  • Import private keys from the TestNet into our keyring
  • Call the default eosio.token Smart Contract to transfer some tokens to another blockchain account.

Setup

Install the eosio Forge Component into your development environment. The forge component consists of multiple modules

  • EOS_RPC — Integrates with the JSON RPC HTTP endpoint of an eos.io node.
  • EOS_EXT — actions for binary serialization of data, creating public-/private-key pairs and signing transactions with a private key
  • EOS_Core_CS — the main module with entities for chain configuration, keyrings, and keys, along with actions for building transactions
  • EOS_Contracts_CS — Wrapper actions for the basic eos.io system and token contracts.
  • EOSWallets — A management app which allows you to add blockchain networks, create keyrings and keys.

After installation login to Service Center. Go to the EOS_Core_CS module and set the KeyEncryptionPassword with a secure password.

The eosio component AES encrypts private keys in the database using this password. I will reconsider and mostly likely change that before releasing a stable version.

Do not overwrite or change this password after you have created or imported your first keys!

The EOSWallets module adds a new role EOSWalletManager. Add yourself to that role to get access to the EOSWallets management app.

Use a TestNet

For this walkthrough we are using the block.one eos.io TestNet. Go to https://testnet.eos.io and register.

After registration you already got one account with two key-pairs. one for the owner permission, the other for the active permission.

Create another eos.io account under the Blockchain Accounts menu.

Add TestNet using EOSWallets

Go to the EOSWallets management app and click the Register Blockchain button.

Enter the following details

Click the switch next to the name to mark this entry as a TestNet.

Klick the Save button

EOSWallets calls a server action Blockchain_Create from the EOS_Core_CS module. The action query's the node endpoint URL for the blockchain info and retrieves the unique blockchain identifier. It then creates a new database entry for that chain with the blockchain identifier as primary key. Throws exception if the entry already exists or if the node endpoint could not be reached.

Keyrings

A keyring is bracket over one or more public-/private-key pairs and “belongs” to a single chain. The forge component itself does not store account names and/or permissions. It is up to you and your application if you create a single keyring for your application, or keyring for every Outsystems User, or something else.

It is essential to know that a keyring and not a single public-/private-key pair is the smallest security boundary. For signing a transaction, you hand over one or more keyrings to the transaction signing action, not keys!

For our current tutorial we are using a single keyring. Technically this means that we treat our blockchain account equivalent to a service account, only known to the application, but independent of the user logging into our application.

Click on your created blockchain in EOSWallets and here on the New Keyring button. Give your keyring a name (e.g., My first blockchain application) and click the Save button.

EOSWallets calls the server action Keyring_Create from the EOS_Core_CS module and creates a new database entry for the keyring.

Import private key from TestNet

Select one of your created accounts on the TestNet (https://testnet.eos.io) and copy the private key of the active permission.

In EOSWallets click on your created keyring and there on Import Key. Paste in your copied TestNet private key, the click the Import button.

EOSWallets calls the server action Key_Import from EOS_Core_CS. The action validates first the given key (Format and Checksum of key) and throws an exception if the given key is invalid. If valid the private key is encrypted using the password provided in the KeyEncryptionPassword site property and written to the database.

After importing the private key, we have all we need to create our application.

Create Transfer Application

The final step in our tutorial is to create our application.

Create a new Reactive Web Application in your development environment.

Add dependencies

From EOS_Core_CS add

  • Transaction_Send (Server Action)
  • Blockchain_GetAccount (Service Action)

From EOS_Contracts_CS add

  • Token_Transfer_Action (Server Action)

EOS_Contracts_CS has Wrapper actions for the default eosio contracts. In a later tutorial i will explain how to create your own wrapper actions for custom smart contracts.

Create two Site Properties

  • ChainId with type of Text

Copy the Chain Identifier from EOSWallets to the default value of ChainId

  • KeyringId with type of Text

Copy the Keyring Identifier from EOSWallets to the default value of KeyringId

  • TokenAccount with type of Text

Copy the account name from https://testnet.eos.io to the default value of TokenAccount.

This is the account which we will use to send tokens and must be the account for which you imported the active private key to EOSWallets.

Create a new data structure TransferTokenForm with the properties

  • To (Text with length 12, mandatory)
  • Quantity (Text, mandatory)
  • Memo (Text with length 255)

Create a screen TransferTokens

On top of our screen, we want to show the current liquid balance of the account we want to send tokens from. Next to it we want to show the liquid balance of the account we send tokens to.

Create a new DataAction GetFromAccountBalance. Add the Blockchain_GetAccount Service Action.

Set ChainId to TextToIdentifier(Site.ChainId)

Set AccountName to Site.TokenAccount

Create a new Output for the DataAction “Balance” with type Text.

Assign Blockchain_GetAccount.Result.AccountDetails.CoreLiquidBalance to the new output parameter.

Set the Fetch property of the new data action to “At start”.

Add a local variable to the screen set to type of our data structure TransferTokenForm.

Create another data action GetToAccountBalance repeating the steps above but this time set the AccountName property to the To property of the TransferTokenForm.To property.

Set the Fetch property of the new data action to “Only on demand”.

Add a two-column layout to the main section of the screen. Add two number counter parts and display the Result of the GetFromAccountBalance on the left and the GetToAccountBalance on the right.

Wrap each number counter to display only if the data is fetched from the source.

Add a new form to the screen and drag in the TransferTokenForm fields.

Rename the Save button text to Transfer and create a new button submit action. Your screen should now like something like this:

Transfer Token Screen

Create a new Server Action Transfer_Submit.

Create a new input property “TransferArgs” with type of TransferTokenFrom data structure.

Create a new output property “TransactionId” with type text.

Add the server action Token_Transfer_Action from EOS_Contracts_CS to the action and set the action properties as follows

Token_Transfer_Action properties

Token_Transfer_Action is a simple Wrapper Action which does some validations. Look into the EOS_Contracts_CS module.

Take note of the Authorizations List. This list contains account@permission entries which are used for signature, when pushing this action to the blockchain.

Token_Transfer_Action returns an Action_Serialized Structure.

Next add the Transaction_Send server action from EOS_Core_CS module.

Transaction_Send properties

Transaction_Send does some JSON RPC calls to the node endpoint URL of the given blockchain. It first retrieves all public keys needed to sign the whole transaction. Required keys are compared to the available keys in the keyrings you add to the Keyrings List. If all required keys are available, the transaction is signed and pushed to the blockchain.

Assign the result of Transaction_Send to the TransactionId output parameter.

Return to your Transfer Client Action and add your server action after Form validation.

Transfer_Submit properties

After Transfer_Submit add a new Feedback Message which outputs the TransactionId.

Refresh both data actions. Your Transfer Client Action should now look like this.

Transfer Client Action

Since we are using a blockchain, transactions need to be validated first and put into a final block, which takes some time. In some cases, refreshing the accounts balance will not reflect the transaction. The component does not track finality of blocks and therefor transactions.

Test your application

Test transfer app

If everything is working as expected you just transferred Tokens from one TestNet Account to another. Congratulations! In the next tutorial i will show how to interact with a custom smart contract.

Thank you for reading. If you are interested in further enhancing the eosio Forge component, please let me know.

Business Analyst, Low Coder and Blockchain Enthusiast working in the Legal Industry.