Zebec Instant Card SDK

An sdk for interacting with zebec instant card program in solana.

Usage

To use this sdk, you are required to create a instance of ZebecCardService.

const connection = new Connection(process.env.RPC_URL || clusterApiUrl("mainnet-beta"));
const wallet = useWallet(); // Note: only in frontend. Use `Wallet` from anchor to create wallet instance for backends.
const provider = getAnchorProvider(connection, wallet);
const program = ZebecCardProgramFactory.getProgram(provider);
const instructions = new ZebecCardInstructions(program);
const service = new ZebecCardService(instructions, connection, wallet.signTranaction);

If you are using the service only for fetching pda data, then you don't need to pass third argument which signTransaction function. Also you can use ZebecConnectionProvider to create program instance for such case.

const provider = getZebecConnectionProvider(connection);
const program = ZebecCardProgramFactory.getProgram(provider);
const instructions = new ZebecCardInstructions(program);
const service = new ZebecCardService(instructions, connection);

Initialize Card Config

Card config can be initialize only one time in the program.

const zicOwnerAddress = provider.publicKey.toString();
const cardVaultAddress = "7yJfc32yFeRWTsPQjon38zEuKPGQLbAy8hoz3CVa5A8u";
const revenueVaultAddress = "9EYFiACQrVYYYZaZiE6gD82TfUPXu9FqABbckVMRvHLV";
const commissionVaultAddress = "2efiJoaS2C6tEgWWhXaHxWDPJBk6XLL3TVS6ERXx4AX4";
const revenueFeePercent = "2.5";
const nativeFeePercent = "1.5";
const nonNativeFeePercent = "5";
const usdcAddress = "De31sBPcDejCVpZZh1fq8SNs7AcuWcBKuU3k2jqnkmKc";
const minCardAmount = "5";
const maxCardAmount = "100";
const dailyCardPurchaseLimit = "80";

const feeTiers = [
	{
		minAmount: "5",
		maxAmount: "10",
		feePercent: "5",
	},
	{
		minAmount: "10",
		maxAmount: "40",
		feePercent: "4",
	},
	{
		minAmount: "40",
		maxAmount: "100",
		feePercent: "3",
	},
].map<FeeTier>((ft) => {
	return {
		feePercent: parsePercentString(ft.feePercent),
		maxAmount: parseDecimalString(ft.maxAmount),
		minAmount: parseDecimalString(ft.minAmount),
	};
});

const params: InitCardConfigParams = {
	revenueFeePercent: parsePercentString(revenueFeePercent),
	nativeFeePercent: parsePercentString(nativeFeePercent),
	nonNativeFeePercent: parsePercentString(nonNativeFeePercent),
	zicOwnerAddress,
	usdcAddress,
	commissionVaultAddress,
	cardVaultAddress,
	revenueVaultAddress,
	maxCardAmount: parseDecimalString(maxCardAmount),
	minCardAmount: parseDecimalString(minCardAmount),
	feeTiers,
	dailyCardPurchaseLimit: parseDecimalString(dailyCardPurchaseLimit),
};

const payload = await service.initCardConfig(params);
const signature = await payload.execute();

If you need to update card config use setCardConfig method.

Update Card Config

const zicOwnerAddress = provider.publicKey.toString();
const cardVaultAddress = "7yJfc32yFeRWTsPQjon38zEuKPGQLbAy8hoz3CVa5A8u";
const revenueVaultAddress = "9EYFiACQrVYYYZaZiE6gD82TfUPXu9FqABbckVMRvHLV";
const commissionVaultAddress = "2efiJoaS2C6tEgWWhXaHxWDPJBk6XLL3TVS6ERXx4AX4";
const revenueFeePercent = "2.5";
const nativeFeePercent = "1.5";
const nonNativeFeePercent = "5.0";
const minCardAmount = "5";
const maxCardAmount = "1000";
const dailyCardPurchaseLimit = "100";
const feeTiers: FeeTier[] = [
	{
		minAmount: "5",
		maxAmount: "100",
		feePercent: "6.5",
	},
	{
		minAmount: "101",
		maxAmount: "500",
		feePercent: "3.0",
	},
	{
		minAmount: "501",
		maxAmount: "1000",
		feePercent: "0.5",
	},
].map<FeeTier>((ft) => {
	return {
		feePercent: parsePercentString(ft.feePercent),
		maxAmount: parseDecimalString(ft.maxAmount),
		minAmount: parseDecimalString(ft.minAmount),
	};
});

