Skip to content

fix: gate sdk 27 storage compatibility - #102

Open
chigozzdevv wants to merge 4 commits into
boundlessfi:testnetfrom
chigozzdevv:issue-91-sdk27-storage-compat
Open

fix: gate sdk 27 storage compatibility#102
chigozzdevv wants to merge 4 commits into
boundlessfi:testnetfrom
chigozzdevv:issue-91-sdk27-storage-compat

Conversation

@chigozzdevv

@chigozzdevv chigozzdevv commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add SDK 23 to SDK 27 upgrade tests using the deployed mainnet WASMs, an exact mainnet ledger snapshot, and synthetic coverage for every persisted layout.
  • Preserve legacy OpSeen(BytesN<32>) replay markers without weakening caller-namespaced writes.
  • Pin compatibility fixtures and canonical Linux x86_64 SDK 27 release artifacts.
  • Harden the coordinated events and profile mainnet upgrade flow with version, admin, binding, pause, queued-hash, executable-hash, migration, and ordering checks.
  • Document fixture provenance and the guarded mainnet procedure.

Verification

  • cargo test --release — 290 passed
  • ./scripts/test-sdk27-compat.sh — 3 passed
  • ./scripts/test-mainnet-upgrade-guards.sh — 45 passed
  • stellar contract build --locked — passed
  • Canonical SDK 27 artifacts after rebasing on testnet with fix(profile,events): replace saturating_add with checked_add + typed errors #101:
    • events: 31b27e9d5fe554e0710161dd9387693e166bdd755d985a9771b1ed71b9e28321
    • profile: d2d025d0f7c2c29e6dbd95401841cf62b8b61be608c48615cffb5934050890c0
  • Rust formatting, Bash syntax, canonical hash verification, and diff checks passed

No mainnet transaction was submitted. Mainnet application remains gated by the deployment runbook and multisig prerequisites.

Closes #91

@almanax-ai

almanax-ai Bot commented Jul 24, 2026

Copy link
Copy Markdown

Quota reached

Your plan allows 300 CI/CD file units per month. You've used 299 and this scan would add 36 more (total: 335).

@coderabbitai

coderabbitai Bot commented Jul 24, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

This PR pins Rust and Stellar tooling, adds SDK 23-to-27 storage compatibility fixtures and tests, preserves legacy operation-marker reads, strengthens coordinated mainnet upgrade guards, and integrates reproducible builds and validation into CI and deployment documentation.

Changes

SDK 27 upgrade readiness

