Interest in blockchain and DLT (Distributed Ledger Technology) is soaring in the enterprise space, but the prospect of taking the step to engage a technology partner is often the point where the exploration stalls. In many cases this is due to lack of executive sponsorship or the lack of a use case aligned to business value. These key success factors have garnered substantial attention; however, focusing on those two alone, misses another critical factor that I’ve seen repeatedly: team readiness.

The focus here will be on those cases where the team stalls because they find it difficult to determine with certainty if they are prepared to initiate a productive conversation. A significant feature of this problem is an imbalance in information on getting started. A developer can search “how to develop smart contracts” and find a myriad of resources to learn smart contract architecture, infrastructure, and Solidity coding. With some focused self-study, they are off to the races.

What is missing, however, is the other side of the team: the subject matter experts (SMEs) who know the details of the existing contract-based transaction. These are people who the developers rely on to define the content and accuracy of their work. SMEs are vital to the success of a smart contract development project. However, if an SME were to search “how to translate a contract into a smart contract,” they will find there is little to guide them on how to proceed.

This article is an effort to address that information imbalance. What follows is a guide for SMEs who are interested in framing their approach to a smart contract before they begin working with a blockchain or DLT technology partner. This provides a framework for SMEs to catalog their insight into a format that technologists can utilize to build a smart contract. It also enables technologists to develop a realistic estimate about the resources the project will require, so that the SMEs have a good sense of the costs involved.

I will be recommending the development of three assets:

  1. An information inventory
  2. A swim lane diagram
  3. A catalog of user stories

The last two are commonly used by business analysts to document requirements. If you are interested in diving deeper into these, there are numerous articles and guides available. I will walk through what my team finds helpful, and it is likely a simplified version of what you may find elsewhere. The simplified version presented here serves to accelerate the start of a project and enables precise and productive communication. More complex versions might be developed at later stages of the project, but this approach established a solid foundation for the entire solution development process. In short, it establishes team readiness and lays the groundwork for effective partner collaboration.


The information inventory pulls together key information that will inform the development of the smart contract. It is helpful to develop two versions of these assets: current state and future state. Having this information side-by side enables teams to design a future state that captures the essential functions of the current state, while leveraging blockchain technology to streamline and automate much of the existing process.

Throughout this article, I’ll use a concrete example to illustrate the various concepts. A relatively simple example is a contract-driven transaction related to selling a home. We will rely on that example throughout.


This is simply a list of the entities that will be involved. Entities, in this instance, includes everyone and everything that will interact with the contract. Teams usually find it easiest to identify the people that will interact with the contract. Beyond that, however, it is also important to think about how entities like regulators and auditors might need view-access or approve-access. It is also important to consider how “things”—machines, sensors or other IoT devices—might come into play during the course of the transaction.


The next step entails defining the actions that will occur in the course of a transaction in a roughly chronological order. A good approach here is to start by defining the “happy path”—what the process entails when everything goes smoothly. From there, examine each step of the process and detail the course of action that occurs when there is disagreement, corrective action, or repair needed. These are “alternative paths.”

Throughout this process, it is helpful to note which of the entities is responsible for each of the actions that you are detailing. While some are inclined to use a spreadsheet with two columns to capture action and actor side by side, others will use parenthetical notes following each action. Both approaches work.

Additionally, many find it helpful to use an outline format that organizes the variety of alternative path actions associated with each step of the happy path. So, for example, if the happy path moves from “submit purchase offer” to “review offer” to “accept offer,” the alternative path actions included as a subset below “accept offer” would include “reject purchase offer” and “counter offer.”

Data Profile

Now that you’ve defined who is interacting with the contract, and what actions are involved in the contract-related process, now it’s time to dive into the information itself. This is where you inventory and profile the information upon which the contract turns. What are the key points of agreement that must be established and enforced? What data is required to determine if those commitments are kept? What rules govern the formation, performance, and enforcement of the contract? In our home sale example, the data inventory might include the payment date, late date, duration of contract (term), total amount of loan, amount financed, late fee, % rate, and down payment amount.

