@portal-hq/web 3.13.1 → 3.13.2-0

package/lib/commonjs/integrations/yield/yieldxyz.js

@@ -9,9 +9,29 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const logger_1 = require("../../logger");
+const waitForEvmTxConfirmation_1 = require("../../internal/waitForEvmTxConfirmation");
+const stripStalePlanningNonce_1 = require("../../internal/stripStalePlanningNonce");
+const yieldEvmNetwork_1 = require("../../internal/yieldEvmNetwork");
+const LOG_PREFIX = '[YieldXyz]';
+/** CAIP-2 chain ID format: namespace:reference (e.g. eip155:1, solana:5eykt...) */
+const CAIP2_CHAIN_ID_REGEX = /^[a-z0-9-]+:[a-zA-Z0-9]+$/;
 class YieldXyz {
-    constructor({ mpc }) {
+    constructor({ mpc, waitForConfirmation, evmRequestFn, evmPollerOptions, }) {
         this.mpc = mpc;
+        this.waitForConfirmationFn = waitForConfirmation;
+        this.evmRequestFn = evmRequestFn;
+        this.evmPollerDefaults = evmPollerOptions;
+    }
+    /**
+     * Configures the signer used by deposit() and withdraw() when no per-call
+     * `signAndSendTransaction` option is provided. Typically called once after construction
+     * (e.g. Portal wires in its MPC signer via this method instead of the constructor).
+     *
+     * Per-call `signAndSendTransaction` in {@link YieldSubmitOptions} always takes precedence.
+     */
+    setSignAndSendTransaction(fn) {
+        this.signAndSendTransactionFn = fn;
     }
     /**
      * Retrieves yield balances for specified addresses and networks.
@@ -111,5 +131,525 @@ class YieldXyz {
             return (_a = this.mpc) === null || _a === void 0 ? void 0 : _a.getYieldXyzTransaction(transactionId);
         });
     }
+    /**
+     * Resolve suggested defaults (amount, validators) from Portal yield defaults map.
+     * Calls the dedicated Yield.xyz defaults endpoint used in the deposit/withdraw flow.
+     */
+    getYieldDefaults(req) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            return (_a = this.mpc) === null || _a === void 0 ? void 0 : _a.getYieldXyzDefaults(req);
+        });
+    }
+    getValidators(yieldId) {
+        var _a, _b, _c, _d;
+        return __awaiter(this, void 0, void 0, function* () {
+            const res = yield this.mpc.getYieldXyzValidators(yieldId);
+            logger_1.sdkLogger.debug(`${LOG_PREFIX} getValidators raw response`, res);
+            if (res.error) {
+                logger_1.sdkLogger.error(`${LOG_PREFIX} getValidators error`, res.error);
+                throw new Error(`[YieldXyz] getValidators failed: ${res.error}`);
+            }
+            const d = res.data;
+            const validators = (_c = (_a = d === null || d === void 0 ? void 0 : d.validators) !== null && _a !== void 0 ? _a : (_b = d === null || d === void 0 ? void 0 : d.rawResponse) === null || _b === void 0 ? void 0 : _b.validators) !== null && _c !== void 0 ? _c : (_d = d === null || d === void 0 ? void 0 : d.rawResponse) === null || _d === void 0 ? void 0 : _d.items;
+            logger_1.sdkLogger.debug(`${LOG_PREFIX} getValidators processed`, { validators });
+            if (!validators || !Array.isArray(validators)) {
+                logger_1.sdkLogger.error(`${LOG_PREFIX} No validators found for yieldId="${yieldId}"`, { data: d });
+                throw new Error(`[YieldXyz] No validators in response for yieldId="${yieldId}"`);
+            }
+            return validators;
+        });
+    }
+    /**
+     * @internal Validates and trims `chain` to a full CAIP-2 id (no aliases or numeric shortcuts).
+     */
+    requireFullCaip2Chain(chain) {
+        const c = chain.trim();
+        if (!c) {
+            throw new Error('[YieldXyz] chain is required.');
+        }
+        if (!CAIP2_CHAIN_ID_REGEX.test(c)) {
+            throw new Error(`[YieldXyz] chain must be a full CAIP-2 id (e.g. eip155:11155111). Received: "${chain}"`);
+        }
+        return c;
+    }
+    /**
+     * @internal When `params` includes a non-empty `yieldId`, returns it. Otherwise requires
+     * `chain` + `token`, validates CAIP-2, and resolves `yieldId` from Portal yield defaults.
+     */
+    resolveYieldIdForHighLevelAction(params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fromYieldId = 'yieldId' in params && params.yieldId != null
+                ? String(params.yieldId).trim()
+                : '';
+            if (fromYieldId !== '') {
+                return { yieldId: fromYieldId };
+            }
+            if (!('chain' in params) || !('token' in params)) {
+                throw new Error('[YieldXyz] Provide either yieldId, or both chain (full CAIP-2) and token.');
+            }
+            const chainCaip2 = this.requireFullCaip2Chain(params.chain);
+            const token = params.token.trim();
+            const yieldId = yield this.resolveYieldIdFromPortalDefaults(chainCaip2, token);
+            return { yieldId, chain: chainCaip2, token };
+        });
+    }
+    /**
+     * @internal Loads Portal yield defaults and reads `yieldId` for the exact map key `{caip2}:{token}`.
+     */
+    resolveYieldIdFromPortalDefaults(chainCaip2, tokenSymbol) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const token = tokenSymbol.trim();
+            if (!token) {
+                throw new Error('[YieldXyz] token is required; use the exact symbol suffix from the yield defaults map.');
+            }
+            const key = `${chainCaip2}:${token}`;
+            const res = yield this.getYieldDefaults({
+                includeOpportunities: false,
+            });
+            if (res.error) {
+                throw new Error(`[YieldXyz] Failed to get yield defaults: ${res.error}`);
+            }
+            if (!res.data) {
+                throw new Error('[YieldXyz] No data returned from yield defaults endpoint');
+            }
+            const entry = res.data[key];
+            const yieldId = entry === null || entry === void 0 ? void 0 : entry.yieldId;
+            if (yieldId == null || yieldId === '') {
+                throw new Error(`[YieldXyz] No default yield for key "${key}". Use chain and token exactly as in the Portal yield defaults response.`);
+            }
+            return yieldId;
+        });
+    }
+    /**
+     * High-level deposit: build enter yield action, sign and submit each transaction, track hashes.
+     *
+     * The signer is resolved in priority order:
+     * 1. `options.signAndSendTransaction` — per-call override.
+     * 2. Instance setter — configured via {@link YieldXyz.setSignAndSendTransaction} (e.g. Portal).
+     * 3. Error — thrown if neither is available.
+     *
+     * Supply either **`yieldId`** + `amount` (optional `address` / `arguments`), or full **CAIP-2**
+     * **`chain`** + **`token`** + `amount` so the SDK can resolve `yieldId` from Portal yield defaults.
+     * Optional {@link YieldSubmitOptions.onProgress} fires the same steps regardless of input mode.
+     */
+    deposit(params, options) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const signAndSend = (_a = options === null || options === void 0 ? void 0 : options.signAndSendTransaction) !== null && _a !== void 0 ? _a : this.signAndSendTransactionFn;
+            if (!signAndSend) {
+                throw new Error('[YieldXyz] No signer configured. Call setSignAndSendTransaction() on the instance or pass signAndSendTransaction in options.');
+            }
+            const { yieldId, chain: resolvedChain, token: resolvedToken } = yield this.resolveYieldIdForHighLevelAction(params);
+            logger_1.sdkLogger.info(`${LOG_PREFIX} deposit: entry`, {
+                amount: params.amount,
+                yieldId,
+                token: resolvedToken,
+                chain: resolvedChain,
+                usedExplicitYieldId: resolvedChain === undefined,
+                hasAddress: Boolean(params.address),
+                hasArguments: Boolean(params.arguments),
+            });
+            logger_1.sdkLogger.debug(`${LOG_PREFIX} deposit: resolved yieldId`, { yieldId });
+            const request = {
+                yieldId,
+                address: params.address,
+                arguments: Object.assign(Object.assign({}, params.arguments), { amount: params.amount }),
+            };
+            try {
+                const response = yield this.enter(request);
+                const effectiveWaitForConfirmation = this.resolveEffectiveWaitForConfirmation(options);
+                const base = yield this.executeAndTrack(response, signAndSend, options === null || options === void 0 ? void 0 : options.onProgress, effectiveWaitForConfirmation, 'deposit');
+                const result = Object.assign(Object.assign({}, base), (resolvedChain !== undefined && resolvedToken !== undefined
+                    ? { chain: resolvedChain, token: resolvedToken }
+                    : {}));
+                logger_1.sdkLogger.info(`${LOG_PREFIX} deposit: complete`, {
+                    hashes: result.hashes,
+                    yieldId: result.yieldId,
+                    status: result.status,
+                    yieldOpportunityDetails: result.yieldOpportunityDetails,
+                });
+                return result;
+            }
+            catch (error) {
+                logger_1.sdkLogger.debug(`${LOG_PREFIX} deposit: failed, re-throwing`, error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * High-level withdraw: same dual input modes, `yieldId` resolution, and signer fallback
+     * order as {@link YieldXyz.deposit}.
+     */
+    withdraw(params, options) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const signAndSend = (_a = options === null || options === void 0 ? void 0 : options.signAndSendTransaction) !== null && _a !== void 0 ? _a : this.signAndSendTransactionFn;
+            if (!signAndSend) {
+                throw new Error('[YieldXyz] No signer configured. Call setSignAndSendTransaction() on the instance or pass signAndSendTransaction in options.');
+            }
+            const { yieldId, chain: resolvedChain, token: resolvedToken } = yield this.resolveYieldIdForHighLevelAction(params);
+            logger_1.sdkLogger.debug(`${LOG_PREFIX} withdraw: entry`, {
+                amount: params.amount,
+                yieldId,
+                token: resolvedToken,
+                chain: resolvedChain,
+                usedExplicitYieldId: resolvedChain === undefined,
+                hasAddress: Boolean(params.address),
+                hasArguments: Boolean(params.arguments),
+            });
+            logger_1.sdkLogger.debug(`${LOG_PREFIX} withdraw: resolved yieldId`, { yieldId });
+            const request = {
+                yieldId,
+                address: params.address,
+                arguments: Object.assign(Object.assign({}, params.arguments), { amount: params.amount }),
+            };
+            try {
+                const response = yield this.exit(request);
+                const effectiveWaitForConfirmation = this.resolveEffectiveWaitForConfirmation(options);
+                const base = yield this.executeAndTrack(response, signAndSend, options === null || options === void 0 ? void 0 : options.onProgress, effectiveWaitForConfirmation, 'withdraw');
+                const result = Object.assign(Object.assign({}, base), (resolvedChain !== undefined && resolvedToken !== undefined
+                    ? { chain: resolvedChain, token: resolvedToken }
+                    : {}));
+                logger_1.sdkLogger.info(`${LOG_PREFIX} withdraw: complete`, {
+                    hashes: result.hashes,
+                    yieldId: result.yieldId,
+                    status: result.status,
+                    yieldOpportunityDetails: result.yieldOpportunityDetails,
+                });
+                return result;
+            }
+            catch (error) {
+                logger_1.sdkLogger.debug(`${LOG_PREFIX} withdraw: failed, re-throwing`, error);
+                throw error;
+            }
+        });
+    }
+    extractTransactions(response) {
+        var _a, _b;
+        const transactions = (_b = (_a = response.data) === null || _a === void 0 ? void 0 : _a.rawResponse) === null || _b === void 0 ? void 0 : _b.transactions;
+        if (transactions &&
+            Array.isArray(transactions) &&
+            transactions.length > 0) {
+            return transactions;
+        }
+        return [];
+    }
+    buildYieldOpportunityDetails(response) {
+        var _a;
+        const raw = (_a = response.data) === null || _a === void 0 ? void 0 : _a.rawResponse;
+        if (!raw) {
+            return { yieldId: '' };
+        }
+        return {
+            yieldId: raw.yieldId,
+            intent: raw.intent,
+            type: raw.type,
+            executionPattern: raw.executionPattern,
+            status: raw.status,
+            amount: raw.amount,
+            amountUsd: raw.amountUsd,
+        };
+    }
+    parseUnsignedToObject(unsigned) {
+        if (unsigned == null)
+            return {};
+        if (typeof unsigned === 'object')
+            return Object.assign({}, unsigned);
+        try {
+            const parsed = JSON.parse(unsigned);
+            // Validate parsed result is a plain object (not null, not array)
+            if (parsed != null &&
+                typeof parsed === 'object' &&
+                !Array.isArray(parsed)) {
+                return parsed;
+            }
+            logger_1.sdkLogger.warn(`${LOG_PREFIX} JSON.parse returned non-object type: ${typeof parsed}`);
+            return {};
+        }
+        catch (_a) {
+            return {};
+        }
+    }
+    getTransactionPayloadSummary(payload) {
+        var _a, _b, _c;
+        const obj = this.parseUnsignedToObject(typeof payload === 'string'
+            ? payload
+            : payload);
+        const data = (_a = obj.data) !== null && _a !== void 0 ? _a : obj.input;
+        const dataStr = typeof data === 'string' ? data : JSON.stringify(data);
+        return {
+            from: obj.from,
+            to: obj.to,
+            dataLength: (_b = dataStr === null || dataStr === void 0 ? void 0 : dataStr.length) !== null && _b !== void 0 ? _b : 0,
+            value: obj.value,
+            gasLimit: (_c = obj.gas) !== null && _c !== void 0 ? _c : obj.gasLimit,
+            nonce: obj.nonce,
+            maxFeePerGas: obj.maxFeePerGas,
+            maxPriorityFeePerGas: obj.maxPriorityFeePerGas,
+        };
+    }
+    logError(context, error) {
+        const err = error;
+        logger_1.sdkLogger.error(`${LOG_PREFIX} ${context}:`, error);
+        if (err.response !== undefined) {
+            logger_1.sdkLogger.debug(`${LOG_PREFIX} ${context} HTTP response:`, err.response);
+        }
+        if (err.status !== undefined) {
+            logger_1.sdkLogger.debug(`${LOG_PREFIX} ${context} HTTP status:`, err.status);
+        }
+        if (err.data !== undefined) {
+            logger_1.sdkLogger.debug(`${LOG_PREFIX} ${context} HTTP response data:`, err.data);
+        }
+    }
+    resolveEffectiveWaitForConfirmation(options) {
+        var _a;
+        if (options === null || options === void 0 ? void 0 : options.waitForConfirmation) {
+            return options.waitForConfirmation;
+        }
+        if (this.waitForConfirmationFn) {
+            return this.waitForConfirmationFn;
+        }
+        const evmFn = (_a = options === null || options === void 0 ? void 0 : options.evmRequestFn) !== null && _a !== void 0 ? _a : this.evmRequestFn;
+        if (!evmFn) {
+            return undefined;
+        }
+        const pollerOpts = Object.assign(Object.assign({}, this.evmPollerDefaults), options === null || options === void 0 ? void 0 : options.evmPollerOptions);
+        return (txHash, network) => __awaiter(this, void 0, void 0, function* () {
+            var _b;
+            if (!(0, yieldEvmNetwork_1.isYieldEvmNetwork)(network)) {
+                logger_1.sdkLogger.warn(`${LOG_PREFIX} Cannot verify confirmation for non-EVM network ${network}. ` +
+                    'Internal EVM poller fallback does not support non-EVM networks.');
+                return false;
+            }
+            const caip2 = network.startsWith('eip155:')
+                ? network
+                : (_b = (0, yieldEvmNetwork_1.resolveYieldNetworkToCaip2)(network)) !== null && _b !== void 0 ? _b : network;
+            return (0, waitForEvmTxConfirmation_1.waitForEvmTxConfirmation)(txHash, caip2, evmFn, {
+                pollIntervalMs: pollerOpts.pollIntervalMs,
+                timeoutMs: pollerOpts.timeoutMs,
+                onTimeout: 'resolve_false',
+            });
+        });
+    }
+    executeAndTrack(response, signAndSend, onProgress, waitForConfirmation, method = 'deposit') {
+        var _a, _b, _c, _d, _e;
+        return __awaiter(this, void 0, void 0, function* () {
+            const transactions = this.extractTransactions(response);
+            logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: transaction count`, {
+                method,
+                transactionCount: transactions.length,
+            });
+            if (transactions.length === 0) {
+                throw new Error('No transactions in yield action response.');
+            }
+            const total = transactions.length;
+            const hashes = [];
+            let confirmationsReached = 0;
+            let confirmationsRequired = waitForConfirmation ? total : 0;
+            for (let index = 0; index < transactions.length; index++) {
+                const tx = transactions[index];
+                // Validate transaction exists (defensive check for sparse arrays)
+                if (!tx) {
+                    throw new Error(`Transaction at index ${index} is undefined or null. This indicates a malformed API response.`);
+                }
+                try {
+                    if (!tx.id) {
+                        throw new Error(`Transaction at index ${index} is missing required field "id".`);
+                    }
+                    if (tx.network == null || tx.network === '') {
+                        throw new Error(`Transaction ${tx.id} is missing required field "network".`);
+                    }
+                    if (tx.unsignedTransaction == null) {
+                        throw new Error(`Transaction ${tx.id} has no unsignedTransaction to sign.`);
+                    }
+                    const rawUnsigned = tx.unsignedTransaction;
+                    let payloadToSend = rawUnsigned;
+                    const isEvm = typeof tx.network === 'string' && (0, yieldEvmNetwork_1.isYieldEvmNetwork)(tx.network);
+                    const resolvedNetwork = isEvm
+                        ? ((_a = (0, yieldEvmNetwork_1.resolveYieldNetworkToCaip2)(tx.network)) !== null && _a !== void 0 ? _a : tx.network)
+                        : tx.network;
+                    if (isEvm) {
+                        const canStripNonce = typeof rawUnsigned === 'string' ||
+                            (typeof rawUnsigned === 'object' &&
+                                rawUnsigned !== null &&
+                                !Array.isArray(rawUnsigned));
+                        if (canStripNonce) {
+                            payloadToSend = (0, stripStalePlanningNonce_1.stripStalePlanningNonceIfJsonObject)(rawUnsigned);
+                        }
+                        logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: nonce stripped for EVM tx`, {
+                            index,
+                            transactionId: tx.id,
+                            network: tx.network,
+                            payloadKind: typeof payloadToSend,
+                        });
+                    }
+                    const payloadSummary = this.getTransactionPayloadSummary(payloadToSend);
+                    logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: transaction preparation`, {
+                        method,
+                        index,
+                        total,
+                        transactionId: tx.id,
+                        network: tx.network,
+                        type: tx.type,
+                        payloadSummary,
+                    });
+                    const progressSigning = {
+                        step: 'signing',
+                        index,
+                        total,
+                    };
+                    logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: signing start`, {
+                        method,
+                        index,
+                        total,
+                        transactionId: tx.id,
+                    });
+                    onProgress === null || onProgress === void 0 ? void 0 : onProgress(progressSigning);
+                    const hash = yield signAndSend(payloadToSend, resolvedNetwork);
+                    if (typeof hash !== 'string' || hash.trim() === '') {
+                        throw new Error(`Transaction ${tx.id} signing returned an empty or invalid hash.`);
+                    }
+                    hashes.push(hash);
+                    logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: signing complete`, {
+                        method,
+                        index,
+                        total,
+                        transactionId: tx.id,
+                        hash,
+                    });
+                    logger_1.sdkLogger.info(`${LOG_PREFIX} ${method}: submitted tx`, {
+                        index: index + 1,
+                        total,
+                        hash,
+                    });
+                    const progressSubmitted = {
+                        step: 'submitted',
+                        index,
+                        total,
+                        hash,
+                    };
+                    logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: onProgress`, {
+                        step: progressSubmitted.step,
+                        index: progressSubmitted.index,
+                        total: progressSubmitted.total,
+                        hash: progressSubmitted.hash,
+                    });
+                    onProgress === null || onProgress === void 0 ? void 0 : onProgress(progressSubmitted);
+                    if (waitForConfirmation) {
+                        const progressConfirming = {
+                            step: 'confirming',
+                            index,
+                            total,
+                            hash,
+                        };
+                        logger_1.sdkLogger.info(`${LOG_PREFIX} executeAndTrack: waiting for confirmation`, {
+                            method,
+                            index,
+                            total,
+                            hash,
+                            network: tx.network,
+                            strategy: 'waitForConfirmation',
+                        });
+                        onProgress === null || onProgress === void 0 ? void 0 : onProgress(progressConfirming);
+                        const waiterResult = yield waitForConfirmation(hash, resolvedNetwork);
+                        const isConfirmed = waiterResult === true;
+                        if (isConfirmed) {
+                            confirmationsReached += 1;
+                            logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: confirmation received`, {
+                                method,
+                                hash,
+                                confirmationsReached,
+                                total,
+                            });
+                            onProgress === null || onProgress === void 0 ? void 0 : onProgress({ step: 'confirmed', index, total, hash });
+                        }
+                        else {
+                            logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: confirmation not reached (waitForConfirmation did not return true)`, {
+                                method,
+                                hash,
+                                confirmationsReached,
+                                total,
+                                waiterResult,
+                            });
+                            // Uncertain confirmation (timeout / false / no response): safe stop.
+                            // Track the hash with backend before stopping, then return partial result.
+                            logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: track (submitTransactionHash) call before break`, {
+                                method,
+                                transactionId: tx.id,
+                                hash,
+                            });
+                            yield this.track({
+                                transactionId: tx.id,
+                                hash,
+                            });
+                            break;
+                        }
+                    }
+                    logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: track (submitTransactionHash) call`, {
+                        method,
+                        transactionId: tx.id,
+                        hash,
+                    });
+                    const trackResponse = yield this.track({
+                        transactionId: tx.id,
+                        hash,
+                    });
+                    logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: track response`, {
+                        method,
+                        transactionId: tx.id,
+                        hash,
+                        trackStatus: (_c = (_b = trackResponse === null || trackResponse === void 0 ? void 0 : trackResponse.data) === null || _b === void 0 ? void 0 : _b.rawResponse) === null || _c === void 0 ? void 0 : _c.status,
+                    });
+                }
+                catch (error) {
+                    this.logError(`executeAndTrack ${method} failed at index ${index}`, error);
+                    logger_1.sdkLogger.debug(`${LOG_PREFIX} executeAndTrack: error context`, {
+                        method,
+                        index,
+                        total,
+                        transactionId: tx.id,
+                        network: tx.network,
+                        hashesSoFar: hashes.length,
+                    });
+                    throw error;
+                }
+            }
+            const rawResponse = (_d = response.data) === null || _d === void 0 ? void 0 : _d.rawResponse;
+            const yieldId = (_e = rawResponse === null || rawResponse === void 0 ? void 0 : rawResponse.yieldId) !== null && _e !== void 0 ? _e : '';
+            const yieldOpportunityDetails = this.buildYieldOpportunityDetails(response);
+            // Determine status based on confirmation semantics from docs:
+            // - If no confirmations required (no waitForConfirmation): SUCCESS
+            // - If all required confirmations reached: SUCCESS
+            // - If some confirmations reached but not all: PARTIAL_SUCCESS
+            // - If confirmations required but zero reached: FAILED
+            let status;
+            if (confirmationsRequired === 0) {
+                status = 'SUCCESS';
+            }
+            else if (confirmationsReached === confirmationsRequired) {
+                status = 'SUCCESS';
+            }
+            else if (confirmationsReached > 0) {
+                status = 'PARTIAL_SUCCESS';
+            }
+            else {
+                status = 'FAILED';
+            }
+            logger_1.sdkLogger.info(`${LOG_PREFIX} ${method}: executeAndTrack complete`, {
+                yieldId,
+                hashCount: hashes.length,
+                confirmationsReached,
+                confirmationsRequired,
+                status,
+            });
+            return {
+                hashes,
+                yieldId,
+                yieldOpportunityDetails,
+                status,
+            };
+        });
+    }
 }
 exports.default = YieldXyz;

package/lib/commonjs/internal/pollLoop.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Domain-agnostic poll loop (sleep + deadline + optional backoff).
+ * LiFi / other modules supply classification via `tick`.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollLoop = exports.PollLoopTimeoutError = void 0;
+class PollLoopTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PollLoopTimeoutError';
+    }
+}
+exports.PollLoopTimeoutError = PollLoopTimeoutError;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Repeatedly awaits `tick` until it returns `stop` (returns value), `throw` (propagates),
+ * or the deadline passes (throws {@link PollLoopTimeoutError}).
+ */
+function pollLoop(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { tick, intervalMs: baseIntervalMs, initialDelayMs = 0, backoff, timeoutMs, } = options;
+        const deadline = Date.now() + timeoutMs;
+        let interval = baseIntervalMs;
+        if (initialDelayMs > 0) {
+            yield sleep(initialDelayMs);
+        }
+        while (Date.now() < deadline) {
+            const result = yield tick();
+            // Check deadline again after tick completes (tick may have taken a long time)
+            if (Date.now() >= deadline && result.kind === 'continue') {
+                break;
+            }
+            if (result.kind === 'stop') {
+                return result.value;
+            }
+            if (result.kind === 'throw') {
+                throw result.error;
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                break;
+            }
+            const sleepMs = Math.min(interval, Math.max(0, remaining));
+            yield sleep(sleepMs);
+            if (backoff) {
+                interval = Math.min(interval * backoff.factor, backoff.maxIntervalMs);
+            }
+        }
+        throw new PollLoopTimeoutError(`pollLoop timed out after ${timeoutMs}ms`);
+    });
+}
+exports.pollLoop = pollLoop;