Package io.fliqa.client.interledger.model

Class InterledgerAmount

java.lang.Object
io.fliqa.client.interledger.model.InterledgerAmount
public class InterledgerAmount extends Object
Represents a monetary amount in the Interledger Protocol format.

This class encapsulates the three components required for representing monetary amounts in the Interledger network: the asset code (currency), the asset scale (precision), and the amount value (as an unsigned 64-bit integer string).

The Interledger Protocol uses a specific format for amounts to ensure precision and consistency across different systems and currencies. Amounts are represented as scaled integers to avoid floating-point precision issues.

Example: $12.34 USD would be represented as:

  • assetCode: "USD"
  • assetScale: 2
  • amount: "1234" (12.34 * 10^2)
Since:
1.0

  • Field Details

    • DEFAULT_AMOUNT_SCALE

      public static final int DEFAULT_AMOUNT_SCALE
      The default scale for monetary amounts (2 decimal places).

      This is the most common scale used for traditional currencies, representing cents, pence, or similar subunits.

      See Also:

    • assetCode

      public String assetCode
      The asset code indicating the underlying asset.

      This should be an ISO4217 currency code such as "USD", "EUR", "GBP", etc. The asset code identifies the type of value being represented and must be exactly 3 characters long.

      See Also:

    • assetScale

      public int assetScale
      The scale of amounts denoted in the corresponding asset code.

      This represents the number of decimal places in the amount. For example, a scale of 2 means the amount is expressed in hundredths (cents for USD). The scale must be between 0 and 255.

      Common scales:

      • 0 - Whole units (e.g., Japanese Yen)
      • 2 - Cents/pence (e.g., USD, EUR, GBP)
      • 3 - Mills (e.g., some cryptocurrencies)

    • amount

      public String amount
      The value as an unsigned 64-bit integer amount, represented as a string.

      This is the actual amount value scaled by the asset scale. For example, if the human-readable amount is $12.34 and the scale is 2, this value would be "1234" (12.34 * 10^2).

      The value is stored as a string to avoid precision issues and to support the full range of 64-bit unsigned integers.

  • Constructor Details

    • InterledgerAmount

      public InterledgerAmount()

  • Method Details

    • asBigDecimal

      public BigDecimal asBigDecimal()
      Converts this InterledgerAmount to a BigDecimal representation.

      This method converts the scaled integer amount back to a decimal representation by moving the decimal point left by the asset scale.

      Returns:
      a BigDecimal representing the human-readable amount

    • build

      public static InterledgerAmount build(BigDecimal amount, String assetCode)
      Builds an InterledgerAmount object by converting the provided BigDecimal amount into an Interledger formatted amount (string representation) with a default scale of 2 and asset code.
      Parameters:
      amount - the monetary value, must not be null
      assetCode - the asset code, must be a non-empty string with 3 characters (ISO4217 currency code)
      Returns:
      InterledgerAmount instance representing the given parameters

    • build

      public static InterledgerAmount build(BigDecimal amount, String assetCode, int scale)
      Builds an InterledgerAmount object by converting the provided BigDecimal amount into an Interledger formatted amount (string representation) with the specified scale and asset code.
      Parameters:
      amount - the monetary value, must not be null
      assetCode - the asset code, must be a non-empty string with 3 characters (ISO4217 currency code)
      scale - the scale/precision for the amount, must be between 0-255
      Returns:
      InterledgerAmount instance representing the given parameters

    • toInterledgerAmount

      public static String toInterledgerAmount(BigDecimal amount, int amountScale)
      Converts a BigDecimal amount to an Interledger amount string representation.

      This method scales the decimal amount by the specified scale and converts it to a string representation suitable for Interledger protocol usage. The amount is first rounded to 2 decimal places, then scaled by the power of 10 corresponding to the amount scale.

      Parameters:
      amount - the BigDecimal amount to convert
      amountScale - the scale to apply (number of decimal places)
      Returns:
      the string representation of the scaled amount

    • toInterledgerAmount

      public static String toInterledgerAmount(BigDecimal amount)
      Converts a BigDecimal amount to an Interledger amount string using the default scale.

      This is a convenience method that uses the DEFAULT_AMOUNT_SCALE to convert the amount.

      Parameters:
      amount - the BigDecimal amount to convert
      Returns:
      the string representation of the scaled amount

    • toString

      public String toString()
      Overrides:
      toString in class Object