@neutral-trade/sdk 0.3.1 → 0.3.4

package/dist/index.d.mts

@@ -3256,7 +3256,7 @@ declare enum VaultCategory {
   privateCredit = "Private Credit",
   airdropFarming = "Airdrop Farming",
   yieldEnhancement = "Yield Enhancement",
-  fundOfFund = "Fund Of Fund",
+  fundOfFund = "Master Vault",
 }
 /** Raw vault entry from registry JSON */
 interface VaultRegistryEntry {
@@ -3383,11 +3383,12 @@ declare class NeutralTrade {
   buildDepositInstructions({
     vaultId,
     userAddress,
-    amount
+    amountRaw
   }: {
     vaultId: number;
     userAddress: string;
-    amount: number;
+    /** Smallest token units (decimal string), same scale as SPL `amount`. */
+    amountRaw: string;
   }): Promise<TransactionInstruction[]>;
   /**
    * Build request-withdraw instruction. Fetches vault, oracle, and depositor accounts on-chain.
@@ -3395,30 +3396,60 @@ declare class NeutralTrade {
   buildRequestWithdrawInstruction({
     vaultId,
     userAddress,
-    amount
+    amountRaw
   }: {
     vaultId: number;
     userAddress: string;
-    amount: number;
+    /** Smallest token units (decimal string) to request withdrawing. */
+    amountRaw: string;
   }): Promise<TransactionInstruction>;
 }
 //#endregion
+//#region src/utils/amount-raw.d.ts
+/**
+ * Parse `amountRaw`: base-10 digits only, smallest token units (same scale as SPL `amount`).
+ * @throws Error with message `INVALID_AMOUNT_RAW` on invalid input
+ */
+declare function parseAmountRawToBigInt(amountRaw: string): bigint;
+/**
+ * Legacy UI path: finite `human` × 10^`decimals`, rounded to nearest integer token unit.
+ * Prefer integrators sending `amountRaw` from a decimal string instead of this helper.
+ * @throws Error with message `INVALID_HUMAN_AMOUNT` when out of range or non-finite
+ */
+declare function humanFloatToAmountRawString(human: number, decimals: number): string;
+//#endregion
 //#region src/utils/bundle-instructions.d.ts
 interface BuildBundleDepositInstructionsParams {
   bundleProgram: Program<Ntbundle>;
   bundleCluster?: BundleCluster;
   vault: VaultRegistryEntry;
   user: PublicKey;
-  /** UI token amount (multiplied by 10**on-chain decimals inside). */
-  amount: number;
+  /** Smallest token units (decimal string), same scale as SPL token `amount`. */
+  amountRaw: string;
 }
 interface BuildBundleRequestWithdrawInstructionParams {
   bundleProgram: Program<Ntbundle>;
   bundleCluster?: BundleCluster;
   vault: VaultRegistryEntry;
   user: PublicKey;
-  amount: number;
+  /** Smallest token units (decimal string) to request withdrawing. */
+  amountRaw: string;
 }
+/**
+ * Shares to burn for `requestWithdrawal`, from integer token raw and on-chain totals.
+ * Full position: pass `amountRaw >= userTokenRaw` where `userTokenRaw = (userShares * totalEquity) / totalShares`.
+ */
+declare function computeRequestWithdrawalSharesFromAmountRaw({
+  amountRaw,
+  userShares,
+  totalEquity,
+  totalShares
+}: {
+  amountRaw: bigint;
+  userShares: BN;
+  totalEquity: bigint;
+  totalShares: bigint;
+}): BN;
 /**
  * `initializeBundleDepositor` (when missing) + `requestDeposit`. Fetches bundle + user bundle internally.
  */
@@ -3427,7 +3458,7 @@ declare function buildBundleDepositInstructions({
   bundleCluster,
   vault,
   user,
-  amount
+  amountRaw
 }: BuildBundleDepositInstructionsParams): Promise<TransactionInstruction[]>;
 /**
  * `requestWithdrawal` only. Fetches bundle, oracle, and user bundle internally.
@@ -3437,7 +3468,7 @@ declare function buildBundleRequestWithdrawInstruction({
   bundleCluster,
   vault,
   user,
-  amount
+  amountRaw
 }: BuildBundleRequestWithdrawInstructionParams): Promise<TransactionInstruction>;
 //#endregion
 //#region src/utils/pda.d.ts
@@ -3467,4 +3498,4 @@ declare function derivePendingAuthPDA(bundlePDA: PublicKey, programId: PublicKey
  */
 declare function getVaultDepositorAddressSync(programId: PublicKey, vault: PublicKey, authority: PublicKey): PublicKey;
 //#endregion
