@dripfi/drip-sdk

Drip SDK

Introduction

The Drip SDK is a TypeScript library designed to interact with the Perq protocol. It provides methods to retrieve information about Perq Vaults, manage user authentication, and fetch user balances.

Table of Contents

• Installation
• Usage
• Modules
  • Core SDK
  • Lite Vaults
  • Loyalty Cards
  • Vesting
  • Recycler
  • Sign Handler
• Examples
• Types
• Abis

Installation

To use the Drip SDK in your project, you can install it via npm or yarn:

npm i @dripfi/drip-sdk

Usage

import PerqSdk from '@drip/sdk';
import { PerqConfig } from '@dripfi/drip-sdk';

Initialize the SDK with your Drip configuration and an optional signer:

const perqConfig: PerqConfig = PRODUCTION // if targeting ethereum mainnet

const perqConfig: PerqConfig = DEVELOPMENT // if targeting sepolia testnet

const perqSupportedChainId: PerqSupportedChainId = ETHEREUM_CHAIN_ID // if targeting ethereum mainnet for lite vaults

const perqSupportedChainId: PerqSupportedChainId = BASE_CHAIN_ID // if targeting base for lite vaults

const provider: ethers.providers.JsonRpcProvider = /* your Web3Provider instance */;

const perqSdk = new PerqSdk(perqConfig, perqSupportedChainId, provider?: ethers.providers.JsonRpcProvider);

Modules

Core SDK

Core methods available directly on the SDK instance:

Method	Description
updateSigner(newSigner: Signer): Promise<void>	Updates the signer for the SDK instance and all its modules.

Lite Vaults

Access Lite vault methods through sdk.lite:

Method	Description
getAllVaults(): Promise<VaultData[]>	Fetches all Lite vaults.
getVaultDetails(vaultAddress: string, onChainProjectId: number): Promise<VaultData>	Fetches Lite vault details.
deposit(tokenAddress: string, vaultAddress: string, onChainProjectId: number, amount: string): Promise<string>	Deposits into Lite vault.
withdraw(tokenAddress: string, vaultAddress: string, onChainProjectId: number, amount: string): Promise<string>	Withdraws from Lite vault.
swapAndDeposit(fromTokenAddress: string, toTokenAddress: string, amount: string, vaultAddress: string, onChainProjectId: number): Promise<string>	Swaps and deposits into Lite vault.
wrapAndDepositEth(vaultAddress: string, onChainProjectId: number, amount: string): Promise<string>	Wraps ETH and deposits.
getSwapAndDepositAllowance(tokenAddress: string): Promise<string>	Fetches the allowance for swap and deposit operations.
approveSwapAndDeposit(tokenAddress: string, amount: string): Promise<string>	Approves a token for swap and deposit operations.
getExpectedSwapResult(fromTokenAddress: string,toTokenAddress: string,amount: string,decimals: number, chainId: PerqSupportedChainId): Promise<string>	Calculates the expected result of a swap operation on a specific chain.

Loyalty Cards

Access loyalty card methods through sdk.loyaltyCards:

Method	Description
getBeansBalance(): Promise<BeansBalance>	Gets user's beans balance.
getBeansHistory(): Promise<BeanEntry[]>	Gets user's beans history.
getSwapPerqForBeansInfo(): Promise<PerqToBeansSwapInfo>	Gets swap info for Perq to beans.
upgradeLoyaltyCard(index: number): Promise<LoyaltyCard>	Upgrades loyalty card.
claimSpecialEditionCard(cardId: string): Promise<SpecialEditionLoyaltyCard>	Claims special edition loyalty card.
getOwnedLoyaltyCard(): Promise<LoyaltyCard>	Gets user's owned loyalty card.
getOwnedSpecialEditionCards(): Promise<SpecialEditionLoyaltyCard[]>	Gets user's owned special edition loyalty cards.
getAllLoyaltyCards(): Promise<LoyaltyCard[]>	Gets all available loyalty cards.
getAllSpecialEditionCards(): Promise<SpecialEditionLoyaltyCard[]>	Gets all available special edition loyalty cards.

Vesting

Access vesting methods through sdk.vesting:

Method	Description
getVestingStart(): Promise<string>	Gets vesting start time.
getVestingEnd(): Promise<string>	Gets vesting end time.
getVestedAmount(beneficiary: string): Promise<string>	Gets vested amount.
getReleasableAmount(beneficiary: string): Promise<string>	Gets releasable amount.
getReleasableTotalAmount(beneficiary: string): Promise<string>	Gets total releasable amount.
getAllVestingInfo(beneficiaryAddress: string): Promise<VestingInfo>	Gets all vesting info.
claimVestedPerq(amount: string): Promise<string>	Claims vested Perq.
burnVestedPerq(amount: string, price: string, deadline: string, signature: string): Promise<string>	Burns vested Perq.

