-
Notifications
You must be signed in to change notification settings - Fork 0
Integration Guides
dev-mondoshawan edited this page Jul 1, 2026
·
1 revision
**Referenced Files in This Document**
- [counteraudit-integration.md](file://docs/counteraudit-integration.md)
- [ai-frameworks.md](file://docs/ai-frameworks.md)
- [ecosystem.md](file://docs/ecosystem.md)
- [reputation-model.md](file://docs/reputation-model.md)
- [quickstart.md](file://docs/quickstart.md)
- [index.ts](file://packages/sdk/src/index.ts)
- [types.ts](file://packages/sdk/src/types.ts)
- [agent.ts](file://packages/sdk/src/agent.ts)
- [verifier.ts](file://packages/sdk/src/verifier.ts)
- [challenge.ts](file://packages/sdk/src/challenge.ts)
- [did.ts](file://packages/sdk/src/did.ts)
- [CountersigIdentity.sol](file://src/CountersigIdentity.sol)
- [CountersigReputation.sol](file://src/CountersigReputation.sol)
- [CountersigStaking.sol](file://src/CountersigStaking.sol)
- [scoring.js](file://oracle/scoring.js)
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 provides comprehensive integration guidance for external systems and AI frameworks using the Countersig Network. It covers:
- CounterAudit integration for tamper-evident audit trails with on-chain identity and reputation enrichment
- AI framework integrations for LangChain, AutoGen, and CrewAI with implementation patterns
- Integrating Countersig identity and reputation into existing AI agent architectures
- Best practices for production deployments, monitoring, and edge-case handling
- Ecosystem benefits and use cases across different integration scenarios
The repository is organized into:
- docs: Integration guides and ecosystem documentation
- packages/sdk: TypeScript/JavaScript SDK for Countersig identity, reputation, and challenge-response
- src: Solidity contracts implementing CountersigIdentity, CountersigReputation, and CountersigStaking
- oracle: Off-chain scoring implementation used by the reputation system
- site: Static documentation site generated from docs
graph TB
subgraph "Documentation"
D1["docs/counteraudit-integration.md"]
D2["docs/ai-frameworks.md"]
D3["docs/ecosystem.md"]
D4["docs/reputation-model.md"]
D5["docs/quickstart.md"]
end
subgraph "SDK"
S1["packages/sdk/src/index.ts"]
S2["packages/sdk/src/agent.ts"]
S3["packages/sdk/src/verifier.ts"]
S4["packages/sdk/src/challenge.ts"]
S5["packages/sdk/src/did.ts"]
S6["packages/sdk/src/types.ts"]
end
subgraph "Contracts"
C1["src/CountersigIdentity.sol"]
C2["src/CountersigReputation.sol"]
C3["src/CountersigStaking.sol"]
end
subgraph "Oracle"
O1["oracle/scoring.js"]
end
D1 --> S1
D2 --> S1
D3 --> C1
D3 --> C2
D3 --> C3
D4 --> O1
S1 --> S2
S1 --> S3
S1 --> S4
S1 --> S5
S1 --> S6
S3 --> C1
S3 --> C2
S3 --> C3
Diagram sources
- index.ts:1-36
- agent.ts:1-80
- verifier.ts:1-160
- challenge.ts:1-78
- did.ts:1-29
- types.ts:1-66
- CountersigIdentity.sol:1-227
- CountersigReputation.sol:1-181
- CountersigStaking.sol:1-331
- scoring.js:1-50
Section sources
- index.ts:1-36
- types.ts:1-66
- CountersigAgent: Creates deterministic DIDs, signs challenges, and exposes public keys and hashes
- CountersigVerifier: Reads on-chain identity, reputation, and stake; verifies signatures and thresholds
- Challenge utilities: Generate, sign, verify, and parse challenge payloads
- DID utilities: Parse, format, and compute didHash deterministically
- Contracts: CountersigIdentity (DID registry), CountersigReputation (score store), CountersigStaking (slashing and stake management)
- Oracle: Computes reputation scores from on-chain signals
Key integration APIs and patterns:
- Identity generation and DID computation
- Audit ingestion with agent_did for CounterAudit enrichment
- Signature-based agent-to-agent authentication
- Threshold-based gating for trust decisions
Section sources
- agent.ts:1-80
- verifier.ts:1-160
- challenge.ts:1-78
- did.ts:1-29
- CountersigIdentity.sol:1-227
- CountersigReputation.sol:1-181
- CountersigStaking.sol:1-331
The Countersig ecosystem connects agents, on-chain identity and reputation, and tamper-evident audit trails. CounterAudit enriches each sealed packet with identity and reputation at the moment of ingest, freezing the score in time.
graph TB
A["Agent<br/>Ed25519 keypair"]
ID["CountersigIdentity<br/>DID anchoring"]
CA["CounterAudit<br/>Audit trail"]
OC["Oracle<br/>Score computation"]
REP["CountersigReputation<br/>Score store"]
A --> |"1. stake $CSIG + register"| ID
ID --> |"2. emits AgentRegistered"| OC
A --> |"3. sends actions with agent_did"| CA
CA --> |"4. reads identity + score at seal time"| REP
OC --> |"5. computes 6-factor score"| REP
REP --> |"6. score in every sealed packet"| CA
REP --> |"7. higher score → more trust → more work"| A
Diagram sources
- ecosystem.md:33-48
- CountersigIdentity.sol:107-141
- CountersigReputation.sol:100-129
- scoring.js:36-47
CounterAudit enhances audit packets with on-chain identity and reputation when an agent_did is provided. The enrichment is embedded inside the AES-GCM seal and timestamped, ensuring forensic integrity.
- Setup
- Self-hosted: configure RPC URL, contract addresses, chain ID, and optional enrichment timeout
- Managed: contact CounterAudit to enable enrichment for your organization
- API usage
- Ingest endpoint: include connector_id, agent_did, and raw_event
- Verify endpoint: retrieve sealed packet and inspect enriched fields
- Enrichment behavior
- Parallel on-chain queries for identity and reputation
- Deterministic didHash derivation
- Error handling for unsupported chains, unregistered DIDs, timeouts, and RPC errors
- Field reference
- agent_did, agent_did_hash, agent_chain_id, agent_reputation_score, agent_identity_status, agent_identity_verified, agent_enriched_at, agent_enrichment_error
sequenceDiagram
participant App as "Application"
participant CA as "CounterAudit"
participant ID as "CountersigIdentity"
participant REP as "CountersigReputation"
App->>CA : "POST /v1/audit/ingest {connector_id, agent_did, raw_event}"
CA->>CA : "parseDid(agent_did)"
CA->>CA : "computeDidHash()"
CA->>ID : "getIdentity(didHash)"
ID-->>CA : "AgentIdentity"
CA->>REP : "getTotalScore(didHash)"
REP-->>CA : "totalScore"
CA->>CA : "embed fields into packet body"
CA->>CA : "AES-GCM seal + RFC 3161 timestamp"
CA-->>App : "{packet_id, entry_hash, created_at}"
Diagram sources
- counteraudit-integration.md:11-17
- CountersigIdentity.sol:195-202
- CountersigReputation.sol:152-173
Section sources
- counteraudit-integration.md:23-54
- counteraudit-integration.md:57-121
- counteraudit-integration.md:124-173
- counteraudit-integration.md:176-229
Pattern: generate DID at startup, sign challenges for authentication, include agent_did in every audit call.
- LangChain (Python)
- Wrap tools to audit each call with agent_did
- Gate agent execution using meetsThreshold
- AutoGen (Python)
- Extend AssistantAgent to audit replies
- CrewAI (Python)
- Audit task results via callbacks
- TypeScript/Node.js
- Middleware pattern to wrap async actions
- Challenge-response for agent-to-agent authentication
flowchart TD
Start(["Agent Action"]) --> CheckRep["Check meetsThreshold(did, minScore)"]
CheckRep --> |Pass| Audit["POST /v1/audit/ingest {agent_did, raw_event}"]
CheckRep --> |Fail| Deny["Reject Action"]
Audit --> FireForget["Fire-and-forget audit"]
FireForget --> Continue["Continue with action"]
Deny --> End(["End"])
Continue --> End
Diagram sources
- ai-frameworks.md:60-73
- ai-frameworks.md:171-216
Section sources
- ai-frameworks.md:7-74
- ai-frameworks.md:77-122
- ai-frameworks.md:125-167
- ai-frameworks.md:171-261
- Identity at startup
- Create CountersigAgent from stored Ed25519 seed
- DID is deterministic from seed, agent address, and chainId
- Audit on action
- Include agent_did in every ingest call
- Consider fire-and-forget to avoid blocking critical path
- Verify before trust
- verifySignature(did, payload, signature)
- meetsThreshold(did, minScore)
- Both are read-only view calls
classDiagram
class CountersigAgent {
+agentAddress string
+did string
+didHash string
+publicKeyBytes32 string
+issueChallenge(peerDid, ttl) Challenge
+signChallenge(payload) string
}
class CountersigVerifier {
+getIdentity(did) AgentIdentity
+isActive(did) boolean
+getReputation(did) ReputationData
+meetsThreshold(did, threshold) boolean
+getStake(did) bigint
+hasMinimumStake(did) boolean
+verifySignature(did, payload, signature) boolean
+buildDidDocument(did) DidDocument
}
CountersigAgent --> CountersigVerifier : "used by peers"
Diagram sources
- agent.ts:7-79
- verifier.ts:15-133
Section sources
- ai-frameworks.md:252-261
- quickstart.md:104-122
- verifier.ts:50-107
- CountersigIdentity
- Registers agents and stores operator, agent address, Ed25519 public key, status, and registration timestamp
- Computes didHash deterministically
- CountersigReputation
- Stores 6-factor scores and exposes getTotalScore and meetsThreshold
- CountersigStaking
- Manages $CSIG stake, slash initiation and execution, and distributes penalties
erDiagram
AGENT {
address operator
address agentAddress
bytes32 ed25519PubKey
enum status
uint256 registeredAt
}
REPUTATION {
uint8 feeScore
uint8 successScore
uint8 ageScore
uint8 externalScore
uint8 communityScore
uint8 propagationScore
uint256 lastUpdated
}
STAKE {
uint256 amount
uint256 lockedAt
}
COUNTERSIG_IDENTITY ||--o{ AGENT : "stores"
COUNTERSIG_REPUTATION ||--o{ REPUTATION : "stores"
COUNTERSIG_STAKING ||--o{ STAKE : "manages"
Diagram sources
- CountersigIdentity.sol:35-41
- CountersigReputation.sol:42-50
- CountersigStaking.sol:51-54
Section sources
- CountersigIdentity.sol:107-202
- CountersigReputation.sol:100-173
- CountersigStaking.sol:148-293
- Six factors: Fee Activity, Success Rate, Registration Age, External Trust, Community, Trust Propagation
- Oracle computes scores and writes to CountersigReputation
- New agent ramp-up and slashing reset behavior
flowchart TD
A["AgentRegistered event"] --> B["Collect on-chain signals"]
B --> C["Compute factors (feeScore, successScore, ageScore, communityScore)"]
C --> D["Set externalScore, propagationScore (Phase 2)"]
D --> E["Write to CountersigReputation"]
E --> F["getTotalScore(didHash) available to all"]
Diagram sources
- reputation-model.md:8-83
- scoring.js:36-47
Section sources
- reputation-model.md:1-156
- scoring.js:1-50
- SDK exports
- CountersigAgent, CountersigVerifier, challenge utilities, DID utilities, keys utilities, and types
- SDK-to-contracts
- CountersigVerifier interacts with CountersigIdentity, CountersigReputation, and CountersigStaking via RPC
- CounterAudit-to-contracts
- CounterAudit queries identity and reputation at ingest time for enrichment
graph LR
IDX["packages/sdk/src/index.ts"]
AG["agent.ts"]
VF["verifier.ts"]
CH["challenge.ts"]
DI["did.ts"]
TY["types.ts"]
CID["CountersigIdentity.sol"]
CRP["CountersigReputation.sol"]
CST["CountersigStaking.sol"]
IDX --> AG
IDX --> VF
IDX --> CH
IDX --> DI
IDX --> TY
VF --> CID
VF --> CRP
VF --> CST
Diagram sources
- index.ts:1-36
- verifier.ts:26-36
- CountersigIdentity.sol:1-227
- CountersigReputation.sol:1-181
- CountersigStaking.sol:1-331
Section sources
- index.ts:1-36
- verifier.ts:1-160
- Audit calls can be fire-and-forget to avoid blocking critical paths
- Threshold checks and signature verification are read-only view calls with minimal latency
- CounterAudit enrichment is parallelized and bounded by a configurable timeout
- Use caching judiciously for repeated verification results within short windows
- Monitor RPC latency and throughput; configure appropriate timeouts for production
[No sources needed since this section provides general guidance]
Common issues and resolutions:
- DID parsing failures
- Ensure agent_did follows the did:countersig:: format
- Unsupported chain ID
- Configure supported chain ID in CounterAudit environment
- Unregistered DID
- Verify agent registration on-chain and that didHash matches computed value
- RPC timeouts
- Increase COUNTERSIG_ENRICH_TIMEOUT_MS or improve RPC reliability
- Signature verification failures
- Confirm public key retrieval from on-chain identity and correct challenge payload format
- Threshold not met
- Improve agent performance and reputation to reach required score
Section sources
- counteraudit-integration.md:162-173
- verifier.ts:100-107
Countersig enables verifiable, tamper-evident AI agent operations by anchoring identity on-chain, scoring reputation off-chain, and embedding verified attributes into audit trails. Integrations with CounterAudit and AI frameworks provide robust trust mechanisms suitable for production-grade systems.
[No sources needed since this section summarizes without analyzing specific files]
- Secure seed storage and rotation procedures
- Use meetsThreshold for pre-execution gating
- Implement retry and circuit breaker patterns for audit endpoints
- Monitor reputation trends and slash events
- Keep SDK and contract versions aligned
[No sources needed since this section provides general guidance]
- Track ingest success rates and enrichment errors
- Observe reputation score changes and threshold crossings
- Monitor signature verification success and DID resolution latencies
- Alert on unsupported chain IDs and RPC failures
[No sources needed since this section provides general guidance]
Start Here
Core Concepts
Smart Contracts
Oracle System
Agent SDK
Integration Guides
Economic Model
Deployment & Ops
Advanced Topics