DEV Community: Julian.io

Consistent UI with AI prompts

Julian.io — Tue, 03 Feb 2026 14:41:51 +0000

AI is fast until it starts freelancing your design

If you’ve built UI with an AI assistant for more than a day, you’ve probably seen the pattern: the first version looks fine, but the next prompt produces a different button style, a new spacing scale, and "helpfully" adds a whole new styling approach you never asked for. You ship faster, but your UI starts drifting.

The fix is not better vibes. The fix is clear constraints + a reusable spec + a prompt you can reuse. The good news: you don't need a framework-specific setup to do this. You just need to be explicit about what the assistant must detect, what it must reuse, and what it must not introduce.

Two rules that prevent "AI UI drift"

1) Force detection before coding

Instead of telling the assistant "use Tailwind", make it inspect your project first: your package.json, existing components, config files, and style imports. That's how it learns what you already use - and avoids guessing.

2) Enforce "use only what's already in the project"

Most UI inconsistency comes from the assistant mixing approaches. You want one clear rule: reuse the detected styling system and match existing component patterns. No new styling system, no ad-hoc "just this one CSS file," no surprise UI kit.

This single constraint does more for consistency than any "make it look modern" prompt ever will.

What to paste into the AI: a spec, not a library

When you give the assistant a detailed UI guide (dimensions, states, responsive behavior, accessibility requirements, testing checklist), it has less room to invent. It's working from a concrete blueprint rather than its own preferences.

A reusable prompt template you can keep in a snippet

You can paste this into ChatGPT or Claude and reuse it any time you implement UI. The key is that it is constraint-first and project-aware.

You are implementing a UI component in my existing project.

1) First, DETECT my setup before writing code:
- Determine the framework (if any) and the current styling system by checking package.json, existing components, config files, and style imports.
- If detection is uncertain, ask me what framework/styling approach I want.

2) Constraints (must follow):
- Use ONLY what is already in the project for styling. Do not introduce a new styling system or ad-hoc CSS approach.
- Match existing component patterns exactly (file structure, naming conventions, and how components are composed).
- Do not add new dependencies unless I explicitly approve.

3) Implementation requirements:
- Follow the provided component guide/spec exactly: structure, dimensions, behavior, states, and responsive breakpoints.
- Include accessibility requirements (ARIA semantics and keyboard navigation) as described in the guide.
- Include or outline a testing checklist aligned with the guide.

4) Output:
- Provide the implementation steps briefly, then the code.
- Keep the code production-ready and consistent with the project’s existing patterns.

A concrete spec example the AI can actually follow

A good stress test is something easy to get wrong: an accessible dropdown/select with search, multi-select, loading and error states, and correct keyboard behavior.

Here's an example spec you can paste in as the source of truth:
https://uipotion.com/potions/components/dropdown-select.json

Even if you don't build that exact component, it's a great template for what good spec looks like: clear structure, complete states, and explicit accessibility expectations. Fewer gaps = less improvisation.

The small habit that keeps everything consistent

Consistency comes from repetition and constraints - not from writing longer prompts.

Make the assistant detect first. Make it reuse what’s already there. Give it a spec it can't "interpret creatively."

That's how you keep AI fast without letting it rewrite your design system on the side.

Creating NFTs with MultiversX Blockchain Using JavaScript SDK

Julian.io — Sat, 21 Sep 2024 18:00:56 +0000

In the fifth article in the series, let's focus on token management—specifically, non-fungible token management. We will issue the collection, set roles, and create an NFT using some scripts and the MultiversX JavaScript SDK. Let's jump in.

The codebase for this one is bigger, so I will only paste some of it here. You can check the full working example in the GitHub repository. Let's discuss three main functions that we will trigger in exactly that order: issueNftCollection - issue a collection token setSpecialRolesForNft - set special roles for the collection createNft - create an actual NFT Each function reuses the same code, so there are also helper functions. Let's start with the first one.

Issuing the collection token

The collection token is an umbrella for all the NFTs you want to create within it. It can have its unique properties and roles. I won't focus on that much because it is all in the docs. Let's see how we can issue such a token.

Here is what our function will look like:

const issueNftCollection = () => {
  const factory = getTransactionFactory();

  const transaction = factory.createTransactionForIssuingNonFungible({
    canAddSpecialRoles: true,
    canChangeOwner: true,
    canFreeze: true,
    canPause: true,
    canTransferNFTCreateRole: true,
    canUpgrade: true,
    canWipe: true,
    sender: new Address(senderAddress),
    tokenName: collectionName,
    tokenTicker: collectionTicker,
 });

  processTransaction(transaction, "issue");
};

Let's go step by step, including the getTransactionFactory and processTransaction helper functions. The first one is responsible for creating the transaction factory, which is the same for all three functions, so it will always be used similarly. Let's see what it looks like:

import { TransactionsConverter, TokenManagementTransactionsOutcomeParser } from '@multiversx/sdk-core';
(...)
const getTransactionFactory = () => {
  const factoryConfig = new TransactionsFactoryConfig({ chainID: "D" });
  const factory = new TokenManagementTransactionsFactory({
    config: factoryConfig,
 });
  return factory;
};

It's quite straightforward and similar to the previous operations in previous articles. We use TransactionsFactoryConfig and then pass it to the special factory responsible for token management (TokenManagementTransactionsFactory). We will use this to build all three of our transactions for issuing, setting roles, and creating the NFT.

With the transaction factory, we can start using different methods that are responsible for token management. What we need here is createTransactionForIssuingNonFungible. As you can see above, we can use it to provide all required information, like collection properties (read more about them in the docs), token name, and ticker.

When we have the transaction data prepared, we need to do a couple of things, like serialization for signing, signing, and broadcasting the transaction. It is the same for all three transactions. It is why we have another helper function: processTransaction, and we will take a closer look at it now:

import {
  TransactionComputer,
} from "@multiversx/sdk-core";
import {
  syncAndGetAccount,
  getSigner,
  apiNetworkProvider,
} from "./setup.js";

(...)

const processTransaction = async (transaction, type) => {
  const user = await syncAndGetAccount();
  const computer = new TransactionComputer();
  const signer = await getSigner();

  // Increase the nonce
  transaction.nonce = user.getNonceThenIncrement();

  // Serialize the transaction for signing
  const serializedTransaction = computer.computeBytesForSigning(transaction);

  // Sign the transaction with our signer
  transaction.signature = await signer.sign(serializedTransaction);

  // Broadcast the transaction
  const txHash = await apiNetworkProvider.sendTransaction(transaction);

  await parseOutcome(txHash, type);

  console.log(
    "Check in the Explorer: ",
    `https://devnet-explorer.multiversx.com/transactions/${txHash}`
 );
};

These operations are almost the same as in previous articles because they are required for every transaction. So, we use our user, signer, and computer to sign and broadcast the transaction. The user and signer are prepared in the setup.js file and imported here. Check the first article for more information about them. You will also find the file in the repository.

To demonstrate how to parse the outcome from such a transaction, we have another helper function called parseOutcome, and let's jump to its code right away:

import {
  TokenManagementTransactionsOutcomeParser,
  TransactionsConverter,
  TransactionWatcher,
} from "@multiversx/sdk-core";

(...)

const parseOutcome = async (txHash, type) => {
  console.log("Pending...");

  // Get the transaction on network, we need to wait for results here, we use TransactionWatcher for that
  const transactionOnNetwork = await new TransactionWatcher(
    apiNetworkProvider
 ).awaitCompleted(txHash);

  // Parse the outcome
  const converter = new TransactionsConverter();
  const parser = new TokenManagementTransactionsOutcomeParser();
  const transactionOutcome =
    converter.transactionOnNetworkToOutcome(transactionOnNetwork);

  let parsedOutcome;

  if (type === "issue") {
    parsedOutcome = parser.parseIssueNonFungible(transactionOutcome);

    console.log(`Token identifier: ${parsedOutcome?.[0]?.tokenIdentifier}`);
 }
  if (type === "create") {
    parsedOutcome = parser.parseNftCreate(transactionOutcome);

    console.log(
      `Token identifier: ${parsedOutcome?.[0]?.tokenIdentifier} Nonce: ${parsedOutcome?.[0]?.nonce}`
 );
 }
};

It takes the transaction hash and operation type (because they are all used in three different functions, and we want to differentiate the result). Then it uses a specific parser (TokenManagementTransactionsOutcomeParser). It is all a wrapper for the outcome result that needs to be parsed. Otherwise, you would need to do this by hand, which could be more complex. The output of this helper function is to get the token ID and, in the case of NFT creation, also the nonce, which differentiates the NFTs. Here, we only log them to the console.

And that's it. You've issued the NFT collection token.

Set special roles

Next, we need to add special roles. At least an NFTCreate role is required to create NFTs, but there is much more. You can find more information about the roles in the documentation. For now, let's see the second function:

const setSpecialRolesForNft = () => {
  const factory = getTransactionFactory();

  const transaction =
    factory.createTransactionForSettingSpecialRoleOnNonFungibleToken({
      addRoleNFTCreate: true,
      addRoleNFTBurn: true,
      addRoleNFTAddURI: true,
      addRoleNFTUpdateAttributes: true,
      addRoleESDTTransferRole: false,
      sender: new Address(senderAddress),
      tokenIdentifier: collectionId,
      user: new Address(senderAddress), // The owner of the role, in our case, the same as the sender
 });

  processTransaction(transaction);
};

Again, we use the same factory creation helper function. However, the method for building the transaction is different. It is createTransactionForSettingSpecialRoleOnNonFungibleToken (what a long name!). As you can see, you can define all possible roles here. You need to provide the collection ID as the token identifier, and what is important is that you can also provide any address that will get that role. So it can be the address of the collection owner, and usually, it is like that, but it can also be another address/wallet. Processing the transaction is the same as previously.

Creating the NFT

The last function is the actual creation of the NFT, where you need to provide the attributes, URLs for your assets, and other data, such as royalties cut. Here are some important tips, but first, let's see the code.

