SC-004 — Implement Verification Submission Engine

[dDevAhmed]

SC-004 — Implement Verification Submission Engine

📚 Overview

Verification is the core mechanism through which TruthBounty reaches consensus. Once a claim enters the verification phase, eligible participants submit a verdict together with their stake. These submissions collectively determine the final outcome of the claim.

This issue focuses on implementing the on-chain Verification Submission Engine, responsible for securely recording every verification, validating eligibility, locking stake, preventing duplicate submissions, and exposing the data required by the aggregation engine.

The module serves as the protocol's canonical source of verification data and directly feeds the aggregation, settlement, reputation, and dispute systems.

---

🧠 Background

The TruthBounty V1 audit revealed significant flaws in verification handling:

• verification logic resided in the backend
• duplicate votes were possible
• verification history was mutable
• wallet ownership was inconsistently enforced
• protocol consensus depended on centralized services

TruthBounty V2 moves the entire verification process on-chain.

Every verification becomes an immutable protocol record that can be independently audited by any participant without relying on a centralized backend.

---

🎯 Objectives

Implement a secure verification system that:

• allows eligible users to verify claims
• records immutable verification data
• locks verifier stake
• prevents duplicate submissions
• enforces verification windows
• emits deterministic protocol events
• exposes efficient retrieval methods
• supports future delegated verification mechanisms

---

🧩 Technical Scope

1. Verification Data Model

Implement the canonical verification structure.

enum VerificationVerdict {
    TRUE,
    FALSE
}

struct Verification {
    uint256 id;
    uint256 claimId;
    address verifier;
    VerificationVerdict verdict;
    uint256 stake;
    uint64 submittedAt;
}

Every verification must permanently belong to one claim and one verifier.

---

2. Verification Submission

Implement:

function submitVerification(
    uint256 claimId,
    VerificationVerdict verdict,
    uint256 stakeAmount
)
external;

Requirements:

• claim exists
• claim is under verification
• verification window still open
• verifier eligible
• sufficient stake supplied
• duplicate submission rejected
• verification stored
• stake locked
• event emitted

---

3. Duplicate Prevention

Each wallet may verify a claim only once.

Implement:

mapping(uint256 => mapping(address => bool))

or equivalent storage.

Duplicate submissions must revert.

Example:

error AlreadyVerified();

---

4. Eligibility Validation

Before accepting verification, validate:

• claim exists
• claim active
• verification phase open
• verifier not banned
• minimum stake satisfied
• wallet authenticated (future World ID integration)
• claim not resolved

---

5. Stake Locking

Stake submitted alongside a verification must become locked until settlement.

Requirements:

• prevent withdrawal
• associate locked stake with verification
• expose stake information for aggregation
• support future slashing

No immediate transfers should occur.

---

6. Verification Storage

Efficiently associate verifications with claims.

Support:

getVerification()

getClaimVerifications()

getVerificationCount()

hasVerified()

getVerifierStake()

---

7. Event Emission

Emit immutable protocol events.

event VerificationSubmitted(
    uint256 indexed claimId,
    uint256 indexed verificationId,
    address indexed verifier,
    VerificationVerdict verdict,
    uint256 stake
);

Events must enable indexers to reconstruct all verification activity.

---

8. Immutability

Once submitted:

• verdict cannot change
• stake cannot change
• verifier cannot change
• timestamp cannot change

Corrections must occur through disputes—not edits.

---

9. Future Extensibility

Design for future protocol features including:

• reputation weighting
• delegated verification
• quadratic weighting
• multi-round verification
• committee verification
• zk-proof eligibility
• World ID integration

without breaking storage compatibility.

---

🏗 Architectural Considerations

Verification Submission is responsible only for recording protocol inputs.

It must not:

• determine winners
• aggregate votes
• calculate rewards
• slash stake
• update reputation

Those responsibilities belong to downstream modules.

The module should remain deterministic and independent.