-export { BUNDLE_PROGRAM_ID_V2_MAINNET, type BundleAccount, type BundleCluster, type BundleProgram, type BundleProvider, DEFAULT_BUNDLE_PROGRAM_ID_DEVNET, DEFAULT_BUNDLE_PROGRAM_ID_MAINNET, DevnetVaultId, NeutralTrade, type NeutralTradeConfig, type NeutralTradeCoreContext, type OracleData, SEED_ORACLE, SEED_PENDING_AUTH, SEED_TEMP, SEED_USER, SupportedChain, SupportedToken, type Token, type UserBalanceResult, type UserBundleAccount, type UserBundleTempData, type VaultBalanceData, VaultCategory, type VaultRegistryEntry as VaultConfig, type VaultRegistry as VaultConfigRecord, VaultId, VaultType, buildBundleDepositInstructions, buildBundleRequestWithdrawInstruction, createBundleProgramById, createDummyWallet, deriveOraclePDA, derivePendingAuthPDA, deriveTempDataPDA, deriveUserPDA, getBundleProgramId, getDefaultBundleProgramIdByCluster, getSolanaTokenDecimals, getSolanaTokenMint, getVaultByAddress, getVaultById, getVaultDepositorAddressSync, getVaultRegistry, isValidVaultAddress, tokens, vaults, vaultsDevnet };
+export { BUNDLE_PROGRAM_ID_V2_MAINNET, type BuildBundleDepositInstructionsParams, type BuildBundleRequestWithdrawInstructionParams, type BundleAccount, type BundleCluster, type BundleProgram, type BundleProvider, DEFAULT_BUNDLE_PROGRAM_ID_DEVNET, DEFAULT_BUNDLE_PROGRAM_ID_MAINNET, DevnetVaultId, NeutralTrade, type NeutralTradeConfig, type NeutralTradeCoreContext, type OracleData, SEED_ORACLE, SEED_PENDING_AUTH, SEED_TEMP, SEED_USER, SupportedChain, SupportedToken, type Token, type UserBalanceResult, type UserBundleAccount, type UserBundleTempData, type VaultBalanceData, VaultCategory, type VaultRegistryEntry as VaultConfig, type VaultRegistry as VaultConfigRecord, VaultId, VaultType, buildBundleDepositInstructions, buildBundleRequestWithdrawInstruction, computeRequestWithdrawalSharesFromAmountRaw, createBundleProgramById, createDummyWallet, deriveOraclePDA, derivePendingAuthPDA, deriveTempDataPDA, deriveUserPDA, getBundleProgramId, getDefaultBundleProgramIdByCluster, getSolanaTokenDecimals, getSolanaTokenMint, getVaultByAddress, getVaultById, getVaultDepositorAddressSync, getVaultRegistry, humanFloatToAmountRawString, isValidVaultAddress, parseAmountRawToBigInt, tokens, vaults, vaultsDevnet };

package/dist/index.mjs

