feat(contracts): implement PR Simulation Environment for Smart Contract Playground

[goodness-cpu]

closes #813

##summary

This PR implements the PR Simulation Environment — a comprehensive system that simulates pull requests for Soroban smart contract upgrades directly within the Smart Contract Playground. It validates storage-layout compatibility between contract versions, detects breaking changes, and generates actionable simulation reports before any on-chain upgrade is executed.

✨ Features Implemented

🔗 New Soroban Contract: pr_simulation (contracts/pr_simulation/)

A Soroban-native contract that powers the PR simulation lifecycle:

Function	Description
initialise(admin)	One-time setup, sets authorised auditor
simulate_upgrade(author, title, current_wasm, proposed_wasm, changes)	Submit a PR simulation with storage-layout diffs
approve(caller, id)	Auditor approves a simulation
reject(caller, id)	Auditor rejects a simulation
execute(caller, id)	Mark simulation as executed
get_simulation(id)	Retrieve full simulation record
simulation_count()	Total simulations stored
classify_change(change)	Public view — classify a storage change as SAFE or BREAKING

Storage Compatibility Engine:

• SAFE: identical types, additive keys (new enum variants), renamed-but-compatible keys
• BREAKING: type changes (e.g. u32 → u64 causes XDR deserialisation panic), removed keys (orphaned data)

Security & Lifecycle:

• Admin-gated — only authorised auditors create/finalise simulations
• Immutability after finalisation — approved/rejected records cannot be altered
• WASM validation — rejects all-zero hashes (InvalidWasm error)
• Input validation — empty titles and empty change lists rejected
• Event emission — pr_sim:created, pr_sim:approved, pr_sim:rejected, pr_sim:executed

18 Comprehensive Tests:

• Initialisation (single + double-init panic)
• Safe upgrade simulation (additive key, identical types)
• Breaking upgrade simulation (type change, mixed verdict)
• Unauthorised access rejection
• Empty title / empty changes / zero WASM rejection
• Lifecycle: approve, reject, execute, cannot-execute-unapproved, cannot-double-approve
• classify_change: safe-identical, safe-additive, breaking-type-change, breaking-removed-key
• Views: simulation count, nonexistent lookup
• Immutability: cannot reject approved simulation

🎨 Frontend Component (frontend/src/components/playground/PrSimulationPanel.tsx)

Interactive PR Simulation Panel with two tabs:

• Simulations Tab: expandable cards showing storage-layout diffs

  • SAFE/BREAKING badges with colour coding
  • Type change arrows (u32 → u64)
  • Approve/Reject buttons with live state updates
  • Stats bar (Total PRs / Safe / Breaking counts)
  • Demo data mirrors existing proxy V1→V2 upgrade pattern

• Guide Tab: educational reference

  • SAFE change rules (identical types, additive keys, renames)
  • BREAKING change rules (type changes, removed keys, collisions)
  • Safe migration pattern with before/after code examples

🔌 Playground Integration (frontend/src/app/playground/page.tsx)

• New "PR Simulation" tab in desktop and mobile tab switchers
• Desktop: editor stays visible in left column, PR sim replaces terminal in right
• Mobile: standalone PR Sim view when tab active

📁 File Structure

contracts/
├── Cargo.toml                          # Added pr_simulation workspace member
└── pr_simulation/
    ├── Cargo.toml                      # Contract manifest
    └── src/
        └── lib.rs                      # Core contract + 18 tests (490+ lines)

frontend/src/
├── app/playground/
│   └── page.tsx                        # Integrated PR Sim tab
└── components/playground/
    └── PrSimulationPanel.tsx           # Interactive PR simulation UI (370+ lines)

🛠 Technical Architecture

• Tech Stack: Rust, Soroban SDK 22.0.0, Next.js/React, TypeScript, Tailwind CSS
• Integration: Works alongside existing UUPS proxy pattern (proxy, implementation_v1, implementation_v2)
• Design: Matches existing dark-terminal design language (zinc/red colour scheme, monospace typography)
• Patterns: Follows workspace member conventions, Soroban contracttype/contracterror/contractimpl patterns

🧪 Testing

# Smart contract tests (18 tests)
cd contracts && cargo test -p pr-simulation

# Frontend typecheck
cd frontend && pnpm tsc --noEmit

# Full WASM build
cd contracts && cargo build --target wasm32-unknown-unknown --release

✅ Acceptance Criteria

• Feature is fully functional with storage-layout compatibility checking
• SAFE and BREAKING changes correctly classified
• 18 comprehensive tests covering all lifecycle states
• Code matches existing project style guidelines
• Integration with Smart Contract Playground infrastructure
• Frontend UI matches existing design system
• Documentation updated (contract doc comments, guide panel)

🔄 Integration Points

• Existing proxy infrastructure: Demo data reflects V1→V2 storage migration
• Playground compilation: PR Sim sits alongside compile output terminal
• Future: Wire to backend API for live Soroban simulation data

[vercel]

@goodness-cpu is attempting to deploy a commit to the Ayomide Adeniran's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@goodness-cpu Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits