ISSUE-24: Automate milestone release with backend oracle

[Bug-Hunter-X]

Overview

This PR automates milestone release execution for high-confidence jobs so clients no longer need to manually approve final payment when the AI result is trusted. It adds a backend oracle flow that enforces the Issue-23 confidence threshold, constructs and submits the Soroban release transaction, records the release in the backend, and notifies the client with the automated release result and test output.

Related Issue

Closes #165

Changes

⚙️ Backend Oracle Auto-Release

• [MODIFY] backend/app/api/v1/endpoints/payments.py

  • Added a new backend oracle endpoint for automated escrow release.
  • Enforced the > 0.90 confidence threshold before triggering auto-release.
  • Validated the oracle token via X-Oracle-Token.
  • Returned client-facing release details, transaction info, and delivered test results.

• [MODIFY] backend/app/services/payments.py

  • Added the automated milestone release service flow.
  • Reused the existing payment model to record successful auto-releases.
  • Prevented duplicate releases by reusing existing released payment records when present.

🔐 Soroban Oracle Signing

• [MODIFY] backend/app/services/soroban.py

  • Added backend-oracle signing support for Soroban escrow release transactions.
  • Built, prepared, signed, and submitted the release contract invocation.
  • Returned the prepared XDR, signed XDR, and transaction hash for traceability.

• [MODIFY] backend/app/core/config.py

  • Added Soroban network/base-fee settings.
  • Added backend oracle secret/token configuration.
  • Added the auto-release confidence threshold configuration.

🧾 Client Notification

• [MODIFY] backend/app/services/email.py
  • Added automated milestone release email notifications.
  • Included booking ID, transaction hash, confidence score, and test results in the client message.

⛓️ Escrow Contract Automation

• [MODIFY] contracts/escrow/src/lib.rs

  • Updated escrow release logic to support a configured oracle signer.
  • Added oracle configuration storage on the escrow contract.
  • Allowed release to succeed when called by either the client or the configured oracle.

• [MODIFY] contracts/escrow/src/test.rs

  • Added a targeted happy-path contract test for oracle-driven release.
  • Verified that oracle release transfers funds on-chain and marks escrow as released.

🧪 Tests

• [ADD] backend/app/tests/test_payments_oracle.py
  • Added backend tests for successful auto-release, below-threshold skip behavior, and invalid-oracle-token rejection.

🛠️ Repo Boot Fixes Needed For Testing

• [MODIFY] backend/app/api/v1/api.py

  • Fixed the missing stats import so the backend API loads correctly.

• [MODIFY] backend/app/schemas/user.py

  • Added the missing Enum import so backend schema imports do not fail at startup.

Verification Results

Acceptance Criteria	Status
High-confidence jobs trigger the backend Oracle signing sequence	✅
Escrow is successfully released on-chain without client manual intervention	✅
Client is notified of the automated release and provided the test results	✅

How to Test

# 1. Confirm you're on the branch
git branch --show-current

# 2. Run the targeted backend oracle tests
cd backend
DEBUG=False SECRET_KEY=test-secret-key DATABASE_URL=sqlite:///./test.db REQUIRE_EMAIL_VERIFICATION=False .venv314/bin/pytest app/tests/test_payments_oracle.py app/tests/test_main.py -q

# 3. Run the targeted escrow contract oracle-release test
cd ../contracts
cargo test -p escrow test_happy_path_oracle_release_funds_to_artisan -- --nocapture

# 4. Optional: inspect the changed files
git diff -- backend/app/api/v1/api.py backend/app/api/v1/endpoints/payments.py backend/app/core/config.py backend/app/schemas/user.py backend/app/services/email.py backend/app/services/payments.py backend/app/services/soroban.py backend/app/tests/test_payments_oracle.py contracts/escrow/src/lib.rs contracts/escrow/src/test.rs

Screenshots

✅ Backend oracle tests pass

A screenshot of:

cd backend
DEBUG=False SECRET_KEY=test-secret-key DATABASE_URL=sqlite:///./test.db REQUIRE_EMAIL_VERIFICATION=False .venv314/bin/pytest app/tests/test_payments_oracle.py app/tests/test_main.py -q

✅ Escrow oracle-release contract test passes

A screenshot of:

cd contracts
cargo test -p escrow test_happy_path_oracle_release_funds_to_artisan -- --nocapture

`

[drips-wave]

@Bug-Hunter-X 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