Caatinga — LLM Reference

Quick context: start at llms.txt for identity, mental model, boundaries, and doc routing. This file and llms-full.txt are the detailed reference.

Caatinga is Deployment Orchestration + Versioned Artifacts for Soroban: local, graph-aware deploy orchestration and portable, Git-versioned artifacts (caatinga.artifacts.json) for TypeScript teams. Build/deploy/invoke shell out to Stellar CLI; ctg generate runs npx @stellar/stellar-sdk generate.

Human docs: dione-b.github.io/caatinga. Authoritative command/API detail: CLI, Config, Client, Errors, Cheatsheet.

Install & release

Item	Value
npm dist-tag	`latest` → 3.9.0 (`@caatinga/cli`, `@caatinga/core`, `@caatinga/client`, `@caatinga/zk`)
Status	v1.0 stable contract on npm major `3.x`. Pin an exact version for reproducible installs.
Global install	`npm install -g @caatinga/cli` (binaries: `caatinga`, `ctg`)
No global install	`npx ctg <command>` (`caatinga` is a legacy alias)
Reproducible CI	Pin an exact version (e.g. `@caatinga/cli@3.9.0`), not a floating tag
Fresh machine	Node 22+, then check with `npx ctg doctor`. Install Rust, Stellar CLI manually.
Stellar CLI	Hard floor 23.0.0; last tested 27.0.0; newer = advisory warning only

See Public API and Stellar CLI version contract.

Capability limits

Capability	Status
Official frontend templates	Vite + React only (`vite-react`)
`ctg zk build`	Single-party dev ceremony; blocked on mainnet by default
`ctg zk invoke --embed-vk`	Not supported (experimental)
Browser `invoke` via wallet	Single-invoker only
Multi-signer / `signAuthEntry`	Application code → `CAATINGA_MULTI_AUTH_REQUIRED`
Production ZK (MPC ceremony)	Out of scope

1. Core Workflow

bash

npx ctg init my-dapp && cd my-dapp && npm install
npx ctg doctor --network testnet --source alice
npx ctg build counter
npx ctg deploy counter --network testnet --source alice
npx ctg invoke counter.increment --network testnet --source alice
npx ctg read counter.get --network testnet
npx ctg status --network testnet

Fresh machine: install Rust + Stellar CLI manually, then npx ctg doctor to verify. Full graph: npx ctg deploy --network testnet --source alice.

Strategy	Command	`contractId`
In-place	`ctg upgrade`	Preserved
Redeploy	`ctg deploy --upgrade`	New ID

Default react-vite-counter has no upgrade() — use deploy --upgrade for that template. See Contract upgrade and Cheatsheet.

2. Package Reference

Package	Role	Browser-safe
`@caatinga/cli`	CLI binary	No
`@caatinga/core`	Config, artifacts, Stellar CLI orchestration	No (`./browser` yes)
`@caatinga/client`	`createCaatingaClient`, wallet session, invoke/read/simulate/buildXdr	Yes
`@caatinga/client/react`	`WalletProvider` + `useWallet`	Yes
`@caatinga/client/vite`	SWK bundler stubs	Yes
`@caatinga/client/freighter`	Freighter adapter	Yes
`@caatinga/client/stellar-wallets-kit`	Multi-wallet adapter	Yes
`@caatinga/zk` / `@caatinga/zk/browser`	ZK helpers	browser subpath

3. CLI — agent-critical rules

Full flags and tables: CLI · Cheatsheet.

--source = local Stellar CLI identity alias (alice), never G... / S... / seed phrase.
deploy auto-generates bindings unless --no-generate.
Full graph deploy (no contract name) auto-runs wire + sync-env unless --no-wire / --no-sync-env.
doctor --strict = --strict-env + --strict-bindings only; deploy coverage never blocks exit code.
upgrade = in-place WASM (same contractId); deploy --upgrade = new instance + history.
status --strict fails when deployed contracts have bindings other than fresh.
Expect DSL (smoke / read --expect / postDeploy): reachable, equals, contains, matches, jsonEquals, isArray, isNull, minLength, maxLength — see CLI.

Core commands: init, zk init, build, deploy, upgrade, generate, doctor, status, invoke, read, smoke, regression, ci run, wire, sync-env, estimate deploy, inspect, migrate artifacts, rollback, zk build|prove|invoke. Binary alias: ctg ≡ caatinga.

4. Config & artifacts (summary)

Authoritative schema: Config. Minimal shape:

import { defineConfig } from "@caatinga/core";

export default defineConfig({
  project: "my-dapp",
  contracts: {
    counter: {
      path: "./contracts/counter",
      wasm: "./contracts/counter/target/wasm32v1-none/release/counter.wasm",
      dependsOn: ["token"], // optional
      deployArgs: { tokenContractId: "${contracts.token.contractId}" }, // optional
    },
  },
  networks: {
    testnet: {
      rpcUrl: "https://soroban-testnet.stellar.org",
      networkPassphrase: "Test SDF Network ; September 2015",
    },
  },
  frontend: {
    bindingsOutput: "./src/contracts/generated",
  },
});

Placeholders: ${contracts.<name>.contractId}, ${source.address}. Load-time validation requires dependsOn for every ${contracts.*.contractId} in deployArgs.

