Skip to content

Anti Manipulation and Security Measures

Jump to bottom
RunTimeAdmin edited this page Nov 2, 2026 · 17 revisions

Anti-Manipulation & Security Measures

**Referenced Files in This Document** - [SigvaraIdentity.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraIdentity.sol) - [SigvaraStaking.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraStaking.sol) - [SigvaraReputation.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraReputation.sol) - [SigvaraOracleBond.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraOracleBond.sol) - [scoring.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/scoring.js) - [payments.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/payments.js) - [adversarial.test.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/adversarial.test.js) - [index.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/index.js) - [whitepaper.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/whitepaper.md) - [reputation-model.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/reputation-model.md) - [Deploy.s.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/script/Deploy.s.sol)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document explains Sigvara’s anti-manipulation and security design as implemented across the on-chain contracts and the oracle scoring pipeline. It focuses on:

  • Farm-and-cash-out prevention through maturity, decay, and activity requirements.
  • Self-payment detection, wash trading prevention, and counterparty diversity enforcement.
  • Sybil resistance via bonding, slashing, and economic disincentives.
  • Score manipulation defenses including the challenge window, dispute resolution, slash proposals, and evidence commitments.
  • The oracle’s adversarial testing and monitoring role.

The goal is to make these mechanisms understandable for both technical and non-technical readers while remaining grounded in the actual codebase.

Project Structure

Security-relevant logic is split between on-chain contracts and off-chain oracle modules:

  • On-chain identity, stake, reputation, and operator-bond registries enforce state transitions, collateralization, and governance-gated actions.
  • Off-chain oracle modules compute scores from verified payments, apply decay and diversity caps, and propose score updates that are subject to a challenge window.
graph TB
subgraph "On-chain"
Identity["SigvaraIdentity"]
Staking["SigvaraStaking"]
Reputation["SigvaraReputation"]
OracleBond["SigvaraOracleBond"]
end
subgraph "Off-chain Oracle"
Index["oracle/index.js"]
Payments["oracle/payments.js"]
Scoring["oracle/scoring.js"]
Adversarial["oracle/adversarial.test.js"]
end
Index --> Payments
Index --> Scoring
Adversarial --> Scoring
Adversarial --> Payments
Identity --> Staking
Staking --> Reputation
Reputation --> OracleBond
Loading

Diagram sources

Section sources

Core Components

  • Identity registry: Anchors agent identities, enforces “bond before trust,” tracks status, and gates operator transfers.
  • Staking contract: Manages collateral, unbonding, slash initiation/dispute/execution, and prevents self-payment in slash reporting.
  • Reputation contract: Stores six-factor scores, applies maturity, and exposes a challenge window with committee rejection.
  • Operator bond registry: Requires bonded operators to propose scores; supports slashing and demotion if bonds fall below thresholds. A bonded operator can name a signer key to propose for it, so the host’s key need not hold the bond. The Arc testnet registry has supported this since 26 October 2026, but neither operator there has named a signer.
  • Oracle scoring pipeline: Verifies payments, applies decay, diversity caps, and computes factors used by the on-chain reputation system.

Key anti-manipulation properties:

  • Scores are earned immediately but spendable over time (maturity).
  • Payment-backed attestations prevent fake volume.
  • Per-payer caps and distinct counterparty counts resist rings.
  • Tenure measures paid activity span and recency, not registration age.
  • Slashing and unbonding periods penalize misbehavior and exit attempts.
  • Challenge windows and evidence roots allow third-party verification and committee intervention.

Section sources

Architecture Overview

The security model spans multiple layers. In the flow below, the admin Safe rules on a dispute and the committee only files and withdraws a slash; that split is live on the Arc testnet proxies since 26 October 2026, where the admin is a single EOA rather than a Safe.

sequenceDiagram
participant Agent as "Agent Operator"
participant Identity as "SigvaraIdentity"
participant Staking as "SigvaraStaking"
participant Oracle as "Oracle Pipeline"
participant Reputation as "SigvaraReputation"
participant Committee as "Slashing Committee"
participant Admin as "Admin Safe"
Agent->>Identity : registerAgent()
Agent->>Staking : depositStake()
Note over Identity,Staking : Agent becomes Active when stake >= minimumStake
Agent->>Oracle : submit payment-backed attestation
Oracle->>Oracle : verifyPayment(), decay, diversity caps
Oracle->>Reputation : proposeReputation()
Reputation-->>Reputation : open challengeWindow
Committee->>Reputation : rejectReputation() during window
Reputation-->>Committee : proposal discarded
Committee->>Staking : initiateSlash()
Staking-->>Identity : updateStatus(Suspended)
Agent->>Staking : disputeSlash()
Admin->>Staking : resolveDispute(uphold or cancel), an upheld ruling only after the deadline and before the dispute expires
Note over Staking : An undisputed slash is settled by anyone calling executeSlash() after the window
Staking->>Identity : updateStatus(Slashed)
Staking->>Reputation : zeroReputation()
Loading

