🖊️User Signatures

User Signatures

You have multiple options for how to implement the frontend (where users will sign the challenge messages with their crypto wallets). Below we highlight the popular ones, but you can always custom implement solutions with the Blockin library! There are three main options to obtain user's signatures.

Option 1: Popup (Sign In with BitBadges)

Similar to Sign In with Google, you open a child window from your frontend to an existing Blockin implementation. The user signs in on there, the popup handles certain parts of the verification logic, and passes back the (message, signature) pair as well as the verification status to you via a callback.

We refer you to the Sign In with BitBadges documentation for a walkthrough.

Option 2: Directly In-Site

Handle all the signature functionality directly yourself in your frontend. See the BitBadges frontend source code for a production example.

Each blockchain will have resources and documentation for their implementations respectively. The quickstart repository will start you out with an implementation.

Create, Generate, and Sign TxsBitBadges

import { BlockinUIDisplay, ... } from 'blockin/ui';
//import { BlockinUIDisplay, ... } from 'blockin/dist/ui';

...

<BlockinUIDisplay
  connected={connected}
  connect={async () => {
    try {
      await connect();
    } catch (e: any) {
      console.error(e);
    }
  }}
  buttonStyle={{ height: 45 }}
  modalStyle={{ color: `white`, textAlign: 'start' }}
  disconnect={async () => {
    disconnect();
  }}
  chainOptions={[
    { name: 'Ethereum' },
    { name: 'Cosmos' },
    { name: 'Solana' },
    { name: 'Bitcoin' }
  ]}
  hideChainSelect
  address={address}
  selectedChainInfo={undefined}
  onChainUpdate={handleUpdateChain}
  challengeParams={challengeParams}
  loggedIn={loggedIn}
  logout={async () => {
    await logout();
  }}
  selectedChainName={chain}
  accessTiers={[
    {
      assetConditionGroup: {
        assets: [
          {
            collectionId: 1,
            chain: 'BitBadges',
            assetIds: [{ start: 9, end: 9 }],
            ownershipTimes: [],
            mustOwnAmounts: { start: 0, end: 0 }
          }
        ]
      },
      name: 'General Access',
      resourcesToAdd: [`Full Access: Full access to all features.`],
      description: (
        <>
          This sign-in gives full access to all features. For security reasons, we do not allow access to owners of certain
          badges.
        </>
      ),
      image: '/images/bitbadgeslogo.png',
      frozen: true,
      defaultSelected: true
    }
  ]}
  signAndVerifyChallenge={signAndVerifyChallenge}
  hideConnectVsSignInHelper={hideLogin}
  maxTimeInFuture={168 * 60 * 60 * 1000} //1 week
  />

Option 3: Outsourced (BitBadges)

Completely outsource your frontend to a helper tool such as BitBadges. This means you do not run a frontend at all. Users will generate authentication codes for your message via BitBadges and manually provide you with the (message, signature) pairs. This manual process can be using any preferred method (QR codes, via text inputs, etc). The codes (signatures) and messages are stored in user's accounts but can be exported elsewhere.

We refer you to the BitBadges documentation for this or get started at https://bitbadges.io/auth/linkgen. This should only be used if you do not need instant authentication (such as pre-generating a QR code and presenting at a later time like the ticket booth). Learn more below.

Which one to use?

Outsourcing to a helper tool (option 3) is typically used for use cases where users may not have access to their crypto wallets, so they pre-sign the message and present at a later time (e.g. pre-generate a QR code and present at the ticket gate). If you need instant authentication (i.e. sign time -> authentication time is instant), Option 3 is probably not the choice for you.

The other two options require you to run your own frontends, and the decision between the two really comes down to one question: do you need to interact with wallets or the blockchain in any way (e.g. signing transactions, etc), or if you simply have the user's address, can you do everything you need (potentially with libraries like ethers or public blockchain queries)?

If your frontend requires interacting with wallets, you should probably directly host everything in-site to keep everything all in one place and consistent (if not, users have to connect on both your frontend and BitBadges). If not, you can simplify the process by outsourcing most of the logic to a popup.

You should also consider your application's other requirements, such as decentralization, availability, customizability, latency, throughput, and complexity.

Hybrid dApps

With these options, you can also implement a hybrid dApp, where you map a Web2 username to an address / private key. You then manage everything for the user, such as signing all Blockin auth messages. This allows users to select Web2 usernames if they are not comfortable with Web3 and still be compatible with all Web3 interfaces.

Hybrid dApps are typically implemented with Option 2 above. See the quickstart repository for a hybrid dApp starter.

Helper Tools

A tool to help you get the best of multiple implementations is https://bitbadges.io/auth/code?code=... This is a simple tool to generate a QR code for the signature. The site will allow the user to export it in a variety of methods, such as storing in BitBadges account, emailing to themselves, etc. This can be used when you want to self implement signatures but want users to cache them and present them at a later time.

The following URL query params should be passed.

const { code, name, description, image } = router.query;