Quick Start: Build a dApp That Connects to Essentials

Elastos Essentials is a mobile super-wallet built on Ionic/Angular/Cordova. It injects multiple Web3 providers into the browser context for dApps running inside it.

Injected Providers

When your dApp runs inside Essentials, the following globals are available:

Global	Purpose
window.ethereum	Standard EIP-1193 provider for ESC/EID (secp256k1)
window.elastos	Elastos-specific provider for DID operations, Hive access
window.elamain	Provider for main chain ELA operations (P-256)
window.unisat	Bitcoin-compatible provider

Connectivity SDK Setup

For dApps running outside Essentials (standard browsers), use the Connectivity SDK to establish a connection via WalletConnect:

npm install @elastosfoundation/elastos-connectivity-sdk-js

import { connectivity } from "@elastosfoundation/elastos-connectivity-sdk-js";

// Register the Essentials connector
import { EssentialsConnector } from "@elastosfoundation/essentials-connector-client-browser";

const essentialsConnector = new EssentialsConnector();
connectivity.registerConnector(essentialsConnector);

Requesting DID Credentials

import { DID } from "@elastosfoundation/elastos-connectivity-sdk-js";

async function requestUserDID(): Promise<DID.Credential[]> {
  const didAccess = new DID.DIDAccess();

  const presentation = await didAccess.requestCredentials({
    claims: [
      DID.standardNameClaim("Your name", false),
      DID.standardEmailClaim("Your email", false),
      {
        reason: "To verify your identity",
        credential: {
          type: "BasicProfileCredential",
          issuers: [],
          required: true,
        },
      },
    ],
  });

  if (!presentation) {
    throw new Error("User rejected the credential request");
  }

  return presentation.getCredentials();
}

tip

For more on DID credentials and verification, see DID Integration.

Connecting to ESC via Essentials

import { ethers } from "ethers";

async function connectToESC(): Promise<ethers.BrowserProvider> {
  // Inside Essentials, window.ethereum is injected automatically
  if (!window.ethereum) {
    throw new Error("No Ethereum provider found. Open this dApp in Essentials.");
  }

  const provider = new ethers.BrowserProvider(window.ethereum);
  const accounts = await provider.send("eth_requestAccounts", []);
  console.log("Connected account:", accounts[0]);

  const network = await provider.getNetwork();
  if (network.chainId !== 20n) {
    // Request switch to ESC
    await window.ethereum.request({
      method: "wallet_switchEthereumChain",
      params: [{ chainId: "0x14" }],
    });
  }

  return provider;
}

Signing a Transaction

async function sendELA(provider: ethers.BrowserProvider, to: string, amount: string): Promise<string> {
  const signer = await provider.getSigner();
  const tx = await signer.sendTransaction({
    to,
    value: ethers.parseEther(amount),
  });
  const receipt = await tx.wait();
  return receipt!.hash;
}

WalletConnect v2 Integration

For connecting from a standard web browser to a user's Essentials wallet on their phone:

import { EssentialsConnector } from "@elastosfoundation/essentials-connector-client-browser";

const connector = new EssentialsConnector();

// WalletConnect v2 configuration
await connector.setWalletConnectV2({
  projectId: "YOUR_WALLETCONNECT_PROJECT_ID",
  relayUrl: "wss://relay.walletconnect.com",
  metadata: {
    name: "My Elastos dApp",
    description: "A dApp built on Elastos",
    url: "https://mydapp.com",
    icons: ["https://mydapp.com/icon.png"],
  },
});

// This triggers a QR code or deep link to Essentials
const accounts = await connector.connect();
console.log("Connected:", accounts);

// Get an ethers provider from the connector
const provider = new ethers.BrowserProvider(connector.getProvider());

Full dApp Example

import { ethers } from "ethers";
import { connectivity, DID } from "@elastosfoundation/elastos-connectivity-sdk-js";
import { EssentialsConnector } from "@elastosfoundation/essentials-connector-client-browser";

class ElastosDApp {
  private provider: ethers.BrowserProvider | null = null;
  private connector: EssentialsConnector;

  constructor() {
    this.connector = new EssentialsConnector();
    connectivity.registerConnector(this.connector);
  }

  async connect(): Promise<string> {
    if (window.ethereum) {
      this.provider = new ethers.BrowserProvider(window.ethereum);
    } else {
      await this.connector.connect();
      this.provider = new ethers.BrowserProvider(this.connector.getProvider());
    }

    const accounts = await this.provider.send("eth_requestAccounts", []);
    return accounts[0];
  }

  async getUserDID(): Promise<string | null> {
    const didAccess = new DID.DIDAccess();
    const presentation = await didAccess.requestCredentials({
      claims: [DID.standardNameClaim("Name", false)],
    });

    if (!presentation) return null;

    return presentation.getHolder().toString();
  }

  async callContract(address: string, abi: string[], method: string, args: unknown[]): Promise<unknown> {
    if (!this.provider) throw new Error("Not connected");

    const signer = await this.provider.getSigner();
    const contract = new ethers.Contract(address, abi, signer);
    const tx = await contract[method](...args);

    if (tx.wait) {
      const receipt = await tx.wait();
      return receipt;
    }
    return tx;
  }

  async disconnect(): Promise<void> {
    await this.connector.disconnect();
    this.provider = null;
  }
}