Transactions

The Integration Layer provides a generalized transaction module that can be configured to fit most types of transactions in an economy. At its core, three methods are exposed: start, execute and reverse. As the name suggests, the start method starts a transaction by using a particular strategy to trigger an event. The execute method executes a previously created transaction. The reverse method reverses a previously executed transaction.

Configuration

Each transaction must be pre-configured at runtime. Here is a sample transaction configuration:

pay:
  coincore_event: payment
  group: payment
  strategy: simple
  single_step: false
  steps:
    start:
      validate:
        - com.orb.framework.wallet.model.limiter.MaxAmountTransactionLimiter
        - com.orb.framework.wallet.model.limiter.MaxBalanceTransactionLimiter
      targets:
        self: consumer
        merchant: merchant
    execute:
      side_effects:
        - com.orb.framework.wallet.model.payment.MerchantSendMailSenderImpl
    reverse:
      side_effects:
       - 
com.orb.framework.wallet.model.transaction.reverse.ReverseResultMailSender

All transactions must have a unique name. In the example above, pay has been used. Each transaction has five top-level configuration options: coincore_event, group, strategy, single_step and steps. These components define the unique interactions.

coincore_event

In the Orb DLT stack, Coin Core is a highly configurable middleware application for creating and managing virtual currency economies. Events are used for modeling a coin economy. An event is an object that describes the steps involved in a transaction (such as “charge” or “transfer” or “payment”, for example). Click here to read more about Coin-Core.
coincore_event corresponds to the Coin Core event that will be executed during the transaction's execution phase. The same Coin Core event can be used for multiple configured transactions. This is important, because different transaction interactions, permission setups and strategies can be mapped to the same underlying DLT transaction. For example, qr-charge and cash-charge configured transactions can both be mapped to a Coin Core event called charge.

group

An economic system may include interactions that can be grouped together. For example, different types of charges (say qr-charge, cash-charge etc) can be grouped together under ‘charge’ for ease of reporting. This value corresponds to the group parameter when querying transaction history.

strategy

To further enhance a transaction, the strategy option is used to execute additional behaviors. Transaction strategies are discussed in more detail below, but sample behaviors include processing credit cards, net bank integration, merchant identification, etc.

steps

Finally, each transaction has a steps configuration. There are three predefined steps: start, execute, and reverse. Additionally modify can be defined to enhance the configuration. At least the start step must be configured. Optionally, modify, execute and reverse can be added to override and extend the default behavior. In the start step configuration, a mapping of user roles to Coin Core targets is provided. A special target, self, is available so that the transaction module can automatically determine which Coin Core target the requesting user should be mapped to.

Often, a particular transaction can instigate a side effect action in the form of sending emails, calling another API etc. You can also apply validations that govern the transaction to be sensible and feasible. This is especially useful for active transactions between different stakeholders of the economy. Therefore, validators and side_effects can be optionally included at each step of a transaction. validators are executed before a transaction step, while side_effects are executed after their completion. Please consult with your Orb representative to learn more about this configuration option.

When a transaction or strategy requires additional steps to be performed, one or more modify steps can be added to the configuration. For example, credit card charges to introduce coins into the economy are processed via an external payment gateway. modify step can be used to associate a credit card payment to a given transaction request which would return the URL for executing the payment. modify allows additional, required steps to be injected between the start and execute steps.

single_step

single_step can be configured as true to immediately call the execute step after successfully calling start. If not explicitly configured, it is default set to be false.

Transaction Strategies

Because real-world transactions depend on multiple parties and systems to acknowledge state transition, transaction strategies were developed to provide the highest level of flexibility for defining transaction behavior. Generally, strategies initiate interactions with third-party services to provide additional validation, context, and authorization for a transaction to be executed.

Simple

For configuring transactions that do not require interactions outside of the Integration Layer, simple can be used. This strategy creates a transaction where all transaction targets are known and no special validation is necessary thereby providing a simple transaction behavior for executing Orb DLT transactions.

📘

Example

QR payments can be configured using the simple strategy.

qr-payment:
  coincore_event: payment
  group: payment
  strategy: simple
  single_step: false
  steps:
    start:
      targets:
        self: consumer
        merchant: merchant
    execute: 
     side_effects:
       - com.orb.framework.wallet.model.payment.MerchantSendMailSenderImpl

📘

Example

Transfers between consumers can be configured using the simple strategy.

bluetooth-transfer:
  coincore_event: transfer
  group: transfer
  strategy: simple
  single_step: true
  steps:
    start:
      targets:
        self: consumer
        consumer: consumer

SSNB

SBI Sumishin Net Bank (SSNB) is an innovative customer-oriented internet bank. Connecting to their API enables accurate and secure acquisition of customer account balances, deposit and withdrawal details, etc. Customers in the economy can use their SSNB account to charge their wallets with coins.

To allow Integration Layer users to connect to the SSNB account, the ssnb strategy has been developed. Prior to utilizing this strategy, users will have had to go through an authentication process. After the Integration Layer has stored the user's credential it can perform operations such as deposit, withdrawal and balance inquiry before executing transactions.

📘

Example

User charges their wallet with coins via their SSNB account

ssnb-charge:
  coincore_event: charge
  group: charge
  strategy: ssnb
  single_step: true
  steps:
    start:
      validators:
        - com.orb.framework.wallet.model.limiter.MaxAmountTransactionLimiter
        - com.orb.framework.wallet.model.limiter.MaxBalanceTransactionLimiter
      targets:
        self: consumer

Coiney

Coiney is a credit card payment processor that provides a secure API that Orb interacts with to offer credit card processing. They provide an ideal environment so that Orb never has to handle a user's credit card details. All exchange of PII and credit card details are handled exclusively by Coiney via their own custom generated web pages. Coiney can be utilized as a means to introduce coins into the economy via the charge function.

The coiney strategy requires a modify step to be configured for registering a credit card processing request with Coiney's APIs. A URL will be returned as a result of this step that should be followed by the requesting user. The execute step for the coiney strategy is actually called by Coiney. This allows Coiney and Orb's servers to synchronize the credit card processing with the resulting Orb DLT transaction.

📘

Example

User charges their wallet with coins via coiney

coiney-charge:
  coincore_event: charge
  group: charge
  strategy: coiney
  single_step: false
  steps:
    start:
      targets:
        self: consumer
    associate:
    execute:

Note that associate is a modifystep that returns the URL.