@varla/sdk 3.2.0 → 4.1.0

package/src/actions/core.ts

@@ -5,6 +5,8 @@ import type { Address, PublicClient } from "viem";
 import { abis } from "../generated.js";
 import type { SimulatedTx } from "./oracle.js";
 
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as const;
+
 export async function prepareCoreDeposit(params: {
   publicClient: Pick<PublicClient, "simulateContract">;
   coreAddress: Address;
@@ -21,18 +23,50 @@ export async function prepareCoreDeposit(params: {
   } as any)) as any;
 }
 
+/**
+ * Withdraw deposited ERC1155 collateral from VarlaCore back to a wallet.
+ *
+ * Two call paths:
+ * - **No `recipient`** (default): calls `withdraw(ids, amounts)` — tokens sent to `msg.sender`.
+ * - **With `recipient`**: calls `withdraw(ids, amounts, destination)` — tokens sent to the
+ *   specified address instead of the caller. Useful for Safe / proxy wallets or any flow
+ *   where the signer and the token recipient differ.
+ *
+ * @example
+ * ```ts
+ * // Withdraw to self (default)
+ * const tx = await prepareCoreWithdraw({ publicClient, coreAddress, account, positionIds, amounts });
+ *
+ * // Withdraw to a different address
+ * const tx = await prepareCoreWithdraw({
+ *   publicClient, coreAddress, account,
+ *   positionIds, amounts,
+ *   recipient: "0xAbc...",
+ * });
+ * ```
+ */
 export async function prepareCoreWithdraw(params: {
   publicClient: Pick<PublicClient, "simulateContract">;
   coreAddress: Address;
   account: Address;
   positionIds: readonly bigint[];
   amounts: readonly bigint[];
+  /**
+   * Optional destination address for the withdrawn ERC1155 tokens.
+   *
+   * When provided, calls `withdraw(positionIds, amounts, destination)`.
+   * When omitted, calls `withdraw(positionIds, amounts)` (tokens go to `msg.sender`).
+   */
+  recipient?: Address;
 }): Promise<SimulatedTx> {
   return (await params.publicClient.simulateContract({
     address: params.coreAddress,
     abi: abis.VARLACORE_ABI,
     functionName: "withdraw",
-    args: [params.positionIds, params.amounts],
+    args:
+      params.recipient !== undefined
+        ? [params.positionIds, params.amounts, params.recipient]
+        : [params.positionIds, params.amounts],
     account: params.account,
   } as any)) as any;
 }
@@ -42,12 +76,17 @@ export async function prepareCoreBorrow(params: {
   coreAddress: Address;
   account: Address;
   amount: bigint;
+  outputAsset?: Address;
+  recipient?: Address;
 }): Promise<SimulatedTx> {
+  const useRecipientPath = params.outputAsset !== undefined || params.recipient !== undefined;
   return (await params.publicClient.simulateContract({
     address: params.coreAddress,
     abi: abis.VARLACORE_ABI,
     functionName: "borrow",
-    args: [params.amount],
+    args: useRecipientPath
+      ? [params.amount, params.outputAsset ?? ZERO_ADDRESS, params.recipient ?? params.account]
+      : [params.amount],
     account: params.account,
   } as any)) as any;
 }
@@ -58,12 +97,13 @@ export async function prepareCoreBorrowWithAsset(params: {
   account: Address;
   amount: bigint;
   outputAsset: Address;
+  recipient?: Address;
 }): Promise<SimulatedTx> {
   return (await params.publicClient.simulateContract({
     address: params.coreAddress,
     abi: abis.VARLACORE_ABI,
     functionName: "borrow",
-    args: [params.amount, params.outputAsset],
+    args: [params.amount, params.outputAsset, params.recipient ?? params.account],
     account: params.account,
   } as any)) as any;
 }
@@ -73,12 +113,17 @@ export async function prepareCoreRepay(params: {
   coreAddress: Address;
   account: Address;
   amount: bigint;
+  inputAsset?: Address;
+  onBehalfOf?: Address;
 }): Promise<SimulatedTx> {
+  const useOnBehalfPath = params.inputAsset !== undefined || params.onBehalfOf !== undefined;
   return (await params.publicClient.simulateContract({
     address: params.coreAddress,
     abi: abis.VARLACORE_ABI,
     functionName: "repay",
-    args: [params.amount],
+    args: useOnBehalfPath
+      ? [params.amount, params.inputAsset ?? ZERO_ADDRESS, params.onBehalfOf ?? params.account]
+      : [params.amount],
     account: params.account,
   } as any)) as any;
 }
