Tutorial on building end-to-end Cardano dApps

This tutorial covers the complete end-to-end flow for implementing a decentralized Application (dApp) on Cardano Blockchain. At the moment of writing it, there is no standard way to fully implement an end-user Cardano dApp. Different projects have developed their own tools and proposed different approaches. The proposal presented here consists of a Client-Server architecture, where the Server side is based on the open-source libraries plutus-apps, developed by IOG, and the Client side is a web frontend using the PAB Client typescript library, which provides the necessary functionality for connecting with the Plutus Application Backend to receive unbalanced transactions, and then balance, sign, and submit them.

The text is based on a concrete implementation, a dApp example whose purpose is to have something simple but containing enough functionality to show how to use the proposed tools. It’s important to note that this tutorial doesn’t pretend to cover how to design complex solutions on the eUTxO model. The example is very simple and some design decisions are related to the specific purpose of including common features of any interesting dApp: parameterized validators, minting policies, how to read and write datums, among others.

It’s assumed that the reader is familiar with the eUTxO model, Haskell programming language and Plutus validators (for example, they already completed the Plutus Pioneer Program).

The structure is as follows: in Preliminaries section we introduce the example to implement, a detailed explanation of the proposed architecture, and instructions for building and running the example dApp. Then we go into details on the Server side, covering the main aspects of the Haskell implementation, introducing the proposed modules design, going through each component, and explaining the main implementation aspects. Finally, we review the Client side by introducing the PAB Client library and how to use it.

Preliminaries

• 1. The Example - A Simple Escrow
  • 1.1. The Problem
  • 1.2. How to solve it
  • 1.3. eUTxO-model-based solution
  • 1.4. More details
• 2. Cardano dApp Architecture
  • 2.1. Server Side
  • 2.2. Client Side
• 3. Setup and Run the example
  • 3.1. Docker
  • 3.2. Local

Server Side

• 1. Modules Design
• 2. Business Logic and Types
  • 2.1. Business
  • 2.2. Types
• 3. Off-Chain
  • 3.1. Interface
  • 3.2. Operations
• 4. On-Chain
  • 4.1. OnChain Module
  • 4.2. Validator Module
• 5. Plutus Application Backend
  • 5.1. Endpoints Specification
  • 5.2. Implementation
• 6. Testing
  • 6.1. Emulator Trace
  • 6.2. Property Based Testing

Client Side

• 1. Introduction
• 2. PAB API
  • 2.1. Create a PAB API instance
  • 2.2. Activate a contract instance
  • 2.3. Call an endpoint
  • 2.4. Query the instance status
• 3. Contract Endpoints
  • 3.1. Create a ContractEndpoints instance
  • 3.2. Perform an operation
  • 3.3. Reload the observable state
• 4. Balancer
  • 4.1. Balancing process overview
  • 4.2. Example: An escrow resolve
  • 4.3. Helper modules
  • 4.4. Instantiate the balancer
  • 4.5. Call the balancer
  • 4.6. Other uses
• 5. Escrow frontend
  • 5.1. User interface
  • 5.2. Main class
  • 5.3. Parameters
  • 5.4. Observable state