Usage Guide
Authentication & Arcana Web3 wallet
Contents
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.