Skip to content

Smart Contracts Reference CountersigReputation Contract

Jump to bottom
dev-mondoshawan edited this page Jul 1, 2026 · 1 revision

CountersigReputation Contract

**Referenced Files in This Document** - [CountersigReputation.sol](file://src/CountersigReputation.sol) - [CountersigReputation.t.sol](file://test/CountersigReputation.t.sol) - [scoring.js](file://oracle/scoring.js) - [index.js](file://oracle/index.js) - [chain.js](file://oracle/chain.js) - [CountersigStaking.sol](file://src/CountersigStaking.sol) - [types.ts](file://packages/sdk/src/types.ts) - [reputation-model.md](file://docs/reputation-model.md)

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 provides comprehensive technical documentation for the CountersigReputation contract, which implements a deterministic 6-factor reputation scoring system. The contract stores and serves reputation scores for registered agents, while the actual computation is performed off-chain by an oracle network. The system separates concerns: the oracle computes scores and writes them on-chain, while the contract validates and exposes them to consumers.

Key aspects covered:

  • 6-factor reputation scoring methodology and weights
  • Storage structure for reputation data and timestamps
  • Threshold validation and score retrieval APIs
  • Oracle integration and epoch processing
  • Event emissions and error handling
  • Practical workflows for reputation checking and integration with agent authentication systems

Project Structure

The reputation system spans multiple components:

  • On-chain contract: CountersigReputation stores and serves reputation data
  • Off-chain oracle: Computes scores and writes them to the contract
  • Supporting contracts: CountersigStaking integrates reputation with slashing
  • SDK types: Define the data structures used by clients
  • Documentation: Describes the reputation model and epoch processing
graph TB
subgraph "On-chain"
CR["CountersigReputation.sol"]
CS["CountersigStaking.sol"]
end
subgraph "Off-chain"
OR["oracle/index.js"]
SC["oracle/scoring.js"]
CH["oracle/chain.js"]
end
subgraph "Consumers"
SDK["packages/sdk/src/types.ts"]
Apps["Applications"]
end
OR --> CH
CH --> CR
OR --> SC
CS --> CR
SDK --> CR
Apps --> CR
Loading

Diagram sources

  • CountersigReputation.sol:24-180
  • CountersigStaking.sol:28-330
  • index.js:1-203
  • scoring.js:1-50
  • chain.js:1-85
  • types.ts:21-30

Section sources

  • CountersigReputation.sol:1-181
  • CountersigStaking.sol:1-331
  • index.js:1-203
  • scoring.js:1-50
  • chain.js:1-85
  • types.ts:1-66

Core Components

  • CountersigReputation: Stores 6-factor reputation data per agent, validates score boundaries, and exposes read APIs and threshold checks.
  • Oracle system: Computes scores off-chain and writes them to the contract via updateReputation.
  • CountersigStaking: Integrates reputation with slashing, zeroing scores upon execution.
  • SDK types: Define the on-chain data structures for clients.

Key capabilities:

  • Deterministic 6-factor scoring with predefined maximums
  • Role-based access control for oracle and staking core
  • Threshold-based gating for agent trust checks
  • Event emissions for score changes and zeroing

Section sources

  • CountersigReputation.sol:24-180
  • CountersigStaking.sol:28-330
  • types.ts:21-30

Architecture Overview

The reputation architecture follows a clear separation of concerns:

  • Oracle computes scores using pure functions and writes them on-chain
  • Contract validates inputs and persists data
  • Consumers query scores and thresholds for trust decisions
  • Staking integrates reputation with slashing to maintain economic finality
sequenceDiagram
participant Oracle as "Oracle"
participant Chain as "EVM Chain"
participant Rep as "CountersigReputation"
participant Staking as "CountersigStaking"
participant Consumer as "Consumer Contracts"
Oracle->>Oracle : "Compute scores (pure functions)"
Oracle->>Chain : "Submit write transaction"
Chain->>Rep : "updateReputation(didHash, data)"
Rep->>Rep : "Validate factor caps"
Rep->>Chain : "Emit ReputationUpdated"
Chain-->>Oracle : "Transaction receipt"
Staking->>Rep : "zeroReputation(didHash) on slash"
Rep->>Chain : "Emit ReputationZeroed"
Consumer->>Rep : "getTotalScore(didHash)"
Consumer->>Rep : "meetsThreshold(didHash, threshold)"
Loading

Diagram sources

  • index.js:41-95
  • scoring.js:36-47
  • CountersigReputation.sol:107-129
  • CountersigStaking.sol:283-293

Detailed Component Analysis

CountersigReputation Contract

The contract defines roles, storage, events, errors, initialization, write functions, and read functions.

  • Roles:

    • ORACLE_ROLE: Authorized to write reputation updates
    • STAKING_CORE_ROLE: Authorized to zero scores on slash
    • UPGRADER_ROLE: Authorized to upgrade the contract

  • Data structure:

    • ReputationData: Contains six factor scores, plus lastUpdated timestamp
    • Storage: mapping of didHash to ReputationData

  • Events:

    • ReputationUpdated: Emitted on successful score update
    • ReputationZeroed: Emitted when scores are zeroed by staking

  • Errors:

    • ScoreOutOfRange: Thrown when any factor exceeds its maximum

  • Initialization:

    • Grants admin/upgrader roles to the admin address
    • Optionally grants ORACLE_ROLE and STAKING_CORE_ROLE to provided addresses

  • Public functions:

    • updateReputation: Writes validated scores and emits ReputationUpdated
    • zeroReputation: Zeros all scores and emits ReputationZeroed
    • getReputation: Returns stored ReputationData
    • getTotalScore: Returns sum of all six factors (≤100)
    • meetsThreshold: Checks if total score meets a given threshold
classDiagram
class CountersigReputation {
+bytes32 ORACLE_ROLE
+bytes32 STAKING_CORE_ROLE
+bytes32 UPGRADER_ROLE
+mapping(bytes32 => ReputationData) reputations
+initialize(admin, oracle, stakingCore)
+updateReputation(didHash, data)
+zeroReputation(didHash)
+getReputation(didHash) ReputationData
+getTotalScore(didHash) uint8
+meetsThreshold(didHash, threshold) bool
+_authorizeUpgrade(address)
}
class ReputationData {
+uint8 feeScore
+uint8 successScore
+uint8 ageScore
+uint8 externalScore
+uint8 communityScore
+uint8 propagationScore
+uint256 lastUpdated
}
CountersigReputation --> ReputationData : "stores"
Loading

Diagram sources

  • CountersigReputation.sol:24-180

Section sources

  • CountersigReputation.sol:24-180

Reputation Calculation Methodology

The off-chain oracle computes six factors using pure functions. The contract validates that each factor does not exceed its maximum before storing.

  • Factor definitions and maximums:

    • feeScore: up to 30
    • successScore: up to 25
    • ageScore: up to 20
    • externalScore: up to 15
    • communityScore: up to 5
    • propagationScore: up to 5

  • Total cap: 100

  • Computation functions (off-chain):

    • feeScore: derived from attestation count (proxy for fee activity)
    • successScore: ratio of successful to total attestations
    • ageScore: logarithmic function of registration age
    • externalScore: placeholder (currently 0)
    • communityScore: penalty based on unresolved flags
    • propagationScore: placeholder (currently 0)

  • Aggregation:

    • getTotalScore sums all six factors and asserts ≤100
flowchart TD
Start(["Compute Scores"]) --> FS["feeScore(attestationTotal)"]
Start --> SS["successScore(successful,total)"]
Start --> AS["ageScore(registeredAtSeconds)"]
Start --> ES["externalScore (placeholder)"]
Start --> CS["communityScore(unresolvedFlags)"]
Start --> PS["propagationScore (placeholder)"]
FS --> Sum["Sum = FS + SS + AS + ES + CS + PS"]
SS --> Sum
AS --> Sum
ES --> Sum
CS --> Sum
PS --> Sum
Sum --> Cap["Assert Sum ≤ 100"]
Cap --> Store["Store in ReputationData"]
Loading

Diagram sources

  • scoring.js:9-47
  • CountersigReputation.sol:156-169

Section sources

  • scoring.js:1-50
  • CountersigReputation.sol:16-23
  • CountersigReputation.sol:156-169

Storage Structure and Timestamps

  • Storage layout:
    • Mapping from didHash to ReputationData
    • Each ReputationData includes:
      • Six uint8 factor scores
      • lastUpdated timestamp (block.timestamp on write)
  • Behavior:
    • updateReputation overwrites all fields and sets lastUpdated
    • zeroReputation sets all scores to 0 but preserves lastUpdated

Section sources

  • CountersigReputation.sol:42-50
  • CountersigReputation.sol:118-126
  • CountersigReputation.sol:135-146

Threshold Validation and Score Retrieval

  • getTotalScore:
    • Sums all six factors
    • Asserts total ≤ 100
    • Returns uint8
  • meetsThreshold:
    • Compares total score to provided threshold
    • Returns boolean
sequenceDiagram
participant App as "Application"
participant Rep as "CountersigReputation"
App->>Rep : "getTotalScore(didHash)"
Rep-->>App : "uint8 total"
App->>Rep : "meetsThreshold(didHash, threshold)"
Rep-->>App : "bool"
Loading

Diagram sources

  • CountersigReputation.sol:156-173

Section sources

  • CountersigReputation.sol:152-173

Oracle Integration and Epoch Processing

  • Oracle responsibilities:
    • Compute scores using pure functions
    • Query registered agents and agent info
    • Write scores to the contract via updateReputation
    • Respect epoch intervals and handle errors
  • Epoch flow:
    • Scan for new registrations within block chunks
    • Aggregate attestations and flags in-memory
    • Compute scores and submit transactions
    • Emit logs for each updated agent
sequenceDiagram
participant Oracle as "Oracle"
participant Identity as "Identity Contract"
participant Rep as "CountersigReputation"
Oracle->>Identity : "getRegisteredAgents()"
Identity-->>Oracle : "List of didHash"
Oracle->>Identity : "getIdentity(didHash)"
Identity-->>Oracle : "registeredAt, status"
Oracle->>Oracle : "computeScore(...)"
Oracle->>Rep : "updateReputation(didHash, scores)"
Rep-->>Oracle : "ReputationUpdated event"
Loading

Diagram sources

  • index.js:41-95
  • chain.js:36-82
  • scoring.js:36-47

Section sources

  • index.js:1-203
  • chain.js:1-85
  • scoring.js:1-50

Relationship with Staking and Slashing

  • Staking triggers reputation zeroing on slash execution:
    • Calls zeroReputation(didHash)
    • Updates agent status to Slashed
  • Economic finality:
    • Slashed agents cannot be reactivated
    • Stake distribution occurs independently
sequenceDiagram
participant Staking as "CountersigStaking"
participant Rep as "CountersigReputation"
Staking->>Rep : "zeroReputation(didHash)"
Rep-->>Staking : "ReputationZeroed event"
Loading

Diagram sources

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

Section sources

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

Practical Workflows and Integration Patterns

  • Reputation checking:
    • Gate access to sensitive operations using meetsThreshold
    • Query total score for transparency
  • Integration with agent authentication:
    • Combine reputation checks with signature verification
    • Enforce minimum thresholds before allowing delegation or payment
  • Example patterns:
    • Require threshold ≥ 50 for advanced features
    • Allow zero threshold for basic operations

Section sources

  • reputation-model.md:117-138

Dependency Analysis

  • Internal dependencies:
    • CountersigStaking depends on CountersigReputation for zeroing scores
    • CountersigReputation depends on OpenZeppelin for access control and upgrades
  • External dependencies:
    • Oracle uses ethers.js for blockchain interaction
    • Oracle uses dotenv for environment configuration
  • Data dependencies:
    • Oracle reads Identity contract events and state
    • Oracle writes to CountersigReputation contract
graph LR
CS["CountersigStaking.sol"] --> CR["CountersigReputation.sol"]
OR["oracle/index.js"] --> CH["oracle/chain.js"]
OR --> SC["oracle/scoring.js"]
CH --> CR
SDK["types.ts"] --> CR
Loading

Diagram sources

  • CountersigStaking.sol:69-71
  • index.js:1-203
  • chain.js:1-85
  • scoring.js:1-50
  • types.ts:21-30

Section sources

  • CountersigStaking.sol:69-71
  • index.js:1-203
  • chain.js:1-85
  • types.ts:21-30

Performance Considerations

  • Gas efficiency:
    • updateReputation performs minimal validation and writes a single struct
    • getTotalScore uses fixed-size arithmetic and asserts ≤100
  • Scalability:
    • Oracle processes agents sequentially to maintain nonce ordering
    • Epoch intervals can be tuned for throughput vs. latency
  • Memory:
    • Oracle maintains in-memory maps for attestations and flags
    • Restarting recomputes from on-chain events

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Unauthorized write attempts:
    • Ensure caller has ORACLE_ROLE
    • Verify role assignment during initialization
  • Score out of range:
    • Confirm factor values do not exceed maximums
    • Review oracle computation logic
  • Zeroing not triggered:
    • Confirm caller has STAKING_CORE_ROLE
    • Verify slash execution path was taken
  • Threshold checks failing unexpectedly:
    • Validate didHash correctness
    • Confirm epoch has run and scores were updated

Section sources

  • CountersigReputation.t.sol:51-115
  • CountersigReputation.t.sol:177-181
  • CountersigReputation.sol:107-129
  • CountersigReputation.sol:135-146

Conclusion

The CountersigReputation contract provides a robust, deterministic 6-factor reputation system with clear separation between computation and storage. Off-chain oracle computation ensures flexibility and evolvability, while on-chain validation guarantees data integrity. The integration with Staking reinforces economic finality, and the threshold-based API enables straightforward trust gating for applications.

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

Appendices

Reputation Factor Definitions and Formulas

  • Fee Activity (up to 30): Derived from attestation count
  • Success Rate (up to 25): Ratio of successful to total attestations
  • Registration Age (up to 20): Logarithmic function of days since registration
  • External Trust (up to 15): Placeholder for cross-platform identity
  • Community (up to 5): Penalty based on unresolved flags
  • Trust Propagation (up to 5): Placeholder for network effects

Section sources

  • reputation-model.md:7-83
  • scoring.js:9-47

Event Emission Reference

  • ReputationUpdated: Emitted on successful updateReputation
  • ReputationZeroed: Emitted on zeroReputation

Section sources

  • CountersigReputation.sol:62-63
  • CountersigReputation.sol
  • CountersigReputation.sol

SDK Data Model

  • ReputationData fields align with contract storage for client consumption

Section sources

  • types.ts:21-30

Home

Start Here

Core Concepts

Smart Contracts

Oracle System

Agent SDK

Integration Guides

Economic Model

Deployment & Ops

Advanced Topics

Clone this wiki locally