This challenge will guide you through the process of setting up, customizing, and deploying a Soroban Payment dapp, a blockchain-powered payment application designed to work with the Freighter wallet. Payment dapps are powerful because they offer users equitable and accessible means to send and receive payments. Transactions via a payment dapp are peer-to-peer, which means that no central authority, third-party, or bank oversees or controls the payment. This decentralization reduces payment fees, which are comparatively minimal on a blockchain, and transaction time, which is, via a payment dapp, almost instantaneous. What's more, the wallet integration in a payment dapp, like Freighter in this case, means that anyone with a smartphone and the wallet installed can use the payment dapp, no matter where they are in the world.

Checkpoint 0: 📦 Install Dependencies​

Before you begin, ensure you have the following installed on your system. You'll also want to be sure you have the most updated versions of Rust and Soroban installed.

• stellar-cli: Install stellar-cli
• Node (>=16.14.0 < 17.0.0): Download Node
• Yarn (v1.22.5 or newer): Install Yarn
• Freighter Wallet: Freighter Wallet

Node and Yarn are package managers that let you install and manage dependencies during the dapp development process. Freighter is the wallet you will integrate into your payment dapp.

Checkpoint 1: 🚀 Clone the Repository​

Clone and set up the Soroban Dapps Challenge repository, which contains the Soroban Payment Dapp files. Then run yarn to install the dependencies.

git clone https://github.com/stellar/soroban-dapps-challenge.git
cd soroban-dapps-challenge
git checkout payment
yarn

Checkpoint 2: 🎬 Deploy Smart Contracts​

For this step you will need to clone and deploy the Soroban token smart contract from the Soroban Examples repository. This Soroban token smart contract, broken into several smaller modules (as is the custom for complex smart contracts like this one), enables you to create and manage tokens on Soroban.

The Soroban token is a custom token that will be used to facilitate payments in the Payment Dapp. Tokens are essentially programmable assets on a blockchain, and smart contracts provide the automation and rules for these tokens. They allow for predefined conditions and actions related to the tokens, such as issuance, transfer, and more complex functions, ensuring the execution of these operations without the need for intermediaries. In the case of this Payment Dapp, you will use the Soroban token to initialize and mint "Demo Token" assets, or DT, that you can then use to make payments via the Payment Dapp.

In a new terminal window, follow the steps below to build and deploy the token smart contract:

git clone https://github.com/stellar/soroban-examples.git
cd soroban-examples/token
make

This will build the smart contracts and put them in the token/target/wasm32-unknown-unknown/release directory.

Next, you will need to deploy the token smart contract to Futurenet. In order to deploy to future, you will need a Stellar account keypair (a public key and its corresponding secret key). Keep in mind that Freighter, where you can create and view your account's public key, intentionally does not allow you or any application to access your secret key. It's recommended therefore to generate a new Futurenet keypair using Stellar Lab, fund the account, and then import the keypair's public key into your Freighter wallet.

Once you have done this and are ready to deploy the token smart contract to Futurenet, open a terminal in the soroban-examples/token directory and follow the steps below:

soroban contract deploy \
    --wasm target/wasm32-unknown-unknown/release/soroban_token_contract.wasm \
    --source <ADMIN_ACCOUNT_SECRET_KEY> \
    --rpc-url https://rpc-futurenet.stellar.org:443 \
    --network-passphrase 'Test SDF Future Network ; October 2022'

Deploying the token contract to Futurenet will return a contract ID that you will need to use in the next step to invoke the token smart contract and initialize the Soroban token as "Demo Token":

soroban contract invoke \
    --id <TOKEN_CONTRACT_ID> \
    --source-account <ADMIN_ACCOUNT_SECRET_KEY> \
    --rpc-url https://rpc-futurenet.stellar.org:443 \
    --network-passphrase 'Test SDF Future Network ; October 2022' \
    -- initialize \
    --admin <ADMIN_PUBLIC_KEY> \
    --decimal 7 \
    --name "Demo Token" \
    --symbol "DT"

Lets take a look at what is happening here:

• admin: This is the public key of the administrator account and corresponds to the secret key you used to deploy the contract in the previous step. It is the "master" account that has control over the token contract.

• decimal: This decimal precision value is set to 7. This value indicates that your token will have 7 decimal places, providing fine-grained control and flexibility in transactions.

• name: This value is set to "Demo Token," the name of your token written as a string.

• symbol: Your token symbol is a short string that represents your token, in this case, "DT."

Next, you will need to mint some tokens to your sender's account (the administrator account you used to deploy the contract and initialize the token above). To do this, run the following command:

soroban contract invoke \
    --id <TOKEN_CONTRACT_ID> \
    --source-account <ADMIN_ACCOUNT_SECRET_KEY> \
    --rpc-url https://rpc-futurenet.stellar.org:443 \
    --network-passphrase 'Test SDF Future Network ; October 2022' \
    -- mint \
    --to <USER_PUBLIC_KEY> \
    --amount 1000000000

This will mint 100 DT tokens to the to address. You can check any address' balance by running the following command:

