A script and a boilerplate

@create-soroban-dapp is both a npx script and a boilerplate dapp for kickstarting any of your ideas for a Soroban-based Dapp.

Largely inspired by the ink!athon project by Scio Labs and by @create-t3-app by T3 Open Source for the script mechanisms.

Check the LIVE VERSION of the dapp that is already utilizing a deployed testnet contract!

Structure

@create-soroban-dapp is composed of two things:

  • A boilerplate dapp utilizing the @soroban-react.

  • A npx script that allows developers to quickstart their project via the command line and npx create-soroban-dapp. Using the script will help them set up the boilerplate dapp.

Usage

Open a terminal in the folder of your choice and simply use:

npx create-soroban-dapp@latest

or

npm create soroban-dapp@latest

Then, navigate inside the new project directory:

cd projectname

Manual cloning

If you prefer to manually clone the repository instead of using the NPX script, follow these steps:

Clone the Repository

Clone the repository using the following command:

git clone git@github.com:paltalabs/create-soroban-dapp.git

The main project (dapp) will be located in a subfolder named soroban-react-dapp, not in the root directory. The root directory is occupied by the NPX script.

Navigate to the subfolder:

cd soroban-react-dapp

Install Dependencies

Inside the soroban-react-dapp folder, install the necessary dependencies. You can use Yarn, npm, or pnpm as per your preference:

yarn install or npm install or pnpm install

Important Note: When using this manual cloning technique, you will also clone the NPX script located in the root folder. This script will not be necessary for your manually cloned project. You can choose to keep only the soroban-react-dapp subfolder, which contains the actual Next.js project.

Troubleshooting

This script is still in its early stages of development and might not function perfectly on every operating system and configuration. If you encounter any issues, please report to devs@paltalabs.io

Set up your secrets!

When deploying our contracts, you will need the secret key of the deployer account. This secret key will be stored in an ignored file located at ./contracts/.env.

To set up your secrets, first copy the example environment file:

cp contracts/.env.example contracts/.env

If you are already inside the contracts folder (such as when using a Docker container), simply use:

cp .env.example .env

Next, edit the .env file and add your secret keys. The file will look like this:

# Stellar accounts Secret Keys
ADMIN_SECRET_KEY=

# RPC Setup
MAINNET_RPC_URL=

You can generate new Accounts and Private Keys from Stellar Laboratory

If you plan to deploy on the Mainnet, you will also need a Mainnet RPC Provider. Find one in Validation Cloud or Nownodes

Welcome to your soroban react dapp boilerplate!

This dapp largely inspired by the ink!athon project will help you kickstart your soroban dapp creator journey.

Dapp Screenshot

Getting started

If it's not done already, you will need first to run the create-soroban-dapp script.

If you prefer it is also possible to clone the boilerplate repo manually.

We now suppose you ran the initialization script and that you have a folder containing the soroban-dapp next.js project.

The customization of the dapp will be done following these steps:

Good luck building!

Verify Installation

Run the app on a local server

To verify that everything is in order, open a shell in the nextjs soroban-dapp folder, and run

# If you use yarn
yarn dev

# If you use npm or pnpm
npm run dev
pnpm run dev

This will start the development server. The dapp will be available on localhost.

The dapp should display the current greeting set in the testnet smart contract.

If you encounter an error, make sure you have installed the dependencies of the project!

Try the dapp

Connect your wallet and check if you can interact with the dapp by sending a new greeting!

You may need some tokens from the faucet to interact with the testnet.

You can fund your wallet address with the testnet friendbot at
https://friendbot.stellar.org/?addr=YOUR_ADDRESS_HERE

Customize app data

You can start by modifying the TODOs with your own data (None of them is mandatory to change):

Manage contracts

The soroban dapp boilerplate comes with an carefully thought contracts organization and scripts which will allow you to manage your contracts compiling, deployment and integration in a simple way.

To see the details and how to use it see

Contract folder organization

In the contracts folder you will find all the Rust contracts you are using for your dapp as well as the deploy scripts and the registry of all deployed contract in deployments.json:

contracts/
    contract1/
        src/
            lib.rs
            test.rs
        Cargo.toml
        Makefile
    contract2/
    ...
    scripts/
        deploy.ts
    utils/
    Makefile

You will also find some makefiles which are used in the deploy scripts to automatically recompile the contracts if they have been updated.

The contract folder is a typescript package in itself and its dependencies need to be installed in order to build the scripts.

Create and build your own contracts

