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, the smart contract platform of Cardano. 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.
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 express 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
Conclusion
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.
