Skip to content

Custom Wallet UI

Estimated time to read: 6 minutes

In this guide, you will learn how Web3 apps that integrate with the Arcana Auth SDK can disable the built-in Arcana Wallet UI altogether and use a custom wallet UI to allow authenticated users to sign blockchain transactions.

To use the white-labeled auth feature, the developers must first use the Arcana Developer Dashboard to register the app, configure authentication providers and only then integrate the app with the Arcana Auth SDK and onboard users.

In addition, developers must also build custom wallet UI and call the standard Ethereum JSON RPC calls supported by the Arcana Auth SDK for enabling the authenticated users to programmatically sign blockchain transactions.

Prerequisites

  • To use the Arcana Developer Dashboard, developers can sign in using one of the supported social login providers or opt for passwordless sign-in.

    • Google
    • GitHub
    • Twitch
    • Discord

Step 1: Developer Dashboard Login

Go to https://dashboard.arcana.network and log in using one of the available options.

Welcome screen
Developer Dashboard Login Page

Aggregate Login

The Arcana Auth protocol aggregates multiple login identities for the user across social login providers under a single identifiable Arcana account. This enables developers to log into the Arcana Developer Dashboard through any of the supported login providers and access the same Arcana developer account and app settings.

Step 2: Register Application

After logging in, the Manage Apps dashboard screen is displayed.

List Registered Apps

Each app registered for a developer account is represented by a card in the Manage Apps screen of the Arcana Developer Dashboard.

Manage Apps
Manage Apps

Initiate App Registration

In the 'Manage Apps' dashboard, click Create New App wizard to register a new app.

Register by Creating New App
Register by Creating New App

Registration Settings

To register a new app, the developer needs to provide the following settings:

  • App name
  • Chain Type: EVM, Solana, MultiversX, Near
  • Default Blockchain
  • Wallet UI Mode

App Name

Add a unique name for the app. It can be edited later. After registration, a unique Client ID is associated with each app name. This Client ID is never changed, even if the app name is altered.

All emails related to a registered app billing or user login will mention the latest app name as displayed in the dashboard. Once an app is deleted, the Client ID is no longer valid. Creating a new app with the same name and registering it with Arcana will result in a new Client ID associated with the same name.

Edit App Name

To edit the name of a registered app entry, use the pen icon. Click Enter in the editable text field to save the changes.

Chain Type

Developers need to decide at the time of registration whether the app will use the EVM chains or one of the non-EVM chains supported by the Arcana Auth SDK.

Non-EVM Chains

When registering an app through Arcana Developer Dashboard, the choice of chain type (EVM, Solana, MultiversX, Near) is final. App developers can't change it later. They can switch the default chain within the same type. For example, a Solana app on Testnet can switch to Solana Mainnet or Solana Dev but not to MultiversX or an EVM chain.

Default Blockchain

The chain marked as default is the one that is selected and displayed in the wallet once the user logs into an app that is integrated with the Arcana Auth.

The default chain can be changed programmatically via the app developer once the user approves switching of the chain. Also, the user can change the default chain anytime by using the wallet UI. Chains can be switched to any one of the ones displayed in the pre-configured list in the wallet UI or in the app chain settings displayed in the dashboard.

Wallet UI Mode

The wallet UI mode setting allows the developers to choose whether they want to enable the built-in Arcana wallet UI in the context of their app or build a custom wallet UI for the app users. Note, this is a one-time setting at the time of registering the app.

By default, Arcana wallet UI is enabled for all registered apps. Selecting Custom Wallet UI option disables the built-in Arcana wallet UI altogether.

Custom Wallet UI

This is a one-time setting. It cannot be changed again later once the app is registered. When selecting the custom wallet UI option, developers must build a custom wallet UI and programmatically wire it to the appropriate JSON-RPC Web3 wallet operations. Also, there are no notifications generated by the Arcana Auth SDK when a custom wallet UI is selected. The developers must add requisite logic and code to get the user approvals for blockchain operations.

Confirm Registration

After providing all the required inputs, click Create to register the app.

Register dApp
Register dApp

A newly registered app dashboard displays Testnet configuration settings. A unique Client ID is assigned for the Testnet profile. Developers can deploy the app on the Arcana once SDK usage is configured in the dashboard and the app is integrated with the SDK.

New app dashboard
New App Dashboard

Mainnet Deployment

To deploy the app on the Arcana Mainnet, developers need to create a Mainnet configuration profile and obtain a different Client ID. Update the integration code with this Mainnet Client ID. This step is necessary to deploy the app on the Arcana Mainnet.

For more information, refer to the Testnet > Mainnet Migration Guide.

Click Configure in the LHS menu to view and edit the configuration settings.

To use a custom wallet UI, specify the Wallet UI Mode setting as 'Custom UI' before clicking the create button.

Choose Custom Wallet UI
Choose Custom Wallet UI

Custom Wallet UI

Developers can choose the custom wallet UI option at the time of registering the app with Arcana. This is a one-time setting. Once selected, the setting cannot be changed later after the app is registered. The app can integrate with the Arcana Auth SDK and cannot use the built-in Arcana wallet UI at all. Developers must create a custom wallet UI and plug in the requisite Web3 wallet operations.

