Setup & Initial Workflow

This step-by-step guide walks you through the complete lifecycle of a new Soroban project scaffolded by Caatinga. Already have contracts? See Add to an Existing Project instead.

Step 1: Scaffold Project

Initialize a new project using the default react-vite-counter template:

npx ctg init my-dapp
cd my-dapp
npm install

Step 2: Health Check

Verify your toolchain and dependencies:

npx ctg doctor

Step 3: Build Smart Contracts

Compile the Rust contracts in contracts/:

npx ctg build

This compiles your contracts and generates .wasm binaries.

Step 4: Deploy to Testnet

Deploy your contracts using your configured network and Stellar identity:

npx ctg deploy --network testnet --source alice

Caatinga resolves dependencies, deploys the WASM binaries on-chain, and writes contract metadata to caatinga.artifacts.json. It also generates TypeScript bindings (skip with --no-generate) and, on a full-graph deploy, runs postDeploy wiring and writes the frontend .env.local.

Step 5: Generate Bindings & Invoke

Deploy already generated the bindings. Run generate yourself to regenerate them, or after deploy --no-generate:

npx ctg generate --network testnet

frontend: {
  bindingsOutput: "./src/contracts/generated"
}

Now invoke contract functions directly. The target is <contract>.<method>; contract arguments are passed as named flags (--<arg> <value>):

npx ctg invoke counter.increment --network testnet --source alice

Read the updated counter state (a simulation — no signing):

npx ctg read counter.get --network testnet