@perena/vault-sdk 1.0.28 → 1.0.30

package/README.md

@@ -406,8 +406,25 @@ const plan = await client.tx.executeWithdraw.getTx({
 await client.sendTransaction(payer, plan);
 ```
 
-For withdrawals routed through external liquidity (CPI), pass
-`externalWithdrawIxRefs`, `externalWithdrawAccounts`, and optionally
+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 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
+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.
+
+To supply the external route explicitly instead of relying on auto-detection,
+pass `externalWithdrawIxRefs`, `externalWithdrawAccounts`, and optionally
 `lookupTables` — see `ExecuteWithdrawTxArgs` in `args.ts`.
 
 ### Example: vault setup (multi-step)
@@ -605,7 +622,7 @@ All builders are on `client.tx`:
 | `requestJuniorTrancheWithdraw` | `request_junior_tranche_withdraw` | Owner            |
 | `cancelJuniorTrancheWithdraw`  | `cancel_junior_tranche_withdraw`  | Owner            |
 | `fulfillJuniorTrancheWithdraw` | `fulfill_junior_tranche_withdraw` | Fulfiller        |
-| `executeWithdraw`              | `execute_withdraw`                | User             |
+| `executeWithdraw`              | `execute_withdraw` / `execute_withdraw_from_external` | User |
 | `managerWithdrawAsset`         | `manager_withdraw_asset`          | HW manager       |
 | `managerRedepositAsset`        | `manager_redeposit_asset`         | HW manager       |
 | `protocolInteraction`          | `protocol_interaction`            | HW manager       |