Skip to content

Deployment and Operations

Jump to bottom
dev-mondoshawan edited this page Jul 1, 2026 · 1 revision

Deployment and Operations

**Referenced Files in This Document** - [README.md](file://README.md) - [foundry.toml](file://foundry.toml) - [script/Deploy.s.sol](file://script/Deploy.s.sol) - [src/CSIGToken.sol](file://src/CSIGToken.sol) - [src/CountersigIdentity.sol](file://src/CountersigIdentity.sol) - [src/CountersigReputation.sol](file://src/CountersigReputation.sol) - [src/CountersigStaking.sol](file://src/CountersigStaking.sol) - [oracle/Dockerfile](file://oracle/Dockerfile) - [docker-compose.oracle.yml](file://docker-compose.oracle.yml) - [oracle/package.json](file://oracle/package.json) - [oracle/index.js](file://oracle/index.js) - [oracle/scoring.js](file://oracle/scoring.js) - [oracle/chain.js](file://oracle/chain.js) - [deployments/11155111.json](file://deployments/11155111.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. Conclusion
  10. Appendices

Introduction

This document provides comprehensive deployment and operations guidance for Countersig Network. It covers smart contract deployment, initialization parameters, address management, upgrade procedures using the UUPS proxy pattern, governance workflows, operational management (monitoring and alerting, troubleshooting, maintenance), Docker-based deployment for the oracle system, environment setup, infrastructure requirements, best practices for production deployments, rollback procedures, and incident response protocols.

Project Structure

The repository is organized into Foundry-based smart contracts, a TypeScript SDK package, an oracle service, and documentation. Key areas for deployment and operations:

  • Smart contracts under src/ implement the identity, reputation, staking, and token components behind UUPS proxies.
  • Deployment automation is implemented in script/Deploy.s.sol using Foundry.
  • The oracle service under oracle/ computes and writes reputation scores to the chain and is containerized for easy operations.
  • Infrastructure and environment configuration are managed via docker-compose and environment files.
graph TB
subgraph "Smart Contracts"
A["CSIGToken.sol"]
B["CountersigIdentity.sol"]
C["CountersigReputation.sol"]
D["CountersigStaking.sol"]
end
subgraph "Deployment"
E["script/Deploy.s.sol"]
F["foundry.toml"]
G["deployments/11155111.json"]
end
subgraph "Oracle"
H["oracle/Dockerfile"]
I["docker-compose.oracle.yml"]
J["oracle/index.js"]
K["oracle/scoring.js"]
L["oracle/chain.js"]
end
E --> A
E --> B
E --> C
E --> D
F --> E
E --> G
I --> H
I --> J
J --> K
J --> L
Loading

Diagram sources

  • script/Deploy.s.sol:1-130
  • foundry.toml:1-21
  • deployments/11155111.json:1-1
  • oracle/Dockerfile:1-11
  • docker-compose.oracle.yml:1-11
  • oracle/index.js:1-178
  • oracle/scoring.js:1-50
  • oracle/chain.js:1-85

Section sources

  • README.md:328-345
  • foundry.toml:1-21
  • script/Deploy.s.sol:1-130
  • deployments/11155111.json:1-1
  • oracle/Dockerfile:1-11
  • docker-compose.oracle.yml:1-11
  • oracle/index.js:1-178
  • oracle/scoring.js:1-50
  • oracle/chain.js:1-85

Core Components

  • CSIGToken: Testnet ERC20 token used for staking and faucet distribution.
  • CountersigIdentity: Anchors agent identities on-chain, stores operator, Ed25519 public key, and AgentStatus. Uses UUPS upgrades.
  • CountersigReputation: Stores 6-factor reputation scores and exposes threshold checks. Uses UUPS upgrades.
  • CountersigStaking: Manages CSIG bonds, slash lifecycle, and parameterization (minimum stake, challenge period). Uses UUPS upgrades.

Initialization and roles:

  • All contracts are initialized behind UUPS proxies and grant roles to governance and operational actors.
  • Access control roles include DEFAULT_ADMIN_ROLE, UPGRADER_ROLE, STAKING_CORE_ROLE, ORACLE_ROLE, and SLASHING_COMMITTEE_ROLE.

Section sources

  • src/CSIGToken.sol:1-27
  • src/CountersigIdentity.sol:18-101
  • src/CountersigReputation.sol:24-94
  • src/CountersigStaking.sol:28-142
  • README.md:348-358

Architecture Overview

The protocol consists of three on-chain contracts coordinated by governance and operational roles, plus an off-chain oracle that periodically writes reputation scores.

graph TB
subgraph "On-Chain"
ID["CountersigIdentity"]
REP["CountersigReputation"]
ST["CountersigStaking"]
TK["CSIGToken"]
end
subgraph "Governance & Roles"
ADM["DEFAULT_ADMIN_ROLE<br/>UPGRADER_ROLE"]
SC["STAKING_CORE_ROLE"]
OR["ORACLE_ROLE"]
CM["SLASHING_COMMITTEE_ROLE"]
end
subgraph "Off-Chain"
ORA["Oracle Service"]
end
ADM --> ID
ADM --> REP
ADM --> ST
SC --> ID
SC --> REP
ORA --> REP
CM --> ST
ST --> ID
ST --> REP
ST --> TK
ORA --> REP
Loading

Diagram sources

  • src/CountersigIdentity.sol:22-27
  • src/CountersigReputation.sol:29-36
  • src/CountersigStaking.sol:40-43
  • src/CountersigStaking.sol:137-141
  • src/CountersigReputation.sol:86-94
  • src/CountersigIdentity.sol:92-101

Detailed Component Analysis

Smart Contract Deployment and Upgrade Procedures

  • Deployment script orchestrates creation of the CSIG token, implementation contracts, UUPS proxies, and role wiring. It also serializes deployed addresses to a JSON file for SDK configuration.
  • Upgrade mechanism uses UUPS proxies with UPGRADER_ROLE controlling upgrades. Contracts implement _authorizeUpgrade to restrict upgrades to the designated role.
sequenceDiagram
participant Dev as "Developer"
participant Forge as "Forge Script"
participant Impl as "Implementation Contracts"
participant Proxy as "UUPS Proxies"
participant Reg as "Address Registry"
Dev->>Forge : Run deployment script with env vars
Forge->>Impl : Deploy implementations
Forge->>Proxy : Create proxies with initialize(...)
Forge->>Proxy : Grant roles (UPGRADER_ROLE, STAKING_CORE_ROLE, ORACLE_ROLE, SLASHING_COMMITTEE_ROLE)
Forge->>Reg : Write deployments/{chainId}.json
Forge-->>Dev : Console logs addresses and parameters
Loading

Diagram sources

  • script/Deploy.s.sol:35-106
  • deployments/11155111.json:1-1

Section sources

  • script/Deploy.s.sol:12-30
  • script/Deploy.s.sol:35-106
  • src/CountersigIdentity.sol:225
  • src/CountersigReputation.sol:179
  • src/CountersigStaking.sol:329

Parameter Management and Governance Workflows

  • CountersigStaking exposes admin functions to update minimum stake and challenge period.
  • Roles are granted during deployment:
    • DEFAULT_ADMIN_ROLE and UPGRADER_ROLE to governance timelock.
    • STAKING_CORE_ROLE to CountersigStaking for identity and reputation actions.
    • ORACLE_ROLE to the oracle address for writing reputation.
    • SLASHING_COMMITTEE_ROLE to the initial committee (testnet multisig).
flowchart TD
Start(["Governance Action"]) --> ParamChange{"Parameter Change?"}
ParamChange --> |Yes| AdminOnly["onlyRole(DEFAULT_ADMIN)"]
AdminOnly --> UpdateMin["setMinimumStake(...)"]
AdminOnly --> UpdatePeriod["setChallengePeriod(...)"]
ParamChange --> |No| SlashAction{"Slash Action?"}
SlashAction --> |Yes| Committee["SLASHING_COMMITTEE_ROLE"]
Committee --> Initiate["initiateSlash(...)"]
Initiate --> Dispute["Operator dispute within window"]
Initiate --> Execute["executeSlash(...) after window"]
SlashAction --> |No| OracleWrite{"Oracle Write?"}
OracleWrite --> |Yes| OracleRole["ORACLE_ROLE"]
OracleRole --> UpdateRep["updateReputation(...)"]
OracleWrite --> |No| End(["No Action"])
UpdateMin --> End
UpdatePeriod --> End
Dispute --> End
Execute --> End
UpdateRep --> End
Loading

Diagram sources

  • src/CountersigStaking.sol:299-307
  • src/CountersigStaking.sol:205-228
  • src/CountersigStaking.sol:237-255
  • src/CountersigStaking.sol:263-293
  • src/CountersigReputation.sol:107-129

Section sources

  • src/CountersigStaking.sol:299-307
  • src/CountersigStaking.sol:205-228
  • src/CountersigStaking.sol:237-255
  • src/CountersigStaking.sol:263-293
  • src/CountersigReputation.sol:107-129
  • script/Deploy.s.sol:77-81

Oracle System Deployment and Operations

  • The oracle service is containerized and runs via docker-compose. It periodically computes scores for registered agents and writes them to CountersigReputation.
  • Environment variables configure RPC endpoint, account credentials, contract addresses, epoch cadence, and optional admin authorization.
sequenceDiagram
participant Cron as "Scheduler"
participant Oracle as "Oracle Service"
participant Chain as "EVM Chain"
participant Rep as "CountersigReputation"
Cron->>Oracle : Trigger epoch
Oracle->>Chain : Query registered agents (logs)
Oracle->>Chain : Fetch agent info (status, registeredAt)
Oracle->>Oracle : Compute scores (fee, success, age, flags)
Oracle->>Rep : updateReputation(...)
Rep-->>Oracle : Transaction receipt
Oracle-->>Cron : Log completion
Loading

Diagram sources

  • oracle/index.js:41-76
  • oracle/chain.js:36-68
  • oracle/chain.js:70-82
  • oracle/scoring.js:36-47

Section sources

  • docker-compose.oracle.yml:1-11
  • oracle/Dockerfile:1-11
  • oracle/package.json:1-19
  • oracle/index.js:11-26
  • oracle/index.js:111-171
  • oracle/chain.js:24-30

Dependency Analysis

  • Foundry configuration defines remappings for OpenZeppelin contracts and sets optimizer and fuzzing profiles.
  • Deployment script depends on OpenZeppelin UUPS proxies and imports contract ABIs for role assignment.
  • Oracle service depends on ethers.js and dotenv; it interacts with on-chain contracts via ABI bindings.
graph TB
FT["foundry.toml"]
DS["script/Deploy.s.sol"]
CI["src/CountersigIdentity.sol"]
CR["src/CountersigReputation.sol"]
CS["src/CountersigStaking.sol"]
CT["src/CSIGToken.sol"]
OD["oracle/Dockerfile"]
OJ["oracle/package.json"]
OI["oracle/index.js"]
OS["oracle/scoring.js"]
OC["oracle/chain.js"]
FT --> DS
DS --> CI
DS --> CR
DS --> CS
DS --> CT
OJ --> OI
OI --> OS
OI --> OC
OD --> OI
Loading

Diagram sources

  • foundry.toml:5-9
  • script/Deploy.s.sol:4-10
  • oracle/package.json:10-13
  • oracle/Dockerfile:1-11

Section sources

  • foundry.toml:1-21
  • script/Deploy.s.sol:4-10
  • oracle/package.json:10-13
  • oracle/Dockerfile:1-11

Performance Considerations

  • Foundry optimizer is enabled with a moderate number of runs suitable for testnet deployment.
  • Oracle epoch cadence and log chunk sizes are configurable to balance throughput and RPC cost.
  • Gas efficiency considerations apply to frequent reputation updates; batching and efficient ABI shapes are recommended.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common operational issues and resolutions:

  • Missing environment variables for oracle: Ensure RPC_URL, ORACLE_PRIVATE_KEY, IDENTITY_ADDRESS, REPUTATION_ADDRESS are set; the service logs a startup error if missing.
  • Unauthorized admin endpoints: Configure ORACLE_ADMIN_TOKEN and use Authorization: Bearer for POST /attest and POST /flag.
  • Chain scanning gaps: Adjust FROM_BLOCK and LOG_CHUNK_SIZE to handle RPC rate limits and ensure full coverage of AgentRegistered events.
  • Upgrade authorization failures: Verify UPGRADER_ROLE is granted to the governance timelock and that _authorizeUpgrade is invoked by the correct role.
  • Slash lifecycle edge cases: Confirm challenge window calculations and ensure operators dispute slashes within the allowed timeframe.

Section sources

  • oracle/index.js:23-26
  • oracle/index.js:105-109
  • oracle/chain.js:36-60
  • src/CountersigIdentity.sol:225
  • src/CountersigStaking.sol:241-244

Conclusion

Countersig Network’s deployment and operations rely on deterministic Foundry-based deployment, UUPS proxy upgrades, and a modular role-based access control model. The oracle system is containerized and configurable for testnet and early mainnet phases. Adhering to governance workflows, parameter discipline, and robust monitoring ensures secure and reliable operations.

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

Appendices

A. Deployment Checklist

  • Prepare Foundry environment and dependencies.
  • Set DEPLOYER_PRIVATE_KEY and optional ORACLE_ADDRESS, COMMITTEE_ADDRESS, MINIMUM_STAKE, CHALLENGE_PERIOD.
  • Run the deployment script with the appropriate RPC URL and verification flags.
  • Review console logs and confirm deployments/{chainId}.json contains expected addresses.
  • Assign roles to governance timelock, oracle, and slashing committee.
  • Initialize token minting permissions and faucet caps (testnet).

Section sources

  • README.md:328-345
  • script/Deploy.s.sol:17-30
  • script/Deploy.s.sol:35-106
  • src/CSIGToken.sol:12-25

B. Upgrade Procedure (UUPS)

  • Ensure only the UPGRADER_ROLE holder (governance timelock) can authorize upgrades.
  • Deploy new implementation contracts and use the UUPS upgrade mechanism.
  • After upgrade, verify roles remain intact and parameters are preserved.

Section sources

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

C. Oracle Configuration Reference

  • Required: RPC_URL, ORACLE_PRIVATE_KEY, IDENTITY_ADDRESS, REPUTATION_ADDRESS.
  • Optional: EPOCH_HOURS, PORT, FROM_BLOCK, LOG_CHUNK_SIZE, ORACLE_ADMIN_TOKEN.
  • Health and admin endpoints: /health, /epoch, /attest, /flag, /score/:didHash.

Section sources

  • oracle/index.js:11-26
  • oracle/index.js:111-171

D. Address Registry

  • deployments/{chainId}.json contains deployed contract addresses and deployer metadata for SDK configuration.

Section sources

  • script/Deploy.s.sol:108-128
  • deployments/11155111.json:1-1

Home

Start Here

Core Concepts

Smart Contracts

Oracle System

Agent SDK

Integration Guides

Economic Model

Deployment & Ops

Advanced Topics

Clone this wiki locally