const createNft = () => {
  const factory = getTransactionFactory();

  const attributes = new TextEncoder().encode(
    "metadata:bafybeihof6n2b4gkahn2nwfhcxe72kvms4o5uevcok5chvg6f2zpfsi6hq/33.json"
 );
  const hash = "";

  const transaction = factory.createTransactionForCreatingNFT({
    // You can read more about attributes in the docs. The data should be in the proper format to be picked up by MultiversX services like Explorer, etc.
    attributes,
    hash, // It can be any hash, for example hash of the attributes, images, etc. (not mandatory)
    initialQuantity: 1n, // It will always be 1 (BigInt) for NFT
    name: "Some NFT name for the token",
    royalties: 500, // number from 0 to 10000 where 10000 is 100%
    sender: new Address(senderAddress),
    tokenIdentifier: collectionId,
    uris: [
      "https://ipfs.io/ipfs/bafybeibimqon4pjm54x27n6we5qohx57gd6n2mnbkxu2r6nejp3nbenk7u/33.png",
      "https://ipfs.io/ipfs/bafybeihof6n2b4gkahn2nwfhcxe72kvms4o5uevcok5chvg6f2zpfsi6hq/33.json",
 ],
 });

  // Very custom gasLimit calculation. Sometimes (like in this case), the built-in gas calculation isn't enough
  // Check docs for more info on how gas limits are calculated
  // Anyway, you can define your own value through transaction.gasLimit
  transaction.gasLimit = BigInt(
    transaction.data.length * 1500 +
 (attributes?.length || 0 + hash?.length || 0) * 50000
 );

  processTransaction(transaction, "create");
};

The MultiversX APIs, Explorer, xSpotlight, and other services will 'prefer' URLs with the default IPFS gateway, as shown in the video and example code. The same goes for the attributes; you can keep there whatever you want, but it is good to keep the metadata information in the form of IPFS CID and file name of the JSON data, like: metadata:bafybeihof6n2b4gkahn2nwfhcxe72kvms4o5uevcok5chvg6f2zpfsi6hq/33.json, plus other data, for example with tags: metadata:bafybeihof6n2b4gkahn2nwfhcxe72kvms4o5uevcok5chvg6f2zpfsi6hq/33.json;tags:tag1. You can also read about it in the documentation.

Anyway, let's get back to our last function. It's the same factory with a different method, which in this case is createTransactionForCreatingNFT. With this, we can provide all the required data, as seen in the example. What is nonstandard here is that I had to overwrite the gas limit to create a transaction. The factory normally handles it, but I needed more than the default calculation for the gas limit. The good part is that you can always overwrite it, like adding a new BigInt value to your transaction object like transaction.gasLimit = <BigUint value>. Read more about the gass calculation in the docs.

Summary

It is not complete code to copy and paste, but we discussed the most crucial parts for creating NFTs with the MultiversX JavaScript SDK. The main steps are issue, roles, and creation. The whole working example is linked below. You'll also find a full walkthrough video with voice-over comments.

As always, feel free to contact me on X or by e-mail. Please check the tools I maintain: the Elven Family and Buildo.dev. With Buildo, you can perform many management operations using a nice web UI. You can issue fungible and non-fungible tokens. You can also perform other operations, like multi-transfers or claiming developer rewards. There is much more.

Check the video. Please subscribe on X, GitHub, and YouTube. Thanks.

Walkthrough video

The demo code

learn-multiversx-js-sdk-with-examples

Step-by-step guide to MultiversX smart contract interactions with JavaScript SDK

Julian.io — Sun, 30 Jun 2024 11:14:07 +0000

In the fourth article of the series on MultiversX JavaScript SDK, we will examine how to interact with deployed smart contracts. As in the previous article, where we tackled smart contract deployment, we will use the Piggy Bank smart contract as an example.

The script is more complex than the previous ones because we will handle calls for three different functions on the smart contract: createPiggy, addAmount, and getLockedAmount. The first two are write functions, and the third one is a read function.

Again, let's see the whole script first, and we will go through it step by step.

import { promises } from "node:fs";
import {
  Address,
  SmartContractTransactionsFactory,
  TransactionsFactoryConfig,
  TransactionComputer,
  AbiRegistry,
  QueryRunnerAdapter,
  SmartContractQueriesController,
} from "@multiversx/sdk-core";
import {
  syncAndGetAccount,
  senderAddress,
  getSigner,
  apiNetworkProvider,
} from "./setup.js";

/**
 * Replace with your own deployed piggy bank smart contract
 * check deploy-smart-contract.js on how to deploy one
 */
const PIGGYBANK_CONTRACT_ADDRESS =
  "erd1qqqqqqqqqqqqqpgqtrajzw4vq0zxccdt9u66cvgg6vz8c6cwnegqkfqkpq";

/**
 * Load ABI file
 */
const getAbi = async () => {
  const abiFile = await promises.readFile("./piggybank.abi.json", "UTF-8");
  return JSON.parse(abiFile);
};

const scTransaction = async ({ functionName, args, amount }) => {
  const user = await syncAndGetAccount();
  const computer = new TransactionComputer();
  const signer = await getSigner();

  const abiObj = await getAbi();

  const factoryConfig = new TransactionsFactoryConfig({ chainID: "D" });
  const factory = new SmartContractTransactionsFactory({
    config: factoryConfig,
    abi: AbiRegistry.create(abiObj),
 });

  const transaction = factory.createTransactionForExecute({
    sender: new Address(senderAddress),
    contract: Address.fromBech32(PIGGYBANK_CONTRACT_ADDRESS),
    function: functionName,
    gasLimit: 5000000,
    arguments: args || [],
    nativeTransferAmount: amount,
 });

  // Increase the nonce
  transaction.nonce = user.getNonceThenIncrement();

  // Serialize the transaction for signing
  const serializedTransaction = computer.computeBytesForSigning(transaction);

  // Sign the transaction with out signer
  transaction.signature = await signer.sign(serializedTransaction);

  // Broadcast the transaction
  const txHash = await apiNetworkProvider.sendTransaction(transaction);

  console.log(
    "Check in the Explorer: ",
    `https://devnet-explorer.multiversx.com/transactions/${txHash}`
 );
};

/**
 * Call the createPiggy endpoint on the PiggyBank smart contract
 * https://github.com/xdevguild/piggy-bank-sc/blob/master/src/lib.rs#L25
 * We pass the unix timestamp in the future
 */
const createPiggy = async () => {
  await scTransaction({
    functionName: "createPiggy",
    args: [1750686756],
 });
};

/**
 * Call the addAmount endpoint on the PiggyBank smart contract
 * https://github.com/xdevguild/piggy-bank-sc/blob/master/src/lib.rs#L42
 */
const addAmount = async () => {
  await scTransaction({
    functionName: "addAmount",
    amount: 1000000000000000n,
 });
};

/**
 * Query the getLockedAmount endpoint on the PiggyBank smart contract
 * https://github.com/xdevguild/piggy-bank-sc/blob/master/src/lib.rs#L92
 */
const getLockedAmount = async () => {
  const abiObj = await getAbi();

  const queryRunner = new QueryRunnerAdapter({
    networkProvider: apiNetworkProvider,
 });

  const controller = new SmartContractQueriesController({
    queryRunner: queryRunner,
    abi: AbiRegistry.create(abiObj),
 });

  const query = controller.createQuery({
    contract: PIGGYBANK_CONTRACT_ADDRESS,
    function: "getLockedAmount",
    arguments: [senderAddress],
 });

  const response = await controller.runQuery(query);

  const [amount] = controller.parseQueryResponse(response);

  // The returned amount is a BigNumber
  console.log("Locked amount is: ", amount.valueOf());
};

/**
 * Here we will manage which function to call
 */
const smartContractInteractions = () => {
  const args = process.argv.slice(2);
  const functionName = args[0];

  const functions = {
    createPiggy,
    addAmount,
    getLockedAmount,
 };

  if (functionName in functions) {
    functions[functionName]();
 } else {
    console.log("Function not found!");
 }
};

smartContractInteractions();

We have a scTransaction function, which is our common helper for the first two smart contract calls: createPiggy and addAmount. Let's analyze it first. Remember to watch the video embedded at the end of this article, where you'll see each step in detail.

const scTransaction = async ({ functionName, args, amount }) => {
  const user = await syncAndGetAccount();
  const computer = new TransactionComputer();
  const signer = await getSigner();

  const abiObj = await getAbi();

  const factoryConfig = new TransactionsFactoryConfig({ chainID: "D" });
  const factory = new SmartContractTransactionsFactory({
    config: factoryConfig,
    abi: AbiRegistry.create(abiObj),
 });

  const transaction = factory.createTransactionForExecute({
    sender: new Address(senderAddress),
    contract: Address.fromBech32(PIGGYBANK_CONTRACT_ADDRESS),
    function: functionName,
    gasLimit: 5000000,
    arguments: args || [],
    nativeTransferAmount: amount,
 });

  // Increase the nonce
  transaction.nonce = user.getNonceThenIncrement();

  // Serialize the transaction for signing
  const serializedTransaction = computer.computeBytesForSigning(transaction);

  // Sign the transaction with our signer
  transaction.signature = await signer.sign(serializedTransaction);

  // Broadcast the transaction
  const txHash = await apiNetworkProvider.sendTransaction(transaction);

  console.log(
    "Check in the Explorer: ",
    `https://devnet-explorer.multiversx.com/transactions/${txHash}`
 );
};

The scTransaction provides common logic for each smart contract write function. It looks similar to the transactions in previous articles. We prepare the transaction using a dedicated transaction factory. We increment the nonce, prepare for signing, sign, and broadcast the transaction.

What is different is that we use the SmartContractTransactionsFactory and then createTransactionForExecute which prepares the transaction for our functions on smart contract. It takes the sender, smart contract address, function name, and gas limit as arguments. Optionally, where required, you can pass arguments for the smart contract function, and if you need to send some native EGLD token amount, you can also do that with nativeTransferAmount. You'll see an example soon. Of course, we also need the address of the deployed smart contract. You can deploy yours using the deploy-smart-contract.js. Check the video below, and also, please check the previous article on smart contract deployments.

The scTransaction is used in the createPiggy and addAmount functions. For the first one, we pass the argument, which is the Unix timestamp in the future - our lock time for the Piggy Bank. In the second one, we don't have attributes, but we send the EGLD amount to lock. This amount will be locked until time passes.

/**
 * Call the createPiggy endpoint on the PiggyBank smart contract
 * https://github.com/xdevguild/piggy-bank-sc/blob/master/src/lib.rs#L25
 * We pass the unix timestamp in the future
 */