soroban contract invoke \
    --id <TOKEN_CONTRACT_ID> \
    --source-account <ADMIN_ACCOUNT_SECRET_KEY> \
    --rpc-url https://rpc-futurenet.stellar.org:443 \
    --network-passphrase 'Test SDF Future Network ; October 2022' \
    -- balance \
    --id <ANY_PUBLIC_KEY>

Checkpoint 3: 🖥️ Launch the Frontend​

In this checkpoint, you will make sure that the frontend of the Payment Dapp successfully communicates with the backend, allowing transactions to be created, signed, and submitted to the network.

Open a terminal in the soroban-dapps-challenge directory and run the following command to launch the frontend of your dapp:

yarn start

You should see the following output:

$ webpack-dev-server --config config/webpack.dev.js
<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] Loopback: http://localhost:9000/
...

Now open your browser and navigate to http://localhost:9000. You should see the Payment Dapp running in your browser.

Checkpoint 4: 🚀 Token Transfer Odyssey​

Strap in and get ready to send some tokens! In this step, you will use the Payment Dapp to send Soroban tokens to another account.

• 📡 Add Token to Freighter
• 🏦 Send Tokens

• Connect
• Add
• Check

Checkpoint 5: 🚢 Ship it! 🚁​

In this step, you will deploy your dapp to a hosting platform so that it can be accessed by anyone with an internet connection. You can use any hosting platform you like, but for demonstration purposes, this section will use Vercel. Vercel is a cloud platform for static sites and serverless functions that offers a free tier for developers. It also has a built-in integration with GitHub, which makes it easy to deploy your dapp directly from your GitHub repository.

If you dont already have a Vercel account, you will need to create one and link it to your GitHub account.

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

Next, you will need to create a new project on vercel. To do this, run the following command:

vercel project add <PROJECT_NAME>

For example:

vercel project add soroban-react-payment

Next you will pull in the project settings locally by running the following command:

vercel pull

Follow the answers to the prompts below to ensure that your local project is correctly linked to the target 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] y
? What’s the name of your existing project? <PROJECT_NAME>

After following the prompts, you should see something similar to the following output:

...
🔗  Linked to julian-dev28/pmt-dapp (created .vercel)
> Downloading `development` Environment Variables for Project pmt-dapp
✅  Created .vercel/.env.development.local file  [92ms]

> Downloading project settings
✅  Downloaded project settings to ~/Documents/GitHub/test/soroban-dapps-challenge/.vercel/project.json [1ms]

Next, you will need to edit the settings section in .vercel/project.json to ensure that the outputDirectory is set to build:

  "settings": {
    "createdAt": 1699390700432,
    "framework": null,
    "devCommand": null,
    "installCommand": null,
    "buildCommand": null,
-   "outputDirectory": null,
+   "outputDirectory": "build",
    "rootDirectory": null,
    "directoryListing": false,
    "nodeVersion": "18.x"
  }

Next, run the following command to build your dapp:

vercel build --prod

What does the vercel build command do? It builds your dapp for production, which means that it optimizes your code for performance and creates an optimized production build of your dapp in the .vercel/output directory. This is the directory that you will deploy to Vercel.

The output of the vercel build command should look something like this:

..
$ webpack --config config/webpack.prod.js
asset 8a7edf3024865247d470.js 1.73 MiB [emitted] [immutable] [minimized] (name: index) 1 related asset
...
webpack compiled in 12408 ms (be8ba6cc95f4aec4d07b)
✨  Done in 13.16s.
✅  Build Completed in .vercel/output [14s]

Next, you will deploy your dapp to Vercel by running the following command:

vercel deploy --prebuilt --prod

Using the --prebuilt flag tells Vercel to deploy the the build outputs in .vercel/output that you created in the previous step.

Once the deployment is complete, you should see something similar to the following output:

🔍  Inspect: https://vercel.com/julian-dev28/soroban-react-payment/9PwV2DvuXJ3FWag7eLbjqNAhCeCu [2s]
✅  Production: https://soroban-react-payment-ahtko9qd1-julian-dev28.vercel.app [2s]

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 Stellar Lab, and follow the instructions to create your Freighter account on Futurenet.

Checkpoint 6: ✅ 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!

Checkpoint 7: 💪 Share Your Accomplishment with the Community​

Don't forget to share your work with the community. Let others see what you've accomplished, receive feedback, and inspire others!

⚔️ Side Quests​

🍴Fork the Example Soroban Payment Dapp repo and make your own changes to your Dapp.

Consider customizing the code and submitting a pull request for the challenge. You can explore advanced features of the Example Soroban Payment Dapp, and Freighter wallet to take your skills to the next level. Show your creativity by adding unique functionalities, enhancing the user interface, or integrating with other APIs or services. Good luck!

📚 User Workflows Checklist​

To ensure that you've covered all the key user actions during the challenge, follow this checklist:

• Clone the repository
• Install dependencies
• Deploy and initialize the token smart contract
• Mint tokens to your account
• Launch the local frontend
• Add the Soroban token to Freighter
• Connect Freighter to the application
• Send tokens to another account
• Deploy the site with Vercel
• Submit your public key and URL

🛡️🗡️ Take On More Challenges​

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