OnLedgerAsset - corda

corda / net.corda.finance.contracts.asset / OnLedgerAsset

# OnLedgerAsset

`abstract class OnLedgerAsset<T : Any, out 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 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.

### Constructors

#### <init> | 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. `OnLedgerAsset()`

### Functions

#### deriveState | 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. `abstract fun deriveState(txState: TransactionState<S>, amount: Amount<Issued<T>>, owner: AbstractParty): TransactionState<S>`
#### extractCommands | `abstract fun extractCommands(commands: Collection<CommandWithParties<CommandData>>): Collection<CommandWithParties<C>>`
#### generateExit | Generate an transaction exiting assets from the ledger. `fun generateExit(tx: TransactionBuilder, amountIssued: Amount<Issued<T>>, assetStates: List<StateAndRef<S>>): Set<PublicKey>` `fun generateExit(tx: TransactionBuilder, amountIssued: Amount<Issued<T>>, assetStates: List<StateAndRef<S>>, payChangeTo: AbstractParty): Set<PublicKey>`
#### generateExitCommand | `abstract fun generateExitCommand(amount: Amount<Issued<T>>): CommandData`
#### generateMoveCommand | `abstract fun generateMoveCommand(): MoveCommand`

### Companion Object Functions

#### generateExit | Generate an transaction exiting fungible assets from the ledger. `fun <S : FungibleAsset<T>, T : Any> generateExit(tx: TransactionBuilder, amountIssued: Amount<Issued<T>>, assetStates: List<StateAndRef<S>>, deriveState: (TransactionState<S>, Amount<Issued<T>>, AbstractParty) -> TransactionState<S>, generateMoveCommand: () -> CommandData, generateExitCommand: (Amount<Issued<T>>) -> CommandData): Set<PublicKey>` `fun <S : FungibleAsset<T>, T : Any> generateExit(tx: TransactionBuilder, amountIssued: Amount<Issued<T>>, assetStates: List<StateAndRef<S>>, payChangeTo: AbstractParty, deriveState: (TransactionState<S>, Amount<Issued<T>>, AbstractParty) -> TransactionState<S>, generateMoveCommand: () -> CommandData, generateExitCommand: (Amount<Issued<T>>) -> CommandData): Set<PublicKey>`
#### generateIssue | Puts together an issuance transaction for the specified state. Normally contracts will provide convenient wrappers around this function, which build the state for you, and those should be used in preference. `fun <S : FungibleAsset<T>, T : Any> generateIssue(tx: TransactionBuilder, transactionState: TransactionState<S>, issueCommand: CommandData): Set<PublicKey>`
#### generateSpend | Generate a transaction that moves an amount of currency to the given pubkey. `fun <S : FungibleAsset<T>, T : Any> generateSpend(tx: TransactionBuilder, amount: Amount<T>, to: AbstractParty, acceptableStates: List<StateAndRef<S>>, payChangeTo: AbstractParty, deriveState: (TransactionState<S>, Amount<Issued<T>>, AbstractParty) -> TransactionState<S>, generateMoveCommand: () -> CommandData): Pair<TransactionBuilder, List<PublicKey>>` Adds to the given transaction states that move amounts of a fungible asset to the given parties, using only the provided acceptable input states to find a solution (not all of them may be used in the end). A change output will be generated if the state amounts don't exactly fit. `fun <S : FungibleAsset<T>, T : Any> generateSpend(tx: TransactionBuilder, payments: List<PartyAndAmount<T>>, acceptableStates: List<StateAndRef<S>>, payChangeTo: AbstractParty, deriveState: (TransactionState<S>, Amount<Issued<T>>, AbstractParty) -> TransactionState<S>, generateMoveCommand: () -> CommandData): Pair<TransactionBuilder, List<PublicKey>>`

### Inheritors

#### 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. `class Cash : OnLedgerAsset<Currency, Commands, State>`