docs: improve inline documentation for overflow prevention

.env.example

@@ -0,0 +1,18 @@
+# Stellar Network Configuration
+NEXT_PUBLIC_STELLAR_NETWORK=TESTNET # Target Stellar network: TESTNET or PUBLIC
+NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org # Soroban RPC endpoint for contract interaction
+
+# Smart Contract Configuration
+NEXT_PUBLIC_STELLAR_CONTRACT_ID= # The deployed Soroban FiatBridge contract ID (starts with 'C')
+NEXT_PUBLIC_XLM_SAC_ID=CAS3J7GYCCXG7WS6Y7G2HGDV6X6YHS2753T55E4YDLM5D35W6N6YJLYE # XLM Stellar Asset Contract ID (Native asset)
+
+# AI Assistant Configuration
+GEMINI_API_KEY= # Google Gemini API key for AI-powered bridge assistance
+
+# Payout Provider Configuration
+PAYOUT_PROVIDER=paystack # Payout provider name (e.g., paystack)
+PAYSTACK_SECRET_KEY= # Paystack secret key for initiating bank transfers and verifying webhooks
+
+# Optional: Monitoring & Security
+# SENTRY_DSN= # Optional: Sentry DSN for error tracking
+# ADMIN_IP_ALLOWLIST= # Optional: Comma-separated list of IPs allowed for admin routes

.github/workflows/auto-merge.yml

@@ -0,0 +1,129 @@
+name: Auto-Merge PRs
+
+# Fires when a PR is opened/updated (to enable native auto-merge) and when a
+# check suite completes (to directly merge if every check went green and the
+# branch has no conflicts).
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches: [main]
+  check_suite:
+    types: [completed]
+
+permissions:
+  contents: write        # needed to merge
+  pull-requests: write   # needed to update PR auto-merge flag
+
+jobs:
+  # ── 1. Enable GitHub's built-in auto-merge the moment a PR is opened / updated
+  enable-auto-merge:
+    name: Enable auto-merge on PR
+    if: |
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable squash auto-merge
+        # continue-on-error so a repo without branch-protection rules doesn't
+        # block the workflow; the merge-when-green job is the primary mechanism.
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh pr merge --auto --squash \
+            --repo "${{ github.repository }}" \
+            "${{ github.event.pull_request.number }}"
+
+  # ── 2. Directly merge when ALL check runs on the suite pass ──────────────
+  merge-when-green:
+    name: Merge PR when all checks pass
+    if: |
+      github.event_name == 'check_suite' &&
+      github.event.check_suite.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Merge passing, conflict-free PRs
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const headSha = context.payload.check_suite.head_sha;
+            const prs     = context.payload.check_suite.pull_requests ?? [];
+
+            if (prs.length === 0) {
+              core.info('No open PRs linked to this check suite — nothing to do.');
+              return;
+            }
+
+            for (const pr of prs) {
+              // Fetch the full PR object (includes mergeable + draft fields)
+              const { data: pull } = await github.rest.pulls.get({
+                owner:       context.repo.owner,
+                repo:        context.repo.repo,
+                pull_number: pr.number,
+              });
+
+              if (pull.draft) {
+                core.info(`PR #${pr.number} is a draft — skipping.`);
+                continue;
+              }
+
+              if (pull.state !== 'open') {
+                core.info(`PR #${pr.number} is already closed — skipping.`);
+                continue;
+              }
+
+              // GitHub computes mergeability asynchronously; poll once if null.
+              let mergeable = pull.mergeable;
+              if (mergeable === null) {
+                core.info(`PR #${pr.number}: mergeability not yet computed, waiting 6 s…`);
+                await new Promise(r => setTimeout(r, 6000));
+                const { data: refreshed } = await github.rest.pulls.get({
+                  owner:       context.repo.owner,
+                  repo:        context.repo.repo,
+                  pull_number: pr.number,
+                });
+                mergeable = refreshed.mergeable;
+              }
+
+              if (mergeable === false) {
+                core.info(`PR #${pr.number} has merge conflicts — skipping.`);
+                continue;
+              }
+
+              // Confirm every completed check run passed (or was neutral/skipped).
+              const { data: { check_runs } } = await github.rest.checks.listForRef({
+                owner:    context.repo.owner,
+                repo:     context.repo.repo,
+                ref:      headSha,
+                per_page: 100,
+              });
+
+              const failing = check_runs.filter(r =>
+                r.status === 'completed' &&
+                !['success', 'skipped', 'neutral'].includes(r.conclusion)
+              );
+
+              if (failing.length > 0) {
+                core.info(
+                  `PR #${pr.number} has failing checks ` +
+                  `(${failing.map(r => r.name).join(', ')}) — skipping.`
+                );
+                continue;
+              }
+
+              // Everything is green and conflict-free — merge!
+              try {
+                await github.rest.pulls.merge({
+                  owner:          context.repo.owner,
+                  repo:           context.repo.repo,
+                  pull_number:    pr.number,
+                  merge_method:   'squash',
+                  commit_title:   `${pull.title} (#${pr.number})`,
+                  commit_message: pull.body ?? '',
+                });
+                core.info(`✅  Auto-merged PR #${pr.number}: ${pull.title}`);
+              } catch (err) {
+                core.error(`Failed to merge PR #${pr.number}: ${err.message}`);
+              }
+            }

