Skip to main content

Using Arcana Wallet

Arcana wallet is an embedded Web3 wallet available to all the dApps that integrate with the Arcana Auth SDK.

In this guide, you will learn about Arcana wallet screens, navigation, usage flows, and how dApp users interact with the wallet screens to perform the following actions on the supported networks:

  • user authentication, login and log out
  • view pending transaction requests
  • check account balance
  • view user profile details
  • add and configure network profiles
  • switch networks
  • export private key
  • add custom tokens
  • send and receive tokens (native, custom)
  • sign (approve, reject) blockchain transactions
  • view assets
  • view transaction activity

Prerequisites

  • Install the @arcana/auth package. Integrate it with your dApp. For details, see Arcana Auth Quick Start Guide.

    const appAddress = '445007f942f9Ba718953094BbeeeeeB9484cAfd2' // App Address Example

    const auth = new AuthProvider(`${appAddress}`, {
    position: 'left', // defaults to right
    theme: 'light', // defaults to dark
    alwaysVisible: false, // defaults to true which is Full UI mode
    chainConfig: {
    chainId: CHAIN.POLYGON_MAINNET,
    rpcUrl: '',
    },
    })
    try {
    await auth.init()
    } catch (e) {
    // Handle exception case
    }

    provider = auth.getProvider()
    // or
    provider = window.ethereum
  • Make sure you have already initialized the wallet in your dApp code before invoking any JSON RPC calls listed below for blockchain transactions such as send tokens, sign transactions, or to check the wallet balance.

    // Assuming Auth SDK is integrated and initialized
    try {
    provider = auth.provider
    const connected = await auth.isLoggedIn()
    console.log({ connected })
    setHooks()
    } catch (e) {
    // Handle exception case
    }

    // setHooks: Manage chain or account switch in Arcana wallet
    function setHooks() {
    provider.on('connect', async (params) => {
    console.log({ type: 'connect', params: params })
    const isLoggedIn = await auth.isLoggedIn()
    console.log({ isLoggedIn })
    })
    provider.on('accountsChanged', (params) => {
    //Handle
    console.log({ type: 'accountsChanged', params: params })
    })
    provider.on('chainChanged', async (params) => {
    console.log({ type: 'chainChanged', params: params })
    })
    }

Arcana Wallet Features

Any dApp that integrates with Arcana Auth SDK and initializes the AuthProvider can allow its users to access the Arcana wallet to log into the dApp and sign blockchain transactions.

User Authentication

A dApp developer can choose to build the user authentication functionality by adding user interfaces for login and call the Auth SDK methods for social authentication and passwordless login. As an alternative, a dApp developer can use the plug-and-play authentication feature of the Auth SDK instead of building the login feature in the dApp from scratch.

The plug-and-play feature of the Arcana Auth SDK brings up a pop-up login screen for user onboarding automatically. The dApp user has to simply configure selected social providers that are available for user onboarding. The plug and play pop-up UI screen displays only those onboarding options that the developer configures.

note

By default, passwordless login option is always available.

Once the user logs in, the pop-up UI from the Auth SDK disappears from the dApp screen.

The Arcana wallet shows up on the bottom right of the dApp window (by default), after the user is logged in.

Whether the Arcana wallet is always displayed for a logged in user or whether it shows up only when a blockchain transaction is triggered can be managed by the dApp developer via the alwaysVisible parameter provided during the AuthProvider instantiation.

Let's take the example of the sample demo dApp to demonstrate various Arcana wallet features and user interface.

Demo App Landing

Plug-and-Play dApp Login

If a dApp uses the plug-and-play feature of the Auth SDK, a pop-up UI screen shows up embedded in the dApp. It displays all the social authentication options enabled by the dApp developer using the Arcana Developer Dashboard before integrating the dApp with the SDK.

  • Discord
  • GitHub
  • Google
  • Twitch

Once the user logs in using one of the available options, then the pop-up UI screen disappears.

If we configure only the Google OAuth in the sample demo-app, then only the Google option will show up in the pop-up login screen:

note

The options displayed by the wallet screen depend upon the ones configured by the dApp developer using the Arcana Developer Dashboard. For example, in the demo app, Twitter is not configured so it does not show up but the Arcana Auth SDK supports Twitter based social authentication too.

In the case of the sample demo dApp, wallet visibility mode is set to 'Full UI'. Once the user has logged into the dApp, the wallet always shows up in the dApp window. It can be minimized and displays as a circular widget. If a user actions results in a blockchain transaction sign request, the wallet screen shows up in the dApp context.

Logout

Click icon at the bottom right of the Arcana wallet. The user profile screen is displayed. Use Logout to log out of the wallet and the sample demo app.

Wallet Screen

Click icon on the bottom left of the Arcana wallet to bring up the wallet home screen. It displays the following information:

  • Wallet address
  • Network
  • Total Balance
  • Refresh button
  • Send button
  • Receive button

Use Send to transfer tokens to other blockchain accounts and Receive to copy the QR code or wallet address and share it with another sender to receive tokens.

Pending Requests

If you see a red dot on the icon at the bottom left of the Arcana wallet, it indicates a pending blockchain transaction that a user needs to review and act upon. Click on the icon to see details of the pending transaction and take appropriate action. Once all pending transactions are processed, you will not see the red dot.

After approving the pending request, the Arcana wallet shows a No Pending Requests! screen.

Demo App Nopending

Example: Pending Personal Sign

Once the user is logged in using one of the available operations, the wallet displays a personal signature request for obtaining user credentials to establish blockchain connectivity. You can see an indication of a pending transaction when the wallet is minimized.

dApp wallet integration example

