Skip to main content

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:
  1. Protocol Registration: On-chain protocol metadata and configuration
  2. Data Provider Management: Trusted data sources for each protocol
  3. Score Contribution: Protocol-specific score calculation
  4. Integration Verification: Cryptographic proof of integration
  5. 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)

3. Social Protocols

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

Testnet Deployments

// Protocol Registry Contract
address: 0x1234567890123456789012345678901234567890

// Proxy Contract
address: 0x2345678901234567890123456789012345678901

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

OperationREGISTRAR_ROLEPROVIDER_ROLEADMIN_ROLEPublic
Register Protocol
Update Protocol
Add Data Provider
Submit Data
View Protocols

Gas Optimization

Gas Estimates

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

Best Practices

For Protocol Developers

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

For Integrators

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