Live Contracts
Setup a node and run your first Live Contract.
Running Live Contracts requires using the LTO Network workflow node.
In these tutorials, we're always using the developer build of the workflow node, which is available as a Docker container.
curl "https://raw.githubusercontent.com/ltonetwork/lto-workflow-node/docker-compose.yml" -o docker-compose.yml
docker-compose up
If you need more help to install Docker and the workflow node, please follow the step-by-step installation guide.
...
JSON screenshot
To check that the node is correctly up visit https://localhost:3000. You'll see a JSON response containing information about the LTO services.
Create a directory named
livecontracts-tutorial.mkdir -p livecontracts-tutorial
cd livecontracts-tutorial
A Live Contract must contain one or more scenarios that describe the process(es) we're automating. We can write a scenario in either JSON or YAML.
Create file
scenario.yml (or scenario.json) in the basic directory.YAML
JSON
$schema: "https://specs.livecontracts.io/v0.2.0/scenario/schema.json#"
title: The basics
{
"$schema": "https://specs.livecontracts.io/v0.2.0/scenario/schema.json#",
"title": "The basics"
}
Actors are organizations or individuals that play a role in the process. The scenario needs to define which actors (may) exist.
YAML
JSON
$schema: "https://specs.livecontracts.io/v0.2.0/scenario/schema.json#"
title: The basics
actors:
initiator:
title: Initiator
{
"$schema": "https://specs.livecontracts.io/v0.2.0/scenario/schema.json#",
"title": "The basics",
"actors": {
"initiator": {
"title": "Initiator"
}
}
}
We've defined a single actor for the process; the initiator. Normally a process contains 2 or more actors.
The key
initiator is used to reference the actor. The title must be defined, but only exists for displaying purposes.All actions that any actor can perform within the process must be defined at forehand in the scenario.
YAML
JSON
$schema: "https://specs.livecontracts.io/v0.2.0/scenario/schema.json#"
title: My first Live Contract
actors:
initiator:
title: Initiator
actions:
complete:
title: Complete the process
actor: initiator
{
"$schema": "https://specs.livecontracts.io/v0.2.0/scenario/schema.json#",
"title": "The basics",
"actors": {
"initiator": {
"title": "Initiator"
}
},
"actions": {
"complete": {
"title": "Complete the process",
"actor": "initiator"
}
}
}
The complete action can be performed by the initiator actor. The intend of this action is to complete the process. However, that transition needs to be defined in the state.
When a process is started, it's in the initial state. From this state it can transition to other states, until the process is completed.
YAML
JSON
$schema: "https://specs.livecontracts.io/v0.2.0/scenario/schema.json#"
title: My first Live Contract
actors:
initiator:
title: Initiator
actions:
complete:
title: Complete the process
actor: initiator
states:
initial:
action: complete
transition: :success
{
"$schema": "https://specs.livecontracts.io/v0.2.0/scenario/schema.json#",
"title": "Basic user",
"actors": {
"initiator": {
"title": "Initiator"
}
},
"actions": {
"complete": {
"title": "Complete the process",
"actor": "initiator"
}
},
"states": {
"initial": {
"action": "complete",
"transition": ":success"
}
}
}
While in the initial state, only the complete action can be performed. Once the action is performed, the process will transition to the :success end state, meaning the process has been completed successfully.
To ensure the Live Contract behaves as expected, we need to create and run tests. Tests must be defined using the Gherkin syntax. The Live Contracts test suite that comes with the full node, defines the steps that can be used in the test.
Create file
main.feature in the basic directory.main.feature
Feature: Run a simple process that is completed in one step
Background:
Given a chain is created by "Joe"
Given "Joe" creates the "main" process using the "basic" scenario
And "Joe" is the "initiator" actor of the "main" process
Scenario:
When "Joe" runs the "complete" action of the "main" process
Then the "main" process is completed
We have a single identity named "Joe". The name is arbitrary but used to keep the identities apart.
Joe initializes the Live Contract by creating a new chain and using our basic scenario. The process name "main" is also arbitrary and used to reference a specific process. It's possible to run multiple processes for a Live Contract, but in our case, only a single process exists.
We need to specify which role Joe is going to have in the process. In this case, he's the initiator of the process.
In the
Scenario section (this is unrelated to the workflow scenario), we state that will Joe performs the complete action. As defined in our workflow scenario, the process should transition from initial to :success, which means the process has been completed successfully.lctest is a command-line tool to test workflows described in a Live Contract. It can be run from the ltonetwork/letsflow-test docker container. docker run ltonetwork/letsflow-test basic
The test should succeed, giving the following output:
You've successfully created and tested your first Live Contract.
Last modified 1yr ago