Elven.js is a tool designed to work in browsers without any build steps and integrate MultiversX blockchain and smart contracts built on it.
The tool is a wrapper for sdk-js - a set of Typescript/Javascript libraries. But because the sdk-js toolset is quite extensive and has a lot of Node module dependencies, there is a need for a simple browser-only library. The Elven.js aspire to be something like that - a helpful plug-and-play solution that will give you the most basic functionalities.
The fundamental functionality is connecting and logging in the user using auth providers. For now, Elven.js supports three of four existing - The MultiversX browser extension (MultiversX Defi), xPortal Mobile app, and MultiversX Web Wallet. In the future, it will also support Ledger Nano hardware wallet. It also supports xPortal Hub integration and xAlias.
So basically, the user can attach the Elven.js script and start authenticating users on the front end. There is also an option to pass a unique token and get a signature after authentication, which you can use for additional backend verification. You will read more about it in the recipes section.
Besides authentication, Elven.js 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. It allows to sign custom messages. There is also a possibility to query smart contracts. For now, you need to decode the returned data using custom logic, but there will be a separate utility soon.
In the end, the Elven.js library is a simple browser-based JS script. You can copy it from the repository and use it as a local JavaScript file or import it directly from the CDN.
The script is a wrapper for sdk-js, an official JavaScript SDK for usage in the Nodejs ecosystem. JS SDK can also be used in the browser but requires additional build steps and configuration, and the file itself will be huge. This is why Elven.js exists.
Elven.js imports only crucial parts of the sdk-js libraries. It will include the most used parts of the sdk-js, which are essential for the browsers. All other functionality will be split into separate scripts, and it will be shipped as optional scripts in the future.
Internally Elven.js uses Typescript, but finally, it is a standard minified JavaScript file. It can be used in static websites and frameworks like React, SolidJS, or Vue. It is worth mentioning that there are official tools for React already, so it will probably be a better choice to check them. You could also check the MultiversX NextJs dApp template.
Because Elven.js is just a JavaScript file, you can import it from CDN and start using its inner parts. You can also copy the file version from the build directory in the repository.
Let's see how to import it from the CDN:
<html>
<body>
<script type="module">
import { ElvenJS } from 'https://unpkg.com/elven.js@0.20.0/build/elven.js';
const initElven = async () => {
await ElvenJS.init(
{
apiUrl: 'https://devnet-api.multiversx.com',
chainType: 'devnet',
apiTimeout: 10000,
// Remember to change it. Get yours here: https://cloud.walletconnect.com/sign-in
walletConnectV2ProjectId: '<your_wc_project_id_here>',
walletConnectV2RelayAddresses: ['wss://relay.walletconnect.com'],
onLoginStart: () => {},
onLoginSuccess: () => {},
onLoginFailure: (error) => {},
onLogoutStart: () => {},
onLogoutSuccess: () => {},
onLogoutFailure: (error) => {},
onTxStart: (tx) => {},
onTxSent: (tx) => {},
onTxFinalized: (tx) => {},
onTxFailure: (tx, error) => {},
onQrPending: () => {},
onQrLoaded: () => {},
onSignMsgStart: (message) => {},
onSignMsgFinalized: (message, messageSignature) => {},
onSignMsgFailure: (message, error) => {},
onQueryStart: (queryArgs) => {},
onQueryFinalized: (queryResponse) => {},
onQueryFailure: (queryArgs, error) => {}
}
);
}
initElven();
</script>
</body>
</html>
As you can see here, we have a simplified HTML document where we import the Elven.js SDK parts. Always check the version number (the example from here is v0.20.0: elven.js@0.20.0).
You can check the demo examples linked on the homepage.
If you work with a frontend framework for which no tools support the MultiversX blockchain, you can also use the Elven.js tools, installing them as a dependency and then importing from it.
npm install elven.js --save
Example with SolidJs:
import { ElvenJS } from 'elven.js';
(...)
onMount(() => {
const initElven = async () => {
await ElvenJS.init({
apiUrl: 'https://devnet-api.multiversx.com',
chainType: 'devnet',
apiTimeout: 10000,
// Remember to change it. Get yours here: https://cloud.walletconnect.com/sign-in
walletConnectV2ProjectId: '<your_wc_project_id_here>',
walletConnectV2RelayAddresses: ['wss://relay.walletconnect.com'],
onLoginStart: () => {},
onLoginSuccess: () => {},
onLoginFailure: (error) => {},
onLogoutStart: () => {},
onLogoutSuccess: () => {},
onLogoutFailure: (error) => {},
onTxStart: (tx) => {},
onTxSent: (tx) => {},
onTxFinalized: (tx) => {},
onTxFailure: (tx, error) => {},
onQrPending: () => {},
onQrLoaded: () => {},
onSignMsgStart: (message) => {},
onSignMsgFinalized: (message, messageSignature) => {},
onSignMsgFailure: (message, error) => {},
onQueryStart: (queryArgs) => {},
onQueryFinalized: (queryResponse) => {},
onQueryFailure: (queryArgs, error) => {}
});
};
initElven();
});
(...)
Because of the ability to adapt to any frontend framework Elven.js is an excellent choice for all widget-like implementations. Imaging WordPress or Shopify plugins with it. Or, for example, simple donation widgets for static hobby websites.
Okay, so you know what Elven.js is and how to start using it. You are now ready to look at the SDK reference and recipes.
Also, there are a lot of links to the demo applications on the homepage, so you could also check the code of each one.