Referral Communication Architecture

1) Why does the ecosystem need referral connections

• predictability of attributions and payouts;
• onboarding and partner scaling speed;
• security/privacy (PII-minimization, RG-guardrails);
• economy (fair split, Cost-to-Serve, ROI channels).

2) Referral linkage models

2. 1 By depth

Single-level (L1): Primary referrer's reward for the target event (FTD/deposit/mission activation).
Multilevel (L2 +): payout shares go up the referral tree; the level/cap/commission limit applies.
Hybrid: L1 fix + a small "thin tail" along L2.

2. 2 By influence carrier

Affiliate/media (networks, publishers, streamers).
User-to-User (referral codes/links of players).
Co-brand/B2B (partner brands/operators, cross-chain crossings).

2. 3 By exchange topology

Hub & Spoke: a single center of attribution and postbacks is an easier conformance.
Mesh (federation): direct connections between chains - requires a strict canon of events and signatures.
Layer-to-Layer: media → offer → payments/CUS → game (clear domains and gateways).

3) Ontology and identifiers

3. 1 Key entities

`referrerId`, `referralId`, `playerId` (псевдоним), `affiliateId`, `campaignId`, `offerId`, `routeId`, `operatorId`, `providerId`, `traceId`.

3. 2 Connectivity and privacy

PII is stored in safe zones, in exchange - only tokens/pseudonyms.
Link click to event: 'traceId' stretches from click/link to registration/deposit/game.
TTL/expiry for refcode tokens; protection against re-binding of devices.

4) Event model and data contracts

4. 1 Minimum set of events

`ref_click`, `deep_link_open`, `session_start`, `registration`, `kyc_status`, `deposit`, `ftd`, `bet/spin`, `mission_progress`, `reward_granted`, `ref_postback_received`, `fraud_signal`.

4. 2 Event requirements

Semantic versions of schemas (Schema Registry), required fields and allowed values.
Idempotency via 'eventId' + deduplication window (± 5 min).
Time zones - UTC/ISO-8601, all amounts and currencies with 'currency'.

5) Protocols: links, diplinks, SmartLink, postbacks

5. 1 Generation of ref-links

Parameters: 'rid' (referrer), 'cid' (campaign), 'oid' (offer), 'sub1.. sub5', 'utm _', 'traceId'.
Parameter signature (JWS/HMAC), TTL, spoofing protection ('kid', 'timestamp').

5. 2 SmartLink/Deep Link

SmartLink redirects to geo/jurisdiction/device/SLO status of payment routes.
Deep Link leads to a specific game/landing/mission (availability check by region/license).

5. 3 Postbecks (S2S)

Signed webhooks: 'signature', 'eventId', 'timestamp', 'rid/cid/oid', 'traceId'.
Retrai with jitter and backoff; register for replay; cursor history upload.

6) Attribution and collisions

6. 1 Attribution rules

Last optional touch with windows by jurisdiction and channel.
Cross-device stitching through agreed tokens/fingerprints (without raw PII).
With multi-stage routes - deposit weights (see splits below).

6. 2 Collision resolution

The priority of the user's direct referral over the media click if the L1 window is active.
Fraud/invalid: marks "disputed," payment hold before reconciliation.

7) Antifraud and quality of referral traffic

Signals: device farm, unnatural CTR/CR, quick click/registration cycles, geo/ASN mismatch, brand-bidding, stimulating traffic under the guise of content.
Actions: auto-cooling, link/offer pause, key revocation, blacklist of sites, re-verification of the referrer.
Scorecard quality: LTV/FTD, retention, chargeback/bonus-abuse, accuracy/timeliness of postbacks.

8) Calculation of payments and splits

8. 1 Basic models

CPA/CPL (fixed per event, e.g. FTD/registration).
RevShare (Net Revenue share by window).
Hybrid (fix + share).
Multilevel split (L1/L2... with mouthguards/rapids).

8. 2 Formulas (simplified)

[
share_i=\frac{W_i \cdot Q_i}{\sum_j W_j \cdot Q_j}
]

where (W_i) is the step weight (L1> L2... or according to the channel contribution model), (Q_i) - quality factor (delivery SLI, postback accuracy, absence of fraud/RG flags).

[
payout_i = share_i \times (Base\ Reward \ \text{или} \ Net\ Revenue \times rate) \times Adjustments
]

'Adjustments': credits/penalties for SLOs, deductions for controversial cases, RG/sanction adjustments.

8. 3 Restrictions and mouth guards

Quarterly/monthly limits; minimum payout; hold on the review of controversial events; slices by jurisdiction and payment status.

9) Security, privacy and RG

