Build a dApp in 15 minutes

Let's build your first decentralized application(dApp) on the MultiversX Blockchain!

Prerequisites

important

Before starting this tutorial, make sure you have the following:

stable Rust version ≥ 1.78.0 (install via rustup)
multiversx-sc-meta (cargo install multiversx-sc-meta)
Node.js with version ≥ 20(guide here)
yarn (npm install --global yarn )

You are going to use sc-meta to:

Create a wallet to handle your transactions.
Build and deploy a contract.

Description

The Ping-Pong app is a very simple decentralized application that allows users to deposit a specific number of tokens to a smart contract address and to lock them for a specific amount of time. After this time interval passes, users can claim back the same amount of tokens.

Endpoints available:

ping: sending funds to the contract.
pong: claiming the same amount back.

Rules:

Each user can only ping once before they pong.
The ping amount must be exactly the specified value—no more, no less.
pong becomes available only after a set waiting period following a ping.

Architecture

Application Layer - Frontend

For the web application, we will have two pages:

Sign in - The page where you can authenticate using the xPortal app, Ledger, DeFi Wallet, xAlias, Web Wallet, Passkey Proxy or with Metamask proxy;
Dashboard - Here, you can either ping or pong. If you have already deposited, you will see a countdown timer until the time interval resets.

Blockchain Layer - Backend

You will interact with a smart contract that provides the following features:

ping: users send tokens to the contract, locking them for a specific period;
pong: users retrieve their funds, but only after the lock period expires.

The contract also includes several views, storage mappers and one event:

didUserPing: view that tells if a specific user has already ping-ed (true) or not (false);
getPongEnableTimestamp: view that provides the timestamp when pong will be available for a given address;
getTimeToPong: view that shows the remaining time until pong is enabled for a specific address;
getAcceptedPaymentToken: storage mapper that saves the token type allowed for deposits;
getPingAmount: storage mapper that records recording the total amount of tokens deposited;
getDurationTimestamp: storage mapper that saves the lock duration (in seconds) before pong can be called after a ping;
getUserPingTimestamp: storage mapper that saves the timestamp of the block where the user ping-ed;
pongEvent: event that signals a successful pong by the user with amount.

Think of this smart contract as the API for our dApp, handling all the core business logic.

To test it out, we will use MultiversX Blockchain Devnet Explorer—a public test network maintained by our community.

Set up the environment

Let's set up the environment for getting your first dApp up and running.

Project Structure

Start by creating a new folder for your project. Let's call it ping-pong.

mkdir -p ping-pong
cd ping-pong

By the time we are done, our project will have three subfolders: wallet, contract, and dapp.

Create wallet

To deploy a smart contract to the blockchain, you will need a wallet-a PEM file is recommended for simplicity and ease of testing.

Make sure you are in the ping-pong folder.

mkdir -p wallet
sc-meta wallet new --format pem --outfile ./wallet/wallet-owner.pem

info

PEM wallets are recommended only for testing and experimenting with non-production code. For real applications, always follow best practices and use secure wallets that can be generated here.

To initiate transactions on the blockchain, your wallet needs funds to cover transaction fees, commonly referred to as gas.

The MultiversX Devnet offers a faucet where you can claim 5 EGLD every 24 hours. Here’s how to fund your wallet:

Go to Devnet Wallet MultiversX and log in using your newly generated PEM file;
Once logged in, open the Faucet from the Tools;
Request 5 xEGLD to top up your wallet with test EGLD.

The Blockchain Layer

With the wallet setup complete, let's move on to the backend—the blockchain layer.

Let's start with the smart contract. You will first clone the Ping-Pong sample contract repository from here.

Make sure you are still in the ping-pong folder.

git clone https://github.com/multiversx/mx-ping-pong-sc contract

This will create a contract folder within ping-pong, containing all the necessary files for the Ping-Pong smart contract.

Build the Smart Contract

Now that you have the source code for the smart contract, you need to compile it into a binary that the MultiversX Virtual Machine can execute. Since the VM runs Web Assembly (WASM) code, you need to compile our Rust source code into a WASM file.

At path ping-pong/, run the following command to build the smart contract into a WASM file.

cd contract/ping-pong
sc-meta all build

After running the build command, a WASM file will be created at output/ping-pong.wasm.

This file contains the bytecode for the smart contract, ready to be deployed on the blockchain.

Deploy the Smart Contract

Next, let's deploy the smart contract to the blockchain.

Make sure wallet_owner.pem is in the wallet/ folder and that the smart contract is built.

Before deploying, you will need to modify the wallet from which transactions are made. Currently, they are made from a test wallet. To use the wallet you created earlier, you will need to make the following changes:

At the path /ping-pong/contract/ping-pong/interactor/src you will run:

In the file interact.rs located at the path /ping-pong/contract/ping-pong/interactor/src, the variable alice_wallet_address from new function will be modified from:

Before
let alice_wallet_address = interactor.register_wallet(test_wallets::alice()).await;

After
let alice_wallet_address = interactor
    .register_wallet(Wallet::from_pem_file("/ping-pong/wallet/wallet-owner.pem").unwrap())
    .await;