const params: SetCardConfigParams = {
	revenueFeePercent: parsePercentString(revenueFeePercent),
	nativeFeePercent: parsePercentString(nativeFeePercent),
	nonNativeFeePercent: parsePercentString(nonNativeFeePercent),
	commissionVaultAddress,
	zicOwnerAddress,
	cardVaultAddress,
	revenueVaultAddress,
	feeTiers,
	maxCardAmount: parseDecimalString(maxCardAmount),
	minCardAmount: parseDecimalString(minCardAmount),
	dailyCardPurchaseLimit: parseDecimalString(dailyCardPurchaseLimit),
};

const payload = await service.setCardConfig(params);
const signature = await payload.execute();

Deposit USDC

While depositing usdc, a unique pda for each deposit is generated from buyers address, a seed phrase and a counter and is initialized. This pda holds data such as amount deposited, type of card requested, etc. The counter is validated in program such that it should be index in card pda plus one. The service instance provides a method for getting next counter.

const userAddress = "<wallet public key>";
const mintAddress = "<usdc mint address>";
const amount = "100";
const params: DepositParams = {
	amount: parseDecimalString(amount),
	userAddress,
	mintAddress,
};

const payload = await service.deposit(params);

const signature = await payload.execute();

Swap and deposit

The swap and deposit method swaps the given input mint to USDC. The swap mode is ExactOut means you specify how much USDC you want to swap and in this case slippage is on the input amount.

const userAddress = "<wallet public key>";
const inputAmount = "1";
const inputMintAddress = "<mint address>";
// const inputMintAddress = "zebeczgi5fSEtbpfQKVZKCJ3WgYXxjkMUkNNx7fLKAF";
const outputMintAddress = "<usdc mint address>";
const slippagePercent = "0.1";

const params: SwapAndDepositParams = {
	userAddress,
	outputMintAddress,
	inputAmount: parseDecimalString(inputAmount),
	inputMintAddress,
	slippagePercent: parsePercentString(slippagePercent),
};

const payload = await service.swapAndDeposit(params);

const signature = await payload.execute();

Withdraw

const userAddress = "<wallet public key>";
const mintAddress = "<usdc mint address>";
const amount = "10";

const params: WithdrawParams = {
	amount: parseDecimalString(amount),
	userAddress,
	mintAddress,
};

const payload = await service.withdraw(params);

const signature = await payload.execute();

Purchase card

To purchase card you need to call buycard method. It transfers usdc from user's vault to card treasury vault deducting commission and revenue fee.

const buyerAddress = "<wallet public key>";
const mintAddress = "<usdc mint address>";
const amount = "5";
const cardTypeId: CardTypeId = "103115238587";
const buyerEmail = parseEmailString("[email protected]");

const nextBuyerCounter = await service.getNextBuyerCounter();
console.debug("next buyer counter", nextBuyerCounter);

const params: BuyCardParams = {
	amount: parseDecimalString(amount),
	cardTypeId,
	nextBuyerCounter,
	buyerAddress,
	mintAddress,
	buyerEmail,
};
const payload = await service.buyCard(params);

const signature = await payload.execute();

Fetch config data

const configData: CardConfigInfo = await service.getCardConfigInfo();
console.log("configData", configData);

Fetch user purchase record of a day

const buyerAddress = "<pubkey string>";
const userPurchaseRecordPda = ZebecCardService.deriveUserPurchaseRecordPda(
	buyerAddress,
	program.programId,
);
const info: UserPurchaseRecordInfo = await service.getUserPurchaseRecord(userPurchaseRecordPda);

console.log("info", info);

Fetch user vault balance

const balance: string = await service.getUserVaultBalance(userAddress, mintAddress);

console.log("balance:", balance);

Fetch card purchase info

const buyerAddress = "<wallet public key>";
const buyerCounter = BigInt("1");

const buyerPda = ZebecCardService.deriveBuyerPda(buyerAddress, program.programId, buyerCounter);
const info: CardPurchaseInfo = await service.getCardPurchaseInfo(buyerPda);

console.log("info", info);

Fetch all card purchase info of a user

const buyerAddress = "<wallet public key>";

const infos: CardPurchaseInfo[] = await service.getAllCardPurchaseInfo(buyerAddress);

console.log("infos", infos);

Fetch swap quote info

const inputMintAddress = "AZsHEMXd36Bj1EMNXhowJajpUXzrKcK57wW4ZGXVa7yR"; // guac
const outputMintAddress = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"; // usdc
const inputAmount = "0.1";
const slippagePercent = "0.1";
const params: GetQuoteInfoParams = {
	inputMintAddress,
	outputMintAddress,
	inputAmount: parseDecimalString(inputAmount),
	slippagePercent: parsePercentString(slippagePercent),
};
const info = await service.getQuoteInfo(params);

console.log("info", info);