@perena/vault-sdk 1.0.55 → 1.0.58

package/README.md

@@ -370,6 +370,33 @@ and pass the data fields into the generated CPI method. For example,
 `addressSeeds`, it corresponds to `execute_deposit`; with seeds, the builder
 selects `execute_deposit_fee_exempt`.
 
+For regular and instant tranche withdrawals, use `getCpiPlan(txArgs)` to resolve
+liquidity and split the requested shares across external positions:
+
+```typescript
+const cpis = await client.tx.executeWithdraw.getCpiPlan({
+  user: programAuthority,
+  vault,
+  assetMint,
+  shareMint,
+  shareAmount: 500_000n,
+  addressSeeds,
+});
+// Invoke each entry in order within the same transaction.
+for (const { accounts, data, remainingAccounts, lookupTables } of cpis) {
+  // Pass accounts, data, and remainingAccounts to your Rust CPI integration.
+  // Include lookupTables in the outer transaction and allow enough compute.
+}
+```
+
+`executeTrancheWithdraw.getCpiPlan(...)` has the same behavior for junior and
+senior redemptions. `getIxArgs(txArgs)` returns the resolved arguments for each
+leg; `getIxs(txArgs)` returns serialized vault instructions without ATA creation
+or compute-budget instructions. `getTx(txArgs)` adds those transaction setup
+instructions and combines lookup tables. The synchronous `getIxData(ixArgs)` and
+`getIxAccounts(ixArgs)` helpers describe a single resolved leg; they do not fetch
+balances or split it.
+
 ### Fee-exempt program integrations
 
 The deposit, withdrawal, tranche deposit, tranche withdrawal, and queued junior
