From 722a519f5e790499eb27b1e2159ed70ba26e61e3 Mon Sep 17 00:00:00 2001 From: huazhuang80-star Date: Mon, 22 Jun 2026 03:00:03 +0800 Subject: [PATCH 1/3] docs: add smart contract upgrade guide --- CONTRACT_UPGRADE_GUIDE.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 CONTRACT_UPGRADE_GUIDE.md diff --git a/CONTRACT_UPGRADE_GUIDE.md b/CONTRACT_UPGRADE_GUIDE.md new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/CONTRACT_UPGRADE_GUIDE.md @@ -0,0 +1 @@ + From 4736485b1b0611a6a9ba5a94c7b78b137ae942cc Mon Sep 17 00:00:00 2001 From: huazhuang80-star Date: Mon, 22 Jun 2026 03:03:08 +0800 Subject: [PATCH 2/3] docs: link contract upgrade guide from readme --- README.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4c7d750..b3a87ca 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,12 @@ The project enables developers to build reactive decentralized applications with 2. [Project Structure](#project-structure) 3. [Event Flow](#event-flow) 4. [Local Development Guide](#local-development-guide) -5. [Features](#features) -6. [Use Cases](#use-cases) -7. [Tech Stack](#tech-stack) -8. [Contributing](#contributing) -9. [License](#license) +5. [Smart Contract Upgrade Guide](#smart-contract-upgrade-guide) +6. [Features](#features) +7. [Use Cases](#use-cases) +8. [Tech Stack](#tech-stack) +9. [Contributing](#contributing) +10. [License](#license) > **Listener service docs**: [Notification Failure Recovery](NOTIFICATION_FAILURE_RECOVERY.md) — retry lifecycle, configuration, and troubleshooting. @@ -398,6 +399,17 @@ Add this to `.vscode/settings.json`: --- +## Smart Contract Upgrade Guide + +Before changing contract storage, public methods, event schemas, authorization +rules, or deployment artifacts, read the +[Smart Contract Upgrade Guide](CONTRACT_UPGRADE_GUIDE.md). It documents the +recommended upgrade workflow, prerequisites, testnet verification steps, +rollback procedures, risk checklist, and PR template for NotifyChain contract +changes. + +--- + ## Features * 📡 Real-time blockchain event monitoring From 7899e18d551df25b02f168b2445ab09772496b6f Mon Sep 17 00:00:00 2001 From: huazhuang80-star Date: Mon, 22 Jun 2026 03:05:08 +0800 Subject: [PATCH 3/3] docs: add smart contract upgrade guide content --- CONTRACT_UPGRADE_GUIDE.md | 311 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 311 insertions(+) diff --git a/CONTRACT_UPGRADE_GUIDE.md b/CONTRACT_UPGRADE_GUIDE.md index 8b13789..85cdb31 100644 --- a/CONTRACT_UPGRADE_GUIDE.md +++ b/CONTRACT_UPGRADE_GUIDE.md @@ -1 +1,312 @@ +# Smart Contract Upgrade Guide +This guide describes a repeatable, contributor-friendly workflow for upgrading +NotifyChain smart contracts without losing reviewability or deployment safety. +It is written for the active Soroban workspaces in this repository: + +- `contract/contracts/hello-world/` for the AutoShare contract. +- `Documents/Task Bounty/` for the TaskBounty contract. + +Use this guide before changing contract storage, public methods, emitted events, +authorization rules, or deployment artifacts. + +## Upgrade Goals + +A contract upgrade should make one intentional change at a time and leave a +review trail that maintainers can audit later. Every upgrade PR should answer: + +- What contract behavior changes? +- Which storage keys, events, or public methods are affected? +- How can reviewers reproduce the build and tests? +- How can a deployer verify the new Wasm before and after deployment? +- What is the rollback or fallback plan if verification fails? + +## Prerequisites + +Install the standard Soroban toolchain: + +```bash +rustup target add wasm32-unknown-unknown +cargo install --locked stellar-cli --features opt +``` + +Verify the tools: + +```bash +rustc --version +cargo --version +stellar --version +``` + +For testnet deployment checks, create and fund a test identity: + +```bash +stellar keys generate test-upgrade --network testnet +stellar keys fund test-upgrade --network testnet +``` + +Keep mainnet deployment keys, hardware wallets, passphrases, and any signing +material out of this repository and out of PR comments. + +## 1. Scope the Upgrade + +Before editing code, identify the target contract and write down the smallest +reviewable scope. + +For AutoShare: + +```bash +cd contract/contracts/hello-world +``` + +For TaskBounty: + +```bash +cd "Documents/Task Bounty" +``` + +Check the relevant files: + +- `src/lib.rs` for exported contract methods. +- `src/base/types.rs` or `src/types.rs` for persisted data structures. +- `src/base/events.rs` or `src/events.rs` for event shapes. +- Existing tests under `src/tests/` or `src/test.rs`. +- README, API, setup, and workflow docs that mention the changed behavior. + +Classify the change before implementation: + +| Change type | Examples | Required review focus | +| --- | --- | --- | +| Public API | New method, removed method, changed arguments | Client compatibility and README/API updates | +| Storage shape | New key, renamed key, changed struct field | Migration path and old-state handling | +| Event schema | New event, renamed field, removed field | Listener/dashboard compatibility | +| Authorization | Admin checks, pause checks, role changes | Access-control tests and misuse cases | +| Deployment config | Wasm path, network, initialization args | Reproducible commands and verification | + +If more than one row changes, consider splitting the work into smaller PRs. + +## 2. Create an Upgrade Branch + +Use a branch name that includes the target contract and issue number: + +```bash +git checkout -b docs/contract-upgrade-guide-140 +``` + +For code upgrades, prefer: + +```bash +git checkout -b contract/autoshare-upgrade- +git checkout -b contract/taskbounty-upgrade- +``` + +## 3. Implement the Change + +Keep the implementation localized: + +- Update the contract module that owns the behavior. +- Add or update tests next to the affected contract. +- Update docs in the same PR when public behavior, events, or setup steps + change. +- Avoid unrelated formatting, generated files, and dependency upgrades. + +When changing storage, document how old state is handled. Soroban contracts do +not automatically migrate historical state for you, so reviewers need to know +whether the new code: + +- reads existing keys without modification, +- introduces optional/defaulted fields, +- writes new keys only after the next successful method call, or +- requires a new deployment instead of an in-place upgrade. + +## 4. Build and Test Locally + +Run contract checks from the workspace that changed. + +AutoShare: + +```bash +cd contract/contracts/hello-world +cargo fmt --all +cargo test +stellar contract build +``` + +TaskBounty: + +```bash +cd "Documents/Task Bounty" +cargo fmt --all +cargo test +stellar contract build +``` + +If a top-level workspace command is more appropriate for the PR, include it in +the PR description with the exact directory where it was run. + +## 5. Inspect the Wasm Artifact + +Record the Wasm path and hash before deployment checks. This gives reviewers a +stable artifact reference. + +```bash +find . -path "*target*" -name "*.wasm" -type f +sha256sum target/wasm32v1-none/release/*.wasm +``` + +Inspect the contract interface: + +```bash +stellar contract inspect --wasm target/wasm32v1-none/release/*.wasm +``` + +Confirm that exported functions, event names, and argument types match the +intended change. If the inspect output differs from the PR description, stop +and fix the code or docs before opening the PR. + +## 6. Deploy to Testnet for Verification + +Use testnet for upgrade rehearsals. Do not use production keys in local testing +or PR evidence. + +Deploy a fresh testnet instance when the change is not backward compatible: + +```bash +stellar contract deploy \ + --wasm target/wasm32v1-none/release/.wasm \ + --source test-upgrade \ + --network testnet +``` + +Save the returned contract ID: + +```bash +export CONTRACT_ID= +``` + +Initialize the contract with test-only values, then invoke the changed method +or the closest verification path. + +For a contract that supports admin initialization: + +```bash +stellar contract invoke \ + --id $CONTRACT_ID \ + --source test-upgrade \ + --network testnet \ + -- \ + initialize_admin \ + --admin +``` + +For TaskBounty-style initialization: + +```bash +stellar contract invoke \ + --id $CONTRACT_ID \ + --source test-upgrade \ + --network testnet \ + -- \ + initialize \ + --dispute_resolver \ + --admin +``` + +Use placeholder values in documentation and PR comments. Never paste private +keys, seeds, live account credentials, or production secrets. + +## 7. Verification Checklist + +Before requesting review, confirm: + +- `cargo fmt --all` was run for the changed contract workspace. +- `cargo test` passes for the changed contract. +- `stellar contract build` produces a Wasm artifact. +- `stellar contract inspect` output matches the documented interface. +- Any changed event schema is reflected in listener or dashboard docs. +- Any changed public method is reflected in README/API docs. +- Authorization and pause behavior are tested for success and failure paths. +- PR body includes exact commands, directory names, and results. + +For docs-only upgrade guidance, verify: + +- All referenced paths exist. +- Commands match the current repository layout. +- No production secrets, private keys, or wallet recovery phrases are included. + +## 8. Rollback and Fallback Procedures + +Rollback depends on the type of upgrade. + +### Documentation or Client-Only Issue + +Revert the PR or follow up with a corrective docs PR. No contract state changes +are involved. + +### Failed Testnet Deployment + +Do not promote the artifact. Open a follow-up issue with: + +- the failing command, +- the contract ID if one was created, +- the Wasm hash, +- observed error output, +- the suspected failure class. + +Then return to the previous known-good commit and rebuild. + +### Failed Mainnet Readiness Check + +Stop before signing any mainnet transaction. Re-run the testnet verification +checklist with a fresh test identity and require maintainer review before +continuing. + +### Post-Deployment Regression + +If a deployed contract has a regression: + +1. Pause affected flows if the contract exposes a pause/admin control. +2. Announce the affected contract ID, network, and user-visible impact. +3. Preserve the failing Wasm hash and transaction IDs for audit. +4. Deploy a corrected contract or restore clients to the previous contract ID, + depending on the integration model. +5. Document the incident and add regression tests before resuming normal use. + +## 9. PR Template for Contract Upgrades + +Use this structure in upgrade PRs: + +```markdown +## Summary +- What changed +- Which contract/workspace changed +- Linked issue + +## Compatibility +- Public methods changed: +- Storage keys or persisted data changed: +- Event schema changed: +- Client/listener/dashboard impact: + +## Verification +- Directory: +- Commands run: +- Wasm path: +- Wasm sha256: +- `stellar contract inspect` reviewed: + +## Rollback +- Safe fallback: +- Conditions that should stop deployment: + +Closes # +``` + +## Related Documentation + +- [Project README](README.md) +- [Root contributing guide](CONTRIBUTING.md) +- [AutoShare contract workspace](contract/) +- [TaskBounty setup guide](Documents/Task%20Bounty/SETUP.md) +- [TaskBounty architecture](Documents/Task%20Bounty/ARCHITECTURE.md) +- [TaskBounty workflows](Documents/Task%20Bounty/WORKFLOWS.md)