@@ -11831,7 +11831,7 @@ var vaults_default = [
 		"vaultId": 76,
 		"name": "Master Bundle",
 		"type": "Bundle",
-		"category": "Fund Of Fund",
+		"category": "Master Vault",
 		"vaultAddress": "J7qhMAKnB6G5dvoAN9281ufabajKbyGQxxd2bq6R7fPJ",
 		"depositToken": "USDC",
 		"pointsMultiplier": 1,
@@ -12794,7 +12794,7 @@ let VaultCategory = /* @__PURE__ */ function(VaultCategory$1) {
 	VaultCategory$1["privateCredit"] = "Private Credit";
 	VaultCategory$1["airdropFarming"] = "Airdrop Farming";
 	VaultCategory$1["yieldEnhancement"] = "Yield Enhancement";
-	VaultCategory$1["fundOfFund"] = "Fund Of Fund";
+	VaultCategory$1["fundOfFund"] = "Master Vault";
 	return VaultCategory$1;
 }({});
 /** Zod schema for validating registry entries */
@@ -13085,14 +13085,50 @@ async function getBundleBalances({ vaultIds, userAddress, vaults: vaults$1, bund
 	return result;
 }
 
+//#endregion
+//#region src/utils/amount-raw.ts
+/** Max SPL token amount we accept (fits u64). */
+const U64_MAX = 18446744073709551615n;
+/**
+* Parse `amountRaw`: base-10 digits only, smallest token units (same scale as SPL `amount`).
+* @throws Error with message `INVALID_AMOUNT_RAW` on invalid input
+*/
+function parseAmountRawToBigInt(amountRaw) {
+	const t = amountRaw.trim();
+	if (!/^\d+$/.test(t)) throw new Error("INVALID_AMOUNT_RAW");
+	const v = BigInt(t);
+	if (v <= 0n) throw new Error("INVALID_AMOUNT_RAW");
+	if (v > U64_MAX) throw new Error("INVALID_AMOUNT_RAW");
+	return v;
+}
+/**
+* Legacy UI path: finite `human` × 10^`decimals`, rounded to nearest integer token unit.
+* Prefer integrators sending `amountRaw` from a decimal string instead of this helper.
+* @throws Error with message `INVALID_HUMAN_AMOUNT` when out of range or non-finite
+*/
+function humanFloatToAmountRawString(human, decimals) {
+	if (!Number.isFinite(human) || human <= 0) throw new Error("INVALID_HUMAN_AMOUNT");
+	if (!Number.isInteger(decimals) || decimals < 0 || decimals > 18) throw new Error("INVALID_HUMAN_AMOUNT");
+	const scaled = human * 10 ** decimals;
+	if (!Number.isFinite(scaled)) throw new Error("INVALID_HUMAN_AMOUNT");
+	const rounded = Math.round(scaled);
+	if (rounded <= 0) throw new Error("INVALID_HUMAN_AMOUNT");
+	return parseAmountRawToBigInt(BigInt(rounded).toString()).toString();
+}
+
 //#endregion
 //#region src/utils/bundle-instructions.ts
-/** Same share math as legacy app `useBundleRequestWithdrawMutation`. */
-function computeRequestWithdrawalSharesAmount({ amount, userVaultBalance, pps, assetDecimals, userShares }) {
-	let sharesAmount;
-	if (Number(amount) >= Number(userVaultBalance)) sharesAmount = userShares;
-	else sharesAmount = new BN(Math.floor(amount * 10 ** assetDecimals / pps));
-	return sharesAmount.lte(userShares) ? sharesAmount : userShares;
+/**
+* Shares to burn for `requestWithdrawal`, from integer token raw and on-chain totals.
+* Full position: pass `amountRaw >= userTokenRaw` where `userTokenRaw = (userShares * totalEquity) / totalShares`.
+*/
+function computeRequestWithdrawalSharesFromAmountRaw({ amountRaw, userShares, totalEquity, totalShares }) {
+	const us = BigInt(userShares.toString());
+	if (totalShares === 0n || us === 0n) return new BN(0);
+	if (amountRaw >= us * totalEquity / totalShares) return userShares;
+	if (totalEquity === 0n) return new BN(0);
+	const sharesBn = new BN((amountRaw * totalShares / totalEquity).toString());
+	return sharesBn.gt(userShares) ? userShares : sharesBn;
 }
 function assertBundleVault(vault) {
 	if (vault.type !== VaultType.Bundle) throw new Error(`Vault ${vault.vaultId} is not a Bundle vault`);
@@ -13105,7 +13141,7 @@ function bundleProgramIdForVault(vault, bundleCluster = "mainnet") {
 /**
 * `initializeBundleDepositor` (when missing) + `requestDeposit`. Fetches bundle + user bundle internally.
 */
-async function buildBundleDepositInstructions({ bundleProgram, bundleCluster = "mainnet", vault, user, amount }) {
+async function buildBundleDepositInstructions({ bundleProgram, bundleCluster = "mainnet", vault, user, amountRaw }) {
 	assertBundleVault(vault);
 	const bundlePDA = new PublicKey(vault.vaultAddress);
 	const programId = bundleProgramIdForVault(vault, bundleCluster);
@@ -13116,7 +13152,7 @@ async function buildBundleDepositInstructions({ bundleProgram, bundleCluster = "
 	if (!bundleAcc?.data?.length) throw new Error(`Bundle account not found for vault ${vault.vaultId}`);
 	const bundleInfo = bundleProgram.coder.accounts.decode("bundle", bundleAcc.data);
 	const needsInit = (userBundleAcc?.data?.length ? bundleProgram.coder.accounts.decode("userBundleAccount", userBundleAcc.data) : null) === null;
-	const depositAmountBN = new BN(Math.floor(amount * 10 ** bundleInfo.assetDecimals));
+	const depositAmountBn = new BN(parseAmountRawToBigInt(amountRaw).toString());
 	const oraclePDA = deriveOraclePDA(bundlePDA, programPk);
 	const tempDataPDA = deriveTempDataPDA(bundlePDA, programPk);
 	const pendingAuthPDA = derivePendingAuthPDA(bundlePDA, programPk);
@@ -13133,7 +13169,7 @@ async function buildBundleDepositInstructions({ bundleProgram, bundleCluster = "
 		}).instruction();
 		instructions$2.push(initIx);
 	}
-	const depositIx = await bundleProgram.methods.requestDeposit(depositAmountBN).accounts({
+	const depositIx = await bundleProgram.methods.requestDeposit(depositAmountBn).accounts({
 		user,
 		userTokenAccount: userTokenAcct,
 		pendingDepositTokenAccount: pendingTokenAcct,
@@ -13153,7 +13189,7 @@ async function buildBundleDepositInstructions({ bundleProgram, bundleCluster = "
 /**
 * `requestWithdrawal` only. Fetches bundle, oracle, and user bundle internally.
 */
-async function buildBundleRequestWithdrawInstruction({ bundleProgram, bundleCluster = "mainnet", vault, user, amount }) {
+async function buildBundleRequestWithdrawInstruction({ bundleProgram, bundleCluster = "mainnet", vault, user, amountRaw }) {
 	assertBundleVault(vault);
 	const bundlePDA = new PublicKey(vault.vaultAddress);
 	const programId = bundleProgramIdForVault(vault, bundleCluster);
@@ -13167,19 +13203,13 @@ async function buildBundleRequestWithdrawInstruction({ bundleProgram, bundleClus
 		bundleProgram.account.oracleData.fetch(oraclePDA),
 		bundleProgram.account.userBundleAccount.fetch(userPDA)
 	]);
-	const pps = calculateOnChainPps({
-		oracleAverageExternalEquity: BigInt(oracleData.averageExternalEquity.toString()),
-		bundleUnderlyingBalance: BigInt(bundleAccount.bundleUnderlyingBalance.toString()),
-		totalShares: BigInt(bundleAccount.totalShares.toString())
-	});
-	const divisor = 10 ** bundleAccount.assetDecimals;
-	const userSharesNum = Number(userBundle.shares.toString());
-	const sharesAmount = computeRequestWithdrawalSharesAmount({
-		amount,
-		userVaultBalance: Math.round(userSharesNum * pps) / divisor,
-		pps,
-		assetDecimals: bundleAccount.assetDecimals,
-		userShares: new BN(userBundle.shares.toString())
+	const totalEquity = BigInt(oracleData.averageExternalEquity.toString()) + BigInt(bundleAccount.bundleUnderlyingBalance.toString());
+	const totalShares = BigInt(bundleAccount.totalShares.toString());
+	const sharesAmount = computeRequestWithdrawalSharesFromAmountRaw({
+		amountRaw: parseAmountRawToBigInt(amountRaw),
+		userShares: new BN(userBundle.shares.toString()),
+		totalEquity,
+		totalShares
 	});
 	return await bundleProgram.methods.requestWithdrawal(sharesAmount).accounts({
 		user,
@@ -13364,7 +13394,7 @@ var NeutralTrade = class NeutralTrade {
 	* Build deposit instructions (`initializeBundleDepositor` when needed, then `requestDeposit`).
 	* Fetches bundle and user bundle accounts on-chain.
 	*/
-	async buildDepositInstructions({ vaultId, userAddress, amount }) {
+	async buildDepositInstructions({ vaultId, userAddress, amountRaw }) {
 		const vault = this.vaults[vaultId];
 		if (!vault) throw new Error(`Vault config not found for vaultId ${vaultId}`);
 		return buildBundleDepositInstructions({
@@ -13372,13 +13402,13 @@ var NeutralTrade = class NeutralTrade {
 			bundleCluster: this.bundleCluster,
 			vault,
 			user: new PublicKey(userAddress),
-			amount
+			amountRaw
 		});
 	}
 	/**
 	* Build request-withdraw instruction. Fetches vault, oracle, and depositor accounts on-chain.
 	*/
-	async buildRequestWithdrawInstruction({ vaultId, userAddress, amount }) {
+	async buildRequestWithdrawInstruction({ vaultId, userAddress, amountRaw }) {
 		const vault = this.vaults[vaultId];
 		if (!vault) throw new Error(`Vault config not found for vaultId ${vaultId}`);
 		return buildBundleRequestWithdrawInstruction({
@@ -13386,10 +13416,10 @@ var NeutralTrade = class NeutralTrade {
 			bundleCluster: this.bundleCluster,
 			vault,
 			user: new PublicKey(userAddress),
-			amount
+			amountRaw
 		});
 	}
 };
 
 //#endregion
-export { BUNDLE_PROGRAM_ID_V2_MAINNET, DEFAULT_BUNDLE_PROGRAM_ID_DEVNET, DEFAULT_BUNDLE_PROGRAM_ID_MAINNET, DevnetVaultId, NeutralTrade, SEED_ORACLE, SEED_PENDING_AUTH, SEED_TEMP, SEED_USER, SupportedChain, SupportedToken, VaultCategory, VaultId, VaultType, buildBundleDepositInstructions, buildBundleRequestWithdrawInstruction, createBundleProgramById, createDummyWallet, deriveOraclePDA, derivePendingAuthPDA, deriveTempDataPDA, deriveUserPDA, getBundleProgramId, getDefaultBundleProgramIdByCluster, getSolanaTokenDecimals, getSolanaTokenMint, getVaultByAddress, getVaultById, getVaultDepositorAddressSync, getVaultRegistry, isValidVaultAddress, tokens, vaults, vaultsDevnet };
+export { BUNDLE_PROGRAM_ID_V2_MAINNET, DEFAULT_BUNDLE_PROGRAM_ID_DEVNET, DEFAULT_BUNDLE_PROGRAM_ID_MAINNET, DevnetVaultId, NeutralTrade, SEED_ORACLE, SEED_PENDING_AUTH, SEED_TEMP, SEED_USER, SupportedChain, SupportedToken, VaultCategory, VaultId, VaultType, buildBundleDepositInstructions, buildBundleRequestWithdrawInstruction, computeRequestWithdrawalSharesFromAmountRaw, createBundleProgramById, createDummyWallet, deriveOraclePDA, derivePendingAuthPDA, deriveTempDataPDA, deriveUserPDA, getBundleProgramId, getDefaultBundleProgramIdByCluster, getSolanaTokenDecimals, getSolanaTokenMint, getVaultByAddress, getVaultById, getVaultDepositorAddressSync, getVaultRegistry, humanFloatToAmountRawString, isValidVaultAddress, parseAmountRawToBigInt, tokens, vaults, vaultsDevnet };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@neutral-trade/sdk",
   "type": "module",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "SDK for Neutral Trade vaults",
   "license": "MIT",
   "homepage": "https://github.com/neutral-trade/sdk#readme",
@@ -71,8 +71,8 @@
     "start": "tsx src/index.ts",
     "example:devnet:deposit": "tsx examples/devnet-deposit.ts",
     "example:devnet:withdraw": "tsx examples/devnet-withdraw.ts",
-    "diagnose:balances": "tsx diagnose/vault-balance-fetch.ts",
-    "diagnose:deposit-conservation": "tsx diagnose/deposit-conservation.ts",
+    "example:api:deposit": "tsx examples/api-deposit.ts",
+    "example:api:withdraw": "tsx examples/api-withdraw.ts",
     "test": "vitest",
     "typecheck": "tsc",
     "docs:build": "typedoc",