Diagram sources

Detailed Component Analysis

Farm-and-Cash-Out Prevention

Farm-and-cash-out is prevented by combining:

  • Maturity: A finalized score climbs toward being spendable at a fixed rate per day. Falls apply immediately.
  • Decay: Payment volume and attestations decay over time so old activity does not permanently inflate scores.
  • Activity requirements: Tenure measures the span between first and last verified payment, weighted by recency. Idle agents earn little even if registered long ago.

Implementation highlights:

  • Maturity rate is configurable and applied on read; it restarts on operator handover to avoid buying/selling matured identities.
  • Decay uses exponential half-life weighting for volume and attestations.
  • AgeScore uses logarithmic growth over activity span multiplied by recency.
flowchart TD
Start(["Finalized Score"]) --> Earned["Earned Score Stored"]
Earned --> Anchor["Anchor = Matured Score Before Finalize"]
Anchor --> RateCheck{"Maturity Rate > 0?"}
RateCheck --> |No| ReturnEarned["Return Earned Score"]
RateCheck --> |Yes| TimeSince["Compute Time Since Last Finalize"]
TimeSince --> Release["Released = Anchor + (time * ratePerDay)"]
Release --> CapCheck{"Released >= Earned?"}
CapCheck --> |Yes| ReturnEarned
CapCheck --> |No| ReturnReleased["Return Released"]
Loading

Diagram sources

Section sources

Self-Payment Detection and Wash Trading Prevention

