Agent skill

Contract Upgradeability

by PlamenTSV in PlamenTSV/plamen

Trigger Pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents, depth-state-trace

MITAuto-check passedSecurity

Install Contract Upgradeability

skills CLI
$ npx skills add PlamenTSV/plamen --skill contract-upgradeability -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install PlamenTSV/plamen contract-upgradeability --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/PlamenTSV/plamen.git skills-src && mkdir -p .claude/skills && cp -r skills-src/agents/skills/soroban/contract-upgradeability .claude/skills/contract-upgradeability && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
contract-upgradeability
GitHub stars
303
Token cost
~2k tokens
SKILL.md length
719 words
Files
1
Skills in repo
87
Repo updated
First seen
Licence
MIT

At a glance

Trigger Pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents, depth-state-trace

  • Works in 5 steps: Upgrade Access Control → Migration Safety → Admin Key Management → …
  • Pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents
  • SKILL.md covers 1. Upgrade Access Control, 2. Migration Safety, 3. Admin Key Management and 4. Upgrade Event Emission, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Contract Upgradeability is an agent skill from PlamenTSV/plamen. Trigger Pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents, depth-state-trace

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Security, covering Smart contract auditing. It works with WebAssembly and Stellar. The repository describes itself as: Autonomous Web3 security audit agent for Claude Code. The licence is MIT.

When your agent uses it

  • Pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents
  • Depth-state-trace

Example prompts

  • “/contract-upgradeability”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Upgrade Access Control
  2. Migration Safety
  3. Admin Key Management
  4. Upgrade Event Emission
  5. Immutability Option

What it can do on your machine

Read from SKILL.md and the folder at commit 795962b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are rust and markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Contract Upgradeability loads about 2k tokens when it runs. Until then it costs about 34 tokens; SKILL.md has 719 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~34
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from PlamenTSV/plamen at commit 795962b, republished under its MIT licence (© PlamenTSV). 719 words, ~1,966 tokens.

