# Network-Derived Recommendations PRD **Status:** Draft for implementation **Last updated:** 2026-04-16 **Priority:** P1 — committed for post-launch delivery --- ## 1) Purpose The Guild is already wired into the Serendipity Network for **emission** — every user signup, referral, and settled commission is published as a canonical v3 event into the portfolio-wide trust graph. This PRD specifies the **read-side** of that integration: how a marketplace operator consumes network-derived signals to improve user acquisition quality, reward calibration, and fraud posture on their own platform. Today Guild is half-duplex with the network (write-only). This PRD makes it full-duplex. --- ## 2) Scope ### In scope - Add `@platform/sdk` to `apps/backend` for graph-read capability - Tenant-scoped query endpoints that expose network signals for *users of that tenant*: - `GET /v1/network/users/:tenant_user_id/signals` — trust context for a specific user - `GET /v1/network/users/:tenant_user_id/recommendations` — candidates similar to high-value users on this tenant - `GET /v1/network/reputation-score/:tenant_user_id` — a scalar network reputation (0–100) - Access control: a tenant can only query users that resolve to a `global_user_id` linked to their own tenant - Network-aware bonus multiplier (opt-in): operators can set starting token velocity for new signups based on the user's network reputation - Guild ops console surfaces network context inline on the user detail view ### Out of scope for v1 of this subsystem - Direct Cypher / arbitrary graph queries (SDK wraps a fixed, safe query surface) - Cross-tenant user enumeration ("show me all users on the network" — never) - Billing (included in the standard 9% protocol fee at v1) - Real-time subscriptions (poll/pull only at v1; push is a future item) --- ## 3) Why now Three pressures converge: 1. **Portfolio growth compounds read-side value.** Every additional marketplace in the portfolio is another source of trust signal. Early contributors benefit first. 2. **Operators ask for it.** The most common question after "how does the economics work" is "what do I get from being part of a network of marketplaces?" Today the honest answer is *identity resolution and anti-fraud signal contribution*. That's true but thin. 3. **Technical prerequisites are done.** Emission is live (`service-hub.ts`, `service-referral-events.ts`, `hub-outbox.ts`). Identity resolution is live. Adding `@platform/sdk` is incremental, not architectural. --- ## 4) Detailed API surface ### 4.1 Trust-context lookup ```http GET /v1/network/users/:tenant_user_id/signals Authorization: Bearer 200 OK { "global_user_id": "gu_abc123", "first_seen_network": "2026-02-11T00:00:00Z", "marketplaces_participated": 3, "total_settlement_count": 47, "cross_marketplace_referrer": true, "known_negative_signals": false, "anchor_density": "moderate" } ``` Returned fields are **aggregate, non-identifying**. No marketplace names, no amounts, no user IDs from other tenants. ### 4.2 Recommendations ```http GET /v1/network/users/:tenant_user_id/recommendations?limit=20 Authorization: Bearer 200 OK { "recommendations": [ { "candidate_tenant_user_id": "tu_...", "similarity_score": 0.87, "rationale": "referred_by_same_person" }, ... ] } ``` Only includes candidates that are already resolvable to *this tenant* (users on your marketplace). The network does not surface users from other marketplaces. ### 4.3 Reputation score ```http GET /v1/network/reputation-score/:tenant_user_id Authorization: Bearer 200 OK { "score": 72, "confidence": "high", "factors": ["multi_marketplace_active", "clean_fraud_history", "sustained_activity"] } ``` Used by the optional network-aware bonus multiplier (see §5). --- ## 5) Network-aware bonus multiplier (opt-in) Today every new signup gets a fixed `2x` first-transaction bonus multiplier (see `launch-readiness.md`). With this PRD shipped, an operator can opt into scaling that starting multiplier by the user's network reputation score. - Operator opts in via a tenant config flag: `network_aware_bonus_multiplier_enabled=true` - When a user links (`POST /v1/users/link`), Guild resolves their `global_user_id` and fetches their reputation score - Starting token velocity scales from `1.0x` (no history, score < 20) to `3.0x` (score ≥ 80) - Operator can cap the ceiling per tenant (default cap: `2.5x`) Off by default. Operators who prefer the uniform `2x` posture keep it. --- ## 6) Privacy, consent, and data boundary This is the gating design constraint, not a footnote. - **Access is always tenant-scoped.** A tenant API key can only query users resolvable to a `global_user_id` that links to their own tenant. Cross-tenant lookup is impossible via this API. - **Returned data is aggregate / structural, never raw.** Callers see *that* a user participates on multiple marketplaces, not *which* ones or *for what amounts*. - **No PII leaks.** Phone, email, and internal IDs from other tenants are never returned. - **Consent basis:** all network signals were emitted under `consent_basis: "first_party"` by the originating marketplace at their own signup flow. Consumption preserves that basis. - **Audit:** every network read is logged with tenant ID, requester API key, and queried `global_user_id`, retained 90 days. - **Operator privacy-policy disclosure:** operators using this PRD's endpoints must update their privacy policy to disclose participation in network-derived trust signals. Doc template to be shipped with the subsystem. --- ## 7) Dependencies - `@platform/sdk` added to `apps/backend/package.json` - `GRAPH_API_URL` and `GRAPH_API_TOKEN` added to env/secrets - Serendipity graph API available at required version (coordinate with platform team) - Tenant API key middleware extended with network-read scope --- ## 8) Rollout 1. **Silent backend ship** — endpoints live behind a feature flag, callable only by Guild ops for internal validation 2. **Design-partner cohort** (2–3 tenants) — enable per-tenant, gather feedback, iterate on the signal shape 3. **General availability** — on for all tenants; optional features (network-aware multiplier) remain opt-in 4. **Docs & messaging** — update `docs/operator/network-participation.md` from "coming" to "available," update homepage --- ## 9) Success metrics - ≥60% of active tenants enable at least one network-read endpoint within 90 days of GA - ≥3 production use cases documented by tenants (anti-fraud, onboarding personalization, rewards calibration) - Zero cross-tenant data leaks confirmed by audit - Latency ≤ 150ms p99 for signal / reputation-score endpoints --- ## 10) Non-goals (restated for clarity) - Guild does **not** become a data broker. Network reads return aggregate trust context, not mineable PII. - Guild does **not** expose arbitrary graph traversal to tenants. Fixed, safe query surface only. - Guild does **not** force operators to integrate network reads — the baseline `/v1/users/link` + `/v1/transactions` flow is unchanged. --- ## 11) Open questions - Should reputation-score calculation be documented publicly, or treated as a proprietary signal? (leaning: publish the factor list, keep the weighting private) - Pricing: include in 9% protocol fee indefinitely, or introduce a premium tier post-v1? (leaning: indefinite inclusion; revisit only if cost structure forces it) - Should high-reputation users be able to see their own score on the wallet page? (leaning: yes, post-GA, as a transparency feature)