This tutorial gives an overview of the Marlowe Playground, an online tool that allows users to interact with and simulate the operation of embedded Marlowe contracts. It is available at https://prod.meadow.marlowe.iohkdev.io.
For Marlowe to be usable in practice, users need to be able to understand how contracts will behave once deployed to the blockchain, but without doing the deployment. We can do that by simulating their behaviour off-chain, interactively stepping through the evaluation of a contract in the browser-based tool, the Marlowe Playground, a web tool that supports the interactive construction, revision, and simulation of smart-contracts written in Marlowe.
Tabs and buttons in the Playground are shown in bold type below.
We can do this in two different ways, represented by two of the tabs in the tool.
-
HASKELL EDITOR In this tab we can design and edit an embedded Marlowe contract, using features of Haskell, and then Compile it to a pure Marlowe contract,
-
BLOCKLY In this tab we can create a a (pure) Marlowe contract using the Blockly visual language; we can then transform it To Code.
Whichever approach we used to develop a contract we can then transfer it to the SIMULATION tab, in which we can simulate the action of the contract step by step, transaction by transaction taking inputs from participants, observations, and so forth.
We now discuss each of these in more detail.
The editor supports Haskell development, with syntax highlighting, and
on clicking the Compile button the Haskell file will be compiled, and
the top-level definition of contract will be evaluated to a pure
Marlowe contract, which is made visible below the Haskell pane. Once we
are happy with the result, we can send it to the simulator pane by
clicking Send to simulator.
The figure shows a screenshot of the Marlowe Playground in the middle of developing an “escrow” contract; other contract examples, based on the ACTUS standard, can be loaded by clicking on the named Demos below the HASKELL EDITOR tab.
If you have a github account, it’s also possible to save contracts that you develop as github gists. To do this log into your account using the Log in button at the top right of the screen. You will then see buttons to allow you to Publish or save contracts as gists, and to Load contracts from github.
This is covered in the tutorial on Escrow step by step.
The second tab in the Marlowe Playground allows users to simulate Marlowe contracts transaction by transaction. Typically these are either contracts developed in the Haskell editor, or within Blockly, but it is also possible to modify the contract under execution, shown in the Marlowe Contract pane at the foot of the page. At each stage in execution, this shows the contract still to be executed.
Other facilities presented by the tool are
-
Towards the top of the screen, the Input Composer which provides us with all the actions, choices and observations that are relevant at this stage of contract execution. This smart interface helps us to validate contracts: are we being offered what we would expect at each stage in the execution?
-
The inputs are gathered in the Transaction Composer, where inputs are sequenced. Again, the interface is smart in only accepting inputs that can be processed and included in a transaction at this stage of contract execution.
-
Once a transaction is composed, it can be applied by choosing the
-
Apply Transaction button applies the transaction, also
-
the Next Block button can be applied at any time to advance to the next block without applying any (more) transactions,
-
the Undo button is used to undo the last step, and this can be used to roll back as many steps as you wish, before perhaps trying an alternative path though the contract, and
-
the Reset button is used to reset the contract and state to their initial values.
-
-
As the contract is evaluated, the internal state of the system changes, and this is reflected in the values show in the State section in the middle of the screen. We revisit this below.
-
A number of additional demos are available using the buttons to the top right of the Marlowe Contract pane.
We can build our first transaction by selecting the purple plus symbol
+ to the left of the potential inputs. If we select the first action
– a deposit by alice – we see
where this potential action has disappeared, but it now appears as the first (and only) element in the input list of the transaction.
If we choose
to apply this transaction, we then see the effect of the deposit by alice, and
the following changes in the screen.
-
The input composer presents a different set of potential inputs, with the deposit removed and two potential choices given.
-
The transaction composer is reset, too.
-
The state now shows that there is an active account, and gives its owner and value.
-
The contract itself has also evolved to a
Whenconstruct that waits for a choice. Two choices are possible here: from Alice or from Bob.
We could then advance to the next block, or indeed a number of steps, and the current block is shown below the row of four buttons, together with the amount of money currently deposited in the contract.
Taking another step to reflect that Alice has received the cat from Bob, Alice and Bob agree and both choose value 0, for “pay”, and make that into a transaction:
Applying that transaction makes the contract evolve and to make the payment of the money to Bob, as is reflected in the state of the Playground in the following image. Note here
-
The account belonging to Alice now has a zero balance,
-
the choices made by Alice and Bob are recorded in the state, and
-
the payment to Bob has been made.
Moreover the current contract is now Refund, which has no effect since all the money in the contract has been spent.
At any point it is possible to undo a step by selecting the Undo
button. From the current state, doing this repeatedly will return us to the
position where Alice and Bob are prompted for a choice. If Alice and Bob now make different choices, we reach the following situation, where Carol is asked to choose 0 (for pay) or 1 (for refund):
After this choice we see this, where Alice is shown to have received her refund:
At any point in the simulation, as well as being able to Undo one step, we can also completely reset the system to its initial state by pressing the Reset button.
Use the Marlowe Playground to interact with the escrow contract in
the various scenarios discussed earlier, in the tutorial on
using Marlowe.
Explore making some changes to the contract, and interactions with those modified contracts.
Use the Marlowe Playground to explore the other contracts presented in there: the deposit incentive contract, and the crowd-funding example.