Skip to content

getting-started.md

Latest commit

 

History

History
144 lines (103 loc) · 5.72 KB

getting-started.md

File metadata and controls

144 lines (103 loc) · 5.72 KB
Raw

Getting Started

Prerequisites

  • Node.js 22+
  • Rust 1.91.1+ with the wasm32v1-none target
  • Stellar CLI 23.0.0+ (28.0.0 recommended)
  • A local Stellar CLI identity for deploy/invoke (e.g. alice)
  • Optional: Freighter or Stellar Wallets Kit for browser @caatinga/client calls

On a fresh machine, run ctg doctor to check what is missing, then install prerequisites manually:

npx ctg doctor --network testnet --source alice

Manual install: Rust + rustup target add wasm32v1-none, Stellar CLI, and stellar keys generate alice --fund --network testnet. To verify: rustc --version, rustup target list --installed, stellar --version.

Install

npm install -g @caatinga/cli
ctg --help
caatinga --help   # legacy alias for ctg

Use npx ctg (or npx caatinga) instead of a global install if you prefer. Pin an exact version for reproducible installs — see Public API.

From the repository:

pnpm install && pnpm build
pnpm dev init my-dapp   # builds @caatinga/core first, then runs the CLI from source

Choose your scaffold

New to Caatinga? Start with the Template path — it scaffolds a complete dApp with Vite + React, wallet wiring, and a sample counter contract ready to build and deploy.

Guide Command Best for
Template project ⭐ npx ctg init my-dapp First Caatinga dApp — browser UI included
Minimal project npx ctg init my-contract-app --minimal Contract + CLI only; choose your UI stack later
ZK project npx ctg zk init my-zk-dapp Groth16 proofs on Soroban

See Choosing a project scaffold for a full comparison.

CLI loop

This section follows the Template scaffold (npx ctg init my-dapp), which generates a counter contract by default. If you used --minimal, your contract is named app — replace counter with app in the commands below.

1. Scaffold and install

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

2. Verify the environment

npx ctg doctor --network testnet --source alice

3. Build, deploy, and interact

# Compile the counter contract to WASM
npx ctg build counter

# Deploy to testnet — writes contractId to caatinga.artifacts.json
# and auto-generates TypeScript bindings (pass --no-generate to skip)
npx ctg deploy counter --network testnet --source alice

# Check what is deployed and whether bindings are fresh
npx ctg status --network testnet

# Read a value without signing (simulation)
npx ctg read counter.get --network testnet

# Call a state-changing method (requires signing)
npx ctg invoke counter.increment --network testnet --source alice

Command summary:

  • build — compiles WASM only
  • deploy — writes contractId to caatinga.artifacts.json and auto-generates bindings (pass --no-generate to skip)
  • read — simulate read-only methods without signing
  • invoke — state-changing calls from the CLI

Use --source with a local Stellar CLI identity alias, not a public G... address. If bindings generation fails: npx ctg generate --network testnet.

For CI: ctg smoke, ctg regression, or ctg ci run. See Cheatsheet.

Optional walkthrough: From Zero to Testnet — expected doctor output and testnet troubleshooting.

Browser client

Prerequisites: complete the CLI loop above — the contract must be deployed and bindings generated before this code runs. If you used the Template scaffold, the src/caatinga.ts file already contains this wiring. The snippet below is for reference or custom project setups.

After deploy, install client packages (match the CLI version when possible):

npm install @caatinga/client @caatinga/core @stellar/stellar-sdk @creit.tech/stellar-wallets-kit
import { createCaatingaClient } from "@caatinga/client";
import {
  createStellarWalletsKitAdapter,
  WalletNetwork,
} from "@caatinga/client/stellar-wallets-kit";
import type { CaatingaArtifacts } from "@caatinga/core/browser";
import * as Counter from "./contracts/generated/counter";
import artifactsJson from "../caatinga.artifacts.json";

const network = {
  name: "testnet",
  rpcUrl: "https://soroban-testnet.stellar.org",
  networkPassphrase: "Test SDF Network ; September 2015",
};

const client = createCaatingaClient({
  network,
  // JSON imports widen `version` to number; the cast restores the artifacts schema type.
  artifacts: artifactsJson as CaatingaArtifacts,
  wallet: createStellarWalletsKitAdapter({
    network: network.networkPassphrase as WalletNetwork,
  }),
  contracts: { counter: { binding: Counter } },
});

await client.contract("counter").read<number>("get");
await client.contract("counter").invoke<number>("increment");

The snippet hardcodes testnet for brevity. The Template scaffold reads the network from VITE_CAATINGA_NETWORK, VITE_CAATINGA_RPC_URL, and VITE_CAATINGA_NETWORK_PASSPHRASE, which ctg deploy and ctg sync-env write to .env.local, so the app follows the network you deployed to (see src/network.ts).

See Client and Wallets. React apps can use WalletProvider / useWallet from @caatinga/client/react.