Skip to content

Usage Guide

Authentication & Arcana Web3 wallet

Contents

  1. Installation
  2. Quick Start with ethers.js
  3. Quick Start with web3.js
  4. Usage

Installation

NPM/Yarn Install

npm install --save @arcana/auth
yarn add @arcana/auth

CDN Install

<script src="https://cdn.jsdelivr.net/npm/@arcana/auth"></script>
<script src="https://unpkg.com/@arcana/auth"></script>

Quick Start with ethers.js

import { AuthProvider } from '@arcana/auth'
import { ethers } from 'ethers'

// clientId: Arcana Unique App Identifier via Dashboard
const auth = new AuthProvider(`${clientId}`) 

window.onload = async () => {
  try {
    await auth.init()

    const arcanaProvider = await auth.connect()
    const provider = new ethers.providers.Web3Provider(arcanaProvider)

    await provider.getBlockNumber()
    // 14983200
  } catch (e) {
    // log error
  }
}

Quick Start with web3.js

import { AuthProvider } from '@arcana/auth'
import Web3 from 'web3'


// clientId: Arcana Unique App Identifier via Dashboard
const auth = new AuthProvider(`${clientId}`)

window.onload = async () => {
  try {
    await auth.init()

    const arcanaProvider = await auth.connect()
    const provider = new Web3(arcanaProvider)

    await provider.getBlockNumber()
  } catch (e) {
    // log error
  }
}

Usage

AuthProvider

Import AuthProvider

const { AuthProvider } = window.arcana.auth // From CDN
// or
import { AuthProvider } from '@arcana/auth' // From npm

Initialize AuthProvider

import { AuthProvider } from '@arcana/auth'

interface ChainConfig {
  chainId: 'number', // Example: Polygon Mumbai Testnet specify '80001'
  rpcUrl?: 'string'
}

const auth = new AuthProvider(`${clientId}`, {  //Arcana Unique App Identifier via Dashboard
  position: 'left', // optional, defaults to right
  theme: 'light', // optional, defaults to dark theme
  alwaysVisible: false, // optional, defaults to true
  network: 'mainnet', // optional, network can be testnet or mainnet - defaults to testnet
  setWindowProvider: true, //optional, defaults to false
  chainConfig: {
    chainId: '80001', //Polygon Mumbai Testnet ChainId
    rpcUrl: 'https://rpc.ankr.com/polygon_mumbai', 
  },
})

await auth.init()  // Note: Initialize Auth SDK before calling any other Auth APIs

See Get Started with Auth SDK for more Auth SDK usage insights.

Auth APIs

Plug and Play Authentication

const provider = await auth.connect()

Login

Social login

// loginType - Google, Discord, Twitter, GitHub, Twitch
const provider = await auth.loginWithSocial(`${loginType}`)

Passwordless login via an email verification link

const provider = await auth.loginWithLink(`${email}`)

Check if a user is logged in

const isloggedIn = await auth.isLoggedIn() // boolean

Check and reconnect, if required

const canReconnect = await auth.canReconnect()
// auth.reconnect() should be on a click event since it opens a new tab
await auth.reconnect()

Get user information

const info = await auth.getUser()

/*
interface UserInfo {
  id: string
  email?: string
  name?: string
  picture?: string
  address: string
  publicKey: string
}
*/

Show wallet UI

auth.showWallet()

Logout

await auth.logout()

Get Public Key

Get the public key associated with an email.

await auth.getPublicKey(`${email}`)

Encryption

ECIES Encryption

The wallet uses ECIES to decrypt cipher text, so a complementary encryption method has to be used from package eth-crypto.

import EthCrypto from 'eth-crypto'

const encrypted = await EthCrypto.encryptWithPublicKey(
  'bf1cc3154424dc22191941d9f4f50b063a2b663a2337e5548abea633c1d06ece...', // publicKey
  'foobar' // message
)

Web3 Wallet Operations

Arcana wallet is an embedded Web3 wallet offered via the Auth SDK. It uses Ethereum JSON-RPC to interact with the blockchains.

JSON RPC Support

Arcana wallet implements the following common interfaces exposed by all Ethereum clients:

Switching Chains

wallet_addEthereumChain

This method is specified by EIP-3085.

try {
  await provider.request({
    method: 'wallet_addEthereumChain',
    params: [{
      chainId: '0xABCDEF',
      chainName: 'My Custom Chain',
      rpcUrls: ['...']
    }]
  })
} catch(error) {
  ...
}

interface AddEthereumChainParameter {
  chainId: string; // A 0x-prefixed hexadecimal string
  chainName: string;
  nativeCurrency: {
    name: string;
    symbol: string; // 2-6 characters long
    decimals: 18;
  };
  rpcUrls: string[];
  blockExplorerUrls?: string[];
}

wallet_switchEthereumChain

This method is specified by EIP-3326.

try {
  await provider.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0xf00' }],
  });
} catch(error) {
  ...
}

interface SwitchEthereumChainParameter {
  chainId: string; // A 0x-prefixed hexadecimal string
}

If the error code (error.code) is 4902, then the requested chain has not been added, and you have to request to add it via wallet_addEthereumChain.

wallet_watchAsset

This method is specified by EIP-747

await provider.request({
  method: 'wallet_watchAsset',
  params: {
    type: 'ERC20',
    options: {
      address: '0xB983E01458529665007fF7E0CDdeCDB74B967Eb6',
      symbol: 'FOO',
      decimals: 18,
      image: 'https://foo.io/token-image.svg',
    },
  },
})

Check out Auth SDK Reference Guide for details.


Last update: July 6, 2023 by shaloo, shalz