@@ -89,12 +134,13 @@ export async function prepareCoreRepayWithAsset(params: {
   account: Address;
   amount: bigint;
   inputAsset: Address;
+  onBehalfOf?: Address;
 }): Promise<SimulatedTx> {
   return (await params.publicClient.simulateContract({
     address: params.coreAddress,
     abi: abis.VARLACORE_ABI,
     functionName: "repay",
-    args: [params.amount, params.inputAsset],
+    args: [params.amount, params.inputAsset, params.onBehalfOf ?? params.account],
     account: params.account,
   } as any)) as any;
 }

package/src/actions/erc1155.ts

@@ -20,3 +20,99 @@ export async function prepareErc1155SetApprovalForAll(params: {
     account: params.account,
   } as any)) as any;
 }
+
+/**
+ * Deposit a single ERC1155 position into VarlaCore by directly calling
+ * `ctf.safeTransferFrom(user, core, id, amount, "")`.
+ *
+ * This triggers VarlaCore's `onERC1155Received` hook which credits the
+ * sender (`from`) with the deposited amount — no prior `setApprovalForAll`
+ * to Core is required since the caller is initiating the transfer themselves.
+ *
+ * Use this as a drop-in alternative to `prepareCoreDeposit` when the user
+ * prefers the ERC1155-push pattern (e.g. in single-token flows or when
+ * building atomic Safe multisend batches where approval is undesirable).
+ *
+ * @example
+ * ```ts
+ * import { prepareCoreDepositViaSafeTransfer } from "@varla/sdk/actions";
+ *
+ * const tx = await prepareCoreDepositViaSafeTransfer({
+ *   publicClient,
+ *   ctfAddress,
+ *   coreAddress,
+ *   account: userAddress,
+ *   positionId: BigInt(posId),
+ *   amount: 100_000_000n, // 100 USDC (6 decimals)
+ * });
+ * await walletClient.writeContract(tx.request);
+ * ```
+ */
+export async function prepareCoreDepositViaSafeTransfer(params: {
+  publicClient: Pick<PublicClient, "simulateContract">;
+  /** Address of the ERC1155 positions token (Polymarket CTF). */
+  ctfAddress: Address;
+  /** Address of VarlaCore (the transfer recipient). */
+  coreAddress: Address;
+  account: Address;
+  positionId: bigint;
+  amount: bigint;
+}): Promise<SimulatedTx> {
+  return (await params.publicClient.simulateContract({
+    address: params.ctfAddress,
+    abi: erc1155Abi,
+    functionName: "safeTransferFrom",
+    args: [params.account, params.coreAddress, params.positionId, params.amount, "0x"],
+    account: params.account,
+  } as any)) as any;
+}
+
+/**
+ * Deposit multiple ERC1155 positions into VarlaCore in a single call by using
+ * `ctf.safeBatchTransferFrom(user, core, ids, amounts, "")`.
+ *
+ * This triggers VarlaCore's `onERC1155BatchReceived` hook which credits the
+ * sender (`from`) with each transferred amount. No prior `setApprovalForAll`
+ * to Core is needed.
+ *
+ * Prefer this over multiple `prepareCoreDepositViaSafeTransfer` calls when
+ * depositing several positions atomically (single tx, lower gas).
+ *
+ * @example
+ * ```ts
+ * import { prepareCoreDepositViaSafeBatchTransfer } from "@varla/sdk/actions";
+ *
+ * const tx = await prepareCoreDepositViaSafeBatchTransfer({
+ *   publicClient,
+ *   ctfAddress,
+ *   coreAddress,
+ *   account: userAddress,
+ *   positionIds: [BigInt(yesId), BigInt(noId)],
+ *   amounts: [50_000_000n, 50_000_000n],
+ * });
+ * await walletClient.writeContract(tx.request);
+ * ```
+ */
+export async function prepareCoreDepositViaSafeBatchTransfer(params: {
+  publicClient: Pick<PublicClient, "simulateContract">;
+  /** Address of the ERC1155 positions token (Polymarket CTF). */
+  ctfAddress: Address;
+  /** Address of VarlaCore (the transfer recipient). */
+  coreAddress: Address;
+  account: Address;
+  positionIds: readonly bigint[];
+  amounts: readonly bigint[];
+}): Promise<SimulatedTx> {
+  if (params.positionIds.length !== params.amounts.length) {
+    throw new Error(
+      `prepareCoreDepositViaSafeBatchTransfer: positionIds.length (${params.positionIds.length}) must equal amounts.length (${params.amounts.length})`,
+    );
+  }
+  return (await params.publicClient.simulateContract({
+    address: params.ctfAddress,
+    abi: erc1155Abi,
+    functionName: "safeBatchTransferFrom",
+    args: [params.account, params.coreAddress, params.positionIds, params.amounts, "0x"],
+    account: params.account,
+  } as any)) as any;
+}

