[ARCHITECTURE] Soroban contracts are immutable - no upgrade mechanism

README.md

@@ -4,6 +4,8 @@ A decentralized bounty and task marketplace built on the Stellar network. Projec
 
 > **Status:** Early development — contributors welcome. Browse [open issues](https://github.com/BountyOnChain/StellarBounty/issues) to get started.
 
+> **Important:** Soroban contracts are immutable. Once deployed, they cannot be upgraded or modified. See [Architecture](docs/architecture.md) for details.
+
 ## Structure
 
 ```

docs/architecture.md

@@ -0,0 +1,77 @@
+# Architecture
+
+## Overview
+
+StellarBounty is a decentralized bounty and task marketplace built on the Stellar network using Soroban smart contracts. The system consists of three main components:
+
+- **Frontend**: Next.js 14 application for user interaction
+- **Backend**: NestJS REST API for business logic and data persistence
+- **Contracts**: Soroban smart contracts for on-chain escrow and payouts
+
+## Smart Contract Architecture
+
+### Contract Immutability
+
+**Critical Constraint:** Soroban contracts are immutable. Once deployed, they cannot be upgraded or modified. This is a fundamental architectural limitation of the Soroban platform.
+
+#### Implications
+
+1. **No Upgrade Mechanism**: There is no built-in upgradeability pattern for Soroban contracts. Unlike Ethereum where proxy patterns can enable upgrades, Soroban contracts are permanently fixed after deployment.
+
+2. **Design for Permanence**: All contract logic must be thoroughly tested and audited before deployment, as bugs cannot be fixed post-deployment.
+
+3. **Migration Strategy**: If contract updates are required, a new contract must be deployed and users must migrate to the new contract address manually.
+
+4. **Initialization Protection**: The current contract implements protection against re-initialization to prevent accidental state corruption (see `ContractError::AlreadyInitialized`).
+
+#### Current Contract Design
+
+The `EscrowContract` in `apps/contracts/src/lib.rs` is designed with immutability in mind:
+
+- **Single Initialization**: The `initialize` function can only be called once per contract instance
+- **Fixed Parameters**: Owner, amount, token address, arbitrator, and timelock duration are set at initialization and cannot be changed
+- **No Admin Functions**: There are no administrative functions that could modify contract behavior post-deployment
+- **Time-locked Operations**: Critical operations (approve, cancel, resolve) use a timelock mechanism to provide safety while maintaining immutability
+
+#### Testing Considerations
+
+The contract includes comprehensive test coverage, including:
+- `test_reinitialize_after_deploy_errs_to_protect_upgrade_state`: Verifies that contracts cannot be re-initialized after deployment
+- Full lifecycle testing for all bounty states
+- Edge case handling for unauthorized access attempts
+
+### Contract State Machine
+
+The bounty contract follows a strict state machine:
+
+```
+Created → Funded → InProgress → UnderReview → Completed
+                ↓                 ↓
+              Cancelled         Disputed → Completed
+```
+
+Each state transition is protected by authorization checks and status validation.
+
+## Backend Architecture
+
+The NestJS backend provides:
+
+- REST API endpoints for frontend integration
+- PostgreSQL database for off-chain data persistence
+- JWT-based authentication
+- Integration with Stellar network for contract interactions
+
+## Frontend Architecture
+
+The Next.js frontend provides:
+
+- User interface for bounty creation and management
+- Integration with backend API
+- Stellar wallet integration for on-chain interactions
+
+## Security Considerations
+
+1. **Contract Immutability**: No upgrade mechanism means thorough testing is essential
+2. **Time-lock Operations**: Critical operations are time-locked to prevent rushed decisions
+3. **Authorization**: All state changes require proper authorization from relevant parties
+4. **Arbitration**: Dispute resolution mechanism built into contract logic

docs/deployment.md

@@ -1,5 +1,43 @@
 # Deployment
 
+## Smart Contract Deployment
+
+**Critical Constraint:** Soroban contracts are immutable. Once deployed, they cannot be upgraded or modified. This is a fundamental architectural limitation of the Soroban platform.
+
+### Pre-Deployment Checklist
+
+Before deploying Soroban contracts to any network:
+
+- **Thorough Testing**: All contract logic must be comprehensively tested. The current contract includes protection against re-initialization (`ContractError::AlreadyInitialized`) to prevent accidental state corruption.
+- **Audit**: Consider a professional security audit for production deployments
+- **Network Selection**: Choose the target network carefully (testnet vs mainnet) as contracts cannot be moved between networks
+- **Parameter Validation**: Ensure all initialization parameters (owner, amount, token address, arbitrator, timelock duration) are correct before deployment
+- **Backup Strategy**: Plan for contract migration in case critical bugs are discovered post-deployment
+
+### Deployment Process
+
+```bash
+cd apps/contracts
+
+# Build WASM for deployment
+cargo build --target wasm32-unknown-unknown --release
+
+# Deploy to testnet (example)
+stellar contract deploy --wasm target/wasm32-unknown-unknown/release/stellar_bounty_contracts.wasm --source <your-account> --network testnet
+
+# Deploy to mainnet (example)
+stellar contract deploy --wasm target/wasm32-unknown-unknown/release/stellar_bounty_contracts.wasm --source <your-account> --network mainnet
+```
+
+### Post-Deployment Considerations
+
+- **Contract Address**: Save the deployed contract address permanently - this cannot be changed
+- **No Upgrades**: If bugs are discovered, a new contract must be deployed and users must migrate manually
+- **State Migration**: Any existing bounty state cannot be transferred to a new contract
+- **Documentation**: Record deployment parameters and contract addresses for future reference
+
+## Backend Deployment
+
 Run the NestJS backend behind a TLS-terminating reverse proxy such as Caddy,
 nginx, or Traefik. Do not expose the backend's plain HTTP port directly to the
 public internet.

docs/operations.md

@@ -1,5 +1,35 @@
 # Operations Runbook
 
+## Smart Contract Operations
+
+**Critical Constraint:** Soroban contracts are immutable. Once deployed, they cannot be upgraded or modified. This affects all operational procedures involving smart contracts.
+
+### Contract Monitoring
+
+- **No Upgrade Path**: Monitor contract behavior carefully as bugs cannot be fixed post-deployment
+- **Event Logging**: Track all contract events for audit trails and debugging
+- **State Verification**: Regularly verify contract state matches expected values
+- **Address Management**: Maintain permanent records of deployed contract addresses
+
+### Incident Response
+
+If critical issues are discovered in deployed contracts:
+
+1. **Assess Impact**: Determine severity and affected users
+2. **Communication**: Notify users of the issue and any workarounds
+3. **Migration Planning**: Plan deployment of new contract instance if necessary
+4. **User Migration**: Guide users to migrate to new contract address
+5. **State Preservation**: Document existing state as it cannot be transferred
+
+### Contract Address Records
+
+Maintain a permanent record of all deployed contract addresses:
+
+| Network | Contract Address | Deployment Date | Notes |
+|---------|------------------|-----------------|-------|
+| testnet | TBD | TBD | Development testing |
+| mainnet | TBD | TBD | Production deployment |
+
 ## Database Backup & Restore
 
 ### Overview