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

Architecture

The OConsent platform employs a layered architecture consisting of:

Components

OConsent Architecture Diagram

Core Components

Consent Manager

The heart of the platform responsible for:

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:

Privacy Features

Zero-Knowledge Proofs

Implementation of Zk-SNARKs for:

Surrogate IDs

Primary ID Surrogate ID Purpose
7a2a83b1694940f38d6a 2C9006E4F5562E09295 Marketing

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:

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