10 KiB
Clauses
Basic clause structure
A clause is a small building block for assembling contract verification logic, reusable and ready to test in separation. To see clauses in action go to: tutorial-contract-clauses
. Let's take a look at a simplified structure of the Clause
class:
class Clause<in S : ContractState, C : CommandData, in K : Any> {
abstract
/** Determine whether this clause runs or not */
open val requiredCommands: Set<Class<out CommandData>> = emptySet()
@Throws(IllegalStateException::class)
fun verify(tx: TransactionForContract,
abstract inputs: List<S>,
outputs: List<S>,
commands: List<AuthenticatedObject<C>>,
groupingKey: K?): Set<C>
... }
Basic clause structure contains two important components: requiredCommands
and verify
function. A clause is triggered when all requiredCommands
are present in transaction's command set (opposite inclusion doesn't have to hold). Then the verify
function is run, which checks if transaction meets conditions specified by this clause. Verification is no different than normal contract verification but using clauses it's split into smaller generic code blocks with single verify method.
When writing a contract you need to override the contract's verify
function which should call verifyClause
. See: verify_ref
.
Note
A clause verify
function returns the set of processed commands, at the end of verifyClause
execution there is a check if all of transaction's commands were matched. If not, then an exception is raised. This is done to enforce that spurious commands cannot be included in a transaction, ensuring that the transaction is as clear as possible. As an example imagine a transaction with two commands: Move
and Issue
included, with verification written using FirstComposition
on clauses that require single command set. Thus only one of transaction's commands will match leaving the second unprocessed. It should raise an error - we want to ensure that commands set is minimal to simplify analysis of intent of a transaction.
An example verify
from Obligation
contract:
override fun verify(tx: TransactionForContract) = verifyClause<Commands>(tx, FirstComposition<ContractState, Commands, Unit>(
Clauses.Net<Commands, P>(),
Clauses.Group<P>() ), tx.commands.select<Obligation.Commands>())
It takes transaction to be verified, and passes it along with a top-level clause and commands to the verifyClause
function. As you can see above we have used FirstComposition
which is a special type of clause, which extends the CompositeClause
abstract class (in that particular case, it ensures that either Net
or Group
will run - for explanation see FirstComposition). It's a type of clause that adds support for encapsulating multiple clauses and defines common behaviour for that composition. There is also a GroupClauseVerifier
special clause, which specifies how to group transaction input/output states together and passes them to adequate clause for further processing.
Composition clauses
One of the most important concepts of clauses - composition clauses which extend CompositeClause
abstract class, providing a range of ways of assembling clauses together. They define a logic of verification execution specifying which clauses will be run.
AllComposition
Description
Composes a number of clauses, such that all of the clauses must run for verification to pass.
Short description:
AllComposition
holds clauses Cl1,..,Cl5.- Check if all clauses that compose
AllComposition
have associated commands in a command set - if not, verification fails. - After successful check runs verification logic specific for every clause Cl1,..,Cl5 from that composition.
Usage
See code in GroupClauseVerifier.
AnyComposition
Description
Composes a number of clauses, such that 0 or more of the clauses can be run.
Short description:
- Checks if zero or more clauses that compose AnyComposition have associated commands in a command set.
- After success runs verification logic specific for every matched (in this case Cl2, Cl4, Cl5) clause from composition.
Usage
Example from CommercialPaper.kt
:
class Group : GroupClauseVerifier<State, Commands, Issued<Terms>>(
AnyComposition(
Redeem(),
Move(),
Issue())) {
override fun groupStates(tx: TransactionForContract): List<TransactionForContract.InOutGroup<State, Issued<Terms>>>
= tx.groupStates<State, Issued<Terms>> { it.token } }
FirstComposition
Description
Composes a number of clauses, such that the first match is run, and it errors if none is run.
Short description:
- Takes first clause that matches and if none found throws an exception.
- If successful runs verification on the clause that matched (in this case Cl4).
Usage
See code in GroupClauseVerifier.
Other types of clauses
There are certain types of clauses that are specialized in particular types of contracts (like AbstractIssue
) or generally should be used as helpers in building parts of logic (the most important one is GroupClauseVerifier
).
GroupClauseVerifier
Description
Groups input and output states according to groupStates
function. Runs the top-level clause verification on each group in turn.
Short description:
GroupClauseVerifier
wraps clause Cl1. After grouping relevant states together with groupStates
into three groups Gr1, Gr2, Gr3 runs Cl1.verify(Gr1), Cl1.verify(Gr2), Cl1.verify(Gr3).
For more detailed example head to state_ref
.
Usage
You need to extend GroupClauseVerifier
clause and define groupStates
function which takes transaction and returns grouped input and output states with a grouping key used for each group. Example from Obligation.kt
contract:
class Group<P> : GroupClauseVerifier<State<P>, Commands, Issued<Terms<P>>>(
AllComposition(
NoZeroSizedOutputs<State<P>, Commands, Terms<P>>(),
FirstComposition(
SetLifecycle<P>(),
AllComposition(
VerifyLifecycle<State<P>, Commands, Issued<Terms<P>>, P>(),
FirstComposition(
Settle<P>(),
Issue(),
ConserveAmount()
)
)
)
)
) {override fun groupStates(tx: TransactionForContract): List<TransactionForContract.InOutGroup<Obligation.State<P>, Issued<Terms<P>>>>
= tx.groupStates<Obligation.State<P>, Issued<Terms<P>>> { it.amount.token } }
Usually it's convenient to use groupStates
function defined on TransactionForContract
class. Which given a type and a selector function, that returns a grouping key, associates inputs and outputs together so that they can be processed as one. The grouping key is any arbitrary object that can act as a map key (so must implement equals and hashCode).
AbstractConserveAmount
Description
Standardised clause for checking input/output balances of fungible assets. Requires that a Move command is provided, and errors if absent. Conserve amount clause can only be used on grouped states.
Usage
/**
* Generic move/exit clause for fungible assets
*/
class ConserveAmount<P> : AbstractConserveAmount<State<P>, Commands, Terms<P>>()
See code in GroupClauseVerifier.
AbstractIssue
Description
Standard issue clause for contracts that issue fungible assets.
Usage
Example from CommercialPaper.kt
:
class Issue : AbstractIssue<State, Commands, Terms>(
map { Amount(it.faceValue.quantity, it.token) }.sumOrThrow() },
{
{ token -> map { Amount(it.faceValue.quantity, it.token) }.sumOrZero(token) }) {override val requiredCommands: Set<Class<out CommandData>> = setOf(Commands.Issue::class.java)
override fun verify(tx: TransactionForContract,
inputs: List<State>,
outputs: List<State>,
commands: List<AuthenticatedObject<Commands>>,
groupingKey: Issued<Terms>?): Set<Commands> {
val consumedCommands = super.verify(tx, inputs, outputs, commands, groupingKey)
...
First function in constructor converts a list of states into an amount of the token. Must error if there are no states in the list. Second function converts a list of states into an amount of the token, and returns zero if there are no states in the list. Takes in an instance of the token definition for constructing the zero amount if needed.
NoZeroSizedOutputs
Description
Clause for fungible asset contracts, which enforces that no output state should have a balance of zero.
Usage
See code in GroupClauseVerifier.
FilterOn
Description
Filter the states that are passed through to the wrapped clause, to restrict them to a specific type.
FilterOn
narrows the scope of the states being verified. Let's take a transaction with multiple cash states of different currencies, we want to run a clause that focuses on only GBP cash states rather than all cash states.
Usage
FilterOn(clause, { states -> states.filter { it.amount.token == GBP} })
Takes filterStates
function that limits states passed to clause
verification.