Skip to content

contract-upgrade.md

Latest commit

 

History

History
131 lines (94 loc) · 4.87 KB

contract-upgrade.md

File metadata and controls

131 lines (94 loc) · 4.87 KB
Raw

Contract Upgrade

Caatinga supports two upgrade strategies. Choose based on whether your contract implements an admin-gated upgrade(new_wasm_hash) entrypoint.

Strategy Command On-chain effect contractId
In-place ctg upgrade Replaces WASM on the existing instance Preserved
Redeploy ctg deploy --upgrade Deploys a new instance New ID

In-place upgrade (admin-gated contracts)

Use when the contract calls env.deployer().update_current_contract_wasm() behind admin auth (for example stellar-album-style upgrade() helpers).

# Build, upload WASM, invoke upgrade(), update artifacts (same contractId)
ctg upgrade sticker --network testnet --source deployer

# Skip when local WASM hash already matches artifacts
ctg upgrade sticker --if-changed --source deployer --network testnet

# Optional: regenerate bindings and sync frontend env
ctg upgrade sticker --source deployer --network testnet --generate --sync-env

# Fail early if local WASM hash does not match an expected value
ctg upgrade sticker --source deployer --expected-hash abc123... --network testnet

Requirements:

  • Contract already deployed (caatinga.artifacts.json has a contractId)
  • Contract exposes upgrade(new_wasm_hash) (Caatinga default; admin must authorize)
  • --source must be the admin identity that can sign the upgrade transaction

Artifact history records prior WASM hashes with the same contractId and upgradeType: "in-place". Rollback to a prior WASM hash via ctg rollback is not supported for in-place history yet — rebuild from git and run ctg upgrade again.

Redeploy upgrade (new contract instance)

Use when the contract has no in-place upgrade entrypoint, or when you intentionally migrate to a new instance.

# 1. Build new WASM
ctg build my-contract

# 2. Estimate fees (advisory)
ctg estimate deploy my-contract --network testnet --source alice

# 3. Redeploy with upgrade history
ctg deploy my-contract --network testnet --source alice --upgrade

# 4. Verify state
ctg inspect my-contract --network testnet
ctg status --network testnet

deploy --upgrade is a semantic alias for --force that records the prior contractId in artifact history (schema v2). It does not call upgrade() on the existing contract.

Artifact history

After the first --upgrade or --force redeploy on a v1 artifacts file, Caatinga bumps the file to schema v2 and appends history entries:

{
  "version": 2,
  "networks": {
    "testnet": {
      "contracts": {
        "counter": {
          "contractId": "CNEW...",
          "upgradeStrategy": "redeploy",
          "history": [
            {
              "contractId": "COLD...",
              "wasmHash": "...",
              "deployedAt": "...",
              "supersededAt": "...",
              "reason": "upgrade",
              "upgradeType": "new-contract"
            }
          ]
        }
      }
    }
  }
}

In-place upgrades keep the same contractId and set upgradeStrategy: "in-place" with history entries that share that ID but record the previous wasmHash.

Migrate existing projects without redeploying:

ctg migrate artifacts

Logical rollback (redeploy only)

Restore a prior contractId in artifacts after a redeploy upgrade (does not change on-chain state):

ctg rollback counter --to COLD... --network testnet

The previous on-chain deployment remains — only your git-tracked artifact entry changes. Frontend bindings may need regeneration:

ctg generate counter --network testnet

Orphan contracts (redeploy)

Each redeploy creates a new on-chain contract. Old instances are orphaned — they still exist but are no longer referenced in caatinga.artifacts.json. Plan for:

  • Migrating user state (if your protocol stores data in the old contract)
  • Communicating contract ID changes to integrators
  • Monitoring costs of abandoned instances (rent/storage)

In-place upgrades avoid orphan instances because the contractId stays the same.

When to use each command

Command / flag History reason Use case
ctg upgrade upgrade + upgradeType: in-place Admin-gated WASM replacement on existing ID
deploy --upgrade upgrade + upgradeType: new-contract Intentional version bump via new instance
deploy --force force-redeploy Recovery, accidental redeploy, CI reset

Related docs