Skip to main content
Version: V4

Client Library

Tests Coverage Status ts MIT license npm Discord

This library includes a simplified interface for interacting with a v4 PoolTogether deployment. Create an instance of PrizePoolNetwork and use the initialized PrizePool and PrizeDistributor to begin reading and writing data to the protocol.

There are several classes that provide interfaces to the different aspects of the V4 PoolTogether protocol. PrizePoolNetwork is the main entry point. A full tutorial is available here.

The Client library also exports several namespaces from the Utility library for convenience.

💾   Installation​

This project is available as an NPM package:

npm install @pooltogether/v4-utils-js

or

yarn add @pooltogether/v4-client-js

The repo can be cloned from Github for contributions.

git clone https://github.com/pooltogether/v4-client-js.git

🏎️   Quickstart​

PrizePoolNetwork​

A PrizePoolNetwork is a collection of PrizePool and PrizeDistributor across several chains that make up a v4 deployment.

To create an instance of PrizePoolNetwork you will need:

  • A Contract List containing all of the relevant contracts for a v4 prize pool. You can obtain this by generating your own after deploying a v4 Prize Pool (start here). Or by importing a copy of our current deployments v4-pool-data.
  • Ethers providers for every chain that a Prize Pool is deployed on.
import { PrizePoolNetwork } from "@pooltogether/v4-client-js";
import { mainnet } from "@pooltogether/v4-pool-data";

const PrizePoolNetwork = new PrizePoolNetwork(providers, mainnet);

PrizePool​

A PrizePool is a representation of a Prize Pool deployment. The Prize Pool is responsible for managing deposits, withdrawals & delegation. PrizePool is a read only object, for write capabilities check out User

const prizePool = PrizePoolNetwork.getPrizePool(1, "0xabc123");

User​

A User is wrapper around PrizePool with the ability to send transactions to manage deposits, withdrawals and delegation.

const user = new User(prizePool.prizePoolMetadata, signer, prizePool);

PrizeDistributor​

A PrizeDistributor is what handles prizes. It is used to determine the current draw, check for prizes & claiming prizes. For write capabilities, pass a Signer when creating an instance.

const prizeDistributor = PrizePoolNetwork.getPrizeDistributor(1, "0xabc123");
const prizeDistributor = PrizePoolNetwork.getPrizeDistributor(1, "0xabc123");
const signer = provider.getSigner();
const signerPrizeDistributor = new PrizeDistributor(
  prizeDistributor.prizeDistributorMetadata,
  signer,
  prizeDistributor.contractMetadataList
);

🧮   Examples​

Get token data for a Prize Pool​

const tokenData = await prizePool.getTokenData(); // Underlying token (ex. USDC)
const ticketData = await prizePool.getTicketData(); // Ticket token

Get a users deposit token & ticket balances​

const usersBalances: {
  chainId: number,
  address: string,
  balances: PrizePoolTokenBalances,
}[] = await PrizePoolNetwork.getUsersPrizePoolBalances(usersAddress);

Get a users deposit token & ticket balance​

const balance: PrizePoolTokenBalances =
  await prizePool.getUsersPrizePoolBalances(usersAddress);

Approve deposits​

NOTE: Make sure you're shifting by the proper decimal amount

const txResponse: TransactionResponse = await user.approveDeposits(
  ethers.utils.parseUnits(10, decimals)
);

Deposit and delegate tokens​

NOTE: Make sure you're shifting by the proper decimal amount

const txResponse: TransactionResponse = await user.depositAndDelegate(
  ethers.utils.parseUnits(10, decimals)
);

Deposit tokens​

NOTE: Make sure you're shifting by the proper decimal amount

const txResponse: TransactionResponse = await user.deposit(
  ethers.utils.parseUnits(10, decimals)
);

Withdraw tokens​

NOTE: Make sure you're shifting by the proper decimal amount

const txResponse: TransactionResponse = await user.withdraw(
  ethers.utils.parseUnits(10, decimals)
);

Get valid draw ids​

Valid draw ids are draw ids that have all of the relevant data pushed to their respective chain & are not expired.

const drawIds = await prizeDistributor.getValidDrawIds();

Get a users prizes​

const drawResults = await PrizeApi.getUsersDrawResultsByDraw(
  chainId,
  usersAddress,
  prizeDistributorAddress,
  drawId,
  maxPicksPerUser
);

Claim a users prizes​

NOTE: Ensure the PrizeDistributor was initialized with a Signer

const txResponse: TransactionResponse =
  await prizeDistributor.claimPrizesByDraw(1);