Integration Guides CounterAudit Integration

CounterAudit Integration

**Referenced Files in This Document** - [docs/counteraudit-integration.md](file://docs/counteraudit-integration.md) - [README.md](file://README.md) - [packages/sdk/src/index.ts](file://packages/sdk/src/index.ts) - [packages/sdk/src/types.ts](file://packages/sdk/src/types.ts) - [packages/sdk/src/verifier.ts](file://packages/sdk/src/verifier.ts) - [packages/sdk/src/agent.ts](file://packages/sdk/src/agent.ts) - [packages/sdk/src/did.ts](file://packages/sdk/src/did.ts) - [packages/sdk/src/challenge.ts](file://packages/sdk/src/challenge.ts) - [packages/sdk/src/abis.ts](file://packages/sdk/src/abis.ts) - [src/CountersigIdentity.sol](file://src/CountersigIdentity.sol) - [src/CountersigReputation.sol](file://src/CountersigReputation.sol) - [oracle/index.js](file://oracle/index.js) - [oracle/scoring.js](file://oracle/scoring.js) - [packages/sdk/test/integration.test.ts](file://packages/sdk/test/integration.test.ts) - [site/countersig_network_v2/countersig_v2/docs/counteraudit.html](file://site/countersig_network_v2/countersig_v2/docs/counteraudit.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 provides enterprise-grade integration guidance for embedding Countersig identity and reputation into CounterAudit sealed audit packets. It documents the API endpoints, request/response formats, authentication requirements, and operational steps to capture agent actions, generate tamper-evident audit trails, and maintain compliance records. It also maps Countersig data structures to CounterAudit’s enriched schema, outlines best practices for production deployments, and addresses common integration challenges.

Project Structure

The repository is organized into:

• Protocol contracts implementing identity, reputation, and staking on-chain
• A TypeScript SDK for agent operations, verification, and DID utilities
• An oracle service that computes and writes reputation scores
• Documentation and website assets for integration guidance

graph TB
subgraph "Documentation"
CA_DOC["docs/counteraudit-integration.md"]
SITE["site/.../docs/counteraudit.html"]
end
subgraph "Contracts"
ID["CountersigIdentity.sol"]
REP["CountersigReputation.sol"]
end
subgraph "SDK"
IDX["index.ts"]
AG["agent.ts"]
VF["verifier.ts"]
DIDU["did.ts"]
CH["challenge.ts"]
ABI["abis.ts"]
TYP["types.ts"]
end
subgraph "Oracle"
OIDX["oracle/index.js"]
OSC["oracle/scoring.js"]
end
CA_DOC --> ID
CA_DOC --> REP
SITE --> IDX
IDX --> AG
IDX --> VF
IDX --> DIDU
IDX --> CH
IDX --> TYP
VF --> ABI
OIDX --> OSC

Loading

Diagram sources

• docs/counteraudit-integration.md:1-229
• site/countersig_network_v2/countersig_v2/docs/counteraudit.html:1-163
• src/CountersigIdentity.sol:1-227
• src/CountersigReputation.sol:1-181
• packages/sdk/src/index.ts:1-36
• packages/sdk/src/agent.ts:1-80
• packages/sdk/src/verifier.ts:1-160
• packages/sdk/src/did.ts:1-29
• packages/sdk/src/challenge.ts:1-78
• packages/sdk/src/abis.ts:1-25
• oracle/index.js:1-178
• oracle/scoring.js:1-50

Section sources

• README.md:1-415
• docs/counteraudit-integration.md:1-229

Core Components

• CounterAudit ingest endpoint with optional agent_did enrichment
• Countersig contracts for identity anchoring and reputation storage
• SDK for agent lifecycle, DID parsing/computation, and verification
• Oracle service for periodic reputation computation and updates

Key integration artifacts:

• Ingest API: POST /v1/audit/ingest with Authorization header and JSON body
• Enrichment: agent_did inclusion triggers on-chain identity and reputation lookup
• Verification API: GET /v1/audit/verify/{packet_id} to decrypt and inspect sealed packet

Section sources

• docs/counteraudit-integration.md:57-121
• docs/counteraudit-integration.md:124-145
• README.md:361-389

Architecture Overview

The integration relies on CounterAudit enriching audit packets with Countersig identity and reputation at ingest time. The process is deterministic and tamper-evident, leveraging on-chain didHash derivation and sealed packet integrity.

sequenceDiagram
participant App as "Your Application"
participant CA as "CounterAudit API"
participant ID as "CountersigIdentity"
participant REP as "CountersigReputation"
App->>CA : "POST /v1/audit/ingest"<br/>Body includes "connector_id", "agent_did", "raw_event"
CA->>CA : Parse "agent_did" and compute "agent_did_hash"
par Parallel Queries
CA->>ID : "getIdentity(didHash)"
CA->>REP : "getTotalScore(didHash)"
end
ID-->>CA : "AgentIdentity"
REP-->>CA : "Total Score"
CA->>CA : Embed fields into packet body<br/>Apply AES-GCM seal + RFC 3161 timestamp
CA-->>App : "{ packet_id, entry_hash, created_at }"

Loading

Diagram sources

• docs/counteraudit-integration.md:9-18
• src/CountersigIdentity.sol:195-202
• src/CountersigReputation.sol:152-173

Detailed Component Analysis

API Endpoints and Authentication

• Endpoint: POST /v1/audit/ingest

  • Headers: Authorization: Bearer {CA_API_KEY}, Content-Type: application/json
  • Body fields:
    • connector_id: string
    • agent_did: string (optional; when present, triggers enrichment)
    • raw_event: object (arbitrary action payload)
  • Response: { packet_id, entry_hash, created_at }

• Endpoint: GET /v1/audit/verify/{packet_id}

  • Headers: Authorization: Bearer {CA_API_KEY}
  • Response: { packet: { /* decrypted sealed packet */ } }

Enriched packet fields (when agent_did is provided):

• agent_did: string
• agent_did_hash: hex string
• agent_chain_id: number
• agent_reputation_score: 0–100
• agent_identity_status: "Active" | "Suspended" | "Slashed"
• agent_identity_verified: boolean
• agent_enriched_at: ISO 8601 timestamp
• agent_enrichment_error: string (on failure only)

Section sources

• docs/counteraudit-integration.md:57-78
• docs/counteraudit-integration.md:124-145
• docs/counteraudit-integration.md:149-172

Enrichment Workflow Details

• DID parsing and didHash derivation
• Parallel on-chain queries for identity and reputation
• Deterministic didHash ensures third-party verification
• Enrichment is included in the sealed packet body and covered by AES-GCM and RFC 3161

flowchart TD
Start(["Ingest Request"]) --> CheckDID["Parse agent_did"]
CheckDID --> ValidDID{"Valid did:countersig?<br/>Format and chainId"}
ValidDID --> |No| SkipEnrich["Skip enrichment"]
ValidDID --> |Yes| ComputeHash["Compute didHash"]
ComputeHash --> QueryID["Query CountersigIdentity.getIdentity(didHash)"]
ComputeHash --> QueryRep["Query CountersigReputation.getTotalScore(didHash)"]
QueryID --> Merge["Merge identity + score into packet body"]
QueryRep --> Merge
Merge --> Seal["AES-GCM seal + RFC 3161 timestamp"]
SkipEnrich --> Seal
Seal --> End(["Return packet_id"])

Loading

Diagram sources

• docs/counteraudit-integration.md:9-18
• src/CountersigIdentity.sol:191-193
• src/CountersigReputation.sol:157-169

SDK Integration Patterns

• Generate agent identity and keys
• Build DID and didHash deterministically
• Verify signatures and build DID Documents
• Threshold checks using on-chain reputation

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
+verifySignature(did, payload, signature) boolean
+buildDidDocument(did) DidDocument
}
class DidUtils {
+parseDid(did) ParsedDid
+formatDid(agentAddress, chainId) string
+computeDidHash(agentAddress, chainId) string
}
CountersigAgent --> DidUtils : "uses"
CountersigVerifier --> DidUtils : "uses"
CountersigVerifier --> VerifierConfig : "configured"