Artifacts (caatinga.artifacts.json): schema v2, git-versioned, per-network contractId + wasmHash + optional history. Migrate with ctg migrate artifacts. See artifacts-spec.

5. Client API (summary)

Full API: Client · Wallets.

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 } },
});

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

API	Signs?	Submits?
`read()`	No	No
`simulate()`	No	No
`invoke()`	Yes	Yes
`buildXdr()`	No	No

Wallet adapters must reject on user dismissal. React: WalletProvider / useWallet from @caatinga/client/react.

6. Error Codes

Automation must key on CAATINGA_* codes, never message text. Full catalog: Errors.

Code	Trigger
`CAATINGA_CONFIG_NOT_FOUND`	Missing `caatinga.config.ts`
`CAATINGA_STELLAR_CLI_NOT_FOUND`	`stellar` not on PATH
`CAATINGA_ARTIFACT_NOT_FOUND`	Missing artifacts / contract record
`CAATINGA_SOURCE_IS_PUBLIC_KEY`	`G...` passed as `--source`
`CAATINGA_SOURCE_IS_SECRET_KEY`	`S...` passed as `--source`
`CAATINGA_PLACEHOLDER_BINDING`	Scaffold bindings still in use
`CAATINGA_MULTI_AUTH_REQUIRED`	Multi-signer needed (app-owned)
`CAATINGA_ZK_DEV_CEREMONY_BLOCKED`	Dev ceremony on mainnet without allow flag
`CAATINGA_UNSUPPORTED_CLI_VERSION`	Stellar CLI below hard floor (23.0.0)

Advisory (non-fatal): STELLAR_CLI_UNTESTED_VERSION.

7. Key Gotchas & Rules

--source must be a CLI identity alias — never a G..., S..., or seed phrase.
Deploy auto-generates bindings — pass --no-generate to skip in CI.
Full graph deploy auto-runs wire + sync-env — pass --no-wire / --no-sync-env to skip.
Browser invoke is single-invoker only — multi-signer throws CAATINGA_MULTI_AUTH_REQUIRED.
ZK on mainnet is blocked by default — --allow-dev-ceremony is not for production.
Fresh machine — Node 22+, install Rust + Stellar CLI manually, then ctg doctor.
Errors are public API — parse CAATINGA_* codes, not message text.
read() vs invoke() — read = simulate (no sign), invoke = sign + submit.
Wallet adapters must reject on dismissal — never leave promise pending.
caatinga.artifacts.json is git-versioned — commit after deploy.
Binding freshness — fresh / stale / missing / unknown via .caatinga-bindings.json.
doctor deploy coverage is advisory — never blocks exit code.
Stellar CLI — hard floor 23.0.0, last tested 27.0.0.
ctg upgrade vs deploy --upgrade — in-place preserves contractId; redeploy creates a new instance.
Config graph validation — ${contracts.*.contractId} in deployArgs must be listed in dependsOn.
doctor --strict — env drift + stale bindings only.
Alias resolution — method args may use ${source.address} or CLI aliases (≥3 chars).

8. Templates

Template	Command	Description
`react-vite-counter` (default)	`ctg init <dir>`	Vite + React + counter + wallet stubs
`zk-starter`	`ctg zk init <dir>`	Circom multiplier + Groth16 verifier

bash

ctg init <dir> --minimal     # CLI-only
ctg zk init <dir> --minimal  # ZK-only

See Templates and Choosing a project scaffold.

9. Binding Freshness

State	Fix
`fresh`	—
`stale`	`ctg generate <name> --network <net>`
`missing`	`ctg generate`
`unknown`	Regenerate once

10. Project File Layout

my-dapp/
├── caatinga.config.ts
├── caatinga.artifacts.json
├── contracts/counter/
├── src/contracts/generated/counter/
├── src/caatinga.ts
└── package.json

11. Agent guidance

Working on a Caatinga project (generated app)

Run ctg doctor --network testnet --source alice before changing deploy state.
Order: build → deploy (or upgrade for in-place) → generate if needed → invoke / browser client.
Parse CAATINGA_* error codes, never message text.
--source = Stellar CLI identity alias only.
Browser wallet flows: single-invoker only.

Optional stellar-build agents: Integration guide.

Working on the Caatinga monorepo

Doc	Use when
AGENTS.md	Repo layout, build/test, version alignment
CONTRIBUTING.md	PR expectations, compatibility contracts
Architecture	Product stance
Errors	Full `CAATINGA_*` catalog
CLI	Authoritative command reference
Config	`caatinga.config.ts` schema
Contract upgrade	In-place vs redeploy

Monorepo: pnpm install --frozen-lockfile, pnpm build, pnpm test, pnpm dev <cli-args>.

Public contracts (do not break without migration note)

caatinga.artifacts.json schema
caatinga.config.ts shape
CaatingaErrorCode values
Published package exports (@caatinga/cli, client, core, zk)

Caatinga — LLM Reference ​

Install & release ​

Capability limits ​

1. Core Workflow ​

2. Package Reference ​

3. CLI — agent-critical rules ​

4. Config & artifacts (summary) ​

5. Client API (summary) ​

6. Error Codes ​

7. Key Gotchas & Rules ​

8. Templates ​

9. Binding Freshness ​

10. Project File Layout ​

11. Agent guidance ​

Working on a Caatinga project (generated app) ​

Working on the Caatinga monorepo ​

Public contracts (do not break without migration note) ​