Zero Trust: mTLS for S2S, short-lived tokens, egress-allow-list.
PII minimization: in ref traffic - only tokens/pseudonyms; detoxification strictly in safe zones.
RG-guardrails: intensity constraints on vulnerable segments; mandatory disclaimers; prohibition of offers in prohibited regions.
DPA/DPIA and localization: storage and processing by jurisdiction, prohibition of cross-border PD export outside the rules.

10) Dashboards and observability

10. 1 Referral/Affiliate Panel

Clicks, registrations, KYC, FTD, deposits, CR/ARPU/LTV, postback statuses, splits and expected payouts, caps/quotas.

10. 2 Ecosystem panel

Linkage map (referrer→referal), cohorts, proportion disputed, RG/sanction fouls, MTTR by incident, channel/circuit contribution.

10. 3 SLO

Postback delivery ≥ 99. 9% (p95 ≤ 1-2 s), bus lag ≤ 200-500 ms, panel render p95 ≤ 1. 5–2. 0 s, trace coverage ≥ 95% of paths.

11) Governance и RACI

12) Operational processes

12. 1 Onboarding referrer

KYP/KYB, traffic sources, jurisdictions, brand guide, RG agreement.
Issuance of keys/API/webhooks; sandbox and conformance tests of signatures/idempotency.

12. 2 Changes/Releases

Change-calendar (green/yellow/red windows), progressive inclusions (1%→5%→25%→100%), guardrails and auto-rollback.

12. 3 Incidents/war-room

P1/P2, stop buttons (traffic/offer/route), SLA for a 60-90 s trace packet, RCA "no blame."

12. 4 Reconciliation and payments

Cursor uploads, reconciliation of event hashes, acts/invoices, NET7/14/30, holds (fraud/chargeback/bonus abuse), FX courses.

13) Integration with the rest of the ecosystem

Payments/AWS: quotas and cut-over for CR/P95 degradation.
KYC/AML: pass-rate and SLA stages; fast-track for low-risk.
Content/Missions: Diplinks to Games/Tournaments with RTP/Volatility and Regional Constraint Checks.
Analytics/ML: propensity models, ranking of offers, anti-fraud signals.

14) Anti-patterns

"Postback Zoo": different formats/signatures/windows → doubles, losses, disputes.
Offset pagination of event history under load → holes/duplicates (cursors only).
Retrai without jitter/limits → storm and double accruals.
PII in ref events → leaks and violations.
Unlimited multilevel tails → toxic economy, inability to control.
Single SPOF redirect without N + 1/health-flip.
There is no traceId → attribution cannot be proved.

15) Checklists

15. 1 Engineering

• Ontology and Schema Registry (versions, required fields).
• Postback and Signature Contracts (JWS/HMAC), Deduplication window.
• SmartLink/Deep Link generator, TTL and parameter protection.
• Attribution: rule, windows, collision priorities, cross-device stitching.
• Pay and split models, caps/limits, deductions.
• Zero Trust, tokenization, DPIA/DPA, RG-guardrails.
• dashboards/scorecards and SLO, alerts and war-room.

15. 2 Launch

• Sandbox/conformance, test events and reconciliation.
• Progressive release, auto-rollback.
• Reconciliation and Invoice Pipeline are configured.

15. 3 Operation

• Weekly scorecards of quality and SLO.
• Review of controversial/hold cases.
• Periodic RCAs and rule updates.

16) Maturity Roadmap

v1 (Foundation): a single canon of events/postbacks, SmartLink, L1 model, basic dashboards.
v2 (Integration): cross-chain refs, cursor cues, hybrid payouts, scorecards, and auto-cool.
v3 (Automation): ML-ranking of offers, predictive cut-over payments/CCP, auto-guardrails by SLI/RG.
v4 (Networked): federated attribution between networks, collective missions/tournaments, split DAO rules.

17) Success metrics

Business: uplift FTD/ARPU/LTV from ref channels, CAC/payback, share of quality sources.
Quality: accuracy/timeliness of postbacks, controversy <X%, holds/chargebacks.
Technique: p95 redirects and postbacks, lag tires, MTTR by incident.
Compliance/RG: PD incidents = 0, jurisdictional compliance, RG triggers/1k active.
Economy: Cost-to-Serve (per rps/txn/event), credits/penalties, ROI channels.

Brief summary

Referral communication architecture is ID and event standards, SmartLink/diplinks and signed postbacks, honest attribution, strict privacy and RG, plus transparent split economics and observability. Build a canon and SLO, automate guardrails and reconciliation - and the referral circuit will become a scalable, safe and profitable foundation for the entire ecosystem.