KYC And Private Sharing

TREA contracts can make compliance decisions without receiving documents, personal data, or validator-only evidence. The ledger stores a minimal public KYC state, and detailed disclosure happens through a private validator channel authorized by the wallet.

This split is deliberate:

• contracts read deterministic public facts from the ledger snapshot;
• validators and consumer servers exchange detailed KYC only off-chain;
• wallet signatures authorize any private disclosure;
• block replay never depends on HTTP, validator availability, or mutable

external state.

Public Contract Surface

Contracts use ctx.kyc_* intrinsics. These calls are deterministic during execution because they read the KYC snapshot available to the runtime.

@tx
def transfer(to: Address, amount: u128):
    require(ctx.kyc_verified(ctx.caller), "sender_not_verified")
    require(ctx.kyc_compat(ctx.caller, "kyb-v1"), "sender_schema")
    require(ctx.kyc_level(ctx.caller) >= KycLevel.Verified, "level")

The public surface is intentionally small:

| Intrinsic | Return | Purpose | |-----------|--------|---------| | ctx.kyc_verified(account) | bool | True when the account has active, non-revoked KYC | | ctx.kyc_level(account) | KycLevel | Comparable level for policy checks | | ctx.kyc_compat(account, schema) | bool | Checks schema compatibility such as cpf-v2 satisfying cpf-v1 | | ctx.kyc_verifier(account) | Address | Verifier address that registered the public status | | ctx.kyc_expires_at(account) | u64 | Expiration timestamp, or 0 for no published expiration |

The contract never receives the KYC file, provider evidence, document number, or private payload. If a contract needs a stronger policy, it should check the published level, verifier, schema compatibility, or expiration.

Public KYC State

The public record is designed to be useful but not sensitive:

subject_kind
subject
verified
level
schema
compatible_with
credential_id
issued_at
expires_at
revoked

credential_id is opaque. It is an anchor for revocation and private sharing; it is not a credential payload.

Private KYC Sharing

When a bank, fintech, issuer, or other consumer needs detailed KYC for its own regulated server, the flow is:

consumer server -> KycShareRequest
wallet          -> reviews purpose/profile/expiry and signs KycShareGrant
consumer server -> POST /api/kyc/grant/redeem
validator       -> verifies grant, authenticates consumer, returns profile privately

The redeem endpoint validates:

• wallet signature over the grant;
• grant expiration;
• consumer authentication and audience binding;
• nonce anti-replay;
• credential existence and revocation state;
• requested disclosure profile.

Disclosure profiles keep the contract model unchanged. A status-only profile can reveal only level/status, while a regulated profile can return a retained copy to the consumer server when legally required.

What Not To Do

Do not put KYC documents, selfies, proof images, raw provider payloads, or bank records into TREA storage or events. That pollutes the chain, increases exposure, and adds no deterministic value to contract execution.

Use the public KYC state for contract enforcement. Use wallet-authorized private sharing for detailed consumer onboarding.