Skip to content

Getting Started

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

Getting Started

**Referenced Files in This Document** - [README.md](file://README.md) - [docs/quickstart.md](file://docs/quickstart.md) - [foundry.toml](file://foundry.toml) - [packages/sdk/package.json](file://packages/sdk/package.json) - [packages/sdk/src/index.ts](file://packages/sdk/src/index.ts) - [packages/sdk/src/agent.ts](file://packages/sdk/src/agent.ts) - [packages/sdk/src/verifier.ts](file://packages/sdk/src/verifier.ts) - [packages/sdk/src/challenge.ts](file://packages/sdk/src/challenge.ts) - [packages/sdk/src/keys.ts](file://packages/sdk/src/keys.ts) - [packages/sdk/test/agent.test.ts](file://packages/sdk/test/agent.test.ts) - [packages/sdk/test/integration.test.ts](file://packages/sdk/test/integration.test.ts) - [script/Deploy.s.sol](file://script/Deploy.s.sol) - [broadcast/Deploy.s.sol/11155111/run-latest.json](file://broadcast/Deploy.s.sol/11155111/run-latest.json) - [deployments/11155111.json](file://deployments/11155111.json) - [src/CountersigIdentity.sol](file://src/CountersigIdentity.sol)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Prerequisites
  4. Environment Configuration
  5. Step-by-Step Setup
  6. Quickstart Workflow
  7. Practical Examples Using the TypeScript SDK
  8. Testnet Deployment Instructions
  9. Basic Usage Patterns
  10. Architecture Overview
  11. Dependency Analysis
  12. Performance Considerations
  13. Troubleshooting Guide
  14. Conclusion

Introduction

Countersig Network provides on-chain identity, reputation, and staking for autonomous AI agents. It anchors W3C Decentralized Identifiers (DIDs) on-chain, enforces Ed25519 PKI authentication off-chain, and secures agent reputation through a staked cryptoeconomic model. This guide helps you install prerequisites, configure your environment, deploy contracts to Sepolia testnet, and register your first agent using the TypeScript SDK.

Project Structure

The repository is organized into:

  • Solidity contracts under src/
  • Foundry configuration and deployment scripts under script/ and broadcast/
  • TypeScript SDK under packages/sdk/
  • Documentation under docs/
  • Testnet deployment artifacts under deployments/
graph TB
subgraph "Contracts (Solidity)"
A["src/CountersigIdentity.sol"]
B["src/CountersigReputation.sol"]
C["src/CountersigStaking.sol"]
D["src/CSIGToken.sol"]
end
subgraph "Tooling"
F["foundry.toml"]
G["script/Deploy.s.sol"]
H["broadcast/Deploy.s.sol/11155111/run-latest.json"]
I["deployments/11155111.json"]
end
subgraph "SDK (TypeScript)"
J["packages/sdk/src/index.ts"]
K["packages/sdk/src/agent.ts"]
L["packages/sdk/src/verifier.ts"]
M["packages/sdk/src/challenge.ts"]
N["packages/sdk/src/keys.ts"]
end
subgraph "Docs"
O["docs/quickstart.md"]
P["README.md"]
end
A --- J
B --- J
C --- J
D --- J
G --> H
G --> I
O --> J
P --> J
Loading

Diagram sources

  • foundry.toml:1-21
  • script/Deploy.s.sol:1-130
  • broadcast/Deploy.s.sol/11155111/run-latest.json:1-727
  • deployments/11155111.json:1-1
  • packages/sdk/src/index.ts:1-36
  • packages/sdk/src/agent.ts:1-80
  • packages/sdk/src/verifier.ts:1-160
  • packages/sdk/src/challenge.ts:1-79
  • packages/sdk/src/keys.ts:1-91
  • docs/quickstart.md:1-183
  • README.md:1-415

Section sources

  • README.md:1-415
  • docs/quickstart.md:1-183
  • foundry.toml:1-21
  • script/Deploy.s.sol:1-130
  • broadcast/Deploy.s.sol/11155111/run-latest.json:1-727
  • deployments/11155111.json:1-1
  • packages/sdk/src/index.ts:1-36

Prerequisites

  • Foundry installed for contract development and deployment.
  • Node.js 18+ for running the TypeScript SDK examples.
  • An Ethereum wallet with Sepolia ETH (use the Sepolia faucet).
  • $CSIG testnet tokens (mint via the CSIGToken contract).

Section sources

  • README.md:328-346
  • docs/quickstart.md:5-10

Environment Configuration

Set up your environment variables and local configuration:

  • Create a .env file with:
    • OPERATOR_PRIVATE_KEY: your Sepolia wallet private key
    • RPC_URL: your Sepolia RPC endpoint
  • Testnet contract addresses (chain ID 11155111) are pre-deployed and documented in the quickstart guide.

Section sources

  • docs/quickstart.md:17-32

Step-by-Step Setup

  1. Install the SDK

    • Run: npm install @countersig/protocol-sdk ethers

  2. Configure Foundry

    • Install dependencies: forge install
    • Build contracts: forge build
    • Run tests: forge test

  3. Explore SDK exports

    • The SDK exposes CountersigAgent, CountersigVerifier, challenge helpers, DID utilities, and key conversion helpers.

Section sources

  • docs/quickstart.md:11-15
  • README.md:328-346
  • packages/sdk/package.json:8-12
  • packages/sdk/src/index.ts:1-36

Quickstart Workflow

Register your first agent end-to-end on Sepolia testnet:

  1. Get testnet $CSIG

    • Mint tokens using the CSIGToken contract’s faucet function.

  2. Generate an Ed25519 keypair

    • Use CountersigAgent.generate() to create a new agent and securely store the private key.

  3. Register on-chain

    • Approve the staking contract to spend CSIG, then call registerAgent() to atomically deposit stake and register the agent.

  4. Verify registration

    • Use CountersigVerifier to fetch identity and reputation data.

  5. Sign a challenge (A2A authentication)

    • Issue a challenge from one agent to another, sign it with your Ed25519 private key, and verify it on-chain.

  6. Optional: Wire CounterAudit

    • Include agent_did in ingest calls to enrich sealed packets with identity and reputation.
sequenceDiagram
participant Dev as "Developer"
participant CSIG as "CSIGToken"
participant Agent as "CountersigAgent"
participant Verifier as "CountersigVerifier"
participant Staking as "CountersigStaking"
participant Identity as "CountersigIdentity"
Dev->>CSIG : "faucet()"
Dev->>Agent : "generate() + store privateKey"
Dev->>CSIG : "approve(STAKING_ADDRESS, minStake)"
Dev->>Staking : "registerAgent(...) via SDK helper"
Staking->>Identity : "registerAgent(...)"
Dev->>Verifier : "getIdentity(did)"
Dev->>Agent : "issueChallenge(peerDID)"
Agent->>Agent : "signChallenge(payload)"
Verifier->>Identity : "getIdentity(didHash)"
Verifier-->>Dev : "verifySignature(valid)"
Loading

Diagram sources

  • docs/quickstart.md:34-147
  • packages/sdk/src/agent.ts:41-79
  • packages/sdk/src/verifier.ts:136-159
  • src/CountersigIdentity.sol:120-141

Section sources

  • docs/quickstart.md:1-183

Practical Examples Using the TypeScript SDK

Below are practical usage patterns with code snippet paths:

  • Create an agent and generate keys

    • See: packages/sdk/src/agent.ts:41-49

  • Issue a challenge and sign it

    • See: packages/sdk/src/agent.ts:70-78
    • See: packages/sdk/src/challenge.ts:10-24

  • Verify a signature and check reputation thresholds

    • See: packages/sdk/src/verifier.ts:100-107
    • See: packages/sdk/src/verifier.ts:84-88

  • Register an agent on-chain

    • See: packages/sdk/src/verifier.ts:136-159

  • Build a W3C DID Document

    • See: packages/sdk/src/verifier.ts:109-132

  • Unit tests demonstrating flows

    • See: packages/sdk/test/agent.test.ts:60-108
    • See: packages/sdk/test/integration.test.ts:84-98

Section sources

  • packages/sdk/src/agent.ts:1-80
  • packages/sdk/src/challenge.ts:1-79
  • packages/sdk/src/verifier.ts:1-160
  • packages/sdk/test/agent.test.ts:1-156
  • packages/sdk/test/integration.test.ts:1-121

Testnet Deployment Instructions

Pre-deployed testnet addresses (chain ID 11155111) are available. Alternatively, deploy locally using Foundry:

  • Local deployment

    • Set environment variables:
      • DEPLOYER_PRIVATE_KEY
      • Optional: ORACLE_ADDRESS, COMMITTEE_ADDRESS, MINIMUM_STAKE, CHALLENGE_PERIOD
    • Run: forge script script/Deploy.s.sol --rpc-url $SEPOLIA_RPC --broadcast --verify -vvvv

  • Post-deployment

    • Addresses are logged and written to deployments/{chainId}.json
    • Example artifact: broadcast/Deploy.s.sol/11155111/run-latest.json:1-727
    • Example deployment file: deployments/11155111.json:1-1

  • Contract initialization highlights

    • Identity, Reputation, and Staking proxies are initialized and roles are granted.
    • See: script/Deploy.s.sol:35-106

Section sources

  • docs/quickstart.md:25-32
  • script/Deploy.s.sol:17-30
  • script/Deploy.s.sol:35-106
  • broadcast/Deploy.s.sol/11155111/run-latest.json:1-727
  • deployments/11155111.json:1-1

Basic Usage Patterns

  • Identity resolution

    • Use CountersigVerifier to resolve agent identity and status from CountersigIdentity.
    • See: packages/sdk/src/verifier.ts:50-60

  • Reputation checks

    • Query reputation scores and threshold compliance from CountersigReputation.
    • See: packages/sdk/src/verifier.ts:67-88

  • Stake verification

    • Confirm minimum stake and current stake amounts from CountersigStaking.
    • See: packages/sdk/src/verifier.ts:90-98

  • DID computation and parsing

    • Compute didHash deterministically from chainId and agentAddress.
    • See: packages/sdk/src/keys.ts:75-85
    • See: packages/sdk/src/verifier.ts:45-48

Section sources

  • packages/sdk/src/verifier.ts:1-160
  • packages/sdk/src/keys.ts:1-91

Architecture Overview

High-level architecture across on-chain contracts and off-chain verification:

graph TB
subgraph "Off-Chain"
A1["Agent Node A<br/>Ed25519 Keys"]
A2["Agent Node B<br/>Ed25519 Keys"]
V["Verifier<br/>CountersigVerifier"]
end
subgraph "On-Chain"
I["CountersigIdentity<br/>DID anchoring, pubkey storage, AgentStatus"]
R["CountersigReputation<br/>6-factor score store"]
S["CountersigStaking<br/>$CSIG bonds, slashing lifecycle"]
end
A1 --> |"challenge-response"| A2
A2 --> |"resolve DID"| I
V --> |"getIdentity/getReputation"| I
V --> |"getStake/meetsThreshold"| R
V --> |"verifySignature"| I
S --> |"updateStatus(Slashed)"| I
S --> |"zeroReputation()"| R
Loading

Diagram sources

  • README.md:20-51
  • README.md:192-250
  • src/CountersigIdentity.sol:18-197

Section sources

  • README.md:20-51
  • README.md:192-250
  • src/CountersigIdentity.sol:1-227

Dependency Analysis

  • SDK dependencies

    • ethers: for interacting with contracts and wallets
    • tweetnacl: for Ed25519 keypair generation and signatures
    • See: packages/sdk/package.json:13-21

  • SDK exports and internal modules

    • Agent, Verifier, challenge helpers, DID utilities, and key conversions
    • See: packages/sdk/src/index.ts:1-36

  • Contract dependencies

    • OpenZeppelin UUPS upgradeable contracts and Forge Std
    • See: foundry.toml:5-9 
graph LR
SDK["@countersig/protocol-sdk"] --> Ethers["ethers"]
SDK --> NaCl["tweetnacl"]
SDK --> Agent["agent.ts"]
SDK --> Verifier["verifier.ts"]
SDK --> Challenge["challenge.ts"]
SDK --> Keys["keys.ts"]
Verifier --> IdentityABI["CountersigIdentity ABI"]
Verifier --> ReputationABI["CountersigReputation ABI"]
Verifier --> StakingABI["CountersigStaking ABI"]
Loading

Diagram sources

  • packages/sdk/package.json:13-21
  • packages/sdk/src/index.ts:1-36
  • packages/sdk/src/verifier.ts:1-14

Section sources

  • packages/sdk/package.json:1-34
  • packages/sdk/src/index.ts:1-36
  • foundry.toml:5-9

Performance Considerations

  • Deterministic didHash computation avoids repeated on-chain reads.
  • Batch off-chain signature verification using the verifier’s helper methods.
  • Use provider caching and efficient polling intervals for reputation and stake queries.
  • Keep challenge TTLs reasonable to prevent replay attacks while minimizing latency.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Registration errors

    • AlreadyRegistered: The agent address is already registered; use a different address or operator account.
    • ZeroPubKey or ZeroAgentAddress: Ensure non-zero public key and agent address are provided.
    • See: src/CountersigIdentity.sol:70-75

  • Challenge verification failures

    • Invalid or expired payload: Ensure the challenge payload format matches the expected prefix and timestamp.
    • See: packages/sdk/src/challenge.ts:36-62

  • Integration tests require live network

    • Integration tests auto-skip when environment variables are missing; set COUNTERSIG_* variables to enable.
    • See: packages/sdk/test/integration.test.ts:1-15

Section sources

  • src/CountersigIdentity.sol:70-75
  • packages/sdk/src/challenge.ts:36-62
  • packages/sdk/test/integration.test.ts:1-15

Conclusion

You are now equipped to install prerequisites, configure your environment, deploy or use pre-deployed testnet contracts, and register your first agent using the TypeScript SDK. Use the practical examples and patterns above to implement agent-to-agent authentication, reputation checks, and on-chain registration. Refer to the documentation links for deeper dives into the ecosystem, reputation model, and integrations.

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

Home

Start Here

Core Concepts

Smart Contracts

Oracle System

Agent SDK

Integration Guides

Economic Model

Deployment & Ops

Advanced Topics

Clone this wiki locally