README.md

SRS Smart Contracts

A blockchain-based OPRF (Oblivious Pseudorandom Function) oracle system built on Algorand. This system provides secure, decentralized OPRF evaluation services with a registry-based topology management system.

Overview

This codebase implements a distributed OPRF oracle system consisting of two main smart contracts:

1. Registry Contract - Manages user registrations, OPRF configurations, and oracle topologies
2. Oracle Contract - Provides OPRF evaluation services with secure request handling

The system enables users to register, configure OPRF parameters, and request OPRF evaluations through a network of trusted oracles.

Architecture

Registry Contract (src/registry.py)

• User Management: Handles user registration with usernames and addresses
• OPRF Configuration: Stores encrypted OPRF configurations for users
• Topology Management: Manages oracle network topologies with threshold-based security
• Fee Management: Centralized fee control for OPRF services

Oracle Contract (src/oracle.py)

• OPRF Evaluation: Processes OPRF evaluation requests
• Request Lifecycle: Manages request states (init → reply → finalize/abort)
• Security: Admin-only operations with proper access controls
• Box Storage: Uses Algorand boxes for efficient data storage

Features

• Decentralized OPRF: Secure oblivious pseudorandom function evaluation
• Threshold Security: Configurable threshold-based oracle networks
• User Registration: Username-based user management system
• Encrypted Configurations: Secure storage of OPRF parameters
• Request Tracking: Full lifecycle management of OPRF requests
• Fee Management: Centralized fee control and harvesting

Prerequisites

• Python 3.8+
• Algorand Node (for local development)
• PyTeal 0.25.0
• py-algorand-sdk 2.5.0

Installation

1. Initialize a virtual environment:

   python -m venv env
   source env/bin/activate  # On Windows: env\Scripts\activate

2. Install dependencies:

   pip install -r requirements.txt

3. Start Algorand node (for local development):

   # Ensure your Algorand node is running on localhost:4001
   # or update the connection details in the deployment scripts

Usage

Key Components

Registry Operations

• User Registration: Register users with usernames
• OPRF Configuration: Set encrypted OPRF parameters
• Topology Creation: Create oracle network topologies
• Fee Management: Set and retrieve OPRF fees

Oracle Operations

• OPRF Init: Initialize OPRF evaluation requests
• OPRF Reply: Process and respond to requests (admin only)
• OPRF Finalize: Complete successful evaluations
• OPRF Abort: Cancel failed requests

Example Usage

from clients.registry_client import RegistryClient
from clients.oracle_client import OracleClient

# Create registry client
registry = RegistryClient(algod_client, registry_app_id)

# Register a user
registry.User_create(
    user_account,
    username="alice",
    payment_txn=payment_transaction
).execute(algod_client, 1000)

# Create OPRF evaluation request
oracle = OracleClient(algod_client, oracle_app_id)
oracle.oprf_evaluate_init(
    user_account,
    request_uuid=uuid.uuid4().bytes,
    topology_id=1,
    encrypted_shard=bytes(80),
    public_input=b'user_data',
    blinded_element=bytes(48),
    registry_app_id=registry_app_id,
    oprf_fee=500000
).execute(algod_client, 1000)

Testing

Run the test suite to verify functionality:

# Run all tests
python -m unittest discover tests

# Run specific test
python tests/test_oracle.py

Project Structure

srs_smart_contracts/
├── bin/                    # Deployment and utility scripts
│   ├── oracle_deploy.py
│   ├── registry_deploy.py
│   └── registry_create_topology.py
├── src/                    # Source code
│   ├── oracle.py          # Oracle smart contract
│   ├── registry.py        # Registry smart contract
│   ├── clients/           # Client libraries
│   ├── utils/             # Utility functions
│   └── artifacts/         # Compiled TEAL contracts
├── tests/                 # Test suite
├── requirements.txt        # Python dependencies
└── topology.txt           # Deployment configuration

Security Features

• Admin Controls: Restricted operations for contract management
• Request Validation: Comprehensive input validation
• State Management: Secure request lifecycle tracking
• Box Storage: Efficient and secure data storage
• Threshold Security: Distributed oracle networks

Configuration

The system uses several configuration files:

• topology.txt: Oracle network configuration
• src/artifacts/: Compiled smart contract artifacts

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions and support, please open an issue on the repository or contact the development team.