.github/workflows/changelog.yml

@@ -0,0 +1,35 @@
+name: Changelog
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  update-changelog:
+    name: Generate and Commit CHANGELOG
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate CHANGELOG.md
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --verbose --output CHANGELOG.md
+
+      - name: Commit and push CHANGELOG.md
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          file_pattern: CHANGELOG.md
+          commit_message: "chore(changelog): update changelog [skip ci]"
+          commit_user_name: github-actions[bot]
+          commit_user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/contract-tests.yml

@@ -0,0 +1,32 @@
+name: Contract Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Run cargo test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Rust stable toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+          targets: wasm32-unknown-unknown
+
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: stellar-contracts -> target
+
+      - name: Run clippy (deny warnings)
+        run: cd stellar-contracts && cargo clippy --all-targets --all-features -- -D warnings
+
+      - name: Run contract tests
+        run: cd stellar-contracts && cargo test

.github/workflows/contracts.yml

@@ -0,0 +1,65 @@
+name: Smart Contract CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "stellar-contracts/**"
+      - ".github/workflows/contracts.yml"
+  push:
+    branches: [main]
+    paths:
+      - "stellar-contracts/**"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test & Build
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: stellar-contracts
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+          components: clippy
+          targets: wasm32-unknown-unknown
+
+      - name: Cache Cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            stellar-contracts/target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('stellar-contracts/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Run tests
+        run: cargo test
+
+      - name: Build WASM release
+        run: cargo build --target wasm32-unknown-unknown --release
+
+      - name: Check WASM size
+        run: |
+          ls -la target/wasm32-unknown-unknown/release/*.wasm
+          SIZE=$(ls -la target/wasm32-unknown-unknown/release/*.wasm | awk '{print $5}')
+          echo "Current WASM size: $SIZE bytes"
+          if [ $SIZE -gt 55000 ]; then
+            echo "Error: WASM size $SIZE bytes exceeds 55 KB limit"
+            exit 1
+          fi
+
+      - name: Run clippy (deny warnings)
+        run: cargo clippy --all-targets --all-features -- -D warnings

.github/workflows/deploy-futurenet.yml

@@ -0,0 +1,113 @@
+name: Deploy FiatBridge to Futurenet
+
+on:
+  push:
+    branches:
+      - 'release/**'
+    paths:
+      - 'stellar-contracts/**'
+      - '.github/workflows/deploy-futurenet.yml'
+
+permissions:
+  contents: read
+  deployments: write
+
+jobs:
+  deploy:
+    name: Deploy to Futurenet
+    runs-on: ubuntu-latest
+    environment: futurenet
+
+    defaults:
+      run:
+        working-directory: stellar-contracts
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+          targets: wasm32-unknown-unknown
+
+      - name: Install Soroban CLI
+        run: |
+          curl -s https://raw.githubusercontent.com/stellar/rs-soroban-sdk/master/soroban-env/install-soroban.sh | bash
+          soroban --version
+
+      - name: Cache Cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            stellar-contracts/target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('stellar-contracts/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Build contract
+        run: cargo build --target wasm32-unknown-unknown --release
+
+      - name: Deploy to Futurenet
+        id: deploy
+        env:
+          FUTURENET_ADMIN_SECRET_KEY: ${{ secrets.FUTURENET_ADMIN_SECRET_KEY }}
+          FUTURENET_RPC_URL: https://rpc-futurenet.stellar.org
+          FUTURENET_NETWORK_PASSPHRASE: 'Test SDF Future Network ; April 2020'
+          OUTPUT_FILE: ./contract_id_futurenet.txt
+        run: |
+          chmod +x ../scripts/deploy_fiat_bridge_futurenet.sh
+          ../scripts/deploy_fiat_bridge_futurenet.sh
+
+          # Pass outputs to GitHub Actions context
+          CONTRACT_ID=$(cat "$OUTPUT_FILE")
+          echo "contract_id=$CONTRACT_ID" >> $GITHUB_OUTPUT
+
+      - name: Upload contract ID artifact
+        if: success()
+        uses: actions/upload-artifact@v4
+        with:
+          name: contract-deployment-${{ github.sha }}
+          path: stellar-contracts/contract_id_futurenet.txt
+          retention-days: 90
+
+      - name: Create deployment status
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const status = '${{ job.status }}' === 'success' ? 'success' : 'failure';
+            const conclusion = status === 'success' ? '✅ Deployment successful' : '❌ Deployment failed';
+
+            github.rest.repos.createDeployment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: context.ref,
+              environment: 'futurenet',
+              required_contexts: [],
+              auto_merge: false,
+              description: 'FiatBridge Smart Contract Deployment'
+            })
+
+      - name: Post deployment summary
+        if: success()
+        run: |
+          echo "## 🎉 Deployment Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Status:** ✅ Success" >> $GITHUB_STEP_SUMMARY
+          echo "**Environment:** Futurenet" >> $GITHUB_STEP_SUMMARY
+          echo "**Contract ID:** ${{ steps.deploy.outputs.contract_id }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Branch:** ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Commit:** ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
+
+      - name: Notify on failure
+        if: failure()
+        run: |
+          echo "## ❌ Deployment Failed" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Environment: Futurenet" >> $GITHUB_STEP_SUMMARY
+          echo "Branch: ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "Check the logs for details." >> $GITHUB_STEP_SUMMARY