Skip to main content

A liquidity pool is a collection of tokens or digital assets deposited by users and held in a smart contract or dapp that can be used to provide essential liquidity to decentralized exchanges (DEXs) and other decentralized finance (DeFi) protocols. Since liquidity plays a crucial role in enabling DeFi systems, liquidity pools, where assets can be held, lent, borrowed, swapped, or traded (depending on dapp functionality), are fundamental to these systems.

The functionality of this liquidity pool dapp will allow users to mint tokens, deposit liquidity, swap between asset types, and withdraw funds from the liquidity pool. This dapp challenge will walk you through the step-by-step process of creating and launching a liquidity pool dapp on Stellar using Soroban smart contracts. You will learn how to deploy smart contracts to a sandbox environment and interact with them through a web frontend. In this context, the term "ship" refers to finalizing the development process of your dapp, ensuring that it functions as expected and is accessible for user interaction and testing through a hosted frontend. Despite the end-to-end functionality of this challenge, this dapp is not promoted nor intended for deployment in a production-level setting on Futurenet, but rather is designed for educational purposes.

Checkpoint 0: πŸ“¦ Install πŸ“šβ€‹

Start by installing the required dependencies. You'll also want to be sure you have the most updated version of Rust installed.

Required:

First, clone the Soroban example dapp repo and navigate to the liquidity-pool directory:

git clone https://github.com/stellar/soroban-dapps-challenge
cd soroban-dapps-challenge
git checkout liquidity-pool

Then, install soroban-cli alias by running the following command:

cargo install_soroban

Soroban CLI is the command line interface to Soroban. It allows you to build, deploy, and interact with smart contracts, configure identities, generate key pairs, manage networks, and more. The soroban-cli alias that is used in this challenge is a pinned version of the soroban-cli that is used in the Soroban Dapps Challenge. Using the soroban-cli alias ensures that the challenge is reproducible and that all participants are using the same version of Soroban.

Checkpoint 1: 🎬 Deploy Smart Contracts​

Deploying a smart contract in a production setting involves submitting the contract code to the blockchain's main network (Mainnet), where it becomes part of the chain's immutable ledger. When you deploy the smart contracts in this challenge, you'll instead deploy to Futurenet, a test network with more cutting-edge features that have not yet been implemented in the Mainnet. Deploying smart contracts to a sandbox environment simulates the production-level deployment process without actually affecting Mainnet.

Now that you have the Liquidity Pool branch checked out, load the contracts and initialize them in the sandbox environment by running the following commands in your terminal:

./initialize.sh futurenet

If the command runs successfully, your terminal will return a series of messages notifying you about the successful initialization of the contracts and the post-installation sequence.

Contract deployed successfully with ID: CBXHU5BWWTOCZRYX3DMSSKCFG7B3K2YG2I5F75ALPQ6GCY6ZES2XKLTI
Deploy the liquidity pool contract
Contract deployed successfully with ID: CBKY7UN5VGD4LIQFOBOTSUSQWK67BZZTA23NIEVWSWRR5SAT26JQN2BN
Initialize the abundance token contract

Initialize the liquidity pool contract

Done

> [email protected] build-contracts
...

The contract ID is a unique identifier for a smart contract deployed on a blockchain. This contract ID is used to interact with and reference the smart contract, allowing users to invoke functions from the smart contract, send transactions, or otherwise interact with the smart contract's functionalities and data stored on the blockchain.

tip

Please, save your deployed contract ID. You will need it to complete the challenge.

Please connect to Testnet network.

Checkpoint 2: 🀝 Connect the Frontend to the Backend​

Now that you have deployed the smart contract, it's time to check out the frontend of your dapp. The frontend is the browser interface where users will connect their digital wallets to make deposits into and withdrawals from the liquidity pool. The frontend is also where users will be able to see their balances and swap tokens.

Because interacting with dapps requires both backend and frontend development, the Soroban Dapps Challenge includes the functionality to easily deploy a frontend interface of the dapps. Building out the frontend from scratch would typically involve creating a user interface (UI) and user experience (UX) design, as well as writing the code for the frontend. In this challenge, you will use the frontend that is already built for you.

To set up the development server, navigate to the frontend folder of the soroban-dapps-challenge repository and run the following command:

make setup && make start_dev

Note: This may require admin privileges on some systems.

Now open your browser and visit http://localhost:5173. You should be able to see the frontend of your dapp.

Note: Follow the instructions below and ensure that you have funded your wallet address that you intend to use from browser.

Now that you have the frontend running, it's time to connect it with the backend, your smart contract, that defines the rules and logic of the liquidity pool, including the token swap and liquidity pool functions.

You will need to add some Futurenet network lumens to your wallet to interact with the dapp. Visit https://laboratory.stellar.org/#account-creator?network=futurenet, and follow the instructions to create and or fund an account on Futurenet. Remember, these are test lumens for use on Futurenet and cannot be used on Mainnet.

Checkpoint 3: 🌊 Dive into the Liquidity Pool​

Embark on a tidal journey! In this step you will mint, deposit, swap, and withdraw tokens from the liquidity pool. Minting tokens, depositing liquidity, swapping between asset types, and withdrawing funds from the liquidity pool constitute the basic lifecycle of interacting with a DeFi protocol.

