{"id":29089592,"url":"https://github.com/openzeppelin/stellar-upgrader-cli","last_synced_at":"2025-06-28T04:04:12.157Z","repository":{"id":298890753,"uuid":"984219375","full_name":"OpenZeppelin/stellar-upgrader-cli","owner":"OpenZeppelin","description":"CLI that help developers to upgrade stellar contracts","archived":false,"fork":false,"pushed_at":"2025-06-20T20:33:15.000Z","size":77,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-06-20T21:41:18.958Z","etag":null,"topics":["stellar-cli-plugin"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenZeppelin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-15T15:21:06.000Z","updated_at":"2025-06-20T20:33:19.000Z","dependencies_parsed_at":"2025-06-13T13:33:56.141Z","dependency_job_id":null,"html_url":"https://github.com/OpenZeppelin/stellar-upgrader-cli","commit_stats":null,"previous_names":["openzeppelin/stellar-upgrader-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/OpenZeppelin/stellar-upgrader-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fstellar-upgrader-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fstellar-upgrader-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fstellar-upgrader-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fstellar-upgrader-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenZeppelin","download_url":"https://codeload.github.com/OpenZeppelin/stellar-upgrader-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fstellar-upgrader-cli/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262371684,"owners_count":23300595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["stellar-cli-plugin"],"created_at":"2025-06-28T04:04:09.079Z","updated_at":"2025-06-28T04:04:12.123Z","avatar_url":"https://github.com/OpenZeppelin.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stellar Contract Upgrader Plugin\n\nA CLI plugin for Stellar that simplifies the process of upgrading smart contracts while performing important security checks.\n\n## Overview\n\nThis is a [Stellar CLI plugin](https://developers.stellar.org/docs/tools/cli/plugins) that provides a streamlined interface for upgrading Stellar smart contracts, replacing the verbose standard command with a simpler syntax. Before executing the upgrade, it performs several security checks to ensure the upgrade will be successful and the contract will remain upgradeable after the operation.\n\n**Plugin Repository**: [https://github.com/OpenZeppelin/stellar-upgrader-cli](https://github.com/OpenZeppelin/stellar-upgrader-cli)\n\nAs a Stellar CLI plugin, this tool integrates seamlessly with the Stellar CLI and follows the standard plugin conventions. Once installed, it becomes available as a subcommand of the `stellar` CLI.\n\n## Installation\n\n### Prerequisites\n\n- Rust and Cargo installed\n- Stellar CLI installed and configured\n\n### Install from source\n\n```bash\n# Clone the repository\ngit clone https://github.com/OpenZeppelin/stellar-upgrader-cli.git\ncd stellar-upgrader\n\n# Build and install\ncargo install --path .\n```\n\n### Verify Installation\n\nAfter installation, verify that the plugin is available by listing installed plugins:\n\n```bash\nstellar plugins --list\n```\n\nYou should see output similar to:\n\n```\nInstalled Plugins:\n    upgrader\n    strkey\n```\n\nThe `upgrader` plugin should be listed among your installed plugins. If it's not showing up, make sure:\n\n1. The binary is named `stellar-upgrader` and is in your `PATH`\n2. The file is executable (`chmod +x` if needed)\n3. Restart your terminal or reload your shell configuration\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Instead of the verbose command:\nstellar contract invoke \\\n  --id CONTRACT_ID \\\n  --source alice \\\n  --network testnet \\\n  -- \\\n  upgrade \\\n  --new_wasm_hash 9ab3011a533a116f82f99ebcd00e72cdca5e42159aaca379fd249fdbd982d9ff\n\n# Use the simplified command:\nstellar upgrader upgrade --id CONTRACT_ID --wasm-hash 9ab3011a533a116f82f99ebcd00e72cdca5e42159aaca379fd249fdbd982d9ff\n\n# You can also specify network and source (optional):\nstellar upgrader upgrade --id CONTRACT_ID --wasm-hash HASH --network testnet --source alice\n```\n\n### Advanced Options\n\nThe plugin supports all the parameters of the original `stellar contract invoke` command:\n\n```bash\nstellar upgrader upgrade \\\n  --id CONTRACT_ID \\\n  --wasm-hash HASH \\\n  --source alice \\\n  --network testnet \\\n  --rpc-url https://soroban-testnet.stellar.org \\\n  --rpc-header \"Authorization: Bearer token\" \\\n  --network-passphrase \"Test SDF Network ; September 2015\" \\\n  --fee 200 \\\n  --is-view \\\n  --instructions 100000 \\\n  --build-only \\\n  --send yes \\\n  --cost \\\n  --force\n```\n\n#### Parameter Reference\n\n| Parameter | Description |\n|-----------|-------------|\n| `--id` | Contract ID to upgrade (required) |\n| `--wasm-hash` | The new WASM hash for the upgrade (required) |\n| `--source` | Source account that will submit the transaction (default: \"alice\") |\n| `--network` | Network to use: testnet, futurenet, mainnet (default: \"testnet\") |\n| `--rpc-url` | RPC server endpoint |\n| `--rpc-header` | RPC Header(s) to include in requests to the RPC provider |\n| `--network-passphrase` | Network passphrase to sign the transaction |\n| `--fee` | Fee amount for transaction, in stroops (1 stroop = 0.0000001 XLM) |\n| `--is-view` | View the result by simulating, without signing or submitting the transaction |\n| `--instructions` | Number of instructions to simulate |\n| `--build-only` | Build the transaction and only write the base64 XDR to stdout |\n| `--send` | Whether to send the transaction: \"yes\", \"no\", \"default\" |\n| `--cost` | Output the cost execution to stderr |\n| `--force` | Force the upgrade and skip all security checks (requires confirmation) |\n\n## Security Checks\n\nThis plugin performs these security checks before executing the upgrade:\n\n1. **Constructor Check**: Verifies the contract doesn't have a `__constructor` function, which could cause issues during upgrades.\n   - ✅ Pass: No `__constructor` function found\n   - ❌ Fail: `__constructor` function found, risk of issues during upgrade\n\n2. **Upgrade Function Check**: Ensures the contract exposes an `upgrade` function with the correct signature.\n   - ✅ Pass: `upgrade` function with proper `new_wasm_hash: soroban_sdk::BytesN\u003c32\u003e` parameter found\n   - ❌ Fail: Missing upgrade function or incorrect signature, which would prevent future upgrades\n\n3. **Version Check**: Compares the binary version (`binver`) in the contract metadata to ensure the new version is greater than the current version.\n   - ✅ Pass: New binary version is greater than current version (e.g., 2.0.0 \u003e 1.0.0)\n   - ❌ Fail: New version is not greater than current version (downgrades are not recommended)\n\nAll security checks must pass for the upgrade command to execute.\n\n### How Version Check Works\n\nThe version check uses the contract metadata to compare versions:\n\n1. **Current Version**: Fetches metadata from the deployed contract using `stellar contract info meta --id CONTRACT_ID`\n2. **New Version**: Fetches metadata from the new WASM hash using `stellar contract info meta --wasm-hash NEW_HASH`\n3. **Comparison**: Compares the `binver` field using semantic versioning rules\n\nExample metadata format:\n```json\n[\n  {\"sc_meta_v0\":{\"key\":\"binver\",\"val\":\"2.0.0\"}},\n  {\"sc_meta_v0\":{\"key\":\"rsver\",\"val\":\"1.85.0\"}},\n  {\"sc_meta_v0\":{\"key\":\"rssdkver\",\"val\":\"22.0.8#f46e9e0610213bbb72285566f9dd960ff96d03d8\"}}\n]\n```\n\nThe plugin extracts the `binver` value and compares versions using semantic versioning:\n- `2.0.0` \u003e `1.9.9` ✅\n- `1.1.0` \u003e `1.0.5` ✅\n- `1.0.0` \u003e `1.0.0` ❌ (equal versions)\n- `1.0.0` \u003e `2.0.0` ❌ (downgrade)\n\n### Bypassing Security Checks\n\nSometimes, even with security checks failing, you may want to force an upgrade. This can be done using the `--force` flag:\n\n```bash\nstellar contract upgrade --id CONTRACT_ID --wasm-hash HASH --force\n```\n\nWhen using `--force`, the tool will display a warning and ask for confirmation before proceeding:\n\n```\n⚠️  WARNING: Security checks are being skipped due to --force flag!\n⚠️  This may result in upgrade failures or loss of upgradeability.\n⚠️  Proceed with caution!\n\nAre you sure you want to proceed without security checks? (y/N):\n```\n\n**⚠️ Warning**: Using `--force` skips all security checks and may result in:\n- Upgrade failures\n- Loss of contract upgradeability\n- Unexpected contract behavior\n- Version downgrades that could cause compatibility issues\n\nOnly use `--force` when you understand the risks and have manually verified the upgrade is safe.\n\n## Development\n\nRun the following commands to install pre-commit hooks:\n\n- Install pre-commit hooks:\n\n  ```bash\n  pip install pre-commit\n  pre-commit install --install-hooks -t commit-msg -t pre-commit -t pre-push\n  ```\n\n  \u003e :warning: If you encounter issues with pip, consider using [pipx](https://pipx.pypa.io/stable/installation/) for a global installation.\n\n- Install the toolchain:\n\n  ```sh\n  rustup component add rustfmt\n  ```\n\n### Project Structure\n\n```\nstellar-upgrader/\n├── src/\n│   ├── main.rs            # CLI entry point\n│   ├── lib.rs             # Core functionality\n│   └── security_checks/   # Modular security checks\n│       ├── mod.rs         # Main security check module\n│       ├── constructor_check.rs\n│       ├── upgrade_function_check.rs\n│       ├── version_check.rs\n│       └── contract_info.rs\n├── examples/              # Usage examples\n└── tests/                 # Integration tests\n```\n\n### Adding New Security Checks\n\n1. Create a new file in `src/security_checks/` (e.g., `new_check.rs`)\n2. Implement the `SecurityCheck` trait\n3. Add your check to the list in `src/security_checks/mod.rs`\n\nExample:\n\n```rust\n// In new_check.rs\nuse crate::UpgradeArgs;\nuse super::{SecurityCheck, SecurityCheckContext};\n\npub struct NewCheck;\n\nimpl NewCheck {\n    pub fn new() -\u003e Self {\n        NewCheck\n    }\n}\n\nimpl SecurityCheck for NewCheck {\n    fn name(\u0026self) -\u003e \u0026str {\n        \"New Security Check\"\n    }\n\n    fn run(\u0026self, _args: \u0026UpgradeArgs, context: \u0026mut SecurityCheckContext) -\u003e Result\u003c(), String\u003e {\n        // Check implementation\n        Ok(())\n    }\n}\n\n// In mod.rs, add to get_security_checks()\npub fn get_security_checks() -\u003e Vec\u003cBox\u003cdyn SecurityCheck\u003e\u003e {\n    vec![\n        Box::new(constructor_check::ConstructorCheck::new()),\n        Box::new(upgrade_function_check::UpgradeFunctionCheck::new()),\n        Box::new(version_check::VersionCheck::new()),\n        Box::new(new_check::NewCheck::new()),\n    ]\n}\n```\n\n### Running Tests\n\n```bash\ncargo test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzeppelin%2Fstellar-upgrader-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenzeppelin%2Fstellar-upgrader-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzeppelin%2Fstellar-upgrader-cli/lists"}