This next command deploys the Ping-Pong contract with the following settings:

Ping Amount: 1 EGLD.
Lock Duration: 180 seconds (3 minutes).

cargo run deploy --ping-amount 1000000000000000000 --duration-in-seconds 180

    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `/ping-pong/contract/target/debug/ping-pong-interact deploy --ping-amount 1000000000000000000 --duration-in-seconds 180`
sender's recalled nonce: 12422
-- tx nonce: 12422
sc deploy tx hash: b6ca6c8e6ac54ed168bcd6929e762610e2360674f562115107cf3702b8a22467
deploy address: erd1qqqqqqqqqqqqqpgqymj43x6anzr38jfz7kw3td2ew33v9jtrd8sse5zzk6
new address: erd1qqqqqqqqqqqqqpgqymj43x6anzr38jfz7kw3td2ew33v9jtrd8sse5zzk6

Once the command runs, review the log output carefully. Two key details to note:

Contract Address: in the example presented below is erd1qqqqqqqqqqqqqpgqymj43x6anzr38jfz7kw3td2ew33v9jtrd8sse5zzk6
Transaction Hash: in the example presented below is b6ca6c8e6ac54ed168bcd6929e762610e2360674f562115107cf3702b8a22467

We will take a look at the transaction details. Let's check them in the Devnet Explorer.

The Devnet Explorer will be your go-to tool for developing dApps on the MultiversX Blockchain. It allows you to test and monitor your deployments on the Devnet, ensuring everything works as expected.

With the smart contract successfully deployed, you can now interact with it using blockchain transactions to invoke its main functions: ping and pong.

The smart contract source code resides in ping-pong/contract/ping-pong/src/ping_pong.rs.

The contract includes several view functions for querying information. These are invoked using the MultiversX API:

didUserPing;
getPongEnableTimestamp;
getTimeToPong;
getAcceptedPaymentToken;
getPingAmount;
getDurationTimestamp;
getUserPingTimestamp.

The Application Layer

Now that the backend is ready, let’s move on to the application layer!

Set Up the dApp Template

To get started, navigate back to the root ping-pong folder.

Next, clone a simple dApp template that includes the necessary calls to interact with your newly deployed smart contract:

git clone https://github.com/multiversx/mx-template-dapp dapp
cd dapp

Use the preferred editor and customize the Smart Contract address located in src/config/config.devnet.ts

Then edit this instruction and change it to the contract address that you created in the deploy step.

important

Make sure you have yarn installed on your machine.

Navigate to the ping-pong/dapp folder and install the required dependencies:

npm install --global yarn
yarn add vite --dev

Start the Development Server

To test your dApp locally, start a development server with the following command:

yarn start:devnet

Running and Accessing the dApp

If you run the development server on your local machine, simply open https://localhost:3000 in your browser.

If the server is hosted on a remote machine, access it using the server's IP address, like http://ip:3000.

The production build of the app consists only of static files, so you can deploy it on any hosting platform you prefer.

Once the development server is up and running, seeing the Template dApp screen confirms that your application is live and ready!

Try your Application

You will log in using the wallet created previously.

To do this, you will press Connect button and then choose Web Wallet option.

After you access Web Wallet connection, you will be forwarded to login on Multiversx Wallet.

You will choose PEM option to login.

Ping Feature

After signing in, you will be directed to the dashboard where the Ping button will be visible.

Click the Ping button and you will be redirected to the authentication page on the web wallet.

A new transaction will be created, and you will be asked to confirm it. This transaction transfers the balance from your wallet to the smart contract address. Those funds will be locked for a specified period of time. Pay attention to the data field, where you call the smart contract function ping.

After you confirm the transaction, a success message will appear and the funds are locked. You can view the transaction shown in the image here.

You can see the amount of time you will have to wait until you can Pong.

Pong Feature

After the time interval has passed, you can claim the funds by clicking the Pong button.

Another blockchain transaction will wait to be processed and again you will be asked to confirm it. This time the amount will be zero, as you only have to invoke the pong function (specified in the data field).

Once the transaction is complete, a success message will appear, and your funds will be returned to your wallet. You can view the transaction shown in the image here.

Where to go next?

The purpose of this guide is to provide a starting point for you to discover the MultiversX technology capabilities and devkit. Keep reading the next docs to dive in deeper.

We welcome your questions and inquiries on Stack Overflow: https://stackoverflow.com/questions/tagged/multiversx.

Dive into more advanced topics and discover how to extend the smart contract, customize the wallet, and leverage MultiversX tools here: https://docs.multiversx.com.

Prerequisites​

Description​

Architecture​

Application Layer - Frontend​

Blockchain Layer - Backend​

Set up the environment​

Project Structure​

Create wallet​

The Blockchain Layer​

Build the Smart Contract​

Deploy the Smart Contract​

The Application Layer​

Set Up the dApp Template​

Start the Development Server​

Running and Accessing the dApp​

Try your Application​

Ping Feature​

Pong Feature​

Where to go next?​