Implement Proposal Timelock: Queued State, Veto, and Execution Countdown (#586)

.env.example

@@ -1,35 +1,49 @@
 # LearnVault environment template for local development. Copy this file to `.env`.
 
+# Optional: comma-separated admin email recipients for server notifications (flags, etc.)
+ADMIN_EMAILS=admin@example.com
+
 # Scaffold / local tooling
+# Environment profile for Stellar scaffold scripts and CLI (`development`, `testing`, `staging`, `production`).
 STELLAR_SCAFFOLD_ENV=development
+# Stellar CLI config directory. See https://developers.stellar.org/docs/tools/cli/stellar-cli#stellar-config-dir
 XDG_CONFIG_HOME=.config
 
-# Docker Compose local development ports
-DEV_DOCKER_FRONTEND_PORT=5173
-DEV_DOCKER_API_PORT=3001
-DEV_DOCKER_POSTGRES_PORT=5432
-DEV_DOCKER_REDIS_PORT=6379
-DEV_DOCKER_STELLAR_PORT=8000
+# --- Stellar network (frontend) ---
+# Prefix with PUBLIC_ so Vite exposes these to the browser.
+# More on networks: https://developers.stellar.org/docs/networks
+
+# Default: local scaffold (Horizon + Soroban on localhost)
+PUBLIC_STELLAR_NETWORK=LOCAL
+PUBLIC_STELLAR_NETWORK_PASSPHRASE="Standalone Network ; February 2017"
+PUBLIC_STELLAR_RPC_URL=http://localhost:8000/rpc
+PUBLIC_STELLAR_HORIZON_URL=http://localhost:8000
+
+# Uncomment for Testnet instead:
+# PUBLIC_STELLAR_NETWORK=TESTNET
+# PUBLIC_STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
+# PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+# PUBLIC_STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
 
-# Stellar network
-PUBLIC_STELLAR_NETWORK=TESTNET
-PUBLIC_STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
-PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
-PUBLIC_STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
+# Uncomment for Mainnet:
+# PUBLIC_STELLAR_NETWORK=MAINNET
+# PUBLIC_STELLAR_NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"
+# PUBLIC_STELLAR_RPC_URL=
+# PUBLIC_STELLAR_HORIZON_URL=
 
-# LearnVault contract IDs
+# --- LearnVault contract IDs (populate after deploy; Vite `VITE_*` vars) ---
 VITE_LEARN_TOKEN_CONTRACT_ID=
 VITE_GOVERNANCE_TOKEN_CONTRACT_ID=
-VITE_SCHOLAR_NFT_CONTRACT_ID=
 VITE_COURSE_MILESTONE_CONTRACT_ID=
-VITE_SCHOLARSHIP_TREASURY_CONTRACT_ID=
 VITE_MILESTONE_ESCROW_CONTRACT_ID=
+VITE_SCHOLARSHIP_TREASURY_CONTRACT_ID=
+VITE_SCHOLAR_NFT_CONTRACT_ID=
 
-# USDC on Stellar Testnet
-VITE_USDC_CONTRACT_ID=
+# USDC on Stellar — the app reads either name (see `src/util/usdc.ts`).
 PUBLIC_USDC_CONTRACT_ID=
+VITE_USDC_CONTRACT_ID=
 
-# Legacy frontend aliases still read by older screens/hooks
+# Legacy `PUBLIC_*` aliases still read by older screens/hooks (optional).
 PUBLIC_LEARN_TOKEN_CONTRACT=
 PUBLIC_GOVERNANCE_TOKEN_CONTRACT=
 PUBLIC_SCHOLAR_NFT_CONTRACT=
@@ -38,14 +52,20 @@ PUBLIC_SCHOLARSHIP_TREASURY_CONTRACT=
 PUBLIC_MILESTONE_ESCROW_CONTRACT=
 PUBLIC_SCHOLARSHIP_GOVERNANCE_CONTRACT=
 
-# Backend API
-VITE_API_URL=http://localhost:4000
-VITE_API_BASE_URL=/api
+# --- Backend / API (frontend → server) ---
+# Backend runs on port 4000 by default (`npm run dev:server` / CONTRIBUTING.md).
 VITE_SERVER_URL=http://localhost:4000
+# Optional override when the API is on a different origin; leave empty to derive from `VITE_SERVER_URL`.
+VITE_API_URL=
+# Relative API prefix used by some upload and scholar flows.
+VITE_API_BASE_URL=/api
 
-# Docker Compose notes:
-# - `npm run dev:docker` injects LOCAL Stellar endpoints for the frontend service.
-# - Override the DEV_DOCKER_* values above if these host ports are already in use.
+# --- Email (optional for local) ---
+RESEND_API_KEY=
+EMAIL_FROM=notifications@learnvault.xyz
+FRONTEND_URL=http://localhost:3000
 
-# IPFS gateway (optional)
+# --- IPFS / Pinata (optional for uploads) ---
+PINATA_API_KEY=
+PINATA_SECRET=
 VITE_IPFS_GATEWAY_URL=https://gateway.pinata.cloud/ipfs

.github/workflows/deploy-staging.yml

@@ -0,0 +1,286 @@
+name: Staging deployment
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: staging-deploy-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  STAGING_BACKEND_URL: ${{ secrets.STAGING_BACKEND_URL }}
+  STAGING_BACKEND_DEPLOY_TOKEN: ${{ secrets.STAGING_BACKEND_DEPLOY_TOKEN }}
+  STAGING_FRONTEND_URL: ${{ secrets.STAGING_FRONTEND_URL }}
+  STAGING_FRONTEND_DEPLOY_TOKEN: ${{ secrets.STAGING_FRONTEND_DEPLOY_TOKEN }}
+  STAGING_API_URL: ${{ secrets.STAGING_API_URL }}
+  STAGING_URL: ${{ secrets.STAGING_URL }}
+  STAGING_DATABASE_URL: ${{ secrets.STAGING_DATABASE_URL || secrets.DATABASE_URL || '' }}
+  STAGING_REDIS_URL: ${{ secrets.STAGING_REDIS_URL || secrets.REDIS_URL || '' }}
+  STELLAR_SECRET_KEY: ${{ secrets.STAGING_STELLAR_SECRET_KEY || secrets.STELLAR_SECRET_KEY || '' }}
+
+jobs:
+  build-and-test:
+    name: Build and validate staging artifacts
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Add Wasm target and native dependencies
+        run: |
+          rustup target add wasm32v1-none
+          sudo apt-get update
+          sudo apt-get install -y libudev-dev libdbus-1-dev pkg-config
+
+      - name: Install stellar-scaffold CLI
+        uses: cargo-bins/cargo-binstall@main
+        with:
+          tool: stellar-scaffold-cli
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install frontend dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Run lint and formatting checks
+        run: |
+          npm run lint
+          npx prettier . --check
+
+      - name: Validate database migration safety
+        run: |
+          if [ -d "server/prisma" ]; then
+            npx prisma migrate dev --dry-run
+          elif [ -f "server/knexfile.js" ]; then
+            npx knex migrate:list
+          else
+            echo "No standard migration tool detected, skipping dry-run."
+          fi
+
+      - name: Build scaffold and generate contract clients
+        run: |
+          STELLAR_SCAFFOLD_ENV=staging stellar-scaffold build --build-clients 2>&1 | tee build_clients.log
+
+      - name: Verify generated clients
+        run: |
+          FAILED=$(grep -Eo "Failed: [0-9]+" build_clients.log | awk '{print $2}')
+          if [ -n "$FAILED" ] && [ "$FAILED" -gt 0 ]; then
+            echo "Client generation summary check failed: Failed: $FAILED"
+            exit 1
+          fi
+
+      - name: Build frontend and contract packages
+        run: |
+          npm run install:contracts
+          npm run build
+
+      - name: Run test suite
+        run: npm test --if-present
+
+  deploy-contracts:
+    name: Deploy contracts to testnet
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    environment: staging
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install Stellar CLI
+        run: npm install -g @stellar/stellar-cli
+
+      - name: Deploy contracts to Stellar Testnet
+        env:
+          STELLAR_SECRET_KEY: ${{ env.STELLAR_SECRET_KEY }}
+        run: |
+          if [ -z "${STELLAR_SECRET_KEY}" ]; then
+            echo "STAGING_STELLAR_SECRET_KEY or STELLAR_SECRET_KEY is not configured."
+            exit 1
+          fi
+          chmod +x scripts/deploy-testnet.sh
+          ./scripts/deploy-testnet.sh
+
+  deploy-backend:
+    name: Deploy backend and run migrations
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    environment: staging
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install backend dependencies
+        run: npm ci --legacy-peer-deps
+        working-directory: server
+
+      - name: Build backend
+        run: npm run build
+        working-directory: server
+
+      - name: Run database migrations
+        env:
+          DATABASE_URL: ${{ env.STAGING_DATABASE_URL }}
+          NODE_ENV: production
+        run: |
+          if [ -z "${DATABASE_URL}" ]; then
+            echo "STAGING_DATABASE_URL or DATABASE_URL is not configured. Cannot run migrations."
+            exit 1
+          fi
+          npm run migrate
+        working-directory: server
+
+      - name: Deploy backend to staging provider
+        if: ${{ env.STAGING_BACKEND_URL != '' && env.STAGING_BACKEND_DEPLOY_TOKEN != '' }}
+        run: |
+          echo "Triggering backend deployment webhook..."
+          curl -fsSL -X POST \
+            -H "Authorization: Bearer ${STAGING_BACKEND_DEPLOY_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d '{"branch":"main","environment":"staging"}' \
+            "${STAGING_BACKEND_URL}"
+
+      - name: Backend deploy webhook skipped
+        if: ${{ env.STAGING_BACKEND_URL == '' || env.STAGING_BACKEND_DEPLOY_TOKEN == '' }}
+        run: |
+          echo "Skipping backend deployment webhook because STAGING_BACKEND_URL or STAGING_BACKEND_DEPLOY_TOKEN is not configured."
+
+  deploy-frontend:
+    name: Deploy frontend to staging
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    environment: staging
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install frontend dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build frontend
+        run: npm run build
+
+      - name: Deploy frontend to staging provider
+        if: ${{ env.STAGING_FRONTEND_URL != '' && env.STAGING_FRONTEND_DEPLOY_TOKEN != '' }}
+        run: |
+          echo "Triggering frontend deployment webhook..."
+          curl -fsSL -X POST \
+            -H "Authorization: Bearer ${STAGING_FRONTEND_DEPLOY_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d '{"branch":"main","environment":"staging"}' \
+            "${STAGING_FRONTEND_URL}"
+
+      - name: Frontend deploy webhook skipped
+        if: ${{ env.STAGING_FRONTEND_URL == '' || env.STAGING_FRONTEND_DEPLOY_TOKEN == '' }}
+        run: |
+          echo "Skipping frontend deployment webhook because STAGING_FRONTEND_URL or STAGING_FRONTEND_DEPLOY_TOKEN is not configured."
+
+  smoke-test:
+    name: Run staging smoke tests
+    needs:
+      - deploy-contracts
+      - deploy-backend
+      - deploy-frontend
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install Stellar CLI
+        run: npm install -g @stellar/stellar-cli
+
+      - name: Run contract smoke tests
+        run: chmod +x scripts/smoke-test-contracts.sh && ./scripts/smoke-test-contracts.sh
+
+      - name: Verify staging API availability
+        if: ${{ env.STAGING_API_URL != '' }}
+        run: |
+          echo "Checking staging API at ${STAGING_API_URL}"
+          curl -fSL "${STAGING_API_URL}" -o /dev/null
+
+      - name: Staging API check skipped
+        if: ${{ env.STAGING_API_URL == '' }}
+        run: |
+          echo "Skipping staging API availability verification because STAGING_API_URL is not configured."
+
+  comment-on-pr:
+    name: Post staging deployment status to merged PR
+    needs: smoke-test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Post deployment status to PR
+        uses: actions/github-script@v7
+        env:
+          STAGING_URL: ${{ env.STAGING_URL }}
+          STAGING_API_URL: ${{ env.STAGING_API_URL }}
+          STAGING_FRONTEND_URL: ${{ env.STAGING_FRONTEND_URL }}
+          STAGING_BACKEND_URL: ${{ env.STAGING_BACKEND_URL }}
+        with:
+          script: |
+            const { data: pulls } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              commit_sha: context.sha,
+            });
+
+            const mergedPR = pulls.find(pr => pr.merged_at);
+            if (!mergedPR) {
+              console.log('No merged PR associated with this commit. Skipping PR comment.');
+              return;
+            }
+
+            const body = `## Staging deployment completed\n\n` +
+              `- **Frontend:** ${process.env.STAGING_FRONTEND_URL || 'not configured'}\n` +
+              `- **Backend:** ${process.env.STAGING_BACKEND_URL || 'not configured'}\n` +
+              `- **API:** ${process.env.STAGING_API_URL || 'not configured'}\n` +
+              `- **Contracts:** deployed to Stellar Testnet\n\n` +
+              `Smoke tests ran after deployment. If a staging URL is missing, configure the corresponding repository secret.\n`;
+
+            await github.rest.issues.createComment({
+              issue_number: mergedPR.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body,
+            });

.qwen/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)"
+    ]
+  },
+  "$version": 3
+}