feat(oracle): implement commit-reveal integration

- Add submitCommitment and submitReveal to TxSubmitterService
- Activate TODOs in CommitRevealWorker (processCommit/processReveal)
- Wire RaffleCreated → commit and DrawTriggered → reveal in EventListenerService
- Rewrite COMMIT_REVEAL.md with contract interface, event flow, and config docs

Author: olawaleakanbi035-maker

oracle/COMMIT_REVEAL.md

@@ -2,96 +2,93 @@
 
 ## Overview
 
-Commit-reveal prevents oracle front-running by requiring the oracle to commit to randomness before the raffle ends, then reveal after draw is triggered.
+Commit-reveal prevents oracle front-running by requiring the oracle to commit to randomness before the raffle ends, then reveal after the draw is triggered. The contract verifies `SHA-256(secret || nonce) == stored_commitment`.
 
-## How It Works
+## Event Flow
 
-### Commit Phase (Before end_time)
-1. Oracle generates random `secret` and `nonce`
-2. Computes `commitment = SHA-256(secret || nonce)`
-3. Submits commitment to contract via `commit_randomness(raffleId, commitment)`
-4. Stores secret/nonce locally for later reveal
-
-### Reveal Phase (After draw triggered)
-1. Oracle retrieves stored secret/nonce
-2. Submits to contract via `reveal_randomness(raffleId, secret, nonce)`
-3. Contract verifies: `SHA-256(secret || nonce) == stored_commitment`
-4. If valid, uses secret as randomness seed for winner selection
-
-## Security Properties
-
-- **Front-running prevention**: Oracle cannot observe ticket purchases after committing
-- **Unpredictability**: Secret is cryptographically random
-- **Verifiability**: Anyone can verify the reveal matches the commitment
-- **Non-manipulability**: Oracle cannot change commitment after submission
-
-## Usage
-
-```typescript
-// Commit phase (before raffle ends)
-await commitRevealWorker.processCommit({
-  raffleId: 1,
-  endTime: Date.now() + 86400000,
-});
-
-// Reveal phase (after draw triggered)
-await commitRevealWorker.processReveal({
-  raffleId: 1,
-  requestId: 'req-123',
-});
+```
+RaffleCreated event
+        ↓
+CommitRevealWorker.processCommit()
+  → CommitmentService.commit(raffleId)       — generates secret + nonce, stores locally
+  → TxSubmitterService.submitCommitment()    — calls commit_randomness(raffle_id, commitment)
+
+DrawTriggered event
+        ↓
+CommitRevealWorker.processReveal()
+  → CommitmentService.reveal(raffleId)       — retrieves stored secret + nonce
+  → TxSubmitterService.submitReveal()        — calls reveal_randomness(raffle_id, secret, nonce)
+  → CommitmentService.clearCommitment()      — removes local state
 ```
 
-## Contract Interface
+## Contract Interface (Required)
 
-The contract must implement:
+The Soroban contract must implement both functions:
 
 ```rust
-// Commit phase
+/// Commit phase — oracle submits hash before raffle ends
 pub fn commit_randomness(env: Env, raffle_id: u32, commitment: BytesN<32>)
 
-// Reveal phase
+/// Reveal phase — oracle reveals preimage after draw is triggered
 pub fn reveal_randomness(env: Env, raffle_id: u32, secret: BytesN<32>, nonce: BytesN<16>)
 ```
 
-Contract verification:
+Contract verification logic:
 ```rust
