Connectivity SDK

The Elastos Connectivity SDK (@elastosfoundation/elastos-connectivity-sdk-js) is the browser-side bridge between your dApp and Elastos identity wallets. It does not implement wallet cryptography itself; it defines how dApps call into connectors that talk to Essentials, local test identities, or your own wallet integration.

What you get out of the box

The package exports a connectivity singleton, namespaces such as DID, Wallet, Hive, and UX, and TypeScript typings for IConnector. Operations route through the active connector (or window.elastos when a wallet injects itself in an in-app browser).

What is the Connectivity SDK?

A TypeScript/JavaScript library that unifies dApp ↔ wallet communication (production use is typically with Elastos Essentials).
One API surface for DID authentication (verifiable presentations), on-chain operations (via WalletAccess and EVM providers), credential flows, and Hive-related identity hooks (App Instance DID and App ID credentials).
A connector pattern: each connector implements IConnector, which extends IDIDConnectorAPI, IWalletConnectorAPI, and IUXConnectorAPI, and exposes getWeb3Provider() for EVM-compatible calls.
Built-in Local Identity connector (no external app) for onboarding and constrained environments; Essentials via @elastosfoundation/essentials-connector-client-browser; custom connectors by implementing IConnector.

Installation

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

For Essentials on the web, install the browser connector package as well:

npm install @elastosfoundation/essentials-connector-client-browser

Core concepts

Connectors

The IConnector interface requires a name, getDisplayName(): Promise<string>, and getWeb3Provider(): any (Ethereum/EVM JSON-RPC provider). DID and wallet methods are declared on the composite interfaces above.

Essentials: mobile app via intent URLs, WalletConnect-style sessions, or window.elastos injection inside Essentials’ browser.
Local Identity: SDK-provided path for a local, unpublished DID and limited flows (see internal connector list via connectivity.getAvailableConnectors() after registration).
Custom: supply your own IConnector implementation and connectivity.registerConnector().

Registration

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

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

With multiple connectors, the default UI can prompt the user; with one connector, activation is typically automatic. You can also call connectivity.setActiveConnector("…") using the connector’s name.

Application DID

Call connectivity.setApplicationDID("did:elastos:…") with your published app DID before flows that need Hive App ID credentials or wallet branding; getApplicationDID() throws if it was never set.

DID authentication

Use DID.DIDAccess and requestCredentials() with a CredentialDisclosureRequest (claims, optional nonce / realm, customization). Helpers such as DID.standardNameClaim, DID.standardEmailClaim, DID.simpleIdClaim, and DID.simpleTypeClaim build claim entries.

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

const didAccess = new DID.DIDAccess();

const presentation = await didAccess.requestCredentials({
  claims: [
    DID.standardNameClaim("Your name"),
    DID.standardEmailClaim("Your email", false),
    // Or match a credential id: DID.simpleIdClaim("Your name", "name", false),
  ],
});

if (presentation) {
  const holder = presentation.getHolder();
  const methodSpecificId = holder.getMethodSpecificId(); // e.g. EID user id fragment
  const credentials = presentation.getCredentials();
  // Verify nonce/realm if your server issued them; inspect credentials.
}

Deprecated path

getCredentials() is deprecated in typings in favor of requestCredentials().

Nonce and realm

If you omit nonce and realm, the SDK can generate them and validate the returned presentation. For server-backed login, pass your challenge and origin explicitly so you can verify them after requestCredentials() resolves.

Credential management

Beyond reading credentials, DID.DIDAccess supports writing, issuing, deleting, and publishing operations. All of these route through the active connector to the wallet for user approval.

Import credentials into a user's DID

Applications generate credentials with the DID SDK and then ask the wallet to add them to the user's profile. The user can keep them private (device-only) or publish them on-chain.

import { DID as ConnDID } from "@elastosfoundation/elastos-connectivity-sdk-js";
import {
  DID,
  DIDBackend,
  DIDStore,
  Issuer,
  Mnemonic,
  RootIdentity,
  VerifiableCredential,
} from "@elastosfoundation/did-js-sdk";

