mercury-sdk

The mercury-sdk is a comprehensive SDK that empowers developers to seamlessly interact with the Mercury Indexer. It has been developed and it's currently supported by the PaltaLabs 🥑 Team.

Useful links:

• Documentation: https://mercury-sdk.paltalabs.io/
• NPM Package: https://www.npmjs.com/package/mercury-sdk
• Github Repo: https://github.com/paltalabs/mercury-sdk/
• Discord: https://discord.gg/QaezKEWXqX

Installation

You can install the package via npm:

npm install mercury-sdk
Copy

Create and fill the .env file

cp .env.example .env
Copy

Usage

Instantiate

Create an instance of mercury:

import { Mercury } from "mercury-sdk";

const mercuryInstance = new Mercury({
  backendEndpoint: process.env.MERCURY_BACKEND_ENDPOINT,
  graphqlEndpoint: process.env.MERCURY_GRAPHQL_ENDPOINT,
  // The post-install script should have saved an API key to .env
  apiKey: process.env.MERCURY_API_KEY,
});
Copy

endpoints should be without "/" and without /graphql or any other path. It should be only domain:port.

Subscriptions

Subscribe to an event:

mercuryInstance.subscribeToContractEvents({
  contractId: "someContractId",
});
Copy

Subscribe to full accounts:

mercuryInstance.subscribeToFullAccount({
  address: "someStellarAddress",
});
Copy

Subscribe to ledger entries:

const contractAddress = "CDSUTAZNBTBAMG2SVZ63FRIBIJOEBSRVVR4GZ3TDXX25AHUN5N3ZYMYU";
const args = {
    contractId: contractAddress,
    keyXdr: "AAAAFA==",
    durability: "persistent",
    hydrate: true,
}
const subscribe = await mercuryInstance.subscribeToLedgerEntries(args).catch((err) => {
    console.error(err)
})
Copy

Review subscriptions:

mercuryInstance.getAllContractEventSubscriptions();
Copy

or for Accounts

mercuryInstance.getAllFullAccountSubscriptions();
Copy

Retrieve information

retrieve sent payments:

mercuryInstance.getSentPayments({
  publicKey: "someStellarAddress",
});
Copy

retrieve received payments:

mercuryInstance.getReceivedPayments({
  publicKey: "someStellarAddress",
});
Copy

retrieve path payments strict send:

mercuryInstance.getPathPaymentsStrictSend({
  publicKey: "someStellarAddress",
});
Copy

retrieve path payments strict receive:

mercuryInstance.getPathPaymentsStrictReceive({
  publicKey: "someStellarAddress",
});
Copy

retrieve SDEX add liquidity:

mercuryInstance.getLiquidityPoolDeposit({
  publicKey: "someStellarAddress",
});
Copy

retrieve SDEX remove liquidity:

mercuryInstance.getLiquidityPoolWithdraw({
  publicKey: "someStellarAddress",
});
Copy

retrieve contract events:

mercuryInstance.getContractEvents({
contractId: "someContractId",
});
Copy

Parse data results

You can use data parsers to get the results in a cleaner way than just the big GraphQL response

Available parsers:

import {
  getSentPaymentsParser,
  getReceivedPaymentsParser,
  getPathPaymentsStrictSendParser,
  getPathPaymentsStrictReceiveParser,
  getLiquidityPoolWithdrawParser,
  getLiquidityPoolDepositParser,
} from "mercury-sdk";

async function someFunction() {
  //Sent payments
  const sentPaymentsResponse = await mercuryInstance.getSentPayments({
    publicKey: "someStellarAddress",
  });

  if (sentPaymentsResponse.ok) {
    const sentPaymentsParsedData = getSentPaymentsParser(
      sentPaymentsResponse.data!
    );
  }

  //Received payments
  const receivedPaymentsResponse = await mercuryInstance.getReceivedPayments({
    publicKey: "someStellarAddress",
  });

  if (receivedPaymentsResponse.ok) {
    const receivedPaymentsParsedData = getReceivedPaymentsParser(
      receivedPaymentsResponse.data!
    );
  }

  //Path Payments Strict Send
  const pathPaymentsStrictSendResponse =
    await mercuryInstance.getPathPaymentsStrictSend({
      publicKey: "someStellarAddress",
    });

  if (pathPaymentsStrictSendResponse.ok) {
    const pathPaymentsStrictSendParsedData = getPathPaymentsStrictSendParser(
      pathPaymentsStrictSendResponse.data!
    );
  }

  //Path Payments Strict Receive
  const pathPaymentsStrictReceiveResponse =
    await mercuryInstance.getPathPaymentsStrictReceive({
      publicKey: "someStellarAddress",
    });

  if (pathPaymentsStrictReceiveResponse.ok) {
    const pathPaymentsStrictReceiveParsedData =
      getPathPaymentsStrictReceiveParser(
        pathPaymentsStrictReceiveResponse.data!
      );
  }

  //Liquidity Pool Withdraw
  const liquidityPoolWithdrawResponse =
    await mercuryInstance.getLiquidityPoolWithdraw({
      publicKey: "someStellarAddress",
    });

  if (liquidityPoolWithdrawResponse.ok) {
    const liquidityPoolWithdrawParsedData = getLiquidityPoolWithdrawParser(
      liquidityPoolWithdrawResponse.data!
    );
  }

  //Liquidity Pool Deposit
  const liquidityPoolDepositResponse =
    await mercuryInstance.getLiquidityPoolDeposit({
      publicKey: "someStellarAddress",
    });

  if (liquidityPoolDepositResponse.ok) {
    const liquidityPoolDepositParsedData = getLiquidityPoolDepositParser(
      liquidityPoolDepositResponse.data!
    );
  }
}
  // Soroswap Events:
  const soroswapEvents = 
    await mercuryInstance.getContractEvents({
      contractId: "someContractId",
    });
  const soroswapEventsParsedData = await getContractEventsParser(
    soroswapEvents.data!
  );
Copy

Local development

Setup your environment variables:

cp .env.example .env
Copy

complete the data

You can use the script run.sh. To run a docker image with node.

Use yarn Install dependencies with yarn

You can play around with the code in src/example.ts and run it with:

yarn start:example
Copy

In order to get your changes reflected in another project that is using yarn link to point to this one you need to run:

yarn tsc
Copy

This will compile typescript into the folder dist/ where other projects will look for the code.

Publish a new version

Make sure you have setup the npm token in your environment variables. Run yarn publish and follow the instructions.