Caatinga v3.12.0

Caatinga v3.12.0

Status

Stable minor release on top of 3.10.3. 3.11.0 was tagged but never published to npm, so this is the first npm release that ships the 3.11.0 changes as well — upgrading from 3.10.3 picks up both. Minor because @caatinga/client adds public API (wallet-less reads).

Packages

• @caatinga/cli@3.12.0
• @caatinga/core@3.12.0
• @caatinga/client@3.12.0
• @caatinga/zk@3.12.0

npm install -g @caatinga/cli@latest

Compatibility

• Node.js 22+
• Stellar CLI minimum 23.0.0, last tested 28.0.0
• Rust 1.91.1+ with the wasm32v1-none target (not 1.91.0)
• @stellar/stellar-sdk ^16.0.1 (templates)

New

• Reads without a wallet. read() and simulate() no longer need a connected wallet, and CaatingaClientConfig.wallet is optional (it is still required for invoke()). The simulation source account is, in order: the per-call sourceAccount option, the connected wallet's public key, readSourceAccount from the client config, then the exported DEFAULT_READ_SOURCE_ACCOUNT (the Stellar null account, never sent to RPC). Invalid source values throw CAATINGA_INVALID_CONFIG. (#239, #270)
• Network origin in every command. Commands print Network: <name> (config) or (flag) up front, so it is clear which network a run targeted. (#244, #269)

Fixes

• ctg wire with only postDeployRead hooks. ctg wire printed "No postDeploy hooks configured" and ran nothing, and full-graph ctg deploy skipped wiring unless a postDeploy array existed. Both now run when either list has hooks. (#243, #286)
• New projects start on artifacts schema v2. The react-vite-counter and zk-starter templates shipped "version": 1, so template projects stayed on v1 until their first upgrade or redeploy. Templates now ship v2, and scaffolding migrates any template that still ships v1 (for example a custom one via CAATINGA_TEMPLATES_DIR). Existing projects are not touched. (#280, #287)
• walletStubPnpmWorkspaceYaml() works on pnpm 9. Its output now starts with packages: []; without it pnpm 9 aborted with "packages field missing or empty" in standalone apps. (#279, #284)
• ctg inspect shows why a contract is unreachable. The on-chain detail now includes the Stellar CLI diagnostics when the probe fails. (#272)
• Deploy recovery on custom networks. Recovery no longer masks CAATINGA_DEPLOY_FAILED with CAATINGA_NETWORK_NOT_FOUND on networks without a Horizon mapping. (#234, #271)
• Inspection paths. Contract inspection falls back to the configured WASM path when the artifact path is missing; inspectContract().localWasm.path reports the absolute path that was hashed. (#249)
• Help text. ctg status --strict and ctg doctor --strict-bindings now say they fail on any binding status other than fresh (stale, missing, or unknown). Behavior unchanged. (#281, #285)

Also in this release (from 3.11.0)

See the v3.11.0 notes for details: clean ctg identity export stdout, a working ctg estimate deploy on the selected network, ctg ci run in user projects, Freighter v4 error handling, templates that follow the deployed network via VITE_CAATINGA_*, the new CAATINGA_WALLET_NETWORK_MISMATCH, and the frontend.env network source key.

Behavior changes

• An empty --network "" (for example --network "$NET" with $NET unset in CI) now fails with CAATINGA_NETWORK_NOT_FOUND instead of silently using defaultNetwork.
• Projects with only postDeployRead hooks now have them run by full-graph ctg deploy (skip with --no-wire) and by ctg wire.
• ctg init / ctg zk init write caatinga.artifacts.json with "version": 2.

Known issue

• ctg doctor prints a STELLAR_SDK_UNTESTED_VERSION advisory in new projects, because ^16.0.1 resolves to 16.3.x while the last-tested version is still 16.0.1. It is informational and does not block; a patch will raise the last-tested version.

Full changelog: v3.10.3...v3.12.0

Caatinga v3.11.0

Not published to npm. 3.11.0 was tagged but never released to the registry (npm went from 3.10.3 to 3.12.0). Its changes ship in v3.12.0 — install that instead.

Caatinga v3.11.0

Status

Stable minor release on top of 3.10.3. Closes the remaining mainnet-blocker (P0) items of the mainnet-readiness audit (#245); P1/P2 items are still tracked there.

Packages

• @caatinga/cli@3.11.0
• @caatinga/core@3.11.0
• @caatinga/client@3.11.0
• @caatinga/zk@3.11.0

npm install -g @caatinga/cli@latest

Compatibility

• Node.js 22+
• Stellar CLI minimum 23.0.0, last tested 28.0.0
• Rust 1.91.1+ with the wasm32v1-none target (not 1.91.0)

Fixes

• ctg identity export output is a clean archive. Status lines went to stdout, so ctg identity export > id.b64 produced a file ctg identity import could not decode. Only the base64 archive is written to stdout now; status goes to stderr. (#227)
• ctg estimate deploy works and uses the selected network. Simulation ran without network args, and fees were parsed with regexes that never matched the real stellar tx simulate output (a base64 envelope), so no estimate was ever produced. It now simulates on the chosen network and reads fees from the decoded envelope: resource = resource_fee, inclusion = fee - resource_fee. The WASM must already be uploaded on the target network. (#225)
• ctg ci run works in user projects. It spawned ./dist/index.js and pnpm dev, which exist only inside the Caatinga monorepo. Each step now re-runs the installed ctg; a failing step stops the recipe and its exit code is propagated, with no silent retry. (#232)
• Freighter adapter handles freighter-api v4 errors. v4 resolves with { error } and an empty address/XDR instead of throwing. A locked or not-allowed Freighter now raises CAATINGA_WALLET_NOT_CONNECTED, and a rejected or failed signature raises CAATINGA_XDR_SIGN_FAILED, both with Freighter's message. (#231)
• Templates follow the deployed network. react-vite-counter and zk-starter were hardwired to testnet (RPC, passphrase, wallet network, artifacts key). They now read VITE_CAATINGA_NETWORK, VITE_CAATINGA_RPC_URL and VITE_CAATINGA_NETWORK_PASSPHRASE, which ctg deploy / ctg sync-env write to .env.local. Without them the app uses testnet, as before. (#229)

New

• CAATINGA_WALLET_NETWORK_MISMATCH. Wallet adapters may implement an optional getNetworkPassphrase(). When the wallet reports a different network than the app, invoke() fails before building or signing, instead of a generic sign/submit error later. The Freighter and Stellar Wallets Kit adapters implement it; wallets that cannot report their network are not blocked. (#230)
• frontend.env accepts a network source key, written as the resolved network name by ctg sync-env / ctg deploy. (#229)

Behavior changes

• Apps using the Freighter adapter get a typed error from getPublicKey() / signTransaction() where they previously got "".
• invoke() can now throw CAATINGA_WALLET_NETWORK_MISMATCH with adapters that report their network.
• Package homepage now points to https://caatinga.xyz.

Full changelog: v3.10.3...v3.11.0

Caatinga v3.10.3

Caatinga v3.10.3

Status

Stable patch release on top of 3.10.2. Recommended for anyone targeting mainnet: with the default mainnet config, 3.10.2 and earlier could not reach mainnet at all.

Packages

• @caatinga/cli@3.10.3
• @caatinga/core@3.10.3
• @caatinga/client@3.10.3
• @caatinga/zk@3.10.3

npm install -g @caatinga/cli@latest

Compatibility

• Node.js 22+
• Stellar CLI minimum 23.0.0, last tested 28.0.0
• Rust 1.91.1+ with the wasm32v1-none target (not 1.91.0)

Fixes

• Mainnet commands use the configured RPC. A config matching the well-known mainnet network (https://mainnet.sorobanrpc.com + the public passphrase, the scaffold default) was passed to the Stellar CLI as --network mainnet. The CLI's built-in mainnet entry has no RPC URL ("Bring Your Own"), so read, invoke, deploy, upgrade and related 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; testnet keeps the --network testnet shorthand. (#224)
• No implicit alice on mainnet. ctg read and ctg smoke no longer fall back to the built-in alice identity on mainnet (detected by name or passphrase). Pass --source <alias> or set CAATINGA_SOURCE; otherwise CAATINGA_SOURCE_ACCOUNT_REQUIRED is raised. Testnet keeps the alice fallback. (#226)
• ZK dev-ceremony block detects mainnet by passphrase. ctg zk build, ctg zk invoke and verifier ctg deploy now block single-party dev-ceremony artifacts on mainnet networks with a custom name (e.g. pubnet), not only on a network literally named mainnet. (#228)

Behavior change

• ctg read / ctg smoke against mainnet now require an explicit source identity.

API additions (backward-compatible)

• describeCliSource(explicit, { network }) / resolveCliSource(explicit, { network }) accept an optional target network.
• isProductionNetwork(name, config?) and assertDevCeremonyAllowed({ networkConfig }) in @caatinga/zk accept an optional network config.

Full changelog: v3.10.2...v3.10.3

Caatinga v3.10.2

Caatinga v3.10.2

Status

Stable patch release on top of 3.10.1.

Packages

• @caatinga/cli@3.10.2
• @caatinga/core@3.10.2
• @caatinga/client@3.10.2
• @caatinga/zk@3.10.2

npm install -g @caatinga/cli@latest

Compatibility

• Node.js 22+
• Stellar CLI minimum 23.0.0, last tested 28.0.0
• Rust 1.91.1+ with the wasm32v1-none target. Do not use 1.91.0.

Fixes

• ctg doctor rejects Rust toolchains that stellar contract build refuses. Stellar CLI fails with use a rust version other than 1.81, 1.82, 1.83 or 1.91.0, but 3.10.1 reported Rust 1.91.0 as OK because it matched the minimum. doctor now fails the 1.81.x, 1.82.x and 1.83.x lines and exactly 1.91.0 with rustup update stable as the fix. (#256)
• RUST_MIN_VERSION is raised to 1.91.1, and the blocked list is exported as RUST_BLOCKED_VERSIONS from @caatinga/core/runtime/requirements.
• Scaffolds, templates and examples declare rust-version = "1.91.1".

If ctg build fails with the message above, run rustup update stable and check rustc --version.

Full changelog: v3.10.1...v3.10.2

Caatinga v3.10.1

Caatinga v3.10.1

Status

Stable release. Supersedes 3.10.0, which was versioned but never published to npm. This release ships everything since 3.9.2, focused on mainnet readiness: stricter mainnet guardrails, safer identity imports, bounded network/subprocess calls, and more honest error reporting.

Packages

• @caatinga/cli@3.10.1
• @caatinga/core@3.10.1
• @caatinga/client@3.10.1
• @caatinga/zk@3.10.1

npm install -g @caatinga/cli@latest

Compatibility

• Node.js 22+
• Stellar CLI minimum 23.0.0, last tested 28.0.0
• Rust 1.91.0+ with the wasm32v1-none target (now checked by ctg doctor)
• Contracts, examples and templates on soroban-sdk 27.0.6

Behavior changes to note

• Mainnet always requires confirmation. requireConfirmation: false is now ignored on mainnet (detected by name or by the public network passphrase). Unattended mainnet runs must pass --yes or set CAATINGA_ASSUME_YES=true; the [MAINNET GUARDRAIL] audit log is still emitted. (#250, B18)
• Mainnet confirmation covers more commands. deploy, upgrade, invoke, wire, rollback, regression runs and ZK invoke prompt on mainnet, the banner shows the target deployment, and automatic retries are disabled on mainnet. (#138)
• ctg doctor fails for Rust older than 1.91.0, with rustup update stable as the fix. (#251)
• ctg upgrade writes a relative sourcePath into caatinga.artifacts.json, matching ctg deploy. Artifacts written by earlier upgrades keep their absolute path until the next upgrade or deploy. (#253, #235)
• Artifacts schema validates contractId / wasmHash format. Malformed values in caatinga.artifacts.json are now rejected. (#170, #135)
• read / invoke no longer treat bare-word String arguments as identity aliases. (#206)

Added

• ctg doctor and ctg version report when the installed CLI is ahead of or behind the npm latest tag. Never fails a command; honors CAATINGA_SKIP_UPDATE_CHECK=1. (#205, #106)
• Subprocess and network calls are bounded by timeouts, including the Horizon lookup in deploy recovery. (#145)
• Stellar CLI checks and feature probes are memoized.

Fixes

Security

• Prevent tar path traversal on identity import and harden identity archive imports. (#162)
• Refuse unverified circom downloads.
• Harden Stellar CLI argument validation. (#204)

Core

• Refuse to guess the contract ID when deploy output is ambiguous.
• Classify artifacts-lock timeouts and self-heal stale locks.
• Take the already-deployed skip before dependency verification and argument resolution.
• Guard deploy/upgrade transient-retry callbacks. (#151)
• Preserve the export prefix when rewriting managed .env lines. (#153)
• Report unavailable deploy fee estimates honestly. (#160)
• Preserve unmapped ZK error codes.
• Key invoke hints and deploy recovery off a single signing-failure pattern. (#209)
• Derive placeholder and expect-matcher validation from their Zod definitions. (#208)
• Hygiene fixes: stderr warnings, history metadata, PATH precedence, sequential generates. (#207)
• The @caatinga/core/runtime/requirements entry point no longer pulls in node:crypto / node:fs. (#251)

Client

• Treat RPC ERROR as failed and report transaction lifecycle status.
• Submit the prepared transaction from the XDR build.

CLI

• Standardize next-step output on the canonical ctg binary.

Thanks

Thanks to everyone who contributed fixes in this release, including @Yasir-TechGuy (#250) and @fastcharger2000 (#251).

Full changelog: @caatinga/cli@3.9.2...v3.10.1

Caatinga v2.0.0-alpha.0

Caatinga v2.0.0-alpha.0

Status

Alpha major release. Breaking changes on the Stellar CLI compatibility surface and removed override APIs.

Packages

• @caatinga/cli@2.0.0
• @caatinga/core@2.0.0
• @caatinga/client@2.0.0

Install channel:

npm install -g @caatinga/cli@next

Compatibility

• Node.js 20+
• Stellar CLI minimum 23.0.0 (hard failure below)
• Stellar CLI last tested 25.2.0 (advisory above; no override flag required)
• Rust 1.84+ with wasm32v1-none target

Breaking changes

• Removed STELLAR_CLI_TESTED_MAX_VERSION; use advisory STELLAR_CLI_LAST_TESTED_VERSION.
• Removed assertSupportedStellarCliVersion; use evaluateStellarCliCompatibility.
• Removed CAATINGA_UNTESTED_CLI_VERSION error code.
• Removed --allow-untested-stellar-cli from build, deploy, generate, invoke, and doctor.
• Removed allowUntestedStellarCli from core command options.

Added

• evaluateStellarCliCompatibility() returning CompatibilityReport with warnings[].
• checkStellarCliVersion() export from @caatinga/core.
• Diagnostic.warnings on caatinga doctor (e.g. STELLAR_CLI_UNTESTED_VERSION).

Migration

Remove --allow-untested-stellar-cli if you used it locally — newer Stellar CLI versions now run with a non-fatal advisory. For CI gating on CLI version, rely on CAATINGA_UNSUPPORTED_CLI_VERSION (hard floor only).

Highlights

• Feature-aware Stellar CLI compatibility (hard floor + advisory last-tested)
• Template init no longer copies local target/ build artifacts
• Architecture overview docs in docs/architecture.md

Known limitations

• Alpha stability; APIs and artifact formats may still change before v1.
• No automated npm/GitHub release pipeline yet — publish remains operator-controlled.

Caatinga v0.2.1-alpha.0

Caatinga v0.2.1-alpha.0

Status

Alpha. APIs, config format, artifacts format and package exports may change before v1.

Packages

• @caatinga/cli@0.2.1
• @caatinga/core@0.2.1
• @caatinga/client@0.2.1

Compatibility

• Node.js 20+
• Stellar CLI 23.0.0–25.2.0
• Rust 1.84+
• wasm32v1-none target

Highlights

• CLI flow: init, build, deploy, generate and invoke
• Network-scoped artifacts
• TypeScript client package
• Browser integration example
• Documented CAATINGA_* error codes

Known limitations

• Alpha stability
• No default mainnet automation
• No multisig flow
• No backend signing abstraction
• No official React hooks yet