DIDBackend.initialize(
  new ConnDID.ElastosIODIDAdapter(ConnDID.ElastosIODIDAdapterMode.MAINNET)
);

const didStore = await DIDStore.open("app-did-store");
const rootIdentity = RootIdentity.createFromMnemonic(
  Mnemonic.getInstance().generate(),
  "",
  didStore,
  "storepass",
  true
);

const issuerDID = await rootIdentity.newDid("storepass", 0, true);
const issuer = new Issuer(issuerDID);

// Target DID obtained from a prior requestCredentials() call
const targetDID = DID.from("did:elastos:iUserDIDString");

const credential = await new VerifiableCredential.Builder(issuer, targetDID)
  .id("#diploma")
  .properties({ year: "2024", speciality: "Engineering" })
  .type("DiplomaCredential")
  .seal("storepass");

const didAccess = new ConnDID.DIDAccess();
const importedCredentials = await didAccess.importCredentials([credential], {
  forceToPublishCredentials: true,
});

Server-side signing

In production, create credentials on your server (where the issuer's private key lives). Then send them to the client for the importCredentials() call.

Issue a credential through the wallet

Ask the connected wallet to sign and return a credential on behalf of the user. Useful when the user is the issuer (e.g., a doctor signing a prescription).

const didAccess = new ConnDID.DIDAccess();

const issuedCredential = await didAccess.issueCredential(
  "did:elastos:iRecipientDID",   // credential subject
  ["PrescriptionCredential"],     // credential types
  {
    drug: "Amoxicillin",
    quantity: 30,
    frequency: "Twice per day",
  },
  "prescription"                  // credential name fragment
);

Delete credentials

Request the wallet to remove specific credentials from the user's DID profile. The user confirms or rejects.

const didAccess = new ConnDID.DIDAccess();

const deletedCredentials = await didAccess.deleteCredentials([
  "#email",
  "#obsoleteCredential",
]);

Publish DID document

Trigger the wallet to publish the user's latest DID document to the EID chain. Returns the transaction ID on success.

const didAccess = new ConnDID.DIDAccess();
const txId = await didAccess.requestPublish();

Sign arbitrary data

Sign any string with the user's DID. The response includes the DID string, public key, signature, and a JWT wrapping the result.

const didAccess = new ConnDID.DIDAccess();

const signedData = await didAccess.signData(
  "data-to-sign",
  { extraField: 123 },       // additional JWT claims (optional)
  "customSignatureField"      // JWT signature field name (optional)
);

// signedData contains: did, publicKey, signature, jwtToken

ElastosIO DID Adapter

The SDK includes a convenience DID resolver adapter that talks to the elastos.io identity node. Use it when initializing DIDBackend without running your own EID node.

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

// Mainnet
const adapter = new DID.ElastosIODIDAdapter(DID.ElastosIODIDAdapterMode.MAINNET);

// Testnet
const adapter = new DID.ElastosIODIDAdapter(DID.ElastosIODIDAdapterMode.TESTNET);

Pass the adapter to DIDBackend.initialize() from the DID JS SDK.

Ethereum provider (ESC / EVM)

Every IConnector exposes getWeb3Provider() for eth_* JSON-RPC usage (Web3, ethers, etc.).

Essentials additionally exposes getWalletConnectProvider() (legacy WalletConnect v1, end-of-life; migrate to v2) plus helpers like hasWalletConnectSession() / disconnectWalletConnect(); see @elastosfoundation/essentials-connector-client-browser typings. For new integrations, use WalletConnect v2.

import { BrowserProvider, parseEther } from "ethers";

const web3Provider = essentialsConnector.getWeb3Provider();
const provider = new BrowserProvider(web3Provider);
const signer = await provider.getSigner();
const address = await signer.getAddress();

await signer.sendTransaction({
  to: "0x…",
  value: parseEther("1.0"),
});

Native payments and voting (`WalletAccess`)

For ELA transfers and related flows exposed by the wallet connector, use Wallet.WalletAccess. The connector implements pay(query: PayQuery) on IWalletConnectorAPI; the result includes a transaction id and TransactionStatus.

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

const walletAccess = new Wallet.WalletAccess();

const result = await walletAccess.pay({
  amount: 1.5,
  receiver: "E…", // ELA address from your integration
  currency: "ELA",
  memo: "Service payment",
});

if (result.status !== "cancelled") {
  console.log(result.txId);
}

voteForDPoS, voteForCRCouncil, and voteForCRProposal exist on the connector interface so the wallet can open governance UIs; behavior depends entirely on the active connector.

Hive vault access

In published 1.1.x typings, Hive.HiveAccess only declares changeHiveProvider(); there is no getVault() on this class. End-to-end vault access uses @elastosfoundation/hive-js-sdk together with the App Instance DID and App ID credential flow on DID.DIDAccess (e.g. getOrCreateAppInstanceDID(), generateAppIdCredential(), getExistingAppIdentityCredential()) after connectivity.setApplicationDID().

Hive.DataSync

The SDK also exports Hive.DataSync helpers for syncing app state with vault data; wire them after authentication with the Hive JS SDK.

UI customization

connectivity.setApplicationDID("did:elastos:iYourAppDID");
connectivity.setGenericUIHandler(customUIHandler); // implements IGenericUIHandler

Override the default Svelte-based connector chooser and related prompts when you need a fully branded UX.

Wallet onboarding (`UXAccess`)

UX.UXAccess exposes onBoard?(feature, title, introduction, button) (optional on the typings; verify your target connector implements it). It asks the wallet to show a first-run style screen for a feature id; unsupported features should fail softly inside the wallet.

Error handling

Failures surface as rejected promises or connector-specific results. For example, Wallet.WalletAccess.pay() returns a TransactionResult whose status uses TransactionStatus (values such as Cancelled and Error appear in typings; some connectors may reuse string values; always branch on the returned status and txId fields).

The SDK does not ship three fixed error classes literally named UserCancelled, ConnectorNotRegistered, and WalletNotAvailable in the published @elastosfoundation/elastos-connectivity-sdk-js typings. Instead, map operational problems in your app layer:

Situation	What to check
User cancelled	Rejected promise from DID/Wallet calls, or `result.status === "cancelled"` from `pay()`
No connector	`connectivity.getActiveConnector()` returns `null` before invoking APIs
Wallet unavailable	Connector-specific errors when the mobile app is missing or deep link fails

Always try/catch async calls and log error.message (and cause, if present) for support.

Architecture

┌────────┐     ┌─────────────────────┐     ┌────────────┐     ┌──────────────────┐
│  dApp  │ ──► │ Connectivity SDK    │ ──► │ IConnector │ ──► │ Essentials wallet │
└────────┘     │ (connectivity API)  │     └────────────┘     │ (intents / WC)    │
               └─────────────────────┘            │          └──────────────────┘
                                                  │
                                                  ├──► Local Identity (in-SDK)
                                                  │
                                                  └──► Custom connector

ConnectivityHelper.ensureActiveConnector() (used internally) blocks DID/Wallet/Hive entry points until a connector is active or the user picks one, which aligns with the Svelte default UI or your IGenericUIHandler.

Optional shortcut: if window.elastos implements IConnector, getActiveConnector() can resolve to it ahead of the registered connector, which is useful inside Essentials’ embedded browser.

Switching connectors

When setActiveConnector() / unregisterConnector() run, the SDK clears per-connector context (for example Hive App ID credential state) so data does not leak between wallets. Plan UX so users understand reconnecting after a switch.

What is the Connectivity SDK?​

Installation​

Core concepts​

Connectors​

Registration​

DID authentication​

Credential management​

Import credentials into a user's DID​

Issue a credential through the wallet​

Delete credentials​

Publish DID document​

Sign arbitrary data​

ElastosIO DID Adapter​

Ethereum provider (ESC / EVM)​

Native payments and voting (WalletAccess)​

Hive vault access​

UI customization​

Wallet onboarding (UXAccess)​

Error handling​

Architecture​