analysis: Bridge customer model for multi-space scenarios — design and implications

[rozagerardo]

Bridge deduplicates customers by email — the same email always returns the same customerId. This means two Spaces using the same contact email are silently linked to the same Bridge customer. This is already an implicit reality in the current model (our existing_kyc_link handler adopts whatever Bridge has for that email). This issue is to analyze whether multi-space customer sharing should be intentionally supported, and if so, how to design it properly.

Questions to answer

• Legitimacy: when is sharing a Bridge customer across Spaces intentional (e.g. a legal entity running multiple Spaces — Hypha's own Spaces) vs. accidental or malicious?
• Virtual account isolation: Bridge VAs are provisioned per (customer, currency, destination_address) — since each Space has its own executor contract as destination, VAs are already Space-specific even when the customer is shared. Does this give us sufficient separation?
• Transaction labeling: if two Spaces share a customer, how do we attribute incoming transfers to the correct Space? Bridge's transfer records are tied to the customer, not to a specific VA destination. Does Bridge expose any labeling or metadata we can use?
• Schema implications: the current bank_customers table is unique on (space_id, provider) — a shared customer means multiple rows with the same provider_customer_id. Is that the right model, or should we normalize with a separate bridge_customers table and a join?
• KYB re-use: if Space A completes KYB and Space B reuses the same email, does Space B get KYB for free? Is that legitimate (same legal entity) or a gap? Relates to Issue 1 (email-ownership gate).
• Admin UX: should a Space admin be able to explicitly say "use our existing Bridge customer" rather than starting a new KYB flow? What's the confirmation/authorization model?

Areas to investigate

• Bridge API behavior when the same customerId is used with different destination addresses for VAs
• Whether Bridge supports any per-transfer or per-VA metadata/labels for attribution
• Whether Bridge's compliance model allows one customer to back multiple unrelated entities
• Current schema constraints and what changes would be needed to support the shared-customer model cleanly

Output

A design decision and, if multi-space sharing is to be supported, a data model and UX flow proposal — to be implemented as a follow-up issue.