-let computed = sha256(secret || nonce);
-assert_eq!(computed, stored_commitment);
+let computed: BytesN<32> = env.crypto().sha256(&Bytes::from_slice(&env, &[secret.as_ref(), nonce.as_ref()].concat()));
+assert_eq!(computed, stored_commitment, "commitment mismatch");
 ```
 
-## Implementation Status
+For low-stakes raffles that use single-shot randomness, the contract must also implement:
+```rust
+pub fn receive_randomness(env: Env, raffle_id: u32, seed: BytesN<32>, proof: BytesN<64>)
+```
 
-✅ CommitmentService - Generate and store commitments  
-✅ CommitRevealWorker - Process commit and reveal phases  
-✅ Unit tests for commitment verification  
-⏳ Contract integration (waiting for contract support)  
-⏳ TxSubmitter methods for commit/reveal transactions  
+## Oracle Events Consumed
 
-## Configuration
+| Event name | Trigger | Oracle action |
+|---|---|---|
+| `RaffleCreated` | New raffle created | `commit_randomness` |
+| `DrawTriggered` | Draw initiated | `reveal_randomness` |
+| `RandomnessRequested` | Low-stakes draw | `receive_randomness` (direct) |
 
-Set threshold for commit-reveal vs direct randomness:
+Event payload (XDR map):
+- `RaffleCreated`: `{ raffle_id: u32, end_time: u64 }`
+- `DrawTriggered`: `{ raffle_id: u32, request_id: string|u64|bytes }`
+- `RandomnessRequested`: `{ raffle_id: u32, request_id: string|u64|bytes }`
 
-```typescript
-// In worker configuration
-const USE_COMMIT_REVEAL = prizeAmount >= 500; // XLM
+## Security Properties
 
-if (USE_COMMIT_REVEAL) {
-  await commitRevealWorker.processCommit(...);
-  // Later...
-  await commitRevealWorker.processReveal(...);
-} else {
-  await randomnessWorker.processRequest(...);
-}
-```
+- **Front-running prevention**: Oracle commits before ticket sales close; cannot observe final ticket set before choosing randomness
+- **Unpredictability**: Secret is 32 cryptographically random bytes
+- **Verifiability**: Anyone can verify `SHA-256(secret || nonce) == commitment`
+- **Non-manipulability**: Commitment is on-chain before the draw; oracle cannot change it
 
-## Testing
+## Configuration
 
-```bash
-npm test commitment.service.spec.ts
+```env
+# Enable commit-reveal for high-stakes raffles (prize >= threshold)
+COMMIT_REVEAL_ENABLED=true          # default: true when contract supports it
+HIGH_STAKES_THRESHOLD_XLM=500       # raffles above this use commit-reveal + VRF
 ```
 
+Low-stakes raffles (prize < threshold) skip commit-reveal and call `receive_randomness` directly via `RandomnessWorker`.
+
+## Implementation Status
+
+| Component | Status |
+|---|---|
+| `CommitmentService` — generate/store/verify commitments | ✅ |
+| `CommitRevealWorker` — processCommit / processReveal | ✅ |
+| `TxSubmitterService.submitCommitment` | ✅ |
+| `TxSubmitterService.submitReveal` | ✅ |
+| `EventListenerService` — `RaffleCreated` → commit | ✅ |
+| `EventListenerService` — `DrawTriggered` → reveal | ✅ |
+| Contract `commit_randomness` / `reveal_randomness` | ⏳ Pending contract deployment |
+| Persistent commitment storage (Redis/DB) | ⏳ Currently in-memory |
+
 ## Notes
 
-- Commitment storage is in-memory; consider persistent storage for production
-- Ensure commit happens before end_time to prevent front-running
-- Monitor for failed reveals and implement retry logic
+- Commitment storage is in-memory. A process restart before reveal will lose pending commitments. For production, persist to Redis or a database keyed by `raffle_id`.
+- Ensure `commit_randomness` is called before `end_time` to prevent front-running.
+- If a reveal fails after max retries, the job is retained in the Bull dead-letter queue and an `[ALERT]` log is emitted.

oracle/src/listener/event-listener.service.ts

@@ -3,6 +3,7 @@ import { ConfigService } from '@nestjs/config';
 import * as StellarSdk from 'stellar-sdk';
 import { Subject, Subscription } from 'rxjs';
 import { RandomnessWorker } from '../queue/randomness.worker';
+import { CommitRevealWorker } from '../queue/commit-reveal.worker';
 import { RandomnessRequest } from '../queue/queue.types';
 import { HealthService } from '../health/health.service';
 import { LagMonitorService } from '../health/lag-monitor.service';