---

🔐 Security Considerations

Protect against:

• duplicate voting
• replay attacks
• verification after deadline
• insufficient stake
• invalid verdicts
• storage corruption
• unauthorized submissions

All validation must occur before state changes.

Prefer custom errors over string reverts.

---

⚡ Performance Considerations

Verification submission is expected to be one of the protocol's most frequently executed operations.

Optimise for:

• packed storage
• minimal storage writes
• efficient mappings
• indexed events
• low gas submission
• efficient retrieval

Benchmark:

• first verification
• additional verification
• duplicate rejection
• retrieval

---

🧪 Testing Requirements

Successful Cases

Test:

• submit TRUE verification
• submit FALSE verification
• multiple verifiers
• stake locking
• retrieval functions
• event emission

---

Validation Failures

Attempt:

• duplicate verification
• verification after deadline
• nonexistent claim
• resolved claim
• insufficient stake
• invalid verifier
• closed verification window

All must revert.

---

Event Tests

Verify:

• claim ID
• verification ID
• verifier
• verdict
• stake

Ensure exactly one event is emitted.

---

Stake Tests

Verify:

• stake correctly locked
• stake cannot be reused
• stake associated with verification
• multiple stakes handled correctly

---

Gas Benchmarks

Benchmark:

• verification submission
• retrieval
• duplicate detection
• eligibility validation

Document benchmark results.

---

✅ Acceptance Criteria

• Verification submission implemented.
• Duplicate submissions prevented.
• Verification window enforced.
• Eligibility validated.
• Stake locking implemented.
• Retrieval functions available.
• Events emitted correctly.
• Verification records immutable.
• Unit tests added.
• Gas benchmarks documented.
• CI passes successfully.

---

📖 References

• TruthBounty Protocol V2 Specification
• Ethereum Smart Contract Best Practices
• OpenZeppelin Guidelines
• TruthBounty Claim Lifecycle
• Verification & Consensus Specification

---

⛓ Dependencies

Depends On

• SC-001 — Implement On-Chain Claim Registry
• SC-002 — Implement Claim Lifecycle State Machine
• SC-003 — Implement Evidence Management & IPFS Integrity Verification

Blocks

• SC-005 — Implement Weighted Verification Aggregation
• SC-006 — Implement Settlement Engine
• SC-007 — Implement Reputation Engine
• SC-008 — Implement Stake Slashing
• Backend Indexer
• Frontend Verification Interface

---

🏷 Labels

• contracts
• protocol-critical
• web3
• architecture
• complexity-medium
• stellar-wave

---

📊 Complexity

Medium

The verification engine is one of the protocol's highest-traffic components. Correct eligibility checks, stake locking, immutability, and efficient storage are essential for protocol integrity and future scalability.

---

⏱ Estimated Effort

2 days

Includes:

• verification implementation
• eligibility validation
• duplicate prevention
• stake locking
• events
• documentation
• unit tests
• gas benchmarking

---

🚀 Definition of Done

This issue is complete when:

• Verification structure has been implemented.
• Users can submit one verification per claim.
• Duplicate submissions revert.
• Eligibility validation is enforced.
• Verification windows are respected.
• Stake is locked correctly.
• Retrieval functions are implemented.
• Events are emitted correctly.
• Verification records are immutable.
• Unit tests cover all success and failure scenarios.
• Gas benchmarks are documented.
• Contract passes formatting, linting, and CI.
• No protocol invariants are violated.
• Documentation has been updated.
• Pull Request has been reviewed and approved.

[akinboyewaSamson]

@akinboyewaSamson has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hello maintainer I’d love to help out with this issue. I’ve checked the current codebase/documentation and know exactly what needs to be updated to make this clearer. I will ensure everything aligns perfectly with your existing contribution guidelines.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @akinboyewaSamson to this issue.

[drips-wave]

Congratulations, @akinboyewaSamson! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @akinboyewaSamson: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