@perena/vault-sdk 1.0.48 → 1.0.50

package/README.md

@@ -565,9 +565,10 @@ The builder auto-detects external liquidity slot 0 and, when it finds an active
 Marginfi position for the asset, emits `execute_withdraw_from_external` instead
 of `execute_withdraw`. That route can pull from the vault's external position in
 the same transaction, so it draws on far more liquidity than the plain
-`execute_withdraw`: the external-liquidity integrity service keeps only ~0.5% of
-each holding in the vault's own token account (see
-`DEFAULT_TARGET_LOCAL_BPS`) and deploys the rest into Marginfi, so a plain
+`execute_withdraw`: the external-liquidity integrity service targets local USDC
+worth 1.5% of total vault TVL (`DEFAULT_TARGET_LOCAL_USDC_TVL_BPS`) and ~0.5% of
+each other holding (`DEFAULT_TARGET_LOCAL_BPS`), deploying the rest into Marginfi.
+It rebalances once local balances drift 20% from those targets, so a plain
 withdrawal is capped at that small local buffer and will fail for anything
 larger.
 

package/dist/browser/nest.d.mts

@@ -90,6 +90,29 @@ declare function decodeNestWithdrawalRequest(args: {
     txBase64: string;
 }): Promise<VaultTransactionPlan>;
 
+interface NestDepositPlan extends VaultTransactionPlan {
+    /** Pass through to prepareVaultTransaction; the keeper's signatures are not reusable. */
+    ephemeralSignerKeys: PublicKey[];
+}
+/** Build a manager-funded deposit, with one event account for Squads to sign. */
+declare function buildNestDepositRequest(args: {
+    connection: Connection;
+    owner: PublicKey;
+    rawAmountUsdc: bigint;
+    apiOptions?: NestApiOptions;
+}): Promise<NestDepositPlan>;
+/**
+ * Validate the USDC burn and Nest/Solana recipient. Replace the keeper rent payer
+ * with the manager, and expose the CCTP event signer for Squads PDA substitution.
+ * Nest remains trusted for the complete cross-chain payload and keeper delivery.
+ */
+declare function decodeNestDepositRequest(args: {
+    connection: Connection;
+    owner: PublicKey;
+    rawAmountUsdc: bigint;
+    txBase64: string;
+}): Promise<NestDepositPlan>;
+
 /**
  * {@link PriceSource} adapter over the `nest` package's price API, bound to the
  * Perena vault's Nest slug and share mint.
@@ -187,6 +210,8 @@ declare function prepareVaultTransaction(args: {
     /** Skip execution simulation when proposing a transaction that depends on future funding. */
     skipSimulation?: boolean;
     addressLookupTableAccounts?: AddressLookupTableAccount[];
+    /** Temporary signer keys used only in account metas, replaced by Squads PDAs. */
+    ephemeralSignerKeys?: readonly PublicKey[];
 }): Promise<PreparedVaultTransaction>;
 
 interface SquadsProposalUpload {
@@ -205,4 +230,4 @@ declare function prepareSquadsProposalUpload(args: {
     prepared: PreparedSquadsTransaction;
 }): Promise<SquadsProposalUpload>;
 
-export { NEST_RWA_SHARE_MINT, NEST_VAULT_SLUG, NestApiError, type NestApiOptions, type NestRedemptionQuote, type NestRedemptionStatus, type PreparedDirectTransaction, type PreparedSquadsTransaction, type PreparedVaultTransaction, type ResolvedSquadsWalletRoute, SquadsProposalExecutionSimulationError, type SquadsProposalUpload, type SquadsWalletRouteConfig, buildNestWithdrawalRequest, decodeNestWithdrawalRequest, fetchNestRedemptionQuote, fetchNestRedemptionStatus, findSquadsWalletRoute, prepareSquadsProposalUpload, prepareVaultTransaction, resolveSquadsWalletRoute, simulateSquadsProposalExecution, validateSquadsWalletRoutes, vaultAuthorityForWallet };
+export { NEST_RWA_SHARE_MINT, NEST_VAULT_SLUG, NestApiError, type NestApiOptions, type NestDepositPlan, type NestRedemptionQuote, type NestRedemptionStatus, type PreparedDirectTransaction, type PreparedSquadsTransaction, type PreparedVaultTransaction, type ResolvedSquadsWalletRoute, SquadsProposalExecutionSimulationError, type SquadsProposalUpload, type SquadsWalletRouteConfig, buildNestDepositRequest, buildNestWithdrawalRequest, decodeNestDepositRequest, decodeNestWithdrawalRequest, fetchNestRedemptionQuote, fetchNestRedemptionStatus, findSquadsWalletRoute, prepareSquadsProposalUpload, prepareVaultTransaction, resolveSquadsWalletRoute, simulateSquadsProposalExecution, validateSquadsWalletRoutes, vaultAuthorityForWallet };

package/dist/browser/nest.mjs

@@ -454,14 +454,148 @@ async function decodeNestWithdrawalRequest(args) {
   };
 }
 
