Polygon Identity

A Python package for managing blockchain-based identities on Polygon. This package provides a simple way to create, manage, and verify decentralized identities with social recovery features and zero-knowledge proof support.

Features

• Identity Management: Create and manage blockchain identities
• Social Recovery: Recover lost identities using trusted guardians
• Zero-Knowledge Proofs: Generate and verify proofs without revealing secrets
• Framework Integration: Ready-to-use middleware for Django and FastAPI
• Type Safety: Full type hints for better development experience

Installation

Install the basic package:

pip install polygon-identity

Framework-specific Installation

For Django projects:

pip install polygon-identity[django]

For FastAPI projects:

pip install polygon-identity[fastapi]

For development with all tools:

pip install polygon-identity[dev]

Quick Start

Basic Usage

from polygon_identity import PolygonIdentity
from polygon_identity.types import IdentityConfig

# Configure the identity manager
config = IdentityConfig(
    rpc_url='https://rpc-amoy.polygon.technology',
    contract_address='0x849c0E1b4371E033e1ccf7d1824e6A2D24Cac4B4',
    private_key='your_private_key_here'
)

# Initialize the identity manager
identity_manager = PolygonIdentity(config)

# Create a new identity
identity_address = identity_manager.create_identity()
print(f'Identity created: {identity_address}')

# Retrieve identity information
identity = identity_manager.get_identity(identity_address)
print(f'Owner: {identity.owner}')
print(f'Created: {identity.created_at}')
print(f'Active: {identity.is_active}')

# Verify an identity
is_valid = identity_manager.verify_identity(identity_address)
print(f'Identity is valid: {is_valid}')

Social Recovery

from polygon_identity import SocialRecovery
from polygon_identity.types import IdentityConfig

config = IdentityConfig(
    rpc_url='https://rpc-amoy.polygon.technology',
    contract_address='0x849c0E1b4371E033e1ccf7d1824e6A2D24Cac4B4',
    private_key='your_private_key_here'
)

# Initialize social recovery
recovery = SocialRecovery(
    config,
    contract_address='0x4c676A17482D95571D5602e197D1eaF93990AFd9'
)

# Set up recovery guardians
guardians = [
    '0x1234567890123456789012345678901234567890',
    '0x2345678901234567890123456789012345678901',
    '0x3456789012345678901234567890123456789012'
]
threshold = 2  # Require 2 out of 3 guardians

recovery.set_recovery_config(identity_address, guardians, threshold)

# Request recovery (if identity is lost)
recovery.request_recovery(identity_address)

# Approve recovery (as a guardian)
recovery.approve_recovery(identity_address)

# Check approval status
approval_count = recovery.get_approval_count(identity_address)
print(f'Approvals: {approval_count}/{threshold}')

Zero-Knowledge Proofs

from polygon_identity import ZKIdentity

zk = ZKIdentity()

# Generate a proof
secret = 'my_secret_data'
public_data = 'public_context'
proof = zk.generate_proof(secret, public_data)

print(f'Commitment: {proof.commitment}')
print(f'Proof: {proof.proof}')

# Verify the proof
is_valid = zk.verify_proof(proof, public_data)
print(f'Proof is valid: {is_valid}')

Framework Integration

FastAPI

Create a FastAPI application with identity authentication:

from fastapi import FastAPI, HTTPException
from polygon_identity import PolygonIdentity
from polygon_identity.types import IdentityConfig
import os

app = FastAPI()

config = IdentityConfig(
    rpc_url=os.getenv('RPC_URL'),
    contract_address=os.getenv('CONTRACT_ADDRESS'),
    private_key=os.getenv('PRIVATE_KEY')
)

identity_manager = PolygonIdentity(config)

@app.post('/identity/create')
async def create_identity():
    try:
        address = identity_manager.create_identity()
        return {'address': address}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

@app.get('/identity/{address}')
async def get_identity(address: str):
    try:
        identity = identity_manager.get_identity(address)
        return {
            'owner': identity.owner,
            'public_key': identity.public_key,
            'created_at': identity.created_at,
            'is_active': identity.is_active
        }
    except Exception as e:
        raise HTTPException(status_code=404, detail=str(e))

Django

Add polygon identity authentication to your Django project:

# settings.py
INSTALLED_APPS = [
    # ... other apps
    'polygon_identity.django',
]

MIDDLEWARE = [
    # ... other middleware
    'polygon_identity.django.middleware.PolygonIdentityMiddleware',
]

AUTHENTICATION_BACKENDS = [
    'polygon_identity.django.auth_backend.PolygonIdentityBackend',
    # ... other backends
]

