eulith-web3js-core
Version:
Eulith core web3js SDK (code to access Eulith services via web3js)
343 lines (342 loc) • 15.5 kB
TypeScript
import { RequestArguments } from "web3-core";
import * as Eulith from "../src/index";
import { IUniswapV3Pool } from "../known_contracts_typings";
/**
* The Uniswap module wraps access to a bunch of UNISWAP APIs (which are mediated by control
* structures within the Eulith Toolkit), as well as raw direct access to UNISWAP APIs.
*/
export declare module Uniswap {
/**
* Uniswap.V3 wraps the V3 version of the Uniswap API
*/
module V3 {
/**
* @typedef Eulith.Uniswap.V3.PoolFee / @typedef Eulith.Uniswap.PoolFee
*
* Uniswap pools are organized by Fee, and have 3 categories of fee.
*
* Fee's are applied to swaps as rate * sellAmount (in units of the sell token).
*
* Selecting a fee is an advanced topic - for experts; obviously buyers want
* the lowest fee possible, but depending on the size of the pool, you may see lower liquidity
* on the lower feed pools, and so worse pricing.
*
* When in doubt, use Eulith.Uniswap.getBestPriceQuote.
*
* Historical Notes: Based on class UniswapV3PoolFee(int, Enum):
*/
enum PoolFee {
FiveBips = 500,
ThirtyBips = 3000,
OneHundredBips = 10000
}
/**
* @typedef Eulith.Uniswap.V3.LoanRequest / @typedef Eulith.Uniswap.LoanRequest
*
* A LoanRequest implements IFlashLoanable - so its designed to work with the 'Flash' mechanism, to create
* instant, temporary liquidity.
*
* In the context of Uniswap, this just means using Uniswap pools to create that instant, temporary liquidity.
*
* This object rquires a borrowTokenA (and borrowAmountA), and an optional borrowTokenB (and borrowAmountB).
*
* payTransferFrom designates who PAYS the loan or sell side of the swap.
*
* @todo better explain this - but wait til I review the Flash code...
*/
class LoanRequest implements Eulith.FlashLiquidity.IFlashLoanable {
borrowTokenA: Eulith.Contracts.ERC20TokenContract;
borrowAmountA: number;
borrowTokenB?: Eulith.Contracts.ERC20TokenContract;
borrowAmountB?: number;
payTransferFrom?: string;
recipient?: string;
/**
* @constructor
*/
constructor(p: Partial<LoanRequest>);
generateLoanRequest(): RequestArguments;
get tokenValues(): Eulith.Tokens.Value.ITokenValue[];
}
/**
* @typedef Eulith.Uniswap.V3.SwapRequest / @typedef Eulith.Uniswap.SwapRequest
*
* This class is may generally be thought of as opaque, and is generally not used directly.
*
* Instead, these 'swap requests' are generally created by
* Eulith.Uniswap.Pool instance method getQuote OR
* Eulith.Uniswap.getBestPriceQuote, which both produce a Eulith.Uniswap.PriceQuote (which aggregates this object in the swapRequest member).
*
* This is then typically USED via a call to Eulith.Uniswap.startSwap()
*
* Historical Note: Based on python class EulithUniV3StartSwapRequest(TypedDict):
*/
class SwapRequest {
sellToken: Eulith.Contracts.ERC20TokenContract;
sellAmount: number;
poolAddress: string;
fillOrKill: boolean;
sqrtLimitPrice: string;
recipient?: string;
payTransferFrom?: string;
/**
* @constructor
*/
constructor(p: Partial<SwapRequest>);
}
/**
* @typedef Eulith.Uniswap.V3.PriceQuote / @typedef Eulith.Uniswap.PriceQuote
*
* Eulith.Uniswap.PriceQuote is generally not created directly, but as a result of calls
* to Eulith.Uniswap.getBestPriceQuote, or 'a uniswap pool'.getQuote
*/
class PriceQuote {
private feePct_;
/**
* @constructor
*/
constructor(p?: Partial<PriceQuote>);
/**
* The price is in units of of the 'sellToken' - used to create the quote.
*/
price: number;
/**
* This is the request object passed along to the Eulith.Uniswap.startSwap API.
*/
swapRequest: SwapRequest;
/**
* The fee is in units of of the 'sellToken', and a percent of the swapRequest.sellAmount - used to create the quote.
*/
get feeAmt(): Eulith.Tokens.Value.ITokenValue;
/**
* The fee is in units of of the 'sellToken', and a percent of the swapRequest.sellAmount - used to create the quote.
*/
get feePct(): number;
}
/**
* @typedef Eulith.Uniswap.Pool / @typedef Eulith.Uniswap.V3.Pool
*
* A UNISWAP pool contains exactly two different token contracts, and allows the user
* to exchange currency in one, for the other.
*
* This cannot be constructed directly, but rather by Eulith.Uniswap.getSwapPool ()
*
* HISTORICAL NOTE: BASED ON PYTHON EulithUniswapV3Pool
*/
class Pool {
private web3;
private poolAddress;
private fee_?;
private token0_;
private token1_;
private contract_;
private logger_;
private constructor();
/**
* @constructor
*/
static AsyncConstructor({ provider, poolAddress, fee, token0Address, token1Address }: {
provider: Eulith.Web3 | Eulith.Provider;
poolAddress: string;
fee?: PoolFee;
token0Address?: string;
token1Address?: string;
}): Promise<Pool>;
/**
* This return the fee (percentage) associated with this pool - Eulith.Uniswap.PoolFee
*
* This number is used to derive the actual fee that appears in specific quotes.
*
* There is an enumeration of possible fees.
*/
get fee(): PoolFee;
/**
* pool.contract returns the web3js native IUniswapV3Pool contract interface, with typescript typings for that interface.
*
* This extension point allows for calling of any of the IUniswapV3Pool apis, via the standard web3js contract syntax
*/
get contract(): IUniswapV3Pool;
/**
* @todo consider redoing this as 'tokens' - a set.
*/
get token0(): Eulith.Contracts.ERC20TokenContract;
/**
* @todo consider redoing this as 'tokens' - a set.
*/
get token1(): Eulith.Contracts.ERC20TokenContract;
/**
* Given a uniswap pool, request a quote for the given sellToken and amount.
*
* @param payTransferFrom is not truely used in forming the 'quote'. But the getQuote method returns both the amount of money
* it will cost, and an object - the swapRequest object. This requires the payTransferFrom to be embedded in it, and must
* contain the 'source account' the sellToken will be transfering funds from, if that differs from the sender of the actual
* request.
*
* @param fillOrKill -- either fill the whole order, or kill it. Don't allow partial fills
* (i.e. if you requested to sell 10 WETH @ $1,700 per, but we can only fill 5 at that price, kill the order.
*
* @param recipient -- the opposite of payTransferFrom. Designates who gets the bought or loaned
* (in this case bought) funds. Defaults to the calling wallet or authorized address of the toolkit contract.
*
* Example Usage:
*
* ```javascript
* const swapPool = await Eulith.Uniswap.getSwapPool({
* request: {
* tokenContracts: [usdcContract, wethContract],
* fee: Eulith.Uniswap.PoolFee.ThirtyBips,
* },
* provider
* });
* const quote = await swapPool.getQuote({ sellToken: usdcContract, sellAmount: sellAmount, payTransferFrom: acct.address });
* ```
*
* HISTORICAL NOTE: Based on Python EulithUniswapV3Pool.get_quote
*/
getQuote({ sellToken, sellAmount, fillOrKill, recipient, payTransferFrom }: {
sellToken: Eulith.Contracts.ERC20TokenContract;
sellAmount: number;
fillOrKill?: boolean;
recipient?: string;
payTransferFrom?: string;
}): Promise<PriceQuote>;
}
/**
* Eulith.Uniswap.getBestPriceQuote / Eulith.Uniswap.V3.getBestPriceQuote
*
* Return the best available price (object Eulith.Uniswap.PriceQuote) which contains
* the price, the fee, and actual swapRequest to use to perform this operation.
*
* Example Usage:
*
* ```javascript
* const quote = await Eulith.Uniswap.getBestPriceQuote({
* swapQuoteRequest: { sellToken: tokenA, buyToken: tokenB, amount: sellAmount },
* payTransferFrom: acct.address,
* provider
* });
* ```
*
* Timing note - if the price changes materially from when the quote happens, to when the actual transaction happens, the
* actual transaction may fail (@todo details here might be interesting)
*
* For info about the @param swapQuoteRequest.fee argument - see Eulith.Uniswap.PoolFee, but mostly - recommended callers ignore/omit.
*
* The @param payTransferFrom is used to specify the account that will be charged for the sellAmount on the sellToken contract. If
* not specified, the sender will be used by the sellToken contract.
*
* @param fillOrKill -- either fill the whole order, or kill it. Don't allow partial fills
* (i.e. if you requested to sell 10 WETH @ $1,700 per, but we can only fill 5 at that price, kill the order.
*
* @param recipient -- the opposite of payTransferFrom. Designates who gets the bought or loaned
* (in this case bought) funds. Defaults to the calling wallet or authorized address of the toolkit contract.
*
* Historical Note: Based on Python get_univ3_best_price_quote API
*/
function getBestPriceQuote({ swapQuoteRequest, fillOrKill, recipient, payTransferFrom, provider }: {
swapQuoteRequest: {
sellToken: Eulith.Contracts.ERC20TokenContract;
buyToken: Eulith.Contracts.ERC20TokenContract;
amount: number;
trueForAmountIn?: boolean;
fee?: PoolFee;
};
fillOrKill?: boolean;
recipient?: string;
payTransferFrom?: string;
provider: Eulith.Provider;
}): Promise<PriceQuote>;
/**
* Eulith.Uniswap.V3.startSwap / Eulith.Uniswap.startSwap
*
* Example Usage:
*
* ```javascript
* const swapAtomicTx: Eulith.AtomicTx.NestedTransaction = await Eulith.Uniswap.startSwap({ request: quote.swapRequest, parentTx: atomicTx })
* await swapAtomicTx.commit();
* ```
*
* \note mark this object as 'completed' calling swapAtomicTx.commit()
* \req parentTx != null
*
* Historical Note: Analogous to Python start_uniswap_v3_swap or start_uni_swap
*/
function startSwap({ request, parentTx }: {
request: SwapRequest;
parentTx: Eulith.AtomicTx.NestedTransaction | Eulith.AtomicTx.Transaction;
}): Promise<Eulith.AtomicTx.NestedTransaction>;
/**
* Eulith.Uniswap.getSwapPool / Eulith.Uniswap.V3.getSwapPool
*
* A UNISWAP pool contains exactly two different token Contracts, and allows the user
* to exchange currency in one, for the other. Each pool also has exactly one fee associated (as a percent of exchange amount).
*
* getSwapPool fetches the UNISWAP pool which contains both these two argument Contracts.
*
* NOTE - the order of the request.tokenContracts is meaningless (not using Set only because JS makes this syntactically more awkward)
*
* The fee is a required parameter for looking up a pool - see Eulith.Uniswap.PoolFee for details.
* If you don't know what fee to use, don't use getSwapPool, but use Eulith.Uniswap.getBestPriceQuote instead
*
* Note that the returned Eulith.Uniswap.Pool object can generally be used directly (as the examples below),
* but also can be used to access the underlying contract: IUniswapV3Pool accessor.
*
* Example Usage:
*
* ```javascript
* const swapPool = await Eulith.Uniswap.getSwapPool({
* request: {
* tokenContracts: [usdcContract, wethContract],
* fee: Eulith.Uniswap.PoolFee.ThirtyBips,
* },
* provider
* });
* const quote = await swapPool.getQuote({ sellToken: usdcContract, sellAmount: sellAmount, payTransferFrom: acct.address });
* ```
*/
function getSwapPool({ request, provider }: {
request: {
tokenContracts?: Eulith.Contracts.ERC20TokenContract[];
fee: PoolFee;
};
provider: Eulith.Provider | Eulith.Web3;
}): Promise<Pool>;
}
/**
* Eulith.Uniswap.PoolFee: see Eulith.Uniswap.V3.PoolFee
*/
const PoolFee: typeof V3.PoolFee;
type PoolFee = V3.PoolFee;
/**
* Eulith.Uniswap.Pool: see Eulith.Uniswap.V3.Pool
*/
const Pool: typeof V3.Pool;
type Pool = V3.Pool;
/**
* Eulith.Uniswap.PriceQuote: See Eulith.Uniswap.V3.PriceQuote
*/
const PriceQuote: typeof V3.PriceQuote;
type PriceQuote = V3.PriceQuote;
/**
* Eulith.Uniswap.LoanRequest: see Eulith.Uniswap.V3.LoanRequest
*/
const LoanRequest: typeof V3.LoanRequest;
type LoanRequest = V3.LoanRequest;
/**
* Eulith.Uniswap.SwapRequest: see Eulith.Uniswap.V3.SwapRequest
*/
const SwapRequest: typeof V3.SwapRequest;
type SwapRequest = V3.SwapRequest;
/**
* Eulith.Uniswap.getBestPriceQuote: see Eulith.Uniswap.V3.getBestPriceQuote
*/
const getBestPriceQuote: typeof V3.getBestPriceQuote;
/**
* Eulith.Uniswap.getSwapPool: see Eulith.Uniswap.V3.getSwapPool
*/
const getSwapPool: typeof V3.getSwapPool;
/**
* Eulith.Uniswap.startSwap: see Eulith.Uniswap.V3.startSwap
*/
const startSwap: typeof V3.startSwap;
}