Coin Core: Configuration and Validation

Coin Core plays a crucial role in the Core component of Orb DLT middleware by offering a platform where you can define your coin economy and perform transaction events based on desirable use cases. The upcoming sections will guide you through the process of configuring Coin Core using our web-based Coin Core configuration tool, accessing and making API calls and validating your use cases.

Prerequisites

Before you start the process of configuring coin core, it is important to have a deep understanding of Coin Core and its relationship to your application layer alongside a robust model of your coin economy. A few prerequisites mentioned below might come in handy.

Modeling your Economy

Your coin economy will primarily be based on how you configure your balance modifiers to execute transactions. It is therefore very important to map down the different types of transactions you would want to perform to support your use cases.

Modifier interdependencies and constraints should be adhered to ensure that event transactions get carried out successfully. Clearly documenting and understanding the desired behaviors of a transaction in your economy can help avoid conflicting events.

Understanding Coin Core and Orb DLT

This guide aims to provide a comprehensive and in-depth understanding of Coin Core and the role it plays in the Orb DLT platform. To further exploit the capabilities of Coin Core, you can use it in conjunction with other components of Orb DLT such as Query Core, Audit Core and Account Core. User guides for these components are available in the same repository where you found the Coin Core User Guide.

We highly recommend you to go through the other guides to get a holistic understanding of Orb DLT as a platform. Furthermore, you can visit https://developer.imagine-orb.com for the latest information, other user guides, and the API reference guide.

Understanding the relationship of your application-layer to Orb DLT

Orb DLT is, in essence, a ledger, which can be used by your application layer to record, update and verify transactions made in your coin economy. Its power lies in its scalability, security and distributed nature. However, Orb DLT does not cater to upper application layer primitives and business workflows. This means that business processes specific to your application (such as reporting, clearance etc) will not be defined and implemented by the Orb DLT platform. Orb DLT is simply the ledger that is used to record coin transaction information.

Using sequence diagrams and architectural diagrams, your team must decide where Orb DLT fits into your application flow.

Configuring Coin Core

Coin Core is configured using several JSON files:

• coin.json: coin objects configuration.
• target.json: Target object configuration.
• event.json: Event and balance modifier configuration.

Since manually writing JSON files can be tedious and error-prone, Coin Core comes with a web-based tool that can be used to generate the necessary configuration files. For the purposes of this guide, we will use the configuration tool, but the relevant JSON configuration is generated at each step.
##Configuring Coins

Follow the steps below to configure coins.

Step1: Access the configuration tool in a web browser.
Step 2: Click on the “Coin” menu item on the left-hand side tools menu. The following screen will open.

Step 3: In the text field labeled “Coin ID”, enter the desired name for your coin.
Step 4: If the coin object has a validity period, enable Expiration by clicking on the toggle labeled “Expiration Configuration”. Enter the starting and/or ending dates in the fields labeled “Start Date” and “End Date.” Refer to Expiration for an explanation of validity periods.
Step 5: If you would like issued coins to expire after some period of time, enter the desired lifetime in seconds. For example, if coins should expire after 180 days, then the value would be 15552000 (180 days 24 hours/day 60 minutes/hour * 60 seconds/minute).

Step 6: If you wish coins to be reclaimed gradually using the diminishment behavior, enable diminishment by clicking the toggle labeled “Diminishment Configuration.” The “Period”, “Reference”, and “Percent” fields will appear.

Step 7: Enter the diminishment interval (in seconds) in the “Period” field.
Step 8: Select the desired balance reference from the “Reference” drop-down.
Step 9: In the “Percent” field, enter the percentage by which coin balances should be diminished

Now, the coin object is configured and the final configuration will be displayed in the output pane on the right-hand side of the screen. Copy the configuration text or click “Save” to save the configuration for use by Coin Core.

🚧

Note

If you click “Save”, a zip folder containing all the four .json files will be downloaded.

Configuring Targets

Follow the steps below to configure targets.

Step 1: Access the configuration tool in a web browser.
Step 2: Click on the “Target” menu item on the left-hand side tools menu.
Step 3: In the text field labeled “TargetID”, enter the desired name for the target.

Repeat the process to create all desired targets.

The final configuration will be displayed in the output pane on the right-hand side of the screen. Copy the configuration text or click “Save” to save the configuration for use by Coin Core.

🚧

Note

If you click “Save”, a zip folder containing all the four .json files will be downloaded.

Configuring Events

Follow the steps below to create a new event.

Step 1: Access the configuration tool in a web browser.
Step 2: Click on the “Event” menu item in the left-hand side tools menu.
Step 3: Write the desired event name in the field labeled “Event ID”.
Step 4: If desired, enter a short description of the event in the field labeled “Event Description”.
Step 5: Click the “Add Modifier” button to add a new balance modifier object to the event.

The required properties are different for each modifier. Reference the “Balance modifiers” section for a description of required properties for each modifier.

The final configuration will be displayed in the output pane on the right-hand side of the screen. Copy the configuration text or click “Save” to save the configuration for use by Coin Core.

🚧

Note

If you click “Save”, a zip folder containing all the four .json files will be downloaded.

Understanding the APIs

The Core API is provided as a RESTful interface for performing actions such as: creating coin transactions, checking account balances and requesting tamper-evidence information for verifying individual coin transaction integrity. Accessing the API can be accomplished using any HTTP client provided by your preferred programming language. Alternatively, you may choose to use an Orb provided client. These clients are available in Go and Java; they are developed specifically for interacting with the Core APIs. Please visit https://developer.imagine-orb.com for more information.

To learn more about the API interface, visit the API reference guide to understand the inputs and outputs of each endpoint. The API reference guide can be found at https://developer.imagine-orb.com

Validating your use cases

After you have completed the process of creating a set of configuration files to support your coin economy, they should be delivered to your system administrator and installed correctly to prepare for running the server application. Your system administrator should refer to the Orb DLT Operations Guide to gain a full understanding of setup and configuration for the runtime environment.

Now that your configuration files are installed and initialized by the Coin Core server, you can validate the configuration by performing a few simple API calls:

• Execute a simple coin issuance event using an account, provided by Account Core, with the “create transaction” endpoint.
• Verify the updated account balance by accessing the “account balance” endpoint.

To validate more complicated events, you will need additional accounts to be used as your desired Targets. By accessing the “create transaction” endpoint with additional accounts, you will gain a better understanding of how your coins can be moved around your economy. You should test each event that you have configured to fully validate your new configuration files.

Wrapping Up

A crucial part of the Core offering of Orb DLT middleware components, Coin Core gives you the tools you need for creating and managing virtual currencies. Whether your currency is used as electronic money, a marketing points program, a store of value or another novel use case, Coin Core allows you to issue your currency individually or through third-party vendors, customize it’s transaction behaviors, and report on all transactions in your economy.

Coin Core is optionally used in conjunction with Account Core and Audit Core which provide the additional functionality you may find necessary or useful in your coin economy. The corresponding user guides for those middleware products can be found in the same location as this guide.