net.corda.contracts.asset

## Class Obligation<P>

- net.corda.contracts.asset.Obligation<P>

- Type Parameters:
    `P` - the product the obligation is for payment of.
  All Implemented Interfaces:
    Contract

      public class Obligation<P>
      implements Contract

  An obligation contract commits the obligor to delivering a specified amount of a fungible asset (for example the `class Cash` contract) at a specified future point in time. Settlement transactions may split and merge contracts across multiple input and output states. The goal of this design is to handle amounts owed, and these contracts are expected to be netted/merged, with settlement only for any remainder amount.

  See Also:
    `class Cash`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Obligation.State<P>` A state representing the obligation of one party (obligor) to deliver a specified number of units of an underlying asset (described as token.acceptableIssuedProducts) to the beneficiary no later than the specified time.
    `static class` | `Obligation.Terms<P>` Subset of state, containing the elements specified when issuing a new settlement contract.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Obligation()` An obligation contract commits the obligor to delivering a specified amount of a fungible asset (for example the `class Cash` contract) at a specified future point in time. Settlement transactions may split and merge contracts across multiple input and output states. The goal of this design is to handle amounts owed, and these contracts are expected to be netted/merged, with settlement only for any remainder amount.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `generateCloseOutNetting(TransactionBuilder tx, CompositeKey signer, net.corda.contracts.asset.Obligation.State states)` Generate a transaction performing close-out netting of two or more states.
    `CompositeKey` | `generateExit(TransactionBuilder tx, Amount<net.corda.core.contracts.Issued> amountIssued, java.util.List<net.corda.core.contracts.StateAndRef> assetStates)` Generate an transaction exiting an obligation from the ledger.
    `void` | `generateIssue(TransactionBuilder tx, AbstractParty obligor, Obligation.Terms<P> issuanceDef, long pennies, CompositeKey beneficiary, Party notary)` Puts together an issuance transaction for the specified amount that starts out being owned by the given pubkey.
    `void` | `generatePaymentNetting(TransactionBuilder tx, Issued<net.corda.contracts.asset.Obligation.Terms> issued, Party notary, net.corda.contracts.asset.Obligation.State states)`
    `void` | `generateSetLifecycle(TransactionBuilder tx, java.util.List<net.corda.core.contracts.StateAndRef> statesAndRefs, Obligation.Lifecycle lifecycle, Party notary)` Generate a transaction changing the lifecycle of one or more state objects.
    `void` | `generateSettle(TransactionBuilder tx, java.lang.Iterable<net.corda.core.contracts.StateAndRef> statesAndRefs, java.lang.Iterable<? extends net.corda.core.contracts.StateAndRef<? extends net.corda.core.contracts.FungibleAsset<P>>> assetStatesAndRefs, MoveCommand moveCommand, Party notary)`
    `SecureHash` | `getLegalContractReference()` TODO:
    `void` | `verify(TransactionForContract 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.

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

      `getLegalContractReference, verify`

- - ### Constructor Detail

    - #### Obligation

          public Obligation()

      An obligation contract commits the obligor to delivering a specified amount of a fungible asset (for example the `class Cash` contract) at a specified future point in time. Settlement transactions may split and merge contracts across multiple input and output states. The goal of this design is to handle amounts owed, and these contracts are expected to be netted/merged, with settlement only for any remainder amount.

      See Also:
        `class Cash`

  - ### Method Detail

    - #### getLegalContractReference

          public SecureHash getLegalContractReference()

      TODO:

      1. hash should be of the contents, not the URI

      2. allow the content to be specified at time of instance creation?

      Motivation: it's the difference between a state object referencing a programRef, which references a legalContractReference and a state object which directly references both. The latter allows the legal wording to evolve without requiring code changes. But creates a risk that users create objects governed by a program that is inconsistent with the legal contract.

    - #### verify

          public void verify(TransactionForContract 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.

    - #### generateCloseOutNetting

          public void generateCloseOutNetting(TransactionBuilder tx,
                                              CompositeKey signer,
                                              net.corda.contracts.asset.Obligation.State states)

      Generate a transaction performing close-out netting of two or more states.

      Parameters:
        `signer` - the party who will sign the transaction. Must be one of the obligor or beneficiary.
        `states` - two or more states, which must be compatible for bilateral netting (same issuance definitions, and same parties involved).

    - #### generateExit

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

      Generate an transaction exiting an obligation 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.

    - #### generateIssue

          public void generateIssue(TransactionBuilder tx,
                                    AbstractParty obligor,
                                    Obligation.Terms<P> issuanceDef,
                                    long pennies,
                                    CompositeKey beneficiary,
                                    Party notary)

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

    - #### generatePaymentNetting

          public void generatePaymentNetting(TransactionBuilder tx,
                                             Issued<net.corda.contracts.asset.Obligation.Terms> issued,
                                             Party notary,
                                             net.corda.contracts.asset.Obligation.State states)

    - #### generateSetLifecycle

          public void generateSetLifecycle(TransactionBuilder tx,
                                           java.util.List<net.corda.core.contracts.StateAndRef> statesAndRefs,
                                           Obligation.Lifecycle lifecycle,
                                           Party notary)

      Generate a transaction changing the lifecycle of one or more state objects.

      Parameters:
        `statesAndRefs` - a list of state objects, which MUST all have the same issuance definition. This avoids potential complications arising from different deadlines applying to different states.

    - #### generateSettle

          public void generateSettle(TransactionBuilder tx,
                                     java.lang.Iterable<net.corda.core.contracts.StateAndRef> statesAndRefs,
                                     java.lang.Iterable<? extends net.corda.core.contracts.StateAndRef<? extends net.corda.core.contracts.FungibleAsset<P>>> assetStatesAndRefs,
                                     MoveCommand moveCommand,
                                     Party notary)

      Parameters:
        `statesAndRefs` - a list of state objects, which MUST all have the same aggregate state. This is done as only a single settlement command can be present in a transaction, to avoid potential problems with allocating assets to different obligation issuances.
        `assetStatesAndRefs` - a list of fungible asset state objects, which MUST all be of the same issued product. It is strongly encouraged that these all have the same beneficiary.
        `moveCommand` - the command used to move the asset state objects to their new owner.