package/src/addresses/polygon.json

@@ -3,16 +3,16 @@
   "generatedAt": "",
   "deploymentsDir": "polygon",
   "contracts": {
-    "VarlaAccessManager": "0x9d880933Def30A33f706dC2c1882a66598d2e891",
-    "VarlaOracle": "0x4E3d7d4264579473FDC2a40db15b42e8CA27CE4f",
-    "VarlaCore": "0x7bD415806e99e852B92fb55cD830F55e7F026C40",
-    "VarlaPool": "0x0B51D2497EdceCF5eedDB16ed6E12270410E18fE",
-    "OracleUpdaterRouter": "0x0e298855e9D06c0a05Efe13163e8D6bfD98ea8BA",
-    "VarlaInterestRateStrategy": "0xA0228e70AdaEb6E64037ca74d033f26d61e16F91",
-    "VarlaProxyAdmin": "0xAF6a35C861f377060a40B14aD18fd167b6AF6d3C",
-    "VarlaLiquidator": "0xacd5FDebE867536703bbC18e6b49fA6053179cf7",
-    "VarlaMergeLiquidator": "0xFfAF752671360cb6baFc7290155e8a81109d4589",
-    "VarlaConvertLiquidator": "0xE8507e011dAC6Bf07e742AF39e16deC647a70746",
-    "PolymarketCtfAdapter": "0xEbB92A5374D277A3e1CA915741ce3077364d95c0"
+    "VarlaAccessManager": "0xEC4CBe73cFA6846B6772341e199289F7A4f20e7e",
+    "VarlaOracle": "0xA63c6ebD3a0C6990D16Ea94D957c2Ad8D3c7Dd10",
+    "VarlaCore": "0xc1c7720Eb3563630aA77be561cD0B58F1Fa280F6",
+    "VarlaPool": "0xc939CC89340E22bDf33df82A55118b19d4A11Bc2",
+    "OracleUpdaterRouter": "0x59389217DEB847b3747767b2D7f56ffec43E9c72",
+    "VarlaInterestRateStrategy": "0x62cf2ab7346b5bA86faaa302d1E39908525166dB",
+    "VarlaProxyAdmin": "0xf06B99237d2A53c6026ff5E3723417E6dEDcA651",
+    "VarlaLiquidator": "0xd7760D42661b8A559A61351873E0e006985F0d75",
+    "VarlaMergeLiquidator": "0x5fA44Ba97470ADaDc97cb7F3ce64baceeE37f97a",
+    "VarlaConvertLiquidator": "0xBA802DF5e8258636738A28d27573203B32D2120A",
+    "PolymarketCtfAdapter": "0x66Ed3cf23719eb9111966AF6D6842F6548165313"
   }
 }

package/src/addresses/polygon.ts

