Protocol Registry Overview

Overview

The ZKScore Protocol Registry is a central registry that tracks integrated protocols, manages protocol metadata, and coordinates cross-protocol score aggregation. It enables seamless integration of new protocols and standardized data collection across the ZKScore ecosystem.

The Protocol Registry is the central coordination layer for all integrated protocols. Always register your protocol before contributing score data.

Contract Architecture

Core Components

The Protocol Registry consists of several key components:

Protocol Registration: On-chain protocol metadata and configuration
Data Provider Management: Trusted data sources for each protocol
Score Contribution: Protocol-specific score calculation
Integration Verification: Cryptographic proof of integration
Cross-Protocol Coordination: Standardized interfaces across protocols

Protocol Types

1. DeFi Protocols

Decentralized finance applications:

DEXs (Uniswap, SushiSwap, Curve)
Lending (Aave, Compound, MakerDAO)
Yield Aggregators (Yearn, Harvest)
Derivatives (dYdX, Synthetix)
Insurance (Nexus Mutual, Cover)

2. NFT Protocols

NFT marketplaces and platforms:

Marketplaces (OpenSea, Blur, LooksRare)
Collections (BAYC, Azuki, Doodles)
Gaming NFTs (Axie, Gods Unchained)
Art Platforms (Foundation, SuperRare)
NFT Finance (NFTfi, BendDAO)

Web3 social platforms:

Social Networks (Lens, Farcaster)
Content Platforms (Mirror, Paragraph)
Messaging (XMTP, Dialect)
Identity (ENS, Unstoppable Domains)
Community (Discord, Guild.xyz)

4. Governance Protocols

DAO and governance systems:

DAO Frameworks (Aragon, DAOstack)
Voting (Snapshot, Tally)
Delegation (delegate.xyz)
Treasury (Gnosis Safe, Parcel)
Governance Aggregators (Boardroom)

Contract Addresses

Mainnet Deployments

// Protocol Registry Contract
address: 0x5678901234567890123456789012345678901234

// Proxy Contract
address: 0x6789012345678901234567890123456789012345

// Protocol Registry Contract
address: 0x7890123456789012345678901234567890123456

// Proxy Contract
address: 0x8901234567890123456789012345678901234567

// Protocol Registry Contract
address: 0x9012345678901234567890123456789012345678

// Proxy Contract
address: 0x0123456789012345678901234567890123456789

Testnet Deployments

// Protocol Registry Contract
address: 0x1234567890123456789012345678901234567890

// Proxy Contract
address: 0x2345678901234567890123456789012345678901

// Protocol Registry Contract
address: 0x3456789012345678901234567890123456789012

// Proxy Contract
address: 0x4567890123456789012345678901234567890123

Protocol Structure

Protocol Data Model

struct Protocol {
    uint256 id;                     // Unique protocol ID
    string name;                    // Protocol name
    string description;             // Protocol description
    ProtocolType protocolType;      // Type (DeFi, NFT, Social, etc.)
    address dataProvider;           // Authorized data provider
    address[] integrationContracts; // Integration contract addresses
    uint256 scoreWeight;            // Weight in overall score (basis points)
    bool isActive;                  // Protocol active status
    uint256 registeredAt;           // Registration timestamp
    uint256 totalUsers;             // Total integrated users
    bytes metadata;                 // Additional metadata
}

Protocol Types

enum ProtocolType {
    DEFI,           // Decentralized Finance
    NFT,            // NFT and Digital Collectibles
    SOCIAL,         // Social and Content
    TRADING,        // Trading and Exchange
    GOVERNANCE,     // DAO and Governance
    GAMING,         // Gaming and Metaverse
    IDENTITY,       // Identity and Verification
    INFRASTRUCTURE  // Infrastructure and Tools
}

Integration Requirements

struct IntegrationRequirements {
    bool requiresKYC;               // KYC required
    bool requiresStaking;           // Staking required
    uint256 minimumStake;           // Minimum stake amount
    bool requiresAttestation;       // Attestation required
    bytes32[] requiredSchemas;      // Required attestation schemas
}

Contract Interface

Core Functions

// Protocol Management
function registerProtocol(
    string memory name,
    string memory description,
    ProtocolType protocolType,
    address dataProvider,
    uint256 scoreWeight,
    bytes memory metadata
) external returns (uint256);

function updateProtocol(uint256 protocolId, bytes memory updateData) external;
function deactivateProtocol(uint256 protocolId) external;

// Data Provider Management
function addDataProvider(uint256 protocolId, address provider) external;
function removeDataProvider(uint256 protocolId, address provider) external;
function isAuthorizedProvider(uint256 protocolId, address provider) external view returns (bool);

