@lukso/transaction-view-headless 0.4.3 → 0.4.4-dev.c5d67d4

package/TRANSACTION_MODIFICATION_GUIDE.md

@@ -0,0 +1,927 @@
+# Transaction Modification Guide
+
+This guide explains how transaction views can modify transaction data through an event-based system, including handling of wrapped transactions and batches.
+
+## Problem
+
+Transaction views often need to allow users to modify transaction parameters before submission:
+
+- **Force Transfer Checkbox**: Enable force flag for LSP7 transfers to EOA addresses
+- **Slippage Tolerance**: Adjust acceptable slippage for DEX swaps
+- **Allowance Amount**: Modify token approval amounts
+- **Gas Settings**: Change gas limits or priorities
+
+These modifications must work correctly even within wrapped transactions (Execute calls) and batch operations.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────┐
+│  View Component (LSP7 Transfer)         │
+│  - User clicks "Force Transfer" checkbox│
+│  - View re-encodes local transaction    │
+│  - Emits modification event              │
+│    { data: "0xnewdata...", index: 2 }   │
+└──────────────┬──────────────────────────┘
+               │ bubbles up
+               ▼
+┌─────────────────────────────────────────┐
+│  <transaction-playback> (index 2)       │
+│  - Validates modification                │
+│  - Re-decodes to verify                  │
+│  - Adds transaction path info            │
+│  - Re-emits with context                 │
+└──────────────┬──────────────────────────┘
+               │ bubbles up
+               ▼
+┌─────────────────────────────────────────┐
+│  Top-Level Container                     │
+│  - Navigates to correct transaction      │
+│  - Applies modification                  │
+│  - Re-wraps if needed (Execute/Batch)    │
+│  - Re-decodes entire tree                │
+│  - Updates UI                            │
+└─────────────────────────────────────────┘
+```
+
+## The Wrapping Challenge
+
+Consider this transaction structure:
+
+```
+ExecuteRelayCall (top level - signed by controller)
+└─ signature: 0x...
+└─ data: "0xaabbcc..." (encoded execute)
+   └─ Decoded: Execute
+      ├─ target: 0xProfile
+      ├─ data: "0x112233..." (encoded executeBatch)
+      └─ Decoded: ExecuteBatch
+         ├─ Child[0]: Execute
+         │  ├─ target: 0xTokenContract
+         │  ├─ data: "0x445566..." (encoded transfer)
+         │  └─ Decoded: transfer(from, to, amount, force=false, data)
+         │
+         └─ Child[1]: SetData
+            └─ setData(key, value)
+```
+
+When the transfer view modifies `force` to `true`:
+
+1. ✅ View encodes **local** transaction data: `transfer(..., force=true, ...)`
+2. ✅ Parent **recomposes** the original wrappers:
+   - Insert new transfer data into Execute wrapper (preserving target, value)
+   - Recompose ExecuteBatch with updated Execute (preserving other children)
+   - Recompose ExecuteRelayCall with updated ExecuteBatch (preserving signature, nonce)
+3. ✅ Parent re-decodes entire transaction to verify and update UI
+
+**Key Insights**:
+- Views only handle their own level
+- Parents **recompose** original wrappers (don't create new ones)
+- All original wrapper arguments are preserved (signatures, nonces, targets, etc.)
+
+## Type Definitions
+
+```typescript
+interface TransactionModification {
+  /**
+   * The modified data for THIS transaction level
+   * NOT the top-level transaction data
+   *
+   * This is the encoded function call for the current transaction,
+   * not wrapped in Execute or Batch calls.
+   */
+  data: `0x${string}`
+
+  /**
+   * The playback index this modification applies to
+   *
+   * - 0 = batch summary (modifies batch itself)
+   * - 1 = first transaction (or single tx)
+   * - 2 = second child transaction
+   * - etc.
+   *
+   * This matches the `index` prop of <transaction-playback>
+   */
+  transactionIndex: number
+
+  /**
+   * Human-readable explanation of why this modification occurred
+   *
+   * @example "User enabled force transfer to EOA"
+   * @example "Slippage tolerance increased to 2%"
+   */
+  reason: string
+
+  /**
+   * Whether this modification was triggered by user interaction
+   *
+   * - true: User clicked checkbox, changed input, etc.
+   * - false: Automatic adjustment by view logic
+   */
+  userInitiated: boolean
+
+  /**
+   * Optional structured summary for quick display/logging
+   */
+  summary?: {
+    /** Name of the field that changed */
+    field: string
+
+    /** Human-readable old value */
+    oldValue: string
+
+    /** Human-readable new value */
+    newValue: string
+  }
+
+  /**
+   * Optional validation information
+   */
+  validation?: {
+    isValid: boolean
+    error?: string
+    warnings?: string[]
+  }
+}
+
+/**
+ * Extended modification info added by transaction-playback
+ * This is what the top-level container receives
+ */
+interface TransactionModificationWithContext extends TransactionModification {
+  /**
+   * Path from root transaction to this transaction
+   *
+   * @example [1] - Simple transaction at index 1
+   * @example [0, 2] - Batch at index 0, child at index 2
+   * @example [0, 1, 0] - Nested batch: batch[0].children[1].children[0]
+   */
+  transactionPath: number[]
+
+  /**
+   * The full local transaction object with modified data
+   */
+  localTransaction: DecoderResult
+
+  /**
+   * Re-decoded result for verification
+   */
+  decodedResult: DecoderResult
+}
+```
+
+## View Implementation
+
+### Basic Example: Force Transfer Checkbox
+
+```typescript
+import { dispatchTransactionModification, getArgByName } from '@lukso/transaction-view-headless'
+import { encodeFunctionData } from 'viem'
+
+@customElement('lsp7-transfer-view')
+export class LSP7TransferView extends CoreLitElement {
+  @property({ type: Object }) transaction!: DecoderResult
+  @property({ type: String }) context?: ViewContext
+  @property({ type: Number }) index!: number  // From transaction-playback
+
+  @state()
+  private forceTransfer = false
+
+  connectedCallback() {
+    super.connectedCallback()
+    // Initialize from transaction
+    this.forceTransfer = (getArgByName(this.transaction.args, 'force') as boolean) ?? false
+  }
+
+  private handleForceChange(checked: boolean) {
+    this.forceTransfer = checked
+
+    // Re-encode with new force value
+    const newData = encodeFunctionData({
+      abi: LSP7_ABI,
+      functionName: 'transfer',
+      args: [
+        getArgByName(this.transaction.args, 'from'),
+        getArgByName(this.transaction.args, 'to'),
+        getArgByName(this.transaction.args, 'amount'),
+        checked,  // <-- modified
+        getArgByName(this.transaction.args, 'data')
+      ]
+    })
+
+    // Emit modification event
+    dispatchTransactionModification(this, {
+      data: newData,
+      transactionIndex: this.index,
+      reason: checked
+        ? 'User enabled force transfer to EOA'
+        : 'User disabled force transfer',
+      userInitiated: true,
+      summary: {
+        field: 'force',
+        oldValue: String(!checked),
+        newValue: String(checked)
+      }
+    })
+  }
+
+  render() {
+    // Context-aware rendering
+    if (this.context === 'approval') {
+      // Show interactive checkbox
+      return html`
+        <div class="transfer-content">
+          <!-- Transfer details -->
+
+          <label class="flex items-center gap-2 mt-4">
+            <input
+              type="checkbox"
+              .checked=${this.forceTransfer}
+              @change=${(e) => this.handleForceChange(e.target.checked)}
+            />
+            <span>Force transfer (required for EOA recipients)</span>
+          </label>
+        </div>
+      `
+    } else if (this.context === 'feed') {
+      // Show read-only status
+      return html`
+        <div class="transfer-summary">
+          <!-- Compact transfer info -->
+          ${this.forceTransfer ? html`
+            <div class="text-12 text-orange-600">⚠️ Forced transfer</div>
+          ` : ''}
+        </div>
+      `
+    } else {
+      // Detail view
+      return html`
+        <div class="transfer-details">
+          <!-- Full transfer info -->
+          <div class="mt-4">
+            <strong>Force:</strong> ${this.forceTransfer ? 'Yes' : 'No'}
+            ${this.forceTransfer ? html`
+              <div class="text-12 text-neutral-60">
+                This transfer will succeed even if recipient is an EOA
+              </div>
+            ` : ''}
+          </div>
+        </div>
+      `
+    }
+  }
+}
+```
+
+### Advanced Example: Slippage Tolerance
+
+```typescript
+@customElement('swap-view')
+export class SwapView extends CoreLitElement {
+  @property({ type: Object }) transaction!: DecoderResult
+  @property({ type: Number }) index!: number
+
+  @state()
+  private slippageBps = 50  // 0.5% default
+
+  private handleSlippageChange(bps: number) {
+    this.slippageBps = bps
+
+    // Recalculate minimum output with new slippage
+    const minOutput = this.calculateMinOutput(
+      getArgByName(this.transaction.args, 'amountOut') as bigint,
+      bps
+    )
+
+    // Re-encode swap with new minimum
+    const newData = encodeFunctionData({
+      abi: SWAP_ABI,
+      functionName: 'swap',
+      args: [
+        getArgByName(this.transaction.args, 'tokenIn'),
+        getArgByName(this.transaction.args, 'tokenOut'),
+        getArgByName(this.transaction.args, 'amountIn'),
+        minOutput,  // <-- modified
+        getArgByName(this.transaction.args, 'recipient')
+      ]
+    })
+
+    dispatchTransactionModification(this, {
+      data: newData,
+      transactionIndex: this.index,
+      reason: `User adjusted slippage tolerance to ${bps / 100}%`,
+      userInitiated: true,
+      summary: {
+        field: 'slippage',
+        oldValue: `${this.slippageBps / 100}%`,
+        newValue: `${bps / 100}%`
+      },
+      validation: {
+        isValid: bps <= 1000,  // Max 10%
+        warnings: bps > 500 ? ['High slippage may result in unfavorable trade'] : []
+      }
+    })
+  }
+
+  render() {
+    return html`
+      <div>
+        <label>
+          Slippage Tolerance: ${this.slippageBps / 100}%
+          <input
+            type="range"
+            min="10"
+            max="1000"
+            step="10"
+            .value=${String(this.slippageBps)}
+            @input=${(e) => this.handleSlippageChange(Number(e.target.value))}
+          />
+        </label>
+      </div>
+    `
+  }
+}
+```
+
+## Parent Container Implementation
+
+### In transaction-playback Component
+
+```typescript
+// Already implemented in transaction-playback.ts
+connectedCallback(): void {
+  super.connectedCallback()
+  this.addEventListener(
+    TransactionViewEvents.TRANSACTION_MODIFICATION,
+    this.handleTransactionModification as EventListener
+  )
+}
+
+private handleTransactionModification = (event: Event): void => {
+  if (!isTransactionModificationEvent(event)) return
+
+  const mod = event.detail
+
+  // Verify this modification is for our transaction
+  if (mod.transactionIndex !== this.index) {
+    console.warn(`Modification index mismatch: expected ${this.index}, got ${mod.transactionIndex}`)
+    return
+  }
+
+  // Create modified local transaction
+  const modifiedLocal: DecoderResult = {
+    ...this.currentResult.transaction,
+    data: mod.data
+  }
+
+  // Re-decode to verify
+  const reDecoded = await decoder.decode(modifiedLocal)
+
+  // Add context and re-emit for top-level container
+  this.dispatchEvent(
+    new CustomEvent(TransactionViewEvents.TRANSACTION_MODIFICATION, {
+      bubbles: true,
+      composed: true,
+      detail: {
+        ...mod,
+        transactionPath: this.getTransactionPath(),
+        localTransaction: modifiedLocal,
+        decodedResult: reDecoded
+      } as TransactionModificationWithContext
+    })
+  )
+}
+
+private getTransactionPath(): number[] {
+  // Get path from root to current transaction
+  return this.playbackState.getTransactionPath(this.index)
+}
+```
+
+### In Top-Level Container (Wallet/App)
+
+```typescript
+class WalletApprovalScreen extends LitElement {
+  @state()
+  private originalTransaction: DecoderResult
+
+  @state()
+  private modifiedTransaction?: DecoderResult
+
+  @state()
+  private modifications: TransactionModificationWithContext[] = []
+
+  render() {
+    return html`
+      <div class="approval-screen">
+        <h2>Approve Transaction</h2>
+
+        <!-- Show modification summary if any -->
+        ${this.modifications.length > 0 ? html`
+          <div class="modifications-summary">
+            <h3>User Modifications:</h3>
+            ${this.modifications.map(mod => html`
+              <div class="modification-item">
+                <span class="icon">✏️</span>
+                <span>${mod.reason}</span>
+                ${mod.summary ? html`
+                  <span class="change">
+                    ${mod.summary.field}:
+                    ${mod.summary.oldValue} → ${mod.summary.newValue}
+                  </span>
+                ` : ''}
+              </div>
+            `)}
+          </div>
+        ` : ''}
+
+        <!-- Transaction view (will re-render with modifications) -->
+        <transaction-playback
+          .transaction=${this.modifiedTransaction ?? this.originalTransaction}
+          index="1"
+          context="approval"
+          @transaction-modification=${this.handleModification}
+        ></transaction-playback>
+
+        <div class="actions">
+          <button @click=${this.reject}>Reject</button>
+          <button @click=${this.approve}>Approve</button>
+        </div>
+      </div>
+    `
+  }
+
+  private async handleModification(event: CustomEvent) {
+    const mod: TransactionModificationWithContext = event.detail
+
+    // Store modification
+    this.modifications.push(mod)
+
+    // Recompose the original transaction with the modification
+    const recomposed = await this.recomposeTransaction(
+      this.originalTransaction,
+      mod
+    )
+
+    // Update state - this triggers re-render
+    this.modifiedTransaction = recomposed
+  }
+
+  /**
+   * Recompose the original transaction with a modification
+   *
+   * Takes the original transaction structure and inserts the modified data
+   * at the correct location, preserving all original wrappers (Execute,
+   * ExecuteBatch, ExecuteRelayCall, etc.)
+   *
+   * Example:
+   *   Original: executeRelayCall(execute(executeBatch([transfer, setData])))
+   *   Modified: executeRelayCall(execute(executeBatch([transfer*, setData])))
+   *   (* = transfer with force=true)
+   */
+  private async recomposeTransaction(
+    originalTx: DecoderResult,
+    mod: TransactionModificationWithContext
+  ): Promise<DecoderResult> {
+    const { transactionPath, data } = mod
+
+    // Clone the original transaction to preserve structure
+    const recomposed = structuredClone(originalTx)
+
+    if (transactionPath.length === 1) {
+      // Simple transaction - just replace data
+      recomposed.data = data
+    } else {
+      // Complex transaction - navigate and recompose wrappers
+      await this.recomposeAtPath(recomposed, transactionPath, data)
+    }
+
+    // Re-decode entire transaction tree to verify and get fresh DecoderResult
+    const reDecoded = await decoder.decode(recomposed)
+
+    return reDecoded
+  }
+
+  /**
+   * Navigate to a transaction path and recompose wrappers bottom-up
+   *
+   * Example path [0, 1, 2] means:
+   *   - Navigate to batch[0].children[1].children[2]
+   *   - Replace that transaction's data
+   *   - Recompose batch[0].children[1] wrapper with updated child
+   *   - Recompose batch[0] wrapper with updated child
+   *   - Recompose root with updated batch
+   */
+  private async recomposeAtPath(
+    root: any,
+    path: number[],
+    newData: string
+  ): Promise<void> {
+    // Navigate to the target transaction
+    let current = root
+    const parents: any[] = [root]
+
+    for (let i = 0; i < path.length - 1; i++) {
+      const index = path[i]
+      if (current.children?.[index]) {
+        current = current.children[index]
+        parents.push(current)
+      } else {
+        throw new Error(`Invalid transaction path: ${path}`)
+      }
+    }
+
+    // Apply modification to the target
+    const targetIndex = path[path.length - 1]
+    if (!current.children?.[targetIndex]) {
+      throw new Error(`Invalid transaction path: ${path}`)
+    }
+
+    current.children[targetIndex].data = newData
+
+    // Recompose wrappers bottom-up
+    // Start from the deepest parent and work up to root
+    for (let i = parents.length - 1; i >= 0; i--) {
+      const parent = parents[i]
+      if (parent.children && parent.functionName) {
+        parent.data = await this.recomposeWrapper(parent)
+      }
+    }
+  }
+
+  /**
+   * Recompose a wrapper transaction (Execute, ExecuteBatch, ExecuteRelayCall, etc.)
+   *
+   * Takes the original wrapper and re-encodes it with updated child data,
+   * preserving all original arguments (operationType, target, value, signature, etc.)
+   */
+  private async recomposeWrapper(wrapper: any): Promise<string> {
+    const { functionName, args, children } = wrapper
+
+    // Recompose based on wrapper type
+    switch (functionName) {
+      case 'execute':
+        return encodeFunctionData({
+          abi: UP_ABI,
+          functionName: 'execute',
+          args: [
+            getArgByName(args, 'operationType') as number,
+            getArgByName(args, 'target') as string,
+            getArgByName(args, 'value') as bigint,
+            children[0].data  // <-- updated child data
+          ]
+        })
+
+      case 'executeBatch':
+        return encodeFunctionData({
+          abi: UP_ABI,
+          functionName: 'executeBatch',
+          args: [
+            getArgByName(args, 'operationTypes') as number[],
+            getArgByName(args, 'targets') as string[],
+            getArgByName(args, 'values') as bigint[],
+            children.map((child: any) => child.data)  // <-- updated children data
+          ]
+        })
+
+      case 'executeRelayCall':
+        return encodeFunctionData({
+          abi: KEY_MANAGER_ABI,
+          functionName: 'executeRelayCall',
+          args: [
+            getArgByName(args, 'signature') as string,
+            getArgByName(args, 'nonce') as bigint,
+            getArgByName(args, 'validityTimestamps') as bigint,
+            children[0].data  // <-- updated execute/executeBatch data
+          ]
+        })
+
+      default:
+        throw new Error(`Unknown wrapper function: ${functionName}`)
+    }
+  }
+
+  private async approve() {
+    // Submit the recomposed transaction (or original if no modifications)
+    const finalTx = this.modifiedTransaction ?? this.originalTransaction
+
+    // Log modifications for audit trail
+    if (this.modifications.length > 0) {
+      console.log('Transaction modifications:', this.modifications)
+    }
+
+    // Send transaction
+    await this.wallet.sendTransaction(finalTx)
+  }
+}
+```
+
+## Helper Functions
+
+### dispatchTransactionModification
+
+```typescript
+/**
+ * Helper function to dispatch transaction modification event
+ * Use this in view components to emit modifications
+ */
+export function dispatchTransactionModification(
+  element: HTMLElement,
+  modification: TransactionModification
+): void {
+  element.dispatchEvent(
+    new CustomEvent(TransactionViewEvents.TRANSACTION_MODIFICATION, {
+      bubbles: true,
+      composed: true,
+      detail: modification,
+    })
+  )
+}
+```
+
+### isTransactionModificationEvent
+
+```typescript
+/**
+ * Type guard to check if an event is a TransactionModificationEvent
+ */
+export function isTransactionModificationEvent(
+  event: Event
+): event is CustomEvent<TransactionModification> {
+  return (
+    event instanceof CustomEvent &&
+    event.type === TransactionViewEvents.TRANSACTION_MODIFICATION
+  )
+}
+```
+
+## Security Considerations
+
+### 1. Always Re-decode
+
+The parent container **must** re-decode modified data to verify it's valid:
+
+```typescript
+// ✅ Good - Re-decode and verify
+const reDecoded = await decoder.decode({ ...tx, data: mod.data })
+if (!reDecoded) {
+  throw new Error('Invalid modification - failed to decode')
+}
+```
+
+### 2. Show Modifications to User
+
+Display what changed before submission:
+
+```typescript
+// ✅ Good - User sees what changed
+<div class="modifications">
+  ${modifications.map(mod => html`
+    <div>${mod.reason}</div>
+    ${mod.summary ? html`
+      <div>${mod.summary.field}: ${mod.summary.oldValue} → ${mod.summary.newValue}</div>
+    ` : ''}
+  `)}
+</div>
+```
+
+### 3. Validate Modifications
+
+Check that modifications make sense:
+
+```typescript
+// ✅ Good - Validate before applying
+if (mod.validation && !mod.validation.isValid) {
+  showError(mod.validation.error)
+  return
+}
+
+if (mod.validation?.warnings) {
+  showWarnings(mod.validation.warnings)
+}
+```
+
+### 4. Audit Trail
+
+Log all modifications:
+
+```typescript
+// ✅ Good - Keep audit trail
+console.log('Transaction modified:', {
+  transactionHash: tx.hash,
+  modifications: modifications.map(m => ({
+    field: m.summary?.field,
+    oldValue: m.summary?.oldValue,
+    newValue: m.summary?.newValue,
+    reason: m.reason,
+    userInitiated: m.userInitiated,
+    timestamp: Date.now()
+  }))
+})
+```
+
+## Best Practices
+
+### 1. Emit Modifications Immediately
+
+Don't batch modifications - emit each change as it happens:
+
+```typescript
+// ✅ Good
+private handleChange(value: string) {
+  this.emitModification(value)
+}
+
+// ❌ Bad - Don't batch
+private handleChange(value: string) {
+  this.pendingChanges.push(value)
+  // Emit later somehow?
+}
+```
+
+### 2. Include Transaction Index
+
+Always include the correct transaction index:
+
+```typescript
+// ✅ Good
+dispatchTransactionModification(this, {
+  data: newData,
+  transactionIndex: this.index,  // From transaction-playback
+  // ...
+})
+
+// ❌ Bad - Hardcoded or missing
+dispatchTransactionModification(this, {
+  data: newData,
+  transactionIndex: 1,  // Wrong!
+  // ...
+})
+```
+
+### 3. Provide Good Reasons
+
+Write clear, human-readable reasons:
+
+```typescript
+// ✅ Good
+reason: 'User enabled force transfer to allow sending to EOA addresses'
+
+// ❌ Bad
+reason: 'force=true'
+```
+
+### 4. Context-Aware UI
+
+Show appropriate UI based on context:
+
+```typescript
+render() {
+  if (this.context === 'approval') {
+    // Interactive controls
+    return html`<input type="checkbox" @change=${this.handleChange} />`
+  } else {
+    // Read-only display
+    return html`<div>Force: ${this.force}</div>`
+  }
+}
+```
+
+## Transaction Path Examples
+
+### Simple Transaction
+```
+Transaction (index: 1)
+Path: [1]
+```
+
+### Execute Wrapper
+```
+Execute (index: 0)
+└─ Transfer (index: 1)
+   Path: [0, 1]
+```
+
+### Batch
+```
+ExecuteBatch (index: 0)
+├─ Transfer (index: 1)
+│  Path: [0, 1]
+└─ SetData (index: 2)
+   Path: [0, 2]
+```
+
+### Nested Batch
+```
+ExecuteBatch (index: 0)
+├─ ExecuteBatch (index: 1)
+│  ├─ Transfer (index: 1, 0)
+│  │  Path: [0, 1, 0]
+│  └─ Transfer (index: 1, 1)
+│     Path: [0, 1, 1]
+└─ SetData (index: 2)
+   Path: [0, 2]
+```
+
+## Event Constants
+
+Use constants instead of hardcoding strings:
+
+```typescript
+import { TransactionViewEvents } from '@lukso/transaction-view-headless'
+
+// ✅ Good
+this.addEventListener(TransactionViewEvents.TRANSACTION_MODIFICATION, handler)
+
+// ❌ Bad
+this.addEventListener('transaction-modification', handler)
+```
+
+## Complete Flow Example
+
+```
+1. User clicks "Force Transfer" checkbox in LSP7TransferView
+   └─> View re-encodes transfer(from, to, amount, true, data)
+   └─> Emits { data: "0x...", transactionIndex: 1, reason: "..." }
+
+2. <transaction-playback index="1"> receives event
+   └─> Validates: mod.transactionIndex === this.index ✓
+   └─> Re-decodes: decoder.decode({ ...tx, data: mod.data }) ✓
+   └─> Adds path: transactionPath: [0, 1] (Execute wrapper)
+   └─> Re-emits with full context
+
+3. Top-level container receives event
+   └─> Clones original transaction structure
+   └─> Navigates to path [0, 1]
+   └─> Replaces children[1].data with mod.data
+   └─> Recomposes wrappers bottom-up:
+       - Recompose execute(target, value, newTransferData)
+       - Recompose executeBatch([newExecuteData, setDataData])
+       - Recompose executeRelayCall(signature, nonce, newExecuteBatchData)
+   └─> Re-decodes entire tree to verify
+   └─> Updates state
+   └─> UI re-renders with modified transaction
+
+4. User sees updated transaction in approval screen
+   └─> "Force: false → true" shown in modifications list
+   └─> Transaction view shows updated state
+   └─> User clicks "Approve"
+   └─> Recomposed transaction is submitted (with original signature intact!)
+```
+
+## Why Recomposition Matters
+
+### ❌ Wrong: Create New Wrappers
+
+```typescript
+// DON'T DO THIS
+const newExecute = encodeFunctionData({
+  abi: UP_ABI,
+  functionName: 'execute',
+  args: [0, target, 0, modifiedData]  // <-- New wrapper, loses context
+})
+
+// This breaks:
+// - Original operationType is lost
+// - Original value is lost
+// - Signature becomes invalid (data changed)
+// - Nonce might be wrong
+```
+
+### ✅ Correct: Recompose Original Wrappers
+
+```typescript
+// DO THIS
+const recomposed = structuredClone(originalTransaction)
+
+// Navigate and update
+recomposed.children[0].children[1].data = modifiedData
+
+// Recompose preserving ALL original args
+recomposed.children[0].data = encodeFunctionData({
+  abi: UP_ABI,
+  functionName: 'execute',
+  args: [
+    getArgByName(originalTransaction.children[0].args, 'operationType') as number,  // ✓ Preserved
+    getArgByName(originalTransaction.children[0].args, 'target') as string,         // ✓ Preserved
+    getArgByName(originalTransaction.children[0].args, 'value') as bigint,          // ✓ Preserved
+    modifiedData                                                                     // ✓ Updated
+  ]
+})
+
+// This preserves:
+// - Original operationType
+// - Original value
+// - Signature validity (if recomposed correctly)
+// - All other wrapper arguments
+```
+
+### Key Principle
+
+**Always start with the original transaction and recompose it, never create new wrappers from scratch.**
+
+This ensures:
+1. ✅ All wrapper arguments are preserved
+2. ✅ Signatures remain valid (if signing over final data)
+3. ✅ Context is maintained (nonces, timestamps, etc.)
+4. ✅ Only the intended modification is applied