-// src/utils/squads.ts
-import * as squads from "@sqds/multisig";
+// src/services/nestDepositService.ts
+import { address as address5 } from "@solana/kit";
 import {
+  ASSOCIATED_TOKEN_PROGRAM_ID as ASSOCIATED_TOKEN_PROGRAM_ID3,
+  createAssociatedTokenAccountIdempotentInstruction,
+  getAssociatedTokenAddressSync as getAssociatedTokenAddressSync3,
+  TOKEN_PROGRAM_ID as TOKEN_PROGRAM_ID2
+} from "@solana/spl-token";
+import {
+  ComputeBudgetProgram as ComputeBudgetProgram2,
   PublicKey as PublicKey4,
-  Transaction,
+  SystemProgram,
   TransactionMessage as TransactionMessage3,
   VersionedTransaction as VersionedTransaction3
 } from "@solana/web3.js";
+var Usdc = new PublicKey4("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+var Messenger = new PublicKey4("CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe");
+var Transmitter = new PublicKey4(
+  "CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC"
+);
+var Router = Buffer.from(
+  "0000000000000000000000007de01896d36bea9cf072ac64e41685418941d8be",
+  "hex"
+);
+var Composer = Buffer.from("908dcb5531691c2124c54e30bb645cf11647090d", "hex");
+var BurnWithHook = Buffer.from([111, 245, 62, 131, 204, 108, 223, 155]);
+var PerenaAssetId = Buffer.from(
+  "355750bed2d05a1eb92ab578335cc3ea6d572dd5f57a086088c68667f11e50d2",
+  "hex"
+);
+var MintAndSend = Buffer.from("fe030ec4", "hex");
+async function buildNestDepositRequest(args) {
+  if (args.rawAmountUsdc <= 0n || args.rawAmountUsdc > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(
+      "Nest deposit must be a positive, safely representable USDC base-unit amount"
+    );
+  }
+  const options = args.apiOptions ?? {};
+  const response = await (options.fetchFn ?? fetch)(
+    `${(options.baseUrl ?? NEST_API_BASE_URL).replace(
+      /\/$/,
+      ""
+    )}/solana/nest/mint/build-tx`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      signal: options.signal,
+      body: JSON.stringify({
+        rawAmountUsdc: Number(args.rawAmountUsdc),
+        receiver: args.owner.toBase58(),
+        nestVaultSlug: NEST_VAULT_SLUG,
+        finality: "standard"
+      })
+    }
+  );
+  const payload = await response.json().catch(() => null);
+  if (!response.ok)
+    throw new Error(
+      `Nest deposit API (${response.status}): ${typeof payload?.error === "string" ? payload.error : response.statusText}`
+    );
+  if (typeof payload?.data?.txBase64 !== "string")
+    throw new Error("Nest API returned no deposit transaction");
+  return decodeNestDepositRequest({ ...args, txBase64: payload.data.txBase64 });
+}
+async function decodeNestDepositRequest(args) {
+  if (args.rawAmountUsdc <= 0n || args.rawAmountUsdc > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(
+      "Nest deposit must be a positive, safely representable USDC base-unit amount"
+    );
+  }
+  const message = VersionedTransaction3.deserialize(
+    Buffer.from(args.txBase64, "base64")
+  ).message;
+  if (!message.staticAccountKeys[0].equals(args.owner))
+    throw new Error("Nest deposit payer must be the manager");
+  const tables = await Promise.all(
+    message.addressTableLookups.map(async (lookup) => {
+      const { value } = await args.connection.getAddressLookupTable(
+        lookup.accountKey
+      );
+      if (!value)
+        throw new Error(`Nest lookup table not found: ${lookup.accountKey}`);
+      return value;
+    })
+  );
+  const instructions2 = TransactionMessage3.decompile(message, {
+    addressLookupTableAccounts: tables
+  }).instructions;
+  const shareMint = new PublicKey4(NEST_RWA_SHARE_MINT2);
+  const shareAta = getAssociatedTokenAddressSync3(shareMint, args.owner, true);
+  const usdcAta = getAssociatedTokenAddressSync3(Usdc, args.owner, true);
+  let burn;
+  for (const ix of instructions2) {
+    if (ix.programId.equals(ComputeBudgetProgram2.programId)) continue;
+    if (ix.programId.equals(ASSOCIATED_TOKEN_PROGRAM_ID3)) {
+      if (ix.data.length !== 1 || ix.data[0] !== 1 || !ix.keys[0]?.pubkey.equals(args.owner) || !ix.keys[1]?.pubkey.equals(shareAta) || !ix.keys[2]?.pubkey.equals(args.owner) || !ix.keys[3]?.pubkey.equals(shareMint) || !ix.keys[4]?.pubkey.equals(SystemProgram.programId) || !ix.keys[5]?.pubkey.equals(TOKEN_PROGRAM_ID2))
+        throw new Error("Unexpected Nest deposit token account creation");
+      continue;
+    }
+    const d = ix.data;
+    const matches = (index, key) => ix.keys[index]?.pubkey.equals(key);
+    if (burn || !ix.programId.equals(Messenger) || ix.keys.length !== 18 || d.length < 316 || !d.subarray(0, 8).equals(BurnWithHook) || d.readBigUInt64LE(8) !== args.rawAmountUsdc || d.readUInt32LE(16) !== 22 || !d.subarray(20, 52).equals(Router) || !d.subarray(52, 84).equals(Router) || d.readBigUInt64LE(84) !== 0n || d.readUInt32LE(92) !== 2e3 || d.readUInt32LE(96) !== d.length - 100 || !d.subarray(100, 120).equals(Composer) || !d.subarray(120, 124).equals(MintAndSend) || !d.subarray(124, 156).equals(PerenaAssetId) || BigInt(`0x${d.subarray(156, 188).toString("hex")}`) !== args.rawAmountUsdc || BigInt(`0x${d.subarray(188, 220).toString("hex")}`) !== 128n || !d.subarray(220, 252).equals(Buffer.concat([Buffer.alloc(12), Composer])) || BigInt(`0x${d.subarray(252, 284).toString("hex")}`) !== 30168n || !d.subarray(284, 316).equals(args.owner.toBuffer()) || !matches(0, args.owner) || !matches(3, usdcAta) || !matches(10, Usdc) || !matches(12, Transmitter) || !matches(13, Messenger) || !matches(14, TOKEN_PROGRAM_ID2) || !matches(15, SystemProgram.programId) || !matches(17, Messenger) || ![0, 1, 11].every((index) => ix.keys[index].isSigner) || ix.keys.some(
+      (meta, index) => meta.isSigner && ![0, 1, 11].includes(index)
+    )) {
+      throw new Error(
+        "Unexpected Nest deposit instruction, amount, or recipient"
+      );
+    }
+    burn = ix;
+  }
+  if (!burn) throw new Error("Nest deposit must contain one CCTP burn");
+  const eventKey = burn.keys[11].pubkey;
+  if (eventKey.equals(args.owner) || burn.keys.some(
+    (meta, index) => index !== 11 && meta.pubkey.equals(eventKey)
+  )) {
+    throw new Error("Nest deposit event signer must be a separate account");
+  }
+  burn.keys[1] = { pubkey: args.owner, isSigner: true, isWritable: true };
+  return {
+    instructions: [
+      createAssociatedTokenAccountIdempotentInstruction(
+        args.owner,
+        shareAta,
+        args.owner,
+        shareMint
+      ),
+      burn
+    ].map(toKitInstruction),
+    lookupTables: tables.map((table) => address5(table.key.toBase58())),
+    ephemeralSignerKeys: [eventKey]
+  };
+}
+
+// src/utils/squads.ts
+import * as squads from "@sqds/multisig";
+import {
+  PublicKey as PublicKey5,
+  Transaction,
+  TransactionInstruction as TransactionInstruction2,
+  TransactionMessage as TransactionMessage4,
+  VersionedTransaction as VersionedTransaction4
+} from "@solana/web3.js";
 var SQUADS_SIMULATION_COMMITMENT = "processed";
 var SquadsProposalExecutionSimulationError = class extends Error {
   constructor(transactionError, logs, unitsConsumed) {
@@ -485,8 +619,8 @@ function validateVaultIndex(vaultIndex) {
 }
 function resolveSquadsWalletRoute(route) {
   validateVaultIndex(route.vaultIndex);
-  const wallet = new PublicKey4(route.wallet);
-  const multisigPda = new PublicKey4(route.multisigPda);
+  const wallet = new PublicKey5(route.wallet);
+  const multisigPda = new PublicKey5(route.multisigPda);
   const [vaultPda] = squads.getVaultPda({
     multisigPda,
     index: route.vaultIndex
@@ -494,7 +628,7 @@ function resolveSquadsWalletRoute(route) {
   return { ...route, wallet, multisigPda, vaultPda };
 }
 function findSquadsWalletRoute(wallet, routes) {
-  const walletKey = typeof wallet === "string" ? new PublicKey4(wallet) : wallet;
+  const walletKey = typeof wallet === "string" ? new PublicKey5(wallet) : wallet;
   const route = routes.find(
     (candidate) => candidate.wallet === walletKey.toBase58()
   );
@@ -512,18 +646,18 @@ function validateSquadsWalletRoutes(routes) {
   }
 }
 function vaultAuthorityForWallet(wallet, routes) {
-  const walletKey = typeof wallet === "string" ? new PublicKey4(wallet) : wallet;
+  const walletKey = typeof wallet === "string" ? new PublicKey5(wallet) : wallet;
   return findSquadsWalletRoute(walletKey, routes)?.vaultPda ?? walletKey;
 }
 async function simulateSquadsProposalExecution(args) {
   const { connection, feePayer, instructions: instructions2 } = args;
   const recentBlockhash = args.recentBlockhash ?? (await connection.getLatestBlockhash(SQUADS_SIMULATION_COMMITMENT)).blockhash;
-  const message = new TransactionMessage3({
+  const message = new TransactionMessage4({
     payerKey: feePayer,
     recentBlockhash,
     instructions: [...instructions2]
   }).compileToV0Message(args.addressLookupTableAccounts);
-  const transaction = new VersionedTransaction3(message);
+  const transaction = new VersionedTransaction4(message);
   const { value } = await connection.simulateTransaction(transaction, {
     sigVerify: false,
     commitment: SQUADS_SIMULATION_COMMITMENT,
@@ -539,9 +673,13 @@ async function simulateSquadsProposalExecution(args) {
   return value;
 }
 async function prepareVaultTransaction(args) {
-  const { connection, proposer, instructions: instructions2 } = args;
+  const { connection, proposer } = args;
+  let instructions2 = [...args.instructions];
+  const ephemeralKeys = args.ephemeralSignerKeys ?? [];
   const route = findSquadsWalletRoute(proposer, args.squadsRoutes ?? []);
   if (!route) {
+    if (ephemeralKeys.length)
+      throw new Error("Ephemeral signers require a Squads route");
     return {
       kind: "direct",
       transaction: new Transaction().add(...instructions2),
@@ -569,6 +707,44 @@ async function prepareVaultTransaction(args) {
     );
   }
   const transactionIndex = BigInt(multisig.transactionIndex.toString()) + 1n;
+  if (ephemeralKeys.length > 255 || new Set(ephemeralKeys.map(String)).size !== ephemeralKeys.length) {
+    throw new Error("Invalid Squads ephemeral signer keys");
+  }
+  const [transactionPda] = squads.getTransactionPda({
+    multisigPda: route.multisigPda,
+    index: transactionIndex
+  });
+  const replacements = /* @__PURE__ */ new Map();
+  ephemeralKeys.forEach((key, index) => {
+    if (key.equals(proposer) || key.equals(route.vaultPda) || !instructions2.some(
+      (ix) => ix.keys.some((meta) => meta.isSigner && meta.pubkey.equals(key))
+    ) || instructions2.some(
+      (ix) => ix.programId.equals(key) || ix.data.includes(key.toBuffer())
+    )) {
+      throw new Error(
+        "Ephemeral signer must be a separate account-meta signer, never embedded in instruction data"
+      );
+    }
+    replacements.set(
+      key.toBase58(),
+      squads.getEphemeralSignerPda({
+        transactionPda,
+        ephemeralSignerIndex: index
+      })[0]
+    );
+  });
+  if (replacements.size) {
+    instructions2 = instructions2.map(
+      (ix) => new TransactionInstruction2({
+        programId: ix.programId,
+        data: ix.data,
+        keys: ix.keys.map((meta) => ({
+          ...meta,
+          pubkey: replacements.get(meta.pubkey.toBase58()) ?? meta.pubkey
+        }))
+      })
+    );
+  }
   const { blockhash } = await connection.getLatestBlockhash("confirmed");
   if (!args.skipSimulation) {
     await simulateSquadsProposalExecution({
@@ -579,7 +755,7 @@ async function prepareVaultTransaction(args) {
       addressLookupTableAccounts: args.addressLookupTableAccounts
     });
   }
-  const transactionMessage = new TransactionMessage3({
+  const transactionMessage = new TransactionMessage4({
     payerKey: route.vaultPda,
     recentBlockhash: blockhash,
     instructions: [...instructions2]
@@ -589,7 +765,7 @@ async function prepareVaultTransaction(args) {
     transactionIndex,
     creator: proposer,
     vaultIndex: route.vaultIndex,
-    ephemeralSigners: 0,
+    ephemeralSigners: ephemeralKeys.length,
     transactionMessage,
     addressLookupTableAccounts: args.addressLookupTableAccounts,
     memo: route.memo
@@ -625,8 +801,8 @@ async function prepareVaultTransaction(args) {
 // src/utils/squadsBuffer.ts
 import * as squads2 from "@sqds/multisig";
 import {
-  PublicKey as PublicKey5,
-  SystemProgram,
+  PublicKey as PublicKey6,
+  SystemProgram as SystemProgram2,
   Transaction as Transaction2
 } from "@solana/web3.js";
 var PacketSize = 1232;
@@ -637,7 +813,7 @@ async function prepareSquadsProposalUpload(args) {
   const transaction = prepared.transaction;
   const sizeProbe = new Transaction2({
     feePayer: proposer,
-    recentBlockhash: PublicKey5.default.toBase58()
+    recentBlockhash: PublicKey6.default.toBase58()
   }).add(...transaction.instructions);
   let fits = false;
   try {
@@ -657,7 +833,7 @@ async function prepareSquadsProposalUpload(args) {
   let bufferPda;
   let bufferIndex = 0;
   for (; bufferIndex <= 255; bufferIndex++) {
-    const [candidate] = PublicKey5.findProgramAddressSync(
+    const [candidate] = PublicKey6.findProgramAddressSync(
       [
         Buffer.from("multisig"),
         prepared.multisigPda.toBuffer(),
@@ -718,7 +894,7 @@ async function prepareSquadsProposalUpload(args) {
       vaultTransactionCreateItemTransaction: prepared.vaultTransactionPda,
       vaultTransactionCreateItemCreator: proposer,
       vaultTransactionCreateItemRentPayer: proposer,
-      vaultTransactionCreateItemSystemProgram: SystemProgram.programId,
+      vaultTransactionCreateItemSystemProgram: SystemProgram2.programId,
       transactionBuffer: bufferPda,
       creator: proposer
     },
@@ -743,7 +919,9 @@ export {
   NEST_VAULT_SLUG,
   NestApiError,
   SquadsProposalExecutionSimulationError,
+  buildNestDepositRequest,
   buildNestWithdrawalRequest,
+  decodeNestDepositRequest,
   decodeNestWithdrawalRequest,
   fetchNestRedemptionQuote,
   fetchNestRedemptionStatus,