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

net.corda.finance.contracts.asset

## Class Cash

- OnLedgerAsset
- - net.corda.finance.contracts.asset.Cash

- All Implemented Interfaces:
    Contract

      public class Cash
      extends OnLedgerAsset

  A cash transaction may split and merge money 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 money can be withdrawn from the ledger easily: if you receive some money 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 money and don't care much who is currently holding it in their vaults can ignore the issuer/depositRefs and just examine the amount fields.

- - ### Field Detail

    - #### PROGRAM_ID

          @NotNull
          public static java.lang.String PROGRAM_ID

      See Also:
        Constant Field Values

    - #### Companion

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

  - ### Constructor Detail

    - #### Cash

          public Cash()

      A cash transaction may split and merge money 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 money can be withdrawn from the ledger easily: if you receive some money 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 money and don't care much who is currently holding it in their vaults can ignore the issuer/depositRefs and just examine the amount fields.

  - ### Method Detail

    - #### extractCommands

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

    - #### generateIssue

          @NotNull
          public java.util.Set<java.security.PublicKey> generateIssue(@NotNull
                                                                               TransactionBuilder tx,
                                                                               @NotNull
                                                                               Issued<java.util.Currency> tokenDef,
                                                                               long pennies,
                                                                               @NotNull
                                                                               AbstractParty owner,
                                                                               @NotNull
                                                                               Party notary)

      Puts together an issuance transaction from the given template, that starts out being owned by the given pubkey.

    - #### generateIssue

          @NotNull
          public java.util.Set<java.security.PublicKey> generateIssue(@NotNull
                                                                               TransactionBuilder tx,
                                                                               @NotNull
                                                                               Amount<net.corda.core.contracts.Issued> amount,
                                                                               @NotNull
                                                                               AbstractParty owner,
                                                                               @NotNull
                                                                               Party notary)

      Puts together an issuance transaction for the specified amount that starts out being owned by the given pubkey.

    - #### deriveState

          @NotNull
          public TransactionState<net.corda.finance.contracts.asset.Cash.State> deriveState(@NotNull
                                                                                                     TransactionState<net.corda.finance.contracts.asset.Cash.State> 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.

    - #### generateExitCommand

          @NotNull
          public net.corda.finance.contracts.asset.Cash.Commands.Exit generateExitCommand(@NotNull
                                                                                                   Amount<net.corda.core.contracts.Issued> amount)

    - #### generateMoveCommand

          @NotNull
          public net.corda.finance.contracts.asset.Cash.Commands.Move generateMoveCommand()

    - #### verify

          public void verify(@NotNull
                             LedgerTransaction tx)

      Takes an object that represents a state transition, and ensures the inputs/outputs/commands make sense. Must throw an exception if there's a problem that should prevent state transition. Takes a single object rather than an argument so that additional data can be added without breaking binary compatibility with existing contract code.