AmountTransfer
Keywords: net.corda.core.contracts.AmountTransfer class
Date: 2023-09-18

net.corda.core.contracts

## Class AmountTransfer<T,P>

- net.corda.core.contracts.AmountTransfer<T,P>

-     public class AmountTransfer<T,P>

  This class represents a possibly negative transfer of tokens from one vault state to another, possibly at a future date.

- - ### Field Detail

    - #### Companion

          public static net.corda.core.contracts.AmountTransfer.Companion Companion

  - ### Constructor Detail

    - #### AmountTransfer

          public AmountTransfer(long quantityDelta,
                                @NotNull
                                T token,
                                @NotNull
                                P source,
                                @NotNull
                                P destination)

      This class represents a possibly negative transfer of tokens from one vault state to another, possibly at a future date.

      Parameters:
        `quantityDelta` - is a signed Long value representing the exchanged number of tokens. If positive thenit represents the movement of Math.abs(quantityDelta) tokens away from source and receipt of Math.abs(quantityDelta)at the destination. If the quantityDelta is negative then the source will receive Math.abs(quantityDelta) tokensand the destination will lose Math.abs(quantityDelta) tokens.Where possible the source and destination should be coded to ensure a positive quantityDelta,but in various scenarios it may be more consistent to allow positive and negative values.For example it is common for a bank to code asset flows as gains and losses from its perspective i.e. always the destination.
        `token` - represents the type of asset token as would be used to construct Amount objects.
        `source` - is the `class Party`, `class CompositeKey`, or other identifier of the token source if quantityDelta is positive,or the token sink if quantityDelta is negative. The type P should support value equality.
        `destination` - is the `class Party`, `class CompositeKey`, or other identifier of the token sink if quantityDelta is positive,or the token source if quantityDelta is negative. The type P should support value equality.

  - ### Method Detail

    - #### plus

          @NotNull
          public AmountTransfer<T,P> plus(@NotNull
                                                   AmountTransfer<T,P> other)

      Add together two `class AmountTransfer` objects to produce the single equivalent net flow. The addition only applies to AmountTransfer objects with the same token type. Also the pair of parties must be aligned, although source destination may be swapped in the second item.

      Throws:
        `ArithmeticException` - if there is underflow, or overflow in the summations.
      See Also:
        `class AmountTransfer`

    - #### toDecimal

          @NotNull
          public java.math.BigDecimal toDecimal()

      Convert the quantityDelta to a displayable format BigDecimal value. The conversion ratio is the same as for `class Amount` of the same token type.

      See Also:
        `class Amount`

    - #### equals

          public boolean equals(@Nullable
                                java.lang.Object other)

      Checks value equality of AmountTransfer objects, but also matches the reversed source and destination equivalent.

    - #### hashCode

          public int hashCode()

      This hash code function ensures that reversed source and destination equivalents will hash to the same value.

    - #### novate

          @NotNull
          public java.util.List<net.corda.core.contracts.AmountTransfer> novate(@NotNull
                                                                                         P centralParty)

      Returns a list of two new AmountTransfers each between one of the original parties and the centralParty. The net total exchange is the same as in the original input. Novation is a common financial operation in which a bilateral exchange is modified so that the same relative asset exchange happens, but with each party exchanging versus a central counterparty, or clearing house.

      Parameters:
        `centralParty` - The central party to face the exchange against.

    - #### apply

          @NotNull
          public java.util.List<net.corda.core.contracts.SourceAndAmount> apply(@NotNull
                                                                                         java.util.List<? extends net.corda.core.contracts.SourceAndAmount<T,? extends P>> balances,
                                                                                         @Nullable
                                                                                         java.lang.Object newRef)

      Applies this AmountTransfer to a list of `class SourceAndAmount` objects representing balances. The list can be heterogeneous in terms of token types and parties, so long as there is sufficient balance of the correct token type held with the party paying for the transfer.

      Parameters:
        `balances` - The source list of `class SourceAndAmount` objects containing the funds to satisfy the exchange.
        `newRef` - An optional marker object which is attached to any new `class SourceAndAmount` objects created in the output.i.e. To the new payment destination entry and to any residual change output.
      Returns:
        A copy of the original list, except that funds needed to cover the exchange will have been removed and a new output and possibly residual amount entry will be added at the end of the list.
      Throws:
        `ArithmeticException` - if there is underflow in the summations.
      See Also:
        `class SourceAndAmount`

    - #### getQuantityDelta

          public long getQuantityDelta()

      is a signed Long value representing the exchanged number of tokens.

      If positive thenit represents the movement of Math.abs(quantityDelta) tokens away from source and receipt of Math.abs(quantityDelta)at the destination. If the quantityDelta is negative then the source will receive Math.abs(quantityDelta) tokensand the destination will lose Math.abs(quantityDelta) tokens.Where possible the source and destination should be coded to ensure a positive quantityDelta,but in various scenarios it may be more consistent to allow positive and negative values.For example it is common for a bank to code asset flows as gains and losses from its perspective i.e. always the destination.

    - #### getToken

          @NotNull
          public T getToken()

      represents the type of asset token as would be used to construct Amount

      objects.

    - #### getSource

          @NotNull
          public P getSource()

      is the

      `class Party`, `class CompositeKey`, or other identifier of the token source if quantityDelta is positive,or the token sink if quantityDelta is negative. The type P should support value equality.

      See Also:
        `class Party`, `class CompositeKey`

    - #### getDestination

          @NotNull
          public P getDestination()

      is the

      `class Party`, `class CompositeKey`, or other identifier of the token sink if quantityDelta is positive,or the token source if quantityDelta is negative. The type P should support value equality.

      See Also:
        `class Party`, `class CompositeKey`

    - #### fromDecimal

          @JvmStatic
           @JvmOverloads
           @NotNull
          public static <T,P> AmountTransfer<T,P> fromDecimal(@NotNull
                                                                                                  java.math.BigDecimal displayQuantityDelta,
                                                                                                  @NotNull
                                                                                                  T token,
                                                                                                  @NotNull
                                                                                                  P source,
                                                                                                  @NotNull
                                                                                                  P destination,
                                                                                                  @NotNull
                                                                                                  java.math.RoundingMode rounding)

      Construct an AmountTransfer object from an indicative/displayable BigDecimal source, applying rounding as specified. The token size is determined from the token type and is the same as for `class Amount` of the same token.

      Parameters:
        `displayQuantityDelta` - is the signed amount to transfer between source and destination in displayable units.Positive values mean transfers from source to destination. Negative values mean transfers from destination to source.
        `token` - defines the asset being represented in the transfer. The token should implement `interface TokenizableAssetInfo` if customconversion logic is required.
        `source` - The payer of the transfer if displayQuantityDelta is positive, the payee if displayQuantityDelta is negative
        `destination` - The payee of the transfer if displayQuantityDelta is positive, the payer if displayQuantityDelta is negative
        `rounding` - The mode of rounding to apply after scaling to integer token units.
      See Also:
        `class Amount`

    - #### fromDecimal

          @JvmStatic
           @JvmOverloads
           @NotNull
          public static <T,P> AmountTransfer<T,P> fromDecimal(@NotNull
                                                                                                  java.math.BigDecimal displayQuantityDelta,
                                                                                                  @NotNull
                                                                                                  T token,
                                                                                                  @NotNull
                                                                                                  P source,
                                                                                                  @NotNull
                                                                                                  P destination)

      Construct an AmountTransfer object from an indicative/displayable BigDecimal source, applying rounding as specified. The token size is determined from the token type and is the same as for `class Amount` of the same token.

      Parameters:
        `displayQuantityDelta` - is the signed amount to transfer between source and destination in displayable units.Positive values mean transfers from source to destination. Negative values mean transfers from destination to source.
        `token` - defines the asset being represented in the transfer. The token should implement `interface TokenizableAssetInfo` if customconversion logic is required.
        `source` - The payer of the transfer if displayQuantityDelta is positive, the payee if displayQuantityDelta is negative
        `destination` - The payee of the transfer if displayQuantityDelta is positive, the payer if displayQuantityDelta is negative
      See Also:
        `class Amount`

    - #### zero

          @JvmStatic
           @NotNull
          public static <T,P> AmountTransfer<T,P> zero(@NotNull
                                                                            T token,
                                                                            @NotNull
                                                                            P source,
                                                                            @NotNull
                                                                            P destination)

      Helper to make a zero size AmountTransfer.