Receiz / Identity Primitive Standard

Identity

Profile, proof, ownership, payment routing, analytics, and public presence resolve under one root.

Your managed profile is the signed workspace. `/<username>` is the canonical public surface. Live Twin, policy, settlement routing, and outward surfaces resolve from this primitive.

CanonicalSession-rootedPublic projectionAPI contract
Authority statement

Identity in Receiz is the canonical state machine for the managed workspace, the public projection (`/<username>`), proof-aware originals, and policy-controlled distribution.

How It WorksUser InstructionsAnalytics DepthDeveloper StandardWhat This Becomes

Two canonical surfaces

Your managed profile is the signed-in identity workspace. `/<username>` is the public projection of that identity.

  • First entry into the managed profile auto-provisions an identity record for the signed-in session.
  • Public identity is always username-canonical and resolved server-side.
  • Legacy /u/[username] normalizes into the canonical /[username] surface.

Deterministic identity constraints

Identity naming, privacy, and profile data are bounded by strict validation and predictable fallbacks.

  • Usernames must satisfy ^[a-z0-9_]{3,24}$ and are normalized to lowercase.
  • Reserved namespace prevents route collision with system pages.
  • Private profiles hide non-owner details while preserving owner manage access.

Evidence-native profile media

Avatar/banner updates are not cosmetic-only uploads; each image is processed, stored, and minted into a verifiable Receiz record.

  • Images are normalized to WebP and size-bounded before publish.
  • Media minting issues verify path + anchor ID tied to profile update.
  • The identity surface can carry sealed originals, not just text metadata.

Ownership + witness graph

Identity is social and operational: follows, showcased originals, download policies, and witnessed analytics are all first-class state.

  • Originals can be creator-owned or verified-owned with explicit showcase visibility.
  • Verified-owned showcase requires authorship entitlement (Authorship/Automation).
  • Witnessed duration and activity rollups feed real profile authority metrics.

Proof-bound commerce and derivatives

Paid access and derivative flows are anchored to challenge/confirm state and deterministic profile-original download policy.

  • Checkout and receiz challenge-confirm paths bind buyer, owner, amount, and receiz ID before release.
  • Image-variant and video-poster generation are first-class identity media operations.
  • Public originals listing supports policy-filtered pagination for profile storefront behavior.
Execution Model

How managed profile identity operates

Route, policy, and proof behaviors reflected directly from runtime + API code paths.

Route flow contract

  1. Your managed profile requires an authenticated session. Anonymous users continue through sign-in with return continuation.
  2. Session entry calls ensureUserProfileForSession, guaranteeing profile row existence before render.
  3. Public route `/<username>` resolves normalized username and loads viewer-aware projection.
  4. Private profiles return owner-only detail while preserving public route boundaries.

Identity state assembly

  1. Profile root data loads from `user_profiles` with normalized social/contact fields.
  2. Follow relationship is resolved to connection state (`self`, `mutual`, `following`, `follower`, `none`).
  3. Originals merge creator-owned records and verified-owned collected records.
  4. Anchor metadata resolves claim hash, media envelope, context preset, and download policy flags.
  5. Proof state resolves Groth16 digest and Poseidon hash through zk cache/API pathways.
  6. Visibility policy is applied per receiz ID and ownership key, then filtered for public projection.
  7. Witness metrics are rolled from analytics and realtime witnessed duration rollups.
User Instruction

Runbook for profile identity operators

The shortest path to a trusted, policy-controlled public identity surface.

1. Open your managed profile to establish your identity root

If you are signed out, Receiz continues through sign-in and lands you back in the managed workspace. After sign-in, identity is guaranteed server-side before the profile UI renders.

2. Lock in a canonical username

Use lowercase + underscores only. Availability checks are live through `/api/profile/username/availability`, and conflicts are rejected before commit.

3. Seal visual identity (avatar/banner)

Upload media through profile controls. Receiz processes the image, stores it, and mints verification metadata so profile media has audit-grade provenance.

4. Publish originals with explicit visibility policy

Each original carries ownership class (`creator` or `verified`), proof state, and show/hide controls. Visibility updates are persisted per receiz ID.

5. Configure collection access and value

Original and derivative download rights, limits, release locks, and optional paid checkout are enforced via profile-original APIs.

6. Deploy identity from `/<username>`

Your deployable surface projects deterministic identity + proof-backed originals + witness metrics, with follow graph and analytics continuity.

Analytics Depth

Robust analytics: what profile operators actually get

Identity includes a full analytics stack: event capture, witness depth, conversion math, attribution, and timelines.

Overview windows