@@ -31,6 +32,7 @@ export class EventListenerService implements OnModuleInit, OnModuleDestroy {
         private readonly healthService: HealthService,
         private readonly lagMonitor: LagMonitorService,
         private readonly randomnessWorker: RandomnessWorker,
+        private readonly commitRevealWorker: CommitRevealWorker,
         @Optional() @InjectQueue(RANDOMNESS_QUEUE) private readonly randomnessQueue?: Queue<RandomnessJobPayload>,
     ) {
         // Config parsing
@@ -118,6 +120,48 @@ export class EventListenerService implements OnModuleInit, OnModuleDestroy {
                 if (primaryTopic.switch() === StellarSdk.xdr.ScValType.scvSymbol()) {
                     const eventName = primaryTopic.sym().toString();
 
+                    if (eventName === 'RaffleCreated') {
+                        const scVal = (eventXdr as any).body().v0().data();
+                        let raffleId: number | undefined;
+                        let endTime: number | undefined;
+
+                        if (scVal.switch() === StellarSdk.xdr.ScValType.scvMap()) {
+                            for (const entry of scVal.map() ?? []) {
+                                const key = entry.key().sym().toString();
+                                if (key === 'raffle_id') raffleId = entry.val().u32();
+                                else if (key === 'end_time') endTime = Number(entry.val().u64().toString());
+                            }
+                        }
+
+                        if (raffleId !== undefined) {
+                            this.logger.log(`RaffleCreated: raffle=${raffleId}, scheduling commit`);
+                            this.commitRevealWorker.processCommit({ raffleId, endTime: endTime ?? 0 }).catch(err =>
+                                this.logger.error(`Commit failed for raffle ${raffleId}: ${err.message}`),
+                            );
+                        }
+                    }
+
+                    if (eventName === 'DrawTriggered') {
+                        const scVal = (eventXdr as any).body().v0().data();
+                        let raffleId: number | undefined;
+                        let requestId: string | undefined;
+
+                        if (scVal.switch() === StellarSdk.xdr.ScValType.scvMap()) {
+                            for (const entry of scVal.map() ?? []) {
+                                const key = entry.key().sym().toString();
+                                if (key === 'raffle_id') raffleId = entry.val().u32();
+                                else if (key === 'request_id') requestId = this.parseRequestId(entry.val());
+                            }
+                        }
+
+                        if (raffleId !== undefined && requestId !== undefined) {
+                            this.logger.log(`DrawTriggered: raffle=${raffleId}, scheduling reveal`);
+                            this.commitRevealWorker.processReveal({ raffleId, requestId }).catch(err =>
+                                this.logger.error(`Reveal failed for raffle ${raffleId}: ${err.message}`),
+                            );
+                        }
+                    }
+
                     if (eventName === 'RandomnessRequested') {
                         this.logger.log(`Received RandomnessRequested event for contract ${this.raffleContractId}`);
 

oracle/src/queue/commit-reveal.worker.ts

@@ -33,15 +33,9 @@ export class CommitRevealWorker {
     this.logger.log(`Processing commit for raffle ${raffleId}`);
 
     try {
-      // Generate commitment
       const commitment = this.commitmentService.commit(raffleId);
-      
-      // Submit commitment to contract
-      // TODO: Implement contract call to commit_randomness(raffleId, commitment)
       this.logger.log(`Commitment for raffle ${raffleId}: ${commitment}`);
-      
-      // When contract supports commit_randomness:
-      // await this.txSubmitter.submitCommitment(raffleId, commitment);
+      await this.txSubmitter.submitCommitment(raffleId, commitment);
 
     } catch (error) {
       this.logger.error(
@@ -70,14 +64,8 @@ export class CommitRevealWorker {
       }
 
       const { secret, nonce } = reveal;
-      
-      // Submit reveal to contract
-      // Contract will verify: SHA-256(secret || nonce) == stored commitment
-      // TODO: Implement contract call to reveal_randomness(raffleId, secret, nonce)
       this.logger.log(`Revealing for raffle ${raffleId}`);
-      
-      // When contract supports reveal_randomness:
-      // await this.txSubmitter.submitReveal(raffleId, secret, nonce);
+      await this.txSubmitter.submitReveal(raffleId, secret, nonce);
 
       // Clear commitment after successful reveal
       this.commitmentService.clearCommitment(raffleId);

oracle/src/submitter/tx-submitter.service.ts

@@ -75,6 +75,88 @@ export class TxSubmitterService {
     );
   }
 
+  async submitCommitment(raffleId: number, commitment: string): Promise<SubmitResult> {
+    if (!this.contractId || !this.oracleSecret) {
+      this.logger.error('Missing configuration for TxSubmitter.');
+      return { txHash: '', ledger: 0, success: false };
+    }
+    const kp = (StellarSdk as any).Keypair.fromSecret(this.oracleSecret);
+    return this.submitContractCall(kp, 'commit_randomness', [
+      (StellarSdk as any).xdr.ScVal.scvU32(raffleId >>> 0),
+      (StellarSdk as any).xdr.ScVal.scvBytes(this.parseToBytes(commitment, 32)),
+    ]);
+  }
+
+  async submitReveal(raffleId: number, secret: string, nonce: string): Promise<SubmitResult> {
+    if (!this.contractId || !this.oracleSecret) {
+      this.logger.error('Missing configuration for TxSubmitter.');
+      return { txHash: '', ledger: 0, success: false };
+    }
+    const kp = (StellarSdk as any).Keypair.fromSecret(this.oracleSecret);
+    return this.submitContractCall(kp, 'reveal_randomness', [
+      (StellarSdk as any).xdr.ScVal.scvU32(raffleId >>> 0),
+      (StellarSdk as any).xdr.ScVal.scvBytes(this.parseToBytes(secret, 32)),
+      (StellarSdk as any).xdr.ScVal.scvBytes(this.parseToBytes(nonce, 16)),
+    ]);
+  }
+
+  private async submitContractCall(kp: any, method: string, args: any[]): Promise<SubmitResult> {
+    const publicKey = kp.publicKey();
+    let feeBump = 1;
+    let attempt = 0;
+    let lastError: any = null;
+
+    while (attempt < this.MAX_RETRIES) {
+      attempt++;
+      try {
+        const account = await this.rpcServer.getAccount(publicKey);
+        const fee = (Number((StellarSdk as any).BASE_FEE || 100) * feeBump).toString();
+        const contract = new (StellarSdk as any).Contract(this.contractId);
+        const tx = new (StellarSdk as any).TransactionBuilder(account, {
+          fee,
+          networkPassphrase: this.networkPassphrase,
+        })
+          .addOperation(contract.call(method, ...args))
+          .setTimeout(30)
+          .build();
+
+        const prepared = await this.rpcServer.prepareTransaction(tx);
+        prepared.sign(kp);
+
+        const sendRes = await this.rpcServer.sendTransaction(prepared);
+        const txHash = sendRes.hash || sendRes?.transactionHash || '';
+        if (!txHash) {
+          if (this.isInsufficientFeeError(JSON.stringify(sendRes))) {
+            feeBump = Math.max(feeBump * 2, feeBump + 1);
+          }
+          lastError = new Error('sendTransaction returned no hash');
+          await this.delay(this.backoff(attempt));
+          continue;
+        }
+
+        const confirm = await this.pollForConfirmation(txHash);
+        if (confirm?.status === 'SUCCESS') {
+          return { txHash, ledger: (confirm.ledger as number) || 0, success: true };
+        }
+        if (this.isInsufficientFeeError(JSON.stringify(confirm))) {
+          feeBump = Math.max(feeBump * 2, feeBump + 1);
+        }
+        lastError = new Error(`${method} failed (status=${confirm?.status || 'UNKNOWN'})`);
+        await this.delay(this.backoff(attempt));
+      } catch (e: any) {
+        const msg = e?.message || String(e);
+        if (this.isRpcError(msg)) this.failoverRpc();
+        else if (this.isInsufficientFeeError(msg)) feeBump = Math.max(feeBump * 2, feeBump + 1);
+        this.logger.error(`Error calling ${method} (attempt ${attempt}/${this.MAX_RETRIES}): ${msg}`);
+        lastError = e;
+        await this.delay(this.backoff(attempt));
+      }
+    }
+
+    this.logger.error(`Persistent failure calling ${method} after ${this.MAX_RETRIES} attempts.`);
+    return { txHash: '', ledger: 0, success: false };
+  }
+
   async submitRandomness(raffleId: number, randomness: RandomnessResult): Promise<SubmitResult> {
     if (!this.contractId || !this.oracleSecret) {
       this.logger.error('Missing configuration for TxSubmitter (contract id or oracle secret).');