Pools

Access pools methods through sdk.pools:

Method	Description
getUserPoolBalance(vaultAddress: string, onChainProjectId: number): Promise<string>	Fetches the user's balance in a specific pool.
getAllPools(): Promise<VaultData[]>	Fetches all available pools.
getMyPerqBalance(): Promise<MyPerqData[]>	Fetches the user's Perq balance.
getPoolDetails(vaultAddress: string, onChainProjectId: number): Promise<VaultData>	Fetches the details of a specific pool.
getAllProjects(): Promise<ReducedProjectData[]>	Fetches all available projects.
getProjectDetails(projectName: string): Promise<DetailedProjectData>	Fetches the details of a specific project.
getPoolStats(): Promise<VaultStats>	Fetches the statistics of a pool.
getOverallStats(): Promise<OverallStats>	Fetches different stats
getRewardsPerHour(vaultAddress: string): Promise<number>	Calculates the rewards per hour for a specific pool.
getUserBoostedNfts(vaultAddress: string): Promise<string[]>	Fetches the user's boosted NFTs for a specific pool.
getRewards(): Promise<UserRewards>	Fetches the user's rewards.

User

Access user methods through sdk.user:

Method	Description
linkSuiWalletWithEthWallet(suiWalletAddress: string): Promise<boolean>	Links a Sui wallet with an Ethereum wallet.
linkNearWalletWithEthWallet(nearWalletAddress: string): Promise<boolean>	Links a Near wallet with an Ethereum wallet.
getLinkedPodWallets(): Promise<LinkedPodWallets>	Retrieves all wallets linked to the user's Ethereum wallet.
getEarnings(projectName: string): Promise<Earnings>	Retrieves the user earnings for each project's vaults

Recycler

Access recycler methods through sdk.recycler:

Method	Description
getTokenAllowanceForRecycler(tokenAddress: string): Promise<BigNumber>	Retrieves the token allowance for the recycler contract.
getTokenAllowanceForSwapAndRecycler(tokenAddress: string): Promise<BigNumber>	Retrieves the token allowance for the swap and recycler contract.
async recycleTokens(tokenAddress: string = this.perqSdk.perqConfig.perqTokenAddress,amountToRecycle: string,beneficiary: string = ethers.constants.AddressZero,price: string,deadline: string,signature: string): Promise<string>	Initiates the recycling of tokens for a given beneficiary, price, and deadline.
swapAndRecycleETH(beneficiary: string,path: string[],minAmountOutWithDecimals: string,amountOfEth: string,price: string,deadline: string,signature: string): Promise<string>	Executes a swap and recycling operation for ETH.
swapAndRecycleERC20(beneficiary: string,path: string[],minAmountOutWithDecimals: string,amountInWithDecimals: string,price: string, deadline: string,signature: string): Promise<string>	Executes a swap and recycling operation for ERC20 tokens.
approveTokenForRecycler(tokenAddress: string, amount: string): Promise<string>	Approves a token for use with the recycler contract.
approveTokenForSwapAndRecycler(tokenAddress: string, amount: string): Promise<string>	Approves a token for use with the swap and recycler contract.

Token Utils

Access token utils methods through sdk.tokenUtils:

| Method | Description |

| -------------------------------------------------------------------- | -------------------------------------- | | getTokenPrice(tokenName: string): Promise<number> | Fetches the current price of a given token."perq", "weth" "eth" and "wbtc" are supported | | getAllowance(tokenAddress: string, spender: string): Promise<string> | Retrieves the current allowance for a token. | | approveAllowance(tokenAddress: string, amount: string, spenderAddress: string): Promise<string> | Approves a specific amount of tokens for use by a spender. | | transferErc20Token(tokenAddress: string, amount: string, receiver: string): Promise<string> | Transfers a specified amount of ERC20 tokens to a receiver. | | wrapEther(amount: string, tokenAddress: string): Promise<string> | Wraps a specified amount of Ether into a WETH token. | | getERC20TokenAllowance(spender: string, tokenAddress: string): Promise<BigNumber> | Retrieves the allowance for a specific ERC20 token. | | getPerqTokenContractAddress(): string | Returns the contract address of the Perq token. |

Sign Handler

Access signing methods through sdk.signHandler:

Method	Description
signPayload<T>(payload: T): Promise<NonceEnrichedSignedPayload<T>>	Signs a payload with nonce enrichment.

Examples

deposit(tokenAddress: string, vaultAddress: string, amount: string): Promise<string>

I want to deposit 100 USDC in a USDC vault:

USDC_TOKEN_ADDRESS = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"    --> USDC contract address in tenderly environment

you can get vault token address from the vault.depositToken.tokenAddress

VAULT_ADDRESS = "0x...c167" --> Check vaults returned by getAllVaults() and get vault address like: vault.vaultAddress

const txHash = await deposit(USDC_TOKEN_ADDRESS, VAULT_ADDRESS, '100')

[!NOTE] User will be prompted with 2 tx: 1st to approve token usage 2nd to deposit the funds in the vault

[!NOTE] Allowance is calculated by the deposit method, based on the current allowance and the required

[!IMPORTANT] Amount should be formatted, not parsed. In the example we want to deposit 100 USDC so we just input that value instead of adding 6 decimals (100000000)

---

swapAndDeposit(fromTokenAddress: string, toTokenAddress: string, fromTokenAmount: string, vaultAddress: string, onChainProjectId: number): Promise<string>

I want to deposit 1.5 ETH in a WETH vault:

WETH_TOKEN_ADDRESS = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"    --> WETH contract address example

// For depositing ETH into WETH pool you have to provide the WETH tokens address as a toTokenAddress as ETH itself doesn't have an address
const txHash = await swapAndDeposit(WETH_TOKEN_ADDRESS, WETH_TOKEN_ADDRESS, '0', vaultAddress, '1.5')

I want to deposit 100 DAI in a USDC vault:

DAI_TOKEN_ADDRESS = "0x6b175474e89094c44da98b954eedeac495271d0f"    --> DAI contract address example

// Assuming you already have the data of the vault
const txHash = await swapAndDeposit(DAI_TOKEN_ADDRESS, vault.depositToken.tokenAdrress, '100', vault.vaultAddress, vault.onChainProjectId)

[!IMPORTANT] ethAmount and fromTokenAmount should be formatted, not parsed. In the example we want to deposit 1.5 WETH so we just input that value instead of adding 18 decimals (1500000000000000000)

---

migrateDepositToOtherProject(tokenAddress: string, vaultAddress: string, onChainProjectId: number, targetOnChainProjectId, amount: string): Promise<string>

I want to migrate 50 USDC from projectA to projectB. ---> Let's assume we already fetched the data for these projects and selected the USDC pool of projectA which is called selectedPool in this example

const txHash = await lite.migrateDepositToOtherProject(
	selectedPool.depositToken.tokenAddress,
	selectedPool.vaultAddress,
	selectedPool.onChainProjectId,
	projectB.onChainProjectId || -1,
	'50',
);

---

withdraw(tokenAddress: string, vaultAddress: string, onChainProjectId: number, amount: string): Promise<string>

const userBalanceObject = await getUserBalance();
const balance = userBalanceObject.userbalance;

[!NOTE] If i check balance, that is the max amount I can withdraw

I want to withdraw 100 USDC from the 1st vault fetched. ---> Let's assume the first vault is a USDC vault for simplicity Fetch vaults returned by getAllVault() and pass the vault you want to withdraw from, and the amount to withdraw (100 in this example)

const txHash = await lite.withdraw(
	vaultToWithdrawFrom.depositToken.tokenAddress,
	vaultToWithdrawFrom.vaultAddress,
	vaultToWithdrawFrom.onChainProjectId,
	'100',
);

I want to withdraw 3.55 WETH from the 1st vault fetched. ---> Let's assume the first vault is a WETH vault for simplicity Fetch vaults returned by getAllVault() and pass the vault you want to withdraw from, and the amount to withdraw (3.55 in this example)

const vaults = await sdk.pools.getAllPools();
const vaultToWithdrawFrom = vaults[0];

const txHash = await lite.withdraw(
	vaultToWithdrawFrom.depositToken.tokenAddress,
	vaultToWithdrawFrom.vaultAddress,
	vaultToWithdrawFrom.onChainProjectId,
	'3.55',
);

Types

type Asset = {
	decimals: number;
	symbol: string;
};

type BeanEntry = {
	address: string;
	reason: string;
	recycledAmount: string;
	beansAmount: string;
	beansSum: string;
	amountDepositedInUsd: string;
	createdAt: string;
	chainId: number;
	nonce: number;
};

type BeansBalance = {
	balance: string;
	bonusesClaimed: string[];
};

type DeployedProject = {
	id: number | undefined;
	projectName: string;
	owners: string[];
	logo: string;
	telegramLink: string;
	twitterLink: string;
	mediumLink: string;
	deckLink: string;
	roadmapLink: string;
	economicsLink: string;
	discordLink: string;
	docsLink: string;
	whitepaperLink: string;
	litepaperLink: string;
	websiteLink: string;
	supplyAtLaunch: number;
	fdv: number;
	latestRoundPriceInUsd: number;
	totalSupply: number;
	disabledTgePrice: boolean;
	backers: ProjectBacker[];
	networks: string[];
	content: string;
	tgeDate?: string;
	tgePrice?: number;
	vAPY?: number;
	wikiLink: string;
	youTubeLink: string;
	tikTokLink: string;
	stretchGoals: StretchGoal[];
	projectInfoText: string;
	projectRewardText: string;
	coingeckoId?: string;
	projectType: string;
	isFeatured: boolean;
	yelayVersion: YelayVersion;
	bannerImage?: string;
	rewardImage?: string;
	rewardTooltipName?: string;
};

type DeployedVault = {
	projectId: number;
	vaultAddress: string;
	liveUntil: string;
	liveFrom: string;
	type: VaultType;
	depositTokenId: string;
	rewards: VaultReward[];
	project?: DeployedProject;
	coingeckoId?: string;
	expectedTge?: string;
};

type DepositToken = {
	name: string;
	symbol: string;
	roundingDecimals: number;
	precisionDecimals: number;
	tokenAddress: string;
};

enum ELoyaltyCardTier {
	White = 'White',
	Ivory = 'Ivory',
	Dune = 'Dune',
	Amber = 'Amber',
	Sienna = 'Sienna',
	Umber = 'Umber',
	Black = 'Black',
}

type LoyaltyCard = {
	id: string;
	tier: ELoyaltyCardTier;
	level: number;
	cost: number;
	boost: number;
};

type MyPerqBalance = {
	currentlyDeposited: number;
	earnedRewards: number;
	earnedRewardsUsd: number;
	rewardsPerHour: number;
};

type MyPerqData = VaultData & MyPerqBalance {
	ethPrice: number;
	btcPrice: number;
	distributionType: VaultType;
	projectTvl: number;
};

type NFTBoost = {
	url: string;
	tokenAddress: string;
	multiplier: number;
	nftAddress: string;
	network: string;
	initialBlock: number;
	imagePath: string;
};

type BasePayload<T> = {
	payload: T;
};

type LinkedPodWallets = {
	suiWalletAddr: string;
	nearWalletAddr: string;
};

type NonceEnrichedPayload<T> = T & {
	deadline: number;
	signature: string;
};

type NonceEnrichedSignedPayload<T> = {
	signature: string;
	signerAddress: string;
	payload: NonceEnrichedPayload<T>;
};

type PerqConfig = {
	route: string;
	yelayLiteSdkConfig: sdkConfig;
	perqTokenAddress: string;
	perqTokenRecyclerAddress: string;
	perqSwapAndRecyclerAddress: string;
	perqVestingAddress: string;
	swapAndDepositContractAddress: string;
	smartVaultManagerContractAddress: string;
	ethereumSwapperAddress: string;
	baseSwapperAddress: string;
};

type PerqToBeansSwapInfo = {
	perqPrice: number;
	price: number;
	priceInFloat: number;
	deadline: number;
	signature: string;
};

type ProjectBacker = {
	name: string;
	image: string;
	link: string;
};

type QLFastRedeem = {
	assetsWithdrawn: {
		asset: {
			decimals: number;
			id: string;
			name: string;
			symbol: string;
		};
		claimed: string;
		id: string;
	}[];
	blockNumber: number;
	id: string;
	svtWithdrawn: string;
};

type SpecialEditionLoyaltyCard = {
	id: string;
	name: string;
	boost: number;
	projects: number[];
	startDate: Date;
	endDate: Date;
};

type Strategy = {
	address: string;
	lastDoHardWorkTime: number | null;
	lastDoHardWorkBlock: number | null;
	name: string;
	assetGroupId: number;
	apy: number;
};

interface StretchGoal {
	threshhold: number;
	amountOfTokens: number;
}

type SwapInfo = {
	swapTarget: any;
	token: string;
	swapCallData: any;
};

type UpgradeLoyaltyCardPayload = {
	index: number;
};

type ClaimSpecialEditionLoyaltyCardPayload = {
	cardId: string;
};

type UserRewards = {
	// vaultAddress => pointsName => rewardsAmount
	[vaultAddress: string]: { [rewardPointsName: string]: number };
};

type VaultData = {
	tvlUsd: number;
	depositToken: DepositToken;
	vaultAddress: string;
	projectName: string;
	projectLogo: string;
	projectType: string;
	liveFrom: string;
	liveUntil: string;
	apy: number;
	tokenPrice: number;
	change24h: number;
	volume24h: number;
	onChainProjectId: number;
	isActive: boolean;
	owners: string[];
	coingeckoId?: string;
	expectedTge?: string;
	chainId: ChainId;
	distributionType: VaultType;
	strategies: Strategy[];
	rewards: VaultReward[];
	stretchGoals: StretchGoal[];
};

type VaultData = {
	depositToken: DepositToken;
	vaultAddress: string;
	projectName: string;
	projectLogo: string;
	projectType: string;
	liveFrom: string;
	liveUntil: string;
	apy: number;
	tvlUsd: number;
	avgTvl: number;
	tokenPrice: number;
	change24h: number;
	volume24h: number;
	peakTvl: number;
	onChainProjectId: number;
	combinedTvl: number;
	isActive: boolean;
	owners: string[];
	coingeckoId?: string;
	expectedTge?: string;
	chainId: ChainId;
	strategies: Strategy[];
	stretchGoals: StretchGoal[];
	rewards: VaultReward[];
	rewardTooltipName: string;
};

type VaultReward = {
	id: number | undefined;
	type: RewardType;
	name: string;
	symbol: string;
	decimals: number;
	tokenAddress: string;
	monthlyEmissionRate: number;
	blockNumber: number;
	rewardRate: number;
	timestamp: number;
	endTime: number;
};

type VaultStats = {
	totalTVL: number;
	totalUsers: number;
	activeVaults: number;
};

type VaultType = 'launch' | 'earn' | 'airdrop';

type VestingInfo = {
	startTimestamp: string;
	endTimestamp: string;
	vested: string;
	releasable: string;
	releasableTotal: string;
};

type YelayVersion = 'v2' | 'lite';

// Additional Types:

type ReducedProjectData = {
	tvlUsd: number;
	peakTvlUsd: number;
	projectName: string;
	logo: string;
	bannerImage: string;
	rewardImage: string;
	rewardTooltipName: string;
	projectInfoText: string;
	projectType: string;
	distributionType: VaultType;
	liveUntil: string;
	liveFrom: string;
	vAPY: number;
	chainIds: number[];
	isFeatured: boolean;
	currencies: DepositToken[];
	isHidden: boolean;
};

type DetailedProjectData = ReducedProjectData & {
	supplyAtLaunch: number;
	fdv: number;
	totalSupply: number;
	content: string;
	telegramLink: string;
	twitterLink: string;
	mediumLink: string;
	deckLink: string;
	roadmapLink: string;
	economicsLink: string;
	discordLink: string;
	docsLink: string;
	whitepaperLink: string;
	litepaperLink: string;
	websiteLink: string;
	projectType: string;
	wikiLink: string;
	youTubeLink: string;
	tikTokLink: string;
	projectRewardText: string;
	networks: string[];
	protocols: string[];
	yelayVersion: YelayVersion;
	stretchGoals: StretchGoal[];
	backers: ProjectBacker[];
	vaults: VaultData[];
}

type RewardType = 'token' | 'points';

type SDKConfig = {
	chainId: number;
	rpcUrl: string;
	// ... other SDK configuration
};

const BASE_CHAIN_ID = 8453;
const ETHEREUM_CHAIN_ID = 1;
const ETHEREUM_SEPOLIA_CHAIN_ID = 11155111;
const ARBITRUM_CHAIN_ID = 42161;
const SONIC_CHAIN_ID = 146;

type ChainId =
	| typeof BASE_CHAIN_ID
	| typeof ETHEREUM_CHAIN_ID
	| typeof ETHEREUM_SEPOLIA_CHAIN_ID
	| typeof ARBITRUM_CHAIN_ID
	| typeof SONIC_CHAIN_ID;

type Earnings = {
	[vaultAddress: string]: {
		onChainProjectId: number;
		precisionDecimals: number;
		amountEarned: string;
		symbol: string;
		deposit: string;
		earningPerHour: string;
	};
};

type OverallStats = {
	activeProjects: number;
	totalTvl: number;
	totalYieldUsd: number;
	totalUsers: number;
};

Abis

• PERQ_SWAP_AND_RECYCLER_ABI

• WETH_TOKEN_ABI

• PERQ_TOKEN_ABI

• TOKEN_RECYCLER_ABI

• PERQ_VESTING_ABI