Getting started

useElven is a set of hooks and tools designed to work with React-base applications.

The tool is a wrapper for sdk-js - a set of Typescript/Javascript libraries.

What useElven can do?

The fundamental functionality is connecting and logging the user using auth providers. useElven supports all of 4 signing providers.

By default useElven uses @multiversx/sdk-native-auth-client under the hood.

Besides authentication, useElven will also help with all the interactions, like sending native $EGLD tokens or even ESDT tokens. It will allow you to make most transactions, including interactions with custom smart contracts. There is also a possibility to query smart contracts. With an ABI file, you can also decode returned data using React hooks.

How to start using it?

Just to let you know, integrating it with frameworks needs some additional configuration. You'll find examples in ready-to-use starter templates: Vite + React and Next.js template. Check the configuration files in both.

Add useElven to your project:

npm install @useelven/core @multiversx/sdk-core --save

Then import in React app. For example:

import { useNetworkSync } from '@useelven/core';

Initialize (example: Next.js App Router):

import { useNetworkSync } from '@useelven/core';
import { ElvenInit } from './components';

const RootLayout = () => {
  return (
    <html lang="en">
      <body className={inter.className}>
        <ElvenInit />
        (...)
      </body>
    </html>
  );
};

where ElvenInit:

'use client';

import { useNetworkSync } from '@useelven/core';

export const ElvenInit = () => {
  useNetworkSync({
    chainType: 'devnet',
    // If you want to use xPortal signing, 
    // you would need to configure your Wallet Connect project id here: https://cloud.walletconnect.com
    walletConnectV2ProjectId: '<your_wallet_connect_project_id_here>'
  });
  return null;
};

import { useLogin } from '@useelven/core';

(...)

const { login, isLoggedIn, error } = useLogin();

Sign and send transaction:

import { useTransaction } from '@useelven/core';
import { TransactionPayload, TokenTransfer } from '@multiversx/sdk-core';

(...)

const { pending, triggerTx, transaction, txResult, error } = useTransaction();

const handleSendTx = () => {
  const demoMessage = 'Transaction demo!';
  triggerTx({
    address: 'erd123.....',
    // additional 50000 will be added internally when working with guarded accounts
    gasLimit: 50000 + 1500 * demoMessage.length, 
    data: new TransactionPayload(demoMessage),
    value: BigInt('1000000000000000000'),
  });
};

The tools should work with most React setups. For example, with Next.js or React + Vite. But each of the setups requires some additional configuration. This is why there are demo templates that you can clone and treat as a base for your app.

You should always use transaction hooks when you are sure that you are in a signed-in context

Summary

Okay, so you know what useElven is and how to start using it. You are now ready to look at the SDK reference.