Skip to content

signing-strategy.md

Latest commit

 

History

History
65 lines (45 loc) · 4.36 KB

signing-strategy.md

File metadata and controls

65 lines (45 loc) · 4.36 KB
Raw

Signing Strategy

Caatinga does not store private keys or run silent signing. This document describes supported signing models, explicit out-of-scope patterns, and recommended testnet vs mainnet practices.

CLI signing (--source)

All state-changing CLI commands (deploy, upgrade, invoke, wire, regression, zk invoke) and estimate deploy require --source. read and smoke fall back to CAATINGA_SOURCE, then alice, but require --source (or CAATINGA_SOURCE) on mainnet:

  • Value: a local Stellar CLI identity alias (e.g. alice), not a public G... address or seed phrase.
  • Mechanism: Caatinga passes --source-account <alias> to Stellar CLI; the CLI loads the key from its local keystore.
  • Validation: CAATINGA_SOURCE_IS_PUBLIC_KEY, CAATINGA_SOURCE_IS_SECRET_KEY, and related codes reject unsafe shapes early.
stellar keys generate alice --fund --network testnet
ctg deploy counter --network testnet --source alice
ctg upgrade counter --network testnet --source alice   # admin-gated in-place WASM upgrade

Run ctg doctor --source alice to verify the identity exists in the local Stellar CLI keystore (stellar keys public-key alice). Doctor does not check funding or signing rights on the selected network.

Browser signing (@caatinga/client)

Browser flows use a wallet adapter — the wallet extension or Stellar Wallets Kit signs transactions:

  • Scope: single-invoker only. The connected wallet signs as the transaction source.
  • Not supported: delegated AddressV2 / non-invoker signAuthEntry orchestration. Contracts requiring multi-auth fail with CAATINGA_MULTI_AUTH_REQUIRED.
  • Adapters: Freighter, Stellar Wallets Kit (xBull, Albedo, Rabet, WalletConnect, etc.). Hardware wallets inside SWK are stubbed for bundle size — not registered in the default adapter.

See Wallets and Client — Single-invoker scope.

CI signing

Caatinga does not manage CI secrets. Recommended pattern:

  1. Generate a dedicated deployer identity on the runner or inject a secret-backed alias.
  2. Fund the identity on testnet (or use a platform secret for mainnet).
  3. Pass --source ci-deployer (or your alias) to ctg deploy / invoke.
  4. Commit updated caatinga.artifacts.json from the pipeline or store as a build artifact.

See Testing — CI without local secrets.

Testnet vs mainnet

Concern Testnet Mainnet
Identity stellar keys generate --fund Pre-funded account; never commit seeds
Source alias Dev alias (alice) acceptable Dedicated deployer alias per environment
ZK dev ceremony Allowed on testnet with warnings Blocked by default (CAATINGA_ZK_DEV_CEREMONY_BLOCKED)
Cost awareness Use ctg estimate deploy before large deploys Required — estimate fees; monitor resource limits
Artifact history Optional Use ctg migrate artifacts + upgrade/rollback workflow

Explicitly not supported

Model Status Notes
Hardware wallets (Ledger/Trezor) Not supported SWK stubs only; no native Ledger integration
KMS / cloud signing (AWS KMS, GCP) Out of scope Use Stellar CLI or custom signing outside Caatinga
Backend / server-side signing Out of scope Application responsibility
Multisig / signAuthEntry in client App-owned CAATINGA_MULTI_AUTH_REQUIRED — orchestrate in application code
Caatinga-managed key storage Never By design — see ADR 0002

Related docs