From 6abb09e4eb26b8a1cbd5f059d8ff1edb8ce43f66 Mon Sep 17 00:00:00 2001 From: JACOB STANLEY Date: Sat, 20 Jun 2026 22:47:54 +0100 Subject: [PATCH] https://github.com/Menjay7/StellarBounty.git --- README.md | 2 ++ docs/architecture.md | 77 ++++++++++++++++++++++++++++++++++++++++++++ docs/deployment.md | 38 ++++++++++++++++++++++ docs/operations.md | 30 +++++++++++++++++ 4 files changed, 147 insertions(+) create mode 100644 docs/architecture.md diff --git a/README.md b/README.md index 477f5c5..173b228 100644 --- a/README.md +++ b/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 ``` diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..06f80c0 --- /dev/null +++ b/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 diff --git a/docs/deployment.md b/docs/deployment.md index 6c228d0..e3c56a0 100644 --- a/docs/deployment.md +++ b/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 --network testnet + +# Deploy to mainnet (example) +stellar contract deploy --wasm target/wasm32-unknown-unknown/release/stellar_bounty_contracts.wasm --source --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. diff --git a/docs/operations.md b/docs/operations.md index 5d0d498..3d58825 100644 --- a/docs/operations.md +++ b/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