feat: add note field support and input transaction ID retrieval (#30)

* feat: add note field support and input transaction ID retrieval

Add the ability to set a custom note on the user-signed input transaction
and retrieve its transaction ID for tracking purposes.

Changes:
- Add optional `note` config to SwapComposerConfig and newSwap()
- Add `getInputTransactionId()` method to SwapComposer
- Track the input transaction index during swap processing
- Add comprehensive tests for note configuration and ID retrieval

The note is only applied to the user-signed payment or asset transfer
transaction (not pre-signed or middleware transactions). The transaction
ID is available after calling buildGroup(), sign(), or execute().

* docs: add note and getInputTransactionId to README

Document the new transaction tracking features:
- Add 'Transaction Tracking' section with usage example
- Add 'note' parameter to newSwap() API reference table
- Add 'getInputTransactionId()' to SwapComposer methods table

Author: drichar

packages/deflex/README.md

@@ -120,6 +120,28 @@ console.log(`Confirmed in round ${result.confirmedRound}`)
 console.log('Transaction IDs:', result.txIds)
 ```
 
+### Transaction Tracking
+
+Add a custom note to the input transaction for tracking purposes, and retrieve its transaction ID after execution:
+
+```typescript
+const swap = await deflex.newSwap({
+  quote,
+  address: activeAddress,
+  signer: transactionSigner,
+  slippage: 1,
+  note: new TextEncoder().encode('tracking-id-123'), // Custom note for tracking
+})
+
+const result = await swap.execute()
+
+// Get the transaction ID of the user-signed input transaction
+const inputTxId = swap.getInputTransactionId()
+console.log('Input transaction ID:', inputTxId)
+```
+
+The `note` is applied only to the user-signed payment or asset transfer transaction (not pre-signed or middleware transactions). The transaction ID is available after calling `buildGroup()`, `sign()`, or `execute()`.
+
 ### Transaction Signing
 
 The SDK supports both standard `algosdk.TransactionSigner` and ARC-1 compliant signer functions.
@@ -395,6 +417,7 @@ async newSwap(config: SwapComposerConfig): Promise<SwapComposer>
 | `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)[]>)` |
+| `note`     | Optional note for the user-signed input transaction (for tracking purposes) | `Uint8Array`                                                                                             |
 
 #### DeflexClient.needsAssetOptIn()
 
@@ -458,6 +481,7 @@ Builder for constructing and executing atomic swap transaction groups, returned
 | `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`                                                                           |
+| `getInputTransactionId()`              | Get the transaction ID of the user-signed input transaction (available after `buildGroup()`, `sign()`, or `execute()`) | None                                                           | `string \| undefined`                                                              |
 
 ## Documentation
 

packages/deflex/src/client.ts

@@ -409,8 +409,10 @@ export class DeflexClient {
     address: string
     slippage: number
     signer: TransactionSigner | SignerFunction
+    /** Optional note field for the user-signed input transaction (payment or asset transfer) */
+    note?: Uint8Array
   }): Promise<SwapComposer> {
-    const { quote, address, slippage, signer } = config
+    const { quote, address, slippage, signer, note } = config
 
     const swapResponse = await this.fetchSwapTransactions({
       quote,
@@ -426,6 +428,7 @@ export class DeflexClient {
       address,
       signer,
       middleware: this.middleware,
+      note,
     })
 
     return composer

packages/deflex/src/composer.ts

@@ -73,6 +73,8 @@ export interface SwapComposerConfig {
   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
 }
 
 /**
@@ -110,6 +112,8 @@ export class SwapComposer {
   private readonly address: string
   private readonly signer: TransactionSigner | SignerFunction
   private readonly middleware: SwapMiddleware[]
+  private readonly note?: Uint8Array
+  private inputTransactionIndex?: number
 
   /**
    * Create a new SwapComposer instance
@@ -150,6 +154,7 @@ export class SwapComposer {
     this.address = this.validateAddress(config.address)
     this.signer = config.signer
     this.middleware = config.middleware ?? []
+    this.note = config.note
   }
 
   /**
@@ -282,7 +287,8 @@ export class SwapComposer {
     }
 
     // Process swap transactions and execute afterSwap hooks
-    const processedTxns = await this.processSwapTransactions()
+    const { txns: processedTxns, userSignedTxnRelativeIndex } =
+      await this.processSwapTransactions()
     const afterTxns = await this.executeMiddlewareHooks('afterSwap')
 
     // Check total length before adding swap and afterSwap transactions
@@ -295,6 +301,12 @@ export class SwapComposer {
       )
     }
 
+    // Calculate the absolute index of the user-signed input transaction
+    // This is: current ATC count (user txns + beforeSwap) + relative index within processed txns
+    if (userSignedTxnRelativeIndex !== undefined) {
+      this.inputTransactionIndex = this.atc.count() + userSignedTxnRelativeIndex
+    }
+
     // Add swap transactions
     for (const txnWithSigner of processedTxns) {
       this.atc.addTransaction(txnWithSigner)
@@ -425,6 +437,46 @@ export class SwapComposer {
     }
   }
 
+  /**
+   * 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 deflex.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 {
+    if (this.getStatus() < SwapComposerStatus.BUILT) {
+      return undefined
+    }
+    if (this.inputTransactionIndex === undefined) {
+      return undefined
+    }
+    const txns = this.atc.buildGroup()
+    const txn = txns[this.inputTransactionIndex]?.txn
+    return txn?.txID()
+  }
+
   /**
    * Validates an Algorand address
    */
@@ -438,10 +490,15 @@ export class SwapComposer {
   /**
    * Processes app opt-ins and decodes swap transactions from API response
    */
-  private async processSwapTransactions(): Promise<TransactionWithSigner[]> {
+  private async processSwapTransactions(): Promise<{
+    txns: TransactionWithSigner[]
+    userSignedTxnRelativeIndex?: number
+  }> {
     const appOptIns = await this.processRequiredAppOptIns()
 
     const swapTxns: TransactionWithSigner[] = []
+    let userSignedTxnRelativeIndex: number | undefined
+
     for (let i = 0; i < this.deflexTxns.length; i++) {
       const deflexTxn = this.deflexTxns[i]
       if (!deflexTxn) continue
@@ -459,6 +516,13 @@ export class SwapComposer {
           })
         } else {
           // User transaction - use configured signer
+          // Set the note if provided (using type assertion since note is readonly but safe to modify before signing)
+          if (this.note !== undefined) {
+            ;(txn as { note: Uint8Array }).note = this.note
+          }
+          // Track the relative index within processed transactions (after app opt-ins)
+          userSignedTxnRelativeIndex = appOptIns.length + swapTxns.length
+
           swapTxns.push({
             txn,
             signer: this.defaultSigner,
@@ -471,7 +535,10 @@ export class SwapComposer {
       }
     }
 
-    return [...appOptIns, ...swapTxns]
+    return {
+      txns: [...appOptIns, ...swapTxns],
+      userSignedTxnRelativeIndex,
+    }
   }
 
   /**