💻 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 theVaultList
. - 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)