Marlowe Playground for Cardano Developers: Build, Simulate, and Analyze Smart Contracts.

The Marlowe Playground is an online environment that allows you to write, simulate, and analyze smart contracts in Marlowe, a domain-specific language for financial contracts that can be compiled to Plutus, Cardano’s native smart contract platform. In this article, we’ll explore how you can get started with the Marlowe Playground. But before that, here’s a primer on the Marlowe playground and its core components. 

Key Components of the Marlowe Playground

The Editor:  This is the central workspace  where you can write and edit your Marlowe smart contracts using either Marlowe DSL,Haskell, or JavaScript syntax. You can also import existing contracts from the examples library or upload your own files. The editor provides syntax highlighting, auto-completion, and error checking features to help you write your contract.

Marlowe also provides the Blockly editor where you can create your Marlowe contract using a graphical interface. You can drag and drop blocks that represent the basic elements of Marlowe, such as actions, choices, observations, and payments. You can also convert your Blockly contract to Haskell or JavaScript code, and vice versa. This intuitive web interface is particularly helpful for developers with limited programming experience.

The simulator is where you can test your Marlowe contract by executing it step by step. You can see the current state of the contract, the inputs and outputs of each step, and the balances of each participant. It allows you to set up initial parameters, including participants, roles, and balances, and define actions and observations. The Evaluate button runs the simulation, showing how the state of the contract evolves over time.You can also use the timeline and the slider to navigate through the execution history of the contract.

The analyzer is where you can verify the properties and behaviors of your Marlowe contract using formal methods without executing them.. You can specify the properties you want to check using logical expressions, and the analyzer will use the SMT solver Z3 to verify them. You can also use the counterexample feature to find scenarios where your properties are violated.

Other than these features, the Marlowe Playground also offers a set of example contracts that users can explore and use as a starting point for their projects. These examples cover a range of scenarios. It also offers extensive documentation and deployment information to help you understand the Marlowe features and how to deploy your smart contracts on the Cardano blockchain.

Getting Started with the Marlowe Playground

To start using the Marlowe Playground, follow these steps:

Choose Your Environment:

Head to https://play.marlowe.iohk.io/ and select your preferred environment, whether it’s Marlowe, JavaScript, Haskell, or Blockly. This choice dictates the language you’ll use to create your contract.

Initialize your project

Within the editor, you have the option to start a fresh, open an existing project or an example, and import or export your project as a file for seamless collaboration and version control.

Edit your smart contract

To write your contract, you can use the Marlowe constructs such as Pay, When, Choice, etc. You can also define custom roles, tokens, and values.

For example, here is a simple contract written in JavaScript that implements a peer-to-peer lending system. The contract has a list of lenders and borrowers, and a mapping of loans for each borrower. It can allow anyone to lend or borrow money, but only with a fixed interest rate and duration. The contract also has a function to repay the loan with interest, and a function to liquidate the loan if the borrower defaults.

function LendingContract() {
  // Initialize the state variables
  this.lenders = []; // The list of lenders
  this.borrowers = []; // The list of borrowers
  this.loans = {}; // The mapping of loans for each borrower
  this.interestRate = 0.1; // The fixed interest rate (10% per year)
  this.duration = 365; // The fixed duration of the loan (365 days)
}

// Define the lend function
LendingContract.prototype.lend = function(lender, amount) {
  // Check if the lender has enough balance
  if (lender.balance < amount) {
    throw new Error("Insufficient balance");
  }

  // Deduct the amount from the lender's balance
  lender.balance -= amount;

  // Add the lender to the list of lenders
  if (this.lenders.indexOf(lender) === -1) {
    this.lenders.push(lender);
  }
};

