A time-based event is a very common requirement in most modern software applications. A time-based event means performing a specific task (event) at a pre-determined time. The way it’s achieved is by having a scheduler that schedules a task to be executed at a specific instant.

It’s not very different in decentralized applications, you may come across such requirements very often. If you are a CorDapp developer, you may wonder how you could achieve this. How could you schedule a flow to be triggered at a specific time in Corda? One simple way is to trigger a flow from outside the node, for example, use spring-boot to schedule a task that would trigger the flow using RPC.

That would work but wouldn’t it be better if we are somehow able to trigger the flow from within the node without having the dependency of an external scheduler? Yes, that’s very much possible. Allow me to introduce SchedulableState.

New to Corda? A great way to start with Corda is to take a look at one of our online bootcamp webinars. The recording for one of them is available here: https://www.youtube.com/watch?v=tVE1rKbFA3g

You may also consider joining us for one of our in-person or live virtual bootcamps. Keep an eye on the link below to know what events are coming up: https://corda.net/blockchain-bootcamp/

SchedulableState

SchedulableState allows CorDapp developers to model time-based events in their corDapps. It is a sub-interface of ContractState , with a single method nextScheduledActivity(). This method should be implemented by the developer and it should return a ScheduledActivity containing the information of the flow to be scheduled and the time when it should be scheduled.

Let’s try to understand this with the help of a simple example. Consider you are implementing a DLT based online auction application. One of the common requirements for an auction is to have an expiry time of the auction i.e. the time when an auction would stop accepting further bids. This is a perfect use case for a time-based event.

When we want to implement this on Corda, we would mostly be having a state modeled for the auction, lets assume its called AuctionState. We would want this AuctionState to expire automatically at a specific time. Thus when we implement AuctionState we should make it a SchedulableState.

We have a code snippet below showing the nextScheduledActivity() implemented. Among other properties, the AuctionState would have anexpiryTimeproperty, which is used to create the instance of ScheduleActivity that needs to be returned from nextScheduledActivity(). We also need a reference to the flow which would run the auction expiry logic. It can be fetched using the FlowLogicRefFactory as shown below. The Corda node would keep track of all scheduled activities and trigger the flows at the specified time.

One common mistake developers make while implementing ScheduledState is to inline the scheduledTime i.e. expiryTime in the example. The scheduledTime should be passed as a constructor parameter while creating the instance of the SchedulableState or you should have a public constructor which have the scheduledTime as a parameter.

Do not use something like: return new ScheduledActivity(flowLogicRef, Instant.now().plusSeconds(30)). The ScheduledActivity would never fire since each time the scheduledtime is reached, your state would be deserialized and the scheduledTime is increased by 30 sec.

Scheduled Flow

A scheduled flow is no different than a regular flow in Corda. There is however one point that needs to be taken care of. All scheduled flows must be annotated with @SchedulableFlow.

Sample Code

Here are some samples on SchedulableState you might want to have a look:

1. A simple corDapp that shows heartbeat every second: https://github.com/corda/samples-java/tree/master/Features/schedulablestate-heartbeat
2. The implementation of Action using Corda that uses SchedulableState: https://github.com/corda/samples-java/tree/master/Advanced/auction-cordapp

Thank you so much for reading.

Want to learn more about building awesome blockchain applications on Corda? Be sure to visit https://corda.net, check out our community page to learn how to connect with other Corda developers, and sign up for one of our newsletters for the latest updates.

— Ashutosh Meher is a Developer Evangelist at R3, an enterprise blockchain software firm working with a global ecosystem of more than 350 participants across multiple industries from both the private and public sectors to develop on Corda, its open-source blockchain platform, and Corda Enterprise, a commercial version of Corda for enterprise usage.

Follow Ashutosh on Twitter here.