Core profile activity is tracked across all-time + rolling 90d/30d/7d/24h windows for every top-level metric.

  • Profile views, original views, opens, unique visitors.
  • Streams, stream completions, download clicks, successful downloads.
  • Checkout starts, checkout paid, paid downloads, revenue, unique buyers.

Witness + stream depth

Listening/viewing depth is modeled, not just click counts, through duration capture and witnessed rollups.

  • Stream play/pause/complete events support completion-rate and avg-listen metrics.
  • Detail-view + stream duration contribute to witnessed time authority.
  • Rollups maintain total_view_ms and total_stream_ms for stable profile stats.

Commerce intelligence

Download and paid checkout analytics are directly connected to profile original access and revenue outcomes.

  • Tracks checkout starts, paid checkout events, paid download totals and revenue.
  • Computes checkout→paid and paid-download-to-stream-play conversion rates.
  • Separates attributed and unattributed revenue in traffic attribution output.

Traffic attribution

Attribution is aggregated by source, referrer, and path with conversion-rate fields for each bucket.

  • Each bucket includes views, opens, streams, downloads, checkout starts, paid, revenue.
  • Unique visitor counting and last-event timestamps are retained per traffic key.
  • Supports channel-level optimization instead of raw totals only.

Tracked event contract

Event taxonomy is typed and scope-classified (`profile`, `original`, `stream`, `commerce`) before storage.

profile_viewprofile_analytics_viewprofile_link_copyprofile_follow_toggleoriginal_impressionoriginal_openoriginal_detail_vieworiginal_download_clickoriginal_download_successoriginal_checkout_startoriginal_checkout_paidoriginal_stream_playoriginal_stream_pauseoriginal_stream_complete

Windows + timeline ranges

  • Every key overview metric includes `all`, `d90`, `d30`, `d7`, `d1` windows.
  • Timeline outputs support `30m, 6h, 24h, 7d, 30d, 90d, 1y, 3y` ranges for short-term and long-horizon analysis.
  • Profile Analytics renders these ranges with interactive chart switching.

User-facing analytics surfaces

  • Managed profile inline stats (followers, witnesses, streams, views, completion, witnessed seconds) with periodic and realtime refresh hooks.
  • Profile Analytics gives owners the full console for funnel, top originals, traffic intelligence, and multi-range charts.
  • Per-original detail viewer instrumentation for impressions, opens, stream actions, download clicks, and paid flow transitions.
Open Profile Analytics

Developer instrumentation notes

  • Ingestion endpoint: `POST /api/profile/analytics/track` with strict event-name validation and bounded payload fields.
  • Client helper: `trackProfileAnalyticsEventClient(...)` uses sendBeacon/fetch fallback and session dedupe via `oncePerSessionKey`.
  • Server aggregation: `loadProfileAnalyticsForOwner(...)` computes overview, stream, commerce, funnel, traffic, timelines, originals, recent activity.
  • Schema support: `user_profile_analytics_events` plus `user_profile_witnessed_rollups` trigger-based duration aggregation.
  • Realtime publication exists for analytics events and witnessed rollups to support live profile stat freshness.

Analytics snapshot shape (owner context)

{
  "overview": {
    "profileViews": { "all": 0, "d90": 0, "d30": 0, "d7": 0, "d1": 0 },
    "streamPlays": { "all": 0, "d90": 0, "d30": 0, "d7": 0, "d1": 0 },
    "checkoutPaid": { "all": 0, "d90": 0, "d30": 0, "d7": 0, "d1": 0 }
  },
  "stream": {
    "totalListenSeconds": 0,
    "avgListenSecondsPerPlay": null,
    "completionRate": null
  },
  "commerce": {
    "lifetimeRevenueCents": 0,
    "checkoutToPaidRate": null
  },
  "funnel": {
    "viewsToOpenRate": null,
    "openToPlayRate": null,
    "playToDownloadRate": null,
    "checkoutToPaidRate": null
  },
  "traffic": {
    "sources": [],
    "referrers": [],
    "paths": [],
    "attributedRevenueCents": 0,
    "unattributedRevenueCents": 0
  },
  "timelines": {
    "30m": [],
    "6h": [],
    "24h": [],
    "7d": [],
    "30d": [],
    "90d": [],
    "1y": [],
    "3y": []
  },
  "originals": [],
  "recentActivity": []
}
Developer Instruction

Implementation standard and API contract

Everything required to integrate, validate, and reason about profile identity behavior.

Data model primitives

user_profiles

Identity root: username, display metadata, privacy state, profile-picture/banner URLs, timestamps. Username is unique and format constrained.

