Skip to content

getting-started.md

Latest commit

 

History

History
143 lines (103 loc) · 6.18 KB

getting-started.md

File metadata and controls

143 lines (103 loc) · 6.18 KB
Raw

Getting Started

Caatinga alpha supports the CLI path first, then optional browser/client integration through @caatinga/client (single-invoker wallet signing until v1.0).

Install published packages from npm. Pin an exact version in apps when you need reproducibility.

Prerequisites

  • Node.js 22+
  • pnpm 9+ for repository development
  • Rust 1.84.0 or newer with the wasm32v1-none target.
  • Stellar CLI
  • A local Stellar CLI identity for CLI deploy/invoke, for example alice
  • Optional: Freighter or another wallet adapter for browser-side @caatinga/client calls

On a fresh machine, install everything above (except Node.js) in one step with caatinga setup — it detects what's missing and installs only that, then creates a funded local identity. See system dependencies for Linux when Stellar CLI must compile from source.

npx caatinga setup                 # installs Rust + wasm32v1-none + Stellar CLI, funds `alice` on testnet

See caatinga setup for flags and behavior. To verify an existing environment instead, run the dependency checks manually:

rustc --version
rustup target add wasm32v1-none
stellar --version

Install from npm

npm install -g @caatinga/cli

Without a global CLI install, use npx caatinga in the commands below.

From the repository

pnpm install
pnpm build
pnpm --filter @caatinga/cli dev init my-dapp

Choose your scaffold

Caatinga supports three starting paths: template (full dApp), minimal (CLI + contract only), and ZK (Circom + Groth16 verifier). See Choosing a project scaffold for a comparison table and links to step-by-step guides:

Guide Command
Template project npx caatinga init my-dapp
Minimal project npx caatinga init my-contract-app --minimal
ZK project npx caatinga zk init my-zk-dapp

The default template flow (react-vite-counter) is summarized below. Minimal and ZK flows are documented in their dedicated guides.

Generated app flow

After caatinga init (global CLI) or npx caatinga init:

cd my-dapp
npm install
npx caatinga build counter
npx caatinga deploy counter --network testnet --source alice
npx caatinga status --network testnet
npx caatinga invoke counter.increment --network testnet --source alice

For read-only calls (getters, pure queries), use read instead of invoke — it simulates without signing or submitting:

npx caatinga read counter.get --network testnet
npx caatinga read counter.count --network testnet --expect '{"matcher":"reachable"}'
npx caatinga smoke --network testnet --source alice   # checks from caatinga.config.ts smoke.reads

After deploy, caatinga smoke runs configured read checks with the same expect DSL as postDeploy. For CI, use caatinga regression (full pipeline) or caatinga ci run (doctor + smoke). See Cheatsheet — CI and regression and Testnet hygiene.

Run the CLI steps in order: build → deploy → invoke (or npm run dev / pnpm dev after deploy). deploy requires compiled WASM, writes the deployed contractId into caatinga.artifacts.json, and generates TypeScript bindings automatically (pass --no-generate to skip). status shows what's deployed and whether bindings are fresh.

build only compiles the WASM file. deploy is the step that writes the deployed contractId into caatinga.artifacts.json; browser clients and generated bindings need that contract ID before they can call the contract.

If bindings generation fails after a deploy (or you skipped it), recover with npx caatinga generate --network testnet.

Use a local Stellar CLI identity alias for --source. Public G... addresses, secret keys, and seed phrases are rejected because deploy and invoke need a signer.

Template projects support pnpm install as well as npm — see Templates — pnpm.

Browser client flow

Single-invoker only until v1.0: @caatinga/client wallet invoke supports one signing invoker. Multi-signer / signAuthEntry flows are application code today (CAATINGA_MULTI_AUTH_REQUIRED). See Client — Single-invoker scope.

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

npm install @caatinga/client @caatinga/core @creit.tech/stellar-wallets-kit

Register the generated bindings with @caatinga/client:

import { createCaatingaClient } from "@caatinga/client";
import { createStellarWalletsKitAdapter } from "@caatinga/client/stellar-wallets-kit";
import * as Counter from "./contracts/generated/counter";
import artifacts from "../caatinga.artifacts.json";

const client = createCaatingaClient({
  network: {
    name: "testnet",
    rpcUrl: "https://soroban-testnet.stellar.org",
    networkPassphrase: "Test SDF Network ; September 2015",
  },
  artifacts,
  wallet: createStellarWalletsKitAdapter(),
  contracts: { counter: { binding: Counter } },
});

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

For debugXdr, buildXdr(), the wallet adapter contract, and the full binding shape Caatinga expects, see Client. React apps can skip hand-rolled wallet state with WalletProvider/useWallet from @caatinga/client/react — see Wallets.

Default local checks:

pnpm typecheck
pnpm build
pnpm test

See client.md for the client contract and debug behavior. For CLI capability limits, see Supported today vs not yet.