Simple Balance Modifiers

Another brief intro will be needed to describe simple balance modifiers. The different types are basic, basic with fee, max use and dependent.

Basic

The basic modifier performs a simple modification against a maximum of two account balance records. Coin Core uses the operations of the basic modifier to build more complicated balance modifiers. At least two ledger entry records for two separate targets will be produced as a result of the basic modifier being executed.

📘

Example

In my coin economy, I want to issue a bonus coin to a consumer based on the transaction amount of a purchase. The basic modifier can be used to perform this operation.

Properties

The characteristics of the basic modifier are configured using the properties listed in the table below.

To correctly configure a basic modifier both DecreaseTarget and IncreaseTarget values must be set to valid target identifiers.

The AvailableCoins or UnavailableCoins properties can be used to restrict which coins are allowed to be used during a modifier operation. It is possible to set either AvailableCoins, UnavailableCoins or neither, but setting both will not be respected when the configuration is loaded. If both properties are set in the modifier configuration, only the AvailableCoins value will be used. If neither of these properties is set, all coins will be available to be used when the event is executed.

The Amount and Percentage properties allow for some flexibility when calculating the amount added or deducted in a transaction.

If the Amount property is set, a static amount that overrides the transaction amount will be used when operating against a balance.

📘

Example

In my coin economy, I want to issue an absolute bonus amount to a consumer irrespective of the transaction amount.

Original Transaction Amount: [Any]
Absolute Amount: 20
Decrease amount for issuer: 20 bonus coins
Increase amount for consumer: 20 bonus coins

Configuration:
DecreaseTarget: “issuer”
IncreaseTarget: “consumer”
AvailableCoins: [
“bonus”
]
Amount: 20

If the Percentage property is set, a new transaction amount will be calculated based on the original transaction amount. Note that percentage can be greater than 100%.

📘

Example

In my coin economy, I want to issue a bonus amount to a consumer on a percentage basis of the transaction amount.

Original Transaction Amount: 100
Percentage of Transaction: 10.0%
Decrease amount for issuer: 10 bonus coins
Increase amount for consumer: 10 bonus coins

Configuration:
DecreaseTarget: “issuer”
IncreaseTarget: “consumer”
AvailableCoins: [
“bonus”
]
Percentage: 10.0

note: Coin-Core will round down calculations that result in fractional amounts.

🚧

Constraint

If both Amount and Percentage properties are set in the modifier configuration, only the Amount value will be used. If neither properties are set in the configuration, the basic modifier will operate against the balance records using an unmodified transaction amount. Even if no amounts change for any target, a transaction will be recorded.

If the DecreaseTarget property is set to issuer, only one coin can be specified in the AvailableCoins property list. This is because the modifier does not understand how to split the issuance amount across multiple coin types.

BasicFee

By using the basic modifier as a building block, the basic fee modifier can be created. This modifier adds an additional increasing target called the FeeTarget in which a portion of the transaction amount can be sent to the fee target. The modifier will produce at least three ledger entry records when the modifier has been executed.
##Properties

The basic fee modifier inherits the properties of the basic modifier. Additional properties are presented in the following table.

The FeeTarget identifies the account which will receive the fee amount, and the FeePercentage will be used to calculate that amount.

📘

Example

In my coin economy, I want to impose a 5% transaction fee when the merchant completes a transaction with a consumer.

Original Transaction Amount: 100
Fee Percentage: 5%
Decrease amount for consumer: 100 coins
Fee increase amount for issuer: 5 coins
Increase amount for merchant: 95 coins

Configuration:
DecreaseTarget: “consumer”
IncreaseTarget: “merchant”
FeeTarget: “issuer”
FeePercentage: 5.0

note: Coin Core will round down calculations that result in fractional amounts.

MaxUse

The max-use modifier can be used to restrict usage of a specific coin type during a transaction. This is a very interesting modifier to build events around because this can create scenarios where some coins become more "important" or “valuable” than others in the coin economy. This modifier also builds upon the basic modifier.
##Properties
The max-use modifier inherits the properties of the basic modifier. Additional properties are presented in the following table:

The MaxCoinID identifies the coin type that will be restricted during a transaction event.

The MaxAmount and MaxPercentage properties operate similar to the Amount and Percentage properties of the basic modifier. At any instance, either MaxAmount or MaxPercentage must be set.

If the MaxAmount property is set, a static amount will be used to determine the max-usage restriction.

📘

Example

In my coin economy, I want to restrict the usage of green coins to a max of 10 during the coin transaction event.

Starting green coin balance: 60
Starting red coin balance: 100
Original Transaction Amount: 50
Max Coin ID: green
Max Absolute Amount: 10
Decrease amount for consumer: 10 green coins and 40 red coins
Increase amount for merchant: 10 green coins and 40 red coins
Remaining green coin balance: 50
Remaining red coin balance: 60

Configuration:
DecreaseTarget: “consumer”
IncreaseTarget: “merchant”
MaxCoinID: green
MaxAmount: 10

If the MaxPercentage property is set, a percentage of the transaction amount will be calculated to determine the max-usage restriction.

📘

Example

In my coin economy, I want to restrict the usage of green coins to a max of 10% of the transaction amount during the coin transaction event.

Starting green coin balance: 60
Starting red coin balance: 100
Original Transaction Amount: 50
Max Coin ID: green
Max Percentage: 10%
Decrease amount for consumer: 5 green coins and 45 red coins
Increase amount for merchant: 5 green coins and 45 red coins
Remaining green coin balance: 55
Remaining red coin balance: 55

Configuration:
DecreaseTarget: “consumer”
IncreaseTarget: “merchant”
MaxCoinID: green
MaxPercentage: 10.0

🚧

Constraints

Similarly to the basic modifier, if both MaxAmount and MaxPercentage properties are set in the modifier configuration, only the MaxAmount value will be used.

Dependent

The dependent modifier calculates the number of coins to transfer based on the usage of a specific coin in a previous modifier in the event. Since this modifier relies on previous balance modifications, it must always be combined with another modifier to function properly.
##Properties
The characteristics of the dependent modifier inherit the properties of the basic modifier. Additional properties are presented in the following table.

The DependentCoinID identifies a coin type that may have been used in a previous modification. The amount transferred in that modification is used to calculate the dependent modifier's amount.

The dependent modifier uses the Amount and Percentage properties provided by the basic modifier to determine the modification amount. If the Amount property is set, a static amount will be used to determine the modification amount.

📘

Example:

In my coin economy, I want to offer an absolute cash-back to consumers when blue coins are used to pay a merchant.

Original Transaction Amount: 100
Blue coins spent: 100
Dependent ID: blue
Amount: 20
Blue coin cash-back: 20

Configuration:
DecreaseTarget: “issuer”
IncreaseTarget: “consumer”
DependentCoinID: blue
Amount: 20

If the Percentage property is set, a percentage of the dependent coin usage amount will be calculated to determine the modification amount. Note that percentage can be greater than 100%.

📘

Example

In my coin economy, I want to offer a 8% cash-back to consumers when blue coins are used to pay a merchant.

Blue coin balance: 60
Green coin balance: 100
Original Transaction Amount: 100
Blue coins spent: 60
Green coins spent: 40
Dependent ID: blue
Percentage: 8
Blue coin cash-back: 4

Configuration:
DecreaseTarget: “issuer”
IncreaseTarget: “consumer”
DependentCoinID: blue
Percentage: 8.0

🚧

Constraints

When configuring an event with a dependent modifier, the 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.

The same constraints apply regarding Amount and Percentage. If both properties are set, only the Amount value will be used.