In addition to creating an inventory of the relevant data, it is also important to build a profile for each. This profile usually includes units, format, possible range, data source, and any other fields that should be captured in relation to that data.

Take, for example, a purchase offer. A profile of that data field should include:


A swim lane diagram pulls all the actions together, and sorts them according to the entity performing them. Each of the entities is given a “swim lane” and then the actions are plotted in roughly chronological order in boxes (and other shapes) that are located in the lanes of those responsible for the action. The actions are usually grouped into a few high-level chronological stages. These swim lane diagrams are excellent assets for communication between subject matter experts and technologists.

Often, in the course of creating a swim lane diagram, you might find that you’ve missed information or actions that should be part of the Information Inventory. That is one of the benefits of creating these mutually-illuminating assets. This is an iterative process, and you will find yourself building and editing across all three.

There are a number of modeling languages that have developed to suit a variety of applications. This SME-oriented guide will recommend using just a few simple shapes and conventions:

  • Box: represents most actions
  • Arrows: connects actions to each other and indicates the order in which actions occur
  • Diamond: represents decision points, at least two arrows proceed from here
  • Yes/No Labels at decision points: indicates which actions flow from yes versus no decisions
  • Document: Indicates an action that is codified in a document
  • Terminator Oval: represents an action that is a termination point in the process

A simplified version of this as it pertains to our home sale example is included below:


User stories can be deceptively simple. Their basic structure is short and straightforward:

As a __<user/entity>__,

I want __<feature>__,

so that __<reason>__.

In our home sale example, one of these might read:

This structure serves to define the features, functionality, and results that a variety of end-users need in order to find the smart contract valuable. The swim lane diagram will help you to get started in defining user stories, but keep in mind that the user stories are more focused on the technology solution, and may include details regarding the functionality that the swim lane diagrams do not capture.

Keep these user stories to a very granular level—this is where all of the minute details related to the smart contract’s use should be captured. Often, the shapes of the swim lane diagram will be numbered so that user stories can be linked to them. This helps to illustrate at what point in the process a specific user story occurs. Some find a numbering convention helps them keep things straight from the start, while others find it to be a taxing additional layer of complexity. Move forward with whatever fits your team’s needs. The detail layers can be added in a later version.



Having outlined three assets that subject matter experts (SMEs) can develop to facilitate their work with technologists, there are a few things to keep in mind:

Firstly: It is not imperative that SMEs develop all of these assets prior to engaging a technologist. Most third parties focused on digital solutions will have a team that specializes in developing assets like these. However, many SMEs find it helpful to begin to inventory their insights beforehand so that they can accelerate the process. This guide gives SMEs three asset formats in which to capture these insights.

Secondly: The assets have been presented in order of ease and importance. The information inventory is the most easily developed of the three, and it provides the technologists with a wealth of information that will support their work. If you only have time or energy to undertake one of the three, choose this one. The swim lane diagram is also very helpful, but usually somewhat more difficult to develop. This would be the second most important asset to develop. The user stories, because of their granularity, are often the most difficult to get right without guidance. If you have the time and energy, then it is certainly worth making the effort. The first draft will likely be expanded as the development process unfolds.

Thirdly: Building out these assets requires a good deal of effort. Before you undertake that task, you will likely want to ensure that you have selected a high-value use case that is well-suited to blockchain or DLT technology. This article assumes you have already worked through that evaluation and prioritization process. If not, spend some time on those activities first. An upcoming post will focus on how to select a great smart contract use case, so if you are at that stage, then stay tuned.

Next steps: Once your team feels prepared to have a productive conversation, you will likely be evaluating partners who specialize in blockchain solution development. At Quisitive, we understand that it is difficult to navigate through the blockchain hype to realize incremental business value in the fastest sensible time frame. Our approach is flexible enough to hone in on a right-sized solution, and our team has the experience and insight to ensure that you reach your goals. If you are interested in hearing more, send me a message and we can find time to talk.