Deployment and Operations Operational Management

Operational Management

**Referenced Files in This Document** - [README.md](file://README.md) - [foundry.toml](file://foundry.toml) - [script/Deploy.s.sol](file://script/Deploy.s.sol) - [docker-compose.oracle.yml](file://docker-compose.oracle.yml) - [oracle/Dockerfile](file://oracle/Dockerfile) - [oracle/index.js](file://oracle/index.js) - [oracle/scoring.js](file://oracle/scoring.js) - [oracle/package.json](file://oracle/package.json) - [src/CountersigReputation.sol](file://src/CountersigReputation.sol) - [src/CountersigIdentity.sol](file://src/CountersigIdentity.sol) - [src/CountersigStaking.sol](file://src/CountersigStaking.sol) - [packages/sdk/package.json](file://packages/sdk/package.json)

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. Maintenance Procedures
10. Environment Management
11. Best Practices
12. Scaling and Cost Optimization
13. Conclusion

Introduction

This document provides comprehensive operational management guidance for Countersig Network operations. It covers monitoring and alerting, health checks for oracle services, performance metrics tracking, troubleshooting common operational issues, maintenance procedures (including UUPS upgrades and parameter updates), environment management with Docker orchestration, operational security, backup procedures, incident response protocols, scaling considerations, capacity planning, and cost optimization strategies.

Project Structure

The repository organizes operational concerns across contracts, an oracle service, deployment automation, and supporting tooling:

• Contracts: Identity, Reputation, Staking, and Token
• Oracle service: Node.js-based reputation computation and on-chain updates
• Deployment: Foundry script with UUPS proxy pattern
• Tooling: Docker Compose for local oracle orchestration, SDK for integrations

graph TB
subgraph "Contracts"
ID["CountersigIdentity.sol"]
REP["CountersigReputation.sol"]
ST["CountersigStaking.sol"]
TK["CSIGToken.sol"]
end
subgraph "Oracle Service"
OCFG["docker-compose.oracle.yml"]
OD["oracle/Dockerfile"]
OIDX["oracle/index.js"]
OSC["oracle/scoring.js"]
end
subgraph "Deployment"
FTK["foundry.toml"]
DSP["script/Deploy.s.sol"]
end
subgraph "SDK"
SDKP["packages/sdk/package.json"]
end
OIDX --> ID
OIDX --> REP
OIDX --> OSC
DSP --> ID
DSP --> REP
DSP --> ST
DSP --> TK
OCFG --> OD
OCFG --> OIDX
SDKP --> ID
SDKP --> REP
SDKP --> ST

Loading

Diagram sources

• docker-compose.oracle.yml:1-11
• oracle/Dockerfile:1-11
• oracle/index.js:1-178
• oracle/scoring.js:1-50
• script/Deploy.s.sol:1-130
• foundry.toml:1-21
• src/CountersigIdentity.sol:1-227
• src/CountersigReputation.sol:1-181
• src/CountersigStaking.sol:1-331
• packages/sdk/package.json:1-34

Section sources

• README.md:1-415
• docker-compose.oracle.yml:1-11
• oracle/Dockerfile:1-11
• oracle/index.js:1-178
• oracle/scoring.js:1-50
• script/Deploy.s.sol:1-130
• foundry.toml:1-21
• src/CountersigIdentity.sol:1-227
• src/CountersigReputation.sol:1-181
• src/CountersigStaking.sol:1-331
• packages/sdk/package.json:1-34

Core Components

• CountersigIdentity: On-chain DID anchoring, Ed25519 public key storage, agent status lifecycle (Active, Suspended, Slashed).
• CountersigReputation: Oracle-written 6-factor reputation store with threshold checks and zeroing on slash.
• CountersigStaking: $CSIG stake management, slashing lifecycle, and governance parameters.
• Oracle Service: Off-chain reputation computation, epoch scheduling, HTTP API for health, manual epoch, attestations, flags, and score previews.
• Deployment and Upgrade: Foundry script deploying UUPS proxies and wiring roles; governance-controlled upgrades.

Operational highlights:

• Oracle health endpoint and manual epoch trigger enable proactive monitoring and testing.
• Reputation writes are role-gated and validated for factor caps.
• Staking enforces minimum stake and challenge periods, with slash distribution and zeroing.

Section sources

• src/CountersigIdentity.sol:18-227
• src/CountersigReputation.sol:24-181
• src/CountersigStaking.sol:28-331
• oracle/index.js:115-171
• script/Deploy.s.sol:35-106

Architecture Overview

The operational architecture centers on the oracle service periodically computing and writing reputation scores to CountersigReputation, while CountersigStaking manages agent status and slashing that can zero reputation.

sequenceDiagram
participant Ops as "Operations Team"
participant Oracle as "Oracle Service"
participant Chain as "EVM"
participant ID as "CountersigIdentity"
participant REP as "CountersigReputation"
participant ST as "CountersigStaking"
Ops->>Oracle : Trigger /epoch or monitor /health
Oracle->>Chain : Query registered agents and agent info
Oracle->>REP : updateReputation(didHash, scores) via ORACLE_ROLE
REP-->>Oracle : ReputationUpdated event
Oracle-->>Ops : Logs and HTTP responses
Note over ST,REP : Slashing lifecycle can zero reputation
ST->>ID : updateStatus(didHash, Slashed)
ST->>REP : zeroReputation(didHash)

Loading

Diagram sources

• oracle/index.js:41-76
• src/CountersigReputation.sol:107-129
• src/CountersigStaking.sol:283-293

Detailed Component Analysis

Oracle Service Operations

• Health endpoint: GET /health returns operational status and epoch interval.
• Manual epoch: POST /epoch triggers immediate computation and writes.
• Attestation ingestion: POST /attest increments success/total counts per didHash.
• Flagging: POST /flag increments unresolved flag count per didHash.
• Score preview: GET /score/:didHash computes and returns projected scores without writing.
• Authentication: Optional Bearer token protection for administrative endpoints.

sequenceDiagram
participant Client as "Client"
participant HTTP as "HTTP Server"
participant Epoch as "runEpoch()"
participant Chain as "chain module"
participant Scoring as "computeScore()"
participant REP as "CountersigReputation"
Client->>HTTP : POST /epoch
HTTP->>Epoch : runEpoch()
Epoch->>Chain : getRegisteredAgents()
Epoch->>Chain : getAgentInfo(didHash)
Epoch->>Scoring : computeScore(...)
Epoch->>REP : updateReputation(didHash, scores)
REP-->>Epoch : ReputationUpdated
Epoch-->>HTTP : success logs
HTTP-->>Client : 202 Accepted

Loading

Diagram sources

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

Section sources

• oracle/index.js:115-171
• oracle/scoring.js:1-50
• src/CountersigReputation.sol:107-129

Monitoring and Alerting

Recommended monitoring signals:

• Oracle uptime: /health endpoint availability and epoch cadence adherence.
• Transaction success rate: Gas usage and failure rates for updateReputation calls.
• Agent coverage: Number of agents processed per epoch vs total registered.
• Factor composition: Track feeScore, successScore, ageScore, communityScore trends.
• Slashing events: Monitor SlashInitiated, SlashExecuted, ReputationZeroed events.

Alerting thresholds:

• Health: Down alerts if /health fails or epoch delay exceeds 1.5× scheduled interval.
• Transaction failures: Immediate alerts for repeated revert reasons (e.g., ScoreOutOfRange).
• Coverage gaps: Alerts when updated count falls below a configured percentage of registered agents.

Section sources

• oracle/index.js:115-118
• src/CountersigReputation.sol:107-129

Health Checks for Oracle Services

• Endpoint: GET /health returns ok and epochMs.
• Local checks: Container restart policy "unless-stopped" ensures resilience.
• Manual verification: POST /epoch to validate end-to-end pipeline.

Section sources

• oracle/index.js:115-118
• docker-compose.oracle.yml:7
• oracle/index.js:120-124

Performance Metrics Tracking

• Epoch duration: Measure runEpoch() wall time and per-agent processing latency.
• Throughput: Transactions per second for updateReputation calls.
• Factor computation costs: CPU time for computeScore per didHash.
• Chain read/write costs: Gas consumption and RPC latency for getRegisteredAgents and updateReputation.

Section sources

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

Reputation Computation Logic

flowchart TD
Start(["Compute Scores"]) --> Load["Load didHash, registeredAt, attestations, flags"]
Load --> Fee["feeScore = min(30, floor(total/10))"]
Load --> Success["successScore = floor(successful/total * 25)"]
Load --> Age["ageScore = min(20, floor(log2(days+1)*4))"]
Load --> External["externalScore = 0 (Phase 2)"]
Load --> Community["communityScore = max(0, 5 - flags*2)"]
Load --> Prop["propagationScore = 0 (Phase 2)"]
Fee --> Sum["total = sum of factors"]
Success --> Sum
Age --> Sum
External --> Sum
Community --> Sum
Prop --> Sum
Sum --> End(["Return scores"])

Loading

Diagram sources

• oracle/scoring.js:36-47

Section sources

• oracle/scoring.js:1-50

Slashing Lifecycle and Impact on Reputation

sequenceDiagram
participant CM as "Slashing Committee"
participant ST as "CountersigStaking"
participant ID as "CountersigIdentity"
participant REP as "CountersigReputation"
CM->>ST : initiateSlash(didHash, victim, evidenceHash)
ST->>ID : updateStatus(didHash, Suspended)
Note over ST : Challenge period begins
alt Operator disputes within window
ST->>ID : updateStatus(didHash, Active)
ST-->>CM : Proposal cancelled
else Window expires undisputed
ST->>ID : updateStatus(didHash, Slashed)
ST->>REP : zeroReputation(didHash)
end

Loading

Diagram sources

• src/CountersigStaking.sol:205-228
• src/CountersigStaking.sol:263-293
• src/CountersigReputation.sol:135-146

Section sources

• src/CountersigStaking.sol:28-331
• src/CountersigReputation.sol:131-146

Dependency Analysis

• Oracle depends on:
  • RPC provider for chain interactions
  • CountersigIdentity and CountersigReputation addresses for on-chain writes
  • Environment variables for configuration
• Contracts depend on:
  • AccessControlUpgradeable and UUPSUpgradeable for role-based access and upgrades
  • OpenZeppelin libraries for safe transfers and reentrancy protection
• Deployment script orchestrates:
  • Implementation creation, proxy instantiation, and role assignment

graph LR
OIDX["oracle/index.js"] --> ID["CountersigIdentity.sol"]
OIDX --> REP["CountersigReputation.sol"]
OIDX --> SC["oracle/scoring.js"]
ST["CountersigStaking.sol"] --> ID
ST --> REP
DSP["script/Deploy.s.sol"] --> ID_IMPL["CountersigIdentity (impl)"]
DSP --> REP_IMPL["CountersigReputation (impl)"]
DSP --> ST_IMPL["CountersigStaking (impl)"]
DSP --> CSIG["CSIGToken.sol"]

Loading

Diagram sources

• oracle/index.js:1-28
• src/CountersigIdentity.sol:1-18
• src/CountersigReputation.sol:1-24
• src/CountersigStaking.sol:1-13
• script/Deploy.s.sol:50-81

Section sources

• oracle/index.js:1-28
• src/CountersigIdentity.sol:1-18
• src/CountersigReputation.sol:1-24
• src/CountersigStaking.sol:1-13
• script/Deploy.s.sol:50-81

Performance Considerations

• Epoch scheduling: Tune EPOCH_HOURS to balance freshness and gas costs.
• Batch processing: Increase LOG_CHUNK_SIZE cautiously to reduce RPC calls while respecting request limits.
• Factor computation: Keep computeScore pure and optimized; cache didHash lookups where appropriate.
• Chain interactions: Use efficient RPC providers and consider rate limiting; monitor gas price spikes.
• Memory footprint: In-memory maps suffice for testnet; plan persistent storage for production.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common operational issues and resolutions:

• Oracle downtime
  • Symptoms: /health unavailable, epoch not running.
  • Actions: Verify container status, check restart policy, review startup logs, confirm RPC_URL and private key configuration.
• Reputation computation failures
  • Symptoms: updateReputation reverts with ScoreOutOfRange.
  • Actions: Validate factor caps, inspect computeScore inputs, ensure didHash corresponds to registered agents.
• Network connectivity problems
  • Symptoms: getRegisteredAgents/getAgentInfo timeouts or errors.
  • Actions: Test RPC_URL reachability, verify network firewall rules, retry with fallback RPC endpoints.
• Slashing-related reputation zeroing
  • Symptoms: Reputation drops to zero unexpectedly.
  • Actions: Confirm slashing execution path, verify Slashed status in Identity, check ReputationZeroed events.

Section sources

• oracle/index.js:23-26
• src/CountersigReputation.sol:111-116
• src/CountersigStaking.sol:263-293

Maintenance Procedures

Contract Upgrades Using UUPS Pattern

• Prerequisites: Governance-controlled timelock holds UPGRADER_ROLE on all proxies.
• Process:
  • Prepare implementation with minimal breaking changes.
  • Execute upgrade via proxy using _authorizeUpgrade gating.
  • Validate roles and state remain intact post-upgrade.
• Rollback: Store previous implementation addresses and re-deploy proxies if needed.

Section sources

• src/CountersigIdentity.sol:225
• src/CountersigReputation.sol:179
• src/CountersigStaking.sol:329

Parameter Updates

• Staking parameters: minimumStake and challengePeriod managed by DEFAULT_ADMIN_ROLE.
• Oracle runtime: Adjust EPOCH_HOURS, FROM_BLOCK, LOG_CHUNK_SIZE via environment variables.
• Governance parameters: Update committee and oracle roles via deployment script and role grants.

Section sources

• src/CountersigStaking.sol:299-307
• oracle/index.js:11-21
• script/Deploy.s.sol:35-42

Emergency Procedures

• Oracle outage: Manual epoch via POST /epoch, notify stakeholders, scale to secondary nodes.
• Slashing abuse: Pause oracle writes, investigate, and coordinate with governance to adjust committee or parameters.
• Critical bug in computeScore: Hot-fix implementation, redeploy proxy, and re-run epochs for affected didHashes.

Section sources

• oracle/index.js:120-124
• src/CountersigStaking.sol:205-228

Environment Management

Development, Staging, Production Environments

• Development: Local Docker Compose for oracle service; ephemeral testnet deployments.
• Staging: Dedicated testnet chains with hardened configurations and monitoring.
• Production: Mainnet with governance-controlled upgrades, robust RPC providers, and redundant oracle nodes.

Section sources

• docker-compose.oracle.yml:1-11
• oracle/Dockerfile:1-11

Docker Orchestration for Oracle System

• Build: Node 20 Alpine image with production dependencies only.
• Runtime: Single oracle container exposing port 3030; restart unless-stopped.
• Configuration: Externalized via env_file pointing to oracle/.env.

Section sources

• oracle/Dockerfile:1-11
• docker-compose.oracle.yml:1-11

Deployment Automation

• Foundry script deploys UUPS proxies, initializes contracts, grants roles, and writes deployment artifacts.
• Environment variables drive oracle address, committee, and staking parameters.

Section sources

• script/Deploy.s.sol:35-106
• foundry.toml:1-21

Best Practices

Operational Security

• Principle of least privilege: Limit ORACLE_ROLE, SLASHING_COMMITTEE_ROLE holders, and UPGRADER_ROLE.
• Secret management: Store RPC_URL, private keys, and admin tokens in secure vaults; avoid committing secrets.
• Network segmentation: Separate staging and production RPC endpoints; restrict inbound ports.

Section sources

• src/CountersigReputation.sol:29-36
• src/CountersigStaking.sol:40-44
• oracle/index.js:105-109

Backup Procedures

• Contract state: Snapshot on-chain state at epoch boundaries; maintain historical logs.
• Oracle state: Persist in-memory attestations and flags to durable storage for fast recovery.
• Secrets: Regular rotation and encrypted backups of private keys and tokens.

Section sources

• oracle/index.js:30-38

Incident Response Protocols

• Define escalation tiers: minor issues (manual epoch), major incidents (pause writes), critical (emergency upgrade).
• Communication: Automated alerts to on-call channels; runbooks linked to each incident type.
• Post-mortem: Document root causes, remediations, and preventive measures.

Section sources

• oracle/index.js:120-124
• src/CountersigStaking.sol:205-228

Scaling and Cost Optimization

Capacity Planning

• Oracle compute: Scale CPU/memory with number of agents; pre-compute didHash sets to minimize chain reads.
• Chain throughput: Batch updateReputation calls where feasible; optimize gas prices during low-fee windows.
• Storage: Transition from in-memory maps to persistent stores (PostgreSQL/SQLite) for production.

Section sources

• oracle/index.js:30-38
• src/CountersigReputation.sol:107-129

Cost Optimization Strategies

• Gas optimization: Use efficient RPC providers, batch transactions, and reduce unnecessary reads/writes.
• Oracle runtime: Right-size EPOCH_HOURS and LOG_CHUNK_SIZE to match agent growth.
• Infrastructure: Use spot instances for staging; reserved instances for production.

Section sources

• oracle/index.js:16-21
• oracle/index.js:47-51

Conclusion

This operational guide consolidates monitoring, maintenance, and security practices for Countersig Network. By leveraging the oracle health endpoints, UUPS upgrade mechanism, and robust role-based access controls, operators can maintain reliable identity, reputation, and staking services across environments while preparing for future scaling and mainnet deployment.