Skip to main content

Leveraging Javascript API for Massa interaction

danger

Important Note:

  • This documentation represents the latest version of the Massa Web3 JS Library as of August 2024. However, please be aware that a significant update is coming soon. The v2 will introduce new features, improvements, and potentially some changes to the existing API.

  • We encourage you to check back regularly for the most up-to-date information. Once the new version is released, this documentation will be comprehensively updated to reflect all changes and new capabilities.

  • Thank you for your patience and continued interest in the Massa Web3 JS Library.

We already started to add the new documentation for the upcoming version. You can find it here.

What is Massa-Web3?​

Massa-web3 is an exhaustive library enabling interaction with the Massa blockchain. It can be used in a browser environment and Node.js runtime.

note

Massa-web3 operates by utilizing JsonRPC API in the background to facilitate blockchain communication. The API is divided into a Private and a Public segment, used for node management and blockchain interactions, respectively. For more information on the API, please refer to the JsonRPC API documentation.

Massa-web3 will allow you to interact with the Massa blockchain in a variety of ways:

  • Send transactions
  • Deploy smart contracts
  • Create, manage and inspect addresses
  • Manage your node
  • Fetch events from the blockchain
  • And much more!

In addition, the library includes a collection of handy utility functions (e.g conversion between different units, etc).

tip

For a quick integration of Massa within a web browser, consider reading our Web Frontend Integration Guide.

Installation​

Massa-web3 can be used as a library for frameworks or as a stand-alone bundled js file which can be easily loaded into the browser.

Requirements​

  • NodeJS 14+
  • npm / yarn (see package.json)

As a library (Node.js/React/Vue.js)​

Just install the library using npm:

npm install @massalabs/massa-web3

In a browser​

If you want to use the library in a vanilla javascript project, please add the following script tag to your html file:

<script
  type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/@massalabs/massa-web3@latest/bundle.js"
></script>

In your code, once the script is fully loaded, just use window.massa to access all massa-web3 exports.

console.log("Massa Web3 ", window.massa);

Initialization​

Some usage of massa-web3 require an account. This account can be either provided using Wallet-provider or directly in the code

With Wallet-provider​

The Wallet-provider allows you to easily connect your dApp to a user's wallet, without having to worry about secret keys and other sensitive information. The Wallet-provider will automatically detect if a wallet is installed and connect to it.

Full code can be found here

useEffect(() => {
  const registerAndSetProvider = async () => {
    try {
      let provider = (await providers(true, 10000))[0];
      let accounts = await provider.accounts();
      if (accounts.length === 0) {
        setErrorMessage("No accounts found");
        return;
      }
      setAccount(accounts[0]);
      if (!account || !provider) {
        return;
      }
      setClient(await ClientFactory.fromWalletProvider(provider, account));
    } catch (e) {
      console.log(e);
      setErrorMessage(
        "Please install massa station and the wallet plugin and refresh."
      );
    }
  };
  registerAndSetProvider();
}, [account]);

Without Wallet-provider​

You can easily initialize a client instance using the ClientFactory class:

const baseAccount: IAccount = await WalletClient.getAccountFromSecretKey(
  privateKey
);
const chainId = CHAIN_ID.MainNet;

const testnetClient: Client = await ClientFactory.createDefaultClient(
  DefaultProviderUrls.MAINNET,
  chainId,
  true, // retry failed requests
  baseAccount // optional parameter
);
info

When initializing the client, you have the option to specify a baseAccount. If provided, this account will be used as the default executor for upcoming calls. If you choose to initialize the client without a baseAccount, it becomes mandatory to specify the executor for each call that requires a signature. You can learn more about how to manage the base account in the Wallet Operations section.

Client exposed APIs​

Once there is an initialized client instance, it is straightforward to call methods on it:

const balance = await web3Client.wallet().getAccountBalance("address");

You can find details for each of the exposed APIs with all the available methods in the following sections: