Protocol Registry Functions

Overview

This document provides a comprehensive reference for all functions available in the ZKScore Protocol Registry contract. Each function includes detailed parameter descriptions, return values, gas estimates, and usage examples.

All functions that modify state require a transaction and will consume gas. View functions are free to call and return data immediately.

Protocol Management Functions

registerProtocol

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

Parameters:

name (string): Protocol name
description (string): Protocol description
protocolType (ProtocolType): Type of protocol (0-7)
dataProvider (address): Authorized data provider address
scoreWeight (uint256): Score contribution weight (basis points)
metadata (bytes): Encoded additional metadata

Returns:

uint256: Newly created protocol ID

Gas Estimate: ~180,000 gas Requirements:

Caller must have REGISTRAR_ROLE
Name cannot be empty
Score weight must be reasonable (max 5000 = 50%)

Events Emitted:

ProtocolRegistered(uint256 indexed protocolId, string name, ProtocolType protocolType)

Example Usage:

const { ethers } = require('ethers');

async function registerProtocol() {
  const provider = new ethers.providers.JsonRpcProvider('https://mainnet.infura.io/v3/YOUR_KEY');
  const signer = provider.getSigner();
  
  const contract = new ethers.Contract(
    '0x5678901234567890123456789012345678901234',
    PROTOCOL_REGISTRY_ABI,
    signer
  );
  
  // Encode metadata
  const metadata = ethers.utils.defaultAbiCoder.encode(
    ['string', 'string', 'string', 'string[]'],
    [
      'https://myprotocol.com',
      'v1.0.0',
      'DeFi lending protocol',
      ['https://twitter.com/myprotocol', 'https://discord.gg/myprotocol']
    ]
  );
  
  const tx = await contract.registerProtocol(
    'MyDeFiProtocol',
    'Decentralized lending and borrowing platform with competitive rates',
    0, // DEFI
    '0x1234567890123456789012345678901234567890',
    1500, // 15%
    metadata
  );
  
  const receipt = await tx.wait();
  const event = receipt.events.find(e => e.event === 'ProtocolRegistered');
  const protocolId = event.args.protocolId;
  
  console.log(`Protocol registered: ID ${protocolId.toString()}`);
  return protocolId;
}

from web3 import Web3
from eth_abi import encode

def register_protocol():
    w3 = Web3(Web3.HTTPProvider('https://mainnet.infura.io/v3/YOUR_KEY'))
    
    contract = w3.eth.contract(
        address='0x5678901234567890123456789012345678901234',
        abi=PROTOCOL_REGISTRY_ABI
    )
    
    account = w3.eth.account.from_key('YOUR_PRIVATE_KEY')
    
    # Encode metadata
    metadata = encode(
        ['string', 'string', 'string', 'string[]'],
        [
            'https://myprotocol.com',
            'v1.0.0',
            'DeFi lending protocol',
            ['https://twitter.com/myprotocol', 'https://discord.gg/myprotocol']
        ]
    )
    
    tx = contract.functions.registerProtocol(
        'MyDeFiProtocol',
        'Decentralized lending and borrowing platform with competitive rates',
        0,  # DEFI
        '0x1234567890123456789012345678901234567890',
        1500,  # 15%
        metadata
    ).buildTransaction({
        'from': account.address,
        'gas': 200000,
        'gasPrice': w3.eth.gas_price,
        'nonce': w3.eth.get_transaction_count(account.address)
    })
    
    signed_tx = w3.eth.account.sign_transaction(tx, account.key)
    tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction)
    receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
    
    event = contract.events.ProtocolRegistered().processReceipt(receipt)[0]
    protocol_id = event['args']['protocolId']
    
    print(f"Protocol registered: ID {protocol_id}")
    return protocol_id

getProtocol

Get detailed protocol information.

function getProtocol(uint256 protocolId) 
    external 
    view 
    returns (Protocol memory);

Parameters:

protocolId (uint256): Protocol identifier

Returns:

Protocol: Complete protocol data structure

Gas Estimate: ~5,000 gas (view function) Example Usage:

async function getProtocolDetails(protocolId) {
  const protocol = await contract.getProtocol(protocolId);
  
  console.log('Protocol:', {
    id: protocol.id.toString(),
    name: protocol.name,
    description: protocol.description,
    type: protocol.protocolType,
    dataProvider: protocol.dataProvider,
    scoreWeight: protocol.scoreWeight.toString(),
    isActive: protocol.isActive,
    totalUsers: protocol.totalUsers.toString()
  });
  
  return protocol;
}

def get_protocol_details(protocol_id):
    protocol = contract.functions.getProtocol(protocol_id).call()
    
    print('Protocol:', {
        'id': protocol[0],
        'name': protocol[1],
        'description': protocol[2],
        'type': protocol[3],
        'dataProvider': protocol[4],
        'scoreWeight': protocol[6],
        'isActive': protocol[7],
        'totalUsers': protocol[9]
    })
    
    return protocol

isAuthorizedProvider

Check if an address is authorized to provide data for a protocol.

function isAuthorizedProvider(uint256 protocolId, address provider) 
    external 
    view 
    returns (bool);

Parameters:

protocolId (uint256): Protocol identifier
provider (address): Provider address to check

Returns:

bool: True if authorized, false otherwise

Gas Estimate: ~2,000 gas (view function)

Error Handling

Common Errors

Error	Description	Solution
`"Protocol not found"`	Invalid protocol ID	Verify protocol ID exists
`"Not authorized"`	Insufficient permissions	Check role assignments
`"Protocol not active"`	Protocol is deactivated	Check isActive status
`"Invalid weight"`	Score weight out of range	Use valid weight (0-5000)
`"Provider already exists"`	Provider already added	Check existing providers

Contract Overview - Contract architecture
Events Reference - Event documentation
Integration Guide - Integration examples

Smart Contracts

IdentitySBT

ScoreCalculator

AchievementRegistry

TrustRegistry