Skip to content

README.md

Latest commit

 

History

History
219 lines (168 loc) · 6.98 KB

README.md

File metadata and controls

219 lines (168 loc) · 6.98 KB
Raw

Scaffold Stellar

Apache 2.0 licensed Ask DeepWiki

Scaffold Stellar is a developer toolkit for building decentralized applications (dApps) and smart contracts on the Stellar blockchain.

It helps you go from idea to working full-stack dApp faster — by providing CLI tools, reusable contract templates, a smart contract registry, and a modern frontend.

Why Use Scaffold Stellar?

  • Simplifies blockchain dApp development
  • Generates smart contract projects and React UIs
  • Deploys smart contracts and manages versions
  • Easy to learn for newcomers; powerful for pros

What Is Stellar?

Stellar is a blockchain designed for fast, low-cost financial transactions and smart contracts written in Rust and compiled to WebAssembly (Wasm).

With Scaffold Stellar, you write smart contracts in Rust and interact with them using modern TypeScript + React tooling.

Prerequisites

Before you begin, make sure you have the following installed:

Tool Description Install Link
Rust & Cargo For writing and compiling smart contracts curl https://sh.rustup.rs -sSf | sh
Node.js & npm For frontend development Download from official site
Stellar CLI for building, deploying, and interacting with smart contracts Link for the repo

Quickstart (New Developers Welcome!)

This section walks you through setting up Scaffold Stellar from scratch.

1. Install the Scaffold Stellar CLI

cargo install stellar-scaffold-cli

The Scaffold Stellar CLI is installed as a plugin under the stellar CLI.

2. Create a New Project

stellar scaffold init my-project
cd my-project

3. Configure Your Environment

# Copy and configure environment variables
cp .env.example .env

Edit .env with your preferred network, secret keys, and other settings.

4. Install Frontend Dependencies

# Install Frontend dependencies
npm install

5. Start Development

npm run dev

You should see your React frontend at http://localhost:5173.

6. For testnet/mainnet deployment:

# First publish your contract to the registry
stellar registry publish

# Then deploy an instance with constructor parameters
stellar registry deploy \
  --deployed-name my-contract \
  --published-name my-contract \
  -- \
  --param1 value1
  
# Can access the help docs with --help
stellar registry deploy \
  --deployed-name my-contract \
  --published-name my-contract \
  -- \
  --help

# Install the deployed contract locally
stellar registry install my-contract

Project Layout

After scaffolding a project, your folder structure will look like this:

my-project/
├── contracts/            # Rust smart contracts (compiled to WASM)
├── packages/             # Auto-generated TypeScript contract clients
├── src/                  # React frontend code
│   ├── components/       # Reusable UI pieces
│   ├── contracts/        # Contract interaction logic
│   ├── App.tsx           # Main app component
│   └── main.tsx          # Entry point
├── environments.toml     # Configuration per environment (dev/test/prod)
├── .env                  # Local environment variables
├── package.json          # Frontend packages
├── target/               # Build outputs

This template provides a ready-to-use frontend application with example smart contracts and their TypeScript clients. You can use these as reference while building your own contracts and UI. The frontend is set up with Vite, React, and includes basic components for interacting with the contracts.

See the CLI Documentation for detailed command information and the Environments Guide for configuration details.

CLI Tools

Scaffold Stellar provides two main CLI tools:

stellar-scaffold Initialize and manage dApp projects:

stellar scaffold init my-project
stellar scaffold build

Manage contract deployment and versions:

stellar registry publish    # Publish contract to the registry
stellar registry deploy     # Deploy a contract instance
stellar registry install    # Install deployed contracts locally

Use --help on any command for usage instructions.

Smart Contract Deployment

  1. Publish Your Contract
stellar registry publish
  1. Deploy the Contract
stellar registry deploy \
  --deployed-name my-contract \
  --published-name my-contract \
  -- \
  --param1 value1
  1. Install the Deployed Contract
stellar registry install my-contract

You can deploy to testnet or mainnet depending on your .env and environments.toml.

Concept: What Is the Contract Registry?

The registry is an on-chain smart contract that lets you:

  • Publish and verify other contracts
  • Manage multiple versions
  • Reuse deployed contracts across dApps

This means your contracts can be upgraded, shared, and used like packages.

Project Structure (Top-Level)

Your repo contains the following key folders:

Folder Purpose
.cargo/, .config/ Rust and build settings
contracts/ Example smart contracts
crates/ Internal Rust libraries and helpers
docs/ Documentation files
npm/ Shared frontend packages
deploy_registry.sh Helper script to deploy the registry
justfile Commands you can run with just

Documentation

Additional Developer Resources

Contributing

We love contributions! If you’re new, check these out:

Contributing Guide

License

This project is licensed under the Apache-2.0 License — see the LICENSE file for details.

Need Help?

If you’re new to Stellar, Rust, or smart contracts:

Ask questions in the repo Discussions tab

Search DeepWiki

Or just open an issue — we're happy to help!

Happy hacking!