Self-payment detection and wash trading prevention rely on:

  • Payment verification: Attestations must reference a settled ERC-20 transfer to the agent’s address. The payer is taken from the transfer log, not the submitter.
  • Self-payment refusal: Payments from the operator or agent address are rejected.
  • Diversity caps: Each counterparty contributes at most maxPerPayer points to feeScore and attestations.
  • Distinct counterparties: Volume and success ratios are computed per payer and capped, preventing one wallet from simulating many customers. At the default of 4 points per payer, filling the 20-point fee factor takes five payers with no standing of their own, and three if each is fully trusted (a payer's cap rises with its own hard standing, up to double).
  • Real value only: A zero-value transfer never counts as a payment, because on a standard ERC-20 anyone can emit one naming any sender. Each sender must also meet PAYMENT_MIN_AMOUNT on its own, and in required mode the oracle refuses to start with a minimum of 0.
  • Outcomes are not open: A settlement hash is public, so a stranger who submits one has not shown that they paid or that they saw the work. Their attestation credits the payment and records no outcome, and only the payer's own signature or a caller holding an oracle token records one, which stops an operator filing "success" against its customers’ payments.
flowchart TD
Submit["Submit Attestation with txHash"] --> Verify["verifyPayment(txHash, agentAddress)"]
Verify --> Logs["Extract Transfer Logs"]
Logs --> Payer["Identify Payer from Log"]
Payer --> SelfCheck{"isSelfPayment(payer, identity)?"}
SelfCheck --> |Yes| Reject["Reject Attestation"]
SelfCheck --> |No| Group["Group by Payer"]
Group --> Cap["Apply maxPerPayer Cap"]
Cap --> Diversity["Compute diversifiedVolume/diversifiedAttestations"]
Diversity --> Score["Feed into computeScore()"]
Loading

Diagram sources

Section sources

Counterparty Diversity Enforcement

Counterparty diversity is enforced by:

  • Per-payer caps: Both volume and attestations are capped per counterparty using maxPerPayer.
  • Trust-weighted multiplier: A counterparty’s contribution can be raised based on its external standing, but only up to a bounded multiplier.
  • Propagation score: Inherited trust is limited to fully trusted counterparties, pro-rated by their external standing, with each counterparty counted once regardless of payment size.
flowchart TD
Events["Payment Events"] --> ByPayer["byPayer(events)"]
ByPayer --> TrustMult["trustMultiplier(payer, payerScores, trustWeight)"]
TrustMult --> Capped["cappedAt(base, payer, payerScores, trustWeight)"]
Capped --> DiversifiedVol["diversifiedVolume()"]
Capped --> DiversifiedAtt["diversifiedAttestations()"]
DiversifiedVol --> FeeScore["feeScoreFromVolume()"]
DiversifiedAtt --> SuccessRatio["successScore()"]
Loading

Diagram sources

Section sources

Sybil Attack Resistance

Sybil resistance combines:

  • Bonding requirements: Agents must hold minimum stake to be Active and scoreable. Operators proposing scores must be admitted and bonded in the operator set.
  • Slashing mechanisms: Misbehavior leads to stake slashing, identity marking as Slashed, and reputation zeroing.
  • Economic disincentives: Wash rings cost gas and working capital; tenure requires sustained paid operation; external trust cannot be minted within the protocol.
classDiagram
class SigvaraIdentity {
+registerAgent()
+updateStatus()
+acceptOperatorTransfer()
+slashSuspended
+operatorChangedAt
}
class SigvaraStaking {
+depositStake()
+initiateWithdrawal()
+initiateSlash()
+disputeSlash()
+executeSlash()
+claimSlashProceeds()
}
class SigvaraReputation {
+proposeReputation()
+finalizeReputation()
+rejectReputation()
+zeroReputation()
+getTotalScore()
}
class SigvaraOracleBond {
+depositBond()
+admit()
+slash()
+isActiveOperator()
}
SigvaraIdentity --> SigvaraStaking : "status checks"
SigvaraStaking --> SigvaraReputation : "zeroReputation()"
SigvaraReputation --> SigvaraOracleBond : "require bonded operator"
Loading

Diagram sources

Section sources

Score Manipulation Defenses

Score manipulation is addressed through:

  • Challenge window: Proposed scores sit open for a configurable period before finalization. On main the end of a proposal’s window is fixed when it is proposed, so an admin who changes the window moves no proposal already pending, and the window is held between 1 hour and 7 days.
  • Committee rejection: A slashing committee can reject bad proposals during the window.
  • Proposer check: On main, finalization is still permissionless but refuses a proposal whose proposer has since been removed, had its signer cleared or lost ORACLE_ROLE, so a stolen key’s pending proposals can be ended at once. A successor replaces them.
  • Evidence roots: Each finalized score commits to a Merkle root of the underlying payments, enabling third-party verification.
  • Slash proposals: Misbehavior triggers slash initiation, dispute, and execution, with proceeds distributed and identity marked Slashed. On main the admin can veto a pending or disputed slash, a slash nobody executes can be lapsed by anyone 14 days after its deadline, and the committee cannot file again against an agent for one challenge period after a proposal against it was dropped.
sequenceDiagram
participant Oracle as "Oracle"
participant Reputation as "SigvaraReputation"
participant Committee as "Slashing Committee"
participant Consumer as "Consumer"
Oracle->>Reputation : proposeReputation(didHash, data, evidenceRoot)
Reputation-->>Reputation : open challengeWindow
Committee->>Reputation : rejectReputation(didHash)
Reputation-->>Committee : proposal discarded
Consumer->>Reputation : verifyEvidence(didHash, leaf, proof)
Reputation-->>Consumer : bool
Oracle->>Reputation : finalizeReputation(didHash) after window (anyone may call)
Reputation-->>Consumer : getTotalScore(didHash)
Loading

Diagram sources

Section sources

Oracle’s Role in Detecting and Preventing Manipulation

The oracle pipeline:

  • Verifies payments against chain logs, extracting payer, amount, and timestamp.
  • Applies decay and diversity caps to prevent wash rings and self-payment inflation.
  • Computes six factors and proposes scores subject to challenge windows.
  • Is tested adversarially to bound what an attacker can buy with synthetic activity.
  • Does not trust the node for the clock or the chain. Whoever supplies the time chooses how old every payment looks, so an epoch does not run when the chain’s latest block time and the host clock differ by more than MAX_CLOCK_SKEW_SECONDS (600 by default). The chain id is checked against EXPECTED_CHAIN_ID (when set) and against the chain the state file was saved on, and the oracle will not sign a transaction whose fee is above MAX_FEE_GWEI or whose worst-case cost is above MAX_TX_COST.
  • Skips an agent for the epoch when a counterparty’s standing cannot be read, instead of scoring it as no standing.
  • Hardens its HTTP surface. Reads and writes are limited to 60 requests per caller per minute, in a separate bucket for each kind of route. X-Forwarded-For is believed only from loopback and the proxies in TRUSTED_PROXIES. A request target that is not a canonical path gets 400, a handler that throws costs one request rather than the process, and public routes do not echo upstream error text. Write credentials are named bearer tokens that can be limited to the scopes attest, flag, link and epoch.
  • Refuses to start on a numeric setting that is set but unusable. A misspelt PAYMENT_MAX_PER_PAYER would otherwise switch the per-payer cap off.
flowchart TD
Scan["Scan Chain for Transfers"] --> Verify["verifyPayment()"]
Verify --> Group["byPayer()"]
Group --> Caps["diversifiedVolume()/diversifiedAttestations()"]
Caps --> Compute["computeScore()"]
Compute --> Propose["proposeReputation()"]
Propose --> Challenge["challengeWindow"]
Loading

Diagram sources

Section sources

Dependency Analysis

The contracts and oracle modules form a layered dependency graph:

  • Identity depends on staking view for collateral checks.
  • Staking depends on identity for status and reputation for zeroing scores.
  • Reputation depends on identity for agent validation and optionally on operator bond registry for proposer requirements.
  • Oracle pipeline depends on payments and scoring modules to produce evidence-backed score proposals.
graph LR
Identity["SigvaraIdentity"] --> Staking["SigvaraStaking"]
Staking --> Reputation["SigvaraReputation"]
Reputation --> OracleBond["SigvaraOracleBond"]
Index["oracle/index.js"] --> Payments["oracle/payments.js"]
Index --> Scoring["oracle/scoring.js"]
Adversarial["oracle/adversarial.test.js"] --> Scoring
Adversarial --> Payments
Loading

Diagram sources

Section sources

Performance Considerations

  • Read-time maturity: Maturity accrues on read, avoiding frequent writes and allowing honest agents to mature even if oracles go offline.
  • Efficient grouping: The oracle groups events once and reuses the grouped map for volume, attestations, and distinct payer calculations.
  • Gas-aware indexing: Identity maintains an index for operator-agent lists to avoid linear scans on transfers.
  • Configurable parameters: Maturity rate, challenge window, unbonding period, and decay half-life are tunable to balance security and responsiveness. On main the contract parameters sit between a floor and a ceiling enforced where they are set, including the initializers: the score challenge window from 1 hour to 7 days, the maturity rate up to 100 points a day, the slash challenge period from 3 to 30 days and the unbonding period from 1 to 90 days.

Troubleshooting Guide

Common issues and mitigations:

  • Proposal replacement race: Use proposeIfEmpty for backup oracles to avoid overwriting live proposals.
  • Proposals revert during a pause (main): A guardian can close new inflows for three days at a time: registerAgent, depositStake, proposeReputation, proposeIfEmpty and depositBond. Proposals revert with InflowsPausedUntil until the pause ends or the guardian or admin lifts it. Withdrawals, disputes, slash execution, and finalizing or rejecting a score already proposed are never paused.
  • Unbonding vs slash timing: Queued withdrawals remain slashable; disputes freeze stakes to prevent escape.
  • Self-payment in slash reporting: The committee takes no share of a slash, and neither the reporter nor any other committee member can be named as the victim, so no member can be paid out of slashed stake.
  • Evidence verification failures: Consumers should call verifyEvidence with leaves built from chain-verified payments.

Section sources

Conclusion

Sigvara’s anti-manipulation and security measures combine on-chain collateral and governance with off-chain verified scoring. Farm-and-cash-out is constrained by maturity, decay, and activity requirements. Self-payment and wash trading are blocked by payment verification, diversity caps, and tenure metrics. Sybil attacks are resisted through bonding, slashing, and economic disincentives. Score manipulation is countered by challenge windows, committee rejection, and evidence roots. The oracle’s adversarial tests ensure that synthetic activity cannot easily buy high scores, preserving the integrity of the reputation system.

Home

Overview

Protocol Architecture

Smart Contracts Reference

Oracle Service

Reputation System Design

TypeScript SDK

Integration Guides

Deployment and Operations

Development and Testing

Advanced Topics

Clone this wiki locally