Objects

Objects are types that define the what, who, and how of a coin economy. Coins specify what assets are available, targets define who can participate in transactions using those assets, and events define how those assets may be used. The upcoming sections will go into the details of each of these objects.

Coin

A coin is an object type that represents an asset in the Coin Core ledger. Coins are issued from the Issuer account and are transferred between accounts using balance modifiers, which are modular components used to build logical transaction types called events. Balance modifiers and events are covered in later sections.
##Properties
The attributes of a coin object are described using properties. Common properties are presented in the following table.

At a minimum, each coin object must define the ID property. ID is used as a reference to a coin object during a transaction and must, therefore, be unique. Each coin object also has an optional Label property which can be used to write a short description of the coin.

Other properties are inherited from specific coin behaviors, which can be configured separately from the coin object itself.
##Behaviors
Behaviors define the basic functionality and lifespan of coin objects. They are classified as expiration and diminishment.
###Expiration

Expiration behavior defines the validity period of a coin type and lifespan of issued coin assets. Coins that have expired are automatically returned to the issuer account on the next transaction involving the account holding the expired coins. This means that there may potentially be a long time between the time when a coin expires and when it is reclaimed (returned to the issuer’s account). If it is necessary to reclaim coins quickly, it may be necessary to force the reclamation to take place by including the account in a transaction.

A validity period can be set for a coin type to make that coin available for use for a desired period of time. When the validity period of a coin type ends, all issued coins of that type are considered expired. The validity period of a coin type is defined using a combination of the StartDate and EndDate properties. StartDate is a timestamp defining the earliest time at which a coin type is valid. Similarly, EndDate is a timestamp defining the latest time at which a coin type is valid. Validity periods may be bounded (have both a StartDate and an EndDate), or open (has either a StartDate or an EndDate, but not both).

In addition to a validity period, coins can also be assigned an expiration period using the ExpirePeriod property. ExpirePeriod applies to issued coins and is measured against either StartDate or the coin issue date, whichever is later. If no ExpirePeriod is set, or the period is 0, then the coin asset will not expire for the remainder of the validity period.

If a coin has both an expire period and a validity period with an end date, the coins will expire at whichever time is earlier.

Diminishment

Similar to expiration, the diminishment behavior provides a mechanism to reclaim issued coins. It differs from expiration in that a coin balance may be gradually reclaimed over time at customizable intervals. Similar to expiration, diminished coins are automatically returned to the issuer account only on the next transaction following the customizable interval.

Please note that expired and diminished coins are only removed from an account once that account participates in a transaction. This means that there may potentially be a long time between the time when a coin expires and when it is reclaimed (returned to the issuer’s account). If it is necessary to reclaim coins quickly it may be necessary to force the reclamation to take place by including the account in a transaction.

Diminishment is enabled when the Diminishment property is specified. The Diminishment property has several sub-properties which define the parameters of the behavior.

Diminishment occurs at set time intervals starting from the time that coins are issued. These intervals are measured in seconds and can be set to any period greater than one hour (3600 seconds) using the Period property.

The amount of diminishment is calculated using either the current balance or the original balance. As the name suggests, current balance is the balance of a coin type owned by an account at any particular time. The amount of diminishment when using the current balance as a reference is simply the percent of the current balance specified by the Percent property. If neither current nor original is set in the Reference property, diminishment is calculated against current balance. It should be noted that if the reference property is set to null, it will not run correctly and show an error.

Original balance is the total of coin balance increases of a given coin type that occur each hour. The following diagram illustrates the relationship between the current and original balance.

In the above diagram, blue bars represent balance increases and red bars represent balance decreases. Whenever the balance is increased, both the original balance (pink line) and the current balance increase. However, when a balance is decreased the original balance remains the same and only the current balance is reduced. The value of original and current balance at the end of the one hour period are the values that will be used when calculating diminishments.

Target

A target is an object that refers to the role that an account takes in a given transaction (such as “consumer” or “merchant” or “shop”, for example). When executing a transaction each target is linked to a specific account. This mapping is then used by balance modifiers to update account balances.

Coin Core implicitly defines one target: the issuer target. The issuer target always refers to the issuer account. Additional targets can be defined in the target configuration to suit the desired use case.

It is possible to restrict an account to certain roles by setting the desired targets when creating the account. For example, if your coin economy has a “merchant” target and you want accounts owned by merchants to only be used as the merchant target in transactions, you can set the “merchant” target for that account in Account Core. For details on how to configure accounts and account targets, see the Account Core User Guide.
##Properties

Each target object has a single required property: the ID property. ID is used to refer to the target when creating a transaction and must be unique.

Event

An event is an object that describes the steps involved in a transaction (such as “charge” or “transfer” or “payment”, for example). Events are composed of one or more balance modifiers. When executing an event, the transaction executor applies each of the modifiers in sequence.
##Properties

Each event has three main properties: ID, Description, and Modifiers. ID is an identifier used to refer to the event when creating a transaction. It must be unique. Description is an optional property which can be used to set a short description of the event. The Modifiers property is a list of balance modifiers that make up the event.