OConsent Protocol Documentation

Introduction

OConsent is an open protocol for privacy and consent management using blockchain technology. It enables transparent processing of personal data throughout its lifecycle from capture, lineage to redaction.

Key Features

• Blockchain-based consent management
• Trusted timestamping
• Zero-knowledge proofs for privacy
• Multi-chain fingerprinting
• Surrogate ID management

Architecture

The OConsent platform employs a layered architecture consisting of:

Components

• API Gateway
• Consent Manager
• Identity Store
• Local Blockchain (Sidechain)
• Fingerprinting Service
• Timestamping Service

Core Components

Consent Manager

The heart of the platform responsible for:

• Agreement creation and lifecycle management
• Validation and enforcement
• Purpose management
• Permission controls

Smart Contracts

contract OConsentOwned {
    address public ownerCurr;
    
    event LogTransfer(address indexed
        ownerPrev, address indexed ownerNew);
        
    modifier ownerSole() {
        require (msg.sender == ownerCurr);
        _;
    }
}

Key Workflows

Consent Agreement Creation

1. Data Controller initiates consent request
2. Agreement template is generated
3. Data Subject reviews and signs
4. Trusted timestamp is applied
5. Agreement is stored on blockchain

Data Access Process

{
  "agreement_hash_id": "f53b3a9e-22e2-4356",
  "timestamp_proofs": {
    "nist_beacon": "9e82461318bd5f55282d",
    "drand_hash": "216296e1dcd5bb2ea996"
  }
}

Blockchain Integration

Fingerprinting Process

The platform uses a multi-chain approach:

• Local Ethereum sidechain for primary storage
• Bitcoin for immutable timestamping
• Ethereum mainnet for state verification

Privacy Features

Zero-Knowledge Proofs

Implementation of Zk-SNARKs for:

• Age verification
• Identity validation
• Attribute verification

Surrogate IDs

Implementation

API Endpoints

POST /consent-agreements
GET /consent-proofs/{agreementId}
POST /blockchain/fingerprint
POST /timestamps
POST /data-access-keys
POST /surrogate-ids

Deployment

The platform can be deployed using:

• Docker containers
• Kubernetes orchestration
• Cloud-native infrastructure

CLI Tools

Installation

OConsent CLI can be installed using pip:

pip install oconsent-cli

Basic Usage

After installation, you can use the oconsent command:

$ oconsent --help
Usage: oconsent [OPTIONS] COMMAND [ARGS]...

Options:
  --version          Show version and exit
  -v, --verbose     Enable verbose output
  --config FILE     Configuration file
  -h, --help        Show this message and exit

Commands:
  agreement    Manage consent agreements
  proof       Generate and verify consent proofs
  timestamp   Generate trusted timestamps
  verify      Verify blockchain fingerprints
  key         Manage data access keys

Python Module Usage

You can also use OConsent programmatically in your Python applications:

from oconsent import ConsentManager, TimestampService, BlockchainService

# Initialize the consent manager
consent_manager = ConsentManager(
    api_key="your_api_key",
    environment="production"
)

# Create a new consent agreement
agreement = consent_manager.create_agreement(
    data_subject_id="7a2a83b1694940f38d6a",
    data_controller_id="478ecb5f2b674ad",
    purpose="marketing",
    data_attributes=["email", "preferences"],
    expiry="2025-12-15"
)

# Generate proof with timestamp
proof = agreement.generate_proof()
print(proof.verification_url)

Configuration

Create a configuration file at ~/.oconsent/config.yaml:

api:
  url: https://api.oconsent.io/v1
  key: your_api_key

blockchain:
  network: mainnet  # or testnet
  providers:
    ethereum: https://eth-mainnet.gateway.pokt.network/v1/...
    bitcoin: https://btc.getblock.io/mainnet/

timestamp:
  providers:
    - nist
    - drand

Common Tasks

Creating a Consent Agreement

$ oconsent agreement create \
    --subject-id 7a2a83b1694940f38d6a \
    --controller-id 478ecb5f2b674ad \
    --purpose marketing \
    --attributes email,preferences \
    --expiry 2025-12-15

Generating Proof

$ oconsent proof generate \
    --agreement-id f53b3a9e-22e2-4356-81a1 \
    --timestamp-source nist

Verifying Blockchain Fingerprint

$ oconsent verify fingerprint \
    --proof-id b94f6f125c79e3a5ffaa826f584c10d52ada669e

Python SDK Examples

Managing Data Access Keys

from oconsent import DataAccessKeyManager

dak_manager = DataAccessKeyManager()

# Generate new data access key
dak = dak_manager.generate_key(
    agreement_id="f53b3a9e-22e2-4356",
    controller_public_key="-----BEGIN PUBLIC KEY-----\n..."
)

# Verify access
is_valid = dak_manager.verify_access(
    key_id=dak.id,
    agreement_id="f53b3a9e-22e2-4356"
)

Working with Zero-Knowledge Proofs

from oconsent import ZKProofService

zk_service = ZKProofService()

# Generate age verification proof
proof = zk_service.generate_proof(
    proof_type="age_verification",
    private_input={"date_of_birth": "1990-01-01"},
    public_input={"min_age": 18}
)

# Verify the proof
is_valid = zk_service.verify_proof(
    proof=proof.proof_data,
    public_input={"min_age": 18}
)

Error Handling

from oconsent import ConsentError, BlockchainError

try:
    agreement = consent_manager.create_agreement(...)
except ConsentError as e:
    print(f"Consent error: {e}")
except BlockchainError as e:
    print(f"Blockchain error: {e}")

Best Practices

• Always use environment variables or a secure configuration manager for API keys
• Implement proper error handling for blockchain operations
• Use the batch operations when processing multiple consents
• Regularly verify blockchain fingerprints for critical agreements