-
Notifications
You must be signed in to change notification settings - Fork 0
Project Overview
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
Countersig Network is an on-chain identity, reputation, and staking solution designed specifically for autonomous AI agents operating as independent economic actors. The project addresses a fundamental structural gap in AI agent ecosystems: the lack of verifiable Non-Human Identity (NHI). Without trustworthy identity mechanisms, AI agents can impersonate peers, game reputation systems, and act without accountability.
The protocol establishes a three-layer architecture that anchors W3C Decentralized Identifiers on-chain while leveraging Ed25519 PKI authentication for off-chain verification. This creates a robust trust infrastructure where AI agents can establish verifiable identities, demonstrate reputation through staked cryptoeconomics, and engage in secure agent-to-agent interactions.
The protocol operates as an open identity layer for AI agent trust infrastructure, enabling any system that needs to know "which" AI agent did "what" to integrate seamlessly. This includes enterprise audit trails, AI framework integrations, and cross-chain interoperability scenarios.
The Countersig Network codebase follows a modular architecture organized around three primary smart contracts and supporting infrastructure:
graph TB
subgraph "Smart Contracts"
ID[CountersigIdentity.sol<br/>DID anchoring + public key storage]
REP[CountersigReputation.sol<br/>6-factor score store]
ST[CountersigStaking.sol<br/>$CSIG bond management]
TK[CSIGToken.sol<br/>$CSIG testnet token]
end
subgraph "Client SDK"
AG[agent.ts<br/>Ed25519 keypair generation]
VF[verifier.ts<br/>Chain interactions + DID resolution]
DID[did.ts<br/>DID parsing + didHash computation]
CH[challenge.ts<br/>Challenge-response protocol]
end
subgraph "Deployment"
DP[Deploy.s.sol<br/>UUPS proxy deployment]
end
subgraph "Documentation"
EC[ecosystem.md<br/>Protocol overview]
QS[quickstart.md<br/>Developer onboarding]
end
AG --> VF
VF --> ID
VF --> REP
VF --> ST
DP --> ID
DP --> REP
DP --> ST
DP --> TK
Diagram sources
- CountersigIdentity.sol:1-227
- CountersigReputation.sol:1-181
- CountersigStaking.sol:1-331
- CSIGToken.sol:1-27
Section sources
- README.md:1-415
- ecosystem.md:1-129
Countersig implements a sophisticated three-layer architecture that separates concerns between off-chain verification, decentralized identity, and on-chain state:
Off-Chain Verification Layer: Implements Ed25519 PKI challenge-response authentication for agent-to-agent trust verification. This layer handles cryptographic proof generation and verification without requiring on-chain computation.
Decentralized Identity Layer: Provides W3C-compliant DID resolution through the did:countersig method. The identity layer ensures global uniqueness and verifiability of agent identities across chains and networks.
On-Chain State Layer: Maintains immutable state for identities, reputation scores, and staking bonds. This layer provides the authoritative source of truth for agent status and reputation.
The protocol leverages W3C Decentralized Identifiers with Ed25519 PKI authentication to create verifiable agent identities:
-
DID Format:
did:countersig:<chainId>:<agentAddress> - Public Key Storage: Ed25519 public keys (32 bytes) are stored on-chain for authentication
-
Deterministic Hashing:
didHashis computed trustlessly using keccak256 hashing - W3C Compliance: Full DID Document support with Ed25519VerificationKey2020
Countersig operates as an open identity layer that enables seamless integration across the AI agent ecosystem:
- CounterAudit Integration: Embeds agent identity and reputation into tamper-evident audit trails
- Oracle Network: Decentralized reputation aggregation and scoring
- Cross-Chain Expansion: Designed for multi-chain deployment and state mirroring
- Framework Integration: Compatible with major AI frameworks (LangChain, AutoGen, CrewAI)
Section sources
- README.md:20-51
- README.md:67-102
- README.md:361-388
The Countersig Network architecture follows a distributed trust model with clear separation of responsibilities:
graph TB
subgraph "Off-Chain Layer"
A1[Agent Node A<br/>Ed25519 Keys]
A2[Agent Node B<br/>Ed25519 Keys]
OR[Oracle Network<br/>24h Epoch Aggregation]
end
subgraph "Identity Layer"
DR[DID Resolver<br/>did:countersig Method]
DD[DID Document<br/>W3C Compliant]
end
subgraph "On-Chain Layer"
CI[CountersigIdentity<br/>DID anchoring + status]
CR[CountersigReputation<br/>6-factor scores]
CS[CountersigStaking<br/>$CSIG bonds + slashing]
CT[CSIGToken<br/>Testnet token]
end
A1 --> |"Challenge Response"| A2
A2 --> |"Resolve DID"| DR
DR --> |"Public key + status"| CI
OR --> |"Update scores"| CR
CS --> |"Slash enforcement"| CI
CS --> |"Zero reputation"| CR
CT --> |"Staking collateral"| CS
Diagram sources
- README.md:22-51
- CountersigIdentity.sol:8-18
- CountersigReputation.sol:8-24
- CountersigStaking.sol:14-27
The architecture ensures that cryptographic proofs are generated off-chain while maintaining on-chain anchoring for verifiability. The three contracts work in concert to provide a complete trust infrastructure.
Section sources
- README.md:20-51
- ecosystem.md:33-48
CountersigIdentity serves as the foundation of the identity layer, anchoring agent identities on-chain with deterministic DID hashing:
classDiagram
class CountersigIdentity {
+bytes32 STAKING_CORE_ROLE
+bytes32 UPGRADER_ROLE
+AgentStatus status
+mapping(bytes32 => AgentIdentity) identities
+mapping(address => bytes32[]) operatorAgents
+registerAgent(agentAddress, ed25519PubKey) bytes32
+updateStatus(didHash, status) void
+rotatePublicKey(didHash, newKey) void
+computeDidHash(agentAddress) bytes32
+getIdentity(didHash) AgentIdentity
+isActive(didHash) bool
}
class AgentIdentity {
+address operator
+address agentAddress
+bytes32 ed25519PubKey
+AgentStatus status
+uint256 registeredAt
}
class AgentStatus {
<<enumeration>>
Active
Suspended
Slashed
}
CountersigIdentity --> AgentIdentity : "stores"
AgentIdentity --> AgentStatus : "uses"
Diagram sources
- CountersigIdentity.sol:18-41
The identity contract implements a state machine with three distinct states:
- Active: Fully operational with authentication capabilities
- Suspended: Temporary suspension for key rotation or investigation
- Slashed: Permanent termination with immutable status
Section sources
- CountersigIdentity.sol:1-227
- README.md:106-126
CountersigReputation maintains the 6-factor reputation scoring system that quantifies agent trustworthiness:
classDiagram
class CountersigReputation {
+bytes32 ORACLE_ROLE
+bytes32 STAKING_CORE_ROLE
+bytes32 UPGRADER_ROLE
+mapping(bytes32 => ReputationData) reputations
+updateReputation(didHash, data) void
+zeroReputation(didHash) void
+getReputation(didHash) ReputationData
+getTotalScore(didHash) uint8
+meetsThreshold(didHash, threshold) bool
}
class ReputationData {
+uint8 feeScore
+uint8 successScore
+uint8 ageScore
+uint8 externalScore
+uint8 communityScore
+uint8 propagationScore
+uint256 lastUpdated
}
CountersigReputation --> ReputationData : "stores"
Diagram sources
- CountersigReputation.sol:24-56
The reputation system employs six factors with predetermined weightings:
- Fee Activity (30 points): Transaction volume and economic activity
- Success Rate (25 points): Task completion and reliability metrics
- Age (20 points): Registration duration with logarithmic growth
- External Trust (15 points): Third-party validation scores
- Community (5 points): Flag-free standing
- Propagation (5 points): Network effect trust
Section sources
- CountersigReputation.sol:1-181
- README.md:129-144
CountersigStaking manages the staked cryptoeconomic model that incentivizes honest agent behavior:
stateDiagram-v2
[*] --> Active : depositStake()
Active --> Suspended : initiateSlash()
Suspended --> Active : disputeSlash()
Suspended --> Slashed : executeSlash()
Active --> Slashed : executeSlash()
Slashed --> [*] : terminal
note right of Suspended
7-day challenge period
Operator can dispute
end note
note right of Slashed
Permanently terminated
No key rotation
Stake distributed
end note
Diagram sources
- README.md:108-120
The staking contract implements a sophisticated slashing mechanism:
- 3-of-5 Multisig Committee (testnet): Initiates slash proposals
- 7-Day Challenge Window: Allows operators to dispute accusations
- Permissionless Execution: Anyone can execute slashes after the window
- Distribution Model: 50% burn, 25% victim, 25% reporter
Section sources
- CountersigStaking.sol:1-331
- README.md:147-187
All core contracts implement the UUPS (Universal Upgradeable Proxy Standard) pattern with OpenZeppelin v5:
sequenceDiagram
participant Admin as Governance Timelock
participant Proxy as UUPS Proxy
participant Impl as Implementation
Admin->>Proxy : upgradeTo(newImpl)
Proxy->>Impl : _authorizeUpgrade()
Impl-->>Proxy : authorization accepted
Proxy->>Proxy : delegateCall(newImpl)
Proxy-->>Admin : upgrade complete
Note over Admin,Impl : Controlled by UPGRADER_ROLE
Note over Proxy : Transparent proxy pattern
Diagram sources
- CountersigIdentity.sol:225-226
- CountersigReputation.sol:179-180
- CountersigStaking.sol:329-330
Section sources
- README.md:63-63
- Deploy.s.sol:31-106
The protocol implements a comprehensive role-based access control system:
| Role | Holder | Permissions |
|---|---|---|
DEFAULT_ADMIN_ROLE |
Governance timelock | Grant/revoke all roles |
UPGRADER_ROLE |
Governance timelock | Authorize UUPS upgrades |
STAKING_CORE_ROLE |
CountersigStaking | Suspend / slash agents, zero reputation |
ORACLE_ROLE |
Oracle consensus contract | Write reputation scores |
SLASHING_COMMITTEE_ROLE |
3-of-5 multisig | Initiate slash proposals |
Section sources
- README.md:348-358
- CountersigIdentity.sol:23-27
- CountersigReputation.sol:29-36
- CountersigStaking.sol:40-43
The Countersig protocol exhibits strong modularity with clear dependency relationships:
graph TB
subgraph "External Dependencies"
OZ[OpenZeppelin Contracts v5]
NACL[tweetnacl for Ed25519]
ETHERS[ethers.js]
end
subgraph "Internal Dependencies"
ID[CountersigIdentity]
REP[CountersigReputation]
ST[CountersigStaking]
TK[CSIGToken]
end
subgraph "SDK Dependencies"
AG[CountersigAgent]
VF[CountersigVerifier]
DK[SDK Utilities]
end
OZ --> ID
OZ --> REP
OZ --> ST
NACL --> AG
ETHERS --> VF
ID --> ST
REP --> ST
TK --> ST
AG --> VF
DK --> VF
Diagram sources
- CountersigIdentity.sol:4-6
- CountersigStaking.sol:4-12
- agent.ts:1-5
- verifier.ts:1-5
The dependency structure ensures that:
- Smart contracts remain focused on their core responsibilities
- The SDK provides clean abstractions for client integration
- External dependencies are minimized and well-defined
- Upgrade paths maintain backward compatibility
Section sources
- CountersigIdentity.sol:4-6
- CountersigStaking.sol:4-12
- agent.ts:1-5
The Countersig protocol is designed with several performance optimizations:
The computeDidHash function enables trustless reproduction of DID hashes without on-chain computation, reducing gas costs and improving scalability.
Ed25519 challenge-response authentication occurs entirely off-chain, minimizing on-chain computational overhead while maintaining cryptographic security.
Each contract maintains focused state with minimal storage overhead:
- Identity: 5 storage slots per agent
- Reputation: 6 factor scores + timestamp per agent
- Staking: Stake amount + slash proposal state per agent
The SDK supports batch operations for common workflows, reducing transaction overhead for operators managing multiple agents.
Missing Environment Variables: Ensure all required environment variables are set for deployment scripts:
-
DEPLOYER_PRIVATE_KEY: Deployer wallet private key -
ORACLE_ADDRESS: Initial oracle role holder -
COMMITTEE_ADDRESS: Initial slashing committee members -
MINIMUM_STAKE: Initial minimum stake requirement -
CHALLENGE_PERIOD: Initial challenge window duration
Upgrade Authorization: Verify that the governance timelock has the UPGRADER_ROLE before attempting upgrades.
DID Resolution Failures: Confirm that the DID format matches the expected did:countersig:<chainId>:<agentAddress> pattern and that the chain ID is correct.
Challenge Verification Errors: Ensure that challenge payloads follow the COUNTERSIG-VERIFY:{DID}:{nonce}:{timestamp} format and that signatures are properly encoded in base58.
Reputation Threshold Checks: Verify that the target reputation threshold is appropriate for your use case, considering the 6-factor scoring system.
Section sources
- Deploy.s.sol:20-30
- challenge.ts:7-15
- README.md:348-358
Countersig Network represents a comprehensive solution for establishing verifiable identity, reputation, and trust in AI agent ecosystems. By combining W3C-compliant decentralized identifiers with Ed25519 PKI authentication and staked cryptoeconomics, the protocol addresses fundamental security challenges facing autonomous AI agents.
The three-layer architecture provides a robust foundation for trust establishment, while the UUPS upgradeable proxy pattern ensures long-term maintainability and evolution. The role-based access control system balances security with operational flexibility, and the comprehensive SDK enables seamless integration across diverse AI frameworks and applications.
The protocol's vision for cross-chain expansion and mainnet deployment positions it as a foundational trust infrastructure for the future of AI agent interactions. As AI agents continue to evolve into independent economic actors, Countersig provides the essential building blocks for verifiable identity, accountable behavior, and sustainable reputation systems.
Through its integration with CounterAudit and support for major AI frameworks, Countersig transforms abstract trust concepts into practical, production-ready solutions that developers can immediately deploy and operators can trust.
Start Here
Core Concepts
Smart Contracts
Oracle System
Agent SDK
Integration Guides
Economic Model
Deployment & Ops
Advanced Topics