Lure

Onboarding through invite links

1 Introduction

While sending invitations on the network provides a path to grow a group membership, it does not accommodate sending an invitation to someone who does not yet own an urbit identity.

Tlon Lure service is designed to fill this gap, and enables, effectively, associating group invitations with their corresponding web link. Upon redemption, the invitee is redirected to a Tlon signup service. After successful registration the user acquires new urbit identity, a hosted urbit instance, and also receives invitations: to a DM with the inviter, and to a group associated with the lure invitation.

2 Architecture

2.1 Overview

There are four agents involved in this process:

  1. The group host issues and validates group invitations.
  2. The pair of agents: reel and bait, control the generation and storage of lure invitations. The bait provider also receives and handles new onboarding notifications received from hosting.
  3. The grouper agents receives a “bite” onboarding notification and requests the group host to generate invites.

_Q: why is “group enabled” status not handled by the %groups agent? Seems like this functionality should be integrated into the new groups agent, and grouper could be altogether eliminated. A new core +bi-core could handle incoming bites.

architecture-beta
group lure(cloud)[Lure Services]

service groups(server)[Groups] in lure
service reel(server)[Reel] in lure
service bait(server)[Bait] in lure
service grouper(server)[Grouper] in lure

service hosting(cloud)[Hosting]
service client(database)[Client]
service joiner(server)[Joiner]

%% The client interacts with the reel agent to obtain
%% a new link.
%%
reel:R <--> L:client

%% The reel agent request the bait provider to generate a new lure
%% invitation link.
%%
bait:T <--> B:reel
%% The bait provider receives an onboarding notification
%% and sends a bait to the lure agent
%%
bait:R <-- L:hosting
%% The grouper agent receives an incoming bait and sends out
%% an invite.
%%
grouper:R <-- L: reel
grouper:B --> T: groups

%% The groups agent invites the joiner
groups:B --> T: joiner

3. Flows

A user can generate a new lure invite associated either to a DM, or to a group. The user must be a group member to generate a lure invite associated to a group.

The client first pokes the reel agent to request a new link to be generated, supplying metadata, which determine the link association. If the invite link is to be associated only with a DM, the metadata will contain a type = user entry.

sequenceDiagram
participant client
participant reel
participant bait

client ->> reel: request an invite link
reel ->> bait: ask for a new invite link
bait ->> bait: generate new lure link
bait ->> reel: give a new link
reel ->> client: give a new link

3.2 Lure link redemption

An invitee can redeem a lure link in two ways: he can either onboard the network and obtain a new Urbit ID, or he can use his existing identity to join the group, DM associated with a particular lure invite link. When hosting detects that a user already own an identity, it skips the new user registration flow. In both cases, the entry point is the onboarding event, called “bite”, sent by hosting to the bait provider, which passes it to the reel agent associated with the particular lure link.

sequenceDiagram
participant joiner
participant groups
participant grouper
participant reel

reel ->> grouper: give the bite
grouper ->> groups: request invitation
groups ->> joiner: send the invite