@@ -2,16 +2,16 @@
 import type { AddressBook } from "../types";
 
 export const polygon: AddressBook = {
-  accessManager: "0x9d880933Def30A33f706dC2c1882a66598d2e891",
-  oracle: "0x4E3d7d4264579473FDC2a40db15b42e8CA27CE4f",
-  core: "0x7bD415806e99e852B92fb55cD830F55e7F026C40",
-  pool: "0x0B51D2497EdceCF5eedDB16ed6E12270410E18fE",
-  oracleUpdaterRouter: "0x0e298855e9D06c0a05Efe13163e8D6bfD98ea8BA",
-  interestRateStrategy: "0xA0228e70AdaEb6E64037ca74d033f26d61e16F91",
-  proxyAdmin: "0xAF6a35C861f377060a40B14aD18fd167b6AF6d3C",
-  liquidator: "0xacd5FDebE867536703bbC18e6b49fA6053179cf7",
-  mergeLiquidator: "0xFfAF752671360cb6baFc7290155e8a81109d4589",
-  convertLiquidator: "0xE8507e011dAC6Bf07e742AF39e16deC647a70746",
-  polymarketCtfAdapter: "0xEbB92A5374D277A3e1CA915741ce3077364d95c0",
+  accessManager: "0xEC4CBe73cFA6846B6772341e199289F7A4f20e7e",
+  oracle: "0xA63c6ebD3a0C6990D16Ea94D957c2Ad8D3c7Dd10",
+  core: "0xc1c7720Eb3563630aA77be561cD0B58F1Fa280F6",
+  pool: "0xc939CC89340E22bDf33df82A55118b19d4A11Bc2",
+  oracleUpdaterRouter: "0x59389217DEB847b3747767b2D7f56ffec43E9c72",
+  interestRateStrategy: "0x62cf2ab7346b5bA86faaa302d1E39908525166dB",
+  proxyAdmin: "0xf06B99237d2A53c6026ff5E3723417E6dEDcA651",
+  liquidator: "0xd7760D42661b8A559A61351873E0e006985F0d75",
+  mergeLiquidator: "0x5fA44Ba97470ADaDc97cb7F3ce64baceeE37f97a",
+  convertLiquidator: "0xBA802DF5e8258636738A28d27573203B32D2120A",
+  polymarketCtfAdapter: "0x66Ed3cf23719eb9111966AF6D6842F6548165313",
 };
 

package/src/addresses/polygonProxy.json

@@ -5,14 +5,14 @@
   "contracts": {
     "VarlaAccessManager": "0x5069d899bA3EBC4e12aB357F44B1DA3b0D0395f4",
     "VarlaOracle": "0x14e102a52474f569eB6C536a1bb15b9F69c5ba8f",
-    "VarlaCore": "0xb4b6887eBFFF5532a1fcED5A1B30F4Cf37aBf78f",
-    "VarlaPool": "0xB5f6F3F547c4CcedF92007B7d05C765aaA998497",
+    "VarlaCore": "0xB7e45923a4B21793Bae7Bd445fdd7318B0fF1409",
+    "VarlaPool": "0x0845B5b2cF295C77eBB23347706A30448bEf9aF2",
     "OracleUpdaterRouter": "0x3E1e6B54626D486b844C94e2385773b018fEB891",
-    "VarlaInterestRateStrategy": "0x80B990D9D637DEe4781A79da1CA9D36Bb3C949f6",
+    "VarlaInterestRateStrategy": "0x3Ae3a0B358a53aF835A924F4799c91943206e3d1",
     "VarlaProxyAdmin": "0x084aBfA2f32A53741DDd12D3166dA1318e7d73f7",
-    "VarlaLiquidator": "0x91949971c5B6F0783dC90F86938B7244215A7311",
-    "VarlaMergeLiquidator": "0x3F86802a7823C2d2D8bBBC3C7208289AfD9aCD96",
-    "VarlaConvertLiquidator": "0xdc0DDd1a58C21f84fA7FCBdA56e8a6f012e4fC43",
+    "VarlaLiquidator": "0x0f031BFbfFB08C3f844b8e59BAd9975CBec194b5",
+    "VarlaMergeLiquidator": "0x573A7bD3117c9D8EA1913c2Ccbdbf29E86EE4621",
+    "VarlaConvertLiquidator": "0xc1ba05218Fb56b5e31D34b3bb772fa57F1eDC7e4",
     "PolymarketCtfAdapter": "0x86B39800540D2C42eF1E34DF69117CB34F35a341"
   }
 }

package/src/addresses/polygonProxy.ts