Loading

Diagram sources

• packages/sdk/src/agent.ts:1-80
• packages/sdk/src/verifier.ts:1-160
• packages/sdk/src/did.ts:1-29
• packages/sdk/src/types.ts:1-66

Section sources

• packages/sdk/src/agent.ts:1-80
• packages/sdk/src/verifier.ts:1-160
• packages/sdk/src/did.ts:1-29
• packages/sdk/src/types.ts:1-66

Oracle and Reputation Computation

• Oracle periodically computes scores for registered agents
• Writes reputation updates on-chain via updateReputation
• Supports preview endpoint for score computation without writing

sequenceDiagram
participant OR as "Oracle"
participant CH as "Chain Reader"
participant REP as "CountersigReputation"
OR->>CH : "getRegisteredAgents()"
OR->>CH : "getAgentInfo(didHash)"
OR->>OR : "computeScore(...) from attestations + flags"
OR->>REP : "updateReputation(didHash, scores)"
REP-->>OR : "ReputationUpdated"

Loading

Diagram sources

• oracle/index.js:41-76
• oracle/scoring.js:36-47
• src/CountersigReputation.sol:107-129

Section sources

• oracle/index.js:1-178
• oracle/scoring.js:1-50
• src/CountersigReputation.sol:1-181

Implementation Examples

