Marlowe contracts are small, purpose-built financial agreements that live on the Cardano blockchain and execute step by step, exactly as written. A marlowe contract is a domain-specific language (DSL) designed so that non-programmers can read, write, and verify financial logic — escrows, payments, crowdfunding, swaps — without writing general-purpose code. Instead of a company or a person holding the money, the rules hold it, and every step is a public transaction anyone can inspect. This guide explains the building blocks, how a contract runs, how Marlowe differs from Plutus, and where to start in the Marlowe Playground.
Figure 1: Marlowe — a small financial DSL with safe, pre-approved templates
1. What Is a Marlowe Contract?
A Marlowe contract is a set of financial rules written in a small, dedicated language and stored on the Cardano blockchain. When the agreed conditions are met, the rules are enforced automatically — not by a bank, a lawyer, or a trading partner, but by the code itself.
Think of a vending machine. You insert money, choose a snack, and the machine delivers it — no shopkeeper needed. The machine's rules are fixed in advance. A Marlowe contract is like a vending machine for financial agreements, but with an important difference: it is a specific kind of vending machine. Its buttons are limited to a few pre-approved actions, because its only job is to handle money agreements safely.
Marlowe vs. a Regular Contract
| Aspect | Regular contract | Marlowe contract |
|---|---|---|
| Written in | Human language | A small financial DSL |
| Enforced by | Courts, lawyers, trust | The Cardano blockchain |
| Cost of enforcing | Time, money, risk | One transaction fee per step |
| Can it change midway? | Often renegotiated | No — rules are final |
| Transparency | Private | Public for everyone to inspect |
A normal agreement between two people relies on enforcement. If one side breaks the deal, the other must sue, wait, and hope. A Marlowe contract removes the waiting and the hoping — the outcome is decided by code at the moment each step executes.
Figure 2: The small set of pieces every Marlowe contract uses
2. The Building Blocks
Every Marlowe contract is a combination of a small, fixed set of parts. There is no arbitrary code — just these building blocks, arranged like the pieces of a flowchart.
Actions are the things a participant can do:
- Deposit — someone puts money into the contract.
- Choice — someone picks an option (for example, "buy" or "refund").
- Notify — someone signals that an outside condition has been met.
Terms are the rules that respond to those actions:
- When — wait for one of a set of events (an action or a timeout).
- Pay — move money from one account to another.
- If — follow one path or another depending on a condition.
- Let — give a value a name so it can be reused.
- Close — finish the contract and return any remaining balance.
- Assert — check a statement; the contract refuses to continue if it is false.
Around these sit values and observations — the math (add, compare, constant) that the rules use to decide things.
The key idea: because the language is limited to these pieces, a contract reads almost like plain language. "When X deposits 500, pay 500 to Y, then close."
Figure 3: One action, one transaction — how a Marlowe contract moves forward
3. How a Marlowe Contract Runs
A Marlowe contract does not run in the background like an app. It sits on the blockchain, waiting. Someone triggers the next step, and the network checks the rules before anything moves.
On Cardano, a contract is a validator — a pure function that answers one question about every proposed step: approve or reject? The Marlowe rules and the current balances live in the contract's state, and each participant action is submitted as a normal Cardano transaction. The validator compares the action against the contract's rules:
- If the action is allowed, the contract advances — money moves, a new state is created, and the next step is available.
- If the action is not allowed, the transaction is rejected and nothing changes.
This is Cardano's eUTXO model at work: spending an old state and creating a new one, with every version permanently visible on the public chain. No edits behind the curtain — the whole history is auditable forever.
The Escape Hatch: Timeouts
Every Marlowe contract is built with timeouts. If a participant never acts, the contract can close the agreement and return the funds. This is a crucial safety feature — money can never be trapped forever in a contract that one side ignores.
4. Marlowe vs. Plutus
Cardano has two main ways to write smart contracts, and they serve different jobs:
| Aspect | Marlowe | Plutus |
|---|---|---|
| Purpose | Financial contracts only | Any logic you can program |
| Language | Small DSL, readable by non-programmers | Full language (Haskell-based) |
| Who writes it | Domain experts, analysts | Developers |
| Room for error | Very small — fixed building blocks | Large — full programming power |
| Built-in analysis | Yes — the analyzer checks properties | You verify it yourself |
Plutus is like a full programming language: anything is possible, but bugs are possible too. Marlowe is like a set of pre-approved financial templates: fewer features, but far fewer ways to break a contract — and the code is simple enough for a non-programmer to audit.
Both run on the same Cardano ledger, pay the same fees, and follow the same validation rules. The choice is about what you are building: standard financial logic → Marlowe; anything beyond that → Plutus.
Figure 4: Marlowe vs Plutus — two tools, one ledger
5. Start in the Marlowe Playground
The best way to understand Marlowe is to build with it — and the Marlowe Playground is a browser tool that needs no installation.
- Blockly visual editor — drag and drop blocks instead of typing code. Each block maps 1:1 to a Marlowe construct, so what you see is what the contract actually does.
- Simulator — step through the contract over time, acting as each participant, and watch the balances move.
- Analyzer — the standout feature. The analyzer proves properties of your contract, such as "money is preserved" and "no funds are locked forever." Think of it as an inspector that checks the contract for traps before anyone signs it — something regular contracts simply cannot offer.
When you are ready to move a contract to the real network, Marlowe Runtime takes the contract from the Playground and runs it on the Cardano blockchain, exposing APIs so apps can interact with it. Because the same Marlowe semantics are encoded in the on-chain validator, every node agrees on the rules.
Figure 5: The Playground, plus the kinds of contracts people build
6. What Can You Build?
All of these examples share one shape: lock value now, release it later when agreed conditions are met — which is exactly what the When, Pay, and Close blocks express.
- Escrow — two parties deposit; money is released only when both confirm. Instantly familiar in cash-on-delivery cultures: the contract is a "trung gian thanh toán" that cannot run away with the funds.
- Coupon payments — a deposit pays out a fixed amount to a holder on a schedule.
- Crowdfunding — supporters deposit toward a target; if the target is not met by the deadline, everyone gets a refund.
- Swaps — two parties exchange tokens when both sides lock them in.
- Options — the right to buy or sell an asset at a fixed price before a deadline.
The theme across every example is the same: no middleman holding the money, no trust required — just a set of rules that everyone can inspect and that the blockchain enforces automatically.
FAQ
1. Do I need to be a programmer to use Marlowe? No — that is the point. Marlowe's building blocks are simple enough to read like plain language, and the Playground's block editor lets you build visually. Plutus, by contrast, requires programming skills.
2. Is a Marlowe contract the same as a smart contract? Yes — Marlowe is a way of writing smart contracts, specialized for financial agreements. It runs on the same Cardano ledger and follows the same validation rules as any other smart contract.
3. Can the money get stuck in a Marlowe contract? Marlowe contracts are designed with timeouts and a Close term precisely to prevent this, and the Playground analyzer can prove that no funds will be locked forever before you commit.
4. What is Marlowe Runtime? It is the backend that takes a contract you built (in the Playground) and runs it on the Cardano blockchain, providing APIs so applications can interact with the live contract.
5. Marlowe or Plutus — which should I use? For standard financial logic — payments, escrow, crowdfunding, swaps — Marlowe is simpler and safer. For anything beyond finance, or unusual logic, Plutus is the general-purpose choice.