Reputation System

Reputation System

**Referenced Files in This Document** - [CountersigReputation.sol](file://src/CountersigReputation.sol) - [scoring.js](file://oracle/scoring.js) - [scoring.test.js](file://oracle/scoring.test.js) - [CountersigStaking.sol](file://src/CountersigStaking.sol) - [CountersigIdentity.sol](file://src/CountersigIdentity.sol) - [CountersigReputation.t.sol](file://test/CountersigReputation.t.sol) - [verifier.ts](file://packages/sdk/src/verifier.ts) - [agent.ts](file://packages/sdk/src/agent.ts) - [index.ts](file://packages/sdk/src/index.ts) - [reputation-model.md](file://docs/reputation-model.md) - [reputation.html](file://site/countersig_network_v2/countersig_v2/docs/reputation.html)

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
10. Appendices

Introduction

This document describes the Countersig Network reputation system: a deterministic 6-factor scoring mechanism that measures trustworthiness for AI agents. The system separates computation (off-chain) from storage (on-chain). Off-chain oracles compute scores using a fixed algorithm and write validated results to the on-chain CountersigReputation contract. Consumers can gate access or tailor service levels using simple threshold checks.

Project Structure

The reputation system spans three primary areas:

• On-chain storage and validation in the CountersigReputation contract
• Off-chain scoring computation in the oracle module
• Consumer integration via the SDK verifier and smart contracts

graph TB
subgraph "Off-chain"
O["Oracle Scoring<br/>computeScore(...)"]
end
subgraph "On-chain"
R["CountersigReputation<br/>updateReputation(), getTotalScore()"]
S["CountersigStaking<br/>executeSlash()"]
I["CountersigIdentity<br/>Agent lifecycle"]
end
subgraph "Consumers"
C["Smart Contracts<br/>meetsThreshold()"]
SDK["SDK Verifier<br/>getReputation(), meetsThreshold()"]
end
O --> |"Writes validated scores"| R
S --> |"zeroReputation()"| R
I --> |"Agent status & DID"| R
C --> |"Reads scores"| R
SDK --> |"Reads scores"| R

Loading

Diagram sources

• CountersigReputation.sol:100-173
• scoring.js:36-47
• CountersigStaking.sol:263-293
• CountersigIdentity.sol:18-41
• verifier.ts:67-88

Section sources

• CountersigReputation.sol:1-181
• scoring.js:1-50
• CountersigStaking.sol:1-331
• CountersigIdentity.sol:1-227
• verifier.ts:1-160

Core Components

• CountersigReputation: stores and validates 6-factor scores; exposes threshold checks and total score reads.
• Oracle scoring: computes each factor off-chain and returns a validated total ≤ 100.
• CountersigStaking: slashes agents and triggers reputation reset.
• CountersigIdentity: anchors agent identities and statuses.
• SDK Verifier: consumer-facing client to read reputation and identity data.

Section sources

• CountersigReputation.sol:24-180
• scoring.js:36-47
• CountersigStaking.sol:28-331
• CountersigIdentity.sol:18-227
• verifier.ts:15-133

Architecture Overview

The reputation pipeline:

• Oracle epoch ends: collect on-chain signals (e.g., registration age, attestations).
• Compute 6 factors off-chain using deterministic formulas.
• Submit updateReputation(didHash, data) with each factor within its cap.
• On-chain contract validates caps and writes the score; emits ReputationUpdated.
• Consumers read meetsThreshold() or getTotalScore() for access control or service tiers.

sequenceDiagram
participant Epoch as "Oracle Epoch"
participant Oracle as "Scoring Engine"
participant Chain as "CountersigReputation"
participant Staking as "CountersigStaking"
participant Consumer as "Contract/App"
Epoch->>Oracle : Aggregate on-chain signals
Oracle->>Oracle : computeScore(...)
Oracle->>Chain : updateReputation(didHash, data)
Chain->>Chain : Validate each factor <= cap
Chain-->>Consumer : emits ReputationUpdated
Consumer->>Chain : meetsThreshold(didHash, threshold)
Chain-->>Consumer : bool
Note over Staking,Chain : executeSlash() -> zeroReputation(didHash)

Loading

Diagram sources

• CountersigReputation.sol:100-129
• scoring.js:36-47
• CountersigStaking.sol:263-293

Detailed Component Analysis

CountersigReputation: On-chain Storage and Validation

Responsibilities:

• Store per-agent 6-factor scores and lastUpdated timestamp.
• Enforce factor caps at write time.
• Provide getTotalScore() and meetsThreshold().
• Emit events on updates and resets.

Key behaviors:

• updateReputation validates each factor against its maximum and reverts if exceeded.
• getTotalScore sums validated factors; assert ensures total ≤ 100.
• meetsThreshold compares total vs. threshold.
• zeroReputation sets all scores to 0 while preserving lastUpdated.

classDiagram
class CountersigReputation {
+initialize(admin, oracle, stakingCore)
+updateReputation(didHash, data)
+zeroReputation(didHash)
+getReputation(didHash) ReputationData
+getTotalScore(didHash) uint8
+meetsThreshold(didHash, threshold) bool
-reputations mapping(bytes32 -> ReputationData)
}
class ReputationData {
+uint8 feeScore
+uint8 successScore
+uint8 ageScore
+uint8 externalScore
+uint8 communityScore
+uint8 propagationScore
+uint256 lastUpdated
}
CountersigReputation --> ReputationData : "stores"

Loading

Diagram sources

• CountersigReputation.sol:42-50
• CountersigReputation.sol:100-173

Section sources

• CountersigReputation.sol:24-180
• CountersigReputation.t.sol:38-197

Oracle Scoring: Off-chain Computation

Responsibilities:

• Compute each of the six factors deterministically from on-chain signals.
• Return a validated total ≤ 100.

Factor definitions and caps:

• feeScore: up to 30
• successScore: up to 25
• ageScore: up to 20
• externalScore: up to 15 (stubbed; Phase 2)
• communityScore: up to 5
• propagationScore: up to 5 (stubbed; Phase 2)

flowchart TD
Start(["Compute Score"]) --> FS["feeScore(attestationTotal)"]
FS --> SS["successScore(successful,total)"]
SS --> AS["ageScore(registeredAtSeconds)"]
AS --> ES["externalScore (stub)"]
ES --> CS["communityScore(unresolvedFlags)"]
CS --> PS["propagationScore (stub)"]
PS --> Sum["total = sum of factors"]
Sum --> Cap["Ensure total ≤ 100"]
Cap --> End(["Return {..., total}"])

Loading

Diagram sources

• scoring.js:9-47

Section sources

• scoring.js:1-50
• scoring.test.js:1-109
• reputation-model.md:7-83

Slashing and Reputation Reset

When an agent is slashed:

• CountersigStaking.executeSlash() sets agent status to Slashed and calls zeroReputation(didHash).
• All six factor scores become 0; lastUpdated remains unchanged.
• The agent cannot be reactivated; operator must register a new agent with a new DID.

sequenceDiagram
participant Staking as "CountersigStaking"
participant Identity as "CountersigIdentity"
participant Reputation as "CountersigReputation"
Staking->>Identity : updateStatus(didHash, Slashed)
Staking->>Reputation : zeroReputation(didHash)
Reputation-->>Staking : emits ReputationZeroed

Loading

Diagram sources

• CountersigStaking.sol:263-293
• CountersigReputation.sol:135-146

Section sources

• CountersigStaking.sol:18-33
• CountersigStaking.sol:263-293
• CountersigReputation.sol:135-146
• reputation-model.md:104-114

Consumer Integration Patterns

• Smart contracts: call meetsThreshold(didHash, threshold) for access control.
• SDK Verifier: getReputation(did) returns full breakdown; meetsThreshold(did, threshold) returns a boolean.

sequenceDiagram
participant App as "Consumer App"
participant SDK as "SDK Verifier"
participant Chain as "CountersigReputation"
App->>SDK : getReputation(did)
SDK->>Chain : getReputation(didHash)
Chain-->>SDK : {fee,success,age,ext,comm,prop,total}
SDK-->>App : ReputationData
App->>SDK : meetsThreshold(did, 60)
SDK->>Chain : meetsThreshold(didHash, 60)
Chain-->>SDK : bool
SDK-->>App : trusted?

Loading

Diagram sources

• verifier.ts:67-88
• CountersigReputation.sol:152-173

Section sources

• verifier.ts:67-88
• reputation-model.md:117-138

Dependency Analysis

• CountersigReputation depends on:
  • Oracle roles for write access (ORACLE_ROLE)
  • Staking core role for zeroing scores (STAKING_CORE_ROLE)
• CountersigStaking depends on:
  • CountersigIdentity for agent status
  • CountersigReputation for score reset
• SDK Verifier depends on:
  • CountersigReputation ABI for reads
  • CountersigIdentity ABI for identity/status
  • CountersigStaking ABI for stake data

graph LR
Oracle["Oracle Scoring"] --> CR["CountersigReputation"]
CS["CountersigStaking"] --> CI["CountersigIdentity"]
CS --> CR
SDK["SDK Verifier"] --> CR
SDK --> CI
SDK --> CS

Loading

Diagram sources

• CountersigReputation.sol:28-36
• CountersigStaking.sol:69-71
• verifier.ts:26-36

Section sources

• CountersigReputation.sol:28-36
• CountersigStaking.sol:69-71
• verifier.ts:26-36

Performance Considerations

• Off-chain computation: Deterministic functions are lightweight; batch processing across many agents is feasible.
• On-chain writes: updateReputation performs bounded validations and a single storage write per agent per epoch.
• Reads: meetsThreshold and getTotalScore are O(1) view calls suitable for frequent checks.
• Gas efficiency: Using meetsThreshold avoids fetching full breakdown when only a pass/fail is needed.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

• ScoreOutOfRange errors on updateReputation indicate a factor exceeded its cap; adjust oracle logic or inputs.
• Non-oracle attempts to update reputation revert; ensure only authorized oracle addresses submit updates.
• Threshold checks returning false: verify didHash derivation and epoch timing; ensure the oracle has written a recent update.
• After slashing, all scores are zero; confirm the agent’s status is Slashed and that zeroReputation executed.

Section sources

• CountersigReputation.sol:100-129
• CountersigReputation.t.sol:51-115
• CountersigStaking.sol:263-293

Conclusion

Countersig’s reputation system balances determinism and evolvability: the scoring algorithm lives off-chain for flexibility, while the on-chain contract guarantees verifiable, immutable storage and fast access. The 6-factor design covers economic activity, reliability, longevity, external trust, community health, and network effects. Slashing provides economic finality, reinforcing the value of reputation. Consumers can integrate thresholds easily, enabling robust reputation-based gating and tiered services.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Scoring Algorithm Reference

• Factor definitions and caps:
  • Fee Activity: up to 30
  • Success Rate: up to 25
  • Registration Age: up to 20
  • External Trust: up to 15 (Phase 2)
  • Community: up to 5
  • Trust Propagation: up to 5 (Phase 2)
• Total cap: 100
• Oracle epoch cadence: configurable; default described in documentation

Section sources

• CountersigReputation.sol:16-23
• scoring.js:36-47
• reputation-model.md:7-148

Practical Examples

• Reputation-based gating:
  • Solidity: require meetsThreshold(didHash, 60) in access-control modifiers.
  • SDK: await meetsThreshold(did, 60) for frontend decisions.
• Score interpretation:
  • 80–100: HIGH trust
  • 60–79: MEDIUM trust
  • 40–59: LOW trust
  • 0–39: UNVERIFIED
• Reputation management strategies:
  • Focus on sustained economic activity and successful attestations.
  • Maintain low unresolved flags.
  • Build external trust credentials (Phase 2).
  • Avoid slashing; it resets all scores to zero.

Section sources

• reputation-model.md:117-167
• reputation.html:129-167