• Minimal ingest with agent_did

  • Add agent_did alongside existing fields
  • Use Authorization: Bearer {CA_API_KEY}

• TypeScript example

  • Construct agent DID and didHash deterministically
  • Call ingest endpoint and capture packet_id

• Python example

  • Send POST with JSON body and Authorization header
  • Raise on HTTP errors and parse response

• Verification

  • Call verify endpoint with packet_id
  • Inspect decrypted packet for enriched fields

Section sources

• docs/counteraudit-integration.md:59-78
• docs/counteraudit-integration.md:79-121
• site/countersig_network_v2/countersig_v2/docs/counteraudit.html:65-96
• site/countersig_network_v2/countersig_v2/docs/counteraudit.html:122-137

Field Reference: Countersig to CounterAudit Schema

• agent_did: string — The W3C DID
• agent_did_hash: hex string — On-chain index key
• agent_chain_id: number — EVM chain ID
• agent_reputation_score: 0–100 — Total score at seal time
• agent_identity_status: "Active" | "Suspended" | "Slashed"
• agent_identity_verified: boolean — true if registered and Active
• agent_enriched_at: ISO 8601 — When enrichment query ran
• agent_enrichment_error: string — On failure only

Error values for agent_enrichment_error:

• invalid_did_format
• unsupported_chain:
• not_registered
• rpc_timeout
• rpc_error

Section sources

• docs/counteraudit-integration.md:149-172

Dependency Analysis

• CounterAudit depends on Countersig contracts for identity and reputation
• SDK provides deterministic didHash derivation and verification utilities
• Oracle supplies reputation data consumed by CounterAudit during enrichment
• Website documentation mirrors the integration guide

graph TB
CA["CounterAudit"] --> ID["CountersigIdentity"]
CA --> REP["CountersigReputation"]
SDK["SDK"] --> ID
SDK --> REP
ORA["Oracle"] --> REP
DOC["Integration Docs"] --> CA
DOC --> SDK

Loading

Diagram sources

• docs/counteraudit-integration.md:9-18
• src/CountersigIdentity.sol:1-227
• src/CountersigReputation.sol:1-181
• oracle/index.js:1-178
• packages/sdk/src/index.ts:1-36

Section sources

• README.md:361-389
• docs/counteraudit-integration.md:1-229

Performance Considerations

• Enrichment runs in parallel for identity and reputation queries
• didHash derivation is deterministic and CPU-light
• Use timeouts appropriate to your RPC latency and CounterAudit’s COUNTERSIG_ENRICH_TIMEOUT_MS
• Batch ingest calls where feasible and monitor packet_id throughput
• Consider caching verified didHash values locally to avoid repeated recomputation

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

• Invalid agent_did format
  • Ensure did:countersig:: format
• Unsupported chain ID
  • Verify chainId matches configured environment
• Not registered
  • Confirm agent is registered on Countersig before ingest
• RPC timeout
  • Increase COUNTERSIG_ENRICH_TIMEOUT_MS or improve RPC reliability
• RPC error
  • Retry with backoff and validate RPC endpoints

Behavior:

• On any enrichment failure, agent_identity_verified is false
• Packet still seals normally; enrichment is non-blocking

Section sources

• docs/counteraudit-integration.md:162-172

Conclusion

By adding agent_did to CounterAudit ingest calls, organizations gain tamper-evident audit trails that embed verified Countersig identity and reputation at the time of action. The deterministic didHash and sealed packet integrity ensure legal defensibility and long-term compliance. The SDK and oracle infrastructure provide robust primitives for agent lifecycle, verification, and reputation management.

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

Appendices

Best Practices for Production Deployments

• Provision CA_API_KEY securely and rotate regularly
• Configure CounterAudit with COUNTERSIG_* environment variables for self-hosted deployments
• Monitor ingest latency and enrichment errors; alert on rpc_timeout and rpc_error
• Gate critical actions using meetsThreshold before auditing
• Verify didHash independently using deterministic derivation

Section sources

• docs/counteraudit-integration.md:23-54
• docs/counteraudit-integration.md:199-218

Compliance and Forensic Properties

• Reputation is frozen at seal time; subsequent changes do not alter historical records
• Enrichment is inside the AES-GCM seal and RFC 3161 timestamped
• Third parties can verify didHash deterministically without querying contracts

Section sources

• docs/counteraudit-integration.md:176-196

Integration Test References

• Integration tests demonstrate DID document building, signature verification, and threshold checks against live deployments

Section sources

• packages/sdk/test/integration.test.ts:1-121