@node-dlc/core/dist/dlc/finance/CsoInfo.d.ts

DLC Core

import { Value } from '@node-dlc/bitcoin';
import { ContractInfo, OrderPositionInfo, PayoutFunction } from '@node-dlc/messaging';
import { DlcParty } from './Builder';
import { HasContractInfo, HasOfferCollateral, HasType } from './OptionInfo';
export interface CsoInfo {
    normalizedMaxGain: Value;
    normalizedMaxLoss: Value;
    maxGainForContractSize: Value;
    maxLossForContractSize: Value;
    minPayout: bigint;
    maxPayout: bigint;
    contractSize: Value;
    offerCollateral: Value;
    totalCollateral: Value;
    expiry: Date;
}
export interface CsoInfoParams {
    normalizedMaxGain: Value;
    normalizedMaxLoss: Value;
    maxGainForContractSize: Value;
    maxLossForContractSize: Value;
    offerCollateral: Value;
}
export type MaybeHasPositionInfo = {
    positionInfo?: OrderPositionInfo;
};
/**
 * getCsoInfoParamsFromContractInfo V0
 *
 * Old getCsoInfoParamsFromContractInfo implementation
 *
 * @param {Value} contractSize - The size of the contract in terms of value.
 * @param {Value} collateral - The collateral value put up for the contract.
 * @param {DlcParty} shiftForFees - Specifies which party ('offeror' or 'acceptor') will bear the fees, affecting the outcome values.
 * @param {Value} fees - The fees associated with the contract.
 * @param {string} unit - The unit of measurement for the contract outcomes (e.g., 'BTC').
 * @param {Value} startOutcomeValue - The starting outcome value for the contract.
 * @param {Value} endOutcomeValue - The ending outcome value for the contract.
 * @returns {CsoInfoParams} An object containing the calculated CSO parameters:
 *                          - normalizedMaxGain: Maximum gain relative to a 1 BTC contract.
 *                          - normalizedMaxLoss: Maximum loss relative to a 1 BTC contract.
 *                          - maxGainForContractSize: Maximum gain for the actual contract size.
 *                          - maxLossForContractSize: Maximum loss for the actual contract size.
 *                          - offerCollateral: The offer collateral value after adjustments.
 *
 * Note: This function calculates the adjusted fees incorrectly, using collateral instead of contract size. Use v1 where possible.
 */
export declare const getCsoInfoParamsFromContractInfoV0: (contractSize: Value, collateral: Value, shiftForFees: DlcParty, fees: Value, unit: string, startOutcomeValue: Value, endOutcomeValue: Value) => CsoInfoParams;
/**
 * getCsoInfoParamsFromContractInfo V1
 *
 * Fixed getCsoInfoParamsFromContractInfo implementation
 *
 * @param {Value} contractSize - The size of the contract in terms of value.
 * @param {Value} collateral - The collateral value put up for the contract.
 * @param {DlcParty} shiftForFees - Specifies which party ('offeror' or 'acceptor') will bear the fees, affecting the outcome values.
 * @param {Value} fees - The fees associated with the contract.
 * @param {string} unit - The unit of measurement for the contract outcomes (e.g., 'BTC').
 * @param {Value} startOutcomeValue - The starting outcome value for the contract.
 * @param {Value} endOutcomeValue - The ending outcome value for the contract.
 * @returns {CsoInfoParams} An object containing the calculated CSO parameters:
 *                          - normalizedMaxGain: Maximum gain relative to a 1 BTC contract.
 *                          - normalizedMaxLoss: Maximum loss relative to a 1 BTC contract.
 *                          - maxGainForContractSize: Maximum gain for the actual contract size.
 *                          - maxLossForContractSize: Maximum loss for the actual contract size.
 *                          - offerCollateral: The offer collateral value after adjustments.
 *
 * This version improves upon the previous by correctly adjusting fees based on the contract size, leading to more accurate
 * calculations of CSO parameters.
 */
export declare const getCsoInfoParamsFromContractInfoV1: (contractSize: Value, collateral: Value, shiftForFees: DlcParty, fees: Value, unit: string, startOutcomeValue: Value, endOutcomeValue: Value) => CsoInfoParams;
/**
 * Decode CsoInfo from a ContractInfo object. Essentially the opposite of buildCustomStrategyOrderOffer
 *
 * @param {_contractInfo} ContractInfo - Contract Info object, containing oracle and descriptor info
 * @param {DlcParty} shiftForFees - Specifies which party ('offeror', 'acceptor', or 'neither') will pay for network fees
 * @param {Value} fees - Network fees associated with the contract. Defaults to 0 sats.
 * @param {_contractSize} Value - Optional.  If not provided, it defaults to the total collateral.
 * @param {csoVersion} 'v0' | 'v1' - Specifies the version of the CSO parameter calculation to use. Defaults to 'v1'.
 * @returns {CsoInfo} An object containing the calculated CSO information:
 *                    - normalizedMaxGain: Maximum gain relative to a 1 BTC contract.
 *                    - normalizedMaxLoss: Maximum loss relative to a 1 BTC contract.
 *                    - maxGainForContractSize: Maximum gain for the actual contract size.
 *                    - maxLossForContractSize: Maximum loss for the actual contract size.
 *                    - minPayout: Minimum payout as determined by the contract's payout function.
 *                    - maxPayout: Maximum payout as determined by the contract's payout function.
 *                    - contractSize: The size of the contract in terms of value.
 *                    - offerCollateral: The offer collateral value after adjustments.
 *                    - totalCollateral: The total collateral put up for the contract.
 *                    - expiry: The expiry date of the contract based on the oracle's event maturity epoch.
 *
 * Note: This function performs several validations to ensure that the contract information and its components are of the
 * expected types and formats.
 *       It throws errors if unsupported types or formats are encountered.
 */
export declare const getCsoInfoFromContractInfo: (_contractInfo: ContractInfo, shiftForFees?: DlcParty, fees?: Value, _contractSize?: Value, csoVersion?: 'v0' | 'v1') => CsoInfo;
/**
 * Get CsoInfo from OrderOffer or DlcOffer and validate
 *
 * @param {HasContractInfo & HasType} offer
 * @returns {CsoInfo}
 */
export declare const getCsoInfoFromOffer: (offer: HasContractInfo & HasType & HasOfferCollateral & MaybeHasPositionInfo, csoVersion?: 'v0' | 'v1') => CsoInfo;
/**
 * Validate Payout Function for proper CSO format
 *
 * It should have 3 PayoutCurvePieces which consist of a flat line (maxLoss),
 * ascending line (maxLoss to maxGain) and finally another flat line (maxGain)
 *
 * All PayoutCurvePieces should be type PolynomialPayoutCurvePieces
 *
 * @param {PayoutFunction} payoutFunction
 */
export declare const validateCsoPayoutFunction: (payoutFunction: PayoutFunction) => void;