The contracts workflow happens in the contracts/ folder. Here you can see that the greeting contract is present already.

Every new contract should be in its own folder, and the folder should be named the same name as the name of the contract in its cargo.toml file. You can check how the tweaked_greeting contract is changed from the greeting contract and you can also start from this to build your own contract.

To build the contracts you can simply invoke the make command which will recursively build all contracts by propagating the make command to subfolders. Each contract needs to have its own Makefile for this to work. The Makefile from the greeting contract is a generic one and can be copied and paste to use with any of your new contract.

If you are not familiar or comfortable with Makefiles you can simply go in the directory of the contract you want to compile and run

# This will create the target wasm blob under target/wasm32-unknown-unknown/release/contract_name.wasm
cargo build --target wasm32-unknown-unknown --release

If it's your first time manipulating soroban contracts you might need to add the wasm32-unknown-unknown target to rust. For this run rustup target add wasm32-unknown-unknown.
Follow instructions you find online if not working ( search for "add target wasm32-unknown-unknown to rust" ).

Deploy your contracts using the provided script

Now that you have added your contract to the project, you can deploy the contract to any network of your choice.

Add a deployer secret key in the .env file

First thing you need to do is to copy paste the .env.example file to create a .env file which will be used to retrieve the deployer secret key by the script. Just add any valid secret key to the .env file under the field ADMIN_SECRET_KEY.

Run the contract

Then we can use the script provided in the contracts folder: scripts/deploy.ts. The script is using stellar-js under the hood.

The contracts folder is a typescript package itself which needs to have its dependencies installed:

# From the contracts folder run
yarn
#
npm -i
#
pnpm -i

The script can then be called using yarn (or any package manager)

yarn deploy network_name contract_name_1 contract_name_2 ...

Replacing network_name by one of testnet|futurenet|standalone|mainnet and adding all the contracts name you want to deploy as next arguments.

For instance if I want to deploy the greeting contract on testnet I will run:

yarn deploy testnet greeting

Under the hood the script will

  • Load the pair provided in the .env for the deployer identity
  • Fund the deployer identity using Friendbot
  • Deploy the contracts on testnet
  • Add the contracts deployment infos in deployments.json

Retrieve the contract object in the frontend

Get the contract wrapper object using the useRegisteredContract hook:

In the file [GreeterContractInteraction.tsx], you can see an example of how to retreive the contract object in the front end:

You first need to import the useRegisteredContract hook in your page here:

import { useRegisteredContract } from '@soroban-react/contracts'

Then you have to call the hook with the name of the contract you want to fetch as a parameter:

const contract = useRegisteredContract("greeting")

The hook will fetch the contract directly in the deployments object passed to the context here and the values will correspond to the values in the deployments.json file updated automatically when the deploy scripts are called.

Contract wrapper object

The contract object has two fields, the deploymentInfo object and the invoke method:

contract
    .deploymentInfo (Object)
        .name
        .networkPassphrase
        .contractAddress
    .invoke (Method)

The deploymentInfo object

deploymentInfo is directly corresponding to the object you can see in the deployments.json, looking like the following:

{
    "contractId": "greeting",
    "networkPassphrase": "Test SDF Network ; September 2015",
    "contractAddress": "CDKU2ZVK2RV3JFPPNAVYHGHMSXD7RENEVMEPURNKEECM7FDVH7WHI7ZO"
}

The invoke method

The invoke method is a wrapper around the contractInvoke method from @soroban-react. It basically use the latter with some parameters computed from the deploymentInfo of the contract and the current context to simplify its calling.

The syntax to call a method of the contract object is as following:

const result = await contract?.invoke({
    method: 'set_title',
    args: [stringToScVal(newMessage)],
})

Where method is the name of the smart contract method you want to call and args the arguments the method expects converted into ScVal.

Fly with your own wings

You are now normally all set! This is your time to shine and show your mastery of Rust and React to build the best dapp!

The idea is for you to inspire yourself from the two methods implemented in the boilerplate (one getter, one setter) to now connect to your own smart contracts and craft the adequate frontend.

Wishing you good luck

SOROCHAT dapp tutorial

SOROCHAT is a nice little messaging dapp built using create-soroban-dapp for demonstration purpose.

SOROCHAT Preview

LIVE VERSION HERE 🕺

Submitted and awarded for the Sorobounties 2024.

Tutorial on Dev.to

You can find a written tutorial explaining how to create the dapp on dev.to 🚀