Skip to content

Community Flag Processing

Jump to bottom
RunTimeAdmin edited this page Nov 5, 2026 · 28 revisions

Community Flag Processing

**Referenced Files in This Document** - [SigvaraStaking.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraStaking.sol) - [SigvaraIdentity.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraIdentity.sol) - [SigvaraReputation.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraReputation.sol) - [architecture.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/architecture.md) - [0003-evidence-intake.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/adr/0003-evidence-intake.md) - [slash-drill.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/slash-drill.md) - [watcher.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/watcher.js) - [watcher-policy.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/watcher-policy.js) - [store.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/store.js) - [index.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/index.js)

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 how community flag processing and governance work in Sigvara. It covers:

  • How community members can submit flags against agents for suspicious behavior or policy violations.
  • The end-to-end workflow from flag intake to dispute state, committee evaluation, slashing proposal generation, and economic penalties.
  • Rate limiting, evidence validation, appeal paths, and integration with watchdog scanners and automated monitoring systems.

The system combines on-chain contracts with off-chain oracle scoring and a watcher that escalates disagreements before time-sensitive windows close.

Project Structure

Community flag processing spans three layers:

  • On-chain governance and enforcement: SigvaraStaking, SigvaraIdentity, and SigvaraReputation.
  • Off-chain scoring and divergence detection: the primary oracle, checker, and watcher.
  • Evidence handling: payment scanning and attestation intake.
graph TB
subgraph "On-chain"
ST["SigvaraStaking"]
ID["SigvaraIdentity"]
REP["SigvaraReputation"]
end
subgraph "Off-chain"
ORA["Primary Oracle"]
CHK["Checker"]
WAT["Watcher"]
WD["Watchdog Scanners"]
end
WD --> |"flags"| ORA
ORA --> |"propose score + evidence root"| REP
CHK --> |"reads pending score, records disagreement off chain"| REP
WAT --> |"alert committee"| REP
ST --> |"slash · suspend · zero reputation"| ID
ST --> |"zero reputation"| REP
Loading

Diagram sources

Section sources

