ReadMe.md

Starter Kit for Marlowe

This repository contains lessons for using Marlowe via REST and at the command line. It is meant to be used with demeter.run or with a Docker deployment of Marlowe Runtime.

Contents

• Setup: two alternatives
  • Use demeter.run extension for Marlowe Runtime: using demeter.run's Marlowe Runtime extension (video) (2:32)
    • Select the "Marlowe Tutorial" starter kit.
    • Be sure to turn on the "Cardano Nodes" and "Cardano Marlowe Runtime" extensions.
    • Check that those match the network you are using for the starter kit.
  • Deploy Marlowe Runtime locally with docker and launching Marlowe Runtime using Docker (video) (9:48).
• Lessons
  • 0. Preliminaries and demonstration of setting up keys and addresses (video) (6:17)
  • Zero-Coupon Bond (ZCB)
    • 1. ZCB using the Marlowe Runtime command-line client
      • ZCB using the Marlowe Runtime command-line client (video) (24:42)
    • 2. ZCB using the Marlowe Runtime REST API
      • ZCB using the Marlowe Runtime REST API (video) (23:46)
    • 3. ZCB using the Marlowe command-line tool
      • ZCB using the Marlowe command-line tool (video) (13:43)
  • 4. Escrow using Marlowe Runtime REST API
    • Escrow using Marlowe Runtime REST API (video) (24:45)
  • 5. Swap of Ada for Djed using Marlowe Runtime Rest API
    • Swap of Ada for Djed using Marlowe Runtime Rest API (video) (16:23)
  • 6. Simple web application using a CIP-30 wallet
    • Simple web application using a CIP-30 wallet (video) (3:13)
• Additional Information
  • Overview of Marlowe Tools
  • Overview of Marlowe Runtime
  • Using Marlowe Safely
  • Manual installation using Nix

You can ask questions about Marlowe in the #ask-marlowe channel on the IOG Discord or post problems with this lesson to the issues list for the Marlowe Starter Kit github repository.

---

Setup

This repository is meant to be used with demeter.run to execute Marlowe contracts using Marlowe Runtime, or with another similar cloud deployment of Marlowe Runtime.

• Using demeter.run's Marlowe Runtime extension (video) (2:42) to access Marlowe Runtime.
• Select the "Marlowe Tutorial" starter kit.
• Be sure to turn on the "Cardano Nodes" and "Cardano Marlowe Runtime" extensions.
• Check that those match the network you are using for the starter kit.

Alternatively, one can deploy Marlowe Runtime locally with docker.

• Launching Marlowe Runtime using Docker (video) (9:48) to set up Marlowe Runtime.

If you are unfamiliar with the Marlowe smart-contract language or with the Cardano blockchain, you may want to familiarize yourself with the following information:

1. The Marlowe Language
2. Cardano's Extended UTxO Model.

Lessons

• Lesson 0. Preliminaries: This lesson describes how to create and fund the Cardano addresses used in the lessons in this starter kit.
  • Demonstration of setting up keys and addresses (video) (6:17)
• Lesson 1. Marlowe Runtime's Command-Line Interface: This lesson shows how to use Marlowe Runtime to execute a zero-coupon bond contract using the command line for a Cardano testnet.
  • ZCB using the Marlowe Runtime command-line client (video) (24:42)
• Lesson 2. Marlowe Runtime's REST Interface: This lesson shows how to use the REST API for Marlowe Runtime to execute a zero-coupon bond contract on a Cardano testnet.
  • ZCB using the Marlowe Runtime REST API (video) (23:46)
• Lesson 3. Marlowe CLI: This lesson shows how to use the Marlowe CLI without Marlowe Runtime to execute a zero-coupon bond contract on a Cardano testnet.
  • ZCB using the Marlowe command-line tool (video) (13:43)
• Lesson 4. Escrow: This lesson shows how to use the REST API of Marlowe Runtime to execute an escrow contract on a Cardano testnet.
  • Escrow using Marlowe Runtime REST API (video) (24:45)
• Lesson 5. Swap: This lesson shows how to use the REST API of Marlowe Runtime to execute a swap contract for ada and djed on a Cardano testnet.
  • Swap of Ada for Djed using Marlowe Runtime Rest API (video) (16:23)
• Lesson 6. Simple web application using a CIP-30 wallet
  • Simple web application using a CIP-30 wallet (video) (3:13)

Additional Information

Marlowe Tools

Three alternative workflows are available for running Marlowe contracts:

1. Marlowe CLI (marlowe-cli) for lightweight experiments with Marlowe transactions.
2. Marlowe Runtime CLI (marlowe-runtime-cli) for non-web applications that use the Marlowe Runtime backend services.
3. Marlowe Runtime Web (marlowe-web-server) for web applications that use Marlowe Runtime backend services.

Marlowe Runtime provides a variety of transaction-building, UTxO management, querying, and submission services for using Marlowe contracts: this makes it easy to run Marlowe contracts without attending to the details of the Cardano ledger and Plutus smart contracts. On the contrary, Marlowe CLI does not support querying and UTxO management, so it is best suited for experienced Cardano developers.

Marlowe Runtime

Marlowe Runtime consists of several backend services and work together with a web server. See the Marlowe documentation for more information on Marlowe Runtime.

Using Marlowe Safely

If one plans to run a Marlowe contract on the Cardano mainnet, then one should check its safety before creating it, so that there is no chance of losing funds.

Here are the steps for checking the safety of a Marlowe contract:

1. Understand the Marlowe Language.
2. Understand Cardano's Extended UTxO Model.
3. Read and understand the Marlowe Best Practices Guide.
4. Read and understand the Marlowe Security Guide.
5. Use Marlowe Playground to flag warnings, perform static analysis, and simulate the contract.
6. Use Marlowe CLI's marlowe-cli run analyze tool to study whether the contract can run on a Cardano network.
7. Run all execution paths of the contract on a Cardano testnet.

Manual Installation Using Nix

When using Marlowe tools within demeter.run, nothing needs to be installed.

If you are not using demeter.run and have the Nix package manager installed with Nix flakes support enabled, you can launch a Jupyter notebook server, open a development environment, or build the tools. Be sure to set yourself as a trusted user in the nix.conf; otherwise, build times will be very long.

Launching a Jupyter Server for Marlowe Tools

One can launch a Jupyter notebook server for the workbooks and tools as follows:

$ git clone https://github.com/input-output-hk/marlowe-starter-kit/
$ cd marlowe-starter-kit
$ nix run

One can even run a Jupyter notebook server with Marlowe tools already installed (but no example notebooks) without manually cloning this repository:

nix run github:input-output-hk/marlowe-starter-kit

Opening a Development Shell

One can also enter a Nix development shell that contains the Marlowe tools:

$ git clone https://github.com/input-output-hk/marlowe-starter-kit/
$ cd marlowe-starter-kit
$ nix develop

This can also be done without cloning this repository:

nix develop github:input-output-hk/marlowe-starter-kit

Building individual Tools

One can build individual Marlowe tools using Nix:

nix build github:input-output-hk/marlowe-starter-kit/#marlowe-runtime-cli -o build/marlowe-runtime-cli
nix build github:input-output-hk/marlowe-starter-kit/#marlowe-cli         -o build/marlowe-cli
nix build github:input-output-hk/marlowe-starter-kit/#marlowe-pipe        -o build/marlowe-pipe