Switch to Verify API for SMS Providers

[codyborn]

All SMS providers have an API specifically for one-time-passwords (OTP):

• Twilio
  • Must create a verification service in the portal
• Nexmo
• MessageBird

These APIs are used for generating, sending, and verifying single-use codes. You cannot send a custom code; the API must generate the code for you. As such, you must also call the verify API with the user submitted code to know whether the code is correct.

The benefits:

• No need for brand/campaign registration (ex 10DLC)
• No need for managing individual numbers (global reach)
• Localization support

Cons:

• More expensive
• Less flexibility on message contents (cannot use custom code)

Security code prefix

Note that we currently add a numeric single-digit prefix to the security code to make it easier to identify which issuer the code came from. The prefix is derived from the hash of the issuer's address.

Generation https://github.com/celo-org/celo-monorepo/blob/master/packages/sdk/contractkit/src/wrappers/Attestations.ts#L29

Usage in wallet https://github.com/celo-org/wallet/blob/623a1cbdef2e7ea330f05a84491d1c80545f427f/packages/mobile/src/identity/securityCode.ts#L42

[asaj]

1. Do we know anything about how impactful this change is likely to be?
2. How will users figure out which issuer sent which code?

[aslawson]

Great questions.

1. is difficult to say, but this essentially puts the onus on the SMS providers to optimize for the best way to send an SMS and ensure delivery. Our current suggestion to validators is to buy at least a US number for each service and a MessageBird Canadian number. But there are countries/carriers that would have a better success rate with local numbers and registered shortcodes. Many providers have long documentation per country on how to optimize for them, but it can be very expensive and complex to register some of these, so we have been hesitant to ask validators to do so without strong evidence that it's critical. The SMS providers have already optimized for delivery in all countries with Verify API requests as they manage the sender. My sense is that it will greatly reduce the SMS delivery issues without us needing to expand with additional providers -- difference among providers will solely be based on the unique relationships they have established with cellular carriers and regulators rather than validator profile setup. Going this route also substantially reduces the complexity of validator configuration, hopefully reducing their operational load.

2. This is something I've put on Valora's radar. But the short answer is clients will not know which issuer sent a code. We will need to design for clients trying multiple issuers with a code (which they already do at a smaller scale; there can be collisions with the prefix indicator) or move to a synchronous flow. But with attestation services accepting up to 5 attempts to redeem a code, the former is an ok solution. Would love if you had any other ideas.

[asaj]

1. Can we estimate it, or put a ceiling on the expected improvement? e.g. if we're seeing X% of users fail to verify after selecting issuers, this feature can improve things by no more than X%.
2. It sounds like the issuers don't know the code themselves, which makes things trickier. Do they know the phone number that was used to send it? If not, I'm not sure I have any suggestions beyond the two that you've proposed, both of which sound acceptable to me.

[codyborn]

1. It's difficult to estimate the coverage impact but we can use these funnel charts to get a ceiling. We see 71% of users successfully reveal attestations (start of SMS send) and 54% of users receive the SMS. So the most we could expect is a 24% increase (71-54/71).
2. I don't think it's possible to know the phone number that the SMS was sent from. Twilio has a custom code feature that allows the caller to specify the code; however MB and Nexmo don't support this.

[aslawson]

Success rates by country (remain relatively consistent)

Traffic by country (US went down after campaign and other countries are steadily climbing)

This suggests reduction in verification success rate is likely due to greater globalization of usage in countries with poorer success rates than US (which is ~80%).

[codyborn]

Deployed Verify for Twilio. Will prioritize measuring impact before supporting other providers.

[0xarthurxyz]

@codyborn: With the Attestation Service 1.3.1 release we support the Twilio VerifyAPI.

• [x] Can we close this ticket (?) with the view that:

1. we're monitoring the Twilio impact (as you mentioned above)

Deployed Verify for Twilio. Will prioritize measuring impact before supporting other providers.

2. we can create new tickets for the Nexmo and MessageBird Verify APIs as and when needed.

[codyborn]

Sounds good! The only reason it wasn't closed was to potentially include other SMS provider but like you said, we can just create new tix if/when we're ready.