This challenge will guide you through the process of building and shipping a crowdfunding dapp on Stellar using Soroban. Unlike traditional crowdfunding applications, crowdfunding dapps (decentralized applications) provide the means for users to pledge funds to a crowdfund campaign directly from their digital wallets, without the need for intermediaries.
In this challenge, you will learn how to deploy smart contracts to Futurenet, and how to 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. However, it's crucial to clarify that despite its functionality, the dapp is not promoted nor intended for deployment in a production-level setting on Futurenet. The challenge is designed for educational purposes, helping you understand how a dapp can be built and interacted with, with further customization and development, it has the potential to evolve into a full-fledged, ready-to-use crowdfunding solution.
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.
soroban-cli alias(installed in the next step)
Nodev18: Download Node
Freighter Wallet: Freighter Wallet
First, clone the Soroban Dapps Challenge repo and check out the
crowdfund branch, which contains the code for the crowdfund smart contract that powers this dapp:
git clone https://github.com/stellar/soroban-dapps-challenge.git
git checkout crowdfund
Then, install soroban-cli alias by running the following command:
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. This ensures that the challenge is reproducible and that all participants are using the same version of Soroban.
Checkpoint 1: 🎬 Deploy Smart Contracts
Now that you have the Crowdfund branch checked out, it's time to deploy the smart contracts to a Sandbox environment. 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. Deploying smart contracts to a Sandbox environment simulates that process without actually affecting Mainnet. When you deploy the smart contracts, you'll instead deploy to Futurenet, a test network with more cutting-edge features that have not yet been implemented in the Mainnet.
In your terminal, load the contracts and initialize them in the Sandbox environment by running the following commands:
npm run setup
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 crowdfund contract
Contract deployed successfully with ID: CBKY7UN5VGD4LIQFOBOTSUSQWK67BZZTA23NIEVWSWRR5SAT26JQN2BN
Initialize the abundance token contract
Initialize the crowdfund contract
> [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.
Please, save your deployed contract ID. You will need it to complete the challenge.
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 contributors to your crowdfund campaign will connect their digital wallets and pledge assets to the campaign's cause.
First, start the development server:
npm run dev
Now open your browser and visit http://localhost:3000. 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, otherwise the dapp display will be blank and a 'Account not found' will be printed on browser's console only. If you are using Freighter, be sure that you have properly configured the Freighter Wallet by following the instructions here.
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 crowdfund campaign, including the function for accepting contributions. If you want to dig into the specifics of the contract, take a look at the video walkthrough of the contract code here.
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: 🌟 Powering the Campaign
Fuel the vision! In this step, you will learn how to mint tokens and fund the crowdfunding campaign. Minting tokens in a crowdfund dapp, while not always required, serves as a bootstrapping mechanism for the campaign, allowing the campaign to be funded with the minted tokens.
- 🏦 Mint Tokens
- 💰 Fund the Campaign
Open Dapp and Mint
Open the dapp frontend and click on the "Mint 100 ABND" button.
You should see a popup from Freighter asking you to sign the transaction. Click on "Approve" and wait for the transaction to be confirmed.
Check Updated Balance
You should see an updated balance in the pledge component.
Fund the Campaign
Now that you have your wallet set up, let's fund the crowdfunding campaign. Open the frontend and click on the "Back this project" button. You should see a popup from Freighter asking you to sign the transaction.
Click on "Approve" and wait for the transaction to be confirmed. Once the transaction is confirmed, you should see a success message.
Check Updated Pledged Amount
You should see an updated balance reflecting the amount you have pledged in the pledge component.
Note: These are test tokens for use with Futurenet and cannot be used on 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 the Vercel cli installed.
If you don't have the Vercel cli installed, run the following command to install it globally:
npm i --global vercel
Next, you will need to remove the
target directory to save space for the the deployment. Run the following command to remove the
rm -rf target
Note: You can build this directory again by running
soroban contract buildin the
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 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 (you will not need to modify any settings) until you reach the completion prompt similar to the following:
🔗 Linked to julian-dev28/soroban-example-dapp (created .vercel)
🔍 Inspect: https://vercel.com/julian-dev28/soroban-example-dapp/C1YZVQSqh6WcyR1uvxz8q2tW1tjD [2s]
✅ Production: https://soroban-example-dapp-rho.vercel.app [42s]
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: 💪 Pass the Challenge!
Now it's time to submit your work!
Production URL from the previous step into the challenge form to pass the challenge!
Join our Community in Discord in case you have any issues or questions.
Checkpoint 6: ✅ Check your work!
In order to successfully complete this challenge, your work needs to be checked. Please, follow the steps below:
- Fork the challenge repository.
- Fill the
crowdfund/challenge/output.txtfile with your wallet address. The filled file should look as follows:
Public Key: GBSXUXZSA2VEXN5VGOWE5ODAJLC575JCMWRJ4FFRDWSTRCJ123456789
- Create a Pull Request to the
stellar/soroban-dapps-challenge/crowdfundbranch. When the PR is created, CI actions will check the
crowdfund/challenge/output.txtfile data and update your progress.
- Wait for the CI/CD pipeline results.
- Fix errors if present:
- find the error reason in the Crowdfund challenge CI results (you can find a link right in the pull request);
- return to your forked repository;
- fix errors and commit changes. The existing PR will be checked again.
- If the pipeline was successful, then congratulations! You completed the challenge!👏
Invite a friend to try out your dapp and ask them to provide feedback!
⚔️ Side Quests
🌐 Explore Stellar Laboratory to inspect your account assets on Futurenet.
You should see something like this:
📚 User Workflows Checklist
During this exercise you should be able to:
- Clone the example repo (Crowdfund Dapp)
- Choose your target amount and deadline
- Deploy your contract to Futurenet
- 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)
- See the current fundraising status (total amount & time remaining)
- See allowed assets
- Deposit an allowed asset
- See your deposit(s) appear on the page as the transactions are confirmed.
- "Live"-Update the page with the total amount with the new amount
🛡️🗡️ Take On More Challenges
View your progress and take on more challenges by visiting your User Dashboard!