const createPiggy = async () => {
  await scTransaction({
    functionName: "createPiggy",
    args: [1750686756],
 });
};

/**
 * Call the addAmount endpoint on the PiggyBank smart contract
 * https://github.com/xdevguild/piggy-bank-sc/blob/master/src/lib.rs#L42
 */
const addAmount = async () => {
  await scTransaction({
    functionName: "addAmount",
    amount: 1000000000000000n,
 });
};

The third function is different. We don't need to trigger a transaction on the blockchain. We need to read the data on smart contract storage. We can do that by interacting with the network. For that, we can use some helpers from MultiversX SDK. First, let's see how it looks.

const getLockedAmount = async () => {
  const abiObj = await getAbi();

  const queryRunner = new QueryRunnerAdapter({
    networkProvider: apiNetworkProvider,
 });

  const controller = new SmartContractQueriesController({
    queryRunner: queryRunner,
    abi: AbiRegistry.create(abiObj),
 });

  const query = controller.createQuery({
    contract: PIGGYBANK_CONTRACT_ADDRESS,
    function: "getLockedAmount",
    arguments: [senderAddress],
 });

  const response = await controller.runQuery(query);

  const [amount] = controller.parseQueryResponse(response);

  // The returned amount is a BigNumber
  console.log("Locked amount is: ", amount.valueOf());
};

We need to define QueryRunnerAdapter, which takes the networkProvider. In our case, we use a standard API network provider from the MultiversX toolset (check the first article for more details), but you can also prepare your own network provider and use it here. Let's keep it simple and use the default API provider.

After that, we need to prepare SmartContractQueriesController. It will manage queries. It takes a previously defined query runner and the contents of the ABI file as AbiRegistry. With that, we will be able to parse the query's response.

So, with the controller, we can create a query where we pass the smart contract address, function name, and arguments, if any. Then, we can run the query and get the response. Finally we can parse the response and get the data we are interested in. In this case, it is the amount of locked EGLD on the smart contract. And that's it. We have the returned locked amount.

There is also a simple helper for this demo that manages which function we want to call. So, if you're going to call the createPiggy function, you use node smart-contract-interactions.js createPiggy. Let's see how it looks, but it isn't important here. Again, check the video below to see more of it.

const smartContractInteractions = () => {
  const args = process.argv.slice(2);
  const functionName = args[0];

  const functions = {
    createPiggy,
    addAmount,
    getLockedAmount,
 };

  if (functionName in functions) {
    functions[functionName]();
 } else {
    console.log("Function not found!");
 }
};

Summary

There are two types of functions for MultiversX smart contracts. The write functions are where you need to broadcast a transaction, and read functions that don't need the transaction and are public to read through the network and APIs.

Interaction with both types is straightforward when you use the MultiversX JavaScript SDK. There are dedicated smart contract transaction factories and query controllers, which are especially helpful when you must parse the response. Here, we had a very simple value, but the returned data can be much more complex. When possible, use ABI files, and where it is not possible, use TypedValues from the SDK.

Follow me on X (@theJulianIo) and YouTube (@julian_io) or GitHub for more MultiversX magic.

Please check the tools I maintain: the Elven Family and Buildo.dev. With Buildo, you can do a lot of management operations using a nice web UI. You can issue fungible tokens, non-fungible tokens. You can also do other operations, like multi-transfers or claiming developer rewards. There is much more.

Walkthrough video

The demo code

learn-multiversx-js-sdk-with-examples

Mastering smart contract deployment with MultiversX JavaScript SDK

Julian.io — Sat, 22 Jun 2024 10:40:33 +0000

In the third article and video, I would like to focus on the MultiversX JavaScript/TypeScript SDK in the context of smart contract deployments. As in previous articles, we will go through the whole script step by step, explaining each SDK tool.

First, let's see the whole script and go through each important part:

import { promises } from "node:fs";
import {
 TransactionComputer,
 TransactionsFactoryConfig,
 SmartContractTransactionsFactory,
 Code,
 Address,
 TransactionWatcher,
 SmartContractTransactionsOutcomeParser,
 TransactionsConverter,
} from "@multiversx/sdk-core";
import {
 syncAndGetAccount,
 senderAddress,
 getSigner,
 apiNetworkProvider,
} from "./setup.js";

const deploySmartContract = async () => {
 const user = await syncAndGetAccount();
 const computer = new TransactionComputer();
 const signer = await getSigner();

 // Load smart contract code
 // For source code check: https://github.com/xdevguild/piggy-bank-sc/tree/master
 const codeBuffer = await promises.readFile("./piggybank.wasm");
 const code = Code.fromBuffer(codeBuffer);

 // Load ABI file (not required for now, but will be useful when interacting with the SC)
 // Although it would be helpful if we had initial arguments to pass
 const abiFile = await promises.readFile("./piggybank.abi.json", "UTF-8");

 // Prepare transfer transactions factory
 const factoryConfig = new TransactionsFactoryConfig({ chainID: "D" });
 let scFactory = new SmartContractTransactionsFactory({
 config: factoryConfig,
 abi: abiFile,
 });

 // Prepare deploy transaction
 const deployTransaction = scFactory.createTransactionForDeploy({
 sender: new Address(senderAddress),
 bytecode: code.valueOf(),
 gasLimit: 10000000n,
 arguments: [], // Pass arguments for init function on SC, we don't have any on this smart contract
 // Below ones are optional with default values
 nativeTransferAmount: 0, // Sometimes you need to send EGLD to the init function on SC
 isUpgradeable: true, // You will be able to upgrade the contract
    isReadable: false, // You will be able to read its state through another contract
    isPayable: false, // You will be able to send funds to it
    isPayableBySmartContract: false, // Only smart contract can send funds to it
 });

  // Increase the nonce
  deployTransaction.nonce = user.getNonceThenIncrement();

  // Serialize the transaction for signing
  const serializedDeployTransaction =
    computer.computeBytesForSigning(deployTransaction);

  // Sign the transaction with our signer
  deployTransaction.signature = await signer.sign(serializedDeployTransaction);

  // Broadcast the transaction
  const txHash = await apiNetworkProvider.sendTransaction(deployTransaction);

  // You can compute the smart contract address before broadcasting the transaction
  // https://docs.multiversx.com/sdk-and-tools/sdk-js/sdk-js-cookbook-v13#computing-the-contract-address
  // But let's see how to get it from the network after deployment

  console.log("Pending...");

  // Get the transaction on the network, we need to wait for the results here. We use TransactionWatcher for that
  const transactionOnNetwork = await new TransactionWatcher(
    apiNetworkProvider
 ).awaitCompleted(txHash);

  // Now let's parse the results with TransactionsConverter and SmartContractTransactionsOutcomeParser
  const converter = new TransactionsConverter();
  const parser = new SmartContractTransactionsOutcomeParser();
  const transactionOutcome =
    converter.transactionOnNetworkToOutcome(transactionOnNetwork);
  const parsedOutcome = parser.parseDeploy({ transactionOutcome });

  console.log(
    `Smart Contract deployed. Here it is:\nhttps://devnet-explorer.multiversx.com/accounts/${parsedOutcome.contracts[0].address}\n\nCheck the transaction in the Explorer:\nhttps://devnet-explorer.multiversx.com/transactions/${txHash}`
 );
};

deploySmartContract();

As you probably have already noticed, the structure is very similar to that of the previous scripts. We use the same helpers from the setup.js file, so I won't focus on them here. Check the first article for more info about them. The preparation to broadcast is also similar. There is one new thing, but we will get to it.

What is important in this demo is that I need a smart contract. This is why I included the WASM source code and the ABI file in the repository. The smart contract is a simple piggy bank functionality, and you can find the source code in the xDevGuild GitHub repository: Piggy Bank Smart Contract. The functionality is simple but not important in this context. Let's focus on the deployment.

After downloading the source code (in the same place as the script file), we need to read and include it in our script. We can do this with Node file system utilities. We also need to use Code from MultiversX SDK to prepare the proper format.

// Load smart contract code
// For source code check: https://github.com/xdevguild/piggy-bank-sc/tree/master
const codeBuffer = await promises.readFile("./piggybank.wasm");
const code = Code.fromBuffer(codeBuffer);

// Load ABI file (not required for now, but will be useful when interacting with the SC)
// Although it would be helpful if we had initial arguments to pass
const abiFile = await promises.readFile("./piggybank.abi.json", "UTF-8");

Next, we need to prepare the core setup. The configuration uses TransactionsFactoryConfig (similar to previous ones) and the SmartContractTransactionsFactory. The factory is similar to others but specific to smart contract operations. After that, we can use the createTransactionForDeploy from our factory and configure the deployment transaction. Let's stop for a moment, but first, let's see that part of the code to clarify it.

// Prepare transfer transactions factory
const factoryConfig = new TransactionsFactoryConfig({ chainID: "D" });
let scFactory = new SmartContractTransactionsFactory({
  config: factoryConfig,
  abi: abiFile,
});

// Prepare deploy transaction
const deployTransaction = scFactory.createTransactionForDeploy({
  sender: new Address(senderAddress),
  bytecode: code.valueOf(),
  gasLimit: 10000000n,
  arguments: [], // Pass arguments for init function on SC, we don't have any on this smart contract
  // Below ones are optional with default values
  nativeTransferAmount: 0, // Sometimes you need to send EGLD to the init function on SC
  isUpgradeable: true, // You will be able to upgrade the contract
  isReadable: false, // You will be able to read its state through another contract
  isPayable: false, // You will be able to send funds to it
  isPayableBySmartContract: false, // Only smart contract can send funds to it
});

When configuring the deployment transaction, you have a couple of options. Of course, the most important is to provide the binary source code of the smart contract, but you can also do a couple of other things.

Each smart contract has an init function, which is triggered when the contract is deployed. This function could be useful in many ways, mostly for initial storage configuration. Of course, you can pass arguments to it. This is why we have the arguments array when configuring the transaction. In our case, the Piggy Bank doesn't require initial arguments, but you would need that in many cases. You can pass plain data to the array when using ABI. It should be handled properly, but you can also use data helpers from MultiversX SDK. You'll find them, for example, here: mx-sdk-js-core typesystem. So, in short words, you can, for example, import U32Value from MultiversX SDK and then use it like: arguments: [new U32Value(123)]. But don't worry about it when you have the ABI. Then it should also work like arguments: [123]. Of course, the order of arguments is important.