Core Components

  • SigvaraStaking: Manages agent bonds, slash proposals, challenge/dispute windows, and economic settlement (a burn and the victim's share; the committee takes nothing).
  • SigvaraIdentity: Anchors agent identities, enforces status transitions, and locks operator actions during slash disputes.
  • SigvaraReputation: Stores computed scores, accepts oracle proposals, exposes Merkle-backed evidence roots, and allows committee rejection during challenge windows.
  • Oracle Watcher: Polls checker divergences, re-validates chain state, and alerts the committee while rejection is still possible.
  • Evidence Intake: Pulls payment evidence from chain logs and validates attestations; an outcome needs the payer's signature or a credential.

Key responsibilities:

  • Flags reduce community standing and can trigger divergence when operators disagree.
  • Committee-initiated slashes immediately suspend agents and freeze stakes.
  • Disputes move proposals into a resolution state where the committee upholds or drops them; on main the admin rules, and can also veto a pending slash.
  • Finalized slash execution burns stake and zeroes reputation.

Section sources

Architecture Overview

Community flags flow through the following stages:

  1. Flag intake: Watchdog scanners report flags to the primary oracle.
  2. Scoring impact: The oracle incorporates flags into the community factor and may lower the total score.
  3. Proposal and challenge window: The oracle proposes a score update with an evidence root. During the challenge window, the committee can reject it.
  4. Divergence detection: A checker recomputes the score independently. If it disagrees, it records a divergence rather than overwriting the live proposal.
  5. Committee alerting: The watcher reads divergences, verifies they are still actionable, and notifies the committee before the window closes.
  6. Slashing path: The committee can initiate a slash against an agent. This suspends the agent, freezes stake, and opens a challenge period.
  7. Dispute and resolution: The operator may dispute, moving the proposal to a disputed state. The committee then upholds or drops the slash; on main the admin rules instead, and an upheld ruling waits for the challenge deadline and is refused once the dispute can be expired.
  8. Settlement: An undisputed slash can be executed by anyone once the window closes. An upheld ruling settles the slash itself, so there is nothing left to execute. Stake is split (75% burned, 25% to the victim), identity becomes slashed, and reputation is zeroed.
sequenceDiagram
participant WD as "Watchdog Scanner"
participant ORA as "Primary Oracle"
participant REP as "SigvaraReputation"
participant CHK as "Checker"
participant WAT as "Watcher"
participant CMT as "Committee"
participant ST as "SigvaraStaking"
participant ID as "SigvaraIdentity"
WD->>ORA : "Submit flags"
ORA->>REP : "Propose score + evidence root"
CHK->>REP : "Read pending score, record divergence off chain if disagreeing"
WAT->>WAT : "Poll checker /divergence"
WAT->>REP : "Read pending score"
WAT-->>CMT : "Alert to reject before window closes"
CMT->>ST : "initiateSlash(didHash, victim, evidenceHash)"
ST->>ID : "Suspend agent"
ST->>ST : "Freeze stake + open challenge window"
CMT->>REP : "rejectReputation(didHash) (optional)"
ST->>ST : "executeSlash() after window"
ST->>ID : "Mark Slashed"
ST->>REP : "Zero reputation"
Loading

Diagram sources

Detailed Component Analysis

Flag Submission Workflow

  • Who submits: Community members operate watchdog scanners that detect suspicious activity (e.g., rug patterns, abuse signals) and send flags to the primary oracle.
  • Where flags enter: The architecture documents that watchdog scanners feed flags into the oracle, which influences the community factor and overall score. A scanner raises one with POST /flag, which needs a write credential (scope flag); the oracle logs which credential raised it.
  • How a flag counts: Each flag is stored with its timestamp and decays on a half-life (FLAG_HALF_LIFE_DAYS, 30 by default, 0 turns decay off). The community factor is max(0, floor(5 - 2 × decayed flags)). POST /flag/resolve clears flags, newest first, and one too old to move the score is pruned each epoch.
  • When the state file cannot be written: POST /flag and POST /flag/resolve answer 202 with durable: false instead of 200. The change is held in memory and written by the next save that works, so a restart before then loses it. Do not resend: a flag sent twice is two flags, and a resolve sent twice clears another one.
  • What happens next: The oracle proposes a new score with an evidence root. During the challenge window, the committee can reject the proposal outright.

Rate limiting and abuse prevention:

  • Every outcome requires a credential or the payer's own signature (an oracle with no credential configured, which only a loopback bind may run, records every caller's outcome). A stranger’s positive attestation with a verified payment is accepted, but it only credits the payment, because a settlement hash is public and says nothing about how the work went. A negative outcome cannot be filed without a credential, which prevents free denial-of-service attacks.
  • Writes are limited to 60 requests per caller per minute, counted before the credential is checked.
  • Payment evidence is pulled from chain logs by each operator independently, closing the gap where unreported work was previously invisible.
flowchart TD
Start(["Flag observed"]) --> Scan["Watchdog scanner detects anomaly"]
Scan --> Submit["Submit flags to primary oracle"]
Submit --> Score["Oracle computes community factor impact"]
Score --> Propose["Oracle proposes score + evidence root"]
Propose --> Window{"Challenge window open?"}
Window --> |Yes| Review["Committee reviews and may reject"]
Window --> |No| Finalize["Anyone finalizes score"]
Review --> Decision{"Committee rejects?"}
Decision --> |Yes| Drop["Proposal dropped"]
Decision --> |No| Finalize
Loading

Diagram sources

Section sources

Evidence Validation Requirements

  • Payment evidence: Each operator scans ERC-20 Transfer logs to registered agent addresses and credits what it finds. Attestation endpoints act as hints and success indicators.
  • Outcome validation: Outcomes arrive by push, through /attest, and need a credential or the payer's signature; payer-signed outcomes then pass between operators through GET /outcomes.
  • Merkle evidence roots: The oracle commits a Merkle root over the evidence set at proposal time. Consumers can verify individual leaves against the chain and compare with the stored root.

Validation rules include:

  • Self-payments refused.
  • Per-payer caps enforced.
  • Volume decay applied.
  • Payer identity read from transfer logs.
  • Deduplication keyed by transaction, recipient, and sender to avoid ambiguity across multi-recipient batches.

Section sources

Dispute State and Committee Evaluation