@@ -560,23 +587,26 @@ const plan = await client.tx.executeWithdraw.getTx({
 await client.sendTransaction(payer, plan);
 ```
 
-Prefer the external-liquidity route when transaction size is not a constraint.
-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 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.
-
-The cost is transaction size — the Marginfi withdraw CPI adds its bank, oracle,
-and liquidity-vault accounts on top of the withdrawal's own accounts. Pass
-`lookupTables` to keep the transaction within the packet limit; only fall back
-to the local-only path (`skipExternalLiquidity: true`) when you are size-bound
-or the vault has no funded external position.
+Regular and instant tranche withdrawal builders first count the live vault ATA
+balance, then visit external liquidity slots in index order. Capacity is bounded
+by the vault's deposit and the bank/reserve's available cash, so borrowed
+liquidity is not counted. Kamino capacity also respects withdrawal caps, queued
+redemptions, and cToken rounding. Automatic routing supports supply-only
+Marginfi and Kamino positions.
+
+If local cash plus slot 0 cannot fund the redemption, the builder splits the
+requested shares into sequential withdrawal instructions, continuing with slot
+1 and later slots until funded. It accounts for fees and integer rounding after
+each burn, skips empty positions, and rejects the whole plan if aggregate
+liquidity is insufficient. Splitting can slightly change rounding compared with
+a single burn. The instructions belong in one atomic transaction.
+
+The builder adds protocol lookup tables and one compute-budget instruction.
+Additional `lookupTables` may be needed for large routes. Solana transaction
+size and compute limits still apply. Capacity is a build-time snapshot; simulate
+before sending and rebuild if balances change. `skipExternalLiquidity: true`
+requires enough local cash, while `externalLiquiditySource: 1` pins routing to
+slot 1 instead of scanning all positions.
 
 To supply the external route explicitly instead of relying on auto-detection,
 pass `externalWithdrawIxRefs`, `externalWithdrawAccounts`, and optionally
@@ -673,9 +703,51 @@ const signature = await client.sendTransaction(payer, plan);
 
 ### Versioned transactions (lookup tables)
 
-Some builders (e.g. `executeWithdraw`, `protocolInteraction`, `jupiterSwap`)
-return `lookupTables` on the plan. `sendTransaction` does **not** compile v0
-messages — use `sendVersionedTransaction` from `common` instead:
+All vault transaction builders include the vault-specific LUT from
+`VAULT_LOOKUP_TABLES` when configured, alongside protocol/caller lookup tables.
+Multi-vault operations include both vaults' tables. `sendTransaction` and
+`simulateTransaction` use v0 messages when the plan contains lookup tables;
+they also apply vault mappings to manually assembled vault instructions.
+
+Create or update a vault's table from the repository root:
+
+```bash
+pnpm vault-lut prod --vault-id 0 --dry-run
+pnpm vault-lut prod --vault-id 0
+pnpm build:vault-sdk
+```
+
+The script defaults to `~/.config/solana/hw-manager-prod.json` as LUT authority
+and rent payer; `--keypair PATH` selects another signer. This signer owns the
+LUT, independently of vault roles. It discovers an existing table for this
+authority/vault or uses the saved mapping, creates a table if absent, and adds
+only missing addresses in batches of 20. It gathers vault PDAs, holding/share
+mints and ATAs, Marginfi withdrawal/health accounts, and Kamino
+obligation/reserve/oracle/farm accounts, including an empty SOL/BTC position.
+`--user KEY` adds user ATAs; `--accounts A,B,...` adds explicit addresses.
+
+The mapping is saved in `src/vaultLookupTables.json` as soon as the table is
+created, so an interrupted extension resumes on the next run. Commit this file
+and rebuild/publish the SDK for downstream consumers. Tables are limited to 256
+addresses; setup fails before extension if the table lacks room. Newly added
+entries must be active in a later slot; the CLI waits for that slot.
+
+Applications can supply a mapping immediately without waiting for a new SDK
+release:
+
+```typescript
+const { client } = createVaultClient("prod", {
+  keypair: payer,
+  vaultLookupTables: { [vault]: vaultLutAddress },
+});
+const plan = await client.tx.executeWithdraw.getTx(withdrawArgs);
+await client.sendTransaction(payer, plan);
+```
+
+Withdrawal `getCpiPlan(...)` and `getIxArgs(...)` also return the vault LUT.
+Single raw `getIx(...)` instructions have no LUT field: use
+`getVaultLookupTables(vault)` or `withVaultLookupTables(plan, programId)` when
+composing outside `VaultClient`. For a custom sender:
 
 ```typescript
 import { fromKitInstruction, sendVersionedTransaction } from "common";
@@ -837,3 +909,46 @@ See [`scripts/README.md`](scripts/README.md) for the full command list.
 - Public keys use `@solana/kit` `Address` strings in builder args.
 - Convert from web3.js: `fromWeb3Pk(keypair.publicKey)` (from `common`).
 - Amounts in `TxArgs` are `bigint` base units unless noted otherwise.
+
+## External liquidity allocation (1.0.57)
+
+`ExternalLiquidityIntegrityService` powers the
+`backend-services/vault-external-liquidity` Lambda. For USDC with both protocols
+registered, it targets **35% Marginfi / 65% Kamino SOL/BTC**, excluding the local
+vault buffer. An external rebalance fires outside **30–40% Marginfi / 60–70%
+Kamino** and restores 35/65. Exactly on a boundary remains inside the band.
+`marginfiWeightBps` (default `3500`) and `externalWeightBandBps` (default `500`)
+configure the target and absolute percentage-point tolerance.
+
+The existing buffer remains: local USDC worth 1.5% of total vault TVL, or 0.5%
+of each other supported holding, with a 20%-of-target buffer band. Buffer
+replenishment takes priority. A buffer adjustment also distributes remaining
+external funds toward the target weights. Single-protocol holdings continue to
+use that protocol; both initialized, registered positions are required for the
+USDC split. Other configured stablecoins continue to use Marginfi.
+
+Allocation uses each live position's supplied balance, including accrued value,
+and the actual vault token balance. Withdrawal capacity also checks bank/reserve
+cash, Kamino withdrawal caps and queued redemptions. Utilization can limit a
+rebalance to a partial transfer; subsequent runs retry if weights remain outside
+the band. Each
+mint's withdrawals and deposits share one atomic transaction and use the vault's
+configured LUT. If a destination rejects a deposit, the whole transaction fails
+and is reported for retry. No transfer is left half-completed.
+
+Kamino deposits use `buildKaminoDepositInteraction` and the appended
+`KLEND_DEPOSIT_AND_COLLATERALIZE_V2` CPI. The vault validates the registered
+obligation, vault-owned source ATA, reserve, market, token programs, farms and
+absence of borrowing. Only the hardware manager can deposit. **Upgrade the vault
+program with this CPI support before deploying the Lambda with SDK 1.0.57.**
+Publish the SDK and then rebuild/deploy the backend consumer; changing the local
+package version alone does not update a running Lambda.
+
+```sh
+# Simulate all eligible vaults; no transactions are submitted.
+pnpm run-external-liquidity-service prod --dry-run
+
+# Explicitly supply the default allocation policy.
+pnpm run-external-liquidity-service prod --dry-run \
+  --marginfi-weight-bps 3500 --external-weight-band-bps 500
+```

package/dist/browser/nest.d.mts

@@ -155,6 +155,8 @@ interface PreparedSquadsTransaction {
     transactionIndex: bigint;
     proposalPda: PublicKey;
     vaultTransactionPda: PublicKey;
+    /** Failed inner-instruction simulation explicitly allowed by the caller. */
+    executionSimulationError?: SquadsProposalExecutionSimulationError;
 }
 type PreparedVaultTransaction = PreparedDirectTransaction | PreparedSquadsTransaction;
 type SquadsSimulationTransactionError = NonNullable<SimulatedTransactionResponse["err"]>;
@@ -209,6 +211,8 @@ declare function prepareVaultTransaction(args: {
     squadsRoutes?: readonly SquadsWalletRouteConfig[];
     /** Skip execution simulation when proposing a transaction that depends on future funding. */
     skipSimulation?: boolean;
+    /** Still prepare the proposal if its inner instructions fail simulation; return the failure for display. */
+    allowExecutionSimulationFailure?: boolean;
     addressLookupTableAccounts?: AddressLookupTableAccount[];
     /** Temporary signer keys used only in account metas, replaced by Squads PDAs. */
     ephemeralSignerKeys?: readonly PublicKey[];

package/dist/browser/nest.mjs

@@ -746,14 +746,22 @@ async function prepareVaultTransaction(args) {
     );
   }
   const { blockhash } = await connection.getLatestBlockhash("confirmed");
+  let executionSimulationError;
   if (!args.skipSimulation) {
-    await simulateSquadsProposalExecution({
-      connection,
-      feePayer: proposer,
-      instructions: instructions2,
-      recentBlockhash: blockhash,
-      addressLookupTableAccounts: args.addressLookupTableAccounts
-    });
+    try {
+      await simulateSquadsProposalExecution({
+        connection,
+        feePayer: proposer,
+        instructions: instructions2,
+        recentBlockhash: blockhash,
+        addressLookupTableAccounts: args.addressLookupTableAccounts
+      });
+    } catch (error) {
+      if (!args.allowExecutionSimulationFailure || !(error instanceof SquadsProposalExecutionSimulationError)) {
+        throw error;
+      }
+      executionSimulationError = error;
+    }
   }
   const transactionMessage = new TransactionMessage4({
     payerKey: route.vaultPda,
@@ -794,7 +802,8 @@ async function prepareVaultTransaction(args) {
     vaultIndex: route.vaultIndex,
     transactionIndex,
     proposalPda,
-    vaultTransactionPda
+    vaultTransactionPda,
+    ...executionSimulationError ? { executionSimulationError } : {}
   };
 }