@txnlab/deflex 1.1.0 → 1.3.0

package/README.md

@@ -1,5 +1,11 @@
 # Deflex SDK
 
+[![npm version](https://img.shields.io/npm/v/@txnlab/deflex.svg)](https://www.npmjs.com/package/@txnlab/deflex)
+[![bundle size](https://deno.bundlejs.com/badge?q=@txnlab/deflex@latest&treeshake=[*])](https://bundlejs.com/?q=%40txnlab%2Fdeflex%40latest&treeshake=%5B*%5D)
+[![CI](https://github.com/TxnLab/deflex-js/actions/workflows/ci.yml/badge.svg)](https://github.com/TxnLab/deflex-js/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+
 TypeScript/JavaScript SDK for [Deflex Order Router](https://txnlab.gitbook.io/deflex-api) - smart order routing and DEX aggregation on Algorand.
 
 ## Prerequisites
@@ -174,6 +180,7 @@ await swap.execute()
 ```
 
 The signer function supports two return patterns:
+
 - **Pattern 1** (Pera, Defly, algosdk): Returns only the signed transactions as `Uint8Array[]`
 - **Pattern 2** (Lute, ARC-1 compliant): Returns an array matching the transaction group length with `null` for unsigned transactions as `(Uint8Array | null)[]`
 
@@ -181,17 +188,25 @@ Both patterns are automatically handled by the SDK.
 
 ### Advanced Transaction Composition
 
-Build the transaction group by adding custom transactions before or after the swap using the [`SwapComposer`](#swapcomposer) instance:
+Build the transaction group by adding custom transactions and ABI method calls before or after the swap using the [`SwapComposer`](#swapcomposer) instance:
 
 ```typescript
-import { Transaction } from 'algosdk'
+import { ABIMethod, Transaction } from 'algosdk'
 import { useWallet } from '@txnlab/use-wallet-*' // react, vue, solid, or svelte
 
 const { activeAddress, transactionSigner } = useWallet()
 
 // Create your custom transactions
-const customTxn1 = new Transaction({...})
-const customTxn2 = new Transaction({...})
+const customTxn = new Transaction({...})
+
+// Define an ABI method call
+const methodCall = {
+  appID: 123456,
+  method: new ABIMethod({...}),
+  methodArgs: [...],
+  sender: activeAddress,
+  suggestedParams: await algodClient.getTransactionParams().do(),
+}
 
 // Build and execute the transaction group
 const swap = await deflex.newSwap({
@@ -202,12 +217,50 @@ const swap = await deflex.newSwap({
 })
 
 const result = await swap
-  .addTransaction(customTxn1)     // Add transaction before swap
+  .addTransaction(customTxn)      // Add transaction before swap
   .addSwapTransactions()          // Add swap transactions
-  .addTransaction(customTxn2)     // Add transaction after swap
+  .addMethodCall(methodCall)      // Add ABI method call after swap
   .execute()                      // Sign and execute entire group
 ```
 
+### Middleware for Custom Asset Requirements
+
+Some Algorand assets require additional transactions to be added to swap groups (e.g., assets with transfer restrictions, taxes, or custom smart contract logic). The Deflex SDK supports a middleware system that allows these special requirements to be handled by external packages without modifying the core SDK.
+
+Middleware can:
+- Adjust quote parameters (e.g., reduce `maxGroupSize` to account for extra transactions)
+- Add transactions before the swap (e.g., unfreeze account, setup calls)
+- Add transactions after the swap (e.g., tax payments, cleanup calls)
+
+```typescript
+import { DeflexClient } from '@txnlab/deflex'
+import { FirstStageMiddleware } from '@firststage/deflex-middleware' // Example external package
+
+// Initialize middleware
+const firstStage = new FirstStageMiddleware({
+  contractAppId: 123456,
+})
+
+// Pass middleware to DeflexClient
+const deflex = new DeflexClient({
+  apiKey: 'your-api-key',
+  middleware: [firstStage], // Middleware is applied automatically
+})
+
+// Use normally - middleware handles everything
+const quote = await deflex.newQuote({
+  fromASAID: 0,        // ALGO
+  toASAID: 789012,     // Custom asset (e.g., MOOJ, DEAL)
+  amount: 1_000_000,
+  address: userAddress,
+})
+
+const swap = await deflex.newSwap({ quote, address, signer, slippage: 1 })
+await swap.execute() // Middleware transactions are automatically included
+```
+
+For details on creating your own middleware, see [MIDDLEWARE.md](MIDDLEWARE.md).
+
 ### Manual Asset Opt-In Detection
 
 If you're not using `autoOptIn: true`, you can manually check if opt-in is needed:
@@ -269,16 +322,17 @@ The main client for interacting with the Deflex API.
 new DeflexClient(config: DeflexConfigParams)
 ```
 
-| Option            | Description                                                  | Type               | Default                                |
-| ----------------- | ------------------------------------------------------------ | ------------------ | -------------------------------------- |
-| `apiKey`          | Your Deflex API key                                          | `string`           | **required**                           |
-| `apiBaseUrl`      | Base URL for the Deflex API                                  | `string`           | `https://deflex.txnlab.dev`            |
-| `algodUri`        | Algod node URI                                               | `string`           | `https://mainnet-api.4160.nodely.dev/` |
-| `algodToken`      | Algod node token                                             | `string`           | `''`                                   |
-| `algodPort`       | Algod node port                                              | `string \| number` | `443`                                  |
-| `referrerAddress` | Referrer address for fee sharing (receives 25% of swap fees) | `string`           | `undefined`                            |
-| `feeBps`          | Fee in basis points (0.15%, max: 300 = 3.00%)                | `number`           | `15`                                   |
-| `autoOptIn`       | Auto-detect and add required opt-in transactions             | `boolean`          | `false`                                |
+| Option            | Description                                                  | Type                  | Default                                |
+| ----------------- | ------------------------------------------------------------ | --------------------- | -------------------------------------- |
+| `apiKey`          | Your Deflex API key                                          | `string`              | **required**                           |
+| `apiBaseUrl`      | Base URL for the Deflex API                                  | `string`              | `https://deflex.txnlab.dev`            |
+| `algodUri`        | Algod node URI                                               | `string`              | `https://mainnet-api.4160.nodely.dev/` |
+| `algodToken`      | Algod node token                                             | `string`              | `''`                                   |
+| `algodPort`       | Algod node port                                              | `string \| number`    | `443`                                  |
+| `referrerAddress` | Referrer address for fee sharing (receives 25% of swap fees) | `string`              | `undefined`                            |
+| `feeBps`          | Fee in basis points (0.15%, max: 300 = 3.00%)                | `number`              | `15`                                   |
+| `autoOptIn`       | Auto-detect and add required opt-in transactions             | `boolean`             | `false`                                |
+| `middleware`      | Array of middleware for custom asset requirements            | `SwapMiddleware[]`    | `[]`                                   |
 
 > **Referral Program**: By providing a `referrerAddress`, you can earn 25% of the swap fees generated through your integration. The `feeBps` parameter sets the total fee charged (default: 0.15%). Learn more about the [Deflex Referral Program](https://txnlab.gitbook.io/deflex-api/referral-treasury/referral-program).
 
@@ -310,11 +364,11 @@ Returns a [`SwapComposer`](#swapcomposer) instance for building and executing sw
 async newSwap(config: SwapComposerConfig): Promise<SwapComposer>
 ```
 
-| Parameter  | Description                                       | Type                                                                                                                                    |
-| ---------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `quote`    | Quote result or raw API response                  | `DeflexQuote \| FetchQuoteResponse`                                                                                                     |
-| `address`  | Signer address                                    | `string`                                                                                                                                |
-| `slippage` | Slippage tolerance as percentage (e.g., 1 for 1%) | `number`                                                                                                                                |
+| Parameter  | Description                                       | Type                                                                                                                   |
+| ---------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `quote`    | Quote result or raw API response                  | `DeflexQuote \| FetchQuoteResponse`                                                                                    |
+| `address`  | Signer address                                    | `string`                                                                                                               |
+| `slippage` | Slippage tolerance as percentage (e.g., 1 for 1%) | `number`                                                                                                               |
 | `signer`   | Transaction signer function                       | `algosdk.TransactionSigner \| ((txnGroup: Transaction[], indexesToSign: number[]) => Promise<(Uint8Array \| null)[]>)` |
 
 #### DeflexClient.needsAssetOptIn()
@@ -368,15 +422,17 @@ Plain object returned by [`newQuote()`](#deflexclientnewquote). Extends the raw
 
 Builder for constructing and executing atomic swap transaction groups, returned by [`newSwap()`](#deflexclientnewswap).
 
-| Method                        | Description                                                                    | Parameters                         | Returns                               |
-| ----------------------------- | ------------------------------------------------------------------------------ | ---------------------------------- | ------------------------------------- |
-| `addTransaction(transaction)` | Add a transaction to the atomic group                                          | `transaction: algosdk.Transaction` | `SwapComposer`                        |
-| `addSwapTransactions()`       | Add swap transactions to the group (includes required app opt-ins)             | None                               | `Promise<SwapComposer>`               |
-| `sign()`                      | Sign the transaction group                                                     | None                               | `Promise<Uint8Array[]>`               |
-| `submit()`                    | Sign and submit the transaction group                                          | None                               | `Promise<string[]>`                   |
-| `execute(waitRounds?)`        | Sign, submit, and wait for confirmation                                        | `waitRounds?: number` (default: 4) | `Promise<PendingTransactionResponse>` |
-| `getStatus()`                 | Get current status: `BUILDING`, `BUILT`, `SIGNED`, `SUBMITTED`, or `COMMITTED` | None                               | `ComposerStatus`                      |
-| `count()`                     | Get the number of transactions in the group                                    | None                               | `number`                              |
+| Method                                 | Description                                                                    | Parameters                                                     | Returns                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `addTransaction(transaction, signer?)` | Add a transaction to the atomic group                                          | `transaction: algosdk.Transaction, signer?: TransactionSigner` | `SwapComposer`                                                                     |
+| `addMethodCall(methodCall, signer?)`   | Add an ABI method call to the atomic group                                     | `methodCall: MethodCall, signer?: TransactionSigner`           | `SwapComposer`                                                                     |
+| `addSwapTransactions()`                | Add swap transactions to the group (includes required app opt-ins)             | None                                                           | `Promise<SwapComposer>`                                                            |
+| `buildGroup()`                         | Build the transaction group and assign group IDs                               | None                                                           | `TransactionWithSigner[]`                                                          |
+| `sign()`                               | Sign the transaction group                                                     | None                                                           | `Promise<Uint8Array[]>`                                                            |
+| `submit()`                             | Sign and submit the transaction group                                          | None                                                           | `Promise<string[]>` (transaction IDs)                                              |
+| `execute(waitRounds?)`                 | Sign, submit, and wait for confirmation                                        | `waitRounds?: number` (default: 4)                             | `Promise<{ confirmedRound: bigint, txIds: string[], methodResults: ABIResult[] }>` |
+| `getStatus()`                          | Get current status: `BUILDING`, `BUILT`, `SIGNED`, `SUBMITTED`, or `COMMITTED` | None                                                           | `SwapComposerStatus`                                                               |
+| `count()`                              | Get the number of transactions in the group                                    | None                                                           | `number`                                                                           |
 
 ## Documentation
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import algosdk, { Algodv2, Transaction, TransactionSigner } from "algosdk";
+import { ABIArgument, ABIMethod, ABIResult, Address, Algodv2, BoxReference, OnApplicationComplete, ResourceReference, SuggestedParams, Transaction, TransactionSigner, TransactionWithSigner } from "algosdk";
 
 //#region src/constants.d.ts
 /**
@@ -281,14 +281,270 @@ interface FetchSwapTxnsResponse {
 /**
  * Processed transaction with optional pre-signature
  *
+ * @deprecated This type is no longer used internally. Use algosdk.TransactionWithSigner instead.
  * @internal
  */
 interface SwapTransaction {
   /** The Algorand transaction */
-  readonly txn: algosdk.Transaction;
+  readonly txn: Transaction;
   /** Pre-signature from Deflex (if applicable) */
   readonly deflexSignature?: DeflexSignature;
 }
+/**
+ * Method call to be executed as part of the swap
+ */
+interface MethodCall {
+  /** The ID of the smart contract to call. Set this to 0 to indicate an application creation call. */
+  appID: number | bigint;
+  /** The method to call on the smart contract */
+  method: ABIMethod;
+  /** The arguments to include in the method call. If omitted, no arguments will be passed to the method. */
+  methodArgs?: ABIArgument[];
+  /** The address of the sender of this application call */
+  sender: string | Address;
+  /** Transactions params to use for this application call */
+  suggestedParams: SuggestedParams;
+  /** The OnComplete action to take for this application call. If omitted, OnApplicationComplete.NoOpOC will be used. */
+  onComplete?: OnApplicationComplete;
+  /** The approval program for this application call. Only set this if this is an application creation call, or if onComplete is OnApplicationComplete.UpdateApplicationOC */
+  approvalProgram?: Uint8Array;
+  /** The clear program for this application call. Only set this if this is an application creation call, or if onComplete is OnApplicationComplete.UpdateApplicationOC */
+  clearProgram?: Uint8Array;
+  /** The global integer schema size. Only set this if this is an application creation call. */
+  numGlobalInts?: number;
+  /** The global byte slice schema size. Only set this if this is an application creation call. */
+  numGlobalByteSlices?: number;
+  /** The local integer schema size. Only set this if this is an application creation call. */
+  numLocalInts?: number;
+  /** The local byte slice schema size. Only set this if this is an application creation call. */
+  numLocalByteSlices?: number;
+  /** The number of extra pages to allocate for the application's programs. Only set this if this is an application creation call. If omitted, defaults to 0. */
+  extraPages?: number;
+  /** Array of Address strings that represent external accounts supplied to this application. If accounts are provided here, the accounts specified in the method args will appear after these. */
+  appAccounts?: Array<string | Address>;
+  /** Array of App ID numbers that represent external apps supplied to this application. If apps are provided here, the apps specified in the method args will appear after these. */
+  appForeignApps?: Array<number | bigint>;
+  /** Array of Asset ID numbers that represent external assets supplied to this application. If assets are provided here, the assets specified in the method args will appear after these. */
+  appForeignAssets?: Array<number | bigint>;
+  /** The box references for this application call */
+  boxes?: BoxReference[];
+  /** The resource references for this application call */
+  access?: ResourceReference[];
+  /** The note value for this application call */
+  note?: Uint8Array;
+  /** The lease value for this application call */
+  lease?: Uint8Array;
+  /** If provided, the address that the sender will be rekeyed to at the conclusion of this application call */
+  rekeyTo?: string | Address;
+  /** The lowest application version for which this transaction should immediately fail. 0 indicates that no version check should be performed. */
+  rejectVersion?: number | bigint;
+  /** A transaction signer that can authorize this application call from sender */
+  signer?: TransactionSigner;
+}
+//#endregion
+//#region src/middleware.d.ts
+/**
+ * Context provided to middleware hooks during swap composition
+ */
+interface SwapContext {
+  /** The quote result from newQuote() */
+  readonly quote: DeflexQuote;
+  /** The address of the account performing the swap */
+  readonly address: string;
+  /** Algodv2 client instance for making additional queries/transactions */
+  readonly algodClient: Algodv2;
+  /** Suggested transaction parameters from the network */
+  readonly suggestedParams: SuggestedParams;
+  /** Input asset ID (always bigint for precision and future-proofing) */
+  readonly fromASAID: bigint;
+  /** Output asset ID (always bigint for precision and future-proofing) */
+  readonly toASAID: bigint;
+  /** Transaction signer for transactions that need to be signed by the user */
+  readonly signer: TransactionSigner;
+}
+/**
+ * Middleware interface for extending Deflex swap functionality
+ *
+ * Middleware allows you to modify quote parameters and inject additional transactions
+ * into the atomic swap group. This is useful for assets that require special handling,
+ * such as those with transfer restrictions, taxes, or custom smart contract logic.
+ *
+ * @example
+ * ```typescript
+ * class CustomAssetMiddleware implements SwapMiddleware {
+ *   readonly name = 'CustomAsset'
+ *   readonly version = '1.0.0'
+ *
+ *   async shouldApply(params) {
+ *     return params.fromASAID === CUSTOM_ASSET_ID || params.toASAID === CUSTOM_ASSET_ID
+ *   }
+ *
+ *   async adjustQuoteParams(params) {
+ *     // Reduce maxGroupSize to account for extra transactions
+ *     return { ...params, maxGroupSize: params.maxGroupSize - 3 }
+ *   }
+ *
+ *   async beforeSwap(context) {
+ *     // Return transactions to add before the swap
+ *     return [unfreezeTransaction]
+ *   }
+ *
+ *   async afterSwap(context) {
+ *     // Return transactions to add after the swap
+ *     return [taxTransaction, refreezeTransaction]
+ *   }
+ * }
+ * ```
+ */
+interface SwapMiddleware {
+  /** Unique identifier for the middleware */
+  readonly name: string;
+  /** Semantic version of the middleware */
+  readonly version: string;
+  /**
+   * Determines if this middleware should be applied to the given swap
+   *
+   * Called during both quote and swap phases. Use this to check if either
+   * the input or output asset requires special handling.
+   *
+   * @param params - Asset IDs being swapped
+   * @returns True if middleware should be applied
+   *
+   * @example
+   * ```typescript
+   * async shouldApply(params) {
+   *   // Check if asset is registered in our smart contract
+   *   const assetInfo = await this.getAssetInfo(params.fromASAID)
+   *   return assetInfo !== null
+   * }
+   * ```
+   */
+  shouldApply(params: {
+    fromASAID: bigint;
+    toASAID: bigint;
+  }): Promise<boolean>;
+  /**
+   * Modify quote parameters before fetching the quote
+   *
+   * **IMPORTANT**: If your middleware adds transactions via `beforeSwap` or `afterSwap`,
+   * you MUST reduce `maxGroupSize` accordingly to prevent failures. The Deflex API may
+   * return routes that use all 16 available transaction slots.
+   *
+   * Use this to adjust the quote request based on your asset's requirements.
+   * Common adjustments include:
+   * - Reducing `maxGroupSize` to account for additional transactions (REQUIRED if adding txns)
+   * - Adjusting `amount` to account for fees/taxes
+   * - Modifying `disabledProtocols` if certain DEXs are incompatible
+   *
+   * @param params - Original quote parameters
+   * @returns Modified quote parameters
+   *
+   * @example
+   * ```typescript
+   * async adjustQuoteParams(params) {
+   *   const [fromTaxed, toTaxed] = await Promise.all([
+   *     this.isAssetTaxed(params.fromASAID),
+   *     this.isAssetTaxed(params.toASAID),
+   *   ])
+   *
+   *   // 3 extra transactions per taxed asset
+   *   let maxGroupSize = params.maxGroupSize ?? 16
+   *   if (fromTaxed) maxGroupSize -= 3
+   *   if (toTaxed) maxGroupSize -= 3
+   *
+   *   // Adjust amount for input tax
+   *   let amount = params.amount
+   *   if (fromTaxed) {
+   *     const taxRate = await this.getTaxRate(params.fromASAID)
+   *     amount = this.applyTax(amount, taxRate)
+   *   }
+   *
+   *   return { ...params, maxGroupSize, amount }
+   * }
+   * ```
+   */
+  adjustQuoteParams?(params: FetchQuoteParams): Promise<FetchQuoteParams>;
+  /**
+   * Add transactions before the swap transactions
+   *
+   * Called when building the swap transaction group. Transactions are added
+   * to the group in the order they appear in the returned array.
+   *
+   * Transaction order in final group: [beforeSwap] → [swap txns] → [afterSwap]
+   *
+   * @param context - Swap context with quote, address, and algod client
+   * @returns Array of transactions with signers to add before swap
+   *
+   * @example
+   * ```typescript
+   * async beforeSwap(context) {
+   *   const txns: TransactionWithSigner[] = []
+   *
+   *   // Unfreeze user account before swap
+   *   if (await this.needsUnfreeze(context.fromASAID)) {
+   *     const unfreezeCall = makeApplicationNoOpTxn(
+   *       context.address,
+   *       this.appId,
+   *       ...,
+   *       context.suggestedParams
+   *     )
+   *
+   *     txns.push({
+   *       txn: unfreezeCall,
+   *       signer: context.signer, // Use the signer from context
+   *     })
+   *   }
+   *
+   *   return txns
+   * }
+   * ```
+   */
+  beforeSwap?(context: SwapContext): Promise<TransactionWithSigner[]>;
+  /**
+   * Add transactions after the swap transactions
+   *
+   * Called when building the swap transaction group. Transactions are added
+   * to the group in the order they appear in the returned array.
+   *
+   * Transaction order in final group: [beforeSwap] → [swap txns] → [afterSwap]
+   *
+   * @param context - Swap context with quote, address, and algod client
+   * @returns Array of transactions with signers to add after swap
+   *
+   * @example
+   * ```typescript
+   * async afterSwap(context) {
+   *   const txns: TransactionWithSigner[] = []
+   *
+   *   // Pay tax and refreeze account
+   *   if (await this.isTaxed(context.fromASAID)) {
+   *     const taxAmount = await this.calculateTax(context)
+   *     const taxPayment = makeAssetTransferTxn(
+   *       context.address,
+   *       this.taxReceiver,
+   *       taxAmount,
+   *       context.fromASAID,
+   *       context.suggestedParams
+   *     )
+   *     const refreezeCall = makeApplicationNoOpTxn(
+   *       context.address,
+   *       this.appId,
+   *       ...,
+   *       context.suggestedParams
+   *     )
+   *
+   *     txns.push(
+   *       { txn: taxPayment, signer: context.signer },
+   *       { txn: refreezeCall, signer: context.signer },
+   *     )
+   *   }
+   *
+   *   return txns
+   * }
+   * ```
+   */
+  afterSwap?(context: SwapContext): Promise<TransactionWithSigner[]>;
+}
 //#endregion
 //#region src/composer.d.ts
 /**
@@ -329,6 +585,8 @@ interface SwapComposerConfig {
   readonly address: string;
   /** Transaction signer function */
   readonly signer: TransactionSigner | SignerFunction;
+  /** Middleware to apply during swap composition */
+  readonly middleware?: SwapMiddleware[];
 }
 /**
  * Composer for building and executing atomic swap transaction groups
@@ -340,27 +598,28 @@ interface SwapComposerConfig {
  * @example
  * ```typescript
  * const quote = await deflex.fetchQuote({ ... })
- * const composer = await deflex.newSwap({ quote, address, slippage })
+ * const composer = await deflex.newSwap({ quote, address, slippage, signer })
  *
  * await composer
  *   .addTransaction(customTxn)
  *   .addSwapTransactions()
- *   .execute(signer)
+ *   .execute()
  * ```
  */
 declare class SwapComposer {
+  /** The ATC used to compose the group */
+  private atc;
   /** The maximum size of an atomic transaction group. */
   static MAX_GROUP_SIZE: number;
-  private status;
-  private transactions;
+  /** Whether the swap transactions have been added to the atomic group. */
   private swapTransactionsAdded;
-  private signedTxns;
-  private txIds;
+  private readonly quote;
   private readonly requiredAppOptIns;
   private readonly deflexTxns;
   private readonly algodClient;
   private readonly address;
   private readonly signer;
+  private readonly middleware;
   /**
    * Create a new SwapComposer instance
    *
@@ -368,11 +627,12 @@ declare class SwapComposer {
    * this directly, as the factory method handles fetching swap transactions automatically.
    *
    * @param config - Configuration for the composer
-   * @param config.requiredAppOptIns - The quote response from fetchQuote()
+   * @param config.quote - The quote response from fetchQuote()
    * @param config.deflexTxns - The swap transactions from fetchSwapTransactions()
    * @param config.algodClient - Algodv2 client instance
    * @param config.address - The address of the account that will sign transactions
    * @param config.signer - Transaction signer function
+   * @param config.middleware - Middleware to apply during swap composition
    */
   constructor(config: SwapComposerConfig);
   /**
@@ -403,12 +663,29 @@ declare class SwapComposer {
    * @throws Error if the composer is not in the BUILDING status
    * @throws Error if the maximum group size is exceeded
    */
-  addTransaction(transaction: Transaction): this;
+  addTransaction(transaction: Transaction, signer?: TransactionSigner): this;
+  /**
+   * Add a method call to the atomic group
+   *
+   * The `signer` property in the `methodCall` parameter is optional. If not provided,
+   * the signer will default to the one passed as the second parameter, or the
+   * configured signer from the constructor if no second parameter is provided.
+   *
+   * @param methodCall - The method call to add
+   * @param signer - The signer to use for the method call (defaults to constructor signer)
+   * @returns This composer instance for chaining
+   */
+  addMethodCall(methodCall: MethodCall, signer?: TransactionSigner): this;
   /**
    * Add swap transactions to the atomic group
    *
-   * This method automatically processes required app opt-ins and adds all swap
-   * transactions from the quote. Can only be called once per composer instance.
+   * This method automatically processes required app opt-ins, executes middleware hooks,
+   * and adds all swap transactions from the quote. Can only be called once per composer instance.
+   *
+   * Middleware hooks are executed in this order:
+   * 1. beforeSwap() - Add transactions before swap transactions
+   * 2. Swap transactions (from API)
+   * 3. afterSwap() - Add transactions after swap transactions
    *
    * @returns This composer instance for chaining
    * @throws Error if the swap transactions have already been added
@@ -416,6 +693,30 @@ declare class SwapComposer {
    * @throws Error if the maximum group size is exceeded
    */
   addSwapTransactions(): Promise<this>;
+  /**
+   * Finalize the transaction group by assigning group IDs
+   *
+   * This method builds the atomic transaction group, assigning group IDs to all transactions
+   * if there is more than one transaction. After calling this method, the composer's status
+   * will be at least BUILT.
+   *
+   * @returns Array of transactions with their associated signers
+   *
+   * @throws Error if the group contains 0 transactions
+   *
+   * @example
+   * ```typescript
+   * const composer = await deflex.newSwap({ quote, address, slippage, signer })
+   * composer.addTransaction(customTxn)
+   *
+   * // Build the group to inspect transactions before signing
+   * const txnsWithSigners = composer.buildGroup()
+   * console.log('Group ID:', txnsWithSigners[0].txn.group)
+   * console.log('Group length:', txnsWithSigners.length)
+   * console.log('Status:', composer.getStatus()) // BUILT
+   * ```
+   */
+  buildGroup(): TransactionWithSigner[];
   /**
    * Sign the transaction group
    *
@@ -467,6 +768,7 @@ declare class SwapComposer {
   execute(waitRounds?: number): Promise<{
     confirmedRound: bigint;
     txIds: string[];
+    methodResults: ABIResult[];
   }>;
   /**
    * Validates an Algorand address
@@ -481,15 +783,25 @@ declare class SwapComposer {
    */
   private processRequiredAppOptIns;
   /**
-   * Finalizes the transaction group by assigning group IDs
-   *
-   * The composer's status will be at least BUILT after executing this method.
+   * The default signer function that uses the configured signer
    */
-  private buildGroup;
+  private defaultSigner;
+  /**
+   * Creates a TransactionSigner function for Deflex pre-signed transactions
+   */
+  private createDeflexSigner;
   /**
    * Re-signs a Deflex transaction using the provided logic signature or secret key
    */
   private signDeflexTransaction;
+  /**
+   * Execute middleware hooks (beforeSwap or afterSwap)
+   */
+  private executeMiddlewareHooks;
+  /**
+   * Create SwapContext for middleware hooks
+   */
+  private createSwapContext;
 }
 //#endregion
 //#region src/client.d.ts
@@ -524,6 +836,7 @@ declare class SwapComposer {
 declare class DeflexClient {
   private readonly config;
   private readonly algodClient;
+  private readonly middleware;
   /**
    * Create a new DeflexClient instance
    *
@@ -536,8 +849,11 @@ declare class DeflexClient {
    * @param config.referrerAddress - Referrer address for fee sharing (receives 25% of swap fees)
    * @param config.feeBps - Fee in basis points (default: 15 = 0.15%, max: 300 = 3.00%)
    * @param config.autoOptIn - Automatically detect and add required opt-in transactions (default: false)
+   * @param config.middleware - Array of middleware to apply to swaps (default: [])
    */
-  constructor(config: DeflexConfigParams);
+  constructor(config: DeflexConfigParams & {
+    middleware?: SwapMiddleware[];
+  });
   /**
    * Fetch a swap quote from the Deflex API
    *
@@ -737,5 +1053,5 @@ declare class HTTPError extends Error {
  */
 declare function request<T>(url: string, options?: RequestInit): Promise<T>;
 //#endregion
-export { Asset, DEFAULT_ALGOD_PORT, DEFAULT_ALGOD_TOKEN, DEFAULT_ALGOD_URI, DEFAULT_API_BASE_URL, DEFAULT_AUTO_OPT_IN, DEFAULT_CONFIRMATION_ROUNDS, DEFAULT_FEE_BPS, DEFAULT_MAX_DEPTH, DEFAULT_MAX_GROUP_SIZE, DEPRECATED_PROTOCOLS, DeflexClient, DeflexConfig, DeflexConfigParams, DeflexQuote, DeflexSignature, DeflexTransaction, DexQuote, FetchQuoteParams, FetchQuoteResponse, FetchSwapTxnsBody, FetchSwapTxnsParams, FetchSwapTxnsResponse, HTTPError, MAX_FEE_BPS, PathElement, Profit, Protocol, QuoteType, Route, SignerFunction, SwapComposer, SwapComposerConfig, SwapComposerStatus, SwapTransaction, TxnPayload, request };
+export { Asset, DEFAULT_ALGOD_PORT, DEFAULT_ALGOD_TOKEN, DEFAULT_ALGOD_URI, DEFAULT_API_BASE_URL, DEFAULT_AUTO_OPT_IN, DEFAULT_CONFIRMATION_ROUNDS, DEFAULT_FEE_BPS, DEFAULT_MAX_DEPTH, DEFAULT_MAX_GROUP_SIZE, DEPRECATED_PROTOCOLS, DeflexClient, DeflexConfig, DeflexConfigParams, DeflexQuote, DeflexSignature, DeflexTransaction, DexQuote, FetchQuoteParams, FetchQuoteResponse, FetchSwapTxnsBody, FetchSwapTxnsParams, FetchSwapTxnsResponse, HTTPError, MAX_FEE_BPS, MethodCall, PathElement, Profit, Protocol, QuoteType, Route, SignerFunction, SwapComposer, SwapComposerConfig, SwapComposerStatus, SwapContext, SwapMiddleware, SwapTransaction, TxnPayload, request };
 //# sourceMappingURL=index.d.ts.map