@neutral-trade/sdk 0.2.13 → 0.3.3

package/README.md

@@ -147,7 +147,16 @@ This is simpler and doesn't require an additional network request at initializat
 
 ## Examples
 
-Check out the [examples](./examples) directory for more usage examples.
+See the [examples](./examples) directory. From the `sdk/` package root (clone this repo):
+
+```bash
+# Local validator default RPC: http://127.0.0.1:8899 — override with SOLANA_RPC_URL
+export SOLANA_KEYPAIR_PATH="$HOME/.config/solana/id.json"
+pnpm example:devnet:deposit
+pnpm example:devnet:withdraw
+```
+
+Uses the built-in devnet registry (`src/registry/vaults.devnet.json`, e.g. vault `100000001`). Your RPC must serve that vault on-chain; override vault id with `DEVNET_BUNDLE_VAULT_ID` if you use `NeutralTrade.create({ registry: [...] })` patterns in a forked script.
 
 ## License
 

package/dist/index.d.mts

@@ -3377,18 +3377,18 @@ declare class NeutralTrade {
     userAddress: string;
   }): Promise<UserBalanceResult>;
   /**
-   * Build deposit instructions (optional init + requestDeposit). Fetches vault state on-chain.
+   * Build deposit instructions (`initializeBundleDepositor` when needed, then `requestDeposit`).
+   * Fetches bundle and user bundle accounts on-chain.
    */
   buildDepositInstructions({
     vaultId,
     userAddress,
-    amount,
-    needsInit
+    amountRaw
   }: {
     vaultId: number;
     userAddress: string;
-    amount: number;
-    needsInit?: boolean;
+    /** 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.
@@ -3396,41 +3396,69 @@ 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;
-  needsInit?: boolean;
+  /** 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;
 }
 /**
- * Optional `initializeBundleDepositor` + `requestDeposit`. Fetches bundle account internally.
+ * 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.
  */
 declare function buildBundleDepositInstructions({
   bundleProgram,
   bundleCluster,
   vault,
   user,
-  amount,
-  needsInit
+  amountRaw
 }: BuildBundleDepositInstructionsParams): Promise<TransactionInstruction[]>;
 /**
  * `requestWithdrawal` only. Fetches bundle, oracle, and user bundle internally.
@@ -3440,7 +3468,7 @@ declare function buildBundleRequestWithdrawInstruction({
   bundleCluster,
   vault,
   user,
-  amount
+  amountRaw
 }: BuildBundleRequestWithdrawInstructionParams): Promise<TransactionInstruction>;
 //#endregion
 //#region src/utils/pda.d.ts
@@ -3470,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

@@ -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`);
@@ -13103,18 +13139,21 @@ function bundleProgramIdForVault(vault, bundleCluster = "mainnet") {
 	return id;
 }
 /**
-* Optional `initializeBundleDepositor` + `requestDeposit`. Fetches bundle account internally.
+* `initializeBundleDepositor` (when missing) + `requestDeposit`. Fetches bundle + user bundle internally.
 */
-async function buildBundleDepositInstructions({ bundleProgram, bundleCluster = "mainnet", vault, user, amount, needsInit = false }) {
+async function buildBundleDepositInstructions({ bundleProgram, bundleCluster = "mainnet", vault, user, amountRaw }) {
 	assertBundleVault(vault);
 	const bundlePDA = new PublicKey(vault.vaultAddress);
 	const programId = bundleProgramIdForVault(vault, bundleCluster);
 	if (programId !== bundleProgram.programId.toBase58()) throw new Error(`Vault ${vault.vaultId} program id mismatch: vault=${programId}, client=${bundleProgram.programId.toBase58()}`);
-	const bundleInfo = await bundleProgram.account.bundle.fetch(bundlePDA);
-	const depositAmountBN = new BN(Math.floor(amount * 10 ** bundleInfo.assetDecimals));
 	const programPk = bundleProgram.programId;
-	const oraclePDA = deriveOraclePDA(bundlePDA, programPk);
 	const userPDA = deriveUserPDA(user, bundlePDA, programPk);
+	const [bundleAcc, userBundleAcc] = await bundleProgram.provider.connection.getMultipleAccountsInfo([bundlePDA, userPDA]);
+	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(parseAmountRawToBigInt(amountRaw).toString());
+	const oraclePDA = deriveOraclePDA(bundlePDA, programPk);
 	const tempDataPDA = deriveTempDataPDA(bundlePDA, programPk);
 	const pendingAuthPDA = derivePendingAuthPDA(bundlePDA, programPk);
 	const userTokenAcct = getAssociatedTokenAddressSync(bundleInfo.assetAddress, user, true);
@@ -13130,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,
@@ -13150,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);
@@ -13164,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,
@@ -13358,9 +13391,10 @@ var NeutralTrade = class NeutralTrade {
 		});
 	}
 	/**
-	* Build deposit instructions (optional init + requestDeposit). Fetches vault state on-chain.
+	* Build deposit instructions (`initializeBundleDepositor` when needed, then `requestDeposit`).
+	* Fetches bundle and user bundle accounts on-chain.
 	*/
-	async buildDepositInstructions({ vaultId, userAddress, amount, needsInit = false }) {
+	async buildDepositInstructions({ vaultId, userAddress, amountRaw }) {
 		const vault = this.vaults[vaultId];
 		if (!vault) throw new Error(`Vault config not found for vaultId ${vaultId}`);
 		return buildBundleDepositInstructions({
@@ -13368,14 +13402,13 @@ var NeutralTrade = class NeutralTrade {
 			bundleCluster: this.bundleCluster,
 			vault,
 			user: new PublicKey(userAddress),
-			amount,
-			needsInit
+			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({
@@ -13383,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.2.13",
+  "version": "0.3.3",
   "description": "SDK for Neutral Trade vaults",
   "license": "MIT",
   "homepage": "https://github.com/neutral-trade/sdk#readme",
@@ -69,6 +69,10 @@
     "lint": "eslint",
     "release": "bumpp",
     "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",
     "test": "vitest",
     "typecheck": "tsc",
     "docs:build": "typedoc",