feat(oracle): implement oracle network contract and off-chain node service (#362)

[s6pa1rta3n-lab]

Summary

Closes #362

Implements the complete Oracle Network system consisting of an on-chain Soroban smart contract and an off-chain persistent node daemon service:

1. On-Chain Oracle Network Contract (contracts/oracle-network):

   • Staked Node Registry: Enforces minimum stake requirement (10 XLM / 100_000_000 stroops) for registration (register_node, deregister_node, get_node). Inactive or under-staked nodes are barred from submitting data.
   • Feed Registry & Configuration: Admin-controlled feed initialization (register_feed, get_feed_config) with configurable freshness window, maximum deviation basis points (max_deviation_bps), and minimum quorum threshold.
   • Data Submission & Median Aggregation:
     • submit_data(node, feed_id, value, timestamp) verifies node authorization, active stake status, and timestamp freshness.
     • Median aggregation computes consensus quote across fresh observations within the freshness window.
     • Outlier detection penalizes anomalous nodes by deducting reputation points (OUTLIER_PENALTY).
   • Slashing & Governance Compatibility:
     • slash_node(caller, node, amount) enforces caller authorization by admin or designated governance contract (set_governance).
     • Compatible with Issue 4 governance contract invocation interface. Automatically deducts stake, applies reputation penalty, and deactivates nodes falling below minimum stake.
   • Adversarial Input Test Suite:
     • Tests for sub-quorum conditions, extreme outlier consensus stability, reputation degradation, governance slashing, deactivation, stale observation rejection, and future timestamp rejection.
   • Backward Compatibility:
     • Retains legacy submit_reading, get_reading, and aggregate methods.

2. Off-Chain Node Daemon Runtime (packages/oracle-node):

   • Persistent Daemon Service: OracleNodeService daemon loop running indefinitely with configurable polling interval (POLL_INTERVAL_MS).
   • Executable CLI Entrypoint: Configured "bin": { "oracle-node": "dist/bin.js" } and "start": "node dist/bin.js" scripts.
   • Modular Data Source Adapters:
     • BackendCreditScoreAdapter: Fetches off-chain credit scores from backend API with fallback.
     • BackendFraudAlertAdapter: Fetches risk and fraud status signals.
     • StaticFeedAdapter: Deterministic / simulated adapter with dynamic value setting and drift simulation.
   • Robust Submitter:
     • Transaction building and signing framework.
     • Exponential backoff with full jitter on transient RPC/network failures.
     • In-memory idempotency deduplication preventing redundant submissions.
     • Real-time counters: submissions_succeeded, submissions_failed, submissions_rejected.
   • HTTP Health & Metrics Server:
     • GET /health / GET /api/v1/status: Health check, uptime, active feeds, and contract info.
     • GET /metrics / GET /api/v1/metrics: Performance metrics in JSON and Prometheus exposition format.
     • Query endpoints compatible with @chenaikit/oracle-node client.
   • Graceful Shutdown:
     • createGracefulShutdown handles SIGINT/SIGTERM signals, closes network listeners, and cancels pending work cleanly.

3. Operational Documentation (docs/oracle-node.md):

   • Comprehensive runbook detailing node architecture, configuration environment variables, Stellar keypair generation, on-chain staking registration, service daemon startup, health/metrics monitoring, and troubleshooting.

Testing done

• Contract test suite:

  cargo test -p oracle-network

  Result: 14 passed; 0 failed (including unit and adversarial tests).
• Contract static analysis:

  cargo clippy -p oracle-network --all-targets
  cargo fmt -p oracle-network --check

  Result: 0 warnings, 0 errors, clean formatting.
• Node runtime build & lint:

  pnpm --filter "@chenaikit/oracle-node" run build
  pnpm --filter "@chenaikit/oracle-node" run lint

  Result: TypeScript compilation and lint passed cleanly with 0 errors.
• Node runtime tests:

  pnpm --filter "@chenaikit/oracle-node" run test

  Result: 12 test suites passed, 73 tests passed.

Screenshots

N/A - backend oracle smart contract and off-chain daemon runtime only.

Checklist

• Branch named according to conventions
• Commits follow Conventional Commits
• Tested locally and verified passing
• Self-review performed
• Documentation added in docs/oracle-node.md

Payout Routing

• EVM (Base/Arbitrum/Polygon/ETH): 0xF46C9F6d70C50BF81ef3588AB523a90a594a2F89
• Stellar: GCL6OXAMLD75BMTINA6EMRUDWK5THQUSHMYNLSNBCJAPZJHNYJTUNIBC

[vercel]

@s6pa1rta3n-lab is attempting to deploy a commit to the Isaac Gellu's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}