com.r3corda.contracts.asset / OnLedgerAsset

# OnLedgerAsset

`abstract class OnLedgerAsset<T : Any, C : CommandData, S : FungibleAsset<T>> : 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 couldnt 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 dont care much who is currently holding it can ignore the issuer/depositRefs and just examine the amount fields.

### Constructors

<init> | `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 couldnt merge outputs of two colours together, but you COULD put them in the same transaction.

### Properties

conserveClause | `abstract val conserveClause: AbstractConserveAmount<S, C, T>`

### Inherited Properties

legalContractReference | `abstract val legalContractReference: SecureHash` Unparsed reference to the natural language contract that this code is supposed to express (usually a hash of the contracts contents).

### Functions

deriveState | `abstract fun deriveState(txState: TransactionState<S>, amount: Amount<Issued<T>>, owner: PublicKey): TransactionState<S>` 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 dont know about here, and we simply leave them untouched when sending out "change" from spending/exiting.
extractCommands | `abstract fun extractCommands(commands: Collection<AuthenticatedObject<CommandData>>): Collection<AuthenticatedObject<C>>`
generateExit | `fun generateExit(tx: TransactionBuilder, amountIssued: Amount<Issued<T>>, assetStates: List<StateAndRef<S>>): PublicKey` Generate an transaction exiting assets from the ledger.
generateExitCommand | `abstract fun generateExitCommand(amount: Amount<Issued<T>>): Exit<T>`
generateIssueCommand | `abstract fun generateIssueCommand(): Issue`
generateMoveCommand | `abstract fun generateMoveCommand(): Move`
generateSpend | `fun generateSpend(tx: TransactionBuilder, amount: Amount<T>, to: PublicKey, assetsStates: List<StateAndRef<S>>, onlyFromParties: Set<Party>? = null): List<PublicKey>` Generate a transaction that consumes one or more of the given input states to move assets to the given pubkey. Note that the vault is not updated: its up to you to do that.

### Inherited Functions

verify | `abstract fun verify(tx: TransactionForContract): Unit` Takes an object that represents a state transition, and ensures the inputs/outputs/commands make sense. Must throw an exception if theres 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.

### Inheritors

Cash | `class Cash : OnLedgerAsset<Currency, Commands, State>` 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 couldnt merge outputs of two colours together, but you COULD put them in the same transaction.
CommodityContract | `class CommodityContract : OnLedgerAsset<Commodity, Commands, State>` A commodity contract represents an amount of some commodity, tracked on a distributed ledger. The design of this contract is intentionally similar to the 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).