From a13c33e9c99e439b8e22118e54f1961ee6da3d85 Mon Sep 17 00:00:00 2001 From: Calvin Koepke Date: Mon, 10 Jun 2024 14:43:33 -0600 Subject: [PATCH] chore: docs --- .../core/classes/Lucid.TxBuilderLucidV1.md | 40 +++++- .../core/classes/Lucid.TxBuilderLucidV3.md | 44 +++++- .../interfaces/Core.IOrderRouteSwapArgs.md | 6 + docs/typescript/core/modules/Core.md | 1 + packages/core/src/@types/txbuilders.ts | 4 + .../TxBuilders/TxBuilder.Lucid.V1.class.ts | 20 ++- .../TxBuilders/TxBuilder.Lucid.V3.class.ts | 126 ++---------------- 7 files changed, 108 insertions(+), 133 deletions(-) create mode 100644 docs/typescript/core/interfaces/Core.IOrderRouteSwapArgs.md diff --git a/docs/typescript/core/classes/Lucid.TxBuilderLucidV1.md b/docs/typescript/core/classes/Lucid.TxBuilderLucidV1.md index a752631c..284c370f 100644 --- a/docs/typescript/core/classes/Lucid.TxBuilderLucidV1.md +++ b/docs/typescript/core/classes/Lucid.TxBuilderLucidV1.md @@ -137,7 +137,7 @@ TxBuilder.cancel #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:444](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L444) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:454](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L454) ___ @@ -244,7 +244,7 @@ const migrationResult = await sdk.builder().migrateLiquidityToV3([ #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:907](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L907) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:917](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L917) ___ @@ -274,6 +274,36 @@ Returns a new Tx instance from Lucid. Throws an error if not ready. ___ +### orderRouteSwap + +▸ **orderRouteSwap**(`args`): `Promise`\<[`IComposedTx`](../interfaces/Core.IComposedTx.md)\<`Tx`, `TxComplete`, `undefined` \| `string`, `Record`\<`string`, `AssetAmount`\<`IAssetAmountMetadata`\>\>\>\> + +Performs an order route swap with the given arguments. + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `args` | [`IOrderRouteSwapArgs`](../interfaces/Core.IOrderRouteSwapArgs.md) | The arguments for the order route swap. | + +#### Returns + +`Promise`\<[`IComposedTx`](../interfaces/Core.IComposedTx.md)\<`Tx`, `TxComplete`, `undefined` \| `string`, `Record`\<`string`, `AssetAmount`\<`IAssetAmountMetadata`\>\>\>\> + +The result of the transaction. + +**`Async`** + +#### Overrides + +TxBuilder.orderRouteSwap + +#### Defined in + +[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:307](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L307) + +___ + ### swap ▸ **swap**(`swapArgs`): `Promise`\<[`IComposedTx`](../interfaces/Core.IComposedTx.md)\<`Tx`, `TxComplete`, `undefined` \| `string`, `Record`\<`string`, `AssetAmount`\<`IAssetAmountMetadata`\>\>\>\> @@ -363,7 +393,7 @@ TxBuilder.update #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:547](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L547) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:557](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L557) ___ @@ -405,7 +435,7 @@ TxBuilder.withdraw #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:687](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L687) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:697](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L697) ___ @@ -447,7 +477,7 @@ TxBuilder.zap #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:739](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L739) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts:749](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts#L749) ___ diff --git a/docs/typescript/core/classes/Lucid.TxBuilderLucidV3.md b/docs/typescript/core/classes/Lucid.TxBuilderLucidV3.md index 22358052..52edc6d1 100644 --- a/docs/typescript/core/classes/Lucid.TxBuilderLucidV3.md +++ b/docs/typescript/core/classes/Lucid.TxBuilderLucidV3.md @@ -96,7 +96,7 @@ TxBuilder.cancel #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:826](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L826) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:720](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L720) ___ @@ -126,7 +126,7 @@ TxBuilder.deposit #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:994](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L994) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:888](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L888) ___ @@ -151,7 +151,7 @@ The generated Bech32 address. #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:1225](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L1225) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:1119](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L1119) ___ @@ -273,7 +273,7 @@ Throws an error if the retrieval of UTXOs fails or if no UTXOs are available. #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:1268](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L1268) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:1162](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L1162) ___ @@ -358,6 +358,36 @@ fee payment if a [ITxBuilderReferralFee](../interfaces/Core.ITxBuilderReferralFe ___ +### orderRouteSwap + +▸ **orderRouteSwap**(`args`): `Promise`\<[`IComposedTx`](../interfaces/Core.IComposedTx.md)\<`Tx`, `TxComplete`, `undefined` \| `string`, `Record`\<`string`, `AssetAmount`\<`IAssetAmountMetadata`\>\>\>\> + +Performs an order route swap with the given arguments. + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `args` | [`IOrderRouteSwapArgs`](../interfaces/Core.IOrderRouteSwapArgs.md) | The arguments for the order route swap. | + +#### Returns + +`Promise`\<[`IComposedTx`](../interfaces/Core.IComposedTx.md)\<`Tx`, `TxComplete`, `undefined` \| `string`, `Record`\<`string`, `AssetAmount`\<`IAssetAmountMetadata`\>\>\>\> + +The result of the transaction. + +**`Async`** + +#### Overrides + +TxBuilder.orderRouteSwap + +#### Defined in + +[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:579](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L579) + +___ + ### swap ▸ **swap**(`swapArgs`): `Promise`\<[`IComposedTx`](../interfaces/Core.IComposedTx.md)\<`Tx`, `TxComplete`, `undefined` \| `string`, `Record`\<`string`, `AssetAmount`\<`IAssetAmountMetadata`\>\>\>\> @@ -416,7 +446,7 @@ TxBuilder.update #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:908](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L908) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:802](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L802) ___ @@ -446,7 +476,7 @@ TxBuilder.withdraw #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:1042](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L1042) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:936](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L936) ___ @@ -476,4 +506,4 @@ TxBuilder.zap #### Defined in -[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:1087](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L1087) +[packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts:981](https://github.com/SundaeSwap-finance/sundae-sdk/blob/main/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts#L981) diff --git a/docs/typescript/core/interfaces/Core.IOrderRouteSwapArgs.md b/docs/typescript/core/interfaces/Core.IOrderRouteSwapArgs.md new file mode 100644 index 00000000..7baa487c --- /dev/null +++ b/docs/typescript/core/interfaces/Core.IOrderRouteSwapArgs.md @@ -0,0 +1,6 @@ +# Interface: IOrderRouteSwapArgs + +[Core](../modules/Core.md).IOrderRouteSwapArgs + +Special arguments for an Order-Route Swap. A combination of +two swap arguments, but simplified for ease-of-use. diff --git a/docs/typescript/core/modules/Core.md b/docs/typescript/core/modules/Core.md index b05bf940..d1d16628 100644 --- a/docs/typescript/core/modules/Core.md +++ b/docs/typescript/core/modules/Core.md @@ -37,6 +37,7 @@ - [IMigrateYieldFarmingLiquidityConfig](../interfaces/Core.IMigrateYieldFarmingLiquidityConfig.md) - [IMintV3PoolConfigArgs](../interfaces/Core.IMintV3PoolConfigArgs.md) - [IOrderConfigArgs](../interfaces/Core.IOrderConfigArgs.md) +- [IOrderRouteSwapArgs](../interfaces/Core.IOrderRouteSwapArgs.md) - [IPoolByIdentQuery](../interfaces/Core.IPoolByIdentQuery.md) - [IPoolByPairQuery](../interfaces/Core.IPoolByPairQuery.md) - [IPoolData](../interfaces/Core.IPoolData.md) diff --git a/packages/core/src/@types/txbuilders.ts b/packages/core/src/@types/txbuilders.ts index 8fc9e5a7..e7ffba31 100644 --- a/packages/core/src/@types/txbuilders.ts +++ b/packages/core/src/@types/txbuilders.ts @@ -83,6 +83,10 @@ export enum EContractVersion { V3 = "V3", } +/** + * Special arguments for an Order-Route Swap. A combination of + * two swap arguments, but simplified for ease-of-use. + */ export interface IOrderRouteSwapArgs { ownerAddress: string; swapA: Omit; diff --git a/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts b/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts index d34dff54..f1b1ffcd 100644 --- a/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts +++ b/packages/core/src/TxBuilders/TxBuilder.Lucid.V1.class.ts @@ -219,7 +219,7 @@ export class TxBuilderLucidV1 extends TxBuilder { * and completes the transaction by paying to the contract and finalizing the transaction details. * * @param {ISwapConfigArgs} swapArgs - The configuration arguments for the swap. - * @returns {Promise} A promise that resolves to the result of the completed transaction. + * @returns {Promise>} A promise that resolves to the result of the completed transaction. * * @async * @example @@ -231,7 +231,7 @@ export class TxBuilderLucidV1 extends TxBuilder { * .then(({ submit }) => submit()) * ``` */ - async swap(swapArgs: ISwapConfigArgs) { + async swap(swapArgs: ISwapConfigArgs): Promise> { const config = new SwapConfig(swapArgs); const { @@ -296,7 +296,17 @@ export class TxBuilderLucidV1 extends TxBuilder { }); } - async orderRouteSwap(args: IOrderRouteSwapArgs) { + /** + * Performs an order route swap with the given arguments. + * + * @async + * @param {IOrderRouteSwapArgs} args - The arguments for the order route swap. + * + * @returns {Promise>} The result of the transaction. + */ + async orderRouteSwap( + args: IOrderRouteSwapArgs + ): Promise> { const isSecondSwapV3 = args.swapB.pool.version === EContractVersion.V3; const secondSwapBuilder = isSecondSwapV3 @@ -429,7 +439,7 @@ export class TxBuilderLucidV1 extends TxBuilder { * sets up the transaction, and completes it. * * @param {ICancelConfigArgs} cancelArgs - The configuration arguments for the cancel transaction. - * @returns {Promise} A promise that resolves to the result of the cancel transaction. + * @returns {Promise>} A promise that resolves to the result of the cancel transaction. * * @async * @example @@ -526,7 +536,7 @@ export class TxBuilderLucidV1 extends TxBuilder { * * @param {{ cancelArgs: ICancelConfigArgs, swapArgs: ISwapConfigArgs }} * The arguments for cancel and swap configurations. - * @returns {Promise} A promise that resolves to the result of the updated transaction. + * @returns {Promise>} A promise that resolves to the result of the updated transaction. * * @throws * @async diff --git a/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts b/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts index 9730e0c8..23df7efd 100644 --- a/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts +++ b/packages/core/src/TxBuilders/TxBuilder.Lucid.V3.class.ts @@ -569,7 +569,16 @@ export class TxBuilderLucidV3 extends TxBuilder { }); } - async orderRouteSwap(args: IOrderRouteSwapArgs) { + /** + * Performs an order route swap with the given arguments. + * + * @async + * @param {IOrderRouteSwapArgs} args - The arguments for the order route swap. + * @returns {Promise>} The result of the transaction. + */ + async orderRouteSwap( + args: IOrderRouteSwapArgs + ): Promise> { const isSecondSwapV1 = args.swapB.pool.version === EContractVersion.V1; const secondSwapBuilder = isSecondSwapV1 @@ -698,121 +707,6 @@ export class TxBuilderLucidV3 extends TxBuilder { referralFee: mergedReferralFee?.payment, scooperFee: fees.scooperFee.add(secondSwapData.fees.scooperFee).amount, }); - - // const swapA = new SwapConfig(args.swapA).buildArgs(); - - // const [aReserve, bReserve] = SundaeUtils.sortSwapAssetsWithAmounts([ - // new AssetAmount( - // args.swapA.pool.liquidity.aReserve, - // args.swapA.pool.assetA - // ), - // new AssetAmount( - // args.swapA.pool.liquidity.bReserve, - // args.swapA.pool.assetB - // ), - // ]); - - // const aOutputAsset = - // swapA.suppliedAsset.metadata.assetId === aReserve.metadata.assetId - // ? bReserve.withAmount(swapA.minReceivable.amount) - // : aReserve.withAmount(swapA.minReceivable.amount); - - // const swapB = new SwapConfig({ - // ...args.swapB, - // suppliedAsset: aOutputAsset, - // }).buildArgs(); - - // const isSecondSwapV1 = swapB.pool.version === EContractVersion.V1; - - // const secondSwapBuilder = isSecondSwapV1 - // ? new TxBuilderLucidV1(this.lucid, new DatumBuilderLucidV1(this.network)) - // : this; - // const secondSwapAddress = isSecondSwapV1 - // ? await secondSwapBuilder - // .getValidatorScript("escrow.spend") - // .then(({ compiledCode }) => - // this.lucid.utils.validatorToAddress({ - // type: "PlutusV1", - // script: compiledCode, - // }) - // ) - // : await (secondSwapBuilder as TxBuilderLucidV3).generateScriptAddress( - // "order.spend", - // args.swapA.ownerAddress ?? - // swapA.orderAddresses.DestinationAddress.address - // ); - - // const secondSwapData = await secondSwapBuilder.swap({ - // ...swapB, - // swapType: args.swapB.swapType, - // }); - - // let referralFeeAmount = 0n; - // if (swapA.referralFee) { - // referralFeeAmount += swapA.referralFee.payment.amount; - // } - - // if (swapB.referralFee) { - // referralFeeAmount += swapB.referralFee.payment.amount; - // } - - // let mergedReferralFee: ITxBuilderReferralFee | undefined; - // if (swapA.referralFee) { - // mergedReferralFee = { - // ...swapA.referralFee, - // payment: swapA.referralFee.payment.withAmount(referralFeeAmount), - // }; - // } else if (swapB.referralFee) { - // mergedReferralFee = { - // ...swapB.referralFee, - // payment: swapB.referralFee.payment.withAmount(referralFeeAmount), - // }; - // } - - // const datumHash = this.lucid.utils.datumToHash( - // secondSwapData.datum as string - // ); - - // const { tx, datum, fees } = await this.swap({ - // ...swapA, - // swapType: { - // type: ESwapType.LIMIT, - // minReceivable: swapA.minReceivable, - // }, - // orderAddresses: { - // ...swapB.orderAddresses, - // DestinationAddress: { - // address: secondSwapAddress, - // datum: { - // type: isSecondSwapV1 ? EDatumType.HASH : EDatumType.INLINE, - // value: isSecondSwapV1 - // ? datumHash - // : (secondSwapData.datum as string), - // }, - // }, - // AlternateAddress: - // args.swapA.ownerAddress ?? - // swapB.orderAddresses.DestinationAddress.address, - // }, - // referralFee: mergedReferralFee, - // }); - - // if (isSecondSwapV1) { - // tx.attachMetadataWithConversion(103251, { - // [`0x${datumHash}`]: SundaeUtils.splitMetadataString( - // secondSwapData.datum as string, - // "0x" - // ), - // }); - // } - - // return this.completeTx({ - // tx, - // datum, - // deposit: ORDER_DEPOSIT_DEFAULT, - // referralFee: mergedReferralFee?.payment, - // scooperFee: fees.scooperFee.add(secondSwapData.fees.scooperFee).amount, - // }); } /**