@exponent-labs/exponent-sdk 0.9.0 → 0.9.1

package/build/exponentVaults/loopscale/client.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Loopscale manager flow:
+ *
+ * 1. Call a raw Loopscale endpoint such as `createStrategy(...)`,
+ *    `createLoan(...)`, or `borrowPrincipal(...)`.
+ * 2. Hand the raw response back to this client.
+ * 3. Choose one of two paths:
+ *    - `prepareVaultTransactions(...)` when you want appendable instruction
+ *      pieces you can compose with your own transaction building logic.
+ *    - `buildVaultTransactions(...)` when you want locally signed
+ *      `VersionedTransaction`s that are ready for optional Loopscale
+ *      co-signing and then `connection.sendTransaction(...)`.
+ * 4. Call `coSign(...)` only on returned transactions where
+ *    `requiresLoopscaleCoSign === true`.
+ *
+ * This distinction is intentional:
+ *
+ * - Wrapped Loopscale sync transactions require Loopscale MPC because they
+ *   represent Loopscale-authored flows that expect Loopscale's signature.
+ * - Setup transactions and other top-level non-Loopscale transactions must
+ *   stay local. They are constructed by the SDK to make the manager flow
+ *   complete, but they are not Loopscale-signed transactions and should not
+ *   be sent to Loopscale's MPC endpoint.
+ *
+ * In other words, `requiresLoopscaleCoSign` is not a convenience flag. It is
+ * the contract that tells the caller which transactions belong to Loopscale's
+ * signing domain and which ones do not.
+ *
+ * Example:
+ *
+ * ```ts
+ * const client = new LoopscaleClient({
+ *   connection,
+ *   userWallet: squadsVault,
+ *   payer: squadsVault,
+ * })
+ *
+ * const response = await client.createStrategy({
+ *   principalMint,
+ *   lender: squadsVault,
+ *   amount: 0,
+ * })
+ *
+ * const builtTransactions = await client.buildVaultTransactions({
+ *   response,
+ *   context: {
+ *     connection,
+ *     signer: manager.publicKey,
+ *     signers: [manager],
+ *     vaultPda: squadsVault,
+ *     vaultAddress,
+ *     squadsProgram,
+ *   },
+ * })
+ *
+ * for (const built of builtTransactions) {
+ *   const transaction = built.requiresLoopscaleCoSign
+ *     ? await client.coSign(built.transaction)
+ *     : built.transaction
+ *
+ *   await connection.sendTransaction(transaction, { skipPreflight: false })
+ * }
+ * ```
+ */
+import { PublicKey, VersionedTransaction } from "@solana/web3.js";
+import type { LoopscaleBorrowPrincipalParams, LoopscaleClientConfig, LoopscaleCloseLoanParams, LoopscaleCloseStrategyParams, LoopscaleCreateLoanParams, LoopscaleCreateLoanResponse, LoopscaleCreateStrategyParams, LoopscaleDepositCollateralParams, LoopscaleDepositStrategyParams, LoopscaleGetStrategiesParams, LoopscaleLoanInfoParams, LoopscaleLoanInfoResponse, LoopscaleLoanTransactionResponse, LoopscaleMaxQuote, LoopscaleMaxQuoteParams, LoopscaleQuote, LoopscaleQuoteParams, LoopscaleRepayLoanSimpleParams, LoopscaleStrategyInfoResponse, LoopscaleTransactionResponse, LoopscaleTransactionsResponse, LoopscaleUpdateStrategyParams, LoopscaleVersionedTransactionBatchResponse, LoopscaleVersionedTransactionResponse, LoopscaleWithdrawCollateralParams, LoopscaleWithdrawStrategyParams } from "./types";
+import type { LoopscaleBuildTransactionsContext, LoopscaleBuiltTransaction, LoopscalePreparedTransaction, LoopscaleVaultPreparationContext } from "./prepared-types";
+import { deserializeLoopscaleTransactionBatchResponse, deserializeLoopscaleTransactionResponse, extractCreatedStrategyAddress, extractCreatedStrategyNonce, getLoopscaleTransactionResponses, identifyLoopscaleInstruction } from "./helpers";
+/**
+ * Thin docs-aligned Loopscale client for strategies, loans, and related query endpoints.
+ *
+ * Transaction methods intentionally return the raw Loopscale response shapes
+ * instead of derived sync-action bundles. Use
+ * {@link LoopscaleClient.prepareVaultTransactions} when you need appendable
+ * transaction pieces, or {@link LoopscaleClient.buildVaultTransactions} when
+ * you want locally signed transactions that are ready for optional
+ * `client.coSign(...)` and `connection.sendTransaction(...)`.
+ *
+ * Refinancing and other lock/unlock maintenance flows remain intentionally
+ * excluded. The client only covers strategies, loans, and cleanup endpoints
+ * that can be represented as raw transaction responses.
+ *
+ * Typical usage:
+ *
+ * - Query Loopscale data through the read methods on this client.
+ * - Build raw Loopscale transactions through the strategy and loan methods.
+ * - Turn raw responses into appendable instruction pieces with
+ *   {@link LoopscaleClient.prepareVaultTransactions}.
+ * - Or compile ready-to-send transactions with
+ *   {@link LoopscaleClient.buildVaultTransactions}.
+ * - Call {@link LoopscaleClient.coSign} only for transactions flagged with
+ *   `requiresLoopscaleCoSign`.
+ */
+export declare class LoopscaleClient {
+    private readonly connection;
+    private readonly baseUrl;
+    private readonly userWallet;
+    private readonly payer;
+    private readonly debug;
+    constructor(config: LoopscaleClientConfig);
+    /**
+     * Load Loopscale quotes for a principal/collateral pair.
+     */
+    getQuotes(params: LoopscaleQuoteParams): Promise<LoopscaleQuote[]>;
+    /**
+     * Load the best quote for one or more specific collateral assets.
+     */
+    getMaxQuote(params: LoopscaleMaxQuoteParams): Promise<LoopscaleMaxQuote[]>;
+    /**
+     * Load Loopscale loan positions.
+     */
+    getLoanInfo(params: LoopscaleLoanInfoParams): Promise<LoopscaleLoanInfoResponse>;
+    /**
+     * Load Loopscale lending strategies.
+     */
+    getStrategies(params: LoopscaleGetStrategiesParams): Promise<LoopscaleStrategyInfoResponse>;
+    /**
+     * Build a raw Loopscale `createStrategy` transaction batch.
+     */
+    createStrategy(params: LoopscaleCreateStrategyParams): Promise<LoopscaleVersionedTransactionBatchResponse>;
+    /**
+     * Build a raw Loopscale `depositStrategy` transaction.
+     */
+    depositStrategy(params: LoopscaleDepositStrategyParams): Promise<LoopscaleVersionedTransactionResponse>;
+    /**
+     * Build a raw Loopscale `withdrawStrategy` transaction.
+     */
+    withdrawStrategy(params: LoopscaleWithdrawStrategyParams): Promise<LoopscaleVersionedTransactionResponse>;
+    /**
+     * Build a raw Loopscale `closeStrategy` transaction.
+     */
+    closeStrategy(params: LoopscaleCloseStrategyParams): Promise<LoopscaleVersionedTransactionResponse>;
+    /**
+     * Build raw Loopscale `updateStrategy` transactions.
+     */
+    updateStrategy(params: LoopscaleUpdateStrategyParams): Promise<LoopscaleVersionedTransactionBatchResponse>;
+    /**
+     * Build a raw Loopscale `createLoan` transaction.
+     */
+    createLoan(params: LoopscaleCreateLoanParams): Promise<LoopscaleCreateLoanResponse>;
+    /**
+     * Build a raw Loopscale `borrowPrincipal` transaction.
+     *
+     * The published OpenAPI schema currently documents a single serialized
+     * transaction response, but live responses can also return a wrapped
+     * `transactions` array with `expectedLoanInfo` when Loopscale inserts
+     * additional internal maintenance steps.
+     */
+    borrowPrincipal(params: LoopscaleBorrowPrincipalParams): Promise<LoopscaleLoanTransactionResponse>;
+    /**
+     * Build a raw Loopscale `depositCollateral` transaction.
+     */
+    depositCollateral(params: LoopscaleDepositCollateralParams): Promise<LoopscaleVersionedTransactionResponse>;
+    /**
+     * Build a raw Loopscale `withdrawCollateral` transaction.
+     *
+     * Full collateral removal can trigger internal loan-maintenance instructions,
+     * so callers should accept either a single serialized transaction or a wrapped
+     * `transactions` array.
+     */
+    withdrawCollateral(params: LoopscaleWithdrawCollateralParams): Promise<LoopscaleLoanTransactionResponse>;
+    /**
+     * Build a raw Loopscale `repay_simple` transaction response.
+     */
+    repayLoanSimple(params: LoopscaleRepayLoanSimpleParams): Promise<LoopscaleTransactionsResponse>;
+    /**
+     * Build a raw Loopscale `close_loan` transaction response.
+     */
+    closeLoan(params: LoopscaleCloseLoanParams): Promise<LoopscaleLoanTransactionResponse>;
+    /**
+     * Convert a raw Loopscale response into manager-ready vault transaction pieces.
+     *
+     * This is the lower-level, appendable "lego" API.
+     *
+     * Each returned entry represents one manager-facing transaction:
+     * send `setupInstructions` first when present, then send the main
+     * `instructions`. Wrapped sync transactions are already flattened into one
+     * instruction list, so callers do not need to manually inspect the raw
+     * Loopscale response to figure out which instructions should be wrapped.
+     *
+     * Use this when you want to compose Loopscale output with your own custom
+     * transaction building logic.
+     */
+    prepareVaultTransactions({ response, context, }: {
+        response: LoopscaleTransactionResponse;
+        context: LoopscaleVaultPreparationContext;
+    }): Promise<LoopscalePreparedTransaction[]>;
+    /**
+     * Build locally signed transactions from a raw Loopscale response.
+     *
+     * This is the simplest manager-facing API.
+     *
+     * The returned transactions are ready for:
+     * 1. `await client.coSign(tx)` when `requiresLoopscaleCoSign === true`
+     * 2. `connection.sendTransaction(tx)`
+     *
+     * The co-signing flag is deliberately per-transaction, not global. A single
+     * Loopscale response can produce:
+     *
+     * - local setup transactions that must be sent as-is,
+     * - local top-level transactions that do not belong to Loopscale's signing
+     *   domain,
+     * - one wrapped Loopscale sync transaction that does require Loopscale MPC.
+     *
+     * The client returns all of them in send order and marks only the wrapped
+     * Loopscale transaction for MPC co-signing. This is the correct boundary:
+     * callers should not guess which transactions need Loopscale's signature.
+     *
+     * The first signer in `context.signers` must match `context.signer`, since
+     * that signer is used as the fee payer for the compiled transactions.
+     */
+    buildVaultTransactions({ response, context, }: {
+        response: LoopscaleTransactionResponse;
+        context: LoopscaleBuildTransactionsContext;
+    }): Promise<LoopscaleBuiltTransaction[]>;
+    /**
+     * Co-sign a prepared transaction with Loopscale's back-end signer.
+     *
+     * This uses Loopscale's public MPC co-signing endpoint. The returned
+     * transaction is required to keep the exact same message as the locally
+     * signed input, and any local signatures that are missing from the response
+     * are copied back onto the returned transaction before it is handed to the
+     * caller.
+     *
+     * Only call this for transactions flagged with
+     * `requiresLoopscaleCoSign === true`. Transactions not flagged that way do
+     * not belong to Loopscale's signing domain and should be sent directly.
+     */
+    coSign(transaction: VersionedTransaction): Promise<VersionedTransaction>;
+    /**
+     * Extract the strategy PDA from a `createStrategy` response using the client's connection.
+     */
+    extractCreatedStrategyAddress(response: LoopscaleTransactionResponse): Promise<PublicKey>;
+    /**
+     * Extract the strategy nonce from a `createStrategy` response using the client's connection.
+     */
+    extractCreatedStrategyNonce(response: LoopscaleTransactionResponse): Promise<PublicKey>;
+    private post;
+}
+export { deserializeLoopscaleTransactionBatchResponse, deserializeLoopscaleTransactionResponse, extractCreatedStrategyAddress, extractCreatedStrategyNonce, getLoopscaleTransactionResponses, identifyLoopscaleInstruction, };