TokenizationGovernor API

The TokenizationGovernor is the primary entry point for all RWA tokenization governance operations. It coordinates the jurisdiction registry, compliance engine, credential issuance, and governance chain.

Initialization

from trusthub.rwa import TokenizationGovernor
from trusthub.crypto.signing import PQCSigner
from trusthub.constants import MLDSALevel
from trusthub import LedgerStore

signer = PQCSigner(MLDSALevel.LEVEL_3)
keypair = signer.generate_keypair()
ledger = LedgerStore("ledger.db")

governor = TokenizationGovernor(signer=signer, ledger=ledger)

Jurisdiction Registry

# Register a jurisdiction
governor.registry.register({
    "jurisdiction_id": "KE",
    "name": "Kenya",
    "regulatory_body": "Capital Markets Authority",
    "frameworks": ["Capital Markets Act"],
    "credential_types": ["PropertyOwnership", "RegulatoryAttestation"],
    "transfer_requirements": ["kyc", "aml", "title_verification"],
})

# Establish bilateral trust between jurisdictions
governor.registry.establish_trust(source="KE", target="AE-AZ")

# List registered jurisdictions
jurisdictions = governor.registry.list_jurisdictions()

# Get jurisdiction details
jurisdiction = governor.registry.get("KE")

# Check trust relationship
is_trusted = governor.registry.is_trusted(source="KE", target="AE-AZ")

Property Credentials

# Issue a property credential (PQC-signed)
credential = governor.issue_property_credential(
    jurisdiction="KE",
    owner_did="did:trusthub:acme:owner123",
    property_data={
        "address": "Westlands, Nairobi",
        "type": "commercial",
        "value_usd": 250_000,
        "title_deed": "LR-2024-00451",
    },
)
# Returns: PropertyCredential with .id, .jurisdiction, .owner_did, .claims, .signature

Regulatory Attestations

# Submit an attestation from a regulatory body
attestation = governor.submit_attestation(
    jurisdiction="KE",
    credential_id=credential.id,
    attestation_type="regulatory_clearance",
    body="Capital Markets Authority",
    claims={"kyc": "passed", "aml": "cleared", "encumbrances": "none"},
)
# Returns: Attestation with .id, .jurisdiction, .credential_id, .body, .claims

Tokenization

# Tokenize an asset
result = governor.tokenize(
    credential_id=credential.id,
    token_standard="ERC-3643",     # or "ERC-1400", "ERC-3525"
    partitions=4,                   # number of fractional tokens
    metadata={"chain": "polygon"},  # optional metadata
)
# Returns: TokenizationResult with .token_id, .credential_id, .partitions, .standard

Cross-Border Transfers

# Request a cross-border transfer (triggers compliance evaluation)
transfer = governor.request_transfer(
    token_id=result.token_id,
    from_jurisdiction="KE",
    to_jurisdiction="AE-AZ",
    recipient_did="did:trusthub:globex:investor456",
    amount=1,                       # number of partitions to transfer
)
# Returns: TransferResult with .transfer_id, .status, .proof_id, .compliance_details

# Status is one of: "approved", "denied", "pending_attestation"
# If approved, .proof_id points to the compliance proof

Compliance Proofs

# Retrieve a compliance proof by ID
proof = governor.get_compliance_proof(proof_id=transfer.proof_id)
# Returns: ComplianceProof with .proof_id, .jurisdictions, .requirements, .result, .signature

# proof.requirements: list of evaluated requirements per jurisdiction
# proof.result: "pass" or "fail"
# proof.signature: PQC signature over the proof payload

Governance Chain Verification

# Verify the full governance chain integrity (hash-chain + signatures)
is_valid = governor.verify_governance_chain()
# Returns: bool

# Get governance history for a specific asset
history = governor.get_asset_history(token_id=result.token_id)
# Returns: list of GovernanceEvent entries

Supporting Classes

JurisdictionRegistry

from trusthub.rwa import JurisdictionRegistry

registry = JurisdictionRegistry()
registry.register(config)
registry.establish_trust(source, target)
registry.revoke_trust(source, target)
jurisdictions = registry.list_jurisdictions()
jurisdiction = registry.get(jurisdiction_id)
is_trusted = registry.is_trusted(source, target)

ComplianceEngine

from trusthub.rwa import ComplianceEngine

engine = ComplianceEngine(registry=registry, signer=signer)

# Evaluate a transfer against multi-jurisdictional policies
evaluation = engine.evaluate_transfer(
    from_jurisdiction="KE",
    to_jurisdiction="AE-AZ",
    credential=credential,
    attestations=attestations,
)
# evaluation.decision: "approved" | "denied"
# evaluation.proof: ComplianceProof (if approved)
# evaluation.missing_requirements: list (if denied)

RWAStore

from trusthub.rwa import RWAStore

store = RWAStore("rwa.db")
store.store_credential(credential)
store.store_attestation(attestation)
store.store_token(token_result)
store.store_transfer(transfer)
store.store_proof(proof)

# Query
credentials = store.get_credentials(jurisdiction="KE")
tokens = store.get_tokens(credential_id=credential.id)
transfers = store.get_transfers(token_id=token_id, status="approved")
history = store.get_governance_chain(token_id=token_id)