When a slash is initiated:

  • The agent is immediately suspended.
  • The stake is frozen.
  • A challenge window begins.
  • The operator may dispute, moving the proposal to a disputed state without releasing the bond.
  • On main the admin rules on the dispute, upholding or dropping it. An upheld ruling waits for the challenge deadline fixed when the slash was filed, so a dispute never brings a slash forward, and on main it is refused once the dispute can be expired (14 days after it was filed); dropping is open at any time.
  • If unresolved, anyone can expire the dispute after a fixed period (14 days) so the freeze does not last forever.
  • The admin can also veto a pending or disputed slash, and a pending slash that nobody executed lapses: anyone can expire it 14 days after its challenge deadline. A dropped proposal of any kind (cancelled, vetoed, expired or resolved in the agent’s favour) keeps the committee from filing against the same agent again for one challenge period. The Arc testnet proxies have run this code since 26 October 2026, and the staking proxy took the bound on upholding a dispute on 28 October.
stateDiagram-v2
[*] --> Pending : "committee initiates slash"
Pending --> Disputed : "operator disputes"
Pending --> Executed : "anyone executes after the challenge deadline"
Pending --> Cancelled : "committee withdraws, admin vetoes, or anyone expires it after the execution period"
Disputed --> Executed : "admin upholds after the challenge deadline and before the dispute expires"
Disputed --> Cancelled : "admin drops or vetoes, or anyone expires it after 14 days"
Executed --> [*]
Cancelled --> [*]
Loading

Diagram sources

Section sources

Slashing Proposal Generation and Economic Penalties

  • Initiation: Only the slashing committee role can initiate a slash. The call includes the agent DID hash, victim address, and an evidence hash referencing off-chain evidence. On main it is refused for one challenge period after a proposal against the agent was dropped.
  • Suspension and freeze: The agent is suspended and its stake is frozen during the challenge window.
  • Execution: After the challenge window, anyone can execute the slash. On main, once 14 days have passed since the deadline, anyone can instead lapse it with expireSlash; until someone does it can still be executed, and whichever lands first stands (0005-governance-and-emergency-powers.md:233-235). Two slash keepers run for this on separate hosts, the primary with no grace and the backup an hour behind. Each simulates executeSlash before sending, stops at the lapse though the contract does not, and never calls expireSlash or expireDispute. As of 5 November 2026 both are live on Arc testnet, holding 20 USDC each with alerts on, and have not yet had a slash to execute (keeper.js:3-27, operations-runbook.md:689-690).
  • Distribution: 75% burned and 25% to the victim; the reporter gets nothing. Proceeds are credited and must be claimed.
  • Consequences: Identity becomes permanently slashed; reputation is zeroed.
flowchart TD
File["Committee files slash"] --> Suspend["Agent suspended + stake frozen"]
Suspend --> Window{"Challenge window active?"}
Window --> |No| Execute["Anyone executes slash"]
Window --> |Yes| Dispute{"Operator disputes?"}
Dispute --> |Yes| Resolve["Admin resolves dispute"]
Dispute --> |No| Execute
Resolve --> Uphold{"Uphold?"}
Uphold --> |Yes| Settle["Ruling settles the slash"]
Uphold --> |No| Drop["Proposal dropped"]
Execute --> Split["Burn 75%, credit victim 25%"]
Settle --> Split
Split --> Terminal["Identity slashed, reputation zeroed"]
Loading

Diagram sources

Section sources

Appeal Process for False Positives

Appeal mechanisms exist at two levels:

  • Score appeals: During the reputation challenge window, the committee can reject a proposed score. If rejected, the existing finalized score remains untouched.
  • Slash appeals: An operator can dispute a slash, freezing the stake and moving the proposal to a disputed state. On main the admin then upholds or drops the slash, and can also veto it outright. If nobody rules, anyone can expire the dispute after the resolution period, lifting the freeze.

Important constraints:

  • Disputing does not cancel the slash automatically and does not reinstate the agent.
  • The stake remains locked while the dispute is open.
  • expireDispute prevents an unruled dispute from locking the stake indefinitely; on main expireSlash does the same for a slash nobody executed.

Section sources

Integration with Watchdog Scanners and Automated Monitoring

  • Watchdog scanners: Report flags to the primary oracle, influencing the community factor and potentially lowering the total score.
  • Checker: Recomputes scores independently and records divergences when it disagrees with the primary’s proposal. It does not overwrite live proposals.
  • Watcher: Polls the checker for divergences, re-reads chain state to confirm whether a proposal is still actionable, and sends alerts to the committee before the challenge window closes. It also emits final warnings as the window nears expiration.
sequenceDiagram
participant WD as "Watchdog Scanner"
participant ORA as "Primary Oracle"
participant CHK as "Checker"
participant WAT as "Watcher"
participant CMT as "Committee"
participant CHN as "SigvaraReputation"
WD->>ORA : "Flags"
ORA->>CHN : "Proposes score"
CHK->>CHN : "Reads the pending score"
CHK-->>CHK : "Recompute and compare"
CHK->>CHK : "Record divergence if disagreeing"
WAT->>CHK : "Poll /divergence"
WAT->>WAT : "Classify actionable/expired/superseded/closed"
WAT-->>CMT : "Alert to reject before window closes"
Loading

Diagram sources

Section sources

Rate Limiting and Abuse Prevention

  • Outcome gating: Outcomes require a credential or the payer's signature, and a negative is refused without a credential (the operators also refuse a payer's signed "not delivered" for now), to prevent free denial-of-service attacks.
  • Pull-based evidence: Operators scan chain logs independently, reducing reliance on a single delivery channel and mitigating silent failures.
  • Per-payer caps and deduplication: Prevent wash trading and double-counting across multi-recipient transfers.
  • Watcher safeguards: The watcher treats checker silence as a finding and warns when the checker is unhealthy or too slow to see proposals before they expire.

Section sources

Dependency Analysis

The flag-processing pipeline depends on coordinated interactions between contracts and off-chain services:

graph LR
WD["Watchdog Scanners"] --> ORA["Primary Oracle"]
ORA --> REP["SigvaraReputation"]
CHK["Checker"] --> REP
WAT["Watcher"] --> REP
CMT["Committee"] --> ST["SigvaraStaking"]
ST --> ID["SigvaraIdentity"]
ST --> REP
Loading

Diagram sources

Section sources

Performance Considerations

  • Chain log scanning: Pulling payment evidence requires per-operator log queries. Backoff and pacing are used to respect RPC rate limits. A span a node refuses for its size is read in halves.
  • Watcher polling: The watcher polls at configurable intervals and avoids noisy notifications by tracking alert keys and escalation states.
  • Divergence pruning: Divergences older than a maximum age are pruned to keep storage bounded and ensure only relevant evidence is considered.

Recommendations:

  • Ensure all operators enable pull-based payment scanning consistently to avoid asymmetry.
  • Tune watcher poll intervals and final warning thresholds to match the challenge window cadence.
  • Monitor checker health and epoch completion to avoid false assurance from stale data.

Section sources

Troubleshooting Guide

Common issues and resolutions:

  • Committee cannot reject a score: Verify the proposal is still within the challenge window. Once expired, the committee loses the ability to reject.
  • Dispute freeze persists: Check whether the dispute was ruled on (by the admin) or whether the dispute resolution period has elapsed. Anyone can expire an unresolved dispute after the period.
  • Slash cannot be filed: On main initiateSlash reverts with SlashCooldownActive for one challenge period after a proposal against the agent was dropped.
  • Slash execution fails early: Ensure the challenge window has fully elapsed before calling executeSlash.
  • Proceeds not received: Slash proceeds are credited, not pushed. A victim claims its share with claimSlashProceeds(), as does a reporter that still holds a credit from a slash executed before 2 November 2026.
  • Watcher not alerting: Confirm the checker is healthy, completing epochs, and fast enough to see proposals before they expire. Also verify webhook configuration and payload compatibility.

Operational checks:

  • Read pending score state and challenge window from SigvaraReputation.
  • Inspect slash proposal state and deadlines from SigvaraStaking.
  • Validate identity status and slash suspension lock from SigvaraIdentity.

Section sources

Conclusion

Community flag processing in Sigvara integrates watchdog-scanner inputs, oracle scoring, Merkle-backed evidence, and a robust governance path. Flags influence community standing and can lead to divergence detection, committee review, and, ultimately, slashing when warranted. The design emphasizes verifiability, time-bound windows, and economic accountability: bonds are frozen, stakeholders are rewarded, and misbehaving agents face terminal consequences. Automated monitoring ensures human decision-makers receive timely alerts, while evidence integrity and rate-limiting measures protect the system from abuse.

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