[ODIS] How does matchmaking work? How often can I matchmake?

[arthurgousset]

This is a note-to-self (for future reference) on a question I received a few times regarding the matchmaking feature in ODIS:

• "Why can I only matchmake once?" (turns out you can do it as often as you want, more below 👇 )
• "Does matchmaking require ODIS quota?" (no, more below 👇)

[arthurgousset]

TLDR:

• users can request contact list matches from ODIS as many times as they want
• they simply need to add an optional argument in the matchmaking request to prevent abuse (more below)

Additional context:

In a nutshell, ODIS matchmaking works as follows:

You provide your phone number +44 444 ... and a contact list:

{
  "+49 999 ...",
  "+33 333 ..."
}

Someone else provides their phone number +49 999 ... and their contact list:

{
  "+44 444 ...",
  "+33 333 ..."
}

If you (+44 444 ...) have someone's phone number (+49 999 ...) in your contact list and they (+49 999 ...) have your phone number (+44 444 ...) in their contact list, then a match exists. Matches can thus only exist among users that have previously made matchmaking requests (i.e. submitted their contact list and phone number).

To prevent abuse, ODIS limits matchmaking to one phone number per account. That is, each account can only query matches for one phone number. These matches can be re-queried, but only if the client supplies the optional signedUserPhoneNumber field in the request body. This field should be populated with a DEK signature over the user’s phone number. The @celo/identity sdk makes this easy for developers. Currently, querying matches for a new number is not supported. Again, this is a precaution against attacks that involve extracting the graph of social connections and registered numbers from ODIS.

For completeness, it's worth noting that:

• ODIS identifier lookup requests cost quota, but
• ODIS matchmaking requests do not.

Thanks for the review @alecps! 🙏