In the context of liquidity pools, depositing and withdrawing assets involve connecting a digital wallet and submitting deposit/withdraw transactions. In this liquidity pool dapp challenge specifically, you will also need to mint the test tokens that you will then use to make deposits to the liquidity pool. (This minting of test tokens is different from liquidity pools where depositors may receive minted tokens in exchange for their deposited funds.) Perhaps one of the most important actions a user can take through liquidity pool dapps is swapping tokens. In fact, the ability to swap from one asset to another through a liqudity pool is a powerful feature of DeFi protocols: instead of exchanging assets through traditional financial institutions and intermediaries, users can have direct access to decentralized asset exchange via liquidity pool dapps, without needing a bank account or other traditional financial instruments.

Mint USDC and BTC​

In order to use this liquidity pool dapp, you will need to mint test tokens which can then be used to make deposits and swaps via the frontend of the dapp. To mint USDC and BTC test tokens, open the dapp frontend and click the "MINT" button for USDC and BTC.

Note: These are test tokens for use on Futurenet or Mainnet.

Checkpoint 4: 🚒 Ship It! πŸšβ€‹

Now that your dapp is fully functional, its time to deploy it to a production environment. In this step, you will learn how to deploy your dapp to Vercel, a cloud platform for static sites that offers a quick and effective way to deploy the frontend of your dapp. This section requires that you have a Vercel account and install the Vercel CLI.

First, you will remove the target directory, as it is not used by Vercel to deploy your site. To do this, navigate to the liquidity-pool directory and run the following:

rm -rf target

Note: You can build this directory again by running soroban contract build in the contracts/abundance directory.

Next, you must move your .soroban directory to the frontend directory.

From a terminal in the liquidity-pool directory, run the following command:

mv .soroban frontend/.soroban

Then, you need to update the package.json file in the frontend directory to point to the new contract binding locations.

-"liquidity-pool-contract": "file:../.soroban/contracts/liquidity-pool",
-"share-token-contract": "file:../.soroban/contracts/share-token",
-"token-a-contract": "file:../.soroban/contracts/token-a",
-"token-b-contract": "file:../.soroban/contracts/token-b",

+"liquidity-pool-contract": "file:.soroban/contracts/liquidity-pool",
+"share-token-contract": "file:.soroban/contracts/share-token",
+"token-a-contract": "file:.soroban/contracts/token-a",
+"token-b-contract": "file:.soroban/contracts/token-b",

Next, you will use the Vercel CLI to complete your deployment.

First, install the Vercel CLI:

npm i --global vercel

Then, remove any existing .vercel directory in your project to ensure that you are starting with a clean slate:

rm -rf .vercel

Then, run the following command to deploy your example dapp:

vercel --prod

Vercel will prompt you to link your local project to a new Vercel project. Follow the answers to the prompts below to ensure that your local project is correctly linked to a new Vercel project:

? Set up β€œ~/Documents/GitHub/test/soroban-dapps-challenge”? [Y/n] y
? Which scope should contain your project? <VERCEL_UNAME>
? Link to existing project? [y/N] n
? What’s your project’s name? <PROJECT_NAME>
? In which directory is your code located? ./

Then, continue through the prompts until you see the following message regarding setting overrides:

? Want to override the settings? [y/N] y
? Which settings would you like to override? (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◯ Build Command
β—― Development Command
β—― Output Directory

Select each entry (type "a") and set the following values:

build command

cd frontend && make build

development command

cd frontend && make start_dev

output directory

frontend/dist

Once the deployment is complete, you should see a completion message similar to the following:

πŸ”—  Linked to julian-dev28/liquidity-pool (created .vercel)
πŸ” Inspect: https://vercel.com/julian-dev28/liquidity-pool/FfsAJdgUR9LKH5EmGiuMCMYUMTi2 [2s]
βœ… Production: https://liquidity-pool.vercel.app [54s]
tip

Please, save your production url, you will need it to complete the challenge.

You can now visit the preview link to see your deployed dapp! πŸŽ‰

Remember, you must add Futurenet network lumens to your Freighter wallet to interact with the deployed example dapp. Visit https://laboratory.stellar.org/#account-creator?network=futurenet, and follow the instructions to create your Freighter account on Futurenet.

Checkpoint 5: βœ… Complete the Challenge!​

Now it's time to submit your work!

Submit your Production URL from the previous step into the challenge form to pass the challenge!

Please connect to Testnet or Futurenet network.

Checkpoint 6: πŸ’ͺ Flex!​

🍴 Fork the Soroban Dapps Challenge repo and make your own changes to the Liquidity Pool branch.

Customize the code and submit a pull request for the Liquidity Pool Dapp Challenge. You can experiment with new fee strategies, improve the user interface, or integrate additional token pair options.

Take this opportunity to showcase your skills and make your mark on the Liquidity Pool Dapp. Good luck!

πŸ“š User Workflows Checklist​

During this exercise, you should be able to:

  • Clone the example repo (Liquidity Pool Dapp)
  • Deploy your contract to a sandbox environment.
  • Deploy the example web UI somewhere (e.g., Netlify, Vercel, Surge, etc.)

Then, via the web UI, you should be able to:

  • Connect your wallet
  • See your current balance(s)
  • Mint assets
  • Deposit assets
  • Swap assets
  • Withdraw assets
  • See your transaction(s) appear on the page as the transactions are confirmed

πŸ›‘οΈπŸ—‘οΈ Take On More Challenges​

View your progress and take on more challenges by visiting your User Dashboard!