Binding Freshness & Markers

Caatinga tracks whether generated TypeScript client bindings are synchronized with deployed contract artifacts using a .caatinga-bindings.json marker file stored inside each generated binding package.

Freshness States

State	Meaning	Resolution
`fresh`	Bindings match deployed `contractId` and `wasmHash` exactly	—
`stale`	Contract was redeployed or upgraded since last `ctg generate`	`ctg generate <name> --network <net>`
`missing`	No TypeScript bindings exist on disk	`ctg generate`
`unknown`	Bindings exist but predate freshness tracking markers	Regenerate once with `ctg generate`

If caatinga.config.ts has no frontend.bindingsOutput, freshness evaluation reports the project as unconfigured (a frontendUnconfigured flag alongside status) rather than missing — ctg generate cannot run at all in that state, and doctor/status no longer suggest running it until the field is set. See CAATINGA_INVALID_CONFIG for the exact snippet to add.

Freshness Marker Structure

Inside src/contracts/generated/<contract>/.caatinga-bindings.json:

{
  "contract": "counter",
  "network": "testnet",
  "contractId": "C...",
  "wasmHash": "...",
  "generatedAt": "2026-01-01T00:00:00.000Z"
}

Status Diagnostics

Run ctg status --strict in CI or locally to verify binding freshness across all deployed contracts:

npx ctg status --network testnet --strict

If any deployed contract has bindings other than fresh, ctg status --strict exits with code 1.