# Identity configuration
POLYGON_IDENTITY_CONFIG = {
    'rpc_url': 'https://rpc-amoy.polygon.technology',
    'contract_address': '0x849c0E1b4371E033e1ccf7d1824e6A2D24Cac4B4',
}

Then use it in your views:

from django.contrib.auth.decorators import login_required
from polygon_identity.django import verify_identity

@login_required
def protected_view(request):
    # User is authenticated with their blockchain identity
    identity_address = request.user.username
    return render(request, 'protected.html', {
        'identity': identity_address
    })

Configuration

Environment Variables

Create a .env file in your project:

RPC_URL=https://rpc-amoy.polygon.technology
CONTRACT_ADDRESS=0x849c0E1b4371E033e1ccf7d1824e6A2D24Cac4B4
SOCIAL_RECOVERY_ADDRESS=0x4c676A17482D95571D5602e197D1eaF93990AFd9
PRIVATE_KEY=your_private_key_here

Load them in your application:

from dotenv import load_dotenv
import os

load_dotenv()

config = IdentityConfig(
    rpc_url=os.getenv('RPC_URL'),
    contract_address=os.getenv('CONTRACT_ADDRESS'),
    private_key=os.getenv('PRIVATE_KEY')
)

Contract Addresses

The package is configured to work with deployed contracts on Polygon Amoy testnet:

• IdentityManager: 0x849c0E1b4371E033e1ccf7d1824e6A2D24Cac4B4
• SocialRecovery: 0x4c676A17482D95571D5602e197D1eaF93990AFd9

For mainnet deployment, you'll need to deploy the contracts yourself or use the official deployed addresses when available.

API Reference

PolygonIdentity

Main class for identity management.

Methods

• create_identity(public_key: Optional[str] = None) -> str: Create a new identity
• get_identity(address: str) -> IdentityData: Retrieve identity information
• verify_identity(address: str) -> bool: Verify if an identity is valid and active
• update_public_key(identity_address: str, new_public_key: str) -> None: Update identity public key
• deactivate_identity(identity_address: str) -> None: Deactivate an identity
• generate_key_pair() -> IdentityKeys: Generate a new key pair

SocialRecovery

Class for managing social recovery.

Methods

• set_recovery_config(identity_address: str, guardians: list, threshold: int) -> None: Set up recovery guardians
• request_recovery(identity_address: str) -> None: Request recovery for a lost identity
• approve_recovery(identity_address: str) -> None: Approve a recovery request as a guardian
• get_approval_count(identity_address: str) -> int: Get current approval count
• get_recovery_config(identity_address: str) -> Optional[RecoveryConfig]: Get recovery configuration

ZKIdentity

Class for zero-knowledge proof operations.

Methods

• generate_commitment(data: str) -> str: Generate a commitment hash
• generate_proof(secret: str, public_data: str) -> ZKProof: Generate a zero-knowledge proof
• verify_proof(proof: ZKProof, public_data: str) -> bool: Verify a zero-knowledge proof

Examples

Check the examples/ directory for more usage examples:

• basic_usage.py: Basic identity operations
• fastapi_server.py: FastAPI integration example

Run an example:

python examples/basic_usage.py

Testing

Install development dependencies:

pip install polygon-identity[dev]

Run tests:

pytest

Run tests with coverage:

pytest --cov=polygon_identity tests/

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/Usamatahir23/polygon_identity_py
cd polygon_identity_py

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .[dev]

Code Quality

Format code with black:

black polygon_identity/

Run linter:

flake8 polygon_identity/

Type checking:

mypy polygon_identity/

Security Notes

• Never commit your private keys to version control
• Always use environment variables for sensitive data
• Use testnet for development and testing
• Audit your code before deploying to mainnet
• Keep your dependencies up to date

Troubleshooting

Common Issues

Issue: web3.exceptions.ContractLogicError

• Solution: Check that you have enough MATIC in your wallet for gas fees

Issue: AttributeError: 'SignedTransaction' object has no attribute 'rawTransaction'

• Solution: The package handles both rawTransaction and raw_transaction attributes automatically

Issue: Identity creation fails

• Solution: Ensure your private key is correct and you're connected to the right network

Getting Help

• Check the examples directory
• Review the API documentation
• Open an issue on GitHub

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Acknowledgments

• Built for Polygon blockchain
• Inspired by decentralized identity standards
• Uses Web3.py for blockchain interactions

Links

• GitHub Repository
• Polygon Documentation
• Web3.py Documentation

Support

If you find this package useful, please consider:

• Starring the repository on GitHub
• Reporting bugs and suggesting features
• Contributing to the codebase

---

Made with ❤️ for the Polygon community