Okay, what next? Sometimes, you need to provide a payment for the init function. For example, your smart contract could have logic that requires locking some EGLD amount on initialization. It is why we have the nativeTransferAmount. You can pass it there.

We also have some 'flags' that will help to configure our smart contract and its future behavior. You can define your contract as upgradable with isUpgradable. You can define if your contract can be payable by anyone by isPayable. You can limit the payable functionality only to allow a smart contract with isPayableBySmartContract. Finally, you can define if your smart contract can be readable by other smart contracts using isReadable.

Okay, let's move on. After we configure our deployment transaction, we need to prepare some standard steps, as with all transactions. So we need to increment the nonce, serialize the transaction, sign it, and broadcast it.

// Increase the nonce
deployTransaction.nonce = user.getNonceThenIncrement();

// Serialize the transaction for signing
const serializedDeployTransaction =
  computer.computeBytesForSigning(deployTransaction);

// Sign the transaction with out signer
deployTransaction.signature = await signer.sign(serializedDeployTransaction);

// Broadcast the transaction
const txHash = await apiNetworkProvider.sendTransaction(deployTransaction);

In this case, we need to get the smart contract address. We can compute it before we send the transaction, but we want to be sure that the deployment transaction went through and that the smart contract was deployed. We will get the address from the transaction outcome. We can do this by using a couple of tools. These operations are more general, not only in the context of smart contracts, so you can use them for any transaction.

// Get the transaction on the network, we need to wait for the results here. We use TransactionWatcher for that
const transactionOnNetwork = await new TransactionWatcher(
  apiNetworkProvider
).awaitCompleted(txHash);

// Now let's parse the results with TransactionsConverter and SmartContractTransactionsOutcomeParser
const converter = new TransactionsConverter();
const parser = new SmartContractTransactionsOutcomeParser();
const transactionOutcome =
  converter.transactionOnNetworkToOutcome(transactionOnNetwork);
const parsedOutcome = parser.parseDeploy({ transactionOutcome });

console.log(
  `Smart Contract deployed. Here it is:\nhttps://devnet-explorer.multiversx.com/accounts/${parsedOutcome.contracts[0].address}\n\nCheck the transaction in the Explorer:\nhttps://devnet-explorer.multiversx.com/transactions/${txHash}`
);

The TransactionWatcher will wait and get the transaction results on the chain. We must also prepare a converter and parser using tools from the MultiversX SDK. With that, we can pass the transactionOnNetwork and parse the outcome to get the address.

The parsedOutome in this case has such a structure:

{
  returnCode: 'ok',
  returnMessage: 'ok',
  contracts: [
    {
      address: 'erd1qqqqqq...',
      ownerAddress: 'erd1...',
      codeHash: <Buffer ...>
    }
  ]
}

Summary

That's it. We have a full deployment script. The smart contract has been deployed to the devnet chain and is ready to work with. I'll put together an article and video that show how to interact with such a smart contract.

Follow me on X (@theJulianIo) and YouTube (@julian_io) or GitHub for more MultiversX magic.

Walkthrough video

The demo code

learn-multiversx-js-sdk-with-examples

Transfer tokens using MultiversX JavaScript SDK

Julian.io — Sat, 22 Jun 2024 10:16:53 +0000

In the second article and video about MultiversX JavaScript/TypeScript SDK, I want to focus on token transfers. Please check the first one, which presents all the helper tools and setup. I will also use them here. At the end of this article, you'll find the video with a voiceover and a link to the repository.

What I want to cover here:

How to send native EGLD using transfer methods
How to send ESDTs using transfer methods

The main focus will be preparing and using transaction factories, in this case, the transfer transaction factory.

How to send native EGLD using transfer methods

In the previous video, we also sent the EGLD native tokens using a custom Transaction class, but there is a simpler and cleaner method.

Let's check the code below and then analyze it step by step.

import {
  TransactionComputer,
  Address,
  TransactionsFactoryConfig,
  TransferTransactionsFactory,
} from "@multiversx/sdk-core";
import {
  receiverAddress,
  syncAndGetAccount,
  senderAddress,
  getSigner,
  apiNetworkProvider,
} from "./setup.js";

const makeTransfer = async () => {
  const user = await syncAndGetAccount();
  const computer = new TransactionComputer();
  const signer = await getSigner();

  // Prepare transfer transactions factory
  const factoryConfig = new TransactionsFactoryConfig({ chainID: "D" });
  const factory = new TransferTransactionsFactory({ config: factoryConfig });

  // Transfer native EGLD token (value transfer, the same as with the simple transaction)
  const egldTransaction = factory.createTransactionForNativeTokenTransfer({
    sender: new Address(senderAddress),
    receiver: new Address(receiverAddress),
    // 0.01 EGLD (EGLD has 18 decimal places)
    nativeAmount: BigInt("10000000000000000"),
  });

  egldTransaction.nonce = user.getNonceThenIncrement();

  const serializedEgldTransaction =
    computer.computeBytesForSigning(egldTransaction);

  egldTransaction.signature = await signer.sign(serializedEgldTransaction);

  const txHash = await apiNetworkProvider.sendTransaction(egldTransaction);

  console.log(
    "EGLD sent. Check in the Explorer: ",
    `https://devnet-explorer.multiversx.com/transactions/${txHash}`
  );
};

makeTransfer();

So, the structure is very similar to that of the first article. What is different here is how we build our transaction object. But let's analyze the makeTransfer function starting from the top.

First, we prepare the objects required for all transactions: the user object, the transaction computer for serialization, and the signer.

const user = await syncAndGetAccount();
const computer = new TransactionComputer();
const signer = await getSigner();

For more information, please check the first article. I won't focus on it much.

Preparing the transfer transaction factory is the central part of this process. You must prepare the config and the factory itself.

const factoryConfig = new TransactionsFactoryConfig({ chainID: "D" });
const factory = new TransferTransactionsFactory({ config: factoryConfig });

Then, you will prepare the transaction for signing (and later broadcast) by invoking the createTransactionForNativeTokenTransfer method on the previously prepared factory.

const egldTransaction = factory.createTransactionForNativeTokenTransfer({
  sender: new Address(senderAddress),
  receiver: new Address(receiverAddress),
  // 0.01 EGLD (EGLD has 18 decimal places)
  nativeAmount: BigInt("10000000000000000"),
});

You need to pass the receiver and sender. Also, you need to pass nativeAmount, which should be a BigInt, and remember that native EGLD has 18 decimal places. So to send 0.01 EGLD, you need to pass BigInt("10000000000000000"). Of course, there are helpers for that, or you can build one using, for example, the bignumber.js library, but let's keep it simple for now.

Ok this is all. You have prepared the transaction for signing.

The following steps are similar to the first video, the first transaction example. You need to set and increment the nonce, serialize the transaction, sign it, and send it.

egldTransaction.nonce = user.getNonceThenIncrement();

const serializedEgldTransaction =
  computer.computeBytesForSigning(egldTransaction);

egldTransaction.signature = await signer.sign(serializedEgldTransaction);

const txHash = await apiNetworkProvider.sendTransaction(egldTransaction);

console.log(
  "EGLD sent. Check in the Explorer: ",
  `https://devnet-explorer.multiversx.com/transactions/${txHash}`
);

That's it. You broadcasted the transaction that moved the EGLD value from one wallet to another. Check the video for more details.

How to send ESDTs using transfer methods

Now, let's check how we can move ESDT tokens, which are custom tokens that you can issue on the MultiversX blockchain. They can be fungible, semi-fungible, or non-fungible (there are also meta tokens, but let's leave them; they are all similar).

As with the EGLD, let's see the whole code first, and then we will proceed step by step. It will be code from the multi-transfer demo. The video will provide a more detailed walkthrough for a single transfer of each token type, but the code is very similar to this one, so let's use it here.

import {
  TransactionComputer,
  Address,
  TransactionsFactoryConfig,
  TransferTransactionsFactory,
  TokenTransfer,
  Token,
} from "@multiversx/sdk-core";
import {
  receiverAddress,
  syncAndGetAccount,
  senderAddress,
  getSigner,
  apiNetworkProvider,
} from "./setup.js";

const makeTransfer = async () => {
  const user = await syncAndGetAccount();
  const computer = new TransactionComputer();
  const signer = await getSigner();

  // Prepare transfer transactions factory
  const factoryConfig = new TransactionsFactoryConfig({ chainID: "D" });
  const factory = new TransferTransactionsFactory({ config: factoryConfig });

  // Transfer native EGLD token (value transfer, the same as with the simple transaction)
  const multiTransferTransaction =
    factory.createTransactionForESDTTokenTransfer({
      sender: new Address(senderAddress),
      receiver: new Address(receiverAddress),
      tokenTransfers: [
        new TokenTransfer({
          token: new Token({
            identifier: "ELVNFACE-762e9d",
            nonce: BigInt("90"),
          }),
          // Send 1, it is always 1 for NFTs
          amount: BigInt("1"), // or 1n
        }),
        new TokenTransfer({
          token: new Token({ identifier: "DEMSFT-00eac9", nonce: BigInt("1") }),
          // Send 10
          amount: BigInt("10"), // or 10n
        }),
        new TokenTransfer({
          token: new Token({ identifier: "DEMFUNGI-3ec13b" }),
          // Send 10, remember about 18 decimal places
          amount: BigInt("10000000000000000000"), // or 10000000000000000000n
        }),
      ],
    });

  multiTransferTransaction.nonce = user.getNonceThenIncrement();

  const serializedmultiTransferTransaction = computer.computeBytesForSigning(
    multiTransferTransaction
  );

  multiTransferTransaction.signature = await signer.sign(
    serializedmultiTransferTransaction
  );

  const txHash = await apiNetworkProvider.sendTransaction(
    multiTransferTransaction
  );

  console.log(
    "Multiple ESDTs sent. Check in the Explorer: ",
    `https://devnet-explorer.multiversx.com/transactions/${txHash}`
  );
};

makeTransfer();

As you can see, the code looks very similar to the native EGLD transfer, and that's the case. We want to have an excellent developer experience here. What changes here is the method on our transfer factory which is now createTransactionForESDTTokenTransfer.

