Smart Contract Upgrade Governance
sickn33/agentic-awesome-skills
Soroban WASM upgrade governance register: executable bytecode hash, timelocked migration delays, and multi-sig authorization quorum.
Trigger Pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents, depth-state-trace
$ npx skills add PlamenTSV/plamen --skill contract-upgradeability -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install PlamenTSV/plamen contract-upgradeability --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ 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-srcUse ~/.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/
Install the "contract-upgradeability" agent skill from https://github.com/PlamenTSV/plamen/tree/main/agents/skills/soroban/contract-upgradeability into .claude/skills/contract-upgradeability/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "contract-upgradeability", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/PlamenTSV/plamen/tree/main/agents/skills/soroban/contract-upgradeabilityType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add PlamenTSV/plamen --skill contract-upgradeability -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install PlamenTSV/plamen contract-upgradeability --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/PlamenTSV/plamen.git skills-src && mkdir -p .agents/skills && cp -r skills-src/agents/skills/soroban/contract-upgradeability .agents/skills/contract-upgradeability && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "contract-upgradeability" agent skill from https://github.com/PlamenTSV/plamen/tree/main/agents/skills/soroban/contract-upgradeability into .agents/skills/contract-upgradeability/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "contract-upgradeability", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add PlamenTSV/plamen --skill contract-upgradeability -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install PlamenTSV/plamen contract-upgradeability --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/PlamenTSV/plamen.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/agents/skills/soroban/contract-upgradeability .cursor/skills/contract-upgradeability && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "contract-upgradeability" agent skill from https://github.com/PlamenTSV/plamen/tree/main/agents/skills/soroban/contract-upgradeability into .cursor/skills/contract-upgradeability/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "contract-upgradeability", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/PlamenTSV/plamen.git --path agents/skills/soroban/contract-upgradeability--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add PlamenTSV/plamen --skill contract-upgradeability -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install PlamenTSV/plamen contract-upgradeability --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/PlamenTSV/plamen.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/agents/skills/soroban/contract-upgradeability .gemini/skills/contract-upgradeability && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "contract-upgradeability" agent skill from https://github.com/PlamenTSV/plamen/tree/main/agents/skills/soroban/contract-upgradeability into .gemini/skills/contract-upgradeability/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "contract-upgradeability", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install PlamenTSV/plamen contract-upgradeabilityInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add PlamenTSV/plamen --skill contract-upgradeability -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/PlamenTSV/plamen.git skills-src && mkdir -p .github/skills && cp -r skills-src/agents/skills/soroban/contract-upgradeability .github/skills/contract-upgradeability && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "contract-upgradeability" agent skill from https://github.com/PlamenTSV/plamen/tree/main/agents/skills/soroban/contract-upgradeability into .github/skills/contract-upgradeability/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "contract-upgradeability", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add PlamenTSV/plamen --skill contract-upgradeability -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install PlamenTSV/plamen contract-upgradeability --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/PlamenTSV/plamen.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/agents/skills/soroban/contract-upgradeability .opencode/skills/contract-upgradeability && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "contract-upgradeability" agent skill from https://github.com/PlamenTSV/plamen/tree/main/agents/skills/soroban/contract-upgradeability into .opencode/skills/contract-upgradeability/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "contract-upgradeability", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
contract-upgradeabilityTrigger Pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents, depth-state-trace
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.
5 steps, taken from the step headings in SKILL.md.
Read from SKILL.md and the folder at commit 795962b. It shows what the files ask for, not the result of running them.
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.
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.
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
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.
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.
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.
The full file from PlamenTSV/plamen at commit 795962b, republished under its MIT licence (© PlamenTSV). 719 words, ~1,966 tokens.
.claude/skills/contract-upgradeability/SKILL.md (or your agent's skills folder).Trigger Pattern:
update_current_contract_wasmdetected 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.
Locate every call to update_current_contract_wasm and verify the auth gate:
| Location | Auth Check Present? | Auth Address | Auth Type | Sufficient? |
|---|---|---|---|---|
{file:line} | YES/NO | {admin / multisig / NONE} | require_auth / require_auth_for_args / NONE | YES/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:
update_current_contract_wasm is called (too late — code already replaced)Also check:
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:
| Concern | Addressed? | Evidence | Risk if Not Addressed |
|---|---|---|---|
| New storage keys initialized after upgrade | YES/NO | {fn:line or NONE} | Panics on first access of uninitialized key |
| Removed storage keys cleaned up | YES/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 stored | YES/NO | {fn:line or NONE} | Cannot detect state of migration |
Migration pattern check:
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.
The admin address used to gate upgrades is itself a critical piece of state. Trace how it is set, updated, and protected:
| Operation | Location | Auth Required? | Two-Step Transfer? | Notes |
|---|---|---|---|---|
| Initial admin set (init) | {file:line} | N/A (first call) | N/A | Is there a re-init guard? |
| Admin transfer/update | {file:line} | YES/NO | YES/NO | Single-step is dangerous |
| Admin stored in | {DataKey} | — | — | Instance/Persistent/Temporary? |
Critical checks:
set_admin(new_admin) without two-step handshake means a mistaken address transfer is irreversibleTwo-step transfer pattern (recommended):
// 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) { ... }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:
| Concern | Status | Notes |
|---|---|---|
| Host system event auto-emitted | ALWAYS (host behavior) | Not controllable by contract |
| Contract-level upgrade event emitted | YES/NO | Recommended for off-chain monitoring |
| Event includes new WASM hash | YES/NO | Enables tracing what was deployed |
| Event includes timestamp / ledger | YES/NO | Enables 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.
Some protocols intend to make contracts permanently immutable after a stabilization period. Check whether such a mechanism exists and is correctly implemented:
| Mechanism | Present? | Implementation | Correctness |
|---|---|---|---|
| Upgrade function can be permanently disabled | YES/NO | {description or NONE} | YES/NO/N/A |
| Immutability flag stored | YES/NO | {DataKey} | Stored as Persistent? |
| Immutability flag checked before upgrade | YES/NO | {fn:line} | Before or after auth? |
Pattern:
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.
**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]| Section | Required | Completed? | Notes |
|---|---|---|---|
| 1. Upgrade Access Control | YES | ✓/✗/? | Every update_current_contract_wasm call |
| 2. Migration Safety | YES | ✓/✗/? | Storage layout compatibility |
| 3. Admin Key Management | YES | ✓/✗/? | Init, transfer, storage type |
| 4. Upgrade Event Emission | YES | ✓/✗/? | Contract-level event presence |
| 5. Immutability Option | IF 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
Just SKILL.md in agents/skills/soroban/contract-upgradeability of PlamenTSV/plamen.
Open the folder on GitHubat commit 795962b
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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Contract Upgradeability this skillPlamenTSV/plamen | 303 | — | ~2k | Automated safety check: Pass | MIT | |
| Smart Contract Upgrade Governancesickn33/agentic-awesome-skills | 47k | 1 repos | ~1.4k | Automated safety check: Pass | MIT | |
| Soroban Contract Auditsickn33/agentic-awesome-skills | 47k | 1 repos | ~1.4k | Automated safety check: Pass | MIT | |
| Soroban Liquidity Poolsickn33/agentic-awesome-skills | 47k | 1 repos | ~1.3k | Automated safety check: Pass | MIT | |
| Soroban Storage Ttl Lifecyclesickn33/agentic-awesome-skills | 47k | 1 repos | ~1.3k | Automated safety check: Pass | MIT | |
| Soroban Token Mintersickn33/agentic-awesome-skills | 47k | 1 repos | ~1.3k | Automated safety check: Pass | MIT |
sickn33/agentic-awesome-skills
Soroban WASM upgrade governance register: executable bytecode hash, timelocked migration delays, and multi-sig authorization quorum.
sickn33/agentic-awesome-skills
Soroban smart contract security audit register: authorization checks, panic pathways, integer overflows, and storage footprint verification for Stellar.
sickn33/agentic-awesome-skills
Automated market maker liquidity pool register: constant-product invariant curves, swap fee tiers, and LP token shares for Soroban DeFi.
sickn33/agentic-awesome-skills
Soroban ledger state rent and TTL extension register: live state tracking, bump thresholds, rent fee reserves, and archive boundaries.
sickn33/agentic-awesome-skills
Soroban SEP-41 token contract architecture register: admin control, supply caps, metadata standard, and transfer event emissions on Stellar.
VelaPayments/vela-payments
End-to-end Stellar development playbook. An agent skill from VelaPayments/vela-payments.
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…
PlamenTSV/plamen
Trigger Pattern Always (used by all verifier agents) - Inject Into security-verifier agents (Phase 5)
PlamenTSV/plamen
Trigger Pattern Always (Aptos Move) - foundational security check - Inject Into Breadth agents, depth agents
PlamenTSV/plamen
Trigger Pattern Always (Sui Move) -- foundational security check - Inject Into Breadth agents, depth agents
PlamenTSV/plamen
Trigger Pattern ACCOUNTCLOSING flag detected (close/CloseAccount usage) - Inject Into Breadth agents, depth agents
PlamenTSV/plamen
Trigger Pattern Always required for Solana audits - Inject Into Breadth agents, depth agents
Works with
Categories
Trigger Pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents, depth-state-trace. Contract Upgradeability is an agent skill from PlamenTSV/plamen.
Contract Upgradeability fits situations like: pattern updatecurrentcontractwasm detected in codebase - Inject Into Breadth agents; depth-state-trace.
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.
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.
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.
SKILL.md names no scripts, command-line tools or credentials: Contract Upgradeability is instructions for the agent only.
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.
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.
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.
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.
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.
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.