You can view the Wallet UI Mode setting in the app configuration dashboard.

Wallet UI Mode Setting Ref
Wallet UI Mode Setting

Global Keys Not supported

If a developer chooses white-labeled auth and plugs in a custom wallet UI, only app-specific keys are supported. What this means is that authenticated users will see different wallet addresses when they sign in using the same authentication provider in a different app in the Arcana ecosystem.

Step 3: Configure Authentication Providers

Follow the instructions to configure authentication providers before integrating the app with the Arcana Auth SDK.

Step 4: Integrate App

Use the appropriate integration method as per the app type and integrate the app with the Arcana Auth SDK.

Step 5: Onboard Users

Apps that are integrated with the Arcana Auth SDK can choose the built-in plug-and-play login UI or use custom login ui to onboard users. For details, see onboarding users documentation.

Step 6: Plug in Custom Wallet UI

Once user onboarding logic is in place, developers can add code to wire the custom wallet UI by using the standard Ethereum EIP-1193 provider. This provider can be obtained after instantiating the AuthProvider while integrating the app with the Arcana Auth SDK.

Use the provider for calling JSON-RPC Web3 wallet operations and display UI notifications to allow the users to approve or reject the blockchain request. Note that in the case of custom wallet UI, there will be no blockchain transaction notification pop-ups generated by the Arcana Auth SDK. Once the app developer issues the JSON-RPC wallet operations supported by the Arcana Auth SDK, the transaction is assumed to be approved and directly submitted to the requisite network as specified in the blockchain request.

Here is a sample code snippet to demonstrate how a vanilla HTML/CSS/JS app can integrate with the Arcana Auth SDK, onboard users via plug-and-play login UI and use the standard EIP-1193 Ethereum provider for plugging in wallet functionality and blockchain signing operations with a custom wallet UI.

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

let provider;
const auth = new AuthProvider('xar_live_nnnnnnnnnnnnnnncdddddddd')  //Use registered app client Id

// initialize the Arcana AuthProvider before calling any AuthProvider functions
...
await auth.init()
...

// onboard users - for e.g. using plug-and-play ui

const arcanaProvider = await auth.connect()

// alternatively, onboard users by calling loginWithLink(deprecated), `loginWithOTPStart`, `loginWithOTPComplete`, loginWithSocial, loginWithBearer for passwordless, social or IAM providers.
...

const provider = new ethers.providers.Web3Provider(arcanaProvider)

// Call ethers provider APIs see https://docs.ethers.org/v5/api/providers/provider/ for details
await provider.getBlockNumber()

// Use the Arcana provider to sign a message using JSON RPC calls

async function signMessage() {

  // Display a notification in custom wallet UI  showing the message details and seeking user's approval

  ...

  // Once user approves, issue the request via the Arcana Auth SDK to sign transaction

  const { sig } = await arcanaProvider.request({
    method: 'eth_sign',
    params: [
      {
        from, // sender account address
        data: 'Some message data',
      },
    ],
  })
  console.log({ sig })
}

...

// You can send tokens or use eth_sendtransaction functionality in custom wallet UI 
// Show a UI notification displaying the transaction details and ask for user's approval

...

// Use the Arcana provider to issue the send transaction

async function sendTransaction() {
  const hash = await arcanaProvider.request({
    method: 'eth_sendTransaction',
      params: [{
      from,
      gasPrice: 0,
      to: '0xE28F01Cf69f27Ee17e552bFDFB7ff301ca07e780', // receiver account address
      value: '0x0de0b6b3a7640000',
    },],
  })
  console.log({ hash })
}

...

Developers can also add code for other supported Web3 wallet operations as required by the app.

Getting Private Key with Custom Wallet UI

When utilizing the default Arcana wallet UI, authenticated users can securely access and copy their private key if needed.

For custom wallet UIs, developers have the freedom to create a similar feature for authenticated users. To enable users to view their private key, developers can use the _arcana_getPrivateKey call to safely retrieve the authenticated user's key share and display the locally generated private key within the app's context.

// Only valid when custom wallet UI is selected in the dashboard
// during app registration

async function onClickGetUserPrivateKey() {
  const authProvider = window.ethereum //assuming setWindowProvider is set when AuthProvider was instantiated 
  try {
    const userPkey = await authProvider.request({
      method: '_arcana_getPrivateKey',
      params: []
    });
    // Do something with the key in custom wallet UI
    // For e.g., display it in the app context, allow user to copy it
  } catch(error) {
        console.log(error);
  };
}

That is all!

The Web3 app is all set to use the custom wallet UI and allow authenticated app users to sign blockchain transactions.

What's Next?

After registering the app, configuring authentication providers, integrating the Arcana Auth SDK with the app and onboarding users, developers can further add code in the app to sign blockchain transactions, send and receive native, ERC20, or custom tokens, and more.

For a complete list of other JSON RPC calls supported by the Arcana wallet, see JSON-RPC Specifications.

See also


Last update: April 12, 2024 by shaloo, shaloo