const multiTransferTransaction =
  factory.createTransactionForESDTTokenTransfer({
    sender: new Address(senderAddress),
    receiver: new Address(receiverAddress),
    tokenTransfers: [
      new TokenTransfer({
        token: new Token({
          identifier: "ELVNFACE-762e9d",
          nonce: BigInt("90"),
        }),
        // Send 1, it is always 1 for NFTs
        amount: BigInt("1"), // or 1n
      }),
      new TokenTransfer({
        token: new Token({ identifier: "DEMSFT-00eac9", nonce: BigInt("1") }),
        // Send 10
        amount: BigInt("10"), // or 10n
      }),
      new TokenTransfer({
        token: new Token({ identifier: "DEMFUNGI-3ec13b" }),
        // Send 10, remember about 18 decimal places
        amount: BigInt("10000000000000000000"), // or 10000000000000000000n
      }),
    ],
  });

We now use the tokenTransfers field instead of nativeAmount. We don't need to move any EGLD value here. In tokenTransfers, you can put different token types where you will define the identifier, amount, and in the case of NFT/SFT/Meta, also proper nonce.

Let's go through all three cases. For non-fungible ESDT, you have:

new TokenTransfer({
  token: new Token({
    identifier: "ELVNFACE-762e9d",
    nonce: BigInt("90"),
  }),
  // Send 1, it is always 1 for NFTs
  amount: BigInt("1"), // or 1n
}),

The TokenTransfer and Token classes are, of course, imported from MultiversX SDK. The identifier here, ELVNFACE-762e9d, is, in fact, the identifier of the NFT collection. Then, for a particular NFT to send, which is here ELVNFACE-762e9d-5a, you need to pass its nonce, here 5a, which is a decimal hex representation of 90. Don't worry. You'll also find the nonce in the MultiversX Explorer. Check the video for more details. Next we need to pass the amount to send. It will always be 1 for NFTs and should be passed as BigInt.

The situation is very similar for the SFTs. The main difference is that you can pass more than 1 in the amount.

new TokenTransfer({
  token: new Token({ identifier: "DEMSFT-00eac9", nonce: BigInt("1") }),
  // Send 10
  amount: BigInt("10"), // or 10n
}),

We send 10 of DEMSFT-00eac9-01 where 01 is nonce 1 and the collection is DEMSFT-00eac9.

There is a critical difference between the fungible ESDTs. They can have decimal places, so you need to remember this when transferring. (By the way, remember that also when transferring Meta ESDTs).

new TokenTransfer({
  token: new Token({ identifier: "DEMFUNGI-3ec13b" }),
  // Send 10, remember about 18 decimal places
  amount: BigInt("10000000000000000000"), // or 10000000000000000000n
}),

We don't need the nonce here. There is no 'collection'. The identifier is our token identifier. And as mentioned you need to remember about the decimal places and pass the value as BigInt.

Summary

Here you have it. You learned how to transfer different types of tokens on the MultiversX blockchain using one of the most used programming language and SDK.

If you want to test with your wallets on the devnet and you need to get some tokens, check these services:

1. www.devnet.buildo.dev
2. dapp-demo.elven.tools

Follow me on X (@theJulianIo) and YouTube (@julian_io) or GitHub for more MultiversX magic.

Walkthrough video

The demo code

learn-multiversx-js-sdk-with-examples

Intro to MultiversX blockchain interactions with JavaScript SDK

Julian.io — Sun, 09 Jun 2024 12:39:19 +0000

Writing low-level code for blockchain applications is one thing, but you must also write tools to interact with the protocol and smart contracts. What is the best programming language for that? A couple exist, but what's quickest to pick up, especially with a great SDK? Of course, JavaScript.

I want to cover interactions in a Node.js environment with MultiversX SDK. For web application integration, I will prepare separate articles.

What we will cover in this article:

How to prepare the environment and tools
How to prepare and broadcast a simple transaction

You will find a video walkthrough at the end of this article.

Let's focus on the Node.js environment first. It will be more helpful to show how the MultiversX JS SDK works in Node.js before introducing you to abstractions like web apps-related tooling.

Preparing the tools

We will need Node.js to interact with the MultiversX blockchain using the JavaScript SDK. If you are a JavaScript developer, there is no need to explain how to install Node.js. If not, it would be better to understand how it all works before reading further, so please learn more about it and then go back to this article.

Ok, let's jump into it. First of all, we need to initialize our dummy project. So create a directory, and inside of it, use npm to initialize the Node.js project:

npm init

It will guide you in creating a package.json file with the setup.

Then we must install @multiversx/sdk-core, @multiversx/sdk-network-providers and @multiversx/sdk-wallet. I will use the second library to prepare a convenient way of making network requests and broadcasting transactions. The third library will be required to prepare a 'signer' wallet for tests, but we will primarily work with the sdk-core.

npm install @multiversx/sdk-core @multiversx/sdk-network-providers @multiversx/sdk-wallet

We will work without the Typescript configuration just for simplicity, but of course, you can also configure this step if you want to.

The next step is to create a wallet. The simplest way is to use the Devnet Web Wallet. Check devnet-wallet.multiversx.com and create a new wallet there. Save the password you provided, the seed phrase, and the generated Keystore file. You will need them later. Remember, all that data should stay private, so don't share it with anyone. I will share everything for demo purposes, but it is still on the devnet, so nothing harms me if the data leaks.

You also need some funds in your wallet. After connecting to the Web wallet using the Keystore, you will find a faucet. You can request some 'fake' EGLD (the native MultiversX token) for testing. The Web Wallet UI should be intuitive enough, but here are the docs on using it: Web Wallet docs.

Ok, let's return to our JavaScript code. Now that we have all the necessary libraries let's create a setup.js file and move the Keystore JSON file to the same directory for convenience.

Till now, you should have:

node_modules
package.json
erd....json
setup.js

We must initialize and prepare some things: our signer to sign transactions with our newly created wallet, our user account to synchronize it with the network, and the network provider to broadcast transactions.

You will do that using helper functions from our previously installed npm packages. It should look like:

import { promises } from "node:fs";
import { Address, Account } from "@multiversx/sdk-core";
import { ApiNetworkProvider } from "@multiversx/sdk-network-providers";
import { UserSigner } from "@multiversx/sdk-wallet";

export const senderAddress =
  "erd10dgr4hshjgkv6wxgmzs9gaxk5q27cq2sntgwugu87ah5pelknegqc6suj6";
export const receiverAddress =
  "erd176ddeqqde20rhgej35taa5jl828n9z4pur52x3lnfnj75w4v2qyqa230vx";

const keyFilePath = `./${senderAddress}.json`;

// Should be always kept privately, here hardcoded for the demo
const password = "Ab!12345678";

// The convenient way of doing network requests using the devnet API
export const apiNetworkProvider = new ApiNetworkProvider(
  "https://devnet-api.multiversx.com"
);

export const syncAndGetAccount = async () => {
  const address = new Address(senderAddress);
  const userAccount = new Account(address);
  const userAccountOnNetwork = await apiNetworkProvider.getAccount(address);
  userAccount.update(userAccountOnNetwork);
  return userAccount;
};

// We read the Keystore file contents here
const getKeyFileObject = async () => {
  const fileContents = await promises.readFile(keyFilePath, {
    encoding: "utf-8",
  });
  return fileContents;
};

export const getSigner = async () => {
  const wallet = await getKeyFileObject();
  return UserSigner.fromWallet(JSON.parse(wallet), password);
};

The functions are self-explanatory, but basically, the tools are:

apiNetworkProvider - required for broadcasting transactions
syncAndGetAccount - preparing and synchronization of the user account
getSigner - prepare the wallet signer for transaction signing

Sign and broadcast the transaction

With our tools ready, we can review our transactions. We want to use the simplest method to prepare and send some EGLD with an attached custom message.

The flow is as follows:

We synchronize and prepare the user instance
We prepare the transaction configuration and payload
We increment the nonce using the user's on-chain data
We serialize the transaction data for signing
We sign the transaction data
We get and set the signature on the transaction object
We broadcast the transaction

It looks like that in the code:

import { Transaction, TransactionComputer } from "@multiversx/sdk-core";
import {
  receiverAddress,
  syncAndGetAccount,
  senderAddress,
  getSigner,
  apiNetworkProvider,
} from "./setup.js";

const sendEgld = async () => {
  const user = await syncAndGetAccount();

  const transaction = new Transaction({
    data: Buffer.from("This is the demo transaction!"),
    gasLimit: 100000n,
    sender: senderAddress,
    receiver: receiverAddress,
    value: 1000000000000000n, // 0.001 EGLD
    chainID: "D",
  });

  transaction.nonce = user.getNonceThenIncrement();

  const computer = new TransactionComputer();
  const serializedTransaction = computer.computeBytesForSigning(transaction);

  const signer = await getSigner();

  transaction.signature = await signer.sign(serializedTransaction);

  const txHash = await apiNetworkProvider.sendTransaction(transaction);

  console.log(
    "Check in the explorer: ",
    `https://devnet-explorer.multiversx.com/transactions/${txHash}`
  );
};

sendEgld();

For more information about all the helper functions from MultiversX JavaScript SDK, you can check the autogenerated API documentation.

There is also a cookbook with the basics like here, but also with much more. You can find it here: sdk-js-cookbook.

I'll also try to prepare more articles on topics like interaction with custom smart contracts and token management, but these will be included in the following articles.

Summary

The MultiversX JavaScript SDK is a powerful tool for interacting with blockchain and smart contracts. Here, you have complete logic for managing simple transactions, but you can reuse that for any other transaction. The only difference will be how the transaction payload is built.

Follow me on X (@theJulianIo) and YouTube (@julian_io) or GitHub for more MultiversX magic.

Walkthrough video

The demo code

learn-multiversx-js-sdk-with-examples

How to enable donations on any website using the MultiversX (Elrond) blockchain and EGLD tokens

Julian.io — Sun, 28 Aug 2022 23:49:00 +0000

The MultiversX (Elrond) blockchain is a layer one solution that is performant and cheap. It is a complete blockchain solution so that anyone can build on it.

I want to show you how simple it is to prepare a website widget that will allow getting donations in EGLD, which is the native token of the MultiversX (Elrond) blockchain.

