@txnlab/haystack-router 2.0.0

package/dist/index.d.mts

@@ -0,0 +1,1246 @@
+import { ABIArgument, ABIMethod, ABIResult, Address, Algodv2, BoxReference, OnApplicationComplete, ResourceReference, SuggestedParams, Transaction, TransactionSigner, TransactionWithSigner } from "algosdk";
+
+//#region src/constants.d.ts
+/**
+ * Supported DEX protocols for swap routing
+ */
+declare enum Protocol {
+  TinymanV2 = "TinymanV2",
+  Algofi = "Algofi",
+  Algomint = "Algomint",
+  Pact = "Pact",
+  Folks = "Folks",
+  TAlgo = "TAlgo",
+}
+/**
+ * Deprecated protocols that are automatically excluded from routing
+ *
+ * @internal
+ */
+declare const DEPRECATED_PROTOCOLS: readonly ["Humble", "Tinyman"];
+/** Default Algod node URI for mainnet */
+declare const DEFAULT_ALGOD_URI = "https://mainnet-api.4160.nodely.dev/";
+/** Default Algod node token (empty for public nodes) */
+declare const DEFAULT_ALGOD_TOKEN = "";
+/** Default Algod node port */
+declare const DEFAULT_ALGOD_PORT = 443;
+/** Default Haystack Router API base URL */
+declare const DEFAULT_API_BASE_URL = "https://hayrouter.txnlab.dev/api";
+/** Default fee in basis points (0.10%) */
+declare const DEFAULT_FEE_BPS = 10;
+/** Maximum allowed fee in basis points (3.00%) */
+declare const MAX_FEE_BPS = 300;
+/** Default maximum transaction group size */
+declare const DEFAULT_MAX_GROUP_SIZE = 16;
+/** Default maximum routing depth (number of hops) */
+declare const DEFAULT_MAX_DEPTH = 4;
+/** Default auto opt-in setting (automatic asset/app opt-in detection) */
+declare const DEFAULT_AUTO_OPT_IN = false;
+/** Default debug level (no debug logging) */
+declare const DEFAULT_DEBUG_LEVEL: "none";
+/** Default number of rounds to wait for transaction confirmation */
+declare const DEFAULT_CONFIRMATION_ROUNDS = 10;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Configuration parameters for initializing RouterClient
+ */
+interface ConfigParams {
+  /** API key for Haystack Router API (required) */
+  readonly apiKey: string;
+  /** Base URL for the Haystack Router API (default: https://hayrouter.txnlab.dev) */
+  readonly apiBaseUrl?: string;
+  /** Algod node URI (default: https://mainnet-api.4160.nodely.dev/) */
+  readonly algodUri?: string;
+  /** Algod node token (can be empty string for public nodes) */
+  readonly algodToken?: string;
+  /** Algod node port (default: 443) */
+  readonly algodPort?: string | number;
+  /** Referrer address for fee sharing (receives 25% of swap fees) */
+  readonly referrerAddress?: string;
+  /** Fee in basis points (default: 15 = 0.15%, max: 300 = 3.00%) */
+  readonly feeBps?: number;
+  /** Automatically detect and add required opt-in transactions (default: false) */
+  readonly autoOptIn?: boolean;
+  /**
+   * Debug logging level (default: 'none')
+   *
+   * - 'none': No debug logging (default)
+   * - 'info': High-level operations (quote fetched, swap created, submitted)
+   * - 'debug': Detailed flow (middleware applied, validation, status transitions)
+   * - 'trace': Everything including request/response payloads, transaction details
+   */
+  readonly debugLevel?: 'none' | 'info' | 'debug' | 'trace';
+}
+/**
+ * Internal configuration with all required fields validated
+ *
+ * @internal
+ */
+type Config = Omit<Required<ConfigParams>, 'referrerAddress' | 'debugLevel'> & {
+  readonly referrerAddress: string | undefined;
+  readonly debugLevel: 'none' | 'info' | 'debug' | 'trace';
+};
+/**
+ * Swap quote type determining which amount is fixed
+ */
+type QuoteType = 'fixed-input' | 'fixed-output';
+/**
+ * Parameters for requesting a swap quote from the Haystack Router API (raw API method)
+ */
+interface FetchQuoteParams {
+  /** Input asset ID */
+  readonly fromASAID: bigint | number;
+  /** Output asset ID */
+  readonly toASAID: bigint | number;
+  /** Amount to swap (in base units) */
+  readonly amount: bigint | number;
+  /** Quote type (default: 'fixed-input') */
+  readonly type?: QuoteType;
+  /** Protocols to exclude from routing (default: []) */
+  readonly disabledProtocols?: readonly Protocol[];
+  /** Maximum transaction group size (default: 16) */
+  readonly maxGroupSize?: number;
+  /** Maximum depth of the route (default: 4) */
+  readonly maxDepth?: number;
+  /** Whether to include asset opt-in transaction (overrides config.autoOptIn if set) */
+  readonly optIn?: boolean;
+  /** Address of the account that will perform the swap (required if autoOptIn is enabled) */
+  readonly address?: string | null;
+  /**
+   * ⚠️ **ADVANCED USE ONLY - NON-COMPOSABLE SWAPS** ⚠️
+   *
+   * When set to `true`, removes the automatic exclusion of Tinyman v1 from routing,
+   * allowing the API to route swaps through protocols that produce **non-composable**
+   * transaction groups.
+   *
+   * **Critical Limitations:**
+   * - You CANNOT add transactions before/after swap transactions in the atomic group
+   * - Asset opt-ins and opt-outs MUST be sent in separate transaction groups
+   * - The SwapComposer will throw errors if you attempt to compose additional transactions
+   * - This parameter CANNOT be used with `optIn: true` or `config.autoOptIn: true`
+   * - This parameter is NOT supported in `newQuote()` (only `fetchQuote()`)
+   *
+   * **When to use this:**
+   * Only use this if you have built custom infrastructure to:
+   * 1. Detect when the route uses non-composable protocols (Tinyman v1)
+   * 2. Handle opt-in/opt-out transactions separately from the swap group
+   * 3. Coordinate multiple transaction groups instead of composing a single atomic group
+   *
+   * **This breaks the standard SDK workflow.** The default behavior of always excluding
+   * Tinyman v1 ensures all swaps are composable, which is the recommended approach.
+   *
+   * @default false
+   * @internal This is not a supported public API feature
+   */
+  readonly _allowNonComposableSwaps?: boolean;
+}
+/**
+ * Asset information from the Haystack Router API
+ */
+interface Asset {
+  /** Asset ID */
+  readonly id: number;
+  /** Number of decimal places */
+  readonly decimals: number;
+  /** Unit name */
+  readonly unit_name: string;
+  /** Full asset name */
+  readonly name: string;
+  /** Price in ALGO */
+  readonly price_algo: number;
+  /** Price in USD */
+  readonly price_usd: number;
+}
+/**
+ * Profit information for a swap
+ */
+interface Profit {
+  /** Profit amount in base units */
+  readonly amount: number;
+  /** The asset in which profit is denominated */
+  readonly asa: Asset;
+}
+/**
+ * A single step in a swap route path
+ */
+interface PathElement {
+  /** Protocol name and fee tier */
+  readonly name: string;
+  /** Protocol class identifier */
+  readonly class: string[][];
+  /** Input asset */
+  readonly in: Asset;
+  /** Output asset */
+  readonly out: Asset;
+}
+/**
+ * A route with its percentage of the total swap amount
+ */
+interface Route {
+  /** Percentage of total swap amount routed through this path */
+  readonly percentage: number;
+  /** The sequence of swaps in this route */
+  readonly path: PathElement[];
+}
+/**
+ * Quote from a specific DEX protocol
+ */
+interface DexQuote {
+  /** Protocol name and fee tier */
+  readonly name: string;
+  /** Protocol class */
+  readonly class: string;
+  /** Quoted output value */
+  readonly value: number;
+}
+/**
+ * Encrypted transaction payload from the quote
+ */
+interface TxnPayload {
+  /** Initialization vector for decryption */
+  readonly iv: string;
+  /** Encrypted transaction data */
+  readonly data: string;
+}
+/**
+ * Quote response from the Haystack Router API
+ */
+interface FetchQuoteResponse {
+  /** The quoted output amount or input amount (depending on quote type) */
+  readonly quote: string | number;
+  /** Profit information for the swap */
+  readonly profit: Profit;
+  /** Baseline price without fees */
+  readonly priceBaseline: number;
+  /** Price impact for the user */
+  readonly userPriceImpact?: number;
+  /** Overall market price impact */
+  readonly marketPriceImpact?: number;
+  /** USD value of input amount */
+  readonly usdIn: number;
+  /** USD value of output amount */
+  readonly usdOut: number;
+  /** The routing path(s) for the swap */
+  readonly route: Route[];
+  /** Flattened view of routing percentages by protocol */
+  readonly flattenedRoute: Record<string, number>;
+  /** Individual quotes from each DEX */
+  readonly quotes: DexQuote[];
+  /** App IDs that require opt-in for this swap */
+  readonly requiredAppOptIns: number[];
+  /** Encrypted transaction payload for generating swap transactions */
+  readonly txnPayload: TxnPayload | null;
+  /** Fees charged by each protocol */
+  readonly protocolFees: Record<string, number>;
+  /** Input asset ID */
+  readonly fromASAID: number;
+  /** Output asset ID */
+  readonly toASAID: number;
+  /** Quote type */
+  readonly type: string;
+  /** Performance timing data */
+  readonly timing?: unknown;
+}
+/**
+ * Enhanced quote result returned by RouterClient.newQuote()
+ *
+ * Extends the raw API response with additional metadata and type normalization.
+ */
+type SwapQuote = Omit<FetchQuoteResponse, 'quote'> & {
+  /**
+   * The quoted output amount or input amount (coerced to bigint)
+   *
+   * For fixed-input swaps: This is the output amount you'll receive
+   * For fixed-output swaps: This is the input amount you'll need to provide
+   */
+  readonly quote: bigint;
+  /** The original amount from the quote request (in base units) */
+  readonly amount: bigint;
+  /** The address parameter from the quote request (if provided) */
+  readonly address?: string;
+  /** Timestamp when the quote was created (in milliseconds) */
+  readonly createdAt: number;
+};
+/**
+ * Transaction signature from the Haystack Router API
+ */
+interface Signature {
+  /** Signature type */
+  readonly type: 'logic_signature' | 'secret_key';
+  /** Signature data */
+  readonly value: unknown;
+}
+/**
+ * Transaction data from the Haystack Router API
+ */
+interface SwapTransaction {
+  /** Base64-encoded transaction data */
+  readonly data: string;
+  /** Group ID for the transaction */
+  readonly group: string;
+  /** Logic signature blob (if applicable) */
+  readonly logicSigBlob: unknown | false;
+  /** Signature data (false if user must sign) */
+  readonly signature: Signature | false;
+}
+/**
+ * Parameters for fetching executable swap transactions
+ */
+interface FetchSwapTxnsParams {
+  /** Quote response from fetchQuote() or newQuote() */
+  readonly quote: FetchQuoteResponse | SwapQuote;
+  /** Algorand address that will sign the transactions */
+  readonly address: string;
+  /** Slippage tolerance as a percentage (e.g., 1 for 1%) */
+  readonly slippage: number;
+}
+/**
+ * Request body for fetching swap transactions
+ *
+ * @internal
+ */
+interface FetchSwapTxnsBody {
+  /** API key for authentication */
+  readonly apiKey: string;
+  /** Address of the account that will sign the transactions */
+  readonly address: string;
+  /** Encrypted transaction payload from the quote */
+  readonly txnPayloadJSON: TxnPayload | null;
+  /** Slippage tolerance as a percentage */
+  readonly slippage: number;
+}
+/**
+ * Response from fetching swap transactions
+ */
+interface FetchSwapTxnsResponse {
+  /** Array of transaction data */
+  readonly txns: SwapTransaction[];
+}
+/**
+ * Summary of a swap transaction group after execution
+ *
+ * Contains the exact input/output amounts and total transaction fees.
+ * Only available after calling execute() on a SwapComposer instance.
+ */
+interface SwapSummary {
+  /** Input asset ID (0 for ALGO) */
+  inputAssetId: bigint;
+  /** Output asset ID (0 for ALGO) */
+  outputAssetId: bigint;
+  /** Exact input amount in base units, from the user-signed transaction */
+  inputAmount: bigint;
+  /** Exact output amount received in base units, from the inner transaction */
+  outputAmount: bigint;
+  /** Quote type */
+  type: QuoteType;
+  /** Total ALGO transaction fees in microAlgos */
+  totalFees: bigint;
+  /** Number of transactions in the group */
+  transactionCount: number;
+  /** Transaction ID of the user-signed input transaction (payment/asset transfer) */
+  inputTxnId: string;
+  /** Transaction ID of the app call containing the output transfer as an inner transaction */
+  outputTxnId: string;
+  /** Address that sent the input asset (the user) */
+  inputSender: string;
+  /** Address that sent the output asset to the user */
+  outputSender: string;
+}
+/**
+ * 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 shouldApply hook
+ */
+interface QuoteContext {
+  /** 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;
+  /** Amount to swap (always bigint for precision and future-proofing) */
+  readonly amount: bigint;
+  /** Quote type */
+  readonly type: QuoteType;
+  /** Address of the account that will perform the swap (if provided) */
+  readonly address?: string;
+  /** Algodv2 client instance for making additional queries */
+  readonly algodClient: Algodv2;
+}
+/**
+ * Context provided to middleware hooks during swap composition
+ */
+interface SwapContext {
+  /** The quote result from newQuote() */
+  readonly quote: SwapQuote;
+  /** 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(context) {
+ *     return context.fromASAID === CUSTOM_ASSET_ID || context.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 context - Quote context with asset IDs, amount, type, address, and algod client
+   * @returns True if middleware should be applied
+   *
+   * @example
+   * ```typescript
+   * async shouldApply(context) {
+   *   // Check if asset is registered in our smart contract
+   *   const assetInfo = await this.getAssetInfo(context.fromASAID)
+   *   return assetInfo !== null
+   * }
+   * ```
+   */
+  shouldApply(context: QuoteContext): 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 Haystack Router 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[]>;
+}
+/**
+ * Configuration options for AutoOptOutMiddleware
+ */
+interface AutoOptOutConfig {
+  /**
+   * Array of asset IDs that should be excluded from automatic opt-out behavior
+   * @default []
+   */
+  readonly excludedAssets?: readonly (number | bigint)[];
+}
+/**
+ * Middleware that automatically adds an asset opt-out transaction when swapping
+ * the full balance of an input asset, leaving it with a zero balance.
+ *
+ * @example
+ * ```typescript
+ * import { RouterClient, AutoOptOutMiddleware } from '@txnlab/haystack-router'
+ *
+ * const autoOptOut = new AutoOptOutMiddleware({
+ *   excludedAssets: [31566704], // Don't auto-opt-out of USDC
+ * })
+ *
+ * const router = new RouterClient({
+ *   apiKey: 'your-api-key',
+ *   middleware: [autoOptOut],
+ * })
+ *
+ * // When swapping full balance, opt-out transaction is automatically added
+ * const quote = await router.newQuote({
+ *   address: userAddress,
+ *   fromASAID: someAssetId,
+ *   toASAID: 0,
+ *   amount: fullBalance, // If this equals account's full balance, opt-out is added
+ *   type: 'fixed-input',
+ * })
+ * ```
+ */
+declare class AutoOptOutMiddleware implements SwapMiddleware {
+  readonly name = "AutoOptOut";
+  readonly version = "1.0.0";
+  private readonly excludedAssets;
+  constructor(config?: AutoOptOutConfig);
+  shouldApply(context: QuoteContext): Promise<boolean>;
+  adjustQuoteParams(params: FetchQuoteParams): Promise<FetchQuoteParams>;
+  afterSwap(context: SwapContext): Promise<TransactionWithSigner[]>;
+}
+//#endregion
+//#region src/composer.d.ts
+/**
+ * A transaction signer function that supports both standard algosdk.TransactionSigner
+ * and ARC-1 compliant signers that may return null for unsigned transactions.
+ *
+ * @param txnGroup - The complete transaction group to sign
+ * @param indexesToSign - Array of indexes indicating which transactions need signing
+ * @returns Array of signed transactions (may include nulls for ARC-1 compliant wallets)
+ */
+type SignerFunction = (txnGroup: Transaction[], indexesToSign: number[]) => Promise<(Uint8Array | null)[]>;
+/**
+ * Status of the SwapComposer transaction group lifecycle
+ */
+declare enum SwapComposerStatus {
+  /** The atomic group is still under construction. */
+  BUILDING = 0,
+  /** The atomic group has been finalized, but not yet signed. */
+  BUILT = 1,
+  /** The atomic group has been finalized and signed, but not yet submitted to the network. */
+  SIGNED = 2,
+  /** The atomic group has been finalized, signed, and submitted to the network. */
+  SUBMITTED = 3,
+  /** The atomic group has been finalized, signed, submitted, and successfully committed to a block. */
+  COMMITTED = 4,
+}
+/**
+ * Configuration for creating a SwapComposer instance
+ */
+interface SwapComposerConfig {
+  /** The quote response from fetchQuote() or newQuote() */
+  readonly quote: FetchQuoteResponse | SwapQuote;
+  /** The swap transactions from fetchSwapTransactions() */
+  readonly swapTxns: SwapTransaction[];
+  /** Algodv2 client instance */
+  readonly algodClient: Algodv2;
+  /** The address of the account that will sign transactions */
+  readonly address: string;
+  /** Transaction signer function */
+  readonly signer: TransactionSigner | SignerFunction;
+  /** Middleware to apply during swap composition */
+  readonly middleware?: SwapMiddleware[];
+  /** Optional note field for the user-signed input transaction (payment or asset transfer) */
+  readonly note?: Uint8Array;
+  /** Debug logging level (propagated from RouterClient) */
+  readonly debugLevel?: 'none' | 'info' | 'debug' | 'trace';
+}
+/**
+ * Composer for building and executing atomic swap transaction groups
+ *
+ * The SwapComposer allows you to build complex transaction groups by adding custom
+ * transactions before and after swap transactions. It handles pre-signed transactions,
+ * automatic app opt-ins, and provides a fluent API for transaction group construction.
+ *
+ * @example
+ * ```typescript
+ * const quote = await router.fetchQuote({ ... })
+ * const composer = await router.newSwap({ quote, address, slippage, signer })
+ *
+ * await composer
+ *   .addTransaction(customTxn)
+ *   .addSwapTransactions()
+ *   .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;
+  /** Whether the swap transactions have been added to the atomic group. */
+  private swapTransactionsAdded;
+  private readonly quote;
+  private readonly requiredAppOptIns;
+  private readonly swapTxns;
+  private readonly algodClient;
+  private readonly address;
+  private readonly signer;
+  private readonly middleware;
+  private readonly note?;
+  private inputTransactionIndex?;
+  private outputTransactionIndex?;
+  /** Summary data built incrementally during swap composition */
+  private summaryData?;
+  /**
+   * Create a new SwapComposer instance
+   *
+   * Note: Most developers should use RouterClient.newSwap() instead of constructing
+   * this directly, as the factory method handles fetching swap transactions automatically.
+   *
+   * @param config - Configuration for the composer
+   * @param config.quote - The quote response from fetchQuote()
+   * @param config.swapTxns - 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);
+  /**
+   * Get the status of this composer's transaction group
+   *
+   * @returns The current status of the transaction group
+   */
+  getStatus(): SwapComposerStatus;
+  /**
+   * Get the number of transactions currently in this atomic group
+   *
+   * @returns The number of transactions in the group
+   */
+  count(): number;
+  /**
+   * Add a transaction to the atomic group
+   *
+   * Transactions are added in the order methods are called. For example:
+   * ```typescript
+   * composer
+   *   .addTransaction(txn1)      // Added first
+   *   .addSwapTransactions()     // Added second
+   *   .addTransaction(txn2)      // Added third
+   * ```
+   *
+   * @param transaction - The transaction to add
+   * @returns This composer instance for chaining
+   * @throws Error if the composer is not in the BUILDING status
+   * @throws Error if the maximum group size is exceeded
+   * @throws Error if attempting to compose with a non-composable swap (Tinyman v1)
+   */
+  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
+   * @throws Error if attempting to compose with a non-composable swap (Tinyman v1)
+   */
+  addMethodCall(methodCall: MethodCall, signer?: TransactionSigner): this;
+  /**
+   * Add swap transactions to the atomic group
+   *
+   * 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
+   * @throws Error if the composer is not in the BUILDING status
+   * @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 router.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
+   *
+   * Automatically adds swap transactions if not already added, builds the atomic group,
+   * and signs all transactions using the configured signer.
+   *
+   * @returns A promise that resolves to an array of signed transaction blobs
+   *
+   * @example
+   * ```typescript
+   * const signedTxns = await composer.sign()
+   * ```
+   */
+  sign(): Promise<Uint8Array[]>;
+  /**
+   * Submit the signed transactions to the network
+   *
+   * This method signs the transaction group (if not already signed) and submits
+   * it to the Algorand network. Does not wait for confirmation.
+   *
+   * @returns The transaction IDs
+   * @throws Error if the transaction group has already been submitted
+   *
+   * @example
+   * ```typescript
+   * const txIds = await composer.submit()
+   * console.log('Submitted transactions:', txIds)
+   * ```
+   */
+  submit(): Promise<string[]>;
+  /**
+   * Execute the swap
+   *
+   * Signs the transaction group, submits it to the network, and waits for confirmation.
+   * This is the primary method for executing swaps and combines sign(), submit(), and
+   * waitForConfirmation() into a single call.
+   *
+   * @param waitRounds - The number of rounds to wait for confirmation (default: 10)
+   * @returns Object containing the confirmed round and transaction IDs
+   * @throws Error if the transaction group has already been committed
+   *
+   * @example
+   * ```typescript
+   * const result = await composer.execute()
+   * console.log(`Confirmed in round ${result.confirmedRound}`)
+   * console.log('Transaction IDs:', result.txIds)
+   * ```
+   */
+  execute(waitRounds?: number): Promise<{
+    confirmedRound: bigint;
+    txIds: string[];
+    methodResults: ABIResult[];
+  }>;
+  /**
+   * Get the transaction ID of the user-signed input transaction
+   *
+   * Returns the transaction ID of the payment or asset transfer transaction
+   * that sends the input asset. This is the transaction whose note field can
+   * be customized via the `note` config option.
+   *
+   * The transaction ID is only available after the group has been built
+   * (after calling buildGroup(), sign(), submit(), or execute()).
+   *
+   * @returns The transaction ID, or undefined if the group hasn't been built yet
+   *          or if the input transaction index couldn't be determined
+   *
+   * @example
+   * ```typescript
+   * const swap = await router.newSwap({
+   *   quote,
+   *   address,
+   *   slippage,
+   *   signer,
+   *   note: new TextEncoder().encode('tracking-123')
+   * })
+   *
+   * await swap.execute()
+   * const inputTxId = swap.getInputTransactionId()
+   * console.log('Input transaction ID:', inputTxId)
+   * ```
+   */
+  getInputTransactionId(): string | undefined;
+  /**
+   * Get a summary of the swap amounts and fees
+   *
+   * Returns the exact input and output amounts, total transaction fees,
+   * and transaction IDs. This is useful for displaying a complete summary
+   * after a swap has been executed.
+   *
+   * Only available after calling execute() - returns undefined before execution.
+   *
+   * @returns SwapSummary containing exact amounts and fees, or undefined if not yet executed
+   *
+   * @example
+   * ```typescript
+   * const swap = await router.newSwap({ quote, address, slippage, signer })
+   * const result = await swap.execute()
+   *
+   * const summary = swap.getSummary()
+   * if (summary) {
+   *   console.log('Sent:', summary.inputAmount, 'Received:', summary.outputAmount)
+   *   console.log('Total fees:', summary.totalFees, 'microAlgos')
+   * }
+   * ```
+   */
+  getSummary(): SwapSummary | undefined;
+  /**
+   * Validates an Algorand address
+   */
+  private validateAddress;
+  /**
+   * Processes app opt-ins and decodes swap transactions from API response
+   *
+   * Also initializes summaryData with input transaction details and output transaction ID
+   */
+  private processSwapTransactions;
+  /**
+   * Creates opt-in transactions for apps the user hasn't opted into yet
+   */
+  private processRequiredAppOptIns;
+  /**
+   * The default signer function that uses the configured signer
+   */
+  private defaultSigner;
+  /**
+   * Creates a TransactionSigner function for Deflex pre-signed transactions
+   */
+  private createSwapSigner;
+  /**
+   * Re-signs a Deflex transaction using the provided logic signature or secret key
+   */
+  private signSwapTransaction;
+  /**
+   * Execute middleware hooks (beforeSwap or afterSwap)
+   */
+  private executeMiddlewareHooks;
+  /**
+   * Extract the actual output amount from the confirmed output transaction's inner transactions
+   *
+   * Analyzes only the output transaction (last app call in the swap) to find the
+   * inner transaction that transfers the output asset to the user.
+   */
+  private extractActualOutputAmount;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * Client for interacting with the Haystack order router API
+ *
+ * The RouterClient provides methods to fetch swap quotes and create transaction composers
+ * for executing swaps on the Algorand blockchain. It handles API communication, transaction
+ * validation, and automatic asset/app opt-in detection.
+ *
+ * @example
+ * ```typescript
+ * const router = new RouterClient({
+ *   apiKey: 'your-api-key',
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const router = new RouterClient({
+ *   apiKey: 'your-api-key',
+ *   apiBaseUrl: 'https://hayrouter.txnlab.dev',
+ *   algodUri: 'https://mainnet-api.4160.nodely.dev/',
+ *   algodToken: '',
+ *   algodPort: 443,
+ *   referrerAddress: 'REFERRER_ADDRESS...',
+ *   feeBps: 15,
+ *   autoOptIn: false,
+ * })
+ * ```
+ */
+declare class RouterClient {
+  private readonly config;
+  private readonly algodClient;
+  private readonly middleware;
+  /**
+   * Create a new RouterClient instance
+   *
+   * @param config - Configuration parameters
+   * @param config.apiKey - API key for Haystack Router API (required)
+   * @param config.apiBaseUrl - Base URL for the Haystack Router API (default: https://hayrouter.txnlab.dev)
+   * @param config.algodUri - Algod node URI (default: https://mainnet-api.4160.nodely.dev/)
+   * @param config.algodToken - Algod node token (default: '')
+   * @param config.algodPort - Algod node port (default: 443)
+   * @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.debugLevel - Debug logging level (default: 'none')
+   * @param config.middleware - Array of middleware to apply to swaps (default: [])
+   */
+  constructor(config: ConfigParams & {
+    middleware?: SwapMiddleware[];
+  });
+  /**
+   * Fetch a swap quote from the Haystack Router API
+   *
+   * Requests optimal swap routing from the Haystack Router API. The quote includes routing
+   * information, price impact, required opt-ins, and an encrypted transaction payload.
+   *
+   * @param params - Parameters for the quote request
+   * @param params.fromASAID - The ID of the asset to swap from
+   * @param params.toASAID - The ID of the asset to swap to
+   * @param params.amount - The amount of the asset to swap in base units
+   * @param params.type - The type of the quote (default: 'fixed-input')
+   * @param params.disabledProtocols - List of protocols to disable (default: [])
+   * @param params.maxGroupSize - The maximum group size (default: 16)
+   * @param params.maxDepth - The maximum depth (default: 4)
+   * @param params.address - The address of the account that will perform the swap (recommended when using `config.autoOptIn` or `params.optIn`)
+   * @param params.optIn - Whether to include asset opt-in transaction
+   *   - If true: API reduces maxGroupSize by 1 and includes opt-in (always included, even if not needed)
+   *   - If false: No opt-in transaction included
+   *   - If undefined: Falls back to `config.autoOptIn` behavior with account check (if `params.address` is provided)
+   * @returns A FetchQuoteResponse object with routing information
+   *
+   * @example
+   * ```typescript
+   * const quote = await router.fetchQuote({
+   *   address: 'ABC...',
+   *   fromASAID: 0,           // ALGO
+   *   toASAID: 31566704,      // USDC
+   *   amount: 1_000_000,      // 1 ALGO
+   * })
+   * ```
+   */
+  fetchQuote(params: FetchQuoteParams): Promise<FetchQuoteResponse>;
+  /**
+   * Check if asset opt-in is required for the output asset
+   *
+   * Convenience method to determine if an address needs to opt into the output asset
+   * of a swap. This is useful when you want to get a quote without requiring wallet
+   * connection upfront, but need to know whether to set `optIn: true` in fetchQuote()
+   * to ensure proper routing (as opt-ins reduce maxGroupSize by 1).
+   *
+   * Note: If you enable `config.autoOptIn`, this check is handled automatically when
+   * an address is provided to fetchQuote().
+   *
+   * @param address - The address to check
+   * @param assetId - The output asset ID to check
+   * @returns True if asset opt-in is required, false otherwise (always false for ALGO)
+   *
+   * @example
+   * ```typescript
+   * // Check if opt-in needed for output asset before fetching quote
+   * const needsOptIn = await router.needsAssetOptIn(userAddress, toAssetId)
+   * const quote = await router.fetchQuote({
+   *   fromAssetId,
+   *   toAssetId,
+   *   amount,
+   *   optIn: needsOptIn,
+   * })
+   * ```
+   */
+  needsAssetOptIn(address: string, assetId: number | bigint): Promise<boolean>;
+  /**
+   * Fetch swap transactions from the Haystack Router API
+   *
+   * Decrypts the quote payload and generates executable swap transactions for the
+   * specified signer address with the given slippage tolerance.
+   *
+   * @param params - Parameters for the swap transaction request
+   * @param params.quote - The quote response from fetchQuote()
+   * @param params.address - The address of the signer
+   * @param params.slippage - The slippage tolerance as a percentage (e.g., 1 for 1%)
+   * @returns A FetchSwapTxnsResponse object with transaction data
+   */
+  fetchSwapTransactions(params: FetchSwapTxnsParams): Promise<FetchSwapTxnsResponse>;
+  /**
+   * Fetch a quote and return an enhanced quote result
+   *
+   * This is the recommended way to fetch quotes. It returns an object that
+   * extends the raw API response with additional metadata and type normalization.
+   *
+   * @param params - Parameters for the quote request
+   * @param params.fromASAID - The ID of the asset to swap from
+   * @param params.toASAID - The ID of the asset to swap to
+   * @param params.amount - The amount of the asset to swap in base units
+   * @param params.type - The type of the quote (default: 'fixed-input')
+   * @param params.disabledProtocols - List of protocols to disable (default: [])
+   * @param params.maxGroupSize - The maximum group size (default: 16)
+   * @param params.maxDepth - The maximum depth (default: 4)
+   * @param params.address - The address of the account that will perform the swap (recommended when using `config.autoOptIn` or `params.optIn`)
+   * @param params.optIn - Whether to include asset opt-in transaction
+   * @returns A SwapQuote enhanced quote result
+   *
+   * @example
+   * ```typescript
+   * const quote = await router.newQuote({
+   *   address: 'ABC...',
+   *   fromASAID: 0,
+   *   toASAID: 31566704,
+   *   amount: 1_000_000,
+   * })
+   *
+   * console.log(quote.quote)     // bigint - quoted amount
+   * console.log(quote.fromASAID) // number - input asset ID
+   * console.log(quote.toASAID)   // number - output asset ID
+   * console.log(quote.amount)    // bigint - original request amount
+   * console.log(quote.createdAt) // number - timestamp
+   * ```
+   */
+  newQuote(params: FetchQuoteParams): Promise<SwapQuote>;
+  /**
+   * Create a SwapComposer instance
+   *
+   * This factory method creates a composer that allows you to add custom transactions
+   * before and after the swap transactions, with automatic handling of pre-signed transactions
+   * and opt-ins.
+   *
+   * @param config.quote - The quote result from newQuote() or raw API response from fetchQuote()
+   * @param config.address - The address of the signer
+   * @param config.slippage - The slippage tolerance
+   * @param config.signer - Transaction signer function
+   * @returns A SwapComposer instance ready for building transaction groups
+   *
+   * @example
+   * ```typescript
+   * // Basic swap
+   * const quote = await router.newQuote({ ... })
+   * await router.newSwap({ quote, address, slippage, signer })
+   *   .execute()
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Advanced swap with custom transactions
+   * const quote = await router.newQuote({ ... })
+   * const swap = await router.newSwap({
+   *   quote,
+   *   address,
+   *   slippage,
+   *   signer,
+   * })
+   *
+   * console.log(swap.getStatus()) // BUILDING
+   *
+   * const signedTxns = await swap
+   *   .addTransaction(beforeTxn)
+   *   .addSwapTransactions() // Adds swap transactions to the group
+   *   .addTransaction(afterTxn)
+   *   .sign()
+   *
+   * console.log(swap.getStatus()) // SIGNED
+   *
+   * const result = await swap.execute(waitRounds)
+   * console.log(result.confirmedRound, result.txIds)
+   *
+   * console.log(swap.getStatus()) // COMMITTED
+   * ```
+   */
+  newSwap(config: {
+    quote: SwapQuote | FetchQuoteResponse;
+    address: string;
+    slippage: number;
+    signer: TransactionSigner | SignerFunction;
+    /** Optional note field for the user-signed input transaction (payment or asset transfer) */
+    note?: Uint8Array;
+  }): Promise<SwapComposer>;
+  /**
+   * Validates the API key
+   */
+  private validateApiKey;
+  /**
+   * Validates an Algorand address
+   */
+  private validateAddress;
+  /**
+   * Validates the fee in basis points (max 300 = 3.00%)
+   */
+  private validateFeeBps;
+}
+//#endregion
+//#region src/utils.d.ts
+/**
+ * HTTP error with status code and response data
+ */
+declare class HTTPError extends Error {
+  status: number;
+  statusText: string;
+  data: unknown;
+  constructor(status: number, statusText: string, data: unknown);
+}
+/**
+ * Make an HTTP request and parse JSON response
+ *
+ * Simple wrapper around native fetch for API calls. Throws HTTPError for
+ * non-2xx responses.
+ *
+ * @param url - The URL to request
+ * @param options - Fetch options
+ * @returns Parsed JSON response
+ * @throws HTTPError if the response status is not ok
+ */
+declare function request<T>(url: string, options?: RequestInit): Promise<T>;
+//#endregion
+export { Asset, AutoOptOutConfig, AutoOptOutMiddleware, Config, ConfigParams, DEFAULT_ALGOD_PORT, DEFAULT_ALGOD_TOKEN, DEFAULT_ALGOD_URI, DEFAULT_API_BASE_URL, DEFAULT_AUTO_OPT_IN, DEFAULT_CONFIRMATION_ROUNDS, DEFAULT_DEBUG_LEVEL, DEFAULT_FEE_BPS, DEFAULT_MAX_DEPTH, DEFAULT_MAX_GROUP_SIZE, DEPRECATED_PROTOCOLS, DexQuote, FetchQuoteParams, FetchQuoteResponse, FetchSwapTxnsBody, FetchSwapTxnsParams, FetchSwapTxnsResponse, HTTPError, MAX_FEE_BPS, MethodCall, PathElement, Profit, Protocol, QuoteContext, QuoteType, Route, RouterClient, Signature, SignerFunction, SwapComposer, SwapComposerConfig, SwapComposerStatus, SwapContext, SwapMiddleware, SwapQuote, SwapSummary, SwapTransaction, TxnPayload, request };
+//# sourceMappingURL=index.d.mts.map