SC-006 — Implement Deterministic Settlement Engine
📚 Overview
The Settlement Engine is responsible for finalising claims once consensus has been reached and executing the protocol's financial settlement.
Following aggregation, the protocol must deterministically distribute rewards, return stake, slash losing verifiers where applicable, and permanently record settlement status. Every participant must be able to independently verify that the same settlement result would always be produced from the same protocol state.
The Settlement Engine is one of the protocol's highest security components because it directly controls value transfer and marks claims as irreversibly resolved.
🧠 Background
The V1 audit identified several critical flaws in settlement:
- settlement logic existed in the backend
- rewards could diverge from aggregation results
- settlement execution was not deterministic
- payout calculations were not reproducible
- settlement state could become inconsistent after failures
- reward and slashing logic were tightly coupled with API services
TruthBounty V2 moves settlement entirely on-chain.
Once consensus is reached, settlement becomes a deterministic protocol operation that no backend service or administrator can alter.
🎯 Objectives
Implement an on-chain settlement engine that:
- finalises resolved claims
- distributes rewards deterministically
- refunds eligible stake
- prepares slashing inputs
- prevents duplicate settlement
- permanently records settlement state
- exposes settlement information to indexers
🧩 Technical Scope
1. Settlement Lifecycle
Support:
Aggregation Complete
↓
Settlement Ready
↓
Settlement Executed
↓
Claim Finalized
Settlement must execute exactly once.
2. Settlement Function
Implement:
settleClaim(uint256 claimId)
Responsibilities:
- verify claim is resolvable
- verify aggregation exists
- verify claim is not already settled
- compute settlement
- distribute rewards
- update claim state
- emit settlement events
3. Settlement Result
Create:
struct SettlementResult {
uint256 rewardPool;
uint256 winningStake;
uint256 losingStake;
uint256 protocolFee;
uint256 totalRewards;
bool settled;
}Persist this information permanently.
4. Reward Distribution
Settlement must distribute:
- verifier rewards
- returned stake
- protocol fee
- treasury allocation
Calculations must be deterministic.
No manual intervention permitted.
5. Settlement State
Track:
pending
executing
completed
Prevent:
- duplicate execution
- re-entry
- partial settlement
6. Claim Finalization
Successful settlement should transition:
After finalisation:
- voting closes permanently
- evidence becomes immutable
- settlement cannot be rerun
7. Failure Recovery
If settlement reverts:
- no partial transfers occur
- state rolls back
- claim remains resolvable
Settlement must remain atomic.
8. Treasury Allocation
Support protocol fee routing.
Example:
Reward Pool
↓
Verifier Rewards
↓
Treasury Fee
↓
Remaining Stake Refunds
Fee percentages must remain configurable through governance.
9. View Functions
Implement:
getSettlement()
isSettled()
calculateSettlement()
previewSettlement()
Preview functions must not modify state.
10. Event Emission
Emit:
event ClaimSettled(
uint256 indexed claimId,
uint256 rewardPool,
uint256 protocolFee
);Also emit events for:
- reward distribution
- treasury allocation
- settlement completion
🏗 Architectural Considerations
Settlement is a terminal protocol operation.
It must never:
- modify aggregation
- reopen claims
- alter evidence
- change votes
Settlement consumes aggregation output.
It does not create consensus.
The architecture should separate:
- aggregation
- settlement
- reputation updates
- slashing
- treasury accounting
Each module should remain independently testable.
🔐 Security Considerations
Protect against:
- double settlement
- reentrancy
- duplicate payouts
- overflow
- underflow
- inconsistent accounting
- failed partial execution
- reward inflation
- malicious settlement replay
Use:
- Checks-Effects-Interactions
- ReentrancyGuard
- custom errors
- atomic execution
Settlement must never leave contracts in a partially updated state.
⚡ Performance Considerations
Optimise:
- storage writes
- reward calculations
- transfer batching
- settlement gas usage
Benchmark:
- small claim
- medium claim
- maximum supported verifier count
Avoid unnecessary loops where possible.
🧪 Testing Requirements
Settlement Tests
Verify:
- successful settlement
- settlement after aggregation
- settlement finalises claim
- reward distribution
- treasury allocation
Failure Tests
Verify:
- double settlement reverts
- settlement without aggregation reverts
- settlement on unresolved claim reverts
- settlement rollback after failure
Security Tests
Test:
- reentrancy attempts
- malicious recipients
- duplicate execution
- invalid state transitions
Gas Tests
Benchmark:
- settlement
- reward transfers
- treasury allocation
- previewSettlement()
Fuzz Tests
Randomise:
- verifier count
- stake size
- reward pool
- protocol fee
Settlement must always remain deterministic.
✅ Acceptance Criteria
- Settlement executes exactly once.
- Rewards distributed correctly.
- Treasury allocation implemented.
- Duplicate settlement prevented.
- Claims permanently finalised.
- Settlement preview implemented.
- Settlement events emitted.
- Atomic execution guaranteed.
- Comprehensive unit tests added.
- Gas benchmarks documented.
- CI passes successfully.
📖 References
- TruthBounty Protocol V2 Specification
- Settlement Architecture
- OpenZeppelin Security Guidelines
- Ethereum Smart Contract Best Practices
- Protocol Economics Specification
⛓ Dependencies
Depends On
- SC-001 — Implement On-Chain Claim Registry
- SC-002 — Implement Claim Lifecycle State Machine
- SC-004 — Implement Verification Submission Engine
- SC-005 — Implement Weighted Verification Aggregation Engine
Blocks
- SC-007 — Reputation Engine
- SC-008 — Stake Slashing
- SC-010 — Treasury Accounting
- Backend Settlement Indexer
- Reward Dashboard
- Analytics Module
🏷 Labels
- contracts
- protocol-critical
- economics
- security
- web3
- complexity-high
- stellar-wave
📊 Complexity
High
The Settlement Engine manages all protocol value transfers. A single flaw could lead to permanent loss of funds, duplicate payouts, or inconsistent protocol state. The implementation must prioritise determinism, atomicity, and security while remaining extensible for future governance-controlled economic parameters.
⏱ Estimated Effort
4–6 days
Includes:
- settlement logic
- reward distribution
- treasury allocation
- preview functions
- security protections
- unit tests
- fuzz testing
- gas benchmarking
- documentation
🚀 Definition of Done
This issue is complete when:
SC-006 — Implement Deterministic Settlement Engine
📚 Overview
The Settlement Engine is responsible for finalising claims once consensus has been reached and executing the protocol's financial settlement.
Following aggregation, the protocol must deterministically distribute rewards, return stake, slash losing verifiers where applicable, and permanently record settlement status. Every participant must be able to independently verify that the same settlement result would always be produced from the same protocol state.
The Settlement Engine is one of the protocol's highest security components because it directly controls value transfer and marks claims as irreversibly resolved.
🧠 Background
The V1 audit identified several critical flaws in settlement:
TruthBounty V2 moves settlement entirely on-chain.
Once consensus is reached, settlement becomes a deterministic protocol operation that no backend service or administrator can alter.
🎯 Objectives
Implement an on-chain settlement engine that:
🧩 Technical Scope
1. Settlement Lifecycle
Support:
Settlement must execute exactly once.
2. Settlement Function
Implement:
Responsibilities:
3. Settlement Result
Create:
Persist this information permanently.
4. Reward Distribution
Settlement must distribute:
Calculations must be deterministic.
No manual intervention permitted.
5. Settlement State
Track:
Prevent:
6. Claim Finalization
Successful settlement should transition:
After finalisation:
7. Failure Recovery
If settlement reverts:
Settlement must remain atomic.
8. Treasury Allocation
Support protocol fee routing.
Example:
Fee percentages must remain configurable through governance.
9. View Functions
Implement:
Preview functions must not modify state.
10. Event Emission
Emit:
Also emit events for:
🏗 Architectural Considerations
Settlement is a terminal protocol operation.
It must never:
Settlement consumes aggregation output.
It does not create consensus.
The architecture should separate:
Each module should remain independently testable.
🔐 Security Considerations
Protect against:
Use:
Settlement must never leave contracts in a partially updated state.
⚡ Performance Considerations
Optimise:
Benchmark:
Avoid unnecessary loops where possible.
🧪 Testing Requirements
Settlement Tests
Verify:
Failure Tests
Verify:
Security Tests
Test:
Gas Tests
Benchmark:
Fuzz Tests
Randomise:
Settlement must always remain deterministic.
✅ Acceptance Criteria
📖 References
⛓ Dependencies
Depends On
Blocks
🏷 Labels
📊 Complexity
High
The Settlement Engine manages all protocol value transfers. A single flaw could lead to permanent loss of funds, duplicate payouts, or inconsistent protocol state. The implementation must prioritise determinism, atomicity, and security while remaining extensible for future governance-controlled economic parameters.
⏱ Estimated Effort
4–6 days
Includes:
🚀 Definition of Done
This issue is complete when: