Repository navigation
System Overview
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
Sigvara is the computed-reputation and staked-slashing layer built on top of ERC-8004. ERC-8004 provides canonical agent identity and a raw feedback ledger; Sigvara turns that feedback plus its own signals into one normalized, slashable score. The system separates computation from storage: the oracle computes scores off-chain, while smart contracts store finalized scores, manage bonds, and enforce slashing.
The high-level design answers three questions:
- How does an agent earn reputation? Through payment-backed attestations, on-chain payments, watchdog flags, ERC-8004 feedback, counterparty standing, and verified tenure.
- How is trust enforced? Through bonded operators, a challenge window around proposed scores, and economic slashing that zeroes an agent’s reputation.
- Why this architecture? It avoids centralizing computation or identity, keeps finalization permissionless, and makes scores auditable through Merkle evidence roots.
Section sources
At a system level, Sigvara consists of:
- Smart contracts for identity, reputation, staking, and operator bonding.
- An off-chain oracle process that scans chain data, computes scores, and proposes them.
- A checker process that independently recomputes pending scores and records disagreements.
- A watcher process that monitors checker divergence and escalates before challenge windows close.
- Client applications and SDKs that read finalized scores and gate access by thresholds.
graph TB
subgraph "Smart Contracts"
ID["SigvaraIdentity"]
REP["SigvaraReputation"]
STK["SigvaraStaking"]
OBOND["SigvaraOracleBond"]
end
subgraph "Off-Chain Processes"
ORA["Primary Oracle"]
CHK["Checker"]
WAT["Watcher"]
end
subgraph "External Systems"
E8004["ERC-8004 Identity + Reputation"]
CHAIN["Blockchain RPC"]
CLIENTS["Client Applications / SDK"]
end
E8004 --> ORA
CHAIN --> ORA
ORA --> REP
STK --> REP
OBOND --> REP
CHK --> REP
WAT --> CHK
CLIENTS --> REP
Diagram sources
- architecture.md:12-40
- SigvaraReputation.sol:15-75
- SigvaraStaking.sol:31-45
- SigvaraOracleBond.sol:14-45
Section sources
Sigvara’s core components are:
- ERC-8004 identity layer: Canonical agent identity and raw feedback.
-
SigvaraIdentity: Identity extension used for slash status and operator metadata. ADR 0001 calls it legacy as a direction of travel; the ERC-8004 cutover has not happened, so every agent is still keyed by its
didHashhere and it is the registry every deployed component reads and writes. - SigvaraReputation: On-chain anchor for computed scores, maturity, evidence roots, and optimistic proposal/finalize flow.
- SigvaraStaking: Agent stake, unbonding, slash initiation/dispute, and execution with reputation zeroing.
- SigvaraOracleBond: Operator performance bond registry that gates who may propose scores when enabled.
- Oracle processes: Primary oracle, checker, and watcher running on separate hosts and RPC providers.
-
SigvaraReader: A stateless, non-upgradeable read helper (
isTrusted,isTrustedFresh,trust) for on-chain consumers. The protocol does not call it, and it is not yet deployed anywhere. -
Shared bases (main):
TimelockedGrantsandInflowGuard, inherited by the four registries. Roles that move funds or change an agent’s standing are granted byUPGRADER_ROLE(the timelock, on mainnet) and revoked by the admin at once, and a guardian can pause new registrations, stake deposits, score proposals and bond deposits for three days at a time.
Key responsibilities:
- ERC-8004 supplies identity and external feedback.
- SigvaraReputation stores and serves the normalized score.
- SigvaraStaking backs agents with stake and destroys reputation on slash.
- SigvaraOracleBond backs operators with a bond and can demote underbonded operators.
- The oracle network computes and proposes scores; the checker audits; the watcher escalates.
Section sources
- 0001-erc8004-as-identity-layer.md:22-67
- SigvaraIdentity.sol:22-64
- SigvaraReputation.sol:15-75
- SigvaraStaking.sol:31-45
- SigvaraOracleBond.sol:14-45
The signal flow starts with payment attestations and ends with a finalized, matured reputation score.
sequenceDiagram
participant Platform as "Payment Platform"
participant Oracle as "Primary Oracle"
participant Chain as "Blockchain"
participant ERC8004 as "ERC-8004"
participant Rep as "SigvaraReputation"
participant Stk as "SigvaraStaking"
participant Client as "Client Application"
Platform->>Oracle : "Submit attestation with settlement transaction"
Oracle->>Chain : "Verify transfer to agent address"
Chain-->>Oracle : "Transfer log confirms payer, amount, block"
Oracle->>ERC8004 : "Read linked agent feedback (externalScore)"
ERC8004-->>Oracle : "Normalized external feedback"
Oracle->>Rep : "Propose score + evidence root"
Note over Rep : "Challenge window opens"
Client->>Rep : "Query getTotalScore / meetsThreshold"
Rep-->>Client : "Matured spendable score"
Stk->>Rep : "Slash → zero reputation"
Diagram sources
- architecture.md:12-40
- oracle README.md:220-294
- SigvaraReputation.sol:369-504
- SigvaraStaking.sol:712-776
The scoring model is optimistic:
- The oracle proposes a score with an evidence root.
- A challenge window opens.
- During the window, the slashing committee can reject a bad proposal.
- After the window, anyone can finalize the score. The window’s end is fixed when the score is proposed (the Arc testnet proxy has done this since 26 October 2026, and judges a proposal made before then against the live window), and on main finalizing refuses a proposal whose proposer has since lost its authority (the operator was removed or unbonded, its signer was cleared, or its role was revoked). A successor’s proposal replaces it.
- Finalization applies maturity so the score becomes spendable gradually.
This design keeps proposal authority flexible while ensuring finalization cannot be held hostage by any single party.
flowchart TD
Start(["Epoch begins"]) --> Compute["Oracle computes six factors"]
Compute --> Propose["Propose score + evidence root"]
Propose --> Window{"Challenge window open?"}
Window --> |Yes| Reject{"Committee rejects?"}
Reject --> |Yes| Discard["Discard pending score"]
Reject --> |No| Wait["Wait for window to close"]
Window --> |No| Finalize["Anyone finalizes score"]
Finalize --> Mature["Apply maturity curve"]
Mature --> Live["Score available to consumers"]
Discard --> End(["End"])
Live --> End
Diagram sources
Section sources
Sigvara intentionally runs three processes on separate hosts with different RPC providers:
- Primary oracle: Computes and proposes scores. Holds signing key and state.
- Checker: Recomputes pending scores independently and records disagreement. Holds signing key and own state.
- Watcher: Polls checker divergence and escalates before challenge windows close. Holds no private key.
Separation prevents shared infrastructure failures from hiding divergence and ensures a compromised watcher cannot touch the protocol.
graph LR
PHost["Primary Host<br/>Circle RPC"] --> PORACLE["Primary Oracle"]
CHost["Checker Host<br/>QuickNode RPC"] --> CHECKER["Checker"]
WHost["Watcher Host<br/>dRPC"] --> WATCHER["Watcher"]
PORACLE --> REP["SigvaraReputation"]
CHECKER --> REP
WATCHER --> CHECKER
Diagram sources
Section sources
When enabled, only admitted and bonded operators, or the signer such an operator has named, may propose scores. The operator bond registry tracks deposits, admission, unbonding, slashing, and active status. If an operator’s bond drops below the required amount, it is demoted out of the active set until it tops up and is re-admitted.
classDiagram
class SigvaraOracleBond {
+depositBond(amount)
+admit(operator)
+initiateUnbond()
+withdrawBond()
+slash(operator, amount)
+isActiveOperator(operator) bool
}
class SigvaraReputation {
+proposeReputation(didHash, data, evidenceRoot)
+finalizeReputation(didHash)
+setOperatorBond(address)
-_requireBondedOracle()
}
SigvaraReputation --> SigvaraOracleBond : "checks isActiveOperator"
Diagram sources
Section sources
ERC-8004 is the canonical identity layer. Sigvara deprecated its own did:sigvara registry as the primary registration path and instead uses ERC-8004 for identity, while retaining SigvaraReputation as the computed-score anchor and SigvaraStaking for staking and slashing. This is the intended direction, not yet the state of the deployment: the cutover has not happened (ADR 0001, update of 22 October 2026), and agents registered today are still registered in SigvaraIdentity and keyed by their didHash. What the oracle takes from ERC-8004 today is feedback for linked agents and an ownership check on the link.
The integration points are:
- ERC-8004 Identity Registry provides canonical agent identity.
- ERC-8004 Reputation Registry provides raw signed feedback.
- Sigvara reads ERC-8004 feedback to compute
externalScore. - CounterAudit publishes outcomes to both the oracle and ERC-8004, but double-counting is prevented because its ERC-8004 feedback carries its own
counteraudittag, which the normalizer does not recognise.
graph TB
CA["CounterAudit"] --> ERREP["ERC-8004 Reputation Registry"]
CA --> ORA["Sigvara Oracle"]
ERID["ERC-8004 Identity Registry"] --> ORA
ERREP --> ORA
ORA --> REP["SigvaraReputation"]
Diagram sources
Section sources
The complete signal path is:
- A platform submits an attestation with a settlement transaction.
- The oracle verifies the transfer on-chain and extracts the payer from the log.
- The oracle reads ERC-8004 feedback for linked agents.
- The oracle computes six factors: fee activity, success rate, tenure, external trust, community, and propagation.
- The oracle proposes a score and evidence root.
- Consumers read the matured score; slashing can zero it.
flowchart TD
A["Payment Attestation"] --> B["On-chain Transfer Verification"]
B --> C["Payer Extraction from Log"]
C --> D["Factor Computation"]
D --> E["Evidence Root Construction"]
E --> F["Propose Score"]
F --> G["Challenge Window"]
G --> H["Finalize Score"]
H --> I["Matured Score"]
I --> J["Consumer Gate"]
K["Slashing"] --> L["Zero Reputation"]
Diagram sources
- oracle README.md:220-294
- reputation-model.md:7-17
- SigvaraReputation.sol:369-504
- SigvaraStaking.sol:712-776
Section sources
The reputation score is deterministic and bounded between 0 and 100. The six factors are:
- Fee Activity: up to 20 points from verified settled payments.
- Success Rate: up to 15 points from outcome attestations.
- Tenure: up to 30 points from span of verified paid activity and recency.
- External Trust: up to 25 points from normalized ERC-8004 feedback.
- Community: up to 5 points reduced by unresolved flags.
- Trust Propagation: up to 5 points inherited from counterparties’ external standing.
Only bonded agents are scored. New agents start with no score and must post minimum stake before being eligible.
graph TB
FA["Fee Activity ≤ 20"] --> SUM["Total Score ≤ 100"]
SR["Success Rate ≤ 15"] --> SUM
TN["Tenure ≤ 30"] --> SUM
ET["External Trust ≤ 25"] --> SUM
CM["Community ≤ 5"] --> SUM
PR["Propagation ≤ 5"] --> SUM
Diagram sources
Section sources
A score is earned immediately upon finalization but becomes spendable over time. The matured score climbs toward the earned score at a fixed daily rate. Falls are immediate. Transfers restart maturity, however mature the score was, to prevent aged identities from becoming liquid commodities. On the Arc testnet proxy a score at or below its anchor is still returned whole.
flowchart TD
Earned["Earned Score"] --> Anchor["Anchor at Last Finalize"]
Anchor --> Rise["Gradual Rise Over Time"]
Rise --> Spendable["Spendable Score"]
Fall["Fall in Earned Score"] --> Immediate["Immediate Effect"]
Transfer["Agent Transfer"] --> Reset["Restart Maturity Clock"]
Diagram sources
Section sources
Slashing is the mechanism that makes reputation meaningful:
- A slashing committee initiates a slash.
- The agent is suspended during the challenge period.
- The operator may dispute.
- If undisputed, anyone can execute the slash.
- On main the committee files and cancels but does not rule on disputes: the admin rules on a disputed slash (an upheld ruling waits for the challenge deadline fixed at filing and is refused once the dispute can be expired) and can veto a pending or disputed one. A dispute nobody rules on expires after 14 days, and a pending slash nobody executes can be lapsed by anyone 14 days after its deadline, so a bond is never frozen by silence. After any dropped proposal the committee waits one challenge period before it can file against the same agent again.
- Execution burns part of the stake, rewards the victim and reporter, marks the agent slashed, and zeros reputation.
stateDiagram-v2
[*] --> Active
Active --> Suspended : "Slash initiated"
Suspended --> Disputed : "Operator disputes"
Disputed --> Executed : "Admin upholds"
Disputed --> Cancelled : "Admin drops"
Executed --> Slashed : "Reputation zeroed"
Cancelled --> Active : "If still bonded"
Slashed --> [*]
Diagram sources
Section sources
The system has clear dependency boundaries:
- ERC-8004 is external and provides identity and raw feedback.
- SigvaraIdentity manages agent metadata and slash status.
- SigvaraReputation depends on SigvaraIdentity and optionally SigvaraOracleBond.
- SigvaraStaking depends on SigvaraIdentity and SigvaraReputation.
- The oracle depends on chain RPCs, ERC-8004 endpoints, and contract interfaces.
- The checker depends on the same contracts but never overwrites live proposals. A proposal whose proposer has lost its authority is not live: it cannot be finalized while its proposer lacks that authority, and the checker may replace it.
- The watcher depends on the checker HTTP API and chain state.
graph TB
E8004["ERC-8004"] --> ORA["Oracle"]
CHAIN["Blockchain"] --> ORA
ORA --> REP["SigvaraReputation"]
REP --> ID["SigvaraIdentity"]
REP --> OBOND["SigvaraOracleBond"]
STK["SigvaraStaking"] --> REP
STK --> ID
CHK["Checker"] --> REP
WAT["Watcher"] --> CHK
Diagram sources
Section sources
- The oracle scans events in chunks with backoff and persists state atomically to survive restarts.
- Evidence reconstruction is expensive; the oracle caches
/evidenceresponses and rate-limits unauthenticated readers. - Maturity accrues on read, so an outage cannot hold an honest agent below its earned score indefinitely.
- The checker comparison uses a tolerance to absorb float drift, which is acknowledged as a trade-off rather than perfect determinism.
- Payment scanning ships off by default (
PAYMENT_SCAN_ENABLED=0) because enabling it changes scores and has to be done on every operator or none. It has been enabled on both live operators since 3 October 2026, forward-only from a recent block.
Common operational issues and their signals:
- Stale scoring: Health endpoint returns 503 if no successful epoch occurred within twice the epoch interval.
-
State persistence failure: Health reports
statePersisted: false; attestations accepted locally may be lost on restart. -
Checker divergence: Checker exposes
/divergence; watcher alerts when a divergence is actionable and again near the challenge window close. - RPC unreliability: Payment scan canaries distinguish empty ranges from broken queries; pacing avoids RPC refusal storms.
-
Missing ERC-8004 feed: Health reports
externalFeedas disabled, configured, or unreachable; external score renders zero in multiple unrelated situations.
Operational recommendations:
- Monitor
/health,/metrics, and watcher alerts. - Ensure the checker epoch cadence is shorter than half the challenge window.
- Run the watcher on a separate host from the checker.
- Keep evidence endpoints reachable so third parties can audit scores without trusting the operator.
Section sources
Sigvara’s system overview centers on a clean separation of concerns: ERC-8004 owns canonical identity and raw feedback, Sigvara computes a normalized reputation score, and staking/slashing gives that score economic meaning. The three-process oracle architecture isolates computation, auditing, and escalation across hosts and RPC providers. The optimistic scoring model balances liveness and security by allowing permissionless finalization while giving a committee a challenge window to reject bad proposals. The bonded operator system adds another layer of accountability for who may propose scores. Together, these choices make Sigvara auditable, slashable, and resilient against single-point failures.
- Agent Registration and Lifecycle
- Contract Overview and Architecture
- Economic Security Model and Incentives
- Evidence Verification and Merkle Proofs
- Key Management and Rotation
- Maturity Mechanism and Score Release
- Proposal Workflow and Challenge System
- Score Storage and Data Model
- SigvaraIdentity Contract
- SigvaraOracleBond Contract
- SigvaraReputation Contract
- SigvaraStaking Contract
- Slashing Lifecycle and Dispute Resolution
- Stake Management Functions
- Status Management and Control
- Token and Fee Contracts
- Unbonding Period and Withdrawal Security
- Anti-Manipulation and Security Measures
- Community Flag Processing
- Evidence Sources and Verification
- External Trust Integration
- Merkle Proof System
- Oracle Score Computation
- Payment-Backed Attestations
- Scoring Model and Formulas
- Agent Creation and Key Management
- Agent Operations
- Agent Registration Workflow
- Challenge-Response Authentication
- Gate Access Control
- Integration Patterns and Examples
- SDK Overview and Setup
- Verifier Functions