Please refer to the official MultiversX (Elrond) docs if you want to read more: https://docs.multiversx.com/.

For the demo and example, I will use Astro and one of its ready-to-use themes, and I will generate a static website. Why Astro? Because I think it will be quick to bootstrap a static blog example with it. But of course, it can be anything. Static site generator, Solid.js, what have you. For React-based websites please check the: MultiversX (Elrond) Nextjs dApp template.

The point of this article is to show you how to prepare a simple widget, even on a static HTML website.

First, let's answer the question, why do we want such a tool?

You probably know services like 'buy me a coffee'. They are excellent forms of catching attention and making your user base support you with real money. The same can work with cryptocurrencies. In this case, the EGLD token.

When it comes to blockchains and native tokens, there is always some community around them, especially when building tools, managing projects or writing articles, creating content on social media, etc. Such a user base requires a lot of custom websites, blogs, and landing pages. In such a case, you can always provide a way of supporting your project with real money.

What will we build?

The app will be a static frontend-only website—just an example for demo purposes. It will be a blog where one of its pages will allow users to donate some EGLD tokens. The users will send them to a predefined wallet address using the Maiar mobile wallet. If you don't know what it is, don't worry. You can read more about it on its website. It is a standard mobile app that serves as a crypto wallet that can store information about MultiversX (Elrond), Bitcoin, Ethereum, and Binance Coin assets.

So the functionality of our donate widget will be pretty straightforward. We will display the QR code where the users can log in with their Maiar mobile apps. Then they can prepare, sign, and send the transaction. We will predefine one price that users can choose for this demo. So I think it could be 0.5 EGLD. You will be able to change that or even add more options. All is just a static website and JavaScript.

After the transaction is done, the user will get the 'receipt' with the link to the MultiversX blockchain explorer. Remember that the functionality here can be extended, and you can add more logic, like some giveaways, free stuff, newsletters signings, and whatever you only can think of.

How will we build it?

The MultiversX (Elrond) ecosystem is rich in a lot of developer tools. There is a Typescript/JavaScript SDK called sdk-js, or I should write the set of libraries, not only the sdk-js. So that's cool, but the problem here is that the SDK and all the libs have a lot of functionality that we don't need, and they require building steps to make them work with the browser. This is why the elven.js tool exists.

The elven.js is a script to be used in browsers. It is a simple wrapper script over the sdk-js libraries. It is prebuilt, so you don't need any build steps. All in one, plug-n-play solution. We will use it for this task. Read more about elven.js in this introduction: How to Interact With the MultiversX (Elrond) Blockchain in a Simple Static Website.

Astro initialization?

First, we need a website. As mentioned above, I will use astro.build with a default blog template. You can scaffold the project using npm with the command:

npm init astro -- --template blog

You will get a fully functional blog with a simple design, but this isn't important now. For simplicity, let's clean the index page content, and I think we can use the index page and implement the donate functionality there. You can also create a separate page for that. It doesn't matter in this case. The whole process will be similar.

You will find the whole demo website with the widget in the GitHub repository.

Ok, now let's see how to use the elven.js script and build the donate widget.

Elven.js initialization

In a standard static website, you can import components from the CDN or local file. Check the example here: Elven.js (StackBlitz).

But with Astro, we will install elven.js using npm. You can add it by:

npm install elven.js

Remember to run the command in the newly created Astro project.

After the elven.js is installed, we need to initialize it. I will create a separate JavaScript file called elven-init.mjs. I will put it in the pages folder, next to our index page. This will be our whole logic for the donate widget. Then in the index.astro, I will import it. So the index file will look similar to this:

---
import BaseHead from '../components/BaseHead.astro';
import Header from '../components/Header.astro';
import Footer from '../components/Footer.astro';
import { SITE_TITLE, SITE_DESCRIPTION } from '../config';
---

<!DOCTYPE html>
<html lang="en-us">
    <head>
        <BaseHead title={SITE_TITLE} description={SITE_DESCRIPTION} />
    </head>
    <body>
        <Header />
        <main>
            <p><strong>MultiversX (Elrond) donate widget with <a href="https://github.com/juliancwirko/elven.js">Elven.js</a></strong></p>
            <p><strong>No real money here!</strong></p>
            <p>All works on the devnet, but it is ready for mainnet usage!</p>
            <div id="elrond-donate-widget-container">
            </div>
        </main>
        <Footer />
        <script>
            import './elven-init.mjs'
        </script>
    </body>
</html>

As you can see here, we have two crucial code sections. The empty div with the id elrond-donate-widget-container and then the script import. We are importing the previously created elven-init.mjs file.

Let's see what should land in the elven-init.mjs custom file.

First of all, we need to import the required components from elven.js:

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

Then below that, we will need to initialize the elven.js. We can do this like that:

const initElven = async () => {
  await ElvenJS.init({
    apiUrl: "https://devnet-api.multiversx.com",
    chainType: "devnet",
    apiTimeout: 10000,
    onLoggedIn: () => { uiLoggedInState(true); uiSpinnerState(false); },
    onLoginPending: () => { uiSpinnerState(true); },
    onLogout: () => { uiLoggedInState(false); uiSpinnerState(false); },
    onTxStarted: () => { uiSpinnerState(true); },
    onTxFinalized: (tx) => { tx?.hash && updateTxHashContainer(tx.hash); uiSpinnerState(false); }
  });
};
initElven();

The ElvenJS.init function is async, so we need to wrap it and call the wrapper function below. The ElvenJS.init takes the network configuration—the API endpoint, chain type, and API timeout. The uiLoggedInState function is a helper function responsible for UI state changes. It will also be added to the elven-init.mjs for simplicity, but you can keep it in a separate file. It is a simple DOM manipulation function and looks like:

const uiLoggedInState = (loggedIn) => {
  const loginMaiarButton = window.document.getElementById(
    "button-login-mobile"
  );
  const logoutButton = document.getElementById("button-logout");
  const txButton = document.getElementById("button-tx");
  if (loggedIn) {
    loginMaiarButton.style.setProperty('display',"none");
    logoutButton.style.setProperty('display', 'block');
    txButton.style.setProperty('display', 'block');
  } else {
    loginMaiarButton.style.setProperty('display',"block");
    logoutButton.style.setProperty('display', 'none');
    txButton.style.setProperty('display', 'none');
  }
};

Login using elven.js

After the initialization, we can start building the login functionality. We need a couple of buttons in our index.astro page file. As you probably know already, looking at the uiLoggedInState.

We can add them below the elrond-donate-widget-container div. It will look like this:

<button class="button" id="button-tx" style="display: none;">Donate!</button>
<button class="button" id="button-login-mobile" style="display: none;">Connect!</button>
<button class="button" id="button-logout" style="display: none;">Disconnect</button>

So we have three buttons, all are hidden initially. In the init function, we set the UI state, so all will be displayed as it should be. We will also need some CSS for the buttons and the containers, but let's leave it now. You can check that in the repository.

Ok, now that we have the button for triggering the login with Maiar mobile app, let's add a click listener. It will initialize the Maiar mobile app login, showing the QR code, and then you will need to scan it with your Maiar wallet. Don't worry. You can also do this on the devnet. You will only need some EGLD from the MultiversX (Elrond) faucet. You will find it in the MultiversX (Elrond) Web Wallet. Choose the devnet wallet or mainnet wallet if required. Of course, on the mainnet, you will need to buy some EGLD. You can log in there using the Maiar mobile app the same way we will use it for the donate widget. In the devnet wallet, you will find the faucet option to get 30 fake EGLD tokens.

Ok, so let's go back to our login button and click listener. It will look like this:

document
  .getElementById("button-login-mobile")
  .addEventListener("click", async () => {
    try {
      await ElvenJS.login("maiar-mobile", {
        qrCodeContainerId: "elrond-donate-widget-container"
      });
    } catch (e) {
      console.log("Login: Something went wrong, try again!", e?.message);
    }
  });

The main function here is the ElvenJS.login('maiar-mobile', {...}). What is important here is that we will pass the id for the QR code container. In our case, it is elrond-donate-widget-container. We also used another UI helper here with the loading spinner text. Don't worry about it. It will also be in the elven-init.mjs file. It is responsible for UI loading states, indicating, and nothing more.

The Maiar mobile auth uses WalletConnect under the hood. This is why we need some callbacks here when we log in and out (This will probably be moved to the init function in the future).

Make a transaction with elven.js

After the login is triggered, you will get the QR code. When you confirm the login using the Maiar mobile app, you will get a button to make the transaction. The transaction trigger code looks like this:

const egldTransferAddress = 'erd17a4wydhhd6t3hhssvcp9g23ppn7lgkk4g2tww3eqzx4mlq95dukss0g50f';
const donatePrice = 0.5;

document.getElementById('button-tx').addEventListener('click', async () => {
  updateTxHashContainer(false);
  const demoMessage = 'MultiversX (Elrond) donate demo!';

  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(donatePrice),
    sender: new Address(ElvenJS.storage.get('address')),
  });

  try {
    await ElvenJS.signAndSendTransaction(tx);
  } catch (e) {
    throw new Error(e?.message);
  }
});

A couple of things here. First, we have two variables, the wallet address to which the EGLD tokens will be sent and the value which will be sent. We are preparing the transaction here using the Transaction class. We need to pass on a couple of things here. The address, the value, gas limit, nonce, etc. All of these are wrapped with helpers that are exported from sdk-js SDK. You will find more info about them in the sdk-js cookbook. Oh, and we also use ElvenJS.storage to get some data from the localStorage. This is provided by elven.js.

Then it is enough to use the ElvenJS.signAndSendTransaction(tx) to sign and send the transaction. You will need to approve the transaction in the Maiar mobile app wallet.

After the transaction is ready, you will get the transaction hash, and in this demo, there will be a link to the MultiversX (Elrond) explorer. We use the updateTxHashContainer UI helper to build and update the UI. You will find it also in the elven-init.mjs.

Logout

There is, of course, an option to log out and clear all the data in the browser. To do that, you will need to use:

document.getElementById('button-logout').addEventListener('click', async () => {
  try {
    await ElvenJS.logout();
  } catch (e) {
    console.error(e.message);
  }
});

So we use ElvenJS.logout() and then trigger all the UI helpers.

