💻   PoolTogether Hyperstucture Client Library

Client Monorepo | Documentation | Prize Pool Contract | Vault Contract

🏆   Overview

A JS client library for wrapping Viem contracts and providing simple, unopinionated interfaces for interacting with the protocol.

The library exports the following classes to interact with different aspects of the protocol, including reading and writing onchain data:

• PrizePool
• Vault
• Vaults

Useful utilities and types are also exported from internal packages. See the utilities or types packages for more info.

💾   Installation

This library is available as an NPM package:

npm install @pooltogether/hyperstructure-client-js

or

pnpm install @pooltogether/hyperstructure-client-js

or

yarn add @pooltogether/hyperstructure-client-js

🏎️   Quickstart

PrizePool

A PrizePool is an interface to interact with a prize pool contract, which is responsible for aggregating contributions from all vaults and awarding prizes.

To create an instance of a PrizePool, you will need:

• The chain ID of the network the prize pool contract is deployed to.
• The prize pool's address.
• A Viem public client.

If you'd like to use any write methods, you must also provide a Viem wallet client.

import { PrizePool } from 'hyperstructure-client-js'
import { createPublicClient, createWalletClient } from 'viem'

// Viem clients
const publicClient = createPublicClient({ ... })
const walletClient = createWalletClient({ ... })

// Optional parameters
const options = {
  walletClient: walletClient,
  prizeTokenAddress: '0x456...',
  drawPeriodInSeconds: 86_400,
  tierShares: 100
}

// Initializing PrizePool
const prizePool = new PrizePool(1, '0x123...', publicClient, options)

Vault

A Vault is an interface to interact with a vault contract, which is an ERC4626 wrapper around any yield source, responsible for deposits and withdrawals.

To create an instance of a Vault, you will need:

• The chain ID of the network the vault contract is deployed to.
• The vault's address.
• A Viem public client.

If you'd like to use any write methods, you must also provide a Viem wallet client.

import { Vault } from 'hyperstructure-client-js'
import { createPublicClient, createWalletClient } from 'viem'

// Viem clients
const publicClient = createPublicClient({ ... })
const walletClient = createWalletClient({ ... })

// Optional parameters
const options = {
  walletClient: walletClient,
  decimals: 18,
  tokenAddress: '0x456...',
  name: 'Really Cool Vault',
  logoURI: 'https://...',
  tokenLogoURI: 'https://...'
}

// Initializing Vault
const vault = new Vault(1, '0x123...', publicClient, options)

Vaults

A Vaults is an read-only interface for multiple vault contracts. It is meant to take in all vaults in a VaultList and create Vault objects for each of them, allowing for more efficient aggregate queries.

To create an instance of Vaults, you will need:

• An array of VaultInfo data for each of the vaults in the VaultList.
• Viem public clients for each network vaults are deployed in.

See the typing of a VaultList here.

import { Vaults } from 'hyperstructure-client-js'

// VaultList
const vaultList = {
  name: 'Amazing Vault List',
  version: { ... },
  timestamp: '...',
  tokens: [{ ... }]
}

// Viem public clients
const publicClients = {
  1: createPublicClient({ ... }),
  10: createPublicClient({ ... }),
  42161: createPublicClient({ ... })
}

// Initializing Vaults
const vaults = new Vaults(vaultList.tokens, publicClients)

🧮   Examples

Getting prize token data for a prize pool

const tokenData = await prizePool.getPrizeTokenData()

Getting a prize pool's last awarded draw ID

const lastDrawId = await prizePool.getLastDrawId()

Getting estimated prize amounts and frequency for all tiers of a prize pool

const allPrizeInfo = await prizePool.getAllPrizeInfo()

Claiming a prize from a prize pool

NOTE: Since this is a write function, a wallet client is required when initializing PrizePool.

const userAddress = '0x123...'
const prizeTier = 0
const txHash = await prizePool.claimPrize(userAddress, prizeTier)

Getting token & share data for a vault

const tokenData = await vault.getTokenData() // Deposited asset
const shareData = await vault.getShareData() // Receipt token

Getting a user's deposited balance for a vault

const userAddress = '0x123...'
const tokenBalance = await vault.getUserTokenBalance(userAddress)
const shareBalance = await vault.getUserShareBalance(userAddress)

Getting total tokens deposited in a vault

const totalTokenBalance = await vault.getTotalTokenBalance()

Depositing into a vault

NOTE: Since this is a write function, a wallet client is required when initializing Vault.

const amount = 123456789n // Bigint value w/ decimals
const txHash = await vault.deposit(amount)

Withdrawing from a vault

NOTE: Since this is a write function, a wallet client is required when initializing Vault.

NOTE: You can withdraw a token amount, but it is generally better to redeem a share amount.

const amount = 123456789n // Bigint value w/ decimals
const txHash = await vault.redeem(amount)

Getting token & share data for multiple vaults

const allTokenData = await vaults.getTokenData()
const allShareData = await vaults.getShareData()

Getting a user's deposited balances for multiple vaults

const userAddress = '0x123...'
const allTokenBalances = await vaults.getUserTokenBalances(userAddress)
const allShareBalances = await vaults.getUserShareBalances(userAddress)