Introducing the Circle Programmable Wallets Web SDK

Circle’s Web SDK allows your app to offer the familiarity of PIN codes and security questions instead of complicated seed phrases and private keys.

Introduction

Web3 UX can be clunky and hard to use. But with Circle’s Programmable Wallets Web SDK, developers can give their Web3 users the Web2 authentication experience they expect. With the Web SDK, instead of complicated seed phrases and private keys, your app can offer the familiar experience of PIN codes and security questions.

Let’s look at how easy it is to use Web SDK and the benefits it brings.

User-Controlled Programmable Wallets

First, let’s begin with a refresher on Circle’s user-controlled Programmable Wallets*.

Wallets are often the first web3 UX users encounter. Unfortunately, wallets tend to have a poor user experience and are technically difficult to use. In fact, they are a huge reason why web3 is associated with a steep and daunting learning curve.

But Circle’s user-controlled Programmable Wallets solve this problem. They are a wallet-as-a-service, embedded in your apps, that give your users the best of both web2 and web3. User-controlled programmable wallets offer:

• The seamless authentication and authorization experience users expect from web2. No browser extensions, recovery phrases, or hexadecimal addresses are needed. Instead, users have familiar paradigms: PINs and security questions. In many cases, your users won’t even know they are using a web3 wallet.
• Advanced security using an advanced multi-party computation (MPC) technology that distributes key shards across multiple parties, guarding wallets against unauthorized access and theft of funds/assets. This approach stands in stark contrast to the typical web3 experience of self-custodial browser wallets, where opening a ZIP file or creating a dangerous signature can lead to permanent loss of funds.
• The ability to offer gas-free transactions to your users. This reduces the complicated overhead of users obtaining native gas tokens.
• All of these features follow the tenets of web3 and give users full control over their funds and digital assets. A transaction can only be conducted with explicit authorization from the user.

Circle’s Web SDK

By using Circle’s Programmable Wallets Web SDK, developers can easily integrate this user-controlled wallet experience directly into your websites and web apps.

With the SDK, you can allow your users to set, and use, a six-digit PIN code and security questions and answers inside their browser, giving them an optimal user experience and abstracting away the perceived complexities of using a web3 wallet. No more private keys or long seed phrases needed.

As in many traditional flows, users can access their wallets and authorize transactions in their browser using their PIN code. If they forget their PIN, they can use the security questions and answers to recover their wallet.

The SDK also creates additional security for users by encrypting the request body (PIN and security answers) with an encryption key. Developers never have access to the PIN codes.

And, through a highly customizable iframe element, you can integrate the look and feel of the experience seamlessly into your web applications. Highlights of customization include:

1. UI Title and Subtitle - customize the title and subtitle to reflect your brand and control the messaging of your wallet’s flow. Add specific instructions or disclaimers.
2. PIN Code Input Layout - adjust the PIN code input field to match your app’s design.
3. Question List Configuration - choose which security questions you want to support and allow your users to choose from your predefined list of questions.
4. SDK Initialization - set an endpoint that allows seamless and secure communication between your web app and the Circle services.
5. Error Messages - customize user error messages, choosing to give as much (or as little) guidance as needed.
6. Challenge ID Acceptance and Operation Retrieval - easily access a challenge ID and retrieve operations associated with that ID from your code. Challenges may include creating a wallet, creating a transaction, signing a message, restoring PIN, and so on.

In combination with the iOS and Android counterparts, the Web SDK enables developers to build interoperable experiences for end users across platforms, providing users with access to their wallets whether it be a browser or mobile device.

For a video walkthrough of how this all works, check out this example of a customer creating a wallet and claiming their USDC as the new joiner gift to buy an item with the USDC stored in their wallet.

Web SDK in Action

The Web SDK can be easily integrated into native Javascript, React, and Vue.

Let’s look at how it might work with React, for example.

import React, { useCallback, useEffect, useState } from 'react'
import { ToastContainer, toast } from 'react-toastify'
import TextField from '@mui/material/TextField'
import Button from '@mui/material/Button'
import { W3SSdk } from '@circle-fin/w3s-pw-web-sdk'

let sdk: W3SSdk

function App() {
  useEffect(() => {
    sdk = new W3SSdk()
  }, [])

  const [appId, setAppId] = useState(
    localStorage.getItem('appId') || 'someAppId'
  )
  const [userToken, setUserToken] = useState(
    localStorage.getItem('userToken') || 'someUserToken'
  )
  const [encryptionKey, setEncryptionKey] = useState(
    localStorage.getItem('encryptionKey') || 'someEncryptionKey'
  )
  const [challengeId, setChallengeId] = useState(
    localStorage.getItem('challengeId') || 'someChallengeId'
  )

  const onChangeHandler = useCallback(
    (setState, key) => (e) => {
      const value = e.target.value
      setState(value)
      localStorage.setItem(key, value)
    },
    []
  )

  const onSubmit = useCallback(() => {
    sdk.setAppSettings({ appId })
    sdk.setAuthentication({ userToken, encryptionKey })

    sdk.execute(challengeId, (error, result) => {
      if (error) {
        toast.error(`Error: ${error?.message ?? 'Error!'}`)
        return
      }
      toast.success(`Challenge: ${result?.type}, Status: ${result?.status}`)
    })
  }, [appId, userToken, encryptionKey, challengeId])
  
  return (<--This HTML block includes multiple TextFields for inputting application ID, user token, encryption key, and challenge ID, along with a button to submit these details for challenge verification.-->)
} 

Let’s take a detailed look at some of the most important lines above:

1. import { W3SSdk } from '@circle-fin/w3s-pw-web-sdk' imports the W3Sdk from the Circle package.
2. The SDK is then initialized using a useEffect hook. In other words, the SDK loads when this particular React component loads (or refreshes).
3. Within the app, we have state variables to store the app ID, encryption key, user token, and challenge ID. The challenge ID will determine what the component is supposed to do at a specific time: create a wallet, create a transaction, accelerate a transaction, set a security question, and so on.
4. The onSubmit function executes the challenge you’ve set (at the Circle backend) using the app and user credentials. It also tracks the success and error messages.
5. The information (such as challenge ID, user credentials, and challenge execution status) is displayed on the frontend. In a real-world app, of course, you would replace this with custom code relevant to your web app.

That’s it! Note how the flow is seamlessly integrated into your frontend and is able to securely communicate with Circle services.

Conclusion

Circle’s Programmable Wallets Web SDK gives developers the delightful authentication and authorization experience of user-controlled programmable wallets—right in your apps.

With the simplicity and familiarity of PIN codes and security questions and answers, web3 wallets, and their complicated and onerous requirements, won’t get in the way of your app’s success.

*Programmable Wallets application programming interface (“API”) is offered by Circle Technology Services, LLC (“CTS”). CTS is not a regulated financial services company and the API does not include financial, investment, tax, legal, regulatory, accounting, business, or other advice. For additional details, please click here to see the Circle Developer terms of service.