net.corda.contracts.asset

## Class CommodityContract

- OnLedgerAsset
- - net.corda.contracts.asset.CommodityContract

- All Implemented Interfaces:
    Contract

      public class CommodityContract
      extends OnLedgerAsset

  A commodity contract represents an amount of some commodity, tracked on a distributed ledger. The design of this contract is intentionally similar to the `class Cash` contract, and the same commands (issue, move, exit) apply, the differences are in representation of the underlying commodity. Issuer in this context means the party who has the commodity, or is otherwise responsible for delivering the commodity on demand, and the deposit reference is use for internal accounting by the issuer (it might be, for example, a warehouse and/or location within a warehouse).

  This is an early stage example contract used to illustrate non-cash fungible assets, and is likely to change significantly in future.

  See Also:
    `class Cash`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `CommodityContract.State` A state representing a commodity claim against some party

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommodityContract()` A commodity contract represents an amount of some commodity, tracked on a distributed ledger. The design of this contract is intentionally similar to the `class Cash` contract, and the same commands (issue, move, exit) apply, the differences are in representation of the underlying commodity. Issuer in this context means the party who has the commodity, or is otherwise responsible for delivering the commodity on demand, and the deposit reference is use for internal accounting by the issuer (it might be, for example, a warehouse and/or location within a warehouse).

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `TransactionState<net.corda.contracts.asset.CommodityContract.State>` | `deriveState(TransactionState<net.corda.contracts.asset.CommodityContract.State> 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.List<net.corda.core.contracts.AuthenticatedObject>` | `extractCommands(java.util.Collection<? extends net.corda.core.contracts.AuthenticatedObject<? extends net.corda.core.contracts.CommandData>> commands)`
    `Commands.Exit` | `generateExitCommand(Amount<net.corda.core.contracts.Issued> amount)`
    `void` | `generateIssue(TransactionBuilder tx, Issued<net.corda.core.contracts.Commodity> tokenDef, long pennies, CompositeKey owner, Party notary)` Puts together an issuance transaction from the given template, that starts out being owned by the given pubkey.
    `void` | `generateIssue(TransactionBuilder tx, Amount<net.corda.core.contracts.Issued> amount, CompositeKey owner, Party notary)` Puts together an issuance transaction for the specified amount that starts out being owned by the given pubkey.
    `Commands.Issue` | `generateIssueCommand()`
    `Commands.Move` | `generateMoveCommand()`
    `AbstractConserveAmount<net.corda.contracts.asset.CommodityContract.State,net.corda.contracts.asset.CommodityContract.Commands,net.corda.core.contracts.Commodity>` | `getConserveClause()`
    `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 class net.corda.contracts.asset.OnLedgerAsset

      `deriveState, extractCommands, generateExit, generateExitCommand, generateIssueCommand, generateMoveCommand, getConserveClause`

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

      `getLegalContractReference, verify`

- - ### Constructor Detail

    - #### CommodityContract

          public CommodityContract()

      A commodity contract represents an amount of some commodity, tracked on a distributed ledger. The design of this contract is intentionally similar to the `class Cash` contract, and the same commands (issue, move, exit) apply, the differences are in representation of the underlying commodity. Issuer in this context means the party who has the commodity, or is otherwise responsible for delivering the commodity on demand, and the deposit reference is use for internal accounting by the issuer (it might be, for example, a warehouse and/or location within a warehouse).

      This is an early stage example contract used to illustrate non-cash fungible assets, and is likely to change significantly in future.

      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

    - #### getConserveClause

          public AbstractConserveAmount<net.corda.contracts.asset.CommodityContract.State,net.corda.contracts.asset.CommodityContract.Commands,net.corda.core.contracts.Commodity> getConserveClause()

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

    - #### extractCommands

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

    - #### generateIssue

          public void generateIssue(TransactionBuilder tx,
                                    Issued<net.corda.core.contracts.Commodity> tokenDef,
                                    long pennies,
                                    CompositeKey owner,
                                    Party notary)

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

    - #### generateIssue

          public void generateIssue(TransactionBuilder tx,
                                    Amount<net.corda.core.contracts.Issued> amount,
                                    CompositeKey owner,
                                    Party notary)

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

    - #### deriveState

          public TransactionState<net.corda.contracts.asset.CommodityContract.State> deriveState(TransactionState<net.corda.contracts.asset.CommodityContract.State> 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.

    - #### generateExitCommand

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

    - #### generateIssueCommand

          public Commands.Issue generateIssueCommand()

    - #### generateMoveCommand

          public Commands.Move generateMoveCommand()