user_profile_follows

Directed witness graph: follower_user_id -> following_user_id with anti-self-follow constraint and indexed traversal.

user_profile_original_visibility

Explicit profile showcase policy per (user_id, receiz_id); used for owner toggles and public filtering.

user_profile_analytics_events

Event stream for profile/original/stream/commerce activity; bounded payload fields and typed event-name contract.

user_profile_witnessed_rollups

Realtime witness aggregates (view_ms, stream_ms) maintained via trigger logic for durable profile authority metrics.

Hard constraints to enforce

  • Username contract: ^[a-z0-9_]{3,24}$, lowercase canonicalization, reserved-word rejection.
  • Profile patch fields are length-bounded and URL-normalized to http/https only.
  • Media + original flows verify content size and SHA-256 before durable publish paths.
  • Visibility updates enforce ownership checks and entitlement checks for verified-owned showcase.
  • Paid downloads require verified Stripe checkout session metadata binding before byte release.
  • Receiz challenge-confirm purchase flow cryptographically binds buyer intent before paid release execution.
  • Derivative media generation (image variants/posters) is size-bounded, validated, and policy-controlled.
  • Analytics ingestion validates event enum and bounds payload fields for stable rollup quality.
GETSession
/api/profile/me

Load caller profile + resolved profilePath.

PATCHSession
/api/profile/me

Update profile fields (username, bio, links, privacy, profile-picture/banner URLs).

GETPublic
/api/profile/:username

Resolve profile view state for any username (manage mode for owner).

GETPublic
/api/profile/:username/originals

Paginated public/manage listing of profile originals with visibility policy filtering.

POSTSession
/api/profile/:username/follow

Follow target profile and return updated relationship state.

DELETESession
/api/profile/:username/follow

Unfollow target profile and return updated relationship state.

GETPublic
/api/profile/username/availability

Validate and suggest canonical username alternatives.

POSTSession
/api/profile/me/media

Upload/process profile picture or banner, mint media Receiz, update profile URL.

PATCHSession
/api/profile/originals/visibility

Set public showcase state for an original (ownership + entitlement enforced).

POSTSession
/api/profile/originals/upload

Multipart original upload with SHA-256 verification.

POSTSession
/api/profile/originals/upload-signed

Initialize signed-upload flow for large originals.

POSTSession
/api/profile/originals/seal

Seal uploaded original into verifiable artifact and return verify path.

POSTPublic
/api/profile/originals/download/checkout

Create embedded Stripe checkout for paid original/derivative access.

POSTSession
/api/profile/originals/download/receiz/challenge

Create PresenceBound challenge for paid original/derivative release authorization.

POSTSession
/api/profile/originals/download/receiz/confirm

Verify PresenceBound assertion and commit paid download release settlement.

GETPublic
/api/profile/originals/download

Authorize and stream original/derivative/moment-record download with limits + payment checks.

POSTSession
/api/profile/originals/image-variants

Generate bounded image variants for profile originals and update derivative metadata.

POSTSession
/api/profile/originals/image-variants/backfill

Backfill missing derivative image variants for already-published originals.

POSTSession
/api/profile/originals/video-poster

Persist verified video-poster frames and derivative variants for video originals.

POSTPublic
/api/profile/analytics/track

Best-effort ingestion of profile analytics events with typed event validation.

Example: profile mutation

PATCH /api/profile/me
content-type: application/json

{
  "username": "operator_prime",
  "displayName": "Operator Prime",
  "bio": "Canonical issuer profile",
  "websiteUrl": "https://example.org",
  "socialXUrl": "https://x.com/operator_prime",
  "isPrivate": false
}

Example: analytics event

POST /api/profile/analytics/track
content-type: application/json

{
  "username": "operator_prime",
  "event": "original_open",
  "receizId": "00000000-0000-0000-0000-000000000000",
  "source": "profile_public_page",
  "durationSeconds": 12.4,
  "meta": {
    "ownershipKind": "creator",
    "layout": "single"
  }
}
Strategic Outcome

What this identity primitive becomes

A canonical identity primitive that can publish proof, carry public presence, and hold commercial and institutional state.

Public identity with proof attached

One username route can carry authored identity, proof-linked artifacts, and witness feedback loops without losing authority.

Source-of-record provenance

Identity and originals stay linked at the claim and proof boundary, making source of record defensible instead of performative.

Policy-native commerce

Download rights, release locks, limits, and paid checkout become governed policy objects instead of ad-hoc operator decisions.

Institutional identity standard

Teams can treat identity as a standard interface for evidence publication, audit traceability, and controlled public presence.