OnLedgerAsset
Keywords: net.corda.finance.contracts.asset.OnLedgerAsset class
Date: 2023-09-18

net.corda.finance.contracts.asset

## Class OnLedgerAsset<T,C extends CommandData,S extends FungibleAsset<T>>

- net.corda.finance.contracts.asset.OnLedgerAsset<T,C,S>

- All Implemented Interfaces:
    Contract
  Direct Known Subclasses:
    Cash

      public class OnLedgerAsset<T,C extends CommandData,S extends FungibleAsset<T>>
      implements Contract

  An asset transaction may split and merge assets represented by a set of (issuer, depositRef) pairs, across multiple input and output states. Imagine a Bitcoin transaction but in which all UTXOs had a colour (a blend of issuer+depositRef) and you couldn't merge outputs of two colours together, but you COULD put them in the same transaction.

  The goal of this design is to ensure that assets can be withdrawn from the ledger easily: if you receive some asset via this contract, you always know where to go in order to extract it from the R3 ledger, no matter how many hands it has passed through in the intervening time.

  At the same time, other contracts that just want assets and don't care much who is currently holding it can ignore the issuer/depositRefs and just examine the amount fields.

- - ### Field Detail

    - #### Companion

          public static net.corda.finance.contracts.asset.OnLedgerAsset.Companion Companion

  - ### Constructor Detail

    - #### OnLedgerAsset

          public OnLedgerAsset()

      An asset transaction may split and merge assets represented by a set of (issuer, depositRef) pairs, across multiple input and output states. Imagine a Bitcoin transaction but in which all UTXOs had a colour (a blend of issuer+depositRef) and you couldn't merge outputs of two colours together, but you COULD put them in the same transaction.

      The goal of this design is to ensure that assets can be withdrawn from the ledger easily: if you receive some asset via this contract, you always know where to go in order to extract it from the R3 ledger, no matter how many hands it has passed through in the intervening time.

      At the same time, other contracts that just want assets and don't care much who is currently holding it can ignore the issuer/depositRefs and just examine the amount fields.

  - ### Method Detail

    - #### extractCommands

          @NotNull
          public java.util.Collection<net.corda.core.contracts.CommandWithParties> extractCommands(@NotNull
                                                                                                            java.util.Collection<? extends net.corda.core.contracts.CommandWithParties<? extends net.corda.core.contracts.CommandData>> commands)

    - #### generateExit

          @Deprecated
           @NotNull
          public java.util.Set<java.security.PublicKey> generateExit(@NotNull
                                                                                           TransactionBuilder tx,
                                                                                           @NotNull
                                                                                           Amount<net.corda.core.contracts.Issued> amountIssued,
                                                                                           @NotNull
                                                                                           java.util.List<? extends net.corda.core.contracts.StateAndRef<? extends S>> assetStates)

      Deprecated.

      Generate an transaction exiting assets from the ledger.

      Parameters:
        `tx` - transaction builder to add states and commands to.
        `amountIssued` - the amount to be exited, represented as a quantity of issued currency.
        `assetStates` - the asset states to take funds from. No checks are done about ownership of these states, it isthe responsibility of the caller to check that they do not exit funds held by others.
      Returns:
        the public keys which must sign the transaction for it to be valid.

    - #### generateExit

          @NotNull
          public java.util.Set<java.security.PublicKey> generateExit(@NotNull
                                                                              TransactionBuilder tx,
                                                                              @NotNull
                                                                              Amount<net.corda.core.contracts.Issued> amountIssued,
                                                                              @NotNull
                                                                              java.util.List<? extends net.corda.core.contracts.StateAndRef<? extends S>> assetStates,
                                                                              @NotNull
                                                                              AbstractParty payChangeTo)

      Generate an transaction exiting assets from the ledger.

      Parameters:
        `tx` - transaction builder to add states and commands to.
        `amountIssued` - the amount to be exited, represented as a quantity of issued currency.
        `assetStates` - the asset states to take funds from. No checks are done about ownership of these states, it isthe responsibility of the caller to check that they do not exit funds held by others.
      Returns:
        the public keys which must sign the transaction for it to be valid.

    - #### generateExitCommand

          @NotNull
          public CommandData generateExitCommand(@NotNull
                                                          Amount<net.corda.core.contracts.Issued> amount)

    - #### generateMoveCommand

          @NotNull
          public MoveCommand generateMoveCommand()

    - #### deriveState

          @NotNull
          public TransactionState<S> deriveState(@NotNull
                                                          TransactionState<? extends S> txState,
                                                          @NotNull
                                                          Amount<net.corda.core.contracts.Issued> amount,
                                                          @NotNull
                                                          AbstractParty owner)

      Derive a new transaction state based on the given example, with amount and owner modified. This allows concrete implementations to have fields in their state which we don't know about here, and we simply leave them untouched when sending out "change" from spending/exiting.

    - #### generateSpend

          @JvmStatic
           @NotNull
          public static <S extends FungibleAsset<T>,T> kotlin.Pair<net.corda.core.transactions.TransactionBuilder,java.util.List> generateSpend(@NotNull
                                                                                                                                                                     TransactionBuilder tx,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     Amount<T> amount,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     AbstractParty to,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     java.util.List<? extends net.corda.core.contracts.StateAndRef<? extends S>> acceptableStates,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     AbstractParty payChangeTo,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     kotlin.jvm.functions.Function3<? super net.corda.core.contracts.TransactionState<? extends S>,? super net.corda.core.contracts.Amount<net.corda.core.contracts.Issued<T>>,? super net.corda.core.identity.AbstractParty,? extends net.corda.core.contracts.TransactionState<? extends S>> deriveState,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     kotlin.jvm.functions.Function0<? extends net.corda.core.contracts.CommandData> generateMoveCommand)

      Generate a transaction that moves an amount of currency to the given pubkey.

      Note: an `class Amount` of Currency is only fungible for a given Issuer Party within a `interface FungibleAsset`

      Parameters:
        `tx` - A builder, which may contain inputs, outputs and commands already. The relevant components needed to move the cash will be added on top.
        `amount` - How much currency to send.
        `to` - a key of the recipient.
        `acceptableStates` - a list of acceptable input states to use.
        `payChangeTo` - party to pay any change to; this is normally a confidential identity of the callingparty.
        `deriveState` - a function to derive an output state based on an input state, amount for the outputand public key to pay to.
      Returns:
        A Pair of the same transaction builder passed in as `tx`, and the list of keys that need to sign the resulting transaction for it to be valid.
      Throws:
        `InsufficientBalanceException` - when a cash spending transaction fails because there is insufficient quantity for a given currency (and optionally set of Issuer Parties).
      See Also:
        `class Amount`, Currency, `interface FungibleAsset`

    - #### generateSpend

          @JvmStatic
           @NotNull
          public static <S extends FungibleAsset<T>,T> kotlin.Pair<net.corda.core.transactions.TransactionBuilder,java.util.List> generateSpend(@NotNull
                                                                                                                                                                     TransactionBuilder tx,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     java.util.List<net.corda.finance.contracts.asset.PartyAndAmount> payments,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     java.util.List<? extends net.corda.core.contracts.StateAndRef<? extends S>> acceptableStates,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     AbstractParty payChangeTo,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     kotlin.jvm.functions.Function3<? super net.corda.core.contracts.TransactionState<? extends S>,? super net.corda.core.contracts.Amount<net.corda.core.contracts.Issued<T>>,? super net.corda.core.identity.AbstractParty,? extends net.corda.core.contracts.TransactionState<? extends S>> deriveState,
                                                                                                                                                                     @NotNull
                                                                                                                                                                     kotlin.jvm.functions.Function0<? extends net.corda.core.contracts.CommandData> generateMoveCommand)

      Adds to the given transaction states that move amounts of a fungible asset to the given parties, using only the provided acceptable input states to find a solution (not all of them may be used in the end). A change output will be generated if the state amounts don't exactly fit.

      The fungible assets must all be of the same type and the amounts must be summable i.e. amounts of the same token.

      Type Parameters:
        `S` -

        A fungible asset state type

        `T` -

        A type representing a token

      Parameters:
        `tx` - A builder, which may contain inputs, outputs and commands already. The relevant components needed to move the cash will be added on top.
        `acceptableStates` - a list of acceptable input states to use.
        `payChangeTo` - party to pay any change to; this is normally a confidential identity of the callingparty. We use a new confidential identity here so that the recipient is not identifiable.
        `deriveState` - a function to derive an output state based on an input state, amount for the outputand public key to pay to.
      Returns:
        A Pair of the same transaction builder passed in as `tx`, and the list of keys that need to sign the resulting transaction for it to be valid.
      Throws:
        `InsufficientBalanceException` - when a cash spending transaction fails because there is insufficient quantity for a given currency (and optionally set of Issuer Parties).

    - #### generateExit

          @JvmStatic
           @Deprecated
           @NotNull
          public static <S extends FungibleAsset<T>,T> java.util.Set<java.security.PublicKey> generateExit(@NotNull
                                                                                                                                             TransactionBuilder tx,
                                                                                                                                             @NotNull
                                                                                                                                             Amount<net.corda.core.contracts.Issued> amountIssued,
                                                                                                                                             @NotNull
                                                                                                                                             java.util.List<? extends net.corda.core.contracts.StateAndRef<? extends S>> assetStates,
                                                                                                                                             @NotNull
                                                                                                                                             kotlin.jvm.functions.Function3<? super net.corda.core.contracts.TransactionState<? extends S>,? super net.corda.core.contracts.Amount<net.corda.core.contracts.Issued<T>>,? super net.corda.core.identity.AbstractParty,? extends net.corda.core.contracts.TransactionState<? extends S>> deriveState,
                                                                                                                                             @NotNull
                                                                                                                                             kotlin.jvm.functions.Function0<? extends net.corda.core.contracts.CommandData> generateMoveCommand,
                                                                                                                                             @NotNull
                                                                                                                                             kotlin.jvm.functions.Function1<? super net.corda.core.contracts.Amount<net.corda.core.contracts.Issued<T>>,? extends net.corda.core.contracts.CommandData> generateExitCommand)

      Deprecated.

      Generate an transaction exiting fungible assets from the ledger.

      Parameters:
        `tx` - transaction builder to add states and commands to.
        `amountIssued` - the amount to be exited, represented as a quantity of issued currency.
        `assetStates` - the asset states to take funds from. No checks are done about ownership of these states, it isthe responsibility of the caller to check that they do not attempt to exit funds held by others.
      Returns:
        the public keys which must sign the transaction for it to be valid.

    - #### generateExit

          @JvmStatic
           @NotNull
          public static <S extends FungibleAsset<T>,T> java.util.Set<java.security.PublicKey> generateExit(@NotNull
                                                                                                                                TransactionBuilder tx,
                                                                                                                                @NotNull
                                                                                                                                Amount<net.corda.core.contracts.Issued> amountIssued,
                                                                                                                                @NotNull
                                                                                                                                java.util.List<? extends net.corda.core.contracts.StateAndRef<? extends S>> assetStates,
                                                                                                                                @NotNull
                                                                                                                                AbstractParty payChangeTo,
                                                                                                                                @NotNull
                                                                                                                                kotlin.jvm.functions.Function3<? super net.corda.core.contracts.TransactionState<? extends S>,? super net.corda.core.contracts.Amount<net.corda.core.contracts.Issued<T>>,? super net.corda.core.identity.AbstractParty,? extends net.corda.core.contracts.TransactionState<? extends S>> deriveState,
                                                                                                                                @NotNull
                                                                                                                                kotlin.jvm.functions.Function0<? extends net.corda.core.contracts.CommandData> generateMoveCommand,
                                                                                                                                @NotNull
                                                                                                                                kotlin.jvm.functions.Function1<? super net.corda.core.contracts.Amount<net.corda.core.contracts.Issued<T>>,? extends net.corda.core.contracts.CommandData> generateExitCommand)

      Generate an transaction exiting fungible assets from the ledger.

      Parameters:
        `tx` - transaction builder to add states and commands to.
        `amountIssued` - the amount to be exited, represented as a quantity of issued currency.
        `assetStates` - the asset states to take funds from. No checks are done about ownership of these states, it isthe responsibility of the caller to check that they do not attempt to exit funds held by others.
        `payChangeTo` - party to pay any change to; this is normally a confidential identity of the callingparty.
      Returns:
        the public keys which must sign the transaction for it to be valid.

    - #### generateIssue

          @JvmStatic
           @NotNull
          public static <S extends FungibleAsset<T>,T> java.util.Set<java.security.PublicKey> generateIssue(@NotNull
                                                                                                                                 TransactionBuilder tx,
                                                                                                                                 @NotNull
                                                                                                                                 TransactionState<? extends S> transactionState,
                                                                                                                                 @NotNull
                                                                                                                                 CommandData issueCommand)

      Puts together an issuance transaction for the specified state. Normally contracts will provide convenient wrappers around this function, which build the state for you, and those should be used in preference.