Package Reference

Caatinga is published as modular TypeScript npm packages under the @caatinga scope.

Release & Versioning Policy

• Latest release: 3.10.3 (all four packages ship in lockstep). 3.10.0 was versioned but never published to npm.
• Status: v1.0 stable contract on npm major 3.x. Breaking changes to the Tier 1 surface require a major bump and will land on an explicit 4.0.0. ZK commands (ctg zk *) are experimental and outside the contract.
• Reproducible CI: Pin an exact version (e.g. @caatinga/cli@3.10.3) rather than floating tags.
• Stellar CLI Compatibility: Hard floor 23.0.0; last tested 28.0.0.
• @caatinga/cli dependency ranges: @caatinga/core and @caatinga/zk ^3.10.3 or later, kept aligned with the release group.

3.10.3 highlights

Recommended for anyone targeting mainnet: with the default mainnet config, 3.10.2 and earlier could not reach mainnet at all.

• Mainnet commands use the configured RPC: configs matching the well-known mainnet network were passed to the Stellar CLI as --network mainnet, whose built-in entry has no RPC URL, so commands failed with Invalid URL Bring Your Own: … (or silently used a locally added mainnet network). Mainnet now always gets explicit --rpc-url / --network-passphrase from caatinga.config.ts.
• No implicit alice on mainnet: ctg read and ctg smoke require --source or CAATINGA_SOURCE on mainnet; otherwise they fail with CAATINGA_SOURCE_ACCOUNT_REQUIRED. Testnet still falls back to alice.
• ZK dev-ceremony block detects mainnet by passphrase: a mainnet network with a custom name (e.g. pubnet) is now blocked too.

3.10.2 highlights

• ctg doctor rejects Rust toolchains that stellar contract build refuses: the 1.81.x, 1.82.x and 1.83.x lines and exactly 1.91.0 now fail the Rust check with rustup update stable as the fix (3.10.1 reported 1.91.0 as OK).
• RUST_MIN_VERSION is 1.91.1; the blocked list is exported as RUST_BLOCKED_VERSIONS from @caatinga/core/runtime/requirements.
• Scaffolds, templates and examples declare rust-version = "1.91.1".

3.10.1 highlights

• Mainnet always requires confirmation: requireConfirmation: false is ignored on mainnet (detected by name or by the public network passphrase). Unattended runs must pass --yes or set CAATINGA_ASSUME_YES=true; the [MAINNET GUARDRAIL] audit log is still printed. The prompt now covers deploy, upgrade, invoke, wire, rollback, regression and ZK invoke, shows the target deployment, and automatic retries are disabled on mainnet.
• ctg doctor checks the Rust version: toolchains older than 1.91.0 fail the Rust check with rustup update stable as the fix. Rust 1.91.0 itself is rejected by stellar contract build; 3.10.2 makes doctor flag it.
• ctg doctor / ctg version update advisory: an informational note when the installed CLI is ahead of or behind the npm latest tag. It never fails a command; set CAATINGA_SKIP_UPDATE_CHECK=1 to skip it.
• ctg upgrade writes a relative sourcePath to caatinga.artifacts.json, matching ctg deploy. Entries written by earlier upgrades keep their absolute path until the next upgrade or deploy.
• Stricter artifacts schema: malformed contractId / wasmHash values in caatinga.artifacts.json are rejected.
• Bounded calls: subprocess and network calls (including the Horizon lookup in deploy recovery) now time out instead of hanging.
• Stellar CLI 28.0.0 is the new last-tested version; contracts, examples and templates use soroban-sdk 27.0.6.

3.9.2 highlights

• Security fix: identity export/import no longer leave a leftover tarball of Stellar secret keys in os.tmpdir(). See CLI Identity Reference for the remediation steps if you ran either command before upgrading.
• Security fix: identity import now rejects a tarball if any entry would extract outside the target Stellar config directory (tar path traversal). Only import archives from a trusted source.
• Security fix: the ZK toolchain now verifies every circom binary — freshly downloaded or read from the ~/.caatinga/zk-tools cache — against a pinned SHA-256 before use, deleting and rejecting it (ZK_CHECKSUM_MISMATCH) on a mismatch instead of running an unverified binary. See Errors reference.
• Smaller install: the published @caatinga/cli tarball dropped from 95.3 MB packed / 283.7 MB unpacked to 67.4 kB — the Rust target/ build directory and test_snapshots are now excluded from what gets published.
• sync-env no longer wipes unrelated variables in the target env file; concurrent deploy/upgrade no longer race on caatinga.artifacts.json; deploy retries when the RPC hasn’t indexed a just-uploaded WASM yet. See Gotchas for the full list.