Download SKILL.mdSave it as .claude/skills/contract-upgradeability/SKILL.md (or your agent's skills folder).
name
contract-upgradeability
description
Trigger Pattern update_current_contract_wasm detected in codebase - Inject Into Breadth agents, depth-state-trace

CONTRACT_UPGRADEABILITY Skill (Soroban)

Trigger Pattern: update_current_contract_wasm detected in codebase Inject Into: Breadth agents, depth-state-trace Finding prefix: [CU-N] Rules referenced: R6, R10, R12, R13

Soroban provides env.deployer().update_current_contract_wasm(new_wasm_hash) for in-place contract upgrades. This is more powerful than EVM proxy patterns — it directly replaces the executing contract's WASM bytecode without changing the contract address or storage. Unrestricted upgrade capability is an absolute control vector; the upgrade gate must be airtight.

1. Upgrade Access Control

Locate every call to update_current_contract_wasm and verify the auth gate:

LocationAuth Check Present?Auth AddressAuth TypeSufficient?
{file:line}YES/NO{admin / multisig / NONE}require_auth / require_auth_for_args / NONEYES/NO

Minimum requirement: The upgrade function MUST call require_auth() or require_auth_for_args() on a privileged address before calling update_current_contract_wasm.

Patterns to flag as insufficient:

  • No auth check at all (anyone can upgrade)
  • Auth check on a non-admin address (e.g., any token holder)
  • Auth check after update_current_contract_wasm is called (too late — code already replaced)
  • The privileged address is stored in Temporary storage (can be deleted/expired, unlocking upgrade for anyone)

Also check:

  • Is the admin address itself protected from replacement without auth? (see Section 3)
  • Can the upgrade function be called during initialization before admin is set? (init race)

2. Migration Safety

An upgrade replaces WASM but preserves ALL storage. If the new WASM has a different storage layout or new required keys, the upgrade function must handle migration:

ConcernAddressed?EvidenceRisk if Not Addressed
New storage keys initialized after upgradeYES/NO{fn:line or NONE}Panics on first access of uninitialized key
Removed storage keys cleaned upYES/NO{fn:line or NONE}Bloat only (low risk unless size-bounded)
Struct fields added/removed (ABI break)YES/NO{fn:line or NONE}Deserialization panic on old data
Version discriminator storedYES/NO{fn:line or NONE}Cannot detect state of migration

Migration pattern check:

rust
pub fn upgrade(env: Env, new_wasm_hash: BytesN<32>) {
    // Step 1: Auth gate
    let admin = env.storage().instance().get::<_, Address>(&DataKey::Admin).unwrap();
    admin.require_auth();
    // Step 2: Replace WASM
    env.deployer().update_current_contract_wasm(new_wasm_hash);
    // Step 3: Migrate storage (if needed)
    // env.storage().instance().set(&DataKey::NewField, &default_value);
}

Absence of migration: If the upgraded WASM accesses storage keys or uses different struct layouts than the currently-stored data, ALL post-upgrade operations will panic. This is effectively a self-inflicted DoS on upgrade.

3. Admin Key Management

The admin address used to gate upgrades is itself a critical piece of state. Trace how it is set, updated, and protected:

OperationLocationAuth Required?Two-Step Transfer?Notes
Initial admin set (init){file:line}N/A (first call)N/AIs there a re-init guard?
Admin transfer/update{file:line}YES/NOYES/NOSingle-step is dangerous
Admin stored in{DataKey}——Instance/Persistent/Temporary?

Critical checks:

  • Admin stored as Temporary: if it expires, the contract becomes permanently non-upgradeable AND the upgrade slot is open to whoever sets themselves as admin via any unguarded init path
  • Single-step admin transfer: set_admin(new_admin) without two-step handshake means a mistaken address transfer is irreversible
  • Admin key not set on init: if the initialize function does not set the admin, the first caller of any admin function can claim admin
  • Admin set to the zero address or contract address by accident

Two-step transfer pattern (recommended):

rust
// Step 1: current admin proposes new admin
pub fn propose_admin(env: Env, new_admin: Address) { ... }
// Step 2: new admin accepts
pub fn accept_admin(env: Env) { ... }
Show full SKILL.md (250 more words)Show less

4. Upgrade Event Emission

The Soroban host automatically emits a contract_upgraded system event on WASM replacement. However, the contract should also emit its own application-level event for indexer/monitoring visibility:

ConcernStatusNotes
Host system event auto-emittedALWAYS (host behavior)Not controllable by contract
Contract-level upgrade event emittedYES/NORecommended for off-chain monitoring
Event includes new WASM hashYES/NOEnables tracing what was deployed
Event includes timestamp / ledgerYES/NOEnables timeline reconstruction

Finding threshold: Missing contract-level upgrade event is Low/Informational severity — the host event provides a baseline. Flag as Medium if the protocol's stated design includes monitoring hooks that depend on contract events.

5. Immutability Option

Some protocols intend to make contracts permanently immutable after a stabilization period. Check whether such a mechanism exists and is correctly implemented:

MechanismPresent?ImplementationCorrectness
Upgrade function can be permanently disabledYES/NO{description or NONE}YES/NO/N/A
Immutability flag storedYES/NO{DataKey}Stored as Persistent?
Immutability flag checked before upgradeYES/NO{fn:line}Before or after auth?

Pattern:

rust
pub fn freeze_upgrades(env: Env) {
    admin.require_auth();
    env.storage().instance().set(&DataKey::Frozen, &true);
}

pub fn upgrade(env: Env, new_wasm_hash: BytesN<32>) {
    // Check frozen BEFORE auth (fail fast)
    let frozen = env.storage().instance().get::<_, bool>(&DataKey::Frozen).unwrap_or(false);
    require!(!frozen, "contract is immutable");
    admin.require_auth();
    env.deployer().update_current_contract_wasm(new_wasm_hash);
}

Finding for incorrect ordering: If the frozen check occurs AFTER require_auth, an admin can bypass the intent by upgrading before freezing. The frozen check must be unconditional and first.

Finding Template

markdown
**ID**: [CU-N]
**Severity**: [Critical if unguarded upgrade, High if admin management flaw, Medium if migration risk, Low if event/immutability]
**Step Execution**: ✓1,2,3,4,5 | ✗(reasons) | ?(uncertain)
**Rules Applied**: [R6:✓/✗, R10:✓/✗, R12:✓/✗, R13:✓/✗]
**Location**: src/{contract}.rs:LineN
**Title**: {Missing auth / migration gap / admin flaw} in upgrade path — {impact}
**Description**: [Specific upgradeability issue with code reference]
**Impact**: [Unauthorized upgrade / post-upgrade DoS / admin key loss / irrecoverable state]

Step Execution Checklist (MANDATORY)

SectionRequiredCompleted?Notes
1. Upgrade Access ControlYES✓/✗/?Every update_current_contract_wasm call
2. Migration SafetyYES✓/✗/?Storage layout compatibility
3. Admin Key ManagementYES✓/✗/?Init, transfer, storage type
4. Upgrade Event EmissionYES✓/✗/?Contract-level event presence
5. Immutability OptionIF freeze mechanism present or stated in docs✓/✗(N/A)/?Freeze ordering and storage type

© PlamenTSV, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in agents/skills/soroban/contract-upgradeability of PlamenTSV/plamen.

Open the folder on GitHubat commit 795962b

Compare with similar skills

Contract Upgradeability next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Contract Upgradeability compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Contract Upgradeability this skillPlamenTSV/plamen303—~2kAutomated safety check: PassMIT
Smart Contract Upgrade Governancesickn33/agentic-awesome-skills47k1 repos~1.4kAutomated safety check: PassMIT
Soroban Contract Auditsickn33/agentic-awesome-skills47k1 repos~1.4kAutomated safety check: PassMIT
Soroban Liquidity Poolsickn33/agentic-awesome-skills47k1 repos~1.3kAutomated safety check: PassMIT
Soroban Storage Ttl Lifecyclesickn33/agentic-awesome-skills47k1 repos~1.3kAutomated safety check: PassMIT
Soroban Token Mintersickn33/agentic-awesome-skills47k1 repos~1.3kAutomated safety check: PassMIT

Similar skills

  • Smart Contract Upgrade Governance

    sickn33/agentic-awesome-skills

    Soroban WASM upgrade governance register: executable bytecode hash, timelocked migration delays, and multi-sig authorization quorum.

    47k GitHub starsUsed in 1 repo~1.4k tokens
    Backend & APIsAuto-check passed
  • Soroban Contract Audit

    sickn33/agentic-awesome-skills

    Soroban smart contract security audit register: authorization checks, panic pathways, integer overflows, and storage footprint verification for Stellar.

    47k GitHub starsUsed in 1 repo~1.4k tokens
    SecurityAuto-check passed
  • Soroban Liquidity Pool

    sickn33/agentic-awesome-skills

    Automated market maker liquidity pool register: constant-product invariant curves, swap fee tiers, and LP token shares for Soroban DeFi.

    47k GitHub starsUsed in 1 repo~1.3k tokens
    SecurityAuto-check passed
  • Soroban Storage Ttl Lifecycle

    sickn33/agentic-awesome-skills

    Soroban ledger state rent and TTL extension register: live state tracking, bump thresholds, rent fee reserves, and archive boundaries.

    47k GitHub starsUsed in 1 repo~1.3k tokens
    SecurityAuto-check passed
  • Soroban Token Minter

    sickn33/agentic-awesome-skills

    Soroban SEP-41 token contract architecture register: admin control, supply caps, metadata standard, and transfer event emissions on Stellar.

    47k GitHub starsUsed in 1 repo~1.3k tokens
    SecurityAuto-check passed
  • Stellar Dev

    VelaPayments/vela-payments

    End-to-end Stellar development playbook. An agent skill from VelaPayments/vela-payments.

    131 GitHub stars~1.8k tokensUpdated 2 days ago
    Backend & APIsAuto-check passed

More from PlamenTSV/plamen

All 87 skills in this repo
  • Audit Prep

    PlamenTSV/plamen

    Prepare Solidity projects for a security audit — test coverage, test quality, NatSpec docs, code hygiene, dependency health, best-practice enforcement, deployment readiness, and project…

    303 GitHub stars~3.7k tokensUpdated 12 days ago
    Auto-check passed
  • Verification Protocol

    PlamenTSV/plamen

    Trigger Pattern Always (used by all verifier agents) - Inject Into security-verifier agents (Phase 5)

    303 GitHub stars~3.5k tokensUpdated 12 days ago
    Auto-check passed
  • Ability Analysis

    PlamenTSV/plamen

    Trigger Pattern Always (Aptos Move) - foundational security check - Inject Into Breadth agents, depth agents

    303 GitHub stars~3.3k tokensUpdated 12 days ago
    Auto-check passed
  • Ability Analysis

    PlamenTSV/plamen

    Trigger Pattern Always (Sui Move) -- foundational security check - Inject Into Breadth agents, depth agents

    303 GitHub stars~3.2k tokensUpdated 12 days ago
    Auto-check passed
  • Account Lifecycle

    PlamenTSV/plamen

    Trigger Pattern ACCOUNTCLOSING flag detected (close/CloseAccount usage) - Inject Into Breadth agents, depth agents

    303 GitHub stars~1.2k tokensUpdated 12 days ago
    Auto-check passed
  • Account Validation

    PlamenTSV/plamen

    Trigger Pattern Always required for Solana audits - Inject Into Breadth agents, depth agents

    303 GitHub stars~1.7k tokensUpdated 12 days ago
    Auto-check passed

Categories

Questions about Contract Upgradeability

What does Contract Upgradeability do?

Trigger Pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents, depth-state-trace. Contract Upgradeability is an agent skill from PlamenTSV/plamen.

When should I use Contract Upgradeability?

Contract Upgradeability fits situations like: pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents; depth-state-trace.

How do I install Contract Upgradeability in Claude Code?

Run `npx skills add PlamenTSV/plamen --skill contract-upgradeability -a claude-code`. Or copy the skill folder (agents/skills/soroban/contract-upgradeability in PlamenTSV/plamen) into .claude/skills/contract-upgradeability in your project. Claude Code loads it when a task matches its description.

How do I install Contract Upgradeability in Codex?

Run `npx skills add PlamenTSV/plamen --skill contract-upgradeability -a codex`. Or copy the skill folder (agents/skills/soroban/contract-upgradeability in PlamenTSV/plamen) into .agents/skills/contract-upgradeability in your project. Codex loads it when a task matches its description.

Can I use Contract Upgradeability in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add PlamenTSV/plamen --skill contract-upgradeability -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/contract-upgradeability, .gemini/skills/contract-upgradeability, .github/skills/contract-upgradeability and .opencode/skills/contract-upgradeability in your project.

What does Contract Upgradeability need to run?

SKILL.md names no scripts, command-line tools or credentials: Contract Upgradeability is instructions for the agent only.

Does Contract Upgradeability access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Contract Upgradeability safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Contract Upgradeability use?

Contract Upgradeability is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Contract Upgradeability use?

About 2k tokens (SKILL.md is roughly 7.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Contract Upgradeability?

Skills that share tags, products or a category with Contract Upgradeability: Smart Contract Upgrade Governance (sickn33/agentic-awesome-skills, 47k stars), Soroban Contract Audit (sickn33/agentic-awesome-skills, 47k stars), Soroban Liquidity Pool (sickn33/agentic-awesome-skills, 47k stars) and Soroban Storage Ttl Lifecycle (sickn33/agentic-awesome-skills, 47k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Contract Upgradeability?

PlamenTSV (a GitHub user) maintains it in PlamenTSV/plamen, which has 303 GitHub stars. The repository holds 87 skills in this directory. The repository was last updated on September 26, 2026.

Source: PlamenTSV/plamen on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.