Skip to content

Latest commit

 

History

History
333 lines (238 loc) · 11.3 KB

README.md

File metadata and controls

333 lines (238 loc) · 11.3 KB
Raw

ElvenJS

One static file to rule it all on the Elrond blockchain!

Demos

Authenticate, sign and send transactions on the Elrond blockchain in the browser. No need for bundlers, frameworks, etc. Just attach the script source, and you are ready to go. You can incorporate it into your preferred CMS framework like WordPress or an e-commerce system. Plus, it will also work on a standard static HTML website.

The primary purpose of this tool is to have a lite script for browser usage where you can authenticate and sign/send transactions on the Elrond blockchain and do this without any additional build steps.

The purpose is to simplify the usage for primary use cases and open the doors for many frontend tools and approaches.

It is a script for browsers incorporates ES6 modules. If you need fully functional JavaScript/Typescript SDK (also in Nodejs), please use erdjs, an official Typescriot Elrond SDK. And if you are React developer, please check the Nextjs dapp.

You can use it already, but it is under active development, and the API might change, and there could be breaking changes.

How to use it

Just copy and include the elven.js script from the build directory (in this repository) or CDN (https://unpkg.com/elven.js/build/elven.js). Use module type, like:

<script type="module">
  import {
    ElvenJS,
    Transaction,
    Address,
    TransactionPayload,
    TokenPayment,
    ContractCallPayloadBuilder,
    ContractFunction,
    U32Value,
  } from './elven.js';

  // Your code here
</script>

or from CDN:

<script type="module">
  import {
    ElvenJS,
    Transaction,
    Address,
    TransactionPayload,
    TokenPayment,
    ContractCallPayloadBuilder,
    ContractFunction,
    U32Value,
  } from 'https://unpkg.com/[email protected]/build/elven.js';

  // Your code here
</script>

Check what exactly is included below:

All exported erdjs classes/types:

(not all is exported from erdjs, and probably never will, but please report all requirements)

  • TokenPayment
  • Address
  • AddressValue
  • Account
  • Transaction
  • TransactionPayload
  • TransactionWatcher
  • BytesValue
  • BigUIntValue
  • U32Value
  • BooleanValue
  • ContractCallPayloadBuilder
  • ESDTTransferPayloadBuilder
  • ESDTNFTTransferPayloadBuilder
  • ContractFunction
  • SmartContract

For now only most used ones.

What else is exposed:

  • ElvenJS.storage - ElvenJS.storage.get(key?), ElvenJS.storage.set(key, value), ElvenJS.storage.clear() - storage helper for localStorage elvenjs_state where couple of information is stored: { address: '', nonce: '', expires: '', loginMethod: '', balance: '' } you can get and set them (be careful, they are used also internally)
  • ElvenJS.networkProvider - access to the simplified network provider which gives some API related helpers, it is also used internally
  • ElvenJS.dappProvider - access to the auth provider instance, it is also used internally
  • ElvenJS.destroy - remove the instances of networkProvider and dappProvider, cleanup

Usage in frontend frameworks

Elven.js from v0.3.0 can also be used in many different frameworks by importing it from node_modules (of course, it is a client-side library). When it comes to React/Nextjs, it is advised to use one of the ready templates, for example, the one mentioned above. But Elven.js can be helpful in other frameworks where there are no templates yet. Example:

npm install elven.js

and then in your client side framework:

import { ElvenJS } from 'elven.js';

The types should also be exported.

Usage example with static website (base demo):

Check out the example file: example/index.html

You will find the whole demo there. The same that is deployed here: elvenjs.netlify.app

What can it do?

The API is limited for now, this will change, but even now, it can do most of the core operations:

  • authenticate using the Maiar mobile and Maiar browser extension
  • handle expiration of the auth state
  • handle login with tokens to be able to get the signature
  • sign transactions
  • send transactions (also custom smart contracts)
  • basic global states handling (local storage)
  • basic structures for transaction payload
  • sync the network on page load
  • querying the smart contracts (without tools for result parsing yet)

What will it do soon? (TODO):

  • authenticate with Ledger Nano
  • authenticate with Elrond Web Wallet
  • result parsing (separate library)
  • sign messages
  • more advanced global state handling and (real-time updates (if needed)?)
  • more structures and simplification for payload builders
  • rethink the structure and split it into more files (???)
  • make it as small as possible, for now, it is pretty big

What it won't probably do:

  • crypto tasks
  • results parsing (but it will land in a separate package)

Why? Because it is supposed to be a browser script, it should be as small as possible. All that functionality can be replaced if needed by a custom implementation or other libraries. There will be docs with examples for that. And in the future, there may be more similar libraries, but optional and separated.

API

Initialize

The main initialization function (init providers, sync the network):

import { ElvenJS } from 'elven.js';

(...)

await ElvenJS.init({
  apiUrl: 'https://devnet-api.elrond.com',
  chainType: 'devnet',
  apiTimeout: 10000,
  onLoginPending: () => { /* Your login pending function call here */ },
  onLoggedIn: () => { /* Your logged in function call here */ },
  onLogout: () => {  /* Your logged out function call here */  },
});

You can define the API endpoint and chain type also the API timeout if needed. These values are set by default. So it will work like that even without them.

Login with auth providers

Login using Maiar mobile app (optionally you can also pass login token, it will be used to generate the signature):

import { ElvenJS } from 'elven.js';

(...)

await ElvenJS.login('maiar-mobile', {
  qrCodeContainerId: 'qr-code-container', // Your qr code container id
  token: '<your_login_token_here>'
});

Login using Maiar browser extension (optionally you can also pass login token, it will be used to generate the signature):

import { ElvenJS } from 'elven.js';

(...)

await ElvenJS.login('maiar-browser-extension', { token: '<your_login_token_here>' });

Logout

Logout using previously initialized provider, here Maiar browser extension.

import { ElvenJS } from 'elven.js';

(...)

const isLoggedIn = await ElvenJS.logout();

Transactions

Transaction builder:

import { ElvenJS, Transaction, Address, TransactionPayload, TokenPayment } from 'elven.js';

(...)

const tx = new Transaction({
  nonce: ElvenJS.storage.get('nonce'),
  receiver: new Address(egldTransferAddress),
  gasLimit: 50000 + 1500 * demoMessage.length,
  chainID: 'D',
  data: new TransactionPayload(demoMessage),
  value: TokenPayment.egldFromAmount(0.001),
  sender: new Address(ElvenJS.storage.get('address')),
});

The API is similar to erdjs, but not all is exported. This could change in the future.

Sign and send transaction using previously initialized provider:

import { ElvenJS } from 'elven.js';

(...)

const transaction = await ElvenJS.signAndSendTransaction(tx);

Here the tx is the transaction from the previous example.

ESDT payload and transaction builder

import { ElvenJS, TokenPayment, ESDTTransferPayloadBuilder, Transaction, Address } from 'elven.js';

(...)

const payment = TokenPayment.fungibleFromAmount(
  'BUILDO-890d14',
  '1',
  18
);
const data = new ESDTTransferPayloadBuilder().setPayment(payment).build();

const tx = new Transaction({
  data,
  gasLimit: 50000 + 1500 * data.length() + 300000,
  receiver: new Address(esdtTransferAddress),
  sender: new Address(ElvenJS.storage.get('address')),
  chainID: 'D',
});

You can use exported helpers/types and build ESDT payloads, it should also work for the NFT/SFT because ESDTNFTTransferPayloadBuilder is also exported.

Interact with smart contracts

import { ElvenJS, ContractCallPayloadBuilder, ContractFunction, U32Valuem, TokenPayment, Address, Transaction } from 'elven.js';

(...)

const data = new ContractCallPayloadBuilder()
  .setFunction(new ContractFunction('mint'))
  .setArgs([new U32Value(1)])
  .build();

const tx = new Transaction({
  data,
  gasLimit: 14000000,
  value: TokenPayment.egldFromAmount(0.01),
  chainID: 'D',
  receiver: new Address(nftMinterSmartContract),
  sender: new Address(ElvenJS.storage.get('address')),
});

Smart contract queries

You can query a smart contract

import { ElvenJS, Address, ContractFunction, AddressValue } from 'elven.js';

(...)

const results = await ElvenJS.queryContract({
  address: new Address(nftMinterSmartContract),
  func: new ContractFunction('getMintedPerAddressTotal'),
  args: [new AddressValue(new Address(minterAddress))]
});

Check for more, complete examples in the example/index.html

Development

  1. clone the repo
  2. npm install dependencies
  3. npm run build
  4. test on example -> npm run dev:server
  5. rebuild with every change in the script

Articles

TODO

Other tools

If you need to use Elrond SDK with React-based projects, you can try these tools:

If you are interested in creating and managing your own PFP NFT collection, you might be interested in:

  • Elven Tools - What is included: NFT minter smart contract (decentralized way of minting), minter Nextjs dapp (interaction on the frontend side), CLI tool (deploy, configuration, interaction)
  • nft-art-maker - tool for creating png assets from provided layers. It can also pack files and upload them to IPFS using nft.storage. All CIDs will be auto-updated

Other tools:

  • Buildo Begins - all Elrond blockchain CLI interactions with erdjs SDK still in progress