This is all that you need to prepare the widget. Please check it live at: elrond-donate-widget-demo.netlify.app.

How to use it with the mainnet?

You would need to do a couple of things to use it on the MultiversX (Elrond) mainnet with real EGLD. First of all, remember to change your wallet address. Of course, you can have the same address on the mainnet, but be sure you have used the proper one.

Then you would need to configure your ElvenJS.init function like that:

await ElvenJS.init({
  apiUrl: 'https://api.multiversx.com',
  chainType: 'mainnet',
  apiTimeout: 10000,
  onLoggedIn: () => { uiLoggedInState(true); uiSpinnerState(false); },
  onLoginPending: () => { uiSpinnerState(true); },
  onLogout: () => { uiLoggedInState(false); uiSpinnerState(false); },
  onTxStarted: () => { uiSpinnerState(true); },
  onTxFinalized: (tx) => { tx?.hash && updateTxHashContainer(tx.hash); uiSpinnerState(false); }
});

And that's it. You are ready to go with the mainnet.

Summary

A simple donate widget shows how helpful is the elven.js script. It can do much more, you can not only transfer EGLD tokens, but you can also make transactions to your custom smart contracts. And there will be more, all simplified.

Check out these links:

elvenjs.com - docs and examples
elven.js - GitHub repository
MultiversX (Elrond) donate widget - the repository of described here demo, with a live website link

Let me know what you think about elven.js and this example. You will find me on Twitter. Also, check out my website: julian.io.

MultiversX NFT collection with Elven Tools

Julian.io — Sat, 12 Mar 2022 17:12:43 +0000

The MultiversX blockchain offers a cheap solution for NFT authors. The protocol natively supports NFTs. These are ESDTs with additional metadata and attributes. In short, the smart contract is not required to issue them, but when it comes to whole collection distribution/selling, it is crucial to have it and prove that the distribution goes in a decentralized manner.

I won't go deep into technical stuff here. You can read more about the ESDTs and NFTs in the official documentation. I want to focus more on using open source tooling to run a simple candy-machine-like version of the smart contract.

The toolset is called Elven Tools, and you can find it here www.elven.tools.

The core of the tools is the smart contract that alow to mint the tokens randomly. Besides that, there is also a CLI tool that simplifies the setup, deployment, and interactions with the smart contract. The dapp - landing page is in progress too. So basically, it is a complete toolset where anyone can run their project, even without technical knowledge or only with basic knowledge about how to work with the terminal.

Let's see how to start with it.

If you want to jump in and start testing stuff, you can start with the CLI only. It will deploy the smart contract directly from its repository. It will be deployed to the devnet chain. So you don't have to worry about real money etc.

Before we start using the CLI, you must prepare your devnet wallet. You can create one here: https://devnet-wallet.multiversx.com/. Also, remember to fund it using the faucet accessible after logging in.

Now we can install the elven-tools CLI.
You can install it globally npm install -g elven-tools.
Remember that you would need the NodeJS environment configured.

Here are the minimum required steps with elven-tools:

Prepare a directory where you can work.
elven-tools derive-pem. Derive the PEM file. It will be required for all operations. You need to provide your seed phrase. The walletKey.pem file will be created in the same directory.
elven-tools deploy nft-minter. Configure and deploy the smart contract. You will be asked about a couple of configuration settings, like base IPFS CIDs collection size. I'll leave links and more explanations on how it works later in the article.
elven-tools nft-minter issue-collection-token. Create the collection identifier/ticker. This will be your main ticker for the collection. All NFTs will be minted under this id with additional suffixes. This is important because it is the main identifier for your collection.
elven-tools nft-minter set-roles. Add proper roles. It will add proper roles to be able to create new tokens.
elven-tools nft-minter start-minting. Start minting process. This command will enable the minting process. You can also pause it later.
elven-tools nft-minter mint. Mint. Here provide the number of tokens to mint and mint them. It will randomly mint the tokens and send them to the caller. You will need to pay for them.

This path is very basic. You can do a lot more with this toolset. Read more about it here:
https://www.elven.tools/docs/jump-start.html
https://www.elven.tools/docs/recipes.html
https://www.elven.tools/docs/cli-commands.html
https://www.elven.tools/docs/sc-endpoints.html
https://www.elven.tools/docs/landing-page.html

Also, check the walkthrough video:

Ok, let's back to the functionality and possibilities.

The smart contract allows you to do more things than described above. You can split the whole collection into a couple of drops. You can change the prices when needed. You can also prepare an allowlist and allow to mint for only eligible addresses. You can also make the giveaway and give the tokens to chosen addresses. Check the Elven Tools Worflows article to learn more about it.

Summary

The toolset is open source and free to use by anyone. If you need to modify the smart contract, you can still work with the CLI deploying from the local file system. You'll find all the information on how to do that in the docs here: https://www.elven.tools/docs/recipes.html.

Repositories:

Elven Tools Minter Dapp demo: https://dapp-demo.elven.tools/

Other tools:

Please stay tuned. Follow me on GitHub and Twitter. Thanks!

Personal blog for free

Julian.io — Sun, 08 Aug 2021 09:08:52 +0000

In this article, I would like to show you a fast and relatively simple way to create, host, and maintain your website and blog totally for free.

First, let's see what you can have without putting in any work. Check out the Default template.

Of course, this is just a demo. It is an initial template which you'll get using Harold - static site generator. If such a demo isn't enough, I built the whole julian.io using Harold.

You can, of course, modify everything there. From overall layout structure, going through JavaScript interactions and ending with unique post lists configurations.

You are probably thinking, ok, that's great, but I bet that it is very complicated and tricky like all other static site generators out there. That's not true. You'll be able to write in standard Markdown files. You can even use some desktop-based app to put your generated .md files in the proper place. All will just work with the default template.

Ok, and what about hosting? Is it also for free? Yes. Thanks to such services as GitHub Pages or Netlify, you can host your website for free. It is straightforward, and I'll show you how to do this in this article.

What is this Harold anyway?

Harold is a simple tool that generates static sites, blogs, etc. You only need to prepare your articles in Markdown files and configure your pages using Handlebars templating. It might sound more complicated than it is. So don't worry.

The best place to start with Harold would be the documentation site: https://www.haroldjs.com/docs/getting-started. But in short, what you need to do is to run :

npm init harold-app name-of-your-app

It will generate an initial structure similar to this one:
https://github.com/juliancwirko/harold-default-template-demo.

When you go to the newly created directory and run:

npm start

You'll get the initial website running at localhost:3000.

When you go to src/posts, you can start adding Markdown files and writing your stories. You'll find a couple of examples there. The important thing here is that you'll always need to provide at least three variables, layout, title, and publicationDate. All others are optional.

Every post can use a different blog layout. That's why you need to define one. Blog layouts should be placed in src/blog-layouts. These are standard Handlebars templates (.hbs files). If you don't know what Handlebars is, don't worry. It is a sort of enhanced HTML. But of course, if you want to modify the structure, you would need to learn a little bit about it. Check their docs: https://handlebarsjs.com/.

I don't want to spend a lot of time on Harold and how to use it. I will probably write some more detailed articles later. As I wrote initially, the best is to watch a quick walk-through video on Youtube and read the docs.

For now, what you need to know is that when you open your build directory, you'll find all HTML, CSS, and JavaScript files there. It is your whole website, and we will host it from that directory.

Hosting with Netlify

First, let's see the more straightforward solution, at least for me, and this will be Netlify. It is a service focused on simplicity when it comes to static site hosting. They provide many additional features, but what is most interesting for us is hosting from the git repository.

Netlify allows to point to the repository, configure build processes and destination directory. Then on every push to that git branch, Netlify will trigger build and deployment processes. So you will only need to make changes and push to the repository hosted by GitHub, Bitbucket, or GitLab.

Here is how to do this: Step by step guide deploying on Netlify

And if you prefer I prepared some quick walk-through video using my accounts here:

Hosting with GitHub Pages

Hosting with GitHub Pages service is a little trickier, but there is a fast solution. You can use GitHub Pages in two ways. The first one is to host your main website using a repository name like yourusername.github.io. When you create such a repository, you will host from the before-mentioned domain without subdirectories. It is an excellent option when you want to make your main personal website. There is a catch. Because we want to host our site from a specific folder, as in the Netlify case, it would be a build folder, we need to point to it somehow. The problem is that GitHub Pages will search for files at the root of a git branch. The only exception is the docs directory, which you can choose. For deployment, it makes no difference because we won't show this directory anywhere so that we can use it. To be able to do that with Harold, you would need to configure the output directory name. You can create the .haroldrc file in the root (next to the src directory). Then the contents of it should be:

{
  outputDirName: 'docs',
}

I prepared some quick walk-through video using my accounts here:

You can also check the docs.

The second way of doing GitHub Pages is to host some projects from a subdirectory. It will look like yourusername.github.io/yourproject. It will allow you to host multiple projects as separate websites from separate repositories. The whole configuration process with Harold is similar. Also, development is the same, and we just need to tell it that we will host in a subdirectory. It also relates to every other use case when we must rely on subdirectory-based hosting. So, additional configuration is to add the name of the subdirectory:

{
  outputDirName: 'docs',
  hostDirName: 'yourproject'
}

You'll find an example of such a project here: https://github.com/juliancwirko/testing-github-pages

Summary

I showed you how fast and straightforward it is to build and host your website and blog for free. Harold is open-source and free-to-use, and services like Netlify or GitHub Pages will let you host your website for free. What is excellent they will give you SSL and CDN for free.

I'll continue to work on Harold because it is a tool for my projects. I use it for landing pages, my blog, and even documentation websites. I'll publish the third template for docs pages very soon, so follow me on Twitter and Github.

Smart Contracts on the MultiversX (Elrond) blockchain

Julian.io — Sat, 07 Aug 2021 16:49:00 +0000

Are you interested in NFTs on the MultiversX (Elrond) blockchain? Check out open source tools that will help you with running and selling your collection: Elven Tools - MultiversX NFT

Lately, I started to explore through docs of many different blockchain protocols out there to find the quickest and simplest entry point to learn how to write Smart Contracts using Rust language. There are fantastic tools from the Polkadot ecosystem. Solana and Terra also look great, and I will for sure take a closer look at these later. But I found that MultiversX (Elrond) blockchain has many simple examples of straightforward code. The tooling is also quite impressive, so I decided to spend some time with it first.

