Advanced Balance Modifiers

Advanced modifiers add additional flexibility on top of basic modifiers by allowing the modification amount to change based on conditions such as the requested transaction amount, time of day, or the amount of a particular coin that was used in previous operations.

Advanced modifiers are particularly useful for implementing marketing campaigns or incentivizing users to perform certain actions.

Tiered

The tiered modifier calculates the number of coins to transfer based on the original transaction amount. The tiered modifier configuration consists of a set of tiers, each defining an amount range and either an absolute amount or a percentage of the original transaction to transfer. This modifier can be useful for encouraging or discouraging coin use based on transaction size.
##Properties
The tiered modifier inherits the properties of the Basic modifier. There is one additional property for defining the list of tiers.

Each tier has the following properties.

UsageAmount is the transaction amount denoting the start point of the tier being configured. Any amount starting from UsageAmount until the next tier (if it exists) will cause this balance modifier to be executed with the given configuration for the tier.

📘

Example

In my coin economy, I want to offer higher Bonus coin payouts to consumers who spend more.

Original Transaction Amount: 175
Coins spent: 175
Bonus percentage: 2
Bonus coins received: 3

Configuration:
DecreaseTarget: “issuer”
IncreaseTarget: “consumer”
AvailableCoins: [“bonus”]
Tiers: [
UsageAmount: 0, Amount: 0
UsageAmount: 100, Percent: 2.0
UsageAmount: 1000, Percent: 5.0
]

🚧

Constraints

Either Amount or Percent must be provided. If both are provided, then Amount will be used. At least one tier must be configured, and the first tier’s usage amount must start at zero. Note that percentage can be greater than 100%.

Tiered Dependent

The tiered dependent modifier calculates the number of coins to transfer based on the usage of a specific coin in a previous modifier in the event. Like the tiered modifier, the tiered dependent modifier configuration takes a set of tiers, each defining an amount range and either an absolute amount or a percentage of the original transaction to transfer. This modifier can especially be useful for rewarding users for using more or less of a particular coin type.
##Properties

The tiered modifier inherits the properties of the Basic and Dependent modifiers. There is one additional property for defining the list of tiers.

Each tier has the following properties:

UsageAmount is the (inclusive) transaction amount from which the tier will be used.

📘

Example

In my coin economy, I want to offer higher Bonus coin payouts to consumers who spend more purple coins.

Original Transaction Amount (Purple coins): 1080
Coins spent: 1080
Bonus received: 10% (108 bonus coins)

Configuration:
DecreaseTarget: “issuer”
IncreaseTarget: “consumer”
AvailableCoins: [“bonus”]
DependentCoinID: “purple”
Tiers: [
UsageAmount: 0, Amount: 0
UsageAmount: 100, Amount: 5
UsageAmount: 1000, Percent: 10.0
]

🚧

Constraints

• Either Amount or Percent must be provided. If both are provided, then Amount will be used. At least one tier must be configured, and the first tier’s usage amount must start at zero.

• When configuring an event with a tiered dependent modifier, the tiered dependent modifier must not be the first modifier to be executed in the event. This would always result in a zero modification amount when the modifier is executed.

Tiered Time

The tiered time modifier calculates the number of coins to transfer based on the time when the transaction takes place. Like the tiered modifier, the tiered time modifier configuration consists of a set of tiers with either an absolute amount or a percentage of the original transaction to transfer. This modifier can be useful for encouraging users to make transactions at certain times during the day (i.e., time campaigns).
##Properties
The tiered time modifier inherits the properties of the Basic modifier. Like the tiered modifier, there is a property for defining the list of tiers.

Each tier has the following properties.

Time is the transaction time denoting the start point of the tier being configured. Any transaction conducted during the period starting from Time up until the next tiered time will cause this balance modifier to be executed with the given configuration for the tier.

📘

Example

In my coin economy, I want to offer higher Bonus coin payouts to consumers between the hours of 17:00 and 20:00 to encourage spending during those times.

Original transaction amount: 100
Time of transaction: 19:06:21
Coins spent: 100
Bonus percentage: 10
Bonus coins received: 10

Configuration:
DecreaseTarget: “issuer”
IncreaseTarget: “consumer”
AvailableCoins: [“bonus”]
Tiers: [
Time: 00:00:00, Percent: 0.0
Time: 17:00:00, Percent: 10.0
Time: 20:00:00, Percent: 1.0
]

🚧

Constraints

• Either Amount or Percent must be provided. If both are provided, then Amount will be used.

• At least one tier must be configured, and the first tier’s usage amount must start at midnight (00:00:00).

Priority Spend

The priority spend modifier calculates the number of coins to transfer based on the priority set at the time of event execution.
##Properties
The priority spend modifier inherits the properties of the Basic balance modifier. There are no additional configuration properties.
##Usage
The misc property of the request payload while executing the /transactions endpoint is used to specify the spending order. Usually, the misc property is an optional map that is used to add additional context to the coin event, but in the case of the priority spend modifier, misc is required. A map of configuration must be added to the misc map using the key: priority.

🚧

NOTE

If the full transaction amount is not consumed after implementing each configuration entry, an error will be returned. In addition, it is not required for all configuration entries to be implemented for a coin event to be successfully executed.

Each configuration entry can have the following parameters:

Note that if both amount and percentage are provided, then amount will be used.

📘

Example

During the coin event execution, I want to spend red coins before using blue coins for the remaining transaction amount.

...
"misc": {
[{
"coin": "red"
},{
"coin": "blue"
}]
}
...

📘

Example

During the coin event execution, I want to spend 150 red coins before using blue coins for the remaining transaction amount.

...
"misc": {
[{
"coin": "red",
"amount": "150"
},{
"coin": "blue"
}]
}
...