Contract Constraints¶

A basic understanding of contract key concepts, which can be found here, is required reading for this page.

Transaction states specify a constraint over the contract that will be used to verify it. For a transaction to be valid, the verify() function associated with each state must run successfully. However, for this to be secure, it is not sufficient to specify the verify() function by name as there may exist multiple different implementations with the same method signature and enclosing class. Contract constraints solve this problem by allowing a contract developer to constrain which verify() functions out of the universe of implementations can be used. (ie the universe is everything that matches the signature and contract constraints restricts this universe to a subset.)

A typical constraint is the hash of the CorDapp JAR that contains the contract and states but will in future releases include constraints that require specific signers of the JAR, or both the signer and the hash. Constraints can be specified when constructing a transaction; if unspecified, an automatic constraint is used.

A TransactionState has a constraint field that represents that state’s attachment constraint. When a party constructs a TransactionState without specifying the constraint parameter a default value (AutomaticHashConstraint) is used. This default will be automatically resolved to a specific HashAttachmentConstraint that contains the hash of the attachment which contains the contract of that TransactionState. This automatic resolution occurs when a TransactionBuilder is converted to a WireTransaction. This reduces the boilerplate involved in finding a specific hash constraint when building a transaction.

It is possible to specify the constraint explicitly with any other class that implements the AttachmentConstraint interface. To specify a hash manually the HashAttachmentConstraint can be used and to not provide any constraint the AlwaysAcceptAttachmentConstraint can be used - though this is intended for testing only. An example below shows how to construct a TransactionState with an explicitly specified hash constraint from within a flow;

// Constructing a transaction with a custom hash constraint on a state
TransactionBuilder tx = new TransactionBuilder()

Party notaryParty = ... // a notary party
DummyState contractState = new DummyState()
SecureHash myAttachmentsHash = serviceHub.cordappProvider.getContractAttachmentID(DummyContract.PROGRAM_ID)
TransactionState transactionState = new TransactionState(contractState, DummyContract.Companion.getPROGRAMID(), notaryParty, new AttachmentHashConstraint(myAttachmentsHash))

tx.addOutputState(transactionState)
WireTransaction wtx = tx.toWireTransaction(serviceHub) // This is where an automatic constraint would be resolved
LedgerTransaction ltx = wtx.toLedgerTransaction(serviceHub)
ltx.verify() // Verifies both the attachment constraints and contracts

This mechanism exists both for integrity and security reasons. It is important not to verify against the wrong contract, which could happen if the wrong version of the contract is attached. More importantly when resolving transaction chains there will, in a future release, be attachments loaded from the network into the attachment sandbox that are used to verify the transaction chain. Ensuring the attachment used is the correct one ensures that the verification will not be tamperable by providing a fake contract.

class SomeTestClass {
     MockNetwork network = null

     @Before
     void setup() {
         // The ordering of the two below lines is important - if the MockNetwork is created before the nodes and network
         // are created the CorDapps will not be loaded into the MockNodes correctly.
         setCordappPackages(Arrays.asList("com.domain.cordapp"))
         network = new MockNetwork()
     }

     @After
     void teardown() {
         // This must be called at the end otherwise the global state set by setCordappPackages may leak into future
         // tests in the same test runner environment.
         unsetCordappPackages()
     }

     ... // Your tests go here
}

MockServices mockServices = new MockServices(Arrays.asList("com.domain.cordapp"))

driver(new DriverParameters().setExtraCordappPackagesToScan(Arrays.asList("com.domain.cordapp"))) ...