@generationsoftware/pt-v5-utils-js

🧰 Javascript Utility Library - PoolTogether V5

📖 Documentation

Compute

The @generationsoftware/v5-utils-js node module package provides computations for the PoolTogether v5 protocol.

High-order operations like processing subgraphs and chain state (draws, winners, etc..) is included in the compute namespaced functions.

🖥️ Computations:

Consume subgraph and protocol chain state to return computed outcomes:

• computeDrawWinners

Create Issue to request new features.
Open Pull Request adhering to Contribution guidelines.

💾 Installation

This project is available as an NPM package:

npm install @generationsoftware/v5-utils-js

yarn add @generationsoftware/v5-utils-js

The repo can be cloned from Github for contributions.

git clone https://github.com/generationsoftware/v5-utils-js

📄 Contracts Blob

downloadContractsBlob(contractJsonUrl)

Gets the list of contracts for a specific network. Typically this would be the URL of the raw JSON file on committed on GitHub.

import { downloadContractsBlob } from "@generationsoftware/v5-utils-js";

async function runAsync() {
  const contracts = await downloadContractsBlob(contractJsonUrl);
}
runAsync();

🏆 Draw Results

computeDrawWinners(provider, contracts, subgraphUrl)

A helper function that runs five intensive utility functions to compute and return a JSON blob of all previous draw winner's Claim objects for each tier of a prize pool, grouped by vault.

import { computeDrawWinners } from "@generationsoftware/v5-utils-js";

async function runAsync() {
  const subgraphUrl = "https://api.studio.thegraph.com/query/63100/pt-v5-optimism/version/latest";

  // Compute Winners for the last Draw
  const winners = await computeDrawWinners(provider, contracts, subgraphUrl);
}
runAsync();

// Returns Claim[] array:
//
// interface Claim {
//   vault: string;
//   winner: string;
//   tier: number;
//   prizeIndex: number;
//   claimed?: boolean;
// }
//

🏊 Prize Pool Info

getPrizePoolInfo(readProvider, contracts)

Gathers info about the prize pool contained in provided the contracts JSON blob.

import { getPrizePoolInfo, PrizePoolInfo } from "@generationsoftware/v5-utils-js";

async function runAsync() {
  const prizePoolInfo: PrizePoolInfo = await getPrizePoolInfo(readProvider, contracts);
}
runAsync();

// Returns PrizePoolInfo object:
//
// interface PrizePoolInfo {
//   drawId: number;
//   numTiers: number;
//   numPrizeIndices: number;
//   reserve: string;
//   tiersRangeArray: number[]; // an easily iterable range of numbers for each tier available (ie. [0, 1, 2])
//   tierPrizeData: {
//     [tierNum: string]: TierPrizeData;
//   };
// }
//
// interface TierPrizeData {
//   prizeIndicesCount: number;
//   prizeIndicesRangeArray: number[]; // an easily iterable range of numbers for each tier's prize indices
//   amount: BigNumber;
//   liquidity: BigNumber;
// }
//

🏦 Get Subgraph Prize Vaults

getSubgraphPrizeVaults(subgraphUrl)

Collects all vaults from the PT v5 subgraph for a specific chain into an array.

import { getSubgraphPrizeVaults } from "@generationsoftware/v5-utils-js";

async function runAsync() {
  const subgraphUrl = "https://api.studio.thegraph.com/query/63100/pt-v5-optimism/version/latest";

  const prizeVaults = await getSubgraphPrizeVaults(subgraphUrl);
}
runAsync();

// Returns PrizeVault[] array:
//
// interface PrizeVault {
//  id: string;
//  accounts: PrizeVaultAccount[]; // empty
// }

👥 Populate Subgraph Prize Vault Accounts

populateSubgraphPrizeVaultAccounts(subgraphUrl, vaults)

Takes the prize vaults from getSubgraphPrizeVaults and adds user deposit account arrays for each. populateSubgraphPrizeVaultAccounts is split up into a separate call from getSubgraphPrizeVaults as it's very network heavy, needing to page through potentially hundreds of thousands of accounts from the subgraph.

import { populateSubgraphPrizeVaultAccounts } from "@generationsoftware/v5-utils-js";

async function runAsync() {
  const subgraphUrl = "https://api.studio.thegraph.com/query/63100/pt-v5-optimism/version/latest";

  let prizeVaults = await getSubgraphPrizeVaults(subgraphUrl);

  prizeVaults = await populateSubgraphPrizeVaultAccounts(subgraphUrl, prizeVaults);
}
runAsync();

// Returns PrizeVault[] array:
//
// interface PrizeVault {
//  ...
//  accounts: PrizeVaultAccount[]; // populated!
// }

🏁 Get Winner's Claims

getWinnersClaims(readaProvider, prizePoolInfo, contracts, vaults)

Collects Claim objects into an array for all prizes in the past draw.

import { getWinnersClaims } from "@generationsoftware/v5-utils-js";

async function runAsync() {
  let claims: Claim[] = await getWinnersClaims(readProvider, prizePoolInfo, contracts, vaults);
}
runAsync();

// Returns Claim[] array:
//
// interface Vault {
//  vault: string;
//  winner: string;
//  tier: number;
//  prizeIndex: number;
//  claimed?: boolean; // null
// }

🏁 Flag Claimed (RPC)

flagClaimedRpc(readProvider, contracts, claims)

Adds the claimed boolean to the claims using RPC lookups.

import { flagClaimedRpc } from "@generationsoftware/v5-utils-js";

async function runAsync() {
  claims = await flagClaimedRpc(readProvider, contracts, claims);
}
runAsync();

// Returns Claim[] array:
//
// interface Vault {
//  ...
//  claimed?: boolean; // now set true or false
// }