// Protocol Queries
function getProtocol(uint256 protocolId) external view returns (Protocol memory);
function getProtocolsByType(ProtocolType protocolType) external view returns (uint256[] memory);
function getAllProtocols() external view returns (uint256[] memory);

// User Integration
function getUserIntegrations(address user) external view returns (uint256[] memory);
function isUserIntegrated(address user, uint256 protocolId) external view returns (bool);

Events

// Protocol Events
event ProtocolRegistered(uint256 indexed protocolId, string name, ProtocolType protocolType);
event ProtocolUpdated(uint256 indexed protocolId, bytes updateData);
event ProtocolDeactivated(uint256 indexed protocolId, uint256 timestamp);

// Provider Events
event DataProviderAdded(uint256 indexed protocolId, address indexed provider);
event DataProviderRemoved(uint256 indexed protocolId, address indexed provider);

// Integration Events
event UserIntegrated(address indexed user, uint256 indexed protocolId, uint256 timestamp);
event IntegrationRemoved(address indexed user, uint256 indexed protocolId, uint256 timestamp);

Integration Examples

Register a Protocol

import { ethers } from 'ethers';

// Contract ABI (simplified)
const PROTOCOL_REGISTRY_ABI = [
  "function registerProtocol(string name, string description, uint8 protocolType, address dataProvider, uint256 scoreWeight, bytes metadata) external returns (uint256)",
  "function getProtocol(uint256 protocolId) external view returns (tuple(uint256 id, string name, string description, uint8 protocolType, address dataProvider, address[] integrationContracts, uint256 scoreWeight, bool isActive, uint256 registeredAt, uint256 totalUsers, bytes metadata))",
  "event ProtocolRegistered(uint256 indexed protocolId, string name, uint8 protocolType)"
];

// Initialize contract
const provider = new ethers.providers.JsonRpcProvider('https://mainnet.infura.io/v3/YOUR_KEY');
const contract = new ethers.Contract(
  '0x5678901234567890123456789012345678901234',
  PROTOCOL_REGISTRY_ABI,
  provider
);

// Register new protocol
async function registerProtocol() {
  const signer = provider.getSigner();
  const contractWithSigner = contract.connect(signer);
  
  // Encode metadata
  const metadata = ethers.utils.defaultAbiCoder.encode(
    ['string', 'string', 'string'],
    ['https://myprotocol.com', 'v1.0.0', 'DeFi protocol for lending']
  );
  
  const tx = await contractWithSigner.registerProtocol(
    'MyDeFiProtocol',
    'Decentralized lending protocol with innovative features',
    0, // DEFI type
    '0x1234567890123456789012345678901234567890', // Data provider
    1500, // 15% weight (1500 basis points)
    metadata
  );
  
  const receipt = await tx.wait();
  const event = receipt.events.find(e => e.event === 'ProtocolRegistered');
  const protocolId = event.args.protocolId;
  
  console.log(`Protocol registered with ID: ${protocolId.toString()}`);
  return protocolId;
}

Access Control

Roles

// Role definitions
bytes32 public constant REGISTRAR_ROLE = keccak256("REGISTRAR_ROLE");
bytes32 public constant PROVIDER_ROLE = keccak256("PROVIDER_ROLE");
bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");

Permission Matrix

Operation	REGISTRAR_ROLE	PROVIDER_ROLE	ADMIN_ROLE	Public
Register Protocol	✅	❌	✅	❌
Update Protocol	✅	❌	✅	❌
Add Data Provider	❌	❌	✅	❌
Submit Data	❌	✅	✅	❌
View Protocols	✅	✅	✅	✅

Gas Optimization

Gas Estimates

Operation	Gas Cost	Description
Register Protocol	~180,000	Register new protocol
Update Protocol	~60,000	Update protocol data
Add Data Provider	~50,000	Add authorized provider
Query Protocol	~4,000	View protocol data
Get User Integrations	~5,000	View user’s protocols

Best Practices

For Protocol Developers

Accurate Metadata: Provide complete protocol information
Secure Data Providers: Use secure, reliable data sources
Appropriate Weight: Request fair score weighting
Regular Updates: Keep protocol information current
Monitor Integration: Track integration metrics

For Integrators

Verify Registration: Confirm protocol is registered
Check Authorization: Verify data provider authorization
Monitor Events: Track protocol changes
Handle Errors: Implement comprehensive error handling
Cache Data: Cache protocol metadata locally

Functions Reference - Complete function documentation
Events Reference - Event documentation
Integration Guide - Integration examples
Score Calculator - Score calculation contract

Smart Contracts

IdentitySBT

ScoreCalculator

AchievementRegistry

TrustRegistry