Layer / File(s) Summary
Storage compatibility fixtures and tests
contracts/compatibility/*
Adds pinned manifests, ledger/WASM fixtures, generated snapshots, and integration tests covering legacy storage, upgrades, migrations, replay markers, prizes, cancellation, and mainnet state.
Legacy operation markers
contracts/events/src/storage.rs, contracts/profile/src/storage.rs, contracts/events/src/tests/*
Reads current scoped and legacy unscoped OpSeen keys, with unused test state removed.
Guarded mainnet upgrade orchestration
deploy_mainnet.sh
Adds pinned artifact checks and coordinated profile/events commands for pause, propose, apply, migrate, cancel, unpause, and verification.
Upgrade guard test harness
scripts/test-mainnet-upgrade-guards.sh, scripts/testdata/mock-stellar
Exercises ordering, state, version, hash, migration, cancellation, and abandonment guards using a mocked Stellar CLI.
Pinned builds and CI enforcement
.github/*, .gitignore, scripts/deploy*, scripts/test-sdk27-compat.sh
Pins Rust 1.93.0, uses locked builds, validates compatibility and snapshots, and expands workflow path coverage.
Fixture capture and operational documentation
scripts/capture-mainnet-compat-snapshot.sh, docs/*, AGENTS.md, BACKLOG.md
Documents and automates fixture provenance, SDK 27 deployment sequencing, recovery, verification, and repository workflows.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related issues

Possibly related PRs

Suggested reviewers: 0xdevcollins

Poem

A rabbit checks each hash in line,
Pins Rust beneath the moon’s design.
Old rows wake in newer code,
Guarded upgrades safely go.
Snapshots thump, the tests all cheer—
SDK 27 is here!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 5.56% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The PR adds SDK 23→27 compatibility tests, snapshot/fixture pinning, and runbook updates that cover the mainnet upgrade gate.
Out of Scope Changes check ✅ Passed The added workflows, fixtures, tests, and docs all support the SDK 27 compatibility and guarded upgrade objectives.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly reflects the core change: adding a gate for SDK 27 storage compatibility.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🧹 Nitpick comments (1)
deploy_mainnet.sh (1)

417-427: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Remove the unused assert_pending_events_version helper.

This helper is only defined once in deploy_mainnet.sh; all events-event version checks go through assert_pending_events_upgrade, which also validates wasm_hash. Removing it avoids stale dead code that only checks new_version.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@deploy_mainnet.sh` around lines 417 - 427, Remove the unused
assert_pending_events_version function from deploy_mainnet.sh, leaving
assert_pending_events_upgrade as the sole helper for pending events upgrade
validation, including wasm_hash checks.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 9-12: Add the text language tag to the Markdown fenced code block
containing the plugin commands in AGENTS.md, preserving both commands unchanged.

In `@contracts/compatibility/src/lib.rs`:
- Around line 383-386: The payout compatibility tests only verify recipient
deltas, leaving fee accrual untested. In contracts/compatibility/src/lib.rs
lines 383-386, capture fee_account’s balance before the grant and crowdfunding
payouts and assert the expected FEE_BPS fee delta alongside each recipient
assertion; in lines 522-523, do the same for the 50/50 prize split alongside
winner and second_winner assertions. Cover the single-position, multi-position,
and sweep variants while reusing the existing payout balance snapshots.

In `@docs/mainnet-deploy-runbook.md`:
- Line 488: Clarify the timelock guidance so the event check aborts when an
event already exists or returns any result other than EventNotFound; only
EventNotFound permits proceeding. Preserve the existing requirements to avoid
unpausing either contract, investigate ambiguous RPC errors, publish both ledger
values, and wait for the later availability ledger.

In `@docs/sdk27-compatibility-fixtures.md`:
- Around line 28-30: Update the paragraph describing the mainnet WASM files to
refer readers to the manifest for the contract IDs instead of claiming they
appear above, while preserving the existing statement about matching deployed
SHA-256 hashes.

In `@scripts/test-sdk27-compat.sh`:
- Around line 27-106: Update the SDK 27 compatibility flow around the stellar
version check and subsequent contract metadata/build commands so it can run
without an ambient stellar binary on PATH. Reuse the repository’s setup action
or local tool installation for CI, or provide the expected version through the
existing CI mock path, while preserving the current version validation and cargo
test behavior.

---

Nitpick comments:
In `@deploy_mainnet.sh`:
- Around line 417-427: Remove the unused assert_pending_events_version function
from deploy_mainnet.sh, leaving assert_pending_events_upgrade as the sole helper
for pending events upgrade validation, including wasm_hash checks.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7be80978-241e-4cf8-82d4-79c278da6fa0

📥 Commits

Reviewing files that changed from the base of the PR and between 8e15770 and bc15269.

⛔ Files ignored due to path filters (6)
  • Cargo.lock is excluded by !**/*.lock
  • contracts/compatibility/fixtures/events-1.3.0-sdk23.wasm is excluded by !**/*.wasm
  • contracts/compatibility/fixtures/events-1.5.0-sdk27.wasm is excluded by !**/*.wasm
  • contracts/compatibility/fixtures/mainnet-events-1.1.0-sdk23.wasm is excluded by !**/*.wasm
  • contracts/compatibility/fixtures/mainnet-profile-1.1.0-sdk23.wasm is excluded by !**/*.wasm
  • contracts/compatibility/fixtures/profile-1.2.0-sdk27.wasm is excluded by !**/*.wasm
📒 Files selected for processing (30)
  • .github/actions/setup-rust-stellar/action.yml
  • .github/workflows/rustfmt.yml
  • .github/workflows/verify-build.yml
  • .gitignore
  • AGENTS.md
  • BACKLOG.md
  • contracts/compatibility/Cargo.toml
  • contracts/compatibility/fixtures/mainnet-state-63617727.json
  • contracts/compatibility/fixtures/manifest.json
  • contracts/compatibility/src/lib.rs
  • contracts/compatibility/test_snapshots/exact_mainnet_snapshot_survives_h6_upgrade_to_sdk27.1.json
  • contracts/compatibility/test_snapshots/sdk23_pre27_prize_and_cancellation_keys_work_after_upgrade.1.json
  • contracts/compatibility/test_snapshots/sdk23_v110_rows_survive_h6_upgrade_to_sdk27.1.json
  • contracts/events/src/storage.rs
  • contracts/events/src/tests/bounty_pillar.rs
  • contracts/events/src/tests/escrow_fee_math.rs
  • contracts/events/src/tests/hackathon_pillar.rs
  • contracts/profile/src/storage.rs
  • deploy_and_upgrade.sh
  • deploy_mainnet.sh
  • docs/DEPLOYMENT.md
  • docs/contract-ops-runbook.md
  • docs/mainnet-deploy-runbook.md
  • docs/sdk27-compatibility-fixtures.md
  • scripts/capture-mainnet-compat-snapshot.sh
  • scripts/deploy/deploy.sh
  • scripts/deploy_and_upgrade.sh
  • scripts/test-mainnet-upgrade-guards.sh
  • scripts/test-sdk27-compat.sh
  • scripts/testdata/mock-stellar
💤 Files with no reviewable changes (1)
  • contracts/events/src/tests/escrow_fee_math.rs

Comment thread AGENTS.md Outdated
Comment thread contracts/compatibility/src/lib.rs
Comment thread docs/mainnet-deploy-runbook.md Outdated
Comment thread docs/sdk27-compatibility-fixtures.md Outdated
Comment thread scripts/test-sdk27-compat.sh

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
.github/workflows/verify-build.yml (1)

56-62: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Syntax-check every changed deployment script.

The current checks omit deploy_and_upgrade.sh, scripts/deploy/deploy.sh, and scripts/deploy_and_upgrade.sh, although they are part of this pinned-build/deployment layer. A Bash syntax regression in those release paths could pass this workflow.

Proposed addition
           bash -n deploy_mainnet.sh
+          bash -n deploy_and_upgrade.sh
           bash -n scripts/capture-mainnet-compat-snapshot.sh
+          bash -n scripts/deploy/deploy.sh
+          bash -n scripts/deploy_and_upgrade.sh
           bash -n scripts/test-sdk27-compat.sh
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/verify-build.yml around lines 56 - 62, Update the “Check
release script syntax” step in the workflow to also run bash -n against
deploy_and_upgrade.sh, scripts/deploy/deploy.sh, and
scripts/deploy_and_upgrade.sh, while preserving the existing syntax checks for
all currently listed deployment scripts.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In @.github/workflows/verify-build.yml:
- Around line 56-62: Update the “Check release script syntax” step in the
workflow to also run bash -n against deploy_and_upgrade.sh,
scripts/deploy/deploy.sh, and scripts/deploy_and_upgrade.sh, while preserving
the existing syntax checks for all currently listed deployment scripts.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bb24301f-6c42-4739-b833-0588e1356163

📥 Commits

Reviewing files that changed from the base of the PR and between bc15269 and 38a40d7.

⛔ Files ignored due to path filters (2)
  • contracts/compatibility/fixtures/events-1.5.0-sdk27.wasm is excluded by !**/*.wasm
  • contracts/compatibility/fixtures/profile-1.2.0-sdk27.wasm is excluded by !**/*.wasm
📒 Files selected for processing (11)
  • .github/workflows/verify-build.yml
  • AGENTS.md
  • contracts/compatibility/fixtures/manifest.json
  • contracts/compatibility/src/lib.rs
  • contracts/compatibility/test_snapshots/exact_mainnet_snapshot_survives_h6_upgrade_to_sdk27.1.json
  • contracts/compatibility/test_snapshots/sdk23_pre27_prize_and_cancellation_keys_work_after_upgrade.1.json
  • contracts/compatibility/test_snapshots/sdk23_v110_rows_survive_h6_upgrade_to_sdk27.1.json
  • deploy_mainnet.sh
  • docs/mainnet-deploy-runbook.md
  • docs/sdk27-compatibility-fixtures.md
  • scripts/test-sdk27-compat.sh
🚧 Files skipped from review as they are similar to previous changes (9)
  • contracts/compatibility/fixtures/manifest.json
  • docs/sdk27-compatibility-fixtures.md
  • scripts/test-sdk27-compat.sh
  • contracts/compatibility/test_snapshots/sdk23_pre27_prize_and_cancellation_keys_work_after_upgrade.1.json
  • contracts/compatibility/src/lib.rs
  • AGENTS.md
  • contracts/compatibility/test_snapshots/sdk23_v110_rows_survive_h6_upgrade_to_sdk27.1.json
  • docs/mainnet-deploy-runbook.md
  • deploy_mainnet.sh

coderabbitai[bot]
coderabbitai Bot previously approved these changes Jul 24, 2026
@0xdevcollins

0xdevcollins commented Jul 28, 2026

Copy link
Copy Markdown
Collaborator

Solid work, this closes #91. Verified the key bits:

  • is_op_seen legacy fix is correct. Reading old OpSeen(BytesN<32>) keys works, and mark_op_seen still only writes the namespaced key so fix(events): namespace OpSeen by authorizing caller (follow-up to #68/#95) #96's squat fix stays intact.
  • Fixtures are the real mainnet wasms (hashes match 2a8789bf / b9e3500c in BACKLOG).
  • 3 compat tests pass, including the real mainnet snapshot. Proves the upgrade is decode-safe.

One blocker: this reverses the snapshot rule and blinds the scanner. CLAUDE.md says never commit snapshots because big diffs make the scanners skip. This PR commits ~12k lines of snapshots, un-ignores them, and flips that rule in AGENTS.md. Result: Almanax skipped this PR, so the storage.rs and mainnet-deploy changes got no security scan.

Fix before merge:

  1. Revert the AGENTS.md + .gitignore rule changes. If we want committed compat snapshots, we'll decide that in CLAUDE.md and make the scanner ignore that dir instead.
  2. Rebase on testnet (missing fix(profile,events): replace saturating_add with checked_add + typed errors #101).
  3. Let Almanax run once the diff is scannable.

Heads up: I didn't line-by-line the 698-line deploy_mainnet.sh or the 770-line compat lib.rs those need a pass with the scanner seeing them.

Close. The fix and fixtures are exactly right.

@chigozzdevv
chigozzdevv force-pushed the issue-91-sdk27-storage-compat branch from f620ae7 to de91a52 Compare July 28, 2026 01:02
@chigozzdevv

Copy link
Copy Markdown
Contributor Author

Addressed the requested changes:

The rebased GitHub build and rustfmt checks pass. Almanax still reports neutral because the account has used 299 of 300 monthly units and this scan requires 7. It will need to be rerun after quota is available.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Verify sdk 23→27 storage decode compatibility before mainnet protocol-27 upgrade

2 participants