-
Notifications
You must be signed in to change notification settings - Fork 0
Advanced Topics Protocol Governance
dev-mondoshawan edited this page Jul 1, 2026
·
1 revision
**Referenced Files in This Document**
- [CSIGToken.sol](file://src/CSIGToken.sol)
- [CountersigIdentity.sol](file://src/CountersigIdentity.sol)
- [CountersigReputation.sol](file://src/CountersigReputation.sol)
- [CountersigStaking.sol](file://src/CountersigStaking.sol)
- [Deploy.s.sol](file://script/Deploy.s.sol)
- [CountersigIdentity.t.sol](file://test/CountersigIdentity.t.sol)
- [CountersigReputation.t.sol](file://test/CountersigReputation.t.sol)
- [CountersigStaking.t.sol](file://test/CountersigStaking.t.sol)
- [tokenomics.md](file://docs/tokenomics.md)
- [reputation-model.md](file://docs/reputation-model.md)
- [README.md](file://README.md)
- [index.js](file://oracle/index.js)
- [scoring.js](file://oracle/scoring.js)
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
This document describes the governance model for Countersig Network, focusing on decision-making processes, parameter management, upgrade mechanisms, access control, multisig governance, emergency pause capabilities, economic governance, and protocol evolution. It synthesizes on-chain contracts, off-chain oracle scoring, and governance documentation to present a complete picture of how the protocol is governed, secured, and evolved.
The repository is organized around three core upgradeable contracts and associated tooling:
- Core contracts: Identity, Reputation, Staking, and the testnet token
- Off-chain oracle for reputation scoring
- Foundry scripts and tests validating governance flows
- Documentation for tokenomics and reputation mechanics
graph TB
subgraph "Contracts"
ID["CountersigIdentity"]
REP["CountersigReputation"]
ST["CountersigStaking"]
TOK["CSIGToken (testnet)"]
end
subgraph "Governance"
TL["TimelockController (mainnet)"]
MS["3-of-5 Multisig (testnet)"]
end
subgraph "Off-chain"
ORA["Oracle Network<br/>HTTP + Scoring"]
end
ID --> ST
REP --> ST
ST --> ID
ST --> REP
ORA --> REP
TL -. "roles, upgrades" .- ID
TL -. "roles, upgrades" .- REP
TL -. "roles, upgrades" .- ST
MS -. "slash initiation (testnet)" .- ST
Diagram sources
- README.md:20-52
- CountersigIdentity.sol:18-101
- CountersigReputation.sol:24-94
- CountersigStaking.sol:28-142
- Deploy.s.sol:31-106
Section sources
- README.md:55-64
- script/Deploy.s.sol:31-106
- CountersigIdentity: Anchors DIDs, stores operator and Ed25519 public key, tracks agent status, and enforces operator-only actions except for STAKING_CORE_ROLE.
- CountersigReputation: Oracle-written store of 6-factor reputation scores; validates per-factor caps and exposes threshold checks.
- CountersigStaking: Manages CSIG stakes, slash lifecycle with a challenge period, and distributes slashed tokens; integrates with Identity and Reputation.
- CSIGToken: Testnet mintable token for operator onboarding and faucet; mainnet token is non-mintable and governed.
- Oracle Network: Off-chain reputation computation and epoch submission to CountersigReputation.
Section sources
- src/CountersigIdentity.sol:18-227
- src/CountersigReputation.sol:24-181
- src/CountersigStaking.sol:28-331
- src/CSIGToken.sol:12-26
- oracle/index.js:46-113
The governance architecture centers on role-based access control and UUPS upgrades, with a timelock controller managing upgrades and parameter changes on mainnet. The testnet uses a multisig for slash initiation, while mainnet paths are designed to replace it with on-chain arbitration.
sequenceDiagram
participant Admin as "Admin/Governance"
participant TL as "TimelockController"
participant ID as "CountersigIdentity"
participant REP as "CountersigReputation"
participant ST as "CountersigStaking"
Admin->>TL : propose role/upgrade changes
TL->>ID : grant roles / authorize upgrades
TL->>REP : grant roles / authorize upgrades
TL->>ST : grant roles / authorize upgrades
TL-->>Admin : execute after delay
Diagram sources
- README.md:348-358
- tokenomics.md:133-146
- CountersigIdentity.sol:224-225
- CountersigReputation.sol:179-179
- CountersigStaking.sol:329-329
- Roles:
- DEFAULT_ADMIN_ROLE: Grants/revokes all roles; authorizes upgrades.
- UPGRADER_ROLE: Authorizes UUPS upgrades.
- STAKING_CORE_ROLE: CountersigStaking can suspend/slashed agents and zero reputation.
- ORACLE_ROLE: Oracle consensus can write reputation updates.
- SLASHING_COMMITTEE_ROLE: Testnet 3-of-5 multisig; mainnet path is on-chain arbitration.
- UUPS Upgrades: All contracts implement UUPSUpgradeable and override _authorizeUpgrade to restrict upgrades to UPGRADER_ROLE holders.
classDiagram
class CountersigIdentity {
+initialize(admin, stakingCore)
+registerAgent(agentAddress, ed25519PubKey)
+rotatePublicKey(didHash, newEd25519PubKey)
+updateStatus(didHash, newStatus)
+_authorizeUpgrade(target)
}
class CountersigReputation {
+initialize(admin, oracle, stakingCore)
+updateReputation(didHash, data)
+zeroReputation(didHash)
+_authorizeUpgrade(target)
}
class CountersigStaking {
+initialize(admin, identity, reputation, csig, minStake, challengePeriod)
+depositStake(didHash, amount)
+withdrawStake(didHash, amount)
+initiateSlash(didHash, victim, evidenceHash)
+disputeSlash(didHash)
+executeSlash(didHash)
+_authorizeUpgrade(target)
}
CountersigIdentity --> CountersigStaking : "STAKING_CORE_ROLE"
CountersigReputation --> CountersigStaking : "STAKING_CORE_ROLE"
CountersigReputation --> Oracle : "ORACLE_ROLE"
CountersigStaking --> CountersigIdentity : "updateStatus()"
CountersigStaking --> CountersigReputation : "zeroReputation()"
Diagram sources
- CountersigIdentity.sol:18-227
- CountersigReputation.sol:24-181
- CountersigStaking.sol:28-331
Section sources
- README.md:348-358
- src/CountersigIdentity.sol:224-225
- src/CountersigReputation.sol:179-179
- src/CountersigStaking.sol:329-329
- Testnet: SLASHING_COMMITTEE_ROLE is held by a 3-of-5 multisig. It can initiate slashes with evidence and a victim address.
- Emergency pause: During the challenge period, the agent operator can dispute a slash; if undisputed, anyone can execute it. The challenge period acts as a de facto pause window for malicious slash attempts.
- Mainnet path: Replace the multisig with on-chain arbitration (UMA OptimisticOracleV3 or Kleros) while keeping the slash initiation/dispute interface isolated to avoid storage migrations.
sequenceDiagram
participant CM as "Committee (3-of-5)"
participant ST as "CountersigStaking"
participant ID as "CountersigIdentity"
participant REP as "CountersigReputation"
CM->>ST : initiateSlash(didHash, victim, evidenceHash)
ST->>ID : updateStatus(Suspended)
Note over ST : Challenge period begins
alt Operator disputes within window
Op->>ST : disputeSlash(didHash)
ST->>ID : updateStatus(Active)
else Challenge period elapses
Anyone->>ST : executeSlash(didHash)
ST->>ID : updateStatus(Slashed)
ST->>REP : zeroReputation(didHash)
end
Diagram sources
- README.md:153-178
- src/CountersigStaking.sol:205-293
Section sources
- README.md:147-188
- src/CountersigStaking.sol:199-293
- Voting and delegation: No governance token is defined in the repository; token-based voting rights are noted as a separate post-mainnet module.
- Participation incentives: Oracle operators are incentivized via query fee shares, treasury subsidies, and epoch submission reimbursements.
- Proposal submission: Mainnet uses a TimelockController with proposers and executors; cancellers are the same multisig group. The delay is locked at 7 days.
flowchart TD
Start(["Governance Proposal"]) --> Propose["Proposer submits to TimelockController"]
Propose --> Delay["7-day delay"]
Delay --> Execute{"Execute?"}
Execute --> |Yes| Apply["Apply changes to contracts"]
Execute --> |No| Cancel["Canceller vetoes"]
Apply --> End(["Protocol Updated"])
Cancel --> End
Diagram sources
- tokenomics.md:133-146
- README.md:348-358
Section sources
- docs/tokenomics.md:133-146
- README.md:348-358
- Adjustable parameters (tunable later):
- Minimum stake (USD target ~$10)
- Query fee (USD target ~$0.001)
- Burn activation threshold
- Oracle operator bond amount
- Fee routing splits (Stage 2/3)
- Locked parameters (now vs. later):
- Total supply (1B), distribution percentages, vesting schedules, LP lock mechanism, timelock delay (7 days mainnet)
flowchart TD
P["Parameter Change Request"] --> Review["Review on-chain triggers"]
Review --> Vote["Governance vote"]
Vote --> Enact["Enact via TimelockController"]
Enact --> Apply["Apply via admin-only setters"]
Apply --> Monitor["Monitor impact"]
Diagram sources
- docs/tokenomics.md:149-162
- src/CountersigStaking.sol:299-307
Section sources
- docs/tokenomics.md:149-162
- src/CountersigStaking.sol:299-307
- All contracts are upgradeable via UUPS proxies with OpenZeppelin v5.
- Upgrade authorization is restricted to UPGRADER_ROLE holders (typically the TimelockController).
- Backward compatibility considerations:
- Roles and storage layout are preserved across upgrades.
- The slash initiation/dispute interface is isolated to allow replacing on-chain arbitration without changing storage.
- Migration procedures:
- Deploy new implementation behind a proxy.
- Initialize with current parameters and roles.
- Transfer ownership to TimelockController.
sequenceDiagram
participant Dev as "Developer"
participant Impl as "New Implementation"
participant Proxy as "UUPS Proxy"
participant TL as "TimelockController"
Dev->>Impl : implement changes
TL->>Proxy : upgradeTo(Impl)
TL->>Proxy : initialize(...)
TL-->>Dev : upgrades complete
Diagram sources
- README.md:63
- CountersigIdentity.sol:224-225
- CountersigReputation.sol:179-179
- CountersigStaking.sol:329-329
Section sources
- README.md:63
- src/CountersigIdentity.sol:224-225
- src/CountersigReputation.sol:179-179
- src/CountersigStaking.sol:329-329
- $CSIG is a work token, not a governance token. It is mintable on testnet and non-mintable on mainnet.
- Token utility: Identity staking and optional oracle epoch prioritization (mainnet).
- Fee mechanics: Fees denominated in USD and settled in $CSIG at oracle-reported spot price; adjustable via admin-only setters.
- Fee routing: Three-stage model (bootstrap, transition, mature) governed by on-chain triggers and governance votes.
- Slashing burn: Categorically separate from fee burn; 50% of slashed stake is burned to address(0xdead).
flowchart TD
Start(["Fee Receipt"]) --> Stage{"Stage"}
Stage --> |1| Validators["100% to validators"]
Stage --> |2| Split["80% validators / 20% burned"]
Stage --> |3| Burn["50% validators / 50% burned"]
Validators --> End(["Protocol Evolution"])
Split --> End
Burn --> End
Diagram sources
- docs/tokenomics.md:77-97
- docs/tokenomics.md:100-112
Section sources
- docs/tokenomics.md:8-12
- docs/tokenomics.md:49-74
- docs/tokenomics.md:77-112
- Emergency pause: The challenge period in the slash lifecycle acts as a pause window for malicious slash attempts.
- Emergency upgrades: Through TimelockController, with a 7-day delay to allow observation and response.
- Protocol evolution planning: Three-phase roadmap with testnet, oracle network, mainnet, and cross-chain mirroring.
stateDiagram-v2
[*] --> Active
Active --> Suspended : "operator or StakingCore"
Suspended --> Active : "operator or StakingCore"
Active --> Slashed : "StakingCore"
Suspended --> Slashed : "StakingCore"
Slashed --> [*]
Diagram sources
- README.md:106-121
- src/CountersigIdentity.sol:33-41
Section sources
- README.md:106-121
- src/CountersigIdentity.sol:164-179
- Transparency: All governance actions occur on-chain via TimelockController; upgrades and parameter changes are auditable.
- Reporting: Oracle network publishes health and epoch status; HTTP endpoints expose metrics and previews.
- Communication: Governance announcements and deployment artifacts are published alongside the codebase.
Section sources
- oracle/index.js:152-213
- docs/tokenomics.md:133-146
The contracts depend on each other and on roles assigned by governance:
graph TB
ID["CountersigIdentity"] --> ST["CountersigStaking"]
REP["CountersigReputation"] --> ST
ST --> ID
ST --> REP
ORA["Oracle Network"] --> REP
TL["TimelockController"] -. "roles, upgrades" .- ID
TL -. "roles, upgrades" .- REP
TL -. "roles, upgrades" .- ST
MS["3-of-5 Multisig"] -. "slash initiation (testnet)" .- ST
Diagram sources
- README.md:20-52
- src/CountersigStaking.sol:69-77
- oracle/index.js:46-113
Section sources
- src/CountersigStaking.sol:69-77
- oracle/index.js:46-113
- Off-chain oracle computes scores in batches and writes sequentially to avoid nonce collisions.
- On-chain reputation updates validate per-factor caps to prevent overflow and ensure total ≤ 100.
- Staking withdrawals enforce minimum stake constraints to preserve network security.
[No sources needed since this section provides general guidance]
Common governance-related issues and resolutions:
- Upgrade authorization failures: Ensure only UPGRADER_ROLE holders call _authorizeUpgrade.
- Slash initiation errors: Verify the agent is active, has a stake, and no pending slash exists.
- Dispute timing: Disputes must occur within the challenge period; otherwise, execution is permissionless.
- Reputation updates: Ensure each factor stays within its cap; otherwise, the transaction reverts.
Section sources
- src/CountersigStaking.sol:205-293
- src/CountersigReputation.sol:107-129
- test/CountersigStaking.t.sol:212-287
- test/CountersigReputation.t.sol:57-115
Countersig Network’s governance model combines role-based access control, UUPS upgrades, and a timelocked upgrade path to ensure secure, transparent, and evolvable protocol management. The multisig-based slash initiation on testnet transitions to on-chain arbitration on mainnet, while economic mechanisms align incentives across operators, validators, and the broader ecosystem. The reputation model and tokenomics provide robust security and utility without introducing governance tokens, with clear escalation paths for emergencies and a structured roadmap for protocol evolution.
[No sources needed since this section summarizes without analyzing specific files]
- Epoch scheduling and concurrency control
- In-memory attestation and flag tracking
- Score computation aligned with on-chain formulas
Section sources
- oracle/index.js:46-113
- oracle/scoring.js:36-47
- Identity: Deterministic DID hashing, operator-only actions, status transitions, and immutability of slashed agents.
- Reputation: Per-factor caps, total ≤ 100, and zeroing on slash.
- Staking: Deposit/withdraw flows, slash lifecycle, and distribution mechanics.
Section sources
- test/CountersigIdentity.t.sol:30-243
- test/CountersigReputation.t.sol:38-197
- test/CountersigStaking.t.sol:95-397
Start Here
Core Concepts
Smart Contracts
Oracle System
Agent SDK
Integration Guides
Economic Model
Deployment & Ops
Advanced Topics