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
- Data Controller initiates consent request
- Agreement template is generated
- Data Subject reviews and signs
- Trusted timestamp is applied
- 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
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:
- 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