I want to do a quick introduction here. The main points:

How to write a Smart Contract on the MultiversX (Elrond) blockchain
How to interact with such Smart Contract

Let's look at how we can start to write Smart Contracts on the MultiversX (Elrond) blockchain. There are pretty good docs on how to start. They use an example of a Crowdfunding Smart Contract. But let's leave it for a moment. You can always read it later. For now, let's jump into the code. I prepared a custom Smart Contract that has all dependencies up to date and is so simple that you will learn a lot by just reading the code. It is a simple PiggyBank Smart Contract. The functionality is basic for now. You can create a Piggy, add tokens, lock them, and claim them when the lock time will expire. You can clone it from Github here: PiggyBank Smart Contract.

As you will see, there are three main concepts.

The first one is on-chain storage. It is a kind of simple key-value storage with which you can interact using annotations that manage and serialize the keys and values behind the scenes. An example could be the storage for the lock time in our PiggyBank Smart Contract:

#[view(getLockTime)]
#[storage_mapper("lockTime")]
fn lock_time(&self, piggy_owner: &Address) -> SingleValueMapper<u64>;

It is as simple as that. You don't have to manage all serialization and all other stuff. The second important concept is #[endpoint] annotation which will expose the function, and users will be able to call it in transactions. For example the pay_out function looks like:

#[endpoint(payOut)]
  fn pay_out(&self) {
    let caller = &self.blockchain().get_caller();
    let caller_address = caller.to_address();
    require!(
      self.lock_time(&caller_address).get() < self.get_current_time(),
      "You can't withdraw your money yet"
    );
    require!(self.locked_amount(&caller_address).get() > 0, "There is nothing to withdraw");
    self.send()
      .direct_egld(caller, &self.locked_amount(&caller_address).get(), &[]);

    self.locked_amount(&caller_address).clear();
    self.lock_time(&caller_address).clear();
  }

We will see how to call such a function very soon. So keep reading.

The last and essential concept is the #[init] annotation, which will set the function as initialization process. The function will trigger only when the owner will deploy the contract. IT is necessary, for example, when we need to set up some ownership logic, etc.

So you see how the contract's code looks like, you'll also find the links to the docs if needed.

Ok, so how to interact with such a Smart Contract.

In the case of the MultiversX (Elrond) Blockchain, there is a couple of options. You can use JavaScript SDK, but you can also use a Python-based CLI tool called erdpy. It is what we will use here for now. Later I plan to write a frontend app for it, so I'll use JavaScript SDK.

You would, of course, need to install the erdpy tools. Docs are here: Installing erdpy. Installation is straightforward, so hopefully, you won't have any problems with that. You can also check my walkthrough video (uses the testnet and older names for functions, new ones are camel cased).

Let's start with the deployment. We need to place the Smart Contract somewhere on the blockchain. We will need a wallet for that. All is going to happen on the devnet, so that you would need the devnet wallet. Go and get one here: devnet-wallet.multiversx.com.

Then you would need to derive the pem key file. Check how to do this in the docs or my walkthrough video linked above.

Remember to build the contract using erdpy contract build. You would need to do this in the cloned PiggyBank directory.

Important!
Last but not least, you need to fund your account. Because this is a devnet wallet, you can use faucet to claim some tokens. Without any tokens, you won't be able to finish any transaction. You can also use the official faucet built into the devnet's web wallet.

After that, let's see the first command:

erdpy --verbose contract deploy --chain="D" --project=multiversx-simple-sc --pem="wallets/test.pem" --gas-limit=80000000 --proxy="https://devnet-gateway.multiversx.com" --recall-nonce --send

Chain D means that we will deploy to the devnet. It will deploy the contract using your wallet, wallet key from the pem file. You need to pass an exact path to this file. You also need to pass the path to the project. After that, you'll get the PiggyBank smart contract address. It is required for later interaction.

Ok, so now we can use the same or another wallet key and interact with the contract. For example, let's see how to create a Piggy.

erdpy --verbose contract call <smart_contract_address_here> --chain="D" --pem="wallets/test.pem" --gas-limit=5000000 --function="createPiggy" --arguments 1628619457 --proxy="https://devnet-gateway.multiversx.com" --recall-nonce --send

It is similar, but now we need to pass the smart contract address, and we are calling the createPiggy function, which you'll find here in the code. We need to pass the Unix time number for the lock deadline date.

Summary

I've done a quick intro of how an example Smart Contract on MultiversX (Elrond) Blockchain looks like and how you can interact with deployed smart contracts. I won't paste all possible calls here and all configuration details. You'll find them in my detailed article: Smart Contract for MultiversX (Elrond). And of course, I encourage you to watch the walkthrough video, which details what I was doing step by step. You can always clone the PiggyBank. You'll find all interaction calls using erdpy in the repository readme file.

Let me know what you would like to know about it. I don't understand all yet, I'm still learning, but I am sure that I will help with your first steps. Please follow me on Twitter and GitHub. I plan to write some other articles that will introduce more functions for our PiggyBank and frontend app.

NPM package in 2021

Julian.io — Sat, 03 Jul 2021 16:56:46 +0000

It was always a little bit hard to prepare JS code to be reusable through the NPM registry.

Over time we had a lot of different approaches. We had many different ways to use modular-like code in JavaScript.

Before 2015 we didn't even have official built-in modules standard in JavaScript. So we had to use third-party tools like AMD with, for example, RequireJS or - in Node ecosystem - CommonJS.

With ES6 or ES2015, we've got modules support in JavaScript. Of course, it was a time when all the development progress within browsers or Node was slow. Lately, we've gained momentum, and we are getting updates quite often. It's good. But what does that mean for NPM packages creators?

Let's imagine an example. I started to think why I even need tools like Babel or Parcel nowadays to create my NPM package when all of the modern browsers and Node supports the newest ES2020 standard. Suppose I want my code to be reusable across many different websites. At the same time, I don't want to use any third-party modules, and I don't care about any additional optimization because the lib is relatively tiny. What should I do in that case?

First thought - do I even need the NPM registry? Shouldn't it be just a simple JS script? It probably could. But why not the NPM registry? It is convenient, and all modern tools integrate with it.

Let's take Skypack as an example. It is a modern CDN that will take your well-prepared package and optimize for very different use cases. For instance, you could do something like:

<html>
  <body>
    <script type="module">
      import smoothScrollTop from 'https://cdn.skypack.dev/smooth-scroll-top';
      // do something with it here
    </script>
  </body>
</html>

As you can see, this is as simple as that. You write your code in clean, modern JavaScript, you publish it in the NPM registry, and then you can import it in the browser or if this is also a backend package in Node.

Ok, so what would you need to prepare such a package?

I think the best would be to look into the code and see what is where? Go to my GitHub and find the Smooth Scroll Top library. It isn't something extraordinary, but it is an excellent example of preparing the package with a modern approach. I had to agree on some compromises because I wanted to support the React apps scaffolded by Create React App. But these are small overheads. You'll find all the details in the README.md file.

Important config steps:

There are still many drawbacks in more significant projects, like handling third-party packages, optimization, tree shaking, etc. Of course, if you need to write the whole front-end app, you should probably still use bundlers and transpilers. But I can bet that we will float slowly towards architectures similar to Deno land, where we can import all as modules and put together our whole app. Like for example, using Web Components, etc.

I wrote an article about this topic on my blog. If you are interested, I would be more than happy to invite you to read more about complicated setups and issues. Please go and check it here: Building NPM package in 2021.

Let's stay in contact: Twitter and GitHub

How I implemented a search engine for my static blog generator

Julian.io — Tue, 01 Jun 2021 21:02:09 +0000

Lately, I worked on my static site generator, and one of the must-haves was that it should provide a search system. It should be pre-configured and ready to use after every new project initialization.
Also it should be based on clean JavaScript for simplicity.

Two fundamental problems here:

Source data
Solid and performant indexing solution

As for source data, I had two choices, read the blog posts from already generated HTML files or prepare JSON data with all blog posts at the build time. I chose the second one because the first one seems a little bit clunky and problematic. There could be many different edge cases when collecting the data. When building, I generate HTML files from markdown source files, so I had this step anyway.

As for the indexing solution, I chose Lunr. They describe themselves as "A bit like Solr, but much smaller and not as bright." I love that headline.
Lunr is a JavaScript library with a clean and simple API. It provides an indexing solution for provided source data. Then it allows triggering search on this set, using search phrase.

I won't focus on Lunr much here because they have excellent documentation, and there are many articles about it on the Internet. I wanted to show this particular implementation used in HaroldJS.

After new project initialization using my static site generator, you'll get the postsData.json file and already implemented JavaScript logic for the search engine.

Lunr initialization looks like that:

fetchPostsJsonData().then((data) => {
  searchIndex = lunr(function () {
    this.ref('fileName');
    this.field('title');
    this.field('body');
    this.field('excerpt');
    this.field('tags');
    data.forEach((doc) => {
      this.add(
        Object.assign(doc, {
          tags: doc.tags.join(' '),
          body: doc.body.replace(/(<([^>]+)>)/gi, ''),
        })
      );
    }, this);
  });
});

We fetched the data from the already generated postsData.json file and then created the Lunr search index. We need to add all fields from the JSON file, on which we will base our search index, and then we iterate through that data, adding it to the index. I've also implemented several improvements for multiple tags and cleanup for HTML to get better search results.

Then we have ready to use search function, which gets the search phrase as an argument and executes a search on the index. It looks like:

const searchResults = searchIndex.search(phrase);

Thanks to Lunr and my custom logic for postsData.json file generation, I have a search engine on every new project I want to create. It can be a blog, portfolio website, or documentation site. All packed with clean, responsive design and full-screen search interactions.

Of course, it needs some improvements at this stage, but the main idea was to have something which works and won't take a lot of time to implement.

Now, it also works when I will add or remove blog posts. It will rebuild the index, so every update of the search index depends on the actual state of our static blog.

I encourage you to play with Harold. Start with:

npm init harold-app my-blog

Also, please check out docs: www.haroldjs.com
And Github: create-harold-app
Quick walkthrough video: youtu.be/DG0T1Fg0mq0
Read more: https://www.julian.io/articles/blog-for-free.html