// Define the borrow function
LendingContract.prototype.borrow = function(borrower, amount) {
  // Check if the borrower has an existing loan
  if (this.loans[borrower]) {
    throw new Error("You already have a loan");
  }

  // Check if there are enough lenders to fund the loan
  if (this.lenders.length === 0) {
    throw new Error("No lenders available");
  }

  // Create a new loan object
  let loan = {
    amount: amount, // The principal amount of the loan
    interest: amount * this.interestRate, // The interest amount of the loan
    dueDate: Date.now() + this.duration * 24 * 60 * 60 * 1000, // The due date of the loan
    status: "active", // The status of the loan
    lender: null // The lender of the loan
  };

  // Assign a lender to the loan
  for (let i = 0; i < this.lenders.length; i++) {
    let lender = this.lenders[i];
    if (lender.balance >= amount) {
      // The lender has enough balance to fund the loan
      loan.lender = lender;
      break;
    }
  }

  // Check if a lender was found
  if (!loan.lender) {
    throw new Error("No lender with enough balance");
  }

  // Add the loan to the mapping of loans
  this.loans[borrower] = loan;

  // Add the borrower to the list of borrowers
  if (this.borrowers.indexOf(borrower) === -1) {
    this.borrowers.push(borrower);
  }

  // Transfer the loan amount to the borrower's balance
  borrower.balance += amount;
};

// Define the repay function
LendingContract.prototype.repay = function(borrower) {
  // Check if the borrower has an active loan
  let loan = this.loans[borrower];
  if (!loan || loan.status !== "active") {
    throw new Error("You don't have an active loan");
  }

  // Check if the borrower has enough balance to repay the loan
  let total = loan.amount + loan.interest; // The total amount to repay
  if (borrower.balance < total) {
    throw new Error("Insufficient balance");
  }

  // Deduct the total amount from the borrower's balance
  borrower.balance -= total;

  // Transfer the total amount to the lender's balance
  loan.lender.balance += total;

  // Update the status of the loan to "repaid"
  loan.status = "repaid";
};

// Define the liquidate function
LendingContract.prototype.liquidate = function(borrower) {
  // Check if the borrower has an active loan
  let loan = this.loans[borrower];
  if (!loan || loan.status !== "active") {
    throw new Error("You don't have an active loan");
  }

  // Check if the loan is overdue
  if (Date.now() < loan.dueDate) {
    throw new Error("The loan is not overdue");
  }

  // Transfer the borrower's balance to the lender's balance
  loan.lender.balance += borrower.balance;

  // Set the borrower's balance to zero
  borrower.balance = 0;

  // Update the status of the loan to "liquidated"
  loan.status = "liquidated";
};
    return Close;
})

In the editor, you can compile your contract to view errors and resolve them until the contract runs successfully.

Simulate the contract

To simulate your contract, you can switch to the Simulation tab and set up the initial parameters, such as participants, roles, and balances. You can also add inputs such as actions and observations.

Run the contract

To run your contract, you can click on the Evaluate button and see how the state of the contract changes after each step. You can also use the slider to go back and forth in the simulation history.

Analyze the contract

For contract analysis, you can switch to the Static Analysis tab and use the tools such as Blockly representation, Marlowe semantics, contract visualization, and property verification.

Deploy your contract

To deploy your contract on the Cardano blockchain, you can follow the instructions in https://developers.cardano.org/docs/smart-contracts/marlowe/#how-do-i-run-my-marlowe-contract-on-the-cardano-blockchain

For more information on how to get started with the Marlowe Playground and other features provided by the platform, follow this thread on X (previously Twitter) and the resources attached.

Putting it all together

The Marlowe Playground is a powerful tool that enables you to design, test, and verify smart contracts in a user-friendly and interactive way. You can learn more about the Marlowe Playground and its features by using the following resources:

• Marlowe Tutorial: This is a comprehensive guide that teaches you how to write Marlowe contracts from scratch, using examples and exercises. You can also use the Marlowe Playground to test your code and see how it works in the simulator.
• Marlowe Examples: This is a repository of Marlowe contracts that you can use as templates or inspiration for your own projects. You can browse the code, download it, or open it in the Marlowe Playground directly.
• Marlowe Playground YouTube Playlist: This is a series of videos that demonstrate how to use the Marlowe Playground and how to create various types of Marlowe contracts, such as escrow, swap, coupon bond, and crowdfunding.