docs: clarify withdraw preconditions

packages/client/README.md

@@ -33,9 +33,23 @@ const result = await supply(client, {
       value: '1000'
     }
   },
-  supplier: evmAddress('0x742d35cc6e5c4ce3b69a2a8c7c8e5f7e9a0b1234'),
+  sender: evmAddress('0x742d35cc6e5c4ce3b69a2a8c7c8e5f7e9a0b1234'),
   chainId: chainId(1),
 })
   .andThen(sendWith(wallet))
   .andThen(client.waitForTransaction);
 ```
+
+## Error handling
+
+Actions return `ResultAsync` values for errors that are part of the normal
+operation flow. For transaction actions, modeled validation outcomes such as
+`InsufficientBalanceError` are returned as execution plans and can be handled
+before signing or sending a transaction.
+
+Some thrown errors represent violated SDK invariants instead. For example, a
+withdrawal request assumes the sender already has a supply position for the
+selected market and reserve. Check user position data with `userSupplies`
+before calling `withdraw`, then only submit withdrawals for reserves that appear
+in the sender's supply positions. Use thrown errors only as a defensive safety
+net rather than relying on their message text for application logic.

packages/client/src/actions/transactions.ts

@@ -148,6 +148,12 @@ export function repay(
 
 /**
  * Creates a transaction to withdraw from a market.
+ * The request assumes the sender already has a supply position for the selected
+ * market and reserve. Query `userSupplies` before calling `withdraw`, and only
+ * submit withdrawals for reserves present in the sender's supply positions.
+ * Modeled execution-plan validation errors such as `InsufficientBalanceError`
+ * are returned through the result; violated preconditions can throw invariant
+ * errors.
  *
  * ```ts
  * const result = await withdraw(client, {
@@ -158,7 +164,7 @@ export function repay(
  *       value: { exact: '750' },
  *     },
  *   },
- *   supplier: evmAddress('0x9abc…'),
+ *   sender: evmAddress('0x9abc…'),
  *   chainId: market.chain.chainId,
  * }).andThen(sendWith(wallet)).andThen(client.waitForTransaction);
  *

packages/react/src/transactions.ts

@@ -183,6 +183,11 @@ export function useRepay(): UseAsyncTask<
 
 /**
  * A hook that provides a way to withdraw supplied assets from an Aave market.
+ * Before calling this hook, check the user's supply position with
+ * `useUserSupplies` and only submit a withdrawal for a reserve the user has
+ * supplied. Execution-plan validation errors such as `InsufficientBalanceError`
+ * are returned through the result, while violated preconditions can throw
+ * invariant errors.
  *
  * ```ts
  * const [withdraw, withdrawing] = useWithdraw();