Skip to main content

FastAuth SDK

Introduction​

FastAuth is a key management system that allows dApp developers to offer an easy and familiar onboarding flow to new users. Users can sign up for an account using just their email address, and they can easily recover access to that account using the same email they used during sign up. Furthermore, dApp developers can also choose to subsidize gas for a certain smart contract, so that users can start interacting with their dApp immediately, without having to fund their account.

System components​

The FastAuth system is comprised of 3 main components:

  • FastAuth Signer App: An app that can be embedded on your website to allow FastAuth users to sign transactions.
  • MPC Recovery Service: service used to create and restore user accounts, as well as signing transactions on behalf of the user. This service uses the OIDC protocol and leverages multiple MPC nodes, each of them containing a secret key. Each action must be signed by all nodes, and those signatures are then combined into a single signature on the leader node.
  • Transaction Relayer: an http server that relays transactions to the network via RPC on behalf of new users who haven't yet acquired NEAR as part of the onboarding process.

Getting started​

Gaining access to the Beta​

tip

FastAuth is currently on a closed early-access Beta. You can apply to be part of the Beta through this form.

During the Beta, user accounts created via FastAuth will be constrained to your own dApp, and won't be interoperable with other domains. In a future FastAuth release, you'll be given the option to make your user accounts interoperable across the ecosystem.

Setting up Firebase​

Create a project​

  • Go to Firebase
  • Create or sign in to an account
  • Go to "Get started", then "Add project"
  • Call this project my-fastauth-issuer
  • Disable Google Analytics (recommended)
  • Click on "Create project"

Set up passwordless authentication​

  • Go to "Authentication", then "Get started", and "Add new provider"
  • Enable "Email/Password" and "Email link (passwordless sign-in)"
  • Hit "Save"

Add user device information to Firestore​

  • Return to "Project Overview"
  • Go to "Cloud Firestore", then "Create database"
  • Select "Start in production mode", then "Next"
  • Select your preferred location, then "Enable"
  • Go to the "Rules" tab
  • Change the rules to the following:
rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId}/{document=**} {
      allow create, read, update, delete: if request.auth != null && request.auth.uid == userId;
    }
  }
}
  • Hit "Publish"
  • Go to the "Data" tab
  • Click on "Start collection"
  • Set the Collection ID to users and hit "Next"
  • Add a Document ID of root and press "Save"

Get the application credentials​

  • Press the gear button next to "Project Overview", and go to "Project settings"
  • Under "Your apps", click on the </> button
  • Set the app nickname as issuer-gcp and hit "Register app"
  • You should see the code needed for initilization and authentication of Firestore, such as:
// Import the functions you need from the SDKs you need
import { initializeApp } from "firebase/app";

// TODO: Add SDKs for Firebase products that you want to use
// https://firebase.google.com/docs/web/setup#available-libraries
// Your web app's Firebase configuration

const firebaseConfig = {
  apiKey: "apikey",
  authDomain: "my-fastauth-issuer-123.firebaseapp.com",
  projectId: "my-fastauth-issuer-123",
  storageBucket: "my-fastauth-issuer-123.appspot.com",
  messagingSenderId: "12345678910",
  appId: "1:12345678910:web:12345678910"
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);

Setting up your relayer​

Setting up a NEAR account​

First ensure that cargo is installed on your local machine. Try rustup if you haven't already installed it.

cargo install near-cli-rs
NEAR_ENV=mainnet
near account create-account fund-later use-auto-generation save-to-folder ~/.near-credentials/implicit

This should output something like:

The file "~/.near-credentials/implicit/275f14eecb0afcb1f46f2b71b7933afd2de6d4ae8b08e9b11fc538a5a81406b7.json" was saved successfully

In this example. 275f14eecb0afcb1f46f2b71b7933afd2de6d4ae8b08e9b11fc538a5a81406b7 is your funded account. We'll refer to this as $FUNDED_ACCOUNT from now on.

Send some NEAR to this address.

This account has been created with one key. However, due to this, you should create an account with N keys where N is the number of requests you expect to get in a second, at peak load.

To generate an additional key, run the following command:

near account add-key $FUNDED_ACCOUNT grant-full-access autogenerate-new-keypair save-to-keychain network-config mainnet sign-with-access-key-file ~/.near-credentials/implicit/$FUNDED_ACCOUNT.json send

Deploying the relayer​

Run the following command:

git clone https://github.com/near/pagoda-relayer-rs

Go to config.toml and change:

network = "mainnet"
num_keys = 3  # correlates to the number of keys in `keys_filenames`. Will be optional in the future.
relayer_account_id = "$FUNDED_ACCOUNT"
keys_filenames = [
    # The original account
    "~/.near-credentials/mainnet/$FUNDED_ACCOUNT.json",

    # Other keys you've optionally created. This will allow rotating through each key as to avoid nonce races.
    "~/.near-credentials/mainnet/$FUNDED_ACCOUNT/ed25519_4ryLkp4AuzBD8yuyRJKb91hvHZ4zgqouWcJzu1gNEvLv.json",
    "~/.near-credentials/mainnet/$FUNDED_ACCOUNT/ed25519_7K3jF8Ft5dKFEPYRH1T4mncvsZGgSoGKsvsnnKEmqubT.json"
]

Optionally, if you need to generate additional access keys for the $FUNDED_ACCOUNT, run the following command N times. Note that this will create keys for implicit accounts, but we'll then tie them to $FUNDED_ACCOUNT.

near generate-key
near add-key $FUNDED_ACCOUNT exampleImplicitPublicKeyCxg2wgFYrdLTEkMu6j5D6aEZqTb3kXbmJygS48ZKbo1S

Then run:

docker compose up

You should do this on a VM server of your choice. We will refer to the URL of this VM as $RELAYER_URL from now on.

Setting up the frontend​

Deploying the signer app​

  • Go to GCP's Cloud Run console and press "Create Service".
  • In the field "Container image URL", paste gcr.io/fa-signer/signer-app:version2.
  • Go to the "Container, Networking, Security" fold out and then "Environment Variables"
  • Click on "Add Variable"
  • Set the following environment variables from the firebaseConfig you generated earlier.
NETWORK_ID:                           'mainnet',
RELAYER_URL:                          '$RELAYER_URL',
FIREBASE_API_KEY:                     'apikey',
FIREBASE_AUTH_DOMAIN:                 'my-fastauth-issuer-123.firebaseapp.com',
FIREBASE_PROJECT_ID:                  'my-fastauth-issuer-123',
FIREBASE_STORAGE_BUCKET:              'my-fastauth-issuer-123.appspot.com',
FIREBASE_MESSAGING_SENDER_ID:         '12345678910',
FIREBASE_APP_ID:                      '1:12345678910:web:12345678910',

Alternatively if you're doing a testnet deployment, do:

NETWORK_ID:                           'testnet',
RELAYER_URL_TESTNET:                  '$RELAYER_URL',
FIREBASE_API_KEY_TESTNET:             'apikey',
FIREBASE_AUTH_DOMAIN_TESTNET:         'my-fastauth-issuer-123.firebaseapp.com',
FIREBASE_PROJECT_ID_TESTNET:          'my-fastauth-issuer-123',
FIREBASE_STORAGE_BUCKET_TESTNET:      'my-fastauth-issuer-123.appspot.com',
FIREBASE_MESSAGING_SENDER_ID_TESTNET: '12345678910',
FIREBASE_APP_ID_TESTNET:              '1:12345678910:web:12345678910',
  • Click on "Create Application"
  • Then, inside your app's control panel copy the app's URL, such as https://signer-app-123456-ab.a.run.app. We will refer to the deploy URL as $WALLET_URL.

Authorizing a domain on Firebase​

  • Go back to the Firebase Console
  • Go to "Authentication" in the sidebar, and then the "Settings" tab
  • Click on the "Authorized domains" menu item
  • Add $WALLET_URL to the list

Deploying your application frontend​

First, install the @near-js/iframe-rpc package from the NPM registry.

import { setupFastAuthWallet } from 'near-fastauth-wallet';
import { setupWalletSelector } from '@near-wallet-selector/core';

// Initialize wallet selector
const selector = setupWalletSelector({
          network: networkId,
          modules: [
            setupFastAuthWallet({
              relayerUrl: "$RELAYER_URL",
              walletUrl: "$WALLET_URL"
            })
          ]
      })

// EITHER setup onClick function for login
const onCLick = () => selector.then((selector: any) => selector.wallet('fast-auth-wallet'))
      .then((fastAuthWallet: any) =>
        fastAuthWallet.signIn({
          contractId: "$CONTRACT_ID",
          email: "<USERS_EMAIL_ADDRESS>",
          isRecovery: true,
        }),);

// OR setup onClick function for login
const onCLick = () => selector.then((selector: any) => selector.wallet('fast-auth-wallet'))
      .then((fastAuthWallet: any) =>
        fastAuthWallet.signIn({
          contractId: "$CONTRACT_ID",
          email: "<USERS_EMAIL_ADDRESS>",
          accountId: "<USERS_DESIRED_NEAR_ADDRESS>.near"
          isRecovery: false,
        }),);

Wehenever the user tries to login, call onClick.

Getting added to the MPC recovery service​

As a last step, we'll need to add your app to our MPC recovery service. To get added, please send us your $FIREBASE_PROJECT_ID, $RELAYER_API_KEY and $RELAYER_URL through this form.