@@ -4,14 +4,14 @@ import type { AddressBook } from "../types";
 export const polygonProxy: AddressBook = {
   accessManager: "0x5069d899bA3EBC4e12aB357F44B1DA3b0D0395f4",
   oracle: "0x14e102a52474f569eB6C536a1bb15b9F69c5ba8f",
-  core: "0xb4b6887eBFFF5532a1fcED5A1B30F4Cf37aBf78f",
-  pool: "0xB5f6F3F547c4CcedF92007B7d05C765aaA998497",
+  core: "0xB7e45923a4B21793Bae7Bd445fdd7318B0fF1409",
+  pool: "0x0845B5b2cF295C77eBB23347706A30448bEf9aF2",
   oracleUpdaterRouter: "0x3E1e6B54626D486b844C94e2385773b018fEB891",
-  interestRateStrategy: "0x80B990D9D637DEe4781A79da1CA9D36Bb3C949f6",
+  interestRateStrategy: "0x3Ae3a0B358a53aF835A924F4799c91943206e3d1",
   proxyAdmin: "0x084aBfA2f32A53741DDd12D3166dA1318e7d73f7",
-  liquidator: "0x91949971c5B6F0783dC90F86938B7244215A7311",
-  mergeLiquidator: "0x3F86802a7823C2d2D8bBBC3C7208289AfD9aCD96",
-  convertLiquidator: "0xdc0DDd1a58C21f84fA7FCBdA56e8a6f012e4fC43",
+  liquidator: "0x0f031BFbfFB08C3f844b8e59BAd9975CBec194b5",
+  mergeLiquidator: "0x573A7bD3117c9D8EA1913c2Ccbdbf29E86EE4621",
+  convertLiquidator: "0xc1ba05218Fb56b5e31D34b3bb772fa57F1eDC7e4",
   polymarketCtfAdapter: "0x86B39800540D2C42eF1E34DF69117CB34F35a341",
 };
 

package/src/leverage/deleverageExecute.ts

@@ -9,11 +9,7 @@
 
 import type { Address, Hash, PublicClient, WalletClient } from "viem";
 
-import {
-  prepareCoreRepay,
-  prepareCoreRepayWithAsset,
-  prepareCoreWithdraw,
-} from "../actions/core.js";
+import { prepareCoreRepay, prepareCoreWithdraw } from "../actions/core.js";
 import { sendTx } from "../actions/tx.js";
 import type { ReceiptRetryOptions } from "./receipt.js";
 import { waitForReceiptWithRetry } from "./receipt.js";
