net.corda.contracts.asset

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

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

- All Implemented Interfaces:
    Contract
  Direct Known Subclasses:
    Cash, CommodityContract

      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.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `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.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `TransactionState<S>` | `deriveState(TransactionState<? extends S> txState, Amount<net.corda.core.contracts.Issued> amount, CompositeKey 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.
    `java.util.Collection<net.corda.core.contracts.AuthenticatedObject>` | `extractCommands(java.util.Collection<? extends net.corda.core.contracts.AuthenticatedObject<? extends net.corda.core.contracts.CommandData>> commands)`
    `CompositeKey` | `generateExit(TransactionBuilder tx, Amount<net.corda.core.contracts.Issued> amountIssued, java.util.List<? extends net.corda.core.contracts.StateAndRef<? extends S>> assetStates)` Generate an transaction exiting assets from the ledger.
    `Commands.Exit<T>` | `generateExitCommand(Amount<net.corda.core.contracts.Issued> amount)`
    `Commands.Issue` | `generateIssueCommand()`
    `Commands.Move` | `generateMoveCommand()`
    `AbstractConserveAmount<S,C,T>` | `getConserveClause()`

    - ### Methods inherited from interface net.corda.core.contracts.Contract

      `getLegalContractReference, verify`

- - ### 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

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

    - #### getConserveClause

          public AbstractConserveAmount<S,C,T> getConserveClause()

    - #### generateExit

          public CompositeKey generateExit(TransactionBuilder tx,
                                           Amount<net.corda.core.contracts.Issued> amountIssued,
                                           java.util.List<? extends net.corda.core.contracts.StateAndRef<? extends S>> assetStates)

      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 is the responsibility of the caller to check that they do not exit funds held by others.
      Returns:
        the public key of the assets issuer, who must sign the transaction for it to be valid.

    - #### generateExitCommand

          public Commands.Exit<T> generateExitCommand(Amount<net.corda.core.contracts.Issued> amount)

    - #### generateIssueCommand

          public Commands.Issue generateIssueCommand()

    - #### generateMoveCommand

          public Commands.Move generateMoveCommand()

    - #### deriveState

          public TransactionState<S> deriveState(TransactionState<? extends S> txState,
                                                 Amount<net.corda.core.contracts.Issued> amount,
                                                 CompositeKey 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.