ZapFarm - integrate conversion depositing into your app

ZapFarm is a plugin, which enables you to integrate conversion depositing into your centralized or decentralized application. Briefly, ZapFarm allows your users to provide liquidity in a single transaction using any funds on any chain. Check the feature description and ZapFarm presentation.

You can integrate ZapFarm within minutes using ZapFarm SDK, which is described below.

ZapFarm SDK

@minimax/zap-farm-sdk is a library that allows you to easily integrate ZapFarm widget into your application and communicate with it. ZapFarm SDK is developed using TypeScript, ensuring strict typings.

Example usage

To start ZapFarm widget, all you need to do is provide a basic configuration to ZapFarm SDK constructor:

import { ZapFarmSDK } from '@minimax/zap-farm-sdk';

const zapFarm = new ZapFarmSDK({
  userAddress: '<user's wallet address>',
  pool: {
    blockchainID: <your liquidity pool's blockchain ID>,
    address: '<your liquidity pool's address>',
  },
  ...otherOptions,
});

zapFarm.show();

That's it! Create ZapFarm SDK instance with a configuration object and call the .show() method when you want to show ZapFarm widget to your users.

For now, if you want to close ZapFarm widget and open it again, you'll need to create new ZapFarm SDK instance, meaning you can't reuse the existing instance. While it may sound limiting, practice shows that you'll rarely need to reopen previously closed ZapFarm widget.

Installation

You can find the package here.

Install via Yarn:

yarn add @minimax/zap-farm-sdk

Install via npm:

npm install @minimax/zap-farm-sdk

In the future, you will be able to use a script tag.

Initialization

Just call new ZapFarmSDK(config) - this will do the necessary prep work for the widget, but won't display it yet. In order to display the widget, run .show() on the instance of the ZapFarmSDK class.

.show() adds the widget to the DOM - specifically, to the body element - starting from that moment, the semi-transparent overlay with a loader appears and the widget starts booting up.

Subscribing to events

In order to subscribe to an event, use the .on(eventType, callback) method on the SDK instance.

The .on(eventType, callback) method accepts either a string with the event's type when you want to subscribe to a specific kind of an event or '*' for subscribing to any event.

callback is called each time a given event occurs.

In order to unsubscribe, call the .unsubscribe(eventType, callback) method with the event type and handler you want to stop receiving updates for.

.on(eventType, callback) and .unsubscribe(eventType, callback)are chainable:

new ZapFarmSDK({ ... })
  .on(...)
  .unsubscribe(...)
  .show();

Configuration

We provide three options for using the SDK:

1. Event mode (you will need to process SDK events on your side).
2. Provider mode (requires an ethers-compatible provider).
3. WIP: Delegation mode.

Event Mode

In event mode, ZapFarm will generate events of certain types, which you can handle on your side in any way you want. The list of available event types will be published later in the corresponding documentation section.

Example:

const zapFarm = new ZapFarmSDK({
  mode: 'events',
  userAddress: 'vitalik.eth', // Required in event mode.
  ...otherOptions,
});

zapFarm
  .on('*', (event) => console.log(event))
  .on('TRANSACTION_READY', async (event) => {
    const signer = provider.getSigner();

    const tx = await signer.sendTransaction(event.payload)
    const receipt = await tx.wait()
  })
  .on('WIDGET_CLOSE', (event) => console.log(event));

zapFarm.show();

When using other types of integration, all events will also be broadcast to the SDK entity and you can use them to display any interface effects.

Provider Mode

Provider mode allows you to easily integrate ZapFarm SDK into your dApp. In this case you need to pass your configuration to a provider:

new ZapFarmSDK({
  mode: 'provider',
  provider: provider,
  ...otherOptions,
}).show();

ZapFarm will generate, send and process approve, deposit (and others, if needed in the future) transactions on its own. You will be able to get information about all the events inside your SDK (e.g. for your app UI changes, or for analytics) using the event system.

WIP: Delegation Mode

In delegate mode, the user's path is completely transferred to ZapFarm.

We will offer users to login (via all modern wallets, including MetaMask, WalletConnect etc.), necessary approves and the deposit itself, and then close the widget.

At this time, you will be able to handle all actions through the SDK and have the access to all events that happen on our side.

Currently, MetaMask's mobile application doesn't support iframe and therefore is not working with ZapFarm.

Integration variants

ZapFarm allows you to integrate it in multiple ways depending on your app's UI and needs.

Overlay mode

If you want ZapFarm to open as an overlay over your app, you should go with this mode. It uses our SDK, so all you need to do is to provide a basic configuration and display ZapFarm widget when you need it.

Embedded mode

This is the mode you want to use if you want to put ZapFarm widget in some DOM element on your page so that you can have a more customized way of displaying our widget. It uses ZapFarm SDK just like the overlay mode - the only difference is that you need to provide a containerNode alongside your configuration:

new ZapFarmSDK({ 
  containerNode: document.getElementById('zap-farm-container'),
  ...otherOptions,
});