Users can click on the wallet to bring up the Full UI wallet visibility mode and review, and approve the personal sign request as displayed in the figure below:

Demo App PersonalSign

Check Balance

Click icon on the bottom left of the Arcana wallet. The account balance for the selected wallet account is displayed. Use the Refresh to get the latest account balance.

User Profile Screen

Click icon on the bottom left of the Arcana wallet to see the user profile screen with these details:

  • User name
  • Email ID used to log into the wallet
  • Network
  • Wallet Address
  • Option to export private key
  • Logout button
  • Close button

Add/Select a Network

Arcana Wallet supports signing transactions on Ethereum, Polygon, and other supported EVM-compatible chains. You can select the desired network from the drop-down list. If your network is not listed, you can also add multiple, EVM-compatible networks.

Once you click Save, the newly added network is automatically selected as the current active chain in the updated network list.

caution

New Network Configuration Persistence:

Web3 developers can programmatically configure Arcana wallet and set up a list of networks from the ones that are supported. If the dApp developer has configured the Arcana wallet visibility to Full UI, the dApp users are also allowed to add new network settings to the Arcana wallet. This is in addition to the ones already configured by the dApp developer.

Only the list of networks configured by the dApp developer is persisted across user login sessions. Any additional blockchain network configurations added by the dApp users are only stored locally on the client-side Arcana SDK. The user-added network configurations are NOT stored by the Arcana Network.

As the dApp user-added networks are not persisted, those will have to be added by the dApp user every time they log in to the Arcana wallet.

Switch Network

Click icon to bring up the wallet screen. Use the network drop-down list to switch to a different network from the list of configured networks.

Export Private Key

Click icon on the bottom left of the Arcana wallet to see the user profile screen. It provides an option to export user's private key. For details, see how to export a user's private key guide.

Add Custom Tokens

In addition to the native XAR token, the Arcana wallet can also be used to send and receive custom tokens.

Click icon to bring up the wallet screen. Refer to the Assets tab. If you do not see your custom token already listed in the asset list, click the icon to add your custom token.

This will bring up the following custom token specification wallet screen. Add the following details:

  • Token Contract Address
  • Token Symbol
  • Token Decimal

Click Save to add the custom token. The newly added custom token will show up under the Assets tab on the wallet screen.

Send & Receive Tokens

Arcana wallet supports sending and receiving of native as well as custom tokens. Once the send/receive token transaction is complete, the dApp user can view the token balance under the Assets tab in the wallet screen.

Choosing Custom or Native Tokens

Before sending tokens, a dApp developer can specify whether they intend to transfer native or custom tokens. To send a custom token, it should already be added to the Arcana wallet.

Click icon to bring up the wallet screen. Choose Send to access the send token functionality. You will see the following wallet screen:

Use the drop-down list to choose one of the custom tokens that you have already added to the Arcana wallet. Refer to the Send Tokens section below and send the custom tokens.

Send Tokens

Click icon at the bottom left of the wallet to access the Send Tokens functionality.

When you click Send, you will see a screen displaying details of the blockchain send transaction. Specify the recipient's account address, choose the token, the amount of token that needs to be sent, and gas fees, and then Click Proceed.

This will bring up a preview screen that displays details of send transaction. You can choose to click Back if you wish to change any transaction details or inputs. If you Click Send and confirm, the send transaction is processed.

Receive Tokens

Click icon at the bottom left of the wallet to access the Receive Tokens functionality. If you wish to receive tokens from another wallet address, click Receive. This will allow you to copy the QR code and share it with the sender for receiving tokens in your account. Alternatively, you can copy the account address and share that with the sender to receive tokens.

Click Refresh to see the updated account balance after a transaction is complete.

Sign Transaction

When the dApp user issues a sign transaction request via the dApp, the Sign Message wallet screen is displayed. It shows the details of the signed message. Scroll down and you will see Reject and Approve buttons.

For example, when a user uploads a file to the Arcana Store or downloads a file, a blockchain transaction is initiated that needs the user's approval as shown in the figure below:

Click Approve, or Reject as the case may be. If you close this screen using the icon on the top right of the Arcana wallet, you will see the wallet in the minimized form with a red box and number indicating a pending transaction. Once you take action on the pending transaction, the home screen of the wallet will show a No Pending Requests! message.

View Assets

The Assets tab in the Arcana wallet displays all the tokens and their balance. Click to view the various assets associated with the Arcana wallet account address.

It shows both the native and custom tokens. The dApp user must add the custom tokens manually to the Arcana wallet before the custom token balance can be viewed in the Assets tab.

View Transaction Activity

The Activity tab in the Arcana wallet displays the following transactions for the current dApp user login session.

  • Activity related to any supported network
    • Send transactions for native or custom tokens
    • Contract Deployment
    • Contract Interaction
  • Activity related to Arcana Network storage transactions
    • Upload
    • Download
    • Delete
    • Transfer Ownership
    • Share
    • Revoke

Click to view the activity details.

It shows both the native and custom token-related transaction activity. The dApp user must add the custom tokens manually to the Arcana wallet before the activity related to the token can be viewed in the Activity tab.

That completes this tour of the Arcana wallet screens for various wallet functions and usage.

That is all! 🎉

You are now well-versed with various Arcana wallet screens and how to use the Arcana wallet to perform blockchain transactions.

What's Next?

It is highly recommended that you try out the Arcana sample demo app deployed at the portal:

https://demo.beta.arcana.network/

This sample demo application integrates with Arcana Auth SDK. It is configured for allowing dApp users to onboard using passwordless login and Google social authentication. When you bring up this dApp, you will see the Arcana wallet on the bottom right area of the screen. Click on it to log into the wallet and perform blockchain operations.

See also