@@ -39,10 +35,16 @@ export type RunDeleverageLoopParams = {
   /**
    * Optional repay settlement asset for core repay steps.
    *
-   * When provided, repay steps call `VarlaCore.repay(amount, inputAsset)`.
+   * When provided, repay steps call `VarlaCore.repay(amount, inputAsset, onBehalfOf)`.
    * When omitted, repay steps call the default `VarlaCore.repay(amount)`.
    */
   inputAsset?: Address;
+  /**
+   * Optional borrower whose debt should be repaid by `account`.
+   *
+   * Defaults to `account`.
+   */
+  repayOnBehalfOf?: Address;
   /** Off-chain sell callback. */
   onSellStep: (step: Extract<DeleverageStep, { kind: "sell" }>) => Promise<SellResult>;
   onProgress?: OnDeleverageProgress;
@@ -139,6 +141,7 @@ export async function runDeleverageLoop(
     coreAddress,
     account,
     inputAsset,
+    repayOnBehalfOf,
     onSellStep,
     onProgress,
     confirmations = 1,
@@ -207,21 +210,17 @@ export async function runDeleverageLoop(
       if (step.kind === "repay") {
         const repayAmount = lastSellActualCollateral ?? step.collateralAmount;
         lastSellActualCollateral = undefined;
+        const onBehalfOf = repayOnBehalfOf ?? account;
+        const useOnBehalfPath =
+          inputAsset !== undefined || onBehalfOf.toLowerCase() !== account.toLowerCase();
 
-        const sim = inputAsset
-          ? await prepareCoreRepayWithAsset({
-              publicClient: publicClient as any,
-              coreAddress,
-              account,
-              amount: repayAmount,
-              inputAsset,
-            })
-          : await prepareCoreRepay({
-              publicClient: publicClient as any,
-              coreAddress,
-              account,
-              amount: repayAmount,
-            });
+        const sim = await prepareCoreRepay({
+          publicClient: publicClient as any,
+          coreAddress,
+          account,
+          amount: repayAmount,
+          ...(useOnBehalfPath ? { inputAsset, onBehalfOf } : {}),
+        });
         const hash = await sendTx({ walletClient: walletClient as any, request: sim.request });
         await waitForReceiptWithRetry({ publicClient, hash, confirmations, retry: receiptRetry });
 

package/src/leverage/execute.ts

@@ -10,11 +10,7 @@
 
 import type { Address, Hash, PublicClient, WalletClient } from "viem";
 
-import {
-  prepareCoreBorrow,
-  prepareCoreBorrowWithAsset,
-  prepareCoreDeposit,
-} from "../actions/core.js";
+import { prepareCoreBorrow, prepareCoreDeposit } from "../actions/core.js";
 import { sendTx } from "../actions/tx.js";
 import type { ReceiptRetryOptions } from "./receipt.js";
 import { waitForReceiptWithRetry } from "./receipt.js";
@@ -44,10 +40,16 @@ export type RunLeverageLoopParams = {
   /**
    * Optional borrow output asset for core borrow steps.
    *
-   * When provided, borrow steps call `VarlaCore.borrow(amount, outputAsset)`.
+   * When provided, borrow steps call `VarlaCore.borrow(amount, outputAsset, recipient)`.
    * When omitted, borrow steps call the default `VarlaCore.borrow(amount)`.
    */
   outputAsset?: Address;
+  /**
+   * Optional recipient for borrow proceeds.
+   *
+   * Defaults to `account`. Debt remains on `account`.
+   */
+  borrowRecipient?: Address;
   /**
    * Consumer-provided callback for off-chain token acquisition.
    *
@@ -166,6 +168,7 @@ export async function runLeverageLoop(
     coreAddress,
     account,
     outputAsset,
+    borrowRecipient,
     onBuyStep,
     onProgress,
     confirmations = 1,
@@ -235,20 +238,16 @@ export async function runLeverageLoop(
       }
 
       if (step.kind === "borrow") {
-        const sim = outputAsset
-          ? await prepareCoreBorrowWithAsset({
-              publicClient: publicClient as any,
-              coreAddress,
-              account,
-              amount: step.collateralAmount,
-              outputAsset,
-            })
-          : await prepareCoreBorrow({
-              publicClient: publicClient as any,
-              coreAddress,
-              account,
-              amount: step.collateralAmount,
-            });
+        const recipient = borrowRecipient ?? account;
+        const useRecipientPath =
+          outputAsset !== undefined || recipient.toLowerCase() !== account.toLowerCase();
+        const sim = await prepareCoreBorrow({
+          publicClient: publicClient as any,
+          coreAddress,
+          account,
+          amount: step.collateralAmount,
+          ...(useRecipientPath ? { outputAsset, recipient } : {}),
+        });
 
         const hash = await sendTx({ walletClient: walletClient as any, request: sim.request });
         await waitForReceiptWithRetry({ publicClient, hash, confirmations, retry: receiptRetry });

package/src/views/core.ts

@@ -196,6 +196,150 @@ export async function previewCoreDeposit(params: {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Withdraw pre-flight (previewCoreWithdraw)
+// ---------------------------------------------------------------------------
+
+/**
+ * Reason a collateral withdrawal would be rejected for a specific position.
+ *
+ * - `"zero-amount"` — caller passed `amount === 0n`.
+ * - `"insufficient-balance"` — user's deposited balance is below the requested amount.
+ */
+export type WithdrawBlockReason = "zero-amount" | "insufficient-balance";
+
+export type PreviewCoreWithdrawItem = {
+  positionId: bigint;
+  amount: bigint;
+  /** Current deposited balance of the user for this position. */
+  balance: bigint;
+  /** `true` when this position passes the pre-flight balance check. */
+  ok: boolean;
+  /** Present only when `ok === false`. */
+  reason?: WithdrawBlockReason;
+};
+
+export type PreviewCoreWithdraw = {
+  /**
+   * `true` only when every position passes the balance check AND the user either
+   * has no outstanding debt or has sufficient health factor to absorb the withdrawal.
+   *
+   * When `hasDeb === true`, always simulate the on-chain call or check HF separately
+   * before submitting — this preview cannot compute the exact post-withdraw HF
+   * without oracle price data.
+   */
+  canWithdraw: boolean;
+  /** Per-position results aligned to input order. */
+  items: PreviewCoreWithdrawItem[];
+  /** `true` when the user has any outstanding debt. Withdrawing while indebted
+   *  may reduce the health factor below the liquidation threshold. */
+  hasDebt: boolean;
+  /** Current health factor (WAD). `0` when the user has no debt. */
+  healthFactor: bigint;
+};
+
+/**
+ * Pre-flight check that mirrors VarlaCore.withdraw() balance validation.
+ *
+ * Checks (per position):
+ * 1. `amount > 0`
+ * 2. `core.positionBalances(user, id) >= amount`
+ *
+ * Account-level:
+ * - Whether the user currently has debt (`debt > 0`).
+ *
+ * **Important**: this function cannot predict the post-withdraw health factor
+ * without live oracle prices. When `hasDebt === true`, always double-check
+ * the HF with `readHealthFactor` or simulate the transaction before submitting.
+ *
+ * @example
+ * ```ts
+ * import { previewCoreWithdraw } from "@varla/sdk/views";
+ *
+ * const preview = await previewCoreWithdraw({
+ *   core,
+ *   user: "0x...",
+ *   positionIds: [yesId],
+ *   amounts: [50_000_000n],
+ * });
+ *
+ * if (!preview.canWithdraw) {
+ *   for (const item of preview.items) {
+ *     if (!item.ok) console.log(`Position ${item.positionId}: ${item.reason}`);
+ *   }
+ *   if (preview.hasDebt) console.log("User has debt — check HF before withdrawing");
+ * }
+ * ```
+ */
+// wraps: VarlaCore.positionBalances,VarlaCore.getDebt,VarlaCore.getHealthFactor
+export async function previewCoreWithdraw(params: {
+  core: {
+    read: {
+      positionBalances: (args: readonly [Address, bigint]) => Promise<bigint>;
+      getDebt: (args: readonly [Address]) => Promise<bigint>;
+      getHealthFactor: (args: readonly [Address]) => Promise<unknown>;
+    };
+  };
+  user: Address;
+  positionIds: readonly bigint[];
+  amounts: readonly bigint[];
+}): Promise<PreviewCoreWithdraw> {
+  const { core, user, positionIds, amounts } = params;
+
+  if (positionIds.length !== amounts.length) {
+    throw new Error("previewCoreWithdraw: positionIds and amounts must have the same length");
+  }
+
+  // Fetch all balances and account debt in parallel.
+  const [balances, debt, hfRaw] = await Promise.all([
+    Promise.all(positionIds.map((pid) => core.read.positionBalances([user, pid]))),
+    core.read.getDebt([user]),
+    core.read.getHealthFactor([user]),
+  ]);
+
+  // Extract health factor from the tuple returned by VarlaCore.getHealthFactor.
+  const hfAny = hfRaw as any;
+  const healthFactor: bigint =
+    typeof hfAny === "bigint"
+      ? hfAny
+      : typeof hfAny?.healthFactor === "bigint"
+        ? hfAny.healthFactor
+        : (hfAny?.[0] ?? 0n);
+
+  // Per-position checks.
+  const items: PreviewCoreWithdrawItem[] = [];
+  let allItemsOk = true;
+
+  for (let i = 0; i < positionIds.length; i++) {
+    const pid = positionIds[i]!;
+    const amount = amounts[i]!;
+    const balance = balances[i]!;
+
+    let ok = true;
+    let reason: WithdrawBlockReason | undefined;
+
+    if (amount === 0n) {
+      ok = false;
+      reason = "zero-amount";
+    } else if (balance < amount) {
+      ok = false;
+      reason = "insufficient-balance";
+    }
+
+    if (!ok) allItemsOk = false;
+    items.push(
+      reason !== undefined
+        ? { positionId: pid, amount, balance, ok, reason }
+        : { positionId: pid, amount, balance, ok },
+    );
+  }
+
+  const hasDebt = debt > 0n;
+  const canWithdraw = allItemsOk;
+
+  return { canWithdraw, items, hasDebt, healthFactor };
+}
+
 export type ReadAccountSnapshot = {
   portfolioValue: bigint;
   collateralValue: bigint;
@@ -513,12 +657,18 @@ export async function readBorrowerState(params: {
   return { user: params.user, scaledDebt, isBorrower, isLiquidatable };
 }
 
-// wraps: VarlaCore.getPortfolioValue
+// wraps: VarlaCore.getAccountSummary
 export async function readPortfolioValue(params: {
-  core: { read: { getPortfolioValue: (args: readonly [Address]) => Promise<bigint> } };
+  core: {
+    read: {
+      getAccountSummary: (
+        args: readonly [Address],
+      ) => Promise<readonly [bigint, bigint, bigint, bigint, bigint]>;
+    };
+  };
   user: Address;
 }): Promise<ReadPortfolioValue> {
-  const portfolioValue = await params.core.read.getPortfolioValue([params.user]);
+  const [portfolioValue] = await params.core.read.getAccountSummary([params.user]);
   return { user: params.user, portfolioValue };
 }