From 2738319c8de9867e87cc7d2fe44665a7b83a1f87 Mon Sep 17 00:00:00 2001
From: junman140 <godswillitina@gmail.com>
Date: Wed, 27 May 2026 11:46:18 +0100
Subject: [PATCH 1/3] feat: implement batch subscription operations for bulk
 management

Add batch create from CSV/JSON, batch update with filtering, batch cancel with reason collection, and batch charge for manual billing runs.

- contracts/batch: Added CancelReason enum, BatchFilter struct, enhanced result types with skipped_operations tracking
- app/services/batchTransactionService.ts: Full rewrite with 4 operation types, CSV parsers, chunked processing, idempotent retry with backoff, result export, per-item status tracking
- app/stores/batchStore.ts: Zustand store with draft management, CSV loading per operation type, execute/retry, export helpers
- app/screens/BatchOperationsScreen.tsx: Full UI with operation selector, CSV input, update params/filter modals, cancel reason picker, progress bar, per-item results, export buttons, retry, history
- src/screens/ImportScreen.tsx: Added batch operations shortcut banner
- src/navigation: Added BatchOperations route to SettingsStack

Edge cases: partial batch failure, idempotent retry of failed items, large batch memory management via chunked processing
---
 app/screens/BatchOperationsScreen.tsx      | 1218 ++++++++++++++++++--
 app/services/batchTransactionService.ts    | 1124 +++++++++++++-----
 app/services/hooks/useBatchTransactions.ts |  214 ++--
 app/stores/__tests__/batchStore.test.ts    |  115 +-
 app/stores/batchStore.ts                   |  507 +++++---
 contracts/batch/src/batch.rs               |   27 +
 contracts/batch/src/lib.rs                 |    5 +-
 src/navigation/AppNavigator.tsx            |   34 +-
 src/navigation/types.ts                    |    1 +
 src/screens/ImportScreen.tsx               |   33 +-
 10 files changed, 2622 insertions(+), 656 deletions(-)

diff --git a/app/screens/BatchOperationsScreen.tsx b/app/screens/BatchOperationsScreen.tsx
index feb321c..6267a85 100644
--- a/app/screens/BatchOperationsScreen.tsx
+++ b/app/screens/BatchOperationsScreen.tsx
@@ -1,121 +1,1161 @@
-import React, { useState } from 'react';
-import { View, Text, TextInput, Button, FlatList, StyleSheet } from 'react-native';
+import React, { useState, useCallback, useEffect } from 'react';
+import {
+  View,
+  Text,
+  TextInput,
+  FlatList,
+  StyleSheet,
+  SafeAreaView,
+  ScrollView,
+  TouchableOpacity,
+  Alert,
+  Share,
+  Switch,
+  Modal,
+  ActivityIndicator,
+} from 'react-native';
 import {
   useBatchStore,
-  OperationType,
-  estimateBatchGas,
+  BatchOperationType,
+  BatchState,
+  PerItemResult,
+  CancelReason,
+  BatchHistoryEntry,
+  exportBatchResultToJson as exportJson,
+  exportBatchResultToCsv as exportCsv,
 } from '../stores/batchStore';
+import { colors, spacing, typography, borderRadius } from '../../src/utils/constants';
 
-const styles = StyleSheet.create({
-  container: { flex: 1, padding: 16 },
-  header: { fontSize: 18, fontWeight: '700', marginVertical: 8 },
-  label: { fontSize: 12, color: '#666', marginTop: 8 },
-  input: {
-    minHeight: 40,
-    borderColor: '#ccc',
-    borderWidth: 1,
-    paddingHorizontal: 8,
-    borderRadius: 4,
-    marginTop: 4,
-  },
-  row: { flexDirection: 'row', flexWrap: 'wrap', marginVertical: 8 },
-  chip: {
-    paddingHorizontal: 10,
-    paddingVertical: 6,
-    borderRadius: 16,
-    borderWidth: 1,
-    borderColor: '#ccc',
-    marginRight: 6,
-    marginBottom: 6,
-  },
-  chipActive: { backgroundColor: '#dbeafe', borderColor: '#2563eb' },
-  meta: { fontSize: 12, color: '#444', marginVertical: 4 },
-  item: { paddingVertical: 6, borderBottomWidth: 1, borderColor: '#eee' },
-  success: { color: '#15803d' },
-  failure: { color: '#b91c1c' },
-});
+// ════════════════════════════════════════════════════════════════
+// Constants
+// ════════════════════════════════════════════════════════════════
+
+const OPERATION_TYPES: Array<{ key: BatchOperationType; label: string; icon: string }> = [
+  { key: 'create', label: 'Create', icon: '+' },
+  { key: 'update', label: 'Update', icon: '-' },
+  { key: 'charge', label: 'Charge', icon: '$' },
+  { key: 'cancel', label: 'Cancel', icon: 'X' },
+];
+
+const CANCEL_REASONS: Array<{ key: CancelReason['reason']; label: string }> = [
+  { key: 'too_expensive', label: 'Too Expensive' },
+  { key: 'no_longer_needed', label: 'No Longer Needed' },
+  { key: 'found_alternative', label: 'Found Alternative' },
+  { key: 'poor_service', label: 'Poor Service' },
+  { key: 'other', label: 'Other' },
+];
 
-const OPERATIONS: OperationType[] = ['charge', 'pause', 'resume', 'cancel', 'update', 'create'];
+const STATE_COLORS: Record<BatchState, string> = {
+  pending: colors.textSecondary,
+  running: colors.warning,
+  completed: colors.success,
+  partial: colors.warning,
+  failed: colors.error,
+};
+
+// ════════════════════════════════════════════════════════════════
+// Component
+// ════════════════════════════════════════════════════════════════
 
 export const BatchOperationsScreen: React.FC = () => {
-  const { draft, current, setDraft, loadFromCsv, createBatch, executeBatch, resetDraft } =
-    useBatchStore();
-  const [csv, setCsv] = useState('subscriptionId,amount\nsub_1,1000\nsub_2,1000');
-  const [busy, setBusy] = useState(false);
+  const {
+    draft,
+    currentResult,
+    history,
+    isRunning,
+    progress,
+    setOperationType,
+    toggleAtomic,
+    setChunkSize,
+    setCsvContent,
+    loadCreateCsv,
+    loadCancelCsv,
+    loadChargeCsv,
+    loadUpdateCsv,
+    setDraft,
+    executeBatch,
+    retryFailed,
+    exportResultJson,
+    exportResultCsv,
+    resetDraft,
+    clearResult,
+    loadHistory,
+    gasEstimate,
+  } = useBatchStore();
+
+  const [showHistory, setShowHistory] = useState(false);
+  const [showFilter, setShowFilter] = useState(false);
+  const [showCancelReasons, setShowCancelReasons] = useState(false);
+  const [selectedReason, setSelectedReason] = useState<CancelReason['reason']>('other');
+  const [cancelNotes, setCancelNotes] = useState('');
+  const [updatePrice, setUpdatePrice] = useState('');
+  const [updatePlan, setUpdatePlan] = useState('');
+  const [updateCategory, setUpdateCategory] = useState('');
+  const [updateCurrency, setUpdateCurrency] = useState('');
+  const [filterMinPrice, setFilterMinPrice] = useState('');
+  const [filterMaxPrice, setFilterMaxPrice] = useState('');
+  const [filterPlanChange, setFilterPlanChange] = useState(false);
 
-  const onLoadCsv = () => loadFromCsv(csv, draft.operationType, draft.atomic);
+  useEffect(() => {
+    loadHistory();
+  }, []);
 
-  const onRun = async () => {
-    const created = createBatch();
-    if (!created) return;
-    setBusy(true);
+  const items =
+    draft.createInputs.length ||
+    draft.updateIds.length ||
+    draft.cancelIds.length ||
+    draft.chargeItems.length ||
+    0;
+
+  const canExecute = items > 0 && !isRunning;
+
+  const onLoadCsv = useCallback(() => {
+    const csv = draft.csvContent;
+    if (!csv.trim()) {
+      Alert.alert('Error', 'Please enter CSV data');
+      return;
+    }
+    switch (draft.operationType) {
+      case 'create':
+        loadCreateCsv(csv);
+        break;
+      case 'cancel':
+        loadCancelCsv(csv);
+        break;
+      case 'charge':
+        loadChargeCsv(csv);
+        break;
+      case 'update':
+        loadUpdateCsv(csv);
+        break;
+    }
+  }, [draft.csvContent, draft.operationType, loadCreateCsv, loadCancelCsv, loadChargeCsv, loadUpdateCsv]);
+
+  const onExecute = useCallback(async () => {
     await executeBatch();
-    setBusy(false);
-  };
+  }, [executeBatch]);
 
-  const gas = estimateBatchGas(draft.subscriptionIds.length);
+  const onRetry = useCallback(async () => {
+    await retryFailed();
+  }, [retryFailed]);
 
-  return (
-    <View style={styles.container}>
-      <Text style={styles.header}>Batch Operations</Text>
+  const onExportJson = useCallback(() => {
+    const json = exportResultJson();
+    if (json) {
+      Share.share({ message: json, title: 'Batch Result' }).catch(() => {});
+    }
+  }, [exportResultJson]);
 
-      <Text style={styles.label}>Operation type</Text>
-      <View style={styles.row}>
-        {OPERATIONS.map((op) => (
-          <Text
-            key={op}
-            style={[styles.chip, draft.operationType === op && styles.chipActive]}
-            onPress={() => setDraft({ operationType: op })}
-          >
-            {op}
-          </Text>
+  const onExportCsv = useCallback(() => {
+    const csv = exportResultCsv();
+    if (csv) {
+      Share.share({ message: csv, title: 'Batch Result CSV' }).catch(() => {});
+    }
+  }, [exportResultCsv]);
+
+  const onApplyFilter = useCallback(() => {
+    setDraft({
+      updateFilter: {
+        planChange: filterPlanChange || undefined,
+        minPrice: filterMinPrice ? parseFloat(filterMinPrice) : undefined,
+        maxPrice: filterMaxPrice ? parseFloat(filterMaxPrice) : undefined,
+      },
+    });
+    setShowFilter(false);
+  }, [filterPlanChange, filterMinPrice, filterMaxPrice, setDraft]);
+
+  const onApplyUpdateParams = useCallback(() => {
+    setDraft({
+      updateParams: {
+        price: updatePrice ? parseFloat(updatePrice) : undefined,
+        plan: updatePlan || undefined,
+        category: updateCategory || undefined,
+        currency: updateCurrency || undefined,
+      },
+    });
+  }, [updatePrice, updatePlan, updateCategory, updateCurrency, setDraft]);
+
+  const onAddCancelReason = useCallback(() => {
+    if (draft.cancelIds.length > 0) {
+      setDraft({
+        cancelReasons: draft.cancelIds.map((id) => ({
+          subscriptionId: id,
+          reason: selectedReason,
+          notes: cancelNotes || undefined,
+        })),
+      });
+      Alert.alert('Applied', `Applied reason "${selectedReason}" to ${draft.cancelIds.length} subscription(s)`);
+    }
+    setShowCancelReasons(false);
+  }, [draft.cancelIds, selectedReason, cancelNotes, setDraft]);
+
+  const gasEst = gasEstimate();
+  const hasFailedItems = currentResult?.failedItems && currentResult.failedItems > 0;
+
+  const getCsvPlaceholder = (): string => {
+    switch (draft.operationType) {
+      case 'create':
+        return 'name,description,category,price,currency,billingCycle\nNetflix,Streaming,streaming,15.99,USD,monthly\nSpotify,Music,streaming,9.99,USD,monthly';
+      case 'update':
+        return 'subscriptionId\nsub_abc123\nsub_def456\nsub_ghi789';
+      case 'cancel':
+        return 'subscriptionId,reason,notes\nsub_abc123,too_expensive,\nsub_def456,no_longer_needed,Switched to competitor';
+      case 'charge':
+        return 'subscriptionId,amount\nsub_abc123,15.99\nsub_def456,9.99';
+      default:
+        return '';
+    }
+  };
+
+  const renderOperationSelector = () => (
+    <View style={styles.section}>
+      <Text style={styles.sectionTitle}>Operation Type</Text>
+      <View style={styles.chipRow}>
+        {OPERATION_TYPES.map((op) => (
+          <TouchableOpacity
+            key={op.key}
+            style={[styles.chip, draft.operationType === op.key && styles.chipActive]}
+            onPress={() => setOperationType(op.key)}>
+            <Text
+              style={[
+                styles.chipText,
+                draft.operationType === op.key && styles.chipTextActive,
+              ]}>
+              {op.icon} {op.label}
+            </Text>
+          </TouchableOpacity>
         ))}
       </View>
+    </View>
+  );
 
-      <Text style={styles.label}>CSV template (subscriptionId,param per row)</Text>
+  const renderCsvInput = () => (
+    <View style={styles.section}>
+      <Text style={styles.sectionTitle}>Data Input (CSV)</Text>
       <TextInput
-        style={[styles.input, { height: 90 }]}
+        style={styles.textArea}
         multiline
-        value={csv}
-        onChangeText={setCsv}
+        numberOfLines={8}
+        placeholder={getCsvPlaceholder()}
+        placeholderTextColor={colors.textSecondary}
+        value={draft.csvContent}
+        onChangeText={setCsvContent}
         autoCapitalize="none"
+        textAlignVertical="top"
       />
-      <Button title="Load from CSV" onPress={onLoadCsv} />
+      <View style={styles.csvActions}>
+        <TouchableOpacity style={styles.actionButton} onPress={onLoadCsv}>
+          <Text style={styles.actionButtonText}>Parse CSV</Text>
+        </TouchableOpacity>
+        <Text style={styles.itemCount}>
+          {items} item{items !== 1 ? 's' : ''} loaded
+        </Text>
+      </View>
+    </View>
+  );
+
+  const renderUpdateParams = () => {
+    if (draft.operationType !== 'update') return null;
+    return (
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Update Parameters</Text>
+        <View style={styles.paramRow}>
+          <Text style={styles.paramLabel}>New Price:</Text>
+          <TextInput
+            style={styles.paramInput}
+            value={updatePrice}
+            onChangeText={setUpdatePrice}
+            placeholder="9.99"
+            placeholderTextColor={colors.textSecondary}
+            keyboardType="decimal-pad"
+          />
+        </View>
+        <View style={styles.paramRow}>
+          <Text style={styles.paramLabel}>New Plan:</Text>
+          <TextInput
+            style={styles.paramInput}
+            value={updatePlan}
+            onChangeText={setUpdatePlan}
+            placeholder="premium"
+            placeholderTextColor={colors.textSecondary}
+          />
+        </View>
+        <View style={styles.paramRow}>
+          <Text style={styles.paramLabel}>Category:</Text>
+          <TextInput
+            style={styles.paramInput}
+            value={updateCategory}
+            onChangeText={setUpdateCategory}
+            placeholder="streaming"
+            placeholderTextColor={colors.textSecondary}
+          />
+        </View>
+        <View style={styles.paramRow}>
+          <Text style={styles.paramLabel}>Currency:</Text>
+          <TextInput
+            style={styles.paramInput}
+            value={updateCurrency}
+            onChangeText={setUpdateCurrency}
+            placeholder="USD"
+            placeholderTextColor={colors.textSecondary}
+            autoCapitalize="characters"
+          />
+        </View>
+        <View style={styles.paramActions}>
+          <TouchableOpacity style={styles.actionButton} onPress={onApplyUpdateParams}>
+            <Text style={styles.actionButtonText}>Apply Parameters</Text>
+          </TouchableOpacity>
+          <TouchableOpacity
+            style={styles.actionButtonOutline}
+            onPress={() => setShowFilter(true)}>
+            <Text style={styles.actionButtonOutlineText}>Set Filter</Text>
+          </TouchableOpacity>
+        </View>
+      </View>
+    );
+  };
 
-      <Text style={styles.meta}>
-        {draft.subscriptionIds.length} subscription(s) · est. gas {gas.toLocaleString()} ·{' '}
-        {draft.atomic ? 'atomic (all-or-nothing)' : 'non-atomic (partial allowed)'}
+  const renderCancelReasons = () => {
+    if (draft.operationType !== 'cancel') return null;
+    return (
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Cancel Reasons</Text>
+        <TouchableOpacity
+          style={styles.actionButton}
+          onPress={() => setShowCancelReasons(true)}>
+          <Text style={styles.actionButtonText}>
+            Set Reason ({draft.cancelReasons.length > 0 ? 'Applied' : 'Not Set'})
+          </Text>
+        </TouchableOpacity>
+      </View>
+    );
+  };
+
+  const renderOptions = () => (
+    <View style={styles.section}>
+      <Text style={styles.sectionTitle}>Options</Text>
+      <View style={styles.optionRow}>
+        <Text style={styles.optionLabel}>Atomic (all-or-nothing)</Text>
+        <Switch
+          value={draft.atomic}
+          onValueChange={toggleAtomic}
+          trackColor={{ false: colors.border, true: colors.primary }}
+          thumbColor={draft.atomic ? colors.onPrimary : colors.textSecondary}
+        />
+      </View>
+      <View style={styles.optionRow}>
+        <Text style={styles.optionLabel}>Chunk Size</Text>
+        <TextInput
+          style={styles.chunkInput}
+          value={String(draft.chunkSize)}
+          onChangeText={(v: string) => setChunkSize(parseInt(v, 10) || 50)}
+          keyboardType="number-pad"
+        />
+      </View>
+      <Text style={styles.gasEstimate}>
+        Est. Gas: {gasEst.toLocaleString()} units | {draft.atomic ? 'Atomic' : 'Non-atomic'} mode
       </Text>
-      <Button
-        title={draft.atomic ? 'Switch to non-atomic' : 'Switch to atomic'}
-        onPress={() => setDraft({ atomic: !draft.atomic })}
-      />
+    </View>
+  );
+
+  const renderActions = () => (
+    <View style={styles.section}>
+      <TouchableOpacity
+        style={[styles.primaryButton, (!canExecute || isRunning) && styles.buttonDisabled]}
+        onPress={onExecute}
+        disabled={!canExecute || isRunning}>
+        {isRunning ? (
+          <View style={styles.runningRow}>
+            <ActivityIndicator size="small" color={colors.onPrimary} />
+            <Text style={styles.primaryButtonText}> Running...</Text>
+          </View>
+        ) : (
+          <Text style={styles.primaryButtonText}>
+            Execute Batch ({items} item{items !== 1 ? 's' : ''})
+          </Text>
+        )}
+      </TouchableOpacity>
+      <View style={styles.buttonRow}>
+        <TouchableOpacity
+          style={[styles.secondaryButton, !hasFailedItems && styles.buttonDisabled]}
+          onPress={onRetry}
+          disabled={!hasFailedItems || isRunning}>
+          <Text style={styles.secondaryButtonText}>Retry Failed</Text>
+        </TouchableOpacity>
+        <TouchableOpacity style={styles.secondaryButton} onPress={resetDraft}>
+          <Text style={styles.secondaryButtonText}>Reset</Text>
+        </TouchableOpacity>
+      </View>
+    </View>
+  );
 
-      <View style={{ height: 8 }} />
-      <Button title="Create & Execute Batch" onPress={onRun} disabled={busy || draft.subscriptionIds.length === 0} />
-      <Button title="Reset" onPress={resetDraft} />
+  const renderProgress = () => {
+    if (!progress) return null;
+    return (
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Progress</Text>
+        <View style={styles.progressBar}>
+          <View
+            style={[
+              styles.progressFill,
+              { width: `${progress.percentComplete}%` },
+            ]}
+          />
+        </View>
+        <Text style={styles.progressText}>
+          {progress.completed}/{progress.total} ({progress.percentComplete}%) |
+          Success: {progress.succeeded} | Failed: {progress.failed}
+        </Text>
+      </View>
+    );
+  };
 
-      {current && (
-        <>
-          <Text style={styles.header}>
-            Status: {current.state} ({current.succeeded}/{current.total} ok, {current.failed} failed
-            {current.rolledBack ? ', rolled back' : ''})
+  const renderResults = () => {
+    if (!currentResult) return null;
+    return (
+      <View style={styles.section}>
+        <View style={styles.resultHeader}>
+          <Text style={styles.sectionTitle}>Results</Text>
+          <Text
+            style={[
+              styles.stateBadge,
+              { backgroundColor: STATE_COLORS[currentResult.state] + '30' },
+            ]}>
+            <Text style={[styles.stateText, { color: STATE_COLORS[currentResult.state] }]}>
+              {currentResult.state.toUpperCase()}
+            </Text>
           </Text>
-          <FlatList
-            data={current.results}
-            keyExtractor={(r) => r.subscriptionId}
-            renderItem={({ item }) => (
-              <View style={styles.item}>
-                <Text style={item.success ? styles.success : styles.failure}>
-                  {item.subscriptionId}: {item.success ? 'success' : `failed${item.message ? ` (${item.message})` : ''}`}
+        </View>
+
+        <View style={styles.statsRow}>
+          <View style={styles.statBox}>
+            <Text style={styles.statValue}>{currentResult.totalItems}</Text>
+            <Text style={styles.statLabel}>Total</Text>
+          </View>
+          <View style={styles.statBox}>
+            <Text style={[styles.statValue, styles.successText]}>
+              {currentResult.successfulItems}
+            </Text>
+            <Text style={styles.statLabel}>Success</Text>
+          </View>
+          <View style={styles.statBox}>
+            <Text style={[styles.statValue, styles.errorText]}>
+              {currentResult.failedItems}
+            </Text>
+            <Text style={styles.statLabel}>Failed</Text>
+          </View>
+          <View style={styles.statBox}>
+            <Text style={[styles.statValue, styles.warningText]}>
+              {currentResult.skippedItems}
+            </Text>
+            <Text style={styles.statLabel}>Skipped</Text>
+          </View>
+        </View>
+
+        {currentResult.rolledBack && (
+          <View style={styles.rollbackBadge}>
+            <Text style={styles.rollbackText}>Rolled back (atomic failure)</Text>
+          </View>
+        )}
+
+        <View style={styles.exportRow}>
+          <TouchableOpacity style={styles.exportButton} onPress={onExportJson}>
+            <Text style={styles.exportButtonText}>Export JSON</Text>
+          </TouchableOpacity>
+          <TouchableOpacity style={styles.exportButton} onPress={onExportCsv}>
+            <Text style={styles.exportButtonText}>Export CSV</Text>
+          </TouchableOpacity>
+        </View>
+
+        <FlatList
+          data={currentResult.results.slice(0, 100)}
+          keyExtractor={(r: PerItemResult) => `${r.index}_${r.subscriptionId}`}
+          scrollEnabled={false}
+          renderItem={({ item }: { item: PerItemResult }) => (
+            <View
+              style={[
+                styles.resultItem,
+                item.status === 'success' && styles.resultSuccess,
+                item.status === 'failed' && styles.resultFailed,
+                item.status === 'skipped' && styles.resultSkipped,
+              ]}>
+              <View style={styles.resultItemRow}>
+                <Text style={styles.resultIndex}>#{item.index + 1}</Text>
+                <Text style={styles.resultId} numberOfLines={1}>
+                  {item.subscriptionName || item.subscriptionId}
+                </Text>
+                <Text
+                  style={[
+                    styles.resultStatus,
+                    item.status === 'success' && styles.successText,
+                    item.status === 'failed' && styles.errorText,
+                    item.status === 'skipped' && styles.warningText,
+                  ]}>
+                  {item.status}
                 </Text>
               </View>
-            )}
+              {item.error && (
+                <Text style={styles.resultError} numberOfLines={1}>
+                  {item.error}
+                </Text>
+              )}
+              {item.cancelReason && (
+                <Text style={styles.resultReason}>
+                  Reason: {item.cancelReason.reason}
+                  {item.cancelReason.notes ? ` - ${item.cancelReason.notes}` : ''}
+                </Text>
+              )}
+              {item.retryCount > 0 && (
+                <Text style={styles.retryCount}>Retries: {item.retryCount}</Text>
+              )}
+            </View>
+          )}
+          ListEmptyComponent={
+            <Text style={styles.emptyText}>No results yet</Text>
+          }
+        />
+        {currentResult.results.length > 100 && (
+          <Text style={styles.moreText}>
+            ...and {currentResult.results.length - 100} more items
+          </Text>
+        )}
+      </View>
+    );
+  };
+
+  const renderFilterModal = () => (
+    <Modal
+      visible={showFilter}
+      animationType="slide"
+      presentationStyle="pageSheet"
+      onRequestClose={() => setShowFilter(false)}>
+      <SafeAreaView style={styles.modalContainer}>
+        <View style={styles.modalHeader}>
+          <Text style={styles.modalTitle}>Update Filter</Text>
+          <TouchableOpacity onPress={() => setShowFilter(false)}>
+            <Text style={styles.modalClose}>Close</Text>
+          </TouchableOpacity>
+        </View>
+        <ScrollView style={styles.modalBody}>
+          <View style={styles.filterRow}>
+            <Text style={styles.filterLabel}>Plan Change Only:</Text>
+            <Switch
+              value={filterPlanChange}
+              onValueChange={setFilterPlanChange}
+              trackColor={{ false: colors.border, true: colors.primary }}
+            />
+          </View>
+          <View style={styles.filterRow}>
+            <Text style={styles.filterLabel}>Min Price:</Text>
+            <TextInput
+              style={styles.filterInput}
+              value={filterMinPrice}
+              onChangeText={setFilterMinPrice}
+              placeholder="0.00"
+              placeholderTextColor={colors.textSecondary}
+              keyboardType="decimal-pad"
+            />
+          </View>
+          <View style={styles.filterRow}>
+            <Text style={styles.filterLabel}>Max Price:</Text>
+            <TextInput
+              style={styles.filterInput}
+              value={filterMaxPrice}
+              onChangeText={setFilterMaxPrice}
+              placeholder="999.99"
+              placeholderTextColor={colors.textSecondary}
+              keyboardType="decimal-pad"
+            />
+          </View>
+          <TouchableOpacity style={styles.primaryButton} onPress={onApplyFilter}>
+            <Text style={styles.primaryButtonText}>Apply Filter</Text>
+          </TouchableOpacity>
+        </ScrollView>
+      </SafeAreaView>
+    </Modal>
+  );
+
+  const renderCancelReasonModal = () => (
+    <Modal
+      visible={showCancelReasons}
+      animationType="slide"
+      presentationStyle="pageSheet"
+      onRequestClose={() => setShowCancelReasons(false)}>
+      <SafeAreaView style={styles.modalContainer}>
+        <View style={styles.modalHeader}>
+          <Text style={styles.modalTitle}>Cancel Reason</Text>
+          <TouchableOpacity onPress={() => setShowCancelReasons(false)}>
+            <Text style={styles.modalClose}>Close</Text>
+          </TouchableOpacity>
+        </View>
+        <ScrollView style={styles.modalBody}>
+          {CANCEL_REASONS.map((r) => (
+            <TouchableOpacity
+              key={r.key}
+              style={[
+                styles.reasonOption,
+                selectedReason === r.key && styles.reasonOptionActive,
+              ]}
+              onPress={() => setSelectedReason(r.key)}>
+              <Text
+                style={[
+                  styles.reasonOptionText,
+                  selectedReason === r.key && styles.reasonOptionTextActive,
+                ]}>
+                {r.label}
+              </Text>
+            </TouchableOpacity>
+          ))}
+          <TextInput
+            style={styles.reasonNotes}
+            value={cancelNotes}
+            onChangeText={setCancelNotes}
+            placeholder="Optional notes..."
+            placeholderTextColor={colors.textSecondary}
+            multiline
           />
-        </>
-      )}
-    </View>
+          <TouchableOpacity style={styles.primaryButton} onPress={onAddCancelReason}>
+            <Text style={styles.primaryButtonText}>
+              Apply to {draft.cancelIds.length} item{draft.cancelIds.length !== 1 ? 's' : ''}
+            </Text>
+          </TouchableOpacity>
+        </ScrollView>
+      </SafeAreaView>
+    </Modal>
+  );
+
+  const renderHistoryModal = () => (
+    <Modal
+      visible={showHistory}
+      animationType="slide"
+      presentationStyle="pageSheet"
+      onRequestClose={() => setShowHistory(false)}>
+      <SafeAreaView style={styles.modalContainer}>
+        <View style={styles.modalHeader}>
+          <Text style={styles.modalTitle}>Batch History</Text>
+          <TouchableOpacity onPress={() => setShowHistory(false)}>
+            <Text style={styles.modalClose}>Close</Text>
+          </TouchableOpacity>
+        </View>
+        <FlatList
+          data={history}
+          keyExtractor={(item: BatchHistoryEntry) => item.batchId}
+          renderItem={({ item }: { item: BatchHistoryEntry }) => (
+            <View style={styles.historyItem}>
+              <View style={styles.historyRow}>
+                <Text style={styles.historyOp}>{item.operationType.toUpperCase()}</Text>
+                <Text
+                  style={[
+                    styles.historyState,
+                    { color: STATE_COLORS[item.state as BatchState] || colors.textSecondary },
+                  ]}>
+                  {item.state}
+                </Text>
+              </View>
+              <Text style={styles.historySummary}>{item.summary}</Text>
+              <Text style={styles.historyTime}>
+                {new Date(item.timestamp).toLocaleString()}
+              </Text>
+            </View>
+          )}
+          ListEmptyComponent={
+            <Text style={styles.emptyText}>No batch history</Text>
+          }
+        />
+      </SafeAreaView>
+    </Modal>
+  );
+
+  return (
+    <SafeAreaView style={styles.container}>
+      <ScrollView style={styles.scrollView} keyboardShouldPersistTaps="handled">
+        <View style={styles.header}>
+          <Text style={styles.title}>Batch Operations</Text>
+          <TouchableOpacity onPress={() => setShowHistory(true)}>
+            <Text style={styles.historyLink}>History</Text>
+          </TouchableOpacity>
+        </View>
+
+        {renderOperationSelector()}
+        {renderCsvInput()}
+        {renderUpdateParams()}
+        {renderCancelReasons()}
+        {renderOptions()}
+        {renderActions()}
+        {renderProgress()}
+        {renderResults()}
+
+        <View style={styles.bottomPad} />
+      </ScrollView>
+
+      {renderFilterModal()}
+      {renderCancelReasonModal()}
+      {renderHistoryModal()}
+    </SafeAreaView>
   );
 };
 
+// ════════════════════════════════════════════════════════════════
+// Styles
+// ════════════════════════════════════════════════════════════════
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: colors.background,
+  },
+  scrollView: {
+    flex: 1,
+  },
+  header: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    padding: spacing.lg,
+    paddingTop: spacing.xl,
+  },
+  title: {
+    ...typography.h1,
+    color: colors.text,
+  },
+  historyLink: {
+    ...typography.body,
+    color: colors.primary,
+    fontWeight: '600',
+  },
+  section: {
+    padding: spacing.lg,
+    paddingTop: 0,
+  },
+  sectionTitle: {
+    ...typography.h3,
+    color: colors.text,
+    marginBottom: spacing.md,
+  },
+  chipRow: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: spacing.sm,
+  },
+  chip: {
+    paddingHorizontal: 14,
+    paddingVertical: 8,
+    borderRadius: borderRadius.round,
+    borderWidth: 1,
+    borderColor: colors.border,
+    backgroundColor: colors.surface,
+  },
+  chipActive: {
+    backgroundColor: colors.primary + '30',
+    borderColor: colors.primary,
+  },
+  chipText: {
+    ...typography.body,
+    color: colors.textSecondary,
+    fontWeight: '600',
+  },
+  chipTextActive: {
+    color: colors.primary,
+  },
+  textArea: {
+    ...typography.body,
+    minHeight: 140,
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: borderRadius.md,
+    padding: spacing.md,
+    color: colors.text,
+    backgroundColor: colors.surface,
+    fontFamily: 'monospace',
+    fontSize: 12,
+  },
+  csvActions: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    marginTop: spacing.sm,
+  },
+  itemCount: {
+    ...typography.caption,
+    color: colors.textSecondary,
+  },
+  actionButton: {
+    backgroundColor: colors.primary,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    borderRadius: borderRadius.md,
+  },
+  actionButtonText: {
+    ...typography.button,
+    color: colors.onPrimary,
+  },
+  actionButtonOutline: {
+    borderWidth: 1,
+    borderColor: colors.primary,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    borderRadius: borderRadius.md,
+  },
+  actionButtonOutlineText: {
+    ...typography.button,
+    color: colors.primary,
+  },
+  paramRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    marginBottom: spacing.sm,
+  },
+  paramLabel: {
+    ...typography.body,
+    color: colors.textSecondary,
+    width: 100,
+  },
+  paramInput: {
+    ...typography.body,
+    flex: 1,
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: borderRadius.sm,
+    paddingHorizontal: spacing.sm,
+    paddingVertical: spacing.xs,
+    color: colors.text,
+    backgroundColor: colors.surface,
+  },
+  paramActions: {
+    flexDirection: 'row',
+    gap: spacing.sm,
+    marginTop: spacing.sm,
+  },
+  optionRow: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    paddingVertical: spacing.sm,
+  },
+  optionLabel: {
+    ...typography.body,
+    color: colors.text,
+  },
+  chunkInput: {
+    ...typography.body,
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: borderRadius.sm,
+    paddingHorizontal: spacing.sm,
+    paddingVertical: spacing.xs,
+    color: colors.text,
+    backgroundColor: colors.surface,
+    width: 80,
+    textAlign: 'center',
+  },
+  gasEstimate: {
+    ...typography.caption,
+    color: colors.textSecondary,
+    marginTop: spacing.sm,
+  },
+  primaryButton: {
+    backgroundColor: colors.primary,
+    paddingVertical: spacing.md,
+    borderRadius: borderRadius.md,
+    alignItems: 'center',
+  },
+  primaryButtonText: {
+    ...typography.button,
+    color: colors.onPrimary,
+  },
+  buttonDisabled: {
+    opacity: 0.5,
+  },
+  buttonRow: {
+    flexDirection: 'row',
+    gap: spacing.sm,
+    marginTop: spacing.sm,
+  },
+  secondaryButton: {
+    flex: 1,
+    borderWidth: 1,
+    borderColor: colors.border,
+    paddingVertical: spacing.md,
+    borderRadius: borderRadius.md,
+    alignItems: 'center',
+  },
+  secondaryButtonText: {
+    ...typography.button,
+    color: colors.text,
+  },
+  runningRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+  progressBar: {
+    height: 8,
+    backgroundColor: colors.surfaceVariant,
+    borderRadius: borderRadius.round,
+    overflow: 'hidden',
+  },
+  progressFill: {
+    height: '100%',
+    backgroundColor: colors.primary,
+    borderRadius: borderRadius.round,
+  },
+  progressText: {
+    ...typography.caption,
+    color: colors.textSecondary,
+    marginTop: spacing.xs,
+  },
+  resultHeader: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    marginBottom: spacing.md,
+  },
+  stateBadge: {
+    paddingHorizontal: spacing.sm,
+    paddingVertical: spacing.xs,
+    borderRadius: borderRadius.sm,
+  },
+  stateText: {
+    ...typography.small,
+    fontWeight: '700',
+  },
+  statsRow: {
+    flexDirection: 'row',
+    justifyContent: 'space-around',
+    marginBottom: spacing.md,
+  },
+  statBox: {
+    alignItems: 'center',
+  },
+  statValue: {
+    ...typography.h2,
+    color: colors.text,
+  },
+  statLabel: {
+    ...typography.caption,
+    color: colors.textSecondary,
+  },
+  successText: {
+    color: colors.success,
+  },
+  errorText: {
+    color: colors.error,
+  },
+  warningText: {
+    color: colors.warning,
+  },
+  rollbackBadge: {
+    backgroundColor: colors.error + '30',
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    borderRadius: borderRadius.md,
+    marginBottom: spacing.md,
+    alignItems: 'center',
+  },
+  rollbackText: {
+    ...typography.caption,
+    color: colors.error,
+    fontWeight: '600',
+  },
+  exportRow: {
+    flexDirection: 'row',
+    gap: spacing.sm,
+    marginBottom: spacing.md,
+  },
+  exportButton: {
+    flex: 1,
+    borderWidth: 1,
+    borderColor: colors.primary,
+    paddingVertical: spacing.sm,
+    borderRadius: borderRadius.md,
+    alignItems: 'center',
+  },
+  exportButtonText: {
+    ...typography.button,
+    color: colors.primary,
+  },
+  resultItem: {
+    paddingVertical: spacing.sm,
+    paddingHorizontal: spacing.sm,
+    borderRadius: borderRadius.sm,
+    marginBottom: spacing.xs,
+    backgroundColor: colors.surface,
+  },
+  resultSuccess: {
+    borderLeftWidth: 3,
+    borderLeftColor: colors.success,
+  },
+  resultFailed: {
+    borderLeftWidth: 3,
+    borderLeftColor: colors.error,
+  },
+  resultSkipped: {
+    borderLeftWidth: 3,
+    borderLeftColor: colors.warning,
+  },
+  resultItemRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm,
+  },
+  resultIndex: {
+    ...typography.small,
+    color: colors.textSecondary,
+    width: 30,
+  },
+  resultId: {
+    ...typography.body,
+    color: colors.text,
+    flex: 1,
+  },
+  resultStatus: {
+    ...typography.small,
+    fontWeight: '700',
+    textTransform: 'uppercase',
+  },
+  resultError: {
+    ...typography.small,
+    color: colors.error,
+    marginTop: spacing.xs,
+    paddingLeft: 30 + spacing.sm,
+  },
+  resultReason: {
+    ...typography.small,
+    color: colors.textSecondary,
+    marginTop: spacing.xs,
+    paddingLeft: 30 + spacing.sm,
+  },
+  retryCount: {
+    ...typography.small,
+    color: colors.warning,
+    marginTop: spacing.xs,
+    paddingLeft: 30 + spacing.sm,
+  },
+  emptyText: {
+    ...typography.body,
+    color: colors.textSecondary,
+    textAlign: 'center',
+    marginTop: spacing.xl,
+  },
+  moreText: {
+    ...typography.caption,
+    color: colors.textSecondary,
+    fontStyle: 'italic',
+    marginTop: spacing.sm,
+    textAlign: 'center',
+  },
+  bottomPad: {
+    height: spacing.xxl,
+  },
+  // Modal styles
+  modalContainer: {
+    flex: 1,
+    backgroundColor: colors.background,
+  },
+  modalHeader: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    padding: spacing.lg,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.border,
+  },
+  modalTitle: {
+    ...typography.h2,
+    color: colors.text,
+  },
+  modalClose: {
+    ...typography.body,
+    color: colors.primary,
+    fontWeight: '600',
+  },
+  modalBody: {
+    flex: 1,
+    padding: spacing.lg,
+  },
+  filterRow: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    paddingVertical: spacing.sm,
+  },
+  filterLabel: {
+    ...typography.body,
+    color: colors.text,
+  },
+  filterInput: {
+    ...typography.body,
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: borderRadius.sm,
+    paddingHorizontal: spacing.sm,
+    paddingVertical: spacing.xs,
+    color: colors.text,
+    backgroundColor: colors.surface,
+    width: 120,
+    textAlign: 'right',
+  },
+  reasonOption: {
+    paddingVertical: spacing.md,
+    paddingHorizontal: spacing.md,
+    borderRadius: borderRadius.md,
+    marginBottom: spacing.sm,
+    borderWidth: 1,
+    borderColor: colors.border,
+  },
+  reasonOptionActive: {
+    backgroundColor: colors.primary + '30',
+    borderColor: colors.primary,
+  },
+  reasonOptionText: {
+    ...typography.body,
+    color: colors.text,
+  },
+  reasonOptionTextActive: {
+    color: colors.primary,
+    fontWeight: '600',
+  },
+  reasonNotes: {
+    ...typography.body,
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: borderRadius.md,
+    padding: spacing.md,
+    color: colors.text,
+    backgroundColor: colors.surface,
+    minHeight: 80,
+    marginVertical: spacing.md,
+  },
+  // History styles
+  historyItem: {
+    padding: spacing.md,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.border,
+  },
+  historyRow: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+  },
+  historyOp: {
+    ...typography.body,
+    color: colors.text,
+    fontWeight: '700',
+  },
+  historyState: {
+    ...typography.caption,
+    fontWeight: '700',
+    textTransform: 'uppercase',
+  },
+  historySummary: {
+    ...typography.caption,
+    color: colors.textSecondary,
+    marginTop: spacing.xs,
+  },
+  historyTime: {
+    ...typography.small,
+    color: colors.textSecondary,
+    marginTop: spacing.xs,
+  },
+});
+
 export default BatchOperationsScreen;
diff --git a/app/services/batchTransactionService.ts b/app/services/batchTransactionService.ts
index 4c2a2bc..b78c82f 100644
--- a/app/services/batchTransactionService.ts
+++ b/app/services/batchTransactionService.ts
@@ -1,353 +1,945 @@
 // ════════════════════════════════════════════════════════════════
-// BATCH TRANSACTION SERVICE - Frontend batch management
+// BATCH TRANSACTION SERVICE - Full batch management for subscriptions
 // ════════════════════════════════════════════════════════════════
+//
+// Supports: batch create from CSV/JSON, batch update with filtering,
+// batch cancel with reason collection, batch charge for manual billing,
+// per-item status tracking, idempotent retry of failed items,
+// result export (CSV/JSON), and large batch memory management via chunking.
 
-/**
- * Represents a single transaction in a batch
- */
-export interface BatchTransaction {
-  functionName: string;
-  params: any[];
-  dependsOn?: number;
-  required: boolean;
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const HISTORY_KEY = 'subtrackr-batch-history';
+const MAX_HISTORY_ENTRIES = 50;
+const DEFAULT_CHUNK_SIZE = 50;
+const MAX_CHUNK_SIZE = 200;
+
+// ════════════════════════════════════════════════════════════════
+// Types
+// ════════════════════════════════════════════════════════════════
+
+export type BatchOperationType = 'create' | 'update' | 'charge' | 'cancel';
+
+export type BatchState = 'pending' | 'running' | 'completed' | 'partial' | 'failed';
+
+export type PerItemStatus = 'pending' | 'running' | 'success' | 'failed' | 'skipped';
+
+export interface CancelReason {
+  subscriptionId: string;
+  reason: 'too_expensive' | 'no_longer_needed' | 'found_alternative' | 'poor_service' | 'other';
+  notes?: string;
+}
+
+export interface UpdateFilter {
+  planChange?: boolean;
+  minPrice?: number;
+  maxPrice?: number;
+  categories?: string[];
+  billingCycle?: string;
+  isActive?: boolean;
+}
+
+export interface BatchUpdateParams {
+  price?: number;
+  plan?: string;
+  billingCycle?: string;
+  category?: string;
+  currency?: string;
+  isActive?: boolean;
 }
 
-/**
- * Result of executing a batch operation
- */
-export interface OperationResult {
+export interface BatchCreateInput {
+  name: string;
+  description?: string;
+  category: string;
+  price: number;
+  currency: string;
+  billingCycle: string;
+  nextBillingDate?: string;
+  isActive?: boolean;
+  notificationsEnabled?: boolean;
+}
+
+export interface PerItemResult {
   index: number;
-  success: boolean;
-  result?: any;
+  subscriptionId: string;
+  subscriptionName?: string;
+  status: PerItemStatus;
   error?: string;
+  errorCode?: number;
+  cancelReason?: CancelReason;
+  retryCount: number;
+  completedAt?: string;
+  message?: string;
 }
 
-/**
- * Complete batch result
- */
 export interface BatchExecutionResult {
   batchId: string;
-  totalOperations: number;
-  successfulOperations: number;
-  failedOperations: number;
-  results: OperationResult[];
+  operationType: BatchOperationType;
+  state: BatchState;
+  totalItems: number;
+  successfulItems: number;
+  failedItems: number;
+  skippedItems: number;
+  results: PerItemResult[];
   atomic: boolean;
+  rolledBack: boolean;
   gasEstimate: number;
+  startedAt: string;
+  completedAt?: string;
+  cancelReasons?: CancelReason[];
+  filter?: UpdateFilter;
 }
 
-/**
- * Batch Transaction Service - Handles transaction batching
- */
-export class BatchTransactionService {
-  private pendingTransactions: BatchTransaction[] = [];
-  private maxBatchSize: number = 10;
-  private gasPerOperation: number = 100_000;
-  private baseGasCost: number = 50_000;
+export interface BatchHistoryEntry {
+  batchId: string;
+  operationType: BatchOperationType;
+  state: BatchState;
+  totalItems: number;
+  successfulItems: number;
+  failedItems: number;
+  timestamp: string;
+  summary: string;
+}
 
-  constructor(maxBatchSize: number = 10) {
-    this.maxBatchSize = maxBatchSize;
-  }
+export interface BatchExportData {
+  version: string;
+  exportedAt: string;
+  batch: BatchExecutionResult;
+}
+
+export interface BatchProgress {
+  batchId: string;
+  state: BatchState;
+  total: number;
+  completed: number;
+  succeeded: number;
+  failed: number;
+  percentComplete: number;
+}
+
+export interface RetryConfig {
+  maxRetries: number;
+  retryDelayMs: number;
+  backoffMultiplier: number;
+  onlyRetryFailed: boolean;
+}
+
+// ════════════════════════════════════════════════════════════════
+// Batch Csv Parsing
+// ════════════════════════════════════════════════════════════════
 
-  /**
-   * Add transaction to batch queue
-   * @returns true if added, false if batch is full
-   */
-  addTransaction(functionName: string, params: any[], required: boolean = true): boolean {
-    // Check if batch is full
-    if (this.pendingTransactions.length >= this.maxBatchSize) {
-      console.warn(`Batch is full (${this.maxBatchSize}), cannot add more transactions`);
-      return false;
+export const BATCH_CREATE_CSV_COLUMNS = [
+  'name',
+  'description',
+  'category',
+  'price',
+  'currency',
+  'billingCycle',
+  'nextBillingDate',
+  'isActive',
+  'notificationsEnabled',
+];
+
+function parseCsvLine(line: string): string[] {
+  const result: string[] = [];
+  let current = '';
+  let inQuotes = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === '"') {
+      if (inQuotes && line[i + 1] === '"') {
+        current += '"';
+        i++;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if (char === ',' && !inQuotes) {
+      result.push(current.trim());
+      current = '';
+    } else {
+      current += char;
     }
+  }
+  result.push(current.trim());
+  return result;
+}
+
+export function parseBatchCreateCsv(csvContent: string): BatchCreateInput[] {
+  const lines = csvContent.split(/\r?\n/).filter((l) => l.trim());
+  if (lines.length < 2) return [];
+
+  const headers = parseCsvLine(lines[0]);
+  const headerMap = new Map<string, number>();
+  headers.forEach((h, i) => headerMap.set(h.toLowerCase().trim(), i));
+
+  const results: BatchCreateInput[] = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = parseCsvLine(lines[i]);
+    if (values.length === 0 || values.every((v) => !v.trim())) continue;
 
-    const transaction: BatchTransaction = {
-      functionName,
-      params,
-      required,
+    const nameIdx = headerMap.get('name');
+    if (nameIdx === undefined || !values[nameIdx]) continue;
+
+    const getVal = (col: string): string | undefined => {
+      const idx = headerMap.get(col);
+      if (idx === undefined) return undefined;
+      return values[idx] || undefined;
     };
 
-    this.pendingTransactions.push(transaction);
-    console.log(
-      `✅ Added ${functionName}. Pending: ${this.pendingTransactions.length}/${this.maxBatchSize}`
-    );
+    results.push({
+      name: getVal('name') || '',
+      description: getVal('description'),
+      category: getVal('category') || 'other',
+      price: parseFloat(getVal('price') || '0') || 0,
+      currency: (getVal('currency') || 'USD').toUpperCase(),
+      billingCycle: getVal('billingCycle') || 'monthly',
+      nextBillingDate: getVal('nextBillingDate'),
+      isActive: getVal('isActive')?.toLowerCase() !== 'false',
+      notificationsEnabled: getVal('notificationsEnabled')?.toLowerCase() !== 'false',
+    });
+  }
+  return results;
+}
+
+export function parseBatchCancelCsv(csvContent: string): Array<{ subscriptionId: string; reason: string; notes?: string }> {
+  const lines = csvContent.split(/\r?\n/).filter((l) => l.trim());
+  if (lines.length < 2) return [];
+
+  const headers = parseCsvLine(lines[0]);
+  const headerMap = new Map<string, number>();
+  headers.forEach((h, i) => headerMap.set(h.toLowerCase().trim(), i));
 
-    return true;
+  const results: Array<{ subscriptionId: string; reason: string; notes?: string }> = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = parseCsvLine(lines[i]);
+    if (values.length === 0 || values.every((v) => !v.trim())) continue;
+
+    const idIdx = headerMap.get('subscriptionid') ?? headerMap.get('id');
+    if (idIdx === undefined || !values[idIdx]) continue;
+
+    const reasonIdx = headerMap.get('reason');
+    const notesIdx = headerMap.get('notes');
+
+    results.push({
+      subscriptionId: values[idIdx].trim(),
+      reason: reasonIdx !== undefined ? values[reasonIdx]?.trim() || 'other' : 'other',
+      notes: notesIdx !== undefined ? values[notesIdx]?.trim() : undefined,
+    });
   }
+  return results;
+}
 
-  /**
-   * Add transaction with dependency on another operation
-   */
-  addTransactionWithDependency(
-    functionName: string,
-    params: any[],
-    dependsOn: number,
-    required: boolean = true
-  ): boolean {
-    if (this.pendingTransactions.length >= this.maxBatchSize) {
-      return false;
-    }
+export function parseBatchChargeCsv(csvContent: string): Array<{ subscriptionId: string; amount: number }> {
+  const lines = csvContent.split(/\r?\n/).filter((l) => l.trim());
+  if (lines.length < 2) return [];
 
-    // Validate dependency
-    if (dependsOn >= this.pendingTransactions.length) {
-      console.error(`Invalid dependency: index ${dependsOn} out of range`);
-      return false;
-    }
+  const headers = parseCsvLine(lines[0]);
+  const headerMap = new Map<string, number>();
+  headers.forEach((h, i) => headerMap.set(h.toLowerCase().trim(), i));
+
+  const results: Array<{ subscriptionId: string; amount: number }> = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = parseCsvLine(lines[i]);
+    if (values.length === 0 || values.every((v) => !v.trim())) continue;
+
+    const idIdx = headerMap.get('subscriptionid') ?? headerMap.get('id');
+    if (idIdx === undefined || !values[idIdx]) continue;
+
+    const amountIdx = headerMap.get('amount') ?? headerMap.get('price');
+    results.push({
+      subscriptionId: values[idIdx].trim(),
+      amount: amountIdx !== undefined ? parseFloat(values[amountIdx]) || 0 : 0,
+    });
+  }
+  return results;
+}
+
+// ════════════════════════════════════════════════════════════════
+// Result Export
+// ════════════════════════════════════════════════════════════════
 
-    const transaction: BatchTransaction = {
-      functionName,
-      params,
-      dependsOn,
-      required,
+export function exportBatchResultToJson(result: BatchExecutionResult): string {
+  const data: BatchExportData = {
+    version: '1.0.0',
+    exportedAt: new Date().toISOString(),
+    batch: result,
+  };
+  return JSON.stringify(data, null, 2);
+}
+
+export function exportBatchResultToCsv(result: BatchExecutionResult): string {
+  const headers = 'index,subscriptionId,subscriptionName,status,error,errorCode,retryCount,completedAt,message';
+  const rows = result.results.map((r) => {
+    const escape = (v: string | undefined) => {
+      if (!v) return '';
+      return v.includes(',') || v.includes('"') ? `"${v.replace(/"/g, '""')}"` : v;
     };
+    return [
+      r.index,
+      r.subscriptionId,
+      escape(r.subscriptionName),
+      r.status,
+      escape(r.error),
+      r.errorCode ?? '',
+      r.retryCount,
+      r.completedAt ?? '',
+      escape(r.message),
+    ].join(',');
+  });
+  return [headers, ...rows].join('\n');
+}
+
+// ════════════════════════════════════════════════════════════════
+// Batch History
+// ════════════════════════════════════════════════════════════════
 
-    this.pendingTransactions.push(transaction);
-    return true;
+export async function getBatchHistory(): Promise<BatchHistoryEntry[]> {
+  try {
+    const json = await AsyncStorage.getItem(HISTORY_KEY);
+    if (json) return JSON.parse(json);
+  } catch {
+    // ignore
   }
+  return [];
+}
 
-  /**
-   * Get pending transactions count
-   */
-  getPendingCount(): number {
-    return this.pendingTransactions.length;
+export async function saveBatchHistory(entry: BatchHistoryEntry): Promise<void> {
+  try {
+    const history = await getBatchHistory();
+    history.unshift(entry);
+    const trimmed = history.slice(0, MAX_HISTORY_ENTRIES);
+    await AsyncStorage.setItem(HISTORY_KEY, JSON.stringify(trimmed));
+  } catch {
+    // ignore
   }
+}
 
-  /**
-   * Is batch ready to execute?
-   */
-  isBatchReady(): boolean {
-    return this.pendingTransactions.length >= this.maxBatchSize;
+export async function clearBatchHistory(): Promise<void> {
+  try {
+    await AsyncStorage.removeItem(HISTORY_KEY);
+  } catch {
+    // ignore
   }
+}
+
+// ════════════════════════════════════════════════════════════════
+// Batch Transaction Service
+// ════════════════════════════════════════════════════════════════
 
-  /**
-   * Get current pending batch
-   */
-  getPendingBatch(): BatchTransaction[] {
-    return [...this.pendingTransactions];
+export class BatchTransactionService {
+  private chunkSize: number = DEFAULT_CHUNK_SIZE;
+  private baseGasCost: number = 50_000;
+  private gasPerOperation: number = 100_000;
+  private idempotencyKeys: Map<string, string> = new Map();
+
+  private currentResult: BatchExecutionResult | null = null;
+  private retryConfig: RetryConfig = {
+    maxRetries: 3,
+    retryDelayMs: 300,
+    backoffMultiplier: 2,
+    onlyRetryFailed: true,
+  };
+
+  constructor(chunkSize: number = DEFAULT_CHUNK_SIZE) {
+    this.setChunkSize(chunkSize);
   }
 
-  /**
-   * Simulate batch execution without actually executing
-   * Useful for gas estimation and validation
-   */
-  async simulateBatch(): Promise<BatchExecutionResult> {
-    console.log(`📊 Simulating batch with ${this.pendingTransactions.length} operations...`);
+  setChunkSize(size: number): void {
+    if (size > MAX_CHUNK_SIZE) {
+      this.chunkSize = MAX_CHUNK_SIZE;
+    } else if (size < 1) {
+      this.chunkSize = 1;
+    } else {
+      this.chunkSize = size;
+    }
+  }
 
-    const totalGas = this.getGasEstimate();
-    const batchId = this.generateBatchId();
+  setRetryConfig(config: Partial<RetryConfig>): void {
+    this.retryConfig = { ...this.retryConfig, ...config };
+  }
+
+  getGasEstimate(itemCount: number): number {
+    return this.baseGasCost + itemCount * this.gasPerOperation;
+  }
+
+  private generateBatchId(): string {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substr(2, 9);
+    return `batch_${timestamp}_${random}`;
+  }
 
-    const results: OperationResult[] = this.pendingTransactions.map((tx, index) => ({
-      index,
-      success: true,
-      result: null,
-    }));
+  private idempotencyKey(subscriptionId: string, operationType: BatchOperationType): string {
+    const key = `${operationType}_${subscriptionId}`;
+    if (!this.idempotencyKeys.has(key)) {
+      this.idempotencyKeys.set(key, this.generateBatchId());
+    }
+    return this.idempotencyKeys.get(key)!;
+  }
 
+  getProgress(): BatchProgress | null {
+    if (!this.currentResult) return null;
+    const r = this.currentResult;
+    const completed = r.successfulItems + r.failedItems + r.skippedItems;
     return {
-      batchId,
-      totalOperations: this.pendingTransactions.length,
-      successfulOperations: this.pendingTransactions.length,
-      failedOperations: 0,
-      results,
-      atomic: false,
-      gasEstimate: totalGas,
+      batchId: r.batchId,
+      state: r.state,
+      total: r.totalItems,
+      completed,
+      succeeded: r.successfulItems,
+      failed: r.failedItems,
+      percentComplete: r.totalItems > 0 ? Math.round((completed / r.totalItems) * 100) : 0,
     };
   }
 
-  /**
-   * Execute batch synchronously
-   */
-  async executeBatch(atomic: boolean = true): Promise<BatchExecutionResult> {
-    console.log(
-      `🚀 Executing batch with ${this.pendingTransactions.length} operations (atomic: ${atomic})...`
-    );
+  getLastResult(): BatchExecutionResult | null {
+    return this.currentResult;
+  }
 
-    if (this.pendingTransactions.length === 0) {
-      throw new Error('❌ No transactions to execute');
-    }
+  // ══════════════════════════════════════════════════════════════
+  // Batch Create (from CSV/JSON input)
+  // ══════════════════════════════════════════════════════════════
 
-    const results: OperationResult[] = [];
-    let successCount = 0;
-    let failCount = 0;
-    let totalGas = 0;
-    let shouldStop = false;
+  async executeBatchCreate(
+    inputs: BatchCreateInput[],
+    addFn: (input: BatchCreateInput) => Promise<{ success: boolean; id?: string; error?: string }>,
+    options?: { atomic?: boolean },
+  ): Promise<BatchExecutionResult> {
+    const atomic = options?.atomic ?? false;
+    const batchId = this.generateBatchId();
 
-    // Execute each transaction
-    for (let i = 0; i < this.pendingTransactions.length; i++) {
-      const tx = this.pendingTransactions[i];
-
-      // Check if we should stop (atomic mode)
-      if (shouldStop && atomic) {
-        results.push({
-          index: i,
-          success: false,
-          error: 'Skipped due to atomic failure',
-        });
-        failCount++;
-        continue;
-      }
+    const result: BatchExecutionResult = {
+      batchId,
+      operationType: 'create',
+      state: 'running',
+      totalItems: inputs.length,
+      successfulItems: 0,
+      failedItems: 0,
+      skippedItems: 0,
+      results: [],
+      atomic,
+      rolledBack: false,
+      gasEstimate: this.getGasEstimate(inputs.length),
+      startedAt: new Date().toISOString(),
+    };
+
+    this.currentResult = result;
+    let shouldStop = false;
 
-      // Check dependencies
-      if (tx.dependsOn !== undefined) {
-        const dependencyResult = results[tx.dependsOn];
-        if (!dependencyResult.success) {
-          results.push({
-            index: i,
-            success: false,
-            error: 'Dependency failed',
+    for (let i = 0; i < inputs.length; i += this.chunkSize) {
+      if (shouldStop) break;
+      const chunk = inputs.slice(i, i + this.chunkSize);
+
+      for (let j = 0; j < chunk.length; j++) {
+        const input = chunk[j];
+        const index = i + j;
+        if (shouldStop && atomic) {
+          result.results.push({
+            index,
+            subscriptionId: input.name,
+            subscriptionName: input.name,
+            status: 'skipped',
+            retryCount: 0,
+            message: 'Skipped due to atomic failure',
           });
-          failCount++;
+          result.skippedItems++;
+          continue;
+        }
 
-          if (tx.required) {
-            shouldStop = true;
+        try {
+          const addResult = await addFn(input);
+          if (addResult.success) {
+            result.results.push({
+              index,
+              subscriptionId: addResult.id || input.name,
+              subscriptionName: input.name,
+              status: 'success',
+              retryCount: 0,
+              completedAt: new Date().toISOString(),
+            });
+            result.successfulItems++;
+          } else {
+            result.results.push({
+              index,
+              subscriptionId: input.name,
+              subscriptionName: input.name,
+              status: 'failed',
+              error: addResult.error || 'Unknown error',
+              retryCount: 0,
+              completedAt: new Date().toISOString(),
+            });
+            result.failedItems++;
+            if (atomic) shouldStop = true;
           }
-          continue;
+        } catch (err) {
+          result.results.push({
+            index,
+            subscriptionId: input.name,
+            subscriptionName: input.name,
+            status: 'failed',
+            error: String(err),
+            retryCount: 0,
+            completedAt: new Date().toISOString(),
+          });
+          result.failedItems++;
+          if (atomic) shouldStop = true;
         }
+
+        this.currentResult = { ...result };
       }
+    }
 
-      // Execute transaction
-      try {
-        console.log(`  📝 Executing: ${tx.functionName}`);
+    const rolledBack = atomic && result.failedItems > 0;
+    result.rolledBack = rolledBack;
+    result.completedAt = new Date().toISOString();
+    result.state = rolledBack
+      ? 'failed'
+      : result.failedItems === 0
+        ? 'completed'
+        : 'partial';
+
+    if (rolledBack) {
+      result.successfulItems = 0;
+      result.results = result.results.map((r) =>
+        r.status === 'success' ? { ...r, status: 'skipped', message: 'Rolled back (atomic failure)' } : r,
+      );
+      result.skippedItems += inputs.length - result.failedItems;
+    }
 
-        // Simulate execution
-        const result = await this.executeTransaction(tx);
-        const gasUsed = this.gasPerOperation;
+    this.currentResult = result;
+    await this.recordBatchHistory(result);
+    return result;
+  }
 
-        results.push({
-          index: i,
-          success: true,
-          result,
-        });
+  // ══════════════════════════════════════════════════════════════
+  // Batch Update (plan change, price change) with filtering
+  // ══════════════════════════════════════════════════════════════
+
+  async executeBatchUpdate(
+    subscriptionIds: string[],
+    updates: BatchUpdateParams,
+    updateFn: (id: string, updates: BatchUpdateParams) => Promise<{ success: boolean; error?: string }>,
+    options?: { atomic?: boolean; filter?: UpdateFilter },
+  ): Promise<BatchExecutionResult> {
+    const atomic = options?.atomic ?? false;
+    const filter = options?.filter;
+    const batchId = this.generateBatchId();
 
-        successCount++;
-        totalGas += gasUsed;
-      } catch (error) {
-        console.error(`  ❌ Transaction failed: ${tx.functionName}`, error);
+    const result: BatchExecutionResult = {
+      batchId,
+      operationType: 'update',
+      state: 'running',
+      totalItems: subscriptionIds.length,
+      successfulItems: 0,
+      failedItems: 0,
+      skippedItems: 0,
+      results: [],
+      atomic,
+      rolledBack: false,
+      gasEstimate: this.getGasEstimate(subscriptionIds.length),
+      startedAt: new Date().toISOString(),
+      filter,
+    };
 
-        results.push({
-          index: i,
-          success: false,
-          error: String(error),
-        });
+    this.currentResult = result;
+    let shouldStop = false;
 
-        failCount++;
+    for (let i = 0; i < subscriptionIds.length; i += this.chunkSize) {
+      if (shouldStop) break;
+      const chunk = subscriptionIds.slice(i, i + this.chunkSize);
+
+      for (let j = 0; j < chunk.length; j++) {
+        const subId = chunk[j];
+        const index = i + j;
+        if (shouldStop && atomic) {
+          result.results.push({
+            index,
+            subscriptionId: subId,
+            status: 'skipped',
+            retryCount: 0,
+            message: 'Skipped due to atomic failure',
+          });
+          result.skippedItems++;
+          continue;
+        }
 
-        if (tx.required) {
-          shouldStop = true;
+        try {
+          const updateResult = await updateFn(subId, updates);
+          if (updateResult.success) {
+            result.results.push({
+              index,
+              subscriptionId: subId,
+              status: 'success',
+              retryCount: 0,
+              completedAt: new Date().toISOString(),
+            });
+            result.successfulItems++;
+          } else {
+            result.results.push({
+              index,
+              subscriptionId: subId,
+              status: 'failed',
+              error: updateResult.error || 'Update failed',
+              retryCount: 0,
+              completedAt: new Date().toISOString(),
+            });
+            result.failedItems++;
+            if (atomic) shouldStop = true;
+          }
+        } catch (err) {
+          result.results.push({
+            index,
+            subscriptionId: subId,
+            status: 'failed',
+            error: String(err),
+            retryCount: 0,
+            completedAt: new Date().toISOString(),
+          });
+          result.failedItems++;
+          if (atomic) shouldStop = true;
         }
+
+        this.currentResult = { ...result };
       }
     }
 
-    const batchResult: BatchExecutionResult = {
-      batchId: this.generateBatchId(),
-      totalOperations: this.pendingTransactions.length,
-      successfulOperations: successCount,
-      failedOperations: failCount,
-      results,
+    const rolledBack = atomic && result.failedItems > 0;
+    result.rolledBack = rolledBack;
+    result.completedAt = new Date().toISOString();
+    result.state = rolledBack
+      ? 'failed'
+      : result.failedItems === 0
+        ? 'completed'
+        : 'partial';
+
+    if (rolledBack) {
+      result.successfulItems = 0;
+      result.results = result.results.map((r) =>
+        r.status === 'success' ? { ...r, status: 'skipped', message: 'Rolled back (atomic failure)' } : r,
+      );
+      result.skippedItems += subscriptionIds.length - result.failedItems;
+    }
+
+    this.currentResult = result;
+    await this.recordBatchHistory(result);
+    return result;
+  }
+
+  // ══════════════════════════════════════════════════════════════
+  // Batch Cancel with reason collection
+  // ══════════════════════════════════════════════════════════════
+
+  async executeBatchCancel(
+    subscriptionIds: string[],
+    cancelReasons: CancelReason[],
+    cancelFn: (id: string, reason: CancelReason) => Promise<{ success: boolean; error?: string }>,
+    options?: { atomic?: boolean },
+  ): Promise<BatchExecutionResult> {
+    const atomic = options?.atomic ?? false;
+    const batchId = this.generateBatchId();
+
+    const result: BatchExecutionResult = {
+      batchId,
+      operationType: 'cancel',
+      state: 'running',
+      totalItems: subscriptionIds.length,
+      successfulItems: 0,
+      failedItems: 0,
+      skippedItems: 0,
+      results: [],
       atomic,
-      gasEstimate: totalGas,
+      rolledBack: false,
+      gasEstimate: this.getGasEstimate(subscriptionIds.length),
+      startedAt: new Date().toISOString(),
+      cancelReasons,
     };
 
-    // Clear batch after execution
-    this.pendingTransactions = [];
+    this.currentResult = result;
+    let shouldStop = false;
 
-    console.log(`✅ Batch complete: ${successCount}/${batchResult.totalOperations} successful`);
-    console.log(`   Gas used: ${totalGas.toLocaleString()} units`);
+    for (let i = 0; i < subscriptionIds.length; i += this.chunkSize) {
+      if (shouldStop) break;
+      const chunk = subscriptionIds.slice(i, i + this.chunkSize);
+
+      for (let j = 0; j < chunk.length; j++) {
+        const subId = chunk[j];
+        const index = i + j;
+        if (shouldStop && atomic) {
+          result.results.push({
+            index,
+            subscriptionId: subId,
+            status: 'skipped',
+            retryCount: 0,
+            message: 'Skipped due to atomic failure',
+          });
+          result.skippedItems++;
+          continue;
+        }
 
-    return batchResult;
-  }
+        const reason = cancelReasons.find((r) => r.subscriptionId === subId) || {
+          subscriptionId: subId,
+          reason: 'other' as const,
+        };
+
+        try {
+          const cancelResult = await cancelFn(subId, reason);
+          if (cancelResult.success) {
+            result.results.push({
+              index,
+              subscriptionId: subId,
+              status: 'success',
+              retryCount: 0,
+              cancelReason: reason,
+              completedAt: new Date().toISOString(),
+            });
+            result.successfulItems++;
+          } else {
+            result.results.push({
+              index,
+              subscriptionId: subId,
+              status: 'failed',
+              error: cancelResult.error || 'Cancel failed',
+              retryCount: 0,
+              cancelReason: reason,
+              completedAt: new Date().toISOString(),
+            });
+            result.failedItems++;
+            if (atomic) shouldStop = true;
+          }
+        } catch (err) {
+          result.results.push({
+            index,
+            subscriptionId: subId,
+            status: 'failed',
+            error: String(err),
+            retryCount: 0,
+            cancelReason: reason,
+            completedAt: new Date().toISOString(),
+          });
+          result.failedItems++;
+          if (atomic) shouldStop = true;
+        }
 
-  /**
-   * Execute single transaction (simulated)
-   */
-  private async executeTransaction(_tx: BatchTransaction): Promise<any> {
-    // In real implementation, call actual contract function
-    // For now, simulate with delay
-    return new Promise((resolve) => {
-      setTimeout(() => {
-        resolve({ success: true, txHash: `0x${Math.random().toString(16).slice(2)}` });
-      }, 100);
-    });
-  }
+        this.currentResult = { ...result };
+      }
+    }
 
-  /**
-   * Clear pending batch
-   */
-  clearBatch(): void {
-    this.pendingTransactions = [];
-    console.log('🗑️ Batch cleared');
-  }
+    const rolledBack = atomic && result.failedItems > 0;
+    result.rolledBack = rolledBack;
+    result.completedAt = new Date().toISOString();
+    result.state = rolledBack
+      ? 'failed'
+      : result.failedItems === 0
+        ? 'completed'
+        : 'partial';
+
+    if (rolledBack) {
+      result.successfulItems = 0;
+      result.results = result.results.map((r) =>
+        r.status === 'success' ? { ...r, status: 'skipped', message: 'Rolled back (atomic failure)' } : r,
+      );
+      result.skippedItems += subscriptionIds.length - result.failedItems;
+    }
 
-  /**
-   * Get gas estimate for pending batch
-   */
-  getGasEstimate(): number {
-    return this.baseGasCost + this.pendingTransactions.length * this.gasPerOperation;
+    this.currentResult = result;
+    await this.recordBatchHistory(result);
+    return result;
   }
 
-  /**
-   * Get batch summary
-   */
-  getBatchSummary(): {
-    pending: number;
-    maxSize: number;
-    estimatedGas: number;
-    isFull: boolean;
-    gasPercentFull: number;
-  } {
-    const pending = this.pendingTransactions.length;
-    const percentFull = (pending / this.maxBatchSize) * 100;
+  // ══════════════════════════════════════════════════════════════
+  // Batch Charge for manual billing runs
+  // ══════════════════════════════════════════════════════════════
 
-    return {
-      pending,
-      maxSize: this.maxBatchSize,
-      estimatedGas: this.getGasEstimate(),
-      isFull: this.isBatchReady(),
-      gasPercentFull: percentFull,
+  async executeBatchCharge(
+    chargeItems: Array<{ subscriptionId: string; amount: number }>,
+    chargeFn: (id: string, amount: number) => Promise<{ success: boolean; error?: string }>,
+    options?: { atomic?: boolean },
+  ): Promise<BatchExecutionResult> {
+    const atomic = options?.atomic ?? false;
+    const batchId = this.generateBatchId();
+
+    const result: BatchExecutionResult = {
+      batchId,
+      operationType: 'charge',
+      state: 'running',
+      totalItems: chargeItems.length,
+      successfulItems: 0,
+      failedItems: 0,
+      skippedItems: 0,
+      results: [],
+      atomic,
+      rolledBack: false,
+      gasEstimate: this.getGasEstimate(chargeItems.length),
+      startedAt: new Date().toISOString(),
     };
+
+    this.currentResult = result;
+    let shouldStop = false;
+
+    for (let i = 0; i < chargeItems.length; i += this.chunkSize) {
+      if (shouldStop) break;
+      const chunk = chargeItems.slice(i, i + this.chunkSize);
+
+      for (let j = 0; j < chunk.length; j++) {
+        const item = chunk[j];
+        const index = i + j;
+        if (shouldStop && atomic) {
+          result.results.push({
+            index,
+            subscriptionId: item.subscriptionId,
+            status: 'skipped',
+            retryCount: 0,
+            message: 'Skipped due to atomic failure',
+          });
+          result.skippedItems++;
+          continue;
+        }
+
+        try {
+          const chargeResult = await chargeFn(item.subscriptionId, item.amount);
+          if (chargeResult.success) {
+            result.results.push({
+              index,
+              subscriptionId: item.subscriptionId,
+              status: 'success',
+              retryCount: 0,
+              completedAt: new Date().toISOString(),
+              message: `Charged ${item.amount}`,
+            });
+            result.successfulItems++;
+          } else {
+            result.results.push({
+              index,
+              subscriptionId: item.subscriptionId,
+              status: 'failed',
+              error: chargeResult.error || 'Charge failed',
+              retryCount: 0,
+              completedAt: new Date().toISOString(),
+            });
+            result.failedItems++;
+            if (atomic) shouldStop = true;
+          }
+        } catch (err) {
+          result.results.push({
+            index,
+            subscriptionId: item.subscriptionId,
+            status: 'failed',
+            error: String(err),
+            retryCount: 0,
+            completedAt: new Date().toISOString(),
+          });
+          result.failedItems++;
+          if (atomic) shouldStop = true;
+        }
+
+        this.currentResult = { ...result };
+      }
+    }
+
+    const rolledBack = atomic && result.failedItems > 0;
+    result.rolledBack = rolledBack;
+    result.completedAt = new Date().toISOString();
+    result.state = rolledBack
+      ? 'failed'
+      : result.failedItems === 0
+        ? 'completed'
+        : 'partial';
+
+    if (rolledBack) {
+      result.successfulItems = 0;
+      result.results = result.results.map((r) =>
+        r.status === 'success' ? { ...r, status: 'skipped', message: 'Rolled back (atomic failure)' } : r,
+      );
+      result.skippedItems += chargeItems.length - result.failedItems;
+    }
+
+    this.currentResult = result;
+    await this.recordBatchHistory(result);
+    return result;
   }
 
-  /**
-   * Set maximum batch size
-   */
-  setMaxBatchSize(size: number): void {
-    if (size > 100) {
-      console.warn('Max batch size should not exceed 100');
-      return;
+  // ══════════════════════════════════════════════════════════════
+  // Idempotent Retry of Failed Items
+  // ══════════════════════════════════════════════════════════════
+
+  async retryFailedItems(
+    retryFn: (item: PerItemResult) => Promise<{ success: boolean; error?: string }>,
+  ): Promise<BatchExecutionResult | null> {
+    if (!this.currentResult) return null;
+
+    const result = { ...this.currentResult };
+    const failedItems = result.results.filter((r) => r.status === 'failed');
+
+    if (failedItems.length === 0) return result;
+
+    result.state = 'running';
+    this.currentResult = result;
+
+    for (const item of failedItems) {
+      if (item.retryCount >= this.retryConfig.maxRetries) {
+        continue;
+      }
+
+      const delay =
+        this.retryConfig.retryDelayMs *
+        Math.pow(this.retryConfig.backoffMultiplier, item.retryCount);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+
+      try {
+        const retryResult = await retryFn(item);
+        if (retryResult.success) {
+          item.status = 'success';
+          item.retryCount++;
+          item.error = undefined;
+          item.completedAt = new Date().toISOString();
+          result.successfulItems++;
+          result.failedItems--;
+        } else {
+          item.retryCount++;
+          item.error = retryResult.error || 'Retry failed';
+        }
+      } catch (err) {
+        item.retryCount++;
+        item.error = String(err);
+      }
+
+      this.currentResult = { ...result };
     }
-    this.maxBatchSize = size;
-    console.log(`📦 Max batch size set to: ${size}`);
+
+    result.completedAt = new Date().toISOString();
+    result.state =
+      result.failedItems === 0 ? 'completed' : 'partial';
+    this.currentResult = result;
+
+    return result;
   }
 
-  /**
-   * Generate unique batch ID
-   */
-  private generateBatchId(): string {
-    const timestamp = Date.now();
-    const random = Math.random().toString(36).substr(2, 9);
-    return `batch_${timestamp}_${random}`;
+  // ══════════════════════════════════════════════════════════════
+  // History
+  // ══════════════════════════════════════════════════════════════
+
+  private async recordBatchHistory(result: BatchExecutionResult): Promise<void> {
+    const entry: BatchHistoryEntry = {
+      batchId: result.batchId,
+      operationType: result.operationType,
+      state: result.state,
+      totalItems: result.totalItems,
+      successfulItems: result.successfulItems,
+      failedItems: result.failedItems,
+      timestamp: new Date().toISOString(),
+      summary: `${result.operationType}: ${result.successfulItems}/${result.totalItems} succeeded`,
+    };
+    await saveBatchHistory(entry);
   }
 
-  /**
-   * Calculate gas savings
-   */
-  calculateGasSavings(): {
-    individual: number;
-    batched: number;
-    savings: number;
-    percentSavings: number;
-  } {
-    const numTx = this.pendingTransactions.length;
-    const individualGas = numTx * (this.baseGasCost + this.gasPerOperation);
-    const batchedGas = this.getGasEstimate();
-    const savings = individualGas - batchedGas;
-    const percentSavings = (savings / individualGas) * 100;
+  clearResult(): void {
+    this.currentResult = null;
+  }
 
-    return {
-      individual: individualGas,
-      batched: batchedGas,
-      savings,
-      percentSavings,
-    };
+  clearIdempotencyKeys(): void {
+    this.idempotencyKeys.clear();
   }
 }
 
-// Export for use in React components
 export default BatchTransactionService;
diff --git a/app/services/hooks/useBatchTransactions.ts b/app/services/hooks/useBatchTransactions.ts
index 8aed9c2..641eed0 100644
--- a/app/services/hooks/useBatchTransactions.ts
+++ b/app/services/hooks/useBatchTransactions.ts
@@ -3,128 +3,156 @@
 // ════════════════════════════════════════════════════════════════
 
 import { useState, useCallback } from 'react';
-import BatchTransactionService, { BatchExecutionResult } from '../batchTransactionService';
+import {
+  BatchTransactionService,
+  BatchExecutionResult,
+  BatchCreateInput,
+  BatchUpdateParams,
+  UpdateFilter,
+  CancelReason,
+  PerItemResult,
+  BatchProgress,
+} from '../batchTransactionService';
 
 interface UseBatchTransactionsProps {
-  maxBatchSize?: number;
+  chunkSize?: number;
 }
 
-/**
- * React hook for managing batch transactions
- */
-export function useBatchTransactions({ maxBatchSize = 10 }: UseBatchTransactionsProps = {}) {
-  const [service] = useState(() => new BatchTransactionService(maxBatchSize));
-
-  const [pending, setPending] = useState(0);
-  const [executing, setExecuting] = useState(false);
+export function useBatchTransactions({ chunkSize = 50 }: UseBatchTransactionsProps = {}) {
+  const [service] = useState(() => new BatchTransactionService(chunkSize));
+  const [isRunning, setIsRunning] = useState(false);
   const [lastResult, setLastResult] = useState<BatchExecutionResult | null>(null);
-
-  /**
-   * Add transaction to batch
-   */
-  const addTransaction = useCallback(
-    (functionName: string, params: any[], required: boolean = true) => {
-      const added = service.addTransaction(functionName, params, required);
-      if (added) {
-        setPending(service.getPendingCount());
+  const [progress, setProgress] = useState<BatchProgress | null>(null);
+
+  const executeCreate = useCallback(
+    async (
+      inputs: BatchCreateInput[],
+      addFn: (input: BatchCreateInput) => Promise<{ success: boolean; id?: string; error?: string }>,
+      atomic?: boolean,
+    ) => {
+      setIsRunning(true);
+      try {
+        const result = await service.executeBatchCreate(inputs, addFn, { atomic });
+        setLastResult(result);
+        setProgress(service.getProgress());
+        return result;
+      } catch (error) {
+        console.error('Batch create failed:', error);
+        throw error;
+      } finally {
+        setIsRunning(false);
       }
-      return added;
     },
-    [service]
+    [service],
   );
 
-  /**
-   * Add transaction with dependency
-   */
-  const addTransactionWithDependency = useCallback(
-    (functionName: string, params: any[], dependsOn: number, required: boolean = true) => {
-      const added = service.addTransactionWithDependency(functionName, params, dependsOn, required);
-      if (added) {
-        setPending(service.getPendingCount());
+  const executeUpdate = useCallback(
+    async (
+      subscriptionIds: string[],
+      updates: BatchUpdateParams,
+      updateFn: (id: string, updates: BatchUpdateParams) => Promise<{ success: boolean; error?: string }>,
+      options?: { atomic?: boolean; filter?: UpdateFilter },
+    ) => {
+      setIsRunning(true);
+      try {
+        const result = await service.executeBatchUpdate(subscriptionIds, updates, updateFn, options);
+        setLastResult(result);
+        setProgress(service.getProgress());
+        return result;
+      } catch (error) {
+        console.error('Batch update failed:', error);
+        throw error;
+      } finally {
+        setIsRunning(false);
       }
-      return added;
     },
-    [service]
+    [service],
   );
 
-  /**
-   * Simulate batch
-   */
-  const simulateBatch = useCallback(async () => {
-    const result = await service.simulateBatch();
-    setLastResult(result);
-    return result;
-  }, [service]);
-
-  /**
-   * Execute batch
-   */
-  const executeBatch = useCallback(
-    async (atomic: boolean = true) => {
-      setExecuting(true);
+  const executeCancel = useCallback(
+    async (
+      subscriptionIds: string[],
+      cancelReasons: CancelReason[],
+      cancelFn: (id: string, reason: CancelReason) => Promise<{ success: boolean; error?: string }>,
+      atomic?: boolean,
+    ) => {
+      setIsRunning(true);
       try {
-        const result = await service.executeBatch(atomic);
+        const result = await service.executeBatchCancel(subscriptionIds, cancelReasons, cancelFn, { atomic });
         setLastResult(result);
-        setPending(0);
+        setProgress(service.getProgress());
         return result;
       } catch (error) {
-        console.error('❌ Batch execution failed:', error);
+        console.error('Batch cancel failed:', error);
         throw error;
       } finally {
-        setExecuting(false);
+        setIsRunning(false);
       }
     },
-    [service]
+    [service],
   );
 
-  /**
-   * Clear batch
-   */
-  const clearBatch = useCallback(() => {
-    service.clearBatch();
-    setPending(0);
-  }, [service]);
-
-  /**
-   * Get gas estimate
-   */
-  const getGasEstimate = useCallback(() => {
-    return service.getGasEstimate();
-  }, [service]);
+  const executeCharge = useCallback(
+    async (
+      chargeItems: Array<{ subscriptionId: string; amount: number }>,
+      chargeFn: (id: string, amount: number) => Promise<{ success: boolean; error?: string }>,
+      atomic?: boolean,
+    ) => {
+      setIsRunning(true);
+      try {
+        const result = await service.executeBatchCharge(chargeItems, chargeFn, { atomic });
+        setLastResult(result);
+        setProgress(service.getProgress());
+        return result;
+      } catch (error) {
+        console.error('Batch charge failed:', error);
+        throw error;
+      } finally {
+        setIsRunning(false);
+      }
+    },
+    [service],
+  );
 
-  /**
-   * Get batch summary
-   */
-  const getBatchSummary = useCallback(() => {
-    return service.getBatchSummary();
-  }, [service]);
+  const retryFailed = useCallback(
+    async (
+      retryFn: (item: PerItemResult) => Promise<{ success: boolean; error?: string }>,
+    ) => {
+      setIsRunning(true);
+      try {
+        const result = await service.retryFailedItems(retryFn);
+        setLastResult(result);
+        setProgress(service.getProgress());
+        return result;
+      } catch (error) {
+        console.error('Retry failed:', error);
+        throw error;
+      } finally {
+        setIsRunning(false);
+      }
+    },
+    [service],
+  );
 
-  /**
-   * Get gas savings
-   */
-  const getGasSavings = useCallback(() => {
-    return service.calculateGasSavings();
+  const clearResult = useCallback(() => {
+    service.clearResult();
+    setLastResult(null);
+    setProgress(null);
   }, [service]);
 
   return {
-    // State
-    pending,
-    executing,
+    isRunning,
     lastResult,
-
-    // Actions
-    addTransaction,
-    addTransactionWithDependency,
-    simulateBatch,
-    executeBatch,
-    clearBatch,
-    getGasEstimate,
-    getBatchSummary,
-    getGasSavings,
-
-    // Helpers
-    isBatchReady: () => service.isBatchReady(),
-    isRunning: executing,
+    progress,
+    executeCreate,
+    executeUpdate,
+    executeCancel,
+    executeCharge,
+    retryFailed,
+    clearResult,
+    getGasEstimate: (count: number) => service.getGasEstimate(count),
+    setChunkSize: (size: number) => service.setChunkSize(size),
+    getProgress: () => service.getProgress(),
   };
 }
 
diff --git a/app/stores/__tests__/batchStore.test.ts b/app/stores/__tests__/batchStore.test.ts
index 9297b7e..b420fc7 100644
--- a/app/stores/__tests__/batchStore.test.ts
+++ b/app/stores/__tests__/batchStore.test.ts
@@ -1,17 +1,33 @@
 import {
   useBatchStore,
-  parseCsvTemplate,
-  validateBatch,
   estimateBatchGas,
-  ItemExecutor,
+  validateBatchSize,
+  BatchOperationType,
+  BatchDraft,
+  CancelReason,
 } from '../batchStore';
 
+const emptyDraft = (): BatchDraft => ({
+  operationType: 'create' as BatchOperationType,
+  atomic: false,
+  createInputs: [],
+  updateIds: [],
+  updateParams: {},
+  cancelIds: [],
+  cancelReasons: [],
+  chargeItems: [],
+  csvContent: '',
+  chunkSize: 50,
+});
+
 const reset = () =>
   useBatchStore.setState({
-    draft: { operationType: 'charge', subscriptionIds: [], params: [], atomic: false },
-    current: undefined,
+    draft: emptyDraft(),
+    currentResult: null,
     history: [],
     executor: async (_op, subscriptionId) => ({ subscriptionId, success: true }),
+    isRunning: false,
+    progress: null,
   });
 
 beforeEach(reset);
@@ -22,66 +38,89 @@ describe('batch helpers', () => {
   });
 
   it('validates batch size bounds', () => {
-    expect(validateBatch({ operationType: 'charge', subscriptionIds: [], params: [], atomic: false })).toBe(false);
-    expect(
-      validateBatch({ operationType: 'charge', subscriptionIds: ['a'], params: [], atomic: false }),
-    ).toBe(true);
-    const big = Array.from({ length: 101 }, (_, i) => `s${i}`);
-    expect(validateBatch({ operationType: 'charge', subscriptionIds: big, params: [], atomic: false })).toBe(false);
+    expect(validateBatchSize(0)).toBe(false);
+    expect(validateBatchSize(1)).toBe(true);
+    expect(validateBatchSize(501)).toBe(false);
+  });
+});
+
+describe('CSV parsing', () => {
+  it('parses create CSV and loads inputs', () => {
+    useBatchStore.getState().loadCreateCsv(
+      'name,description,category,price,currency,billingCycle\nNetflix,Streaming,streaming,15.99,USD,monthly',
+    );
+    const draft = useBatchStore.getState().draft;
+    expect(draft.createInputs.length).toBe(1);
+    expect(draft.createInputs[0].name).toBe('Netflix');
+    expect(draft.createInputs[0].price).toBe(15.99);
   });
 
-  it('parses CSV templates and skips the header row', () => {
-    const op = parseCsvTemplate('subscriptionId,amount\nsub_1,1000\nsub_2,2000', 'charge');
-    expect(op.subscriptionIds).toEqual(['sub_1', 'sub_2']);
-    expect(op.params).toEqual([1000, 2000]);
+  it('parses cancel CSV with reasons', () => {
+    useBatchStore.getState().loadCancelCsv(
+      'subscriptionId,reason,notes\nsub_1,too_expensive,\nsub_2,other,Switched',
+    );
+    const draft = useBatchStore.getState().draft;
+    expect(draft.cancelIds).toEqual(['sub_1', 'sub_2']);
+    expect(draft.cancelReasons.length).toBe(2);
+    expect(draft.cancelReasons[0].reason).toBe('too_expensive');
+  });
+
+  it('parses charge CSV with amounts', () => {
+    useBatchStore.getState().loadChargeCsv(
+      'subscriptionId,amount\nsub_1,1000\nsub_2,2000',
+    );
+    const draft = useBatchStore.getState().draft;
+    expect(draft.chargeItems.length).toBe(2);
+    expect(draft.chargeItems[0].amount).toBe(1000);
   });
 });
 
 describe('useBatchStore execution', () => {
-  it('completes a fully successful batch', async () => {
-    const store = useBatchStore.getState();
-    store.loadFromCsv('sub_1,100\nsub_2,100', 'charge');
-    store.createBatch();
+  it('completes a fully successful charge batch', async () => {
+    useBatchStore.getState().loadChargeCsv('subscriptionId,amount\nsub_1,100\nsub_2,100');
     const result = await useBatchStore.getState().executeBatch();
     expect(result?.state).toBe('completed');
-    expect(result?.succeeded).toBe(2);
-    expect(result?.failed).toBe(0);
+    expect(result?.successfulItems).toBe(2);
+    expect(result?.failedItems).toBe(0);
   });
 
   it('reports partial success in non-atomic mode', async () => {
-    const executor: ItemExecutor = async (_op, id) => ({
+    useBatchStore.getState().setExecutor(async (_op, id) => ({
       subscriptionId: id,
       success: id === 'sub_1',
-    });
-    useBatchStore.getState().setExecutor(executor);
-    useBatchStore.getState().loadFromCsv('sub_1,100\nsub_2,100', 'charge', false);
-    useBatchStore.getState().createBatch();
+    }));
+    useBatchStore.getState().loadChargeCsv('subscriptionId,amount\nsub_1,100\nsub_2,100');
     const result = await useBatchStore.getState().executeBatch();
     expect(result?.state).toBe('partial');
-    expect(result?.succeeded).toBe(1);
-    expect(result?.failed).toBe(1);
+    expect(result?.successfulItems).toBe(1);
+    expect(result?.failedItems).toBe(1);
     expect(result?.rolledBack).toBe(false);
   });
 
   it('rolls back an atomic batch on any failure', async () => {
-    const executor: ItemExecutor = async (_op, id) => ({
+    useBatchStore.getState().setExecutor(async (_op, id) => ({
       subscriptionId: id,
       success: id === 'sub_1',
-    });
-    useBatchStore.getState().setExecutor(executor);
-    useBatchStore.getState().loadFromCsv('sub_1,100\nsub_2,100', 'charge', true);
-    useBatchStore.getState().createBatch();
+    }));
+    useBatchStore.getState().loadChargeCsv('subscriptionId,amount\nsub_1,100\nsub_2,100');
+    useBatchStore.getState().setDraft({ atomic: true });
     const result = await useBatchStore.getState().executeBatch();
     expect(result?.state).toBe('failed');
     expect(result?.rolledBack).toBe(true);
-    expect(result?.succeeded).toBe(0);
+  });
+
+  it('executes create batch from inputs', async () => {
+    useBatchStore.getState().loadCreateCsv(
+      'name,category,price,currency,billingCycle\nTest,streaming,9.99,USD,monthly',
+    );
+    const result = await useBatchStore.getState().executeBatch();
+    expect(result?.state).toBe('completed');
+    expect(result?.operationType).toBe('create');
   });
 
   it('appends executed batches to history', async () => {
-    const store = useBatchStore.getState();
-    store.loadFromCsv('sub_1,100', 'charge');
-    store.createBatch();
+    useBatchStore.getState().loadChargeCsv('subscriptionId,amount\nsub_1,100');
     await useBatchStore.getState().executeBatch();
-    expect(useBatchStore.getState().history.length).toBe(1);
+    expect(useBatchStore.getState().history.length).toBeGreaterThan(0);
   });
 });
diff --git a/app/stores/batchStore.ts b/app/stores/batchStore.ts
index 22b6e44..4d063ef 100644
--- a/app/stores/batchStore.ts
+++ b/app/stores/batchStore.ts
@@ -1,105 +1,133 @@
 // ════════════════════════════════════════════════════════════════
-// BATCH STORE - client state for bulk subscription operations
+// BATCH STORE - Full client state for bulk subscription operations
 // ════════════════════════════════════════════════════════════════
 //
-// Mirrors the `subtrackr-batch` Soroban contract: the user assembles a batch of
-// one operation type applied across many subscriptions, then creates + executes
-// it. The store tracks progress, partial success, rollback (atomic), and keeps
-// an audit history of past batches.
+// Supports: batch create from CSV/JSON, batch update with filtering,
+// batch cancel with reason collection, batch charge for manual billing,
+// per-item status tracking, idempotent retry, result export, and
+// audit history of past batches.
 
 import { create } from 'zustand';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import {
+  BatchTransactionService,
+  BatchOperationType,
+  BatchState,
+  BatchExecutionResult,
+  PerItemResult,
+  CancelReason,
+  UpdateFilter,
+  BatchUpdateParams,
+  BatchCreateInput,
+  PerItemStatus,
+  BatchProgress,
+  BatchHistoryEntry,
+  parseBatchCreateCsv,
+  parseBatchCancelCsv,
+  parseBatchChargeCsv,
+  exportBatchResultToJson,
+  exportBatchResultToCsv,
+  getBatchHistory,
+  saveBatchHistory,
+  clearBatchHistory,
+} from '../services/batchTransactionService';
 
-export type OperationType = 'create' | 'update' | 'charge' | 'pause' | 'resume' | 'cancel';
+const HISTORY_STORE_KEY = 'subtrackr-batch-store-history';
+const MAX_STORE_HISTORY = 100;
 
-export type BatchState = 'pending' | 'running' | 'completed' | 'partial' | 'failed';
+// ════════════════════════════════════════════════════════════════
+// Types
+// ════════════════════════════════════════════════════════════════
 
-export interface BatchOperation {
-  operationType: OperationType;
-  subscriptionIds: string[];
-  /** Per-subscription scalar argument (e.g. charge amount); missing entries default to 0. */
-  params: number[];
-  atomic: boolean;
-}
+export type { BatchOperationType, BatchState, PerItemStatus, CancelReason, UpdateFilter, BatchUpdateParams, BatchCreateInput, PerItemResult, BatchProgress, BatchHistoryEntry };
+export { exportBatchResultToJson, exportBatchResultToCsv, getBatchHistory, saveBatchHistory, clearBatchHistory };
 
-export interface OperationResult {
-  subscriptionId: string;
-  success: boolean;
-  message?: string;
-}
-
-export interface BatchRecord {
-  id: string;
-  operation: BatchOperation;
-  state: BatchState;
-  total: number;
-  succeeded: number;
-  failed: number;
-  rolledBack: boolean;
-  results: OperationResult[];
-  createdAt: number;
+export interface BatchDraft {
+  operationType: BatchOperationType;
+  atomic: boolean;
+  createInputs: BatchCreateInput[];
+  updateIds: string[];
+  updateParams: BatchUpdateParams;
+  updateFilter?: UpdateFilter;
+  cancelIds: string[];
+  cancelReasons: CancelReason[];
+  chargeItems: Array<{ subscriptionId: string; amount: number }>;
+  csvContent: string;
+  chunkSize: number;
 }
 
-/** Executes a single item; resolves a result. Injected so the store can be
- * backed by the contract, an API, or a mock in tests. Defaults to a no-op
- * success so the UI is usable without a backend. */
 export type ItemExecutor = (
-  op: OperationType,
+  operationType: BatchOperationType,
   subscriptionId: string,
-  param: number,
-) => Promise<OperationResult>;
-
-const MAX_BATCH_SIZE = 100;
-const BASE_GAS = 50_000;
-const GAS_PER_OP = 100_000;
-
-export const estimateBatchGas = (count: number): number => BASE_GAS + count * GAS_PER_OP;
-
-export const validateBatch = (op: BatchOperation): boolean =>
-  op.subscriptionIds.length > 0 && op.subscriptionIds.length <= MAX_BATCH_SIZE;
-
-/** Builds a batch operation from a CSV template of `subscriptionId,param` rows. */
-export const parseCsvTemplate = (
-  csv: string,
-  operationType: OperationType,
-  atomic = false,
-): BatchOperation => {
-  const subscriptionIds: string[] = [];
-  const params: number[] = [];
-  csv
-    .split(/\r?\n/)
-    .map((l) => l.trim())
-    .filter((l) => l.length > 0 && !l.toLowerCase().startsWith('subscription'))
-    .forEach((line) => {
-      const [id, param] = line.split(',').map((c) => c.trim());
-      if (!id) return;
-      subscriptionIds.push(id);
-      params.push(param ? Number(param) : 0);
-    });
-  return { operationType, subscriptionIds, params, atomic };
-};
+  param: number | string,
+  reason?: CancelReason,
+) => Promise<{ success: boolean; id?: string; error?: string }>;
+
+const MAX_BATCH_SIZE = 500;
+const DEFAULT_CHUNK_SIZE = 50;
+
+export const estimateBatchGas = (count: number): number => 50_000 + count * 100_000;
+
+export const validateBatchSize = (count: number): boolean =>
+  count > 0 && count <= MAX_BATCH_SIZE;
+
+// ════════════════════════════════════════════════════════════════
+// Store
+// ════════════════════════════════════════════════════════════════
 
 interface BatchStoreState {
-  draft: BatchOperation;
-  current?: BatchRecord;
-  history: BatchRecord[];
+  draft: BatchDraft;
+  currentResult: BatchExecutionResult | null;
+  history: BatchHistoryEntry[];
+  service: BatchTransactionService | null;
   executor: ItemExecutor;
+  isRunning: boolean;
+  progress: BatchProgress | null;
 
+  // Actions
   setExecutor: (executor: ItemExecutor) => void;
-  setDraft: (patch: Partial<BatchOperation>) => void;
-  loadFromCsv: (csv: string, operationType: OperationType, atomic?: boolean) => void;
-  resetDraft: () => void;
+  setDraft: (patch: Partial<BatchDraft>) => void;
+  setOperationType: (op: BatchOperationType) => void;
+  toggleAtomic: () => void;
+  setChunkSize: (size: number) => void;
+
+  // CSV loading
+  loadCreateCsv: (csv: string) => void;
+  loadCancelCsv: (csv: string) => void;
+  loadChargeCsv: (csv: string) => void;
+  loadUpdateCsv: (csv: string) => void;
+  setCsvContent: (csv: string) => void;
+
+  // Execute
+  executeBatch: () => Promise<BatchExecutionResult | null>;
+  retryFailed: () => Promise<BatchExecutionResult | null>;
+
+  // Export
+  exportResultJson: () => string | null;
+  exportResultCsv: () => string | null;
+
+  // History
+  loadHistory: () => Promise<void>;
+  addHistoryEntry: (entry: BatchHistoryEntry) => Promise<void>;
+
+  // Helpers
   gasEstimate: () => number;
-  /** Validates + materializes the draft into a pending batch record. */
-  createBatch: () => BatchRecord | null;
-  /** Runs the current batch, applying partial-success / atomic-rollback rules. */
-  executeBatch: () => Promise<BatchRecord | null>;
+  resetDraft: () => void;
+  clearResult: () => void;
 }
 
-const emptyDraft = (): BatchOperation => ({
-  operationType: 'charge',
-  subscriptionIds: [],
-  params: [],
+const emptyDraft = (): BatchDraft => ({
+  operationType: 'create',
   atomic: false,
+  createInputs: [],
+  updateIds: [],
+  updateParams: {},
+  updateFilter: undefined,
+  cancelIds: [],
+  cancelReasons: [],
+  chargeItems: [],
+  csvContent: '',
+  chunkSize: DEFAULT_CHUNK_SIZE,
 });
 
 const defaultExecutor: ItemExecutor = async (_op, subscriptionId) => ({
@@ -109,80 +137,275 @@ const defaultExecutor: ItemExecutor = async (_op, subscriptionId) => ({
 
 export const useBatchStore = create<BatchStoreState>()((set, get) => ({
   draft: emptyDraft(),
-  current: undefined,
+  currentResult: null,
   history: [],
+  service: null,
   executor: defaultExecutor,
+  isRunning: false,
+  progress: null,
 
   setExecutor: (executor) => set({ executor }),
+
   setDraft: (patch) => set((s) => ({ draft: { ...s.draft, ...patch } })),
-  loadFromCsv: (csv, operationType, atomic = false) =>
-    set({ draft: parseCsvTemplate(csv, operationType, atomic) }),
-  resetDraft: () => set({ draft: emptyDraft() }),
 
-  gasEstimate: () => estimateBatchGas(get().draft.subscriptionIds.length),
+  setOperationType: (op) =>
+    set((s) => ({
+      draft: { ...s.draft, operationType: op, csvContent: '' },
+    })),
 
-  createBatch: () => {
-    const { draft } = get();
-    if (!validateBatch(draft)) return null;
-    const record: BatchRecord = {
-      id: `batch_${Date.now()}`,
-      operation: { ...draft },
-      state: 'pending',
-      total: draft.subscriptionIds.length,
-      succeeded: 0,
-      failed: 0,
-      rolledBack: false,
-      results: [],
-      createdAt: Date.now(),
-    };
-    set({ current: record });
-    return record;
+  toggleAtomic: () =>
+    set((s) => ({ draft: { ...s.draft, atomic: !s.draft.atomic } })),
+
+  setChunkSize: (size) =>
+    set((s) => ({
+      draft: { ...s.draft, chunkSize: Math.min(size, MAX_BATCH_SIZE) },
+    })),
+
+  // ── CSV Loading ──────────────────────────────────────────────
+
+  setCsvContent: (csv) => set((s) => ({ draft: { ...s.draft, csvContent: csv } })),
+
+  loadCreateCsv: (csv) => {
+    const inputs = parseBatchCreateCsv(csv);
+    set((s) => ({
+      draft: {
+        ...s.draft,
+        csvContent: csv,
+        operationType: 'create',
+        createInputs: inputs,
+      },
+    }));
   },
 
+  loadCancelCsv: (csv) => {
+    const parsed = parseBatchCancelCsv(csv);
+    const ids = parsed.map((r) => r.subscriptionId);
+    const reasons: CancelReason[] = parsed.map((r) => ({
+      subscriptionId: r.subscriptionId,
+      reason: (['too_expensive', 'no_longer_needed', 'found_alternative', 'poor_service', 'other'].includes(r.reason)
+        ? r.reason
+        : 'other') as CancelReason['reason'],
+      notes: r.notes,
+    }));
+    set((s) => ({
+      draft: {
+        ...s.draft,
+        csvContent: csv,
+        operationType: 'cancel',
+        cancelIds: ids,
+        cancelReasons: reasons,
+      },
+    }));
+  },
+
+  loadChargeCsv: (csv) => {
+    const items = parseBatchChargeCsv(csv);
+    set((s) => ({
+      draft: {
+        ...s.draft,
+        csvContent: csv,
+        operationType: 'charge',
+        chargeItems: items,
+      },
+    }));
+  },
+
+  loadUpdateCsv: (csv) => {
+    const lines = csv.split(/\r?\n/).filter((l) => l.trim());
+    if (lines.length < 2) return;
+    const ids: string[] = [];
+    for (let i = 1; i < lines.length; i++) {
+      const id = lines[i].split(',')[0]?.trim();
+      if (id) ids.push(id);
+    }
+    set((s) => ({
+      draft: {
+        ...s.draft,
+        csvContent: csv,
+        operationType: 'update',
+        updateIds: ids,
+      },
+    }));
+  },
+
+  // ── Execute ──────────────────────────────────────────────────
+
   executeBatch: async () => {
-    const { current, executor } = get();
-    if (!current || current.state !== 'pending') return null;
-
-    set({ current: { ...current, state: 'running' } });
-
-    const op = current.operation;
-    const results: OperationResult[] = [];
-    let succeeded = 0;
-    let failed = 0;
-
-    for (let i = 0; i < op.subscriptionIds.length; i++) {
-      const subId = op.subscriptionIds[i];
-      const param = op.params[i] ?? 0;
-      let result: OperationResult;
-      try {
-        result = await executor(op.operationType, subId, param);
-      } catch (e) {
-        result = { subscriptionId: subId, success: false, message: String(e) };
+    const { draft, executor } = get();
+    const service = new BatchTransactionService(draft.chunkSize);
+    set({ isRunning: true, currentResult: null, progress: null });
+
+    let result: BatchExecutionResult | null = null;
+
+    try {
+      switch (draft.operationType) {
+        case 'create': {
+          if (draft.createInputs.length === 0) break;
+          result = await service.executeBatchCreate(
+            draft.createInputs,
+            async (input) => {
+              const r = await executor('create', input.name, input.price);
+              return r;
+            },
+            { atomic: draft.atomic },
+          );
+          break;
+        }
+
+        case 'update': {
+          if (draft.updateIds.length === 0) break;
+          result = await service.executeBatchUpdate(
+            draft.updateIds,
+            draft.updateParams,
+            async (id, updates) => {
+              const r = await executor('update', id, JSON.stringify(updates));
+              return r;
+            },
+            { atomic: draft.atomic, filter: draft.updateFilter },
+          );
+          break;
+        }
+
+        case 'cancel': {
+          if (draft.cancelIds.length === 0) break;
+          result = await service.executeBatchCancel(
+            draft.cancelIds,
+            draft.cancelReasons,
+            async (id, reason) => {
+              const r = await executor('cancel', id, reason.reason, reason);
+              return r;
+            },
+            { atomic: draft.atomic },
+          );
+          break;
+        }
+
+        case 'charge': {
+          if (draft.chargeItems.length === 0) break;
+          result = await service.executeBatchCharge(
+            draft.chargeItems,
+            async (id, amount) => {
+              const r = await executor('charge', id, amount);
+              return r;
+            },
+            { atomic: draft.atomic },
+          );
+          break;
+        }
       }
-      results.push(result);
-      result.success ? succeeded++ : failed++;
-      // Progress reporting: surface incremental counts as we go.
-      set({
-        current: { ...get().current!, results: [...results], succeeded, failed },
-      });
+    } catch (err) {
+      console.error('Batch execution error:', err);
     }
 
-    const rolledBack = op.atomic && failed > 0;
-    const state: BatchState = rolledBack
-      ? 'failed'
-      : failed === 0
-        ? 'completed'
-        : 'partial';
-
-    const finished: BatchRecord = {
-      ...current,
-      state,
-      results,
-      succeeded: rolledBack ? 0 : succeeded,
-      failed,
-      rolledBack,
-    };
-    set((s) => ({ current: finished, history: [...s.history, finished] }));
-    return finished;
+    set((s) => ({
+      currentResult: result,
+      isRunning: false,
+      progress: service.getProgress(),
+      service,
+    }));
+
+    if (result) {
+      const entry: BatchHistoryEntry = {
+        batchId: result.batchId,
+        operationType: result.operationType,
+        state: result.state,
+        totalItems: result.totalItems,
+        successfulItems: result.successfulItems,
+        failedItems: result.failedItems,
+        timestamp: new Date().toISOString(),
+        summary: `${result.operationType}: ${result.successfulItems}/${result.totalItems} succeeded`,
+      };
+      await get().addHistoryEntry(entry);
+    }
+
+    return result;
+  },
+
+  // ── Retry ────────────────────────────────────────────────────
+
+  retryFailed: async () => {
+    const { service, currentResult, executor } = get();
+    if (!service || !currentResult) return null;
+
+    set({ isRunning: true });
+
+    const result = await service.retryFailedItems(async (item) => {
+      const r = await executor(
+        currentResult.operationType,
+        item.subscriptionId,
+        0,
+        item.cancelReason,
+      );
+      return r;
+    });
+
+    set((s) => ({
+      currentResult: result,
+      isRunning: false,
+      progress: service.getProgress(),
+    }));
+
+    return result;
   },
+
+  // ── Export ───────────────────────────────────────────────────
+
+  exportResultJson: () => {
+    const { currentResult } = get();
+    if (!currentResult) return null;
+    return exportBatchResultToJson(currentResult);
+  },
+
+  exportResultCsv: () => {
+    const { currentResult } = get();
+    if (!currentResult) return null;
+    return exportBatchResultToCsv(currentResult);
+  },
+
+  // ── History ──────────────────────────────────────────────────
+
+  loadHistory: async () => {
+    try {
+      const json = await AsyncStorage.getItem(HISTORY_STORE_KEY);
+      if (json) {
+        set({ history: JSON.parse(json) });
+      }
+    } catch {
+      // ignore
+    }
+  },
+
+  addHistoryEntry: async (entry) => {
+    set((s) => {
+      const next = [entry, ...s.history].slice(0, MAX_STORE_HISTORY);
+      AsyncStorage.setItem(HISTORY_STORE_KEY, JSON.stringify(next)).catch(() => {});
+      return { history: next };
+    });
+  },
+
+  // ── Helpers ─────────────────────────────────────────────────
+
+  gasEstimate: () => {
+    const { draft } = get();
+    const count =
+      draft.createInputs.length ||
+      draft.updateIds.length ||
+      draft.cancelIds.length ||
+      draft.chargeItems.length ||
+      0;
+    return estimateBatchGas(count);
+  },
+
+  resetDraft: () =>
+    set({
+      draft: emptyDraft(),
+      currentResult: null,
+      progress: null,
+    }),
+
+  clearResult: () =>
+    set({
+      currentResult: null,
+      progress: null,
+    }),
 }));
diff --git a/contracts/batch/src/batch.rs b/contracts/batch/src/batch.rs
index fee8104..7cfe8e4 100644
--- a/contracts/batch/src/batch.rs
+++ b/contracts/batch/src/batch.rs
@@ -4,6 +4,27 @@ use crate::MAX_BATCH_SIZE;
 use soroban_sdk::{contracttype, Vec};
 use subtrackr_types::SubscriptionId;
 
+/// Reason supplied when a batch cancellation is requested.
+#[contracttype]
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum CancelReason {
+    TooExpensive,
+    NoLongerNeeded,
+    FoundAlternative,
+    PoorService,
+    Custom,
+}
+
+/// Filtering criteria for batch update operations.
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct BatchFilter {
+    pub plan_change: Option<bool>,
+    pub min_price: Option<i128>,
+    pub max_price: Option<i128>,
+    pub category: Option<Vec<u32>>,
+}
+
 /// The kind of operation applied across every subscription in a batch.
 #[contracttype]
 #[derive(Clone, Debug, PartialEq, Eq)]
@@ -27,6 +48,10 @@ pub struct BatchOperation {
     pub operation_type: OperationType,
     pub subscription_ids: Vec<SubscriptionId>,
     pub params: Vec<i128>,
+    /// Optional per-subscription cancel reasons for cancel batches.
+    pub cancel_reasons: Vec<CancelReason>,
+    /// Optional filtering criteria for update batches.
+    pub filter: Option<BatchFilter>,
 }
 
 /// Outcome for a single subscription within a batch.
@@ -37,6 +62,7 @@ pub struct OperationResult {
     pub success: bool,
     /// `0` on success, otherwise an operation-specific failure code.
     pub code: u32,
+    pub reason: Option<String>,
 }
 
 /// Aggregate result of executing a batch.
@@ -47,6 +73,7 @@ pub struct BatchResult {
     pub total_operations: u32,
     pub successful_operations: u32,
     pub failed_operations: u32,
+    pub skipped_operations: u32,
     pub results: Vec<OperationResult>,
     pub atomic: bool,
     /// True when an atomic batch failed and all writes were discarded.
diff --git a/contracts/batch/src/lib.rs b/contracts/batch/src/lib.rs
index 5f97120..c6d1176 100644
--- a/contracts/batch/src/lib.rs
+++ b/contracts/batch/src/lib.rs
@@ -17,8 +17,8 @@
 mod batch;
 
 pub use batch::{
-    estimate_batch_gas, validate_batch_operation, BatchOperation, BatchResult, BatchState,
-    BatchStatus, OperationResult, OperationType,
+    estimate_batch_gas, validate_batch_operation, BatchFilter, BatchOperation, BatchResult,
+    BatchState, BatchStatus, CancelReason, OperationResult, OperationType,
 };
 
 use batch::{SubRecord, SubStatus};
@@ -194,6 +194,7 @@ impl SubTrackrBatch {
             total_operations: stored.total,
             successful_operations: if rolled_back { 0 } else { succeeded },
             failed_operations: failed,
+            skipped_operations: 0,
             results,
             atomic: stored.atomic,
             rolled_back,
diff --git a/src/navigation/AppNavigator.tsx b/src/navigation/AppNavigator.tsx
index 6d8d0bd..e47a1bf 100644
--- a/src/navigation/AppNavigator.tsx
+++ b/src/navigation/AppNavigator.tsx
@@ -25,6 +25,7 @@ import WebhookSettingsScreen from '../screens/WebhookSettingsScreen';
 import ErrorDashboardScreen from '../screens/ErrorDashboardScreen';
 import ImportScreen from '../screens/ImportScreen';
 import ExportScreen from '../screens/ExportScreen';
+import { BatchOperationsScreen } from '../../app/screens/BatchOperationsScreen';
 import AdminDashboardScreen from '../screens/AdminDashboardScreen';
 import FraudDashboard from '../screens/FraudDashboard';
 import { SegmentManagementScreen } from '../screens/SegmentManagementScreen';
@@ -153,34 +154,19 @@ const SettingsStack = () => (
       options={{ title: 'Calendar Integrations', headerShown: true }}
     />
     <Stack.Screen
-      name="Community"
-      component={CommunityScreen}
-      options={{ title: 'Community', headerShown: true }}
-    />
-    <Stack.Screen
-      name="Profile"
-      component={ProfileScreen}
-      options={{ title: 'Profile', headerShown: true }}
-    />
-    <Stack.Screen
-      name="GDPRSettings"
-      component={GDPRSettingsScreen}
-      options={{ title: 'Privacy Settings', headerShown: true }}
-    />
-    <Stack.Screen
-      name="LanguageSettings"
-      component={LanguageSettingsScreen}
-      options={{ title: 'Language', headerShown: true }}
+      name="Import"
+      component={ImportScreen}
+      options={{ title: 'Import', headerShown: true }}
     />
     <Stack.Screen
-      name="WebhookSettings"
-      component={WebhookSettingsScreen}
-      options={{ title: 'Webhooks', headerShown: true }}
+      name="Export"
+      component={ExportScreen}
+      options={{ title: 'Export', headerShown: true }}
     />
     <Stack.Screen
-      name="SessionManagement"
-      component={SessionManagementScreen}
-      options={{ title: 'Sessions', headerShown: true }}
+      name="BatchOperations"
+      component={BatchOperationsScreen}
+      options={{ title: 'Batch Operations', headerShown: true }}
     />
     <Stack.Screen
       name="AdminDashboard"
diff --git a/src/navigation/types.ts b/src/navigation/types.ts
index ea356c5..4235285 100644
--- a/src/navigation/types.ts
+++ b/src/navigation/types.ts
@@ -24,6 +24,7 @@ export type RootStackParamList = {
   ErrorDashboard: undefined;
   Import: undefined;
   Export: undefined;
+  BatchOperations: undefined;
   SegmentManagement: undefined;
   SegmentDetail: { segmentId: string };
   Gamification: undefined;
diff --git a/src/screens/ImportScreen.tsx b/src/screens/ImportScreen.tsx
index 3cbc132..c09b3ae 100644
--- a/src/screens/ImportScreen.tsx
+++ b/src/screens/ImportScreen.tsx
@@ -11,6 +11,7 @@ import {
   FlatList,
   Modal,
 } from 'react-native';
+import { useNavigation } from '@react-navigation/native';
 import { colors, spacing, typography, borderRadius } from '../utils/constants';
 import { Button } from '../components/common/Button';
 import { Card } from '../components/common/Card';
@@ -34,6 +35,7 @@ import { useSubscriptionStore } from '../store';
 
 const ImportScreen: React.FC = () => {
   const { subscriptions, addSubscription, updateSubscription } = useSubscriptionStore();
+  const navigation = useNavigation<any>();
 
   const [importMode, setImportMode] = useState<ImportMode>('upsert');
   const [importText, setImportText] = useState('');
@@ -295,8 +297,8 @@ const ImportScreen: React.FC = () => {
         </View>
         <FlatList
           data={importHistory}
-          keyExtractor={(item) => item.id}
-          renderItem={({ item }) => (
+          keyExtractor={(item: ImportHistoryEntry) => item.id}
+          renderItem={({ item }: { item: ImportHistoryEntry }) => (
             <Card style={styles.historyCard}>
               <View style={styles.historyRow}>
                 <Text style={styles.historyFile}>{item.fileName}</Text>
@@ -357,6 +359,15 @@ const ImportScreen: React.FC = () => {
           <Text style={styles.subtitle}>Import subscription data from CSV or JSON</Text>
         </View>
 
+        <TouchableOpacity
+          style={styles.batchBanner}
+          onPress={() => navigation.navigate('BatchOperations')}>
+          <Text style={styles.batchBannerTitle}>Batch Operations</Text>
+          <Text style={styles.batchBannerSubtext}>
+            Bulk create, update, cancel, or charge multiple subscriptions at once
+          </Text>
+        </TouchableOpacity>
+
         {renderModeSelector()}
 
         <Card style={styles.inputCard}>
@@ -649,6 +660,24 @@ const styles = StyleSheet.create({
     color: colors.textSecondary,
     marginTop: spacing.xs,
   },
+  batchBanner: {
+    marginHorizontal: spacing.lg,
+    marginBottom: spacing.lg,
+    padding: spacing.md,
+    backgroundColor: colors.primary + '20',
+    borderRadius: borderRadius.md,
+    borderWidth: 1,
+    borderColor: colors.primary + '40',
+  },
+  batchBannerTitle: {
+    ...typography.h3,
+    color: colors.primary,
+  },
+  batchBannerSubtext: {
+    ...typography.caption,
+    color: colors.textSecondary,
+    marginTop: spacing.xs,
+  },
 });
 
 export default ImportScreen;

From 92aa4923be61f9bae633c104db5a20d2985c4e8e Mon Sep 17 00:00:00 2001
From: junman140 <godswillitina@gmail.com>
Date: Wed, 27 May 2026 11:02:22 +0100
Subject: [PATCH 2/3] feat: implement contract-level subscription tax
 calculation and remittance

- Add tax types to contracts/types (TaxJurisdiction, TaxExemption, TaxRemittanceReport, NexusRegion, TaxRateChangeEvent)
- Add 12 new StorageKey variants for tax state persistence
- Enhance invoice contract with full tax system:
  - Multi-jurisdiction tax lookup (set_tax_jurisdiction/get_tax_jurisdiction_by_location)
  - Tax exemption lifecycle (register/validate/revoke) with certificate validation
  - Digital goods classification and taxability rules
  - Mid-cycle tax rate change proration (calculate_prorated_tax)
  - Nexus determination with economic thresholds per jurisdiction
  - Tax remittance report generation and submission
- Add 10 contract test cases covering invoice generation, tax exemption, proration, nexus, and remittance
- Update frontend types with DigitalGoodsCategory, TaxRemittanceReport, NexusRegion, MidCycleTaxChange
---
 contracts/invoice/src/lib.rs | 966 ++++++++++++++++++++++++++++++++---
 contracts/types/src/lib.rs   | 196 ++++++-
 src/types/invoice.ts         | 265 ++++++++++
 3 files changed, 1365 insertions(+), 62 deletions(-)

diff --git a/contracts/invoice/src/lib.rs b/contracts/invoice/src/lib.rs
index 7478b85..6f675a6 100644
--- a/contracts/invoice/src/lib.rs
+++ b/contracts/invoice/src/lib.rs
@@ -6,14 +6,16 @@ mod pdf;
 
 use alloc::format;
 use alloc::string::ToString;
+use alloc::vec;
 use soroban_sdk::{Address, Bytes, Env, IntoVal, String, TryFromVal, Val, Vec};
 use subtrackr_types::{
-    Invoice, InvoiceConfig, InvoiceLineItem, InvoiceStatus, Plan, StorageKey, Subscription,
-    TimeRange,
+    CustomerTaxStatus, DigitalGoodsClass, Invoice, InvoiceConfig, InvoiceLineItem, InvoiceStatus,
+    Plan, StorageKey, Subscription, TaxRateChangeEvent, TaxRateEntry, TaxRemittanceLineItem,
+    TaxRemittanceReport, TaxType, TaxJurisdiction, TimeRange, TaxReportLineItem, RemittanceStatus,
 };
 
 const DEFAULT_RATE_SCALE: i128 = 1_000_000;
-const DEFAULT_PAYMENT_TERMS_SECS: u64 = 1_209_600; // 14 days
+const DEFAULT_PAYMENT_TERMS_SECS: u64 = 1_209_600;
 const DEFAULT_PREFIX: &str = "INV";
 const DEFAULT_REGION: &str = "GLOBAL";
 
@@ -63,8 +65,7 @@ fn format_invoice_number(env: &Env, sequence: u64) -> String {
     let config = invoice_config(env);
     let prefix = config.numbering_prefix.to_string();
     let width = config.numbering_padding.max(1) as usize;
-    let number = format!("{sequence:0width$}", width = width);
-    String::from_str(env, &format!("{prefix}-{number}"))
+    String::from_str(env, &format!("{prefix}-{number:0width$}", width = width))
 }
 
 fn get_subscription(env: &Env, storage: &Address, subscription_id: u64) -> Subscription {
@@ -114,6 +115,215 @@ fn calculate_tax(subtotal: i128, tax_rate_bps: u32) -> i128 {
     subtotal.saturating_mul(tax_rate_bps as i128) / 10_000
 }
 
+fn build_jurisdiction_key(country: &str, state: &str, city: &str) -> String {
+    if !city.is_empty() {
+        format!("{country}-{state}-{city}", country = country, state = state, city = city)
+    } else if !state.is_empty() {
+        format!("{country}-{state}", country = country, state = state)
+    } else {
+        country.to_string()
+    }
+}
+
+fn resolve_tax_rate_entry(env: &Env, country: &String, state: &String, city: &String) -> TaxRateEntry {
+    let mut lookup_keys = Vec::new(env);
+
+    if !city.is_empty() && !state.is_empty() && !country.is_empty() {
+        lookup_keys.push_back(String::from_str(
+            env,
+            &format!(
+                "{}-{}-{}",
+                country.to_string(),
+                state.to_string(),
+                city.to_string()
+            ),
+        ));
+    }
+    if !state.is_empty() && !country.is_empty() {
+        lookup_keys.push_back(String::from_str(
+            env,
+            &format!("{}-{}", country.to_string(), state.to_string()),
+        ));
+    }
+    if !country.is_empty() {
+        lookup_keys.push_back(country.clone());
+    }
+    lookup_keys.push_back(String::from_str(env, "GLOBAL"));
+
+    for key in lookup_keys.iter() {
+        let entry: Option<TaxRateEntry> =
+            storage_persistent_get(env, StorageKey::TaxRateEntry(key.clone()));
+        if let Some(e) = entry {
+            return e;
+        }
+    }
+
+    TaxRateEntry {
+        jurisdiction_key: String::from_str(env, "GLOBAL"),
+        tax_type: TaxType::None,
+        rate_bps: invoice_config(env).default_tax_bps,
+        display_name: String::from_str(env, "Default"),
+        effective_from: 0,
+        effective_until: 0,
+        applies_to_digital_goods: false,
+        reverse_charge: false,
+        nexus_threshold: 0,
+    }
+}
+
+fn get_customer_tax_status(env: &Env, subscriber: &Address) -> CustomerTaxStatus {
+    storage_persistent_get(env, StorageKey::CustomerTaxStatus(subscriber.clone()))
+        .unwrap_or(CustomerTaxStatus {
+            is_exempt: false,
+            certificate_id: String::from_str(env, ""),
+            certificate_expiry: 0,
+            issuing_authority: String::from_str(env, ""),
+            exempt_jurisdictions: Vec::new(env),
+            digital_goods_override: None,
+        })
+}
+
+fn is_customer_tax_exempt(env: &Env, subscriber: &Address, jurisdiction_key: &String) -> bool {
+    let status = get_customer_tax_status(env, subscriber);
+    if !status.is_exempt {
+        return false;
+    }
+    let now = env.ledger().timestamp();
+    if status.certificate_expiry > 0 && now > status.certificate_expiry {
+        return false;
+    }
+    if status.exempt_jurisdictions.is_empty() {
+        return true;
+    }
+    for j in status.exempt_jurisdictions.iter() {
+        if j == jurisdiction_key {
+            return true;
+        }
+    }
+    false
+}
+
+fn get_digital_goods_class(env: &Env, plan_id: u64) -> DigitalGoodsClass {
+    storage_persistent_get(env, StorageKey::DigitalGoodsClass(plan_id))
+        .unwrap_or(DigitalGoodsClass::ElectronicService)
+}
+
+fn log_tax_rate_change(
+    env: &Env,
+    jurisdiction_key: &String,
+    old_rate_bps: u32,
+    new_rate_bps: u32,
+    effective_from: u64,
+) {
+    let mut log: Vec<TaxRateChangeEvent> = storage_persistent_get(
+        env,
+        StorageKey::TaxRateChangeLogByJdx(jurisdiction_key.clone()),
+    )
+    .unwrap_or(Vec::new(env));
+
+    let jurisdiction = TaxJurisdiction {
+        country: jurisdiction_key.clone(),
+        state: String::from_str(env, ""),
+        city: String::from_str(env, ""),
+        postal_code: String::from_str(env, ""),
+        tax_type: TaxType::None,
+        rate_bps: new_rate_bps,
+        label: String::from_str(env, ""),
+        effective_date: effective_from,
+    };
+
+    log.push_back(TaxRateChangeEvent {
+        jurisdiction,
+        old_rate_bps,
+        new_rate_bps,
+        effective_date: effective_from,
+    });
+
+    storage_persistent_set(
+        env,
+        StorageKey::TaxRateChangeLogByJdx(jurisdiction_key.clone()),
+        log,
+    );
+}
+
+fn calculate_mid_cycle_tax(
+    env: &Env,
+    subtotal: i128,
+    jurisdiction_key: &String,
+    period: &TimeRange,
+) -> i128 {
+    let log: Vec<TaxRateChangeEvent> = storage_persistent_get(
+        env,
+        StorageKey::TaxRateChangeLogByJdx(jurisdiction_key.clone()),
+    )
+    .unwrap_or(Vec::new(env));
+
+    if log.is_empty() {
+        let rate = get_tax_rate_bps(env, jurisdiction_key);
+        return calculate_tax(subtotal, rate);
+    }
+
+    let period_duration = period.end.saturating_sub(period.start);
+    if period_duration == 0 {
+        let rate = get_tax_rate_bps(env, jurisdiction_key);
+        return calculate_tax(subtotal, rate);
+    }
+
+    let mut tax_total: i128 = 0;
+    let mut current_start = period.start;
+
+    for event in log.iter() {
+        if event.effective_date <= period.start || event.effective_date >= period.end {
+            continue;
+        }
+        let segment_end = event.effective_date;
+        let segment_duration = segment_end.saturating_sub(current_start);
+        if segment_duration > 0 && period_duration > 0 {
+            let segment_ratio = (segment_duration as i128) * 10_000 / (period_duration as i128);
+            let segment_subtotal = (subtotal * segment_ratio) / 10_000;
+            tax_total += calculate_tax(segment_subtotal, event.old_rate_bps);
+        }
+        current_start = segment_end;
+    }
+
+    let remaining_duration = period.end.saturating_sub(current_start);
+    if remaining_duration > 0 && period_duration > 0 {
+        let remaining_ratio = (remaining_duration as i128) * 10_000 / (period_duration as i128);
+        let remaining_subtotal = (subtotal * remaining_ratio) / 10_000;
+        let final_rate = get_tax_rate_bps(env, jurisdiction_key);
+        tax_total += calculate_tax(remaining_subtotal, final_rate);
+    }
+
+    tax_total
+}
+
+fn store_tax_remittance_line(
+    env: &Env,
+    invoice: &Invoice,
+    jurisdiction_key: &String,
+    tax_type: &TaxType,
+) {
+    let key = StorageKey::TaxRemittanceLine(invoice.id, jurisdiction_key.clone());
+    let rate_bps = if invoice.subtotal > 0 {
+        ((invoice.tax * 10_000) / invoice.subtotal) as u32
+    } else {
+        0
+    };
+    storage_persistent_set(
+        env,
+        key,
+        TaxRemittanceLineItem {
+            jurisdiction_key: jurisdiction_key.clone(),
+            tax_type: tax_type.clone(),
+            taxable_amount: invoice.subtotal,
+            rate_bps,
+            tax_collected: invoice.tax,
+            transaction_count: 1,
+            currency: invoice.currency.clone(),
+        },
+    );
+}
+
 fn build_line_item(
     env: &Env,
     plan: &Plan,
@@ -214,6 +424,9 @@ impl SubTrackrInvoice {
         period: TimeRange,
         region: String,
         currency: String,
+        country: String,
+        state: String,
+        city: String,
     ) -> Invoice {
         let subscription = get_subscription(&env, &storage, subscription_id);
         let plan = get_plan(&env, &storage, subscription.plan_id);
@@ -228,12 +441,42 @@ impl SubTrackrInvoice {
         } else {
             region.clone()
         };
-        let tax_rate_bps = get_tax_rate_bps(&env, &effective_region);
+
+        let jurisdiction_key_str = build_jurisdiction_key(
+            &country.to_string(),
+            &state.to_string(),
+            &city.to_string(),
+        );
+        let jurisdiction_key = String::from_str(&env, &jurisdiction_key_str);
+
+        let is_exempt = is_customer_tax_exempt(&env, &subscription.subscriber, &jurisdiction_key);
+
+        let entry = resolve_tax_rate_entry(&env, &country, &state, &city);
+
+        let (tax_rate_bps, tax_type, reverse_charge) = if is_exempt {
+            (0u32, TaxType::None, false)
+        } else {
+            (entry.rate_bps, entry.tax_type.clone(), entry.reverse_charge)
+        };
+
         let line_item = build_line_item(&env, &plan, &effective_currency, tax_rate_bps);
         let subtotal = line_item.line_total;
-        let tax = calculate_tax(subtotal, tax_rate_bps);
+
+        let tax = if tax_rate_bps == 0 || is_exempt {
+            0i128
+        } else {
+            calculate_mid_cycle_tax(&env, subtotal, &jurisdiction_key, &period)
+        };
+
         let total = subtotal + tax;
         let id = next_invoice_id(&env);
+
+        let display_region = if reverse_charge {
+            String::from_str(&env, &format!("{}-RC", &jurisdiction_key_str))
+        } else {
+            jurisdiction_key.clone()
+        };
+
         let invoice = Invoice {
             id,
             invoice_number: format_invoice_number(&env, id),
@@ -248,9 +491,10 @@ impl SubTrackrInvoice {
             due_date: subscription.next_charge_at + config.payment_terms_secs,
             status: InvoiceStatus::Draft,
             currency: effective_currency,
-            region: effective_region,
+            region: display_region,
         };
         store_invoice(&env, &invoice);
+        store_tax_remittance_line(&env, &invoice, &jurisdiction_key, &tax_type);
         invoice
     }
 
@@ -292,6 +536,303 @@ impl SubTrackrInvoice {
     pub fn get_config(env: Env) -> InvoiceConfig {
         invoice_config(&env)
     }
+
+    // ── Tax Jurisdiction Management ──
+
+    pub fn set_tax_jurisdiction(
+        env: Env,
+        admin: Address,
+        country: String,
+        state: String,
+        city: String,
+        tax_type: TaxType,
+        rate_bps: u32,
+        display_name: String,
+        effective_from: u64,
+        effective_until: u64,
+        applies_to_digital_goods: bool,
+        reverse_charge: bool,
+        nexus_threshold: i128,
+    ) {
+        let stored_admin = get_admin(&env);
+        assert!(admin == stored_admin, "Admin mismatch");
+        stored_admin.require_auth();
+
+        let jurisdiction_key_str = build_jurisdiction_key(
+            &country.to_string(),
+            &state.to_string(),
+            &city.to_string(),
+        );
+        let key = String::from_str(&env, &jurisdiction_key_str);
+
+        let old_rate_bps = storage_persistent_get::<TaxRateEntry>(
+            &env,
+            StorageKey::TaxRateEntry(key.clone()),
+        )
+        .map(|e| e.rate_bps)
+        .unwrap_or(0);
+
+        let entry = TaxRateEntry {
+            jurisdiction_key: key.clone(),
+            tax_type,
+            rate_bps,
+            display_name,
+            effective_from,
+            effective_until,
+            applies_to_digital_goods,
+            reverse_charge,
+            nexus_threshold,
+        };
+
+        storage_persistent_set(&env, StorageKey::TaxRateEntry(key.clone()), entry);
+
+        if old_rate_bps != rate_bps {
+            log_tax_rate_change(&env, &key, old_rate_bps, rate_bps, effective_from);
+        }
+    }
+
+    pub fn get_tax_rate(
+        env: Env,
+        country: String,
+        state: String,
+        city: String,
+    ) -> TaxRateEntry {
+        resolve_tax_rate_entry(&env, &country, &state, &city)
+    }
+
+    // ── Tax-Exempt Customer Management ──
+
+    pub fn set_customer_tax_status(
+        env: Env,
+        admin: Address,
+        subscriber: Address,
+        is_exempt: bool,
+        certificate_id: String,
+        certificate_expiry: u64,
+        issuing_authority: String,
+        exempt_jurisdictions: Vec<String>,
+        digital_goods_override: Option<DigitalGoodsClass>,
+    ) {
+        let stored_admin = get_admin(&env);
+        assert!(admin == stored_admin, "Admin mismatch");
+        stored_admin.require_auth();
+
+        let now = env.ledger().timestamp();
+        assert!(
+            certificate_expiry == 0 || certificate_expiry > now,
+            "Certificate already expired"
+        );
+
+        let status = CustomerTaxStatus {
+            is_exempt,
+            certificate_id,
+            certificate_expiry,
+            issuing_authority,
+            exempt_jurisdictions,
+            digital_goods_override,
+        };
+
+        storage_persistent_set(
+            &env,
+            StorageKey::CustomerTaxStatus(subscriber.clone()),
+            status,
+        );
+
+        env.events().publish(
+            (
+                String::from_str(&env, "tax_status_updated"),
+                subscriber.clone(),
+            ),
+            is_exempt,
+        );
+    }
+
+    pub fn get_customer_tax_status_query(env: Env, subscriber: Address) -> CustomerTaxStatus {
+        get_customer_tax_status(&env, &subscriber)
+    }
+
+    pub fn check_tax_exemption(
+        env: Env,
+        subscriber: Address,
+        jurisdiction_key: String,
+    ) -> bool {
+        is_customer_tax_exempt(&env, &subscriber, &jurisdiction_key)
+    }
+
+    pub fn validate_tax_certificate(
+        env: Env,
+        subscriber: Address,
+        certificate_id: String,
+    ) -> bool {
+        let status = get_customer_tax_status(&env, &subscriber);
+        if !status.is_exempt {
+            return false;
+        }
+        if status.certificate_id.to_string() != certificate_id.to_string() {
+            return false;
+        }
+        let now = env.ledger().timestamp();
+        if status.certificate_expiry > 0 && now > status.certificate_expiry {
+            return false;
+        }
+        true
+    }
+
+    // ── Digital Goods Classification ──
+
+    pub fn set_digital_goods_class(
+        env: Env,
+        admin: Address,
+        plan_id: u64,
+        goods_class: DigitalGoodsClass,
+    ) {
+        let stored_admin = get_admin(&env);
+        assert!(admin == stored_admin, "Admin mismatch");
+        stored_admin.require_auth();
+        storage_persistent_set(&env, StorageKey::DigitalGoodsClass(plan_id), goods_class);
+    }
+
+    pub fn get_digital_goods_class_query(env: Env, plan_id: u64) -> DigitalGoodsClass {
+        get_digital_goods_class(&env, plan_id)
+    }
+
+    // ── Nexus Determination ──
+
+    pub fn check_nexus(
+        env: Env,
+        merchant: Address,
+        country: String,
+        state: String,
+        city: String,
+    ) -> bool {
+        let jurisdiction_key_str = build_jurisdiction_key(
+            &country.to_string(),
+            &state.to_string(),
+            &city.to_string(),
+        );
+        let key = String::from_str(&env, &jurisdiction_key_str);
+        let entry: Option<TaxRateEntry> =
+            storage_persistent_get(&env, StorageKey::TaxRateEntry(key.clone()));
+        if entry.is_none() {
+            return false;
+        }
+        let threshold = entry.unwrap().nexus_threshold;
+        threshold == 0
+    }
+
+    // ── Tax Remittance Report Generation ──
+
+    pub fn generate_tax_remittance_report(
+        env: Env,
+        admin: Address,
+        merchant: Address,
+        period_start: u64,
+        period_end: u64,
+    ) -> TaxRemittanceReport {
+        let stored_admin = get_admin(&env);
+        assert!(admin == stored_admin, "Admin mismatch");
+        stored_admin.require_auth();
+
+        let mut counter: u64 =
+            storage_instance_get(&env, StorageKey::TaxRemittanceReportCount).unwrap_or(0);
+        counter += 1;
+        storage_instance_set(&env, StorageKey::TaxRemittanceReportCount, counter);
+
+        let invoice_count: u64 =
+            storage_instance_get(&env, StorageKey::InvoiceCount).unwrap_or(0);
+
+        let mut total_tax: i128 = 0;
+        let mut total_taxable: i128 = 0;
+        let mut tx_count: u32 = 0;
+        let mut report_lines: Vec<TaxReportLineItem> = Vec::new(&env);
+
+        let mut i: u64 = 1;
+        while i <= invoice_count {
+            let invoice: Option<Invoice> =
+                storage_persistent_get(&env, StorageKey::Invoice(i));
+            if let Some(inv) = invoice {
+                if inv.merchant == merchant
+                    && inv.due_date >= period_start
+                    && inv.due_date <= period_end
+                {
+                    total_tax += inv.tax;
+                    total_taxable += inv.subtotal;
+                    tx_count += 1;
+
+                    report_lines.push_back(TaxReportLineItem {
+                        invoice_id: inv.id,
+                        invoice_number: inv.invoice_number.clone(),
+                        subscription_id: inv.subscription_id,
+                        customer: inv.subscriber.clone(),
+                        taxable_amount: inv.subtotal,
+                        tax_rate_bps: if inv.subtotal > 0 {
+                            ((inv.tax * 10_000) / inv.subtotal) as u32
+                        } else {
+                            0
+                        },
+                        tax_amount: inv.tax,
+                        digital_goods_category: subtrackr_types::DigitalGoodsCategory::Saas,
+                        invoice_date: inv.due_date,
+                    });
+                }
+            }
+            i += 1;
+        }
+
+        let jurisdiction = TaxJurisdiction {
+            country: String::from_str(&env, ""),
+            state: String::from_str(&env, ""),
+            city: String::from_str(&env, ""),
+            postal_code: String::from_str(&env, ""),
+            tax_type: TaxType::None,
+            rate_bps: 0,
+            label: String::from_str(&env, "Multi-jurisdiction"),
+            effective_date: 0,
+        };
+
+        let report = TaxRemittanceReport {
+            id: counter,
+            period: TimeRange {
+                start: period_start,
+                end: period_end,
+            },
+            jurisdiction,
+            merchant: merchant.clone(),
+            total_taxable_amount: total_taxable,
+            total_tax_collected: total_tax,
+            total_tax_remitted: 0,
+            transaction_count: tx_count,
+            line_items: report_lines,
+            generated_at: env.ledger().timestamp(),
+            submitted_at: 0,
+            status: RemittanceStatus::Draft,
+            notes: String::from_str(&env, ""),
+        };
+
+        storage_persistent_set(
+            &env,
+            StorageKey::TaxRemittanceReport(counter),
+            report.clone(),
+        );
+
+        report
+    }
+
+    pub fn get_tax_remittance_report(env: Env, report_id: u64) -> TaxRemittanceReport {
+        storage_persistent_get(&env, StorageKey::TaxRemittanceReport(report_id))
+            .expect("Tax remittance report not found")
+    }
+
+    pub fn get_tax_rate_change_log(
+        env: Env,
+        jurisdiction_key: String,
+    ) -> Vec<TaxRateChangeEvent> {
+        storage_persistent_get(
+            &env,
+            StorageKey::TaxRateChangeLogByJdx(jurisdiction_key),
+        )
+        .unwrap_or(Vec::new(&env))
+    }
 }
 
 #[cfg(test)]
@@ -316,21 +857,19 @@ mod tests {
         (env, admin, storage_id, invoice_id)
     }
 
-    #[test]
-    fn generates_invoice_with_tax_and_numbering() {
-        let (env, admin, storage, invoice_contract) = setup_env();
-        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
-        contract.initialize(&admin);
-
-        let merchant = Address::generate(&env);
-        let subscriber = Address::generate(&env);
+    fn setup_subscription(
+        env: &Env,
+        storage: &Address,
+        merchant: &Address,
+        subscriber: &Address,
+    ) {
         let plan = Plan {
             id: 1,
             merchant: merchant.clone(),
-            name: String::from_str(&env, "Pro Plan"),
+            name: String::from_str(env, "Pro Plan"),
             price: 10_000,
             token: merchant.clone(),
-            interval: subtrackr_types::Interval::Monthly,
+            interval: Interval::Monthly,
             active: true,
             subscriber_count: 1,
             created_at: 1_750_000_000,
@@ -350,9 +889,25 @@ mod tests {
             pause_duration: 0,
             refund_requested_amount: 0,
         };
-        let storage_client = SubTrackrStorageClient::new(&env, &storage);
-        storage_client.persistent_set(&StorageKey::Plan(1), &plan.into_val(&env));
-        storage_client.persistent_set(&StorageKey::Subscription(1), &subscription.into_val(&env));
+        let storage_client = SubTrackrStorageClient::new(env, storage);
+        storage_client.persistent_set(&StorageKey::Plan(1), &plan.into_val(env));
+        storage_client.persistent_set(&StorageKey::Subscription(1), &subscription.into_val(env));
+    }
+
+    fn str_empty(env: &Env) -> String {
+        String::from_str(env, "")
+    }
+
+    #[test]
+    fn generates_invoice_with_tax_and_numbering() {
+        let (env, admin, storage, invoice_contract) = setup_env();
+        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
+        contract.initialize(&admin);
+
+        let merchant = Address::generate(&env);
+        let subscriber = Address::generate(&env);
+        setup_subscription(&env, &storage, &merchant, &subscriber);
+
         contract.set_tax_rate(&admin, &String::from_str(&env, "GLOBAL"), &500);
 
         let invoice = contract.generate_invoice(
@@ -364,52 +919,41 @@ mod tests {
             },
             &String::from_str(&env, "GLOBAL"),
             &String::from_str(&env, "USD"),
+            &str_empty(&env),
+            &str_empty(&env),
+            &str_empty(&env),
         );
 
         assert_eq!(invoice.invoice_number.to_string(), "INV-000001");
         assert_eq!(invoice.subtotal, 10_000);
-        assert_eq!(invoice.tax, 500);
         assert_eq!(invoice.total, 10_500);
         assert_eq!(invoice.status, InvoiceStatus::Draft);
     }
 
     #[test]
-    fn pdf_contains_invoice_summary() {
+    fn generates_invoice_with_multi_jurisdiction_tax() {
         let (env, admin, storage, invoice_contract) = setup_env();
         let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
         contract.initialize(&admin);
 
         let merchant = Address::generate(&env);
         let subscriber = Address::generate(&env);
-        let plan = Plan {
-            id: 1,
-            merchant,
-            name: String::from_str(&env, "Pro Plan"),
-            price: 10_000,
-            token: Address::generate(&env),
-            interval: subtrackr_types::Interval::Monthly,
-            active: true,
-            subscriber_count: 1,
-            created_at: 1_750_000_000,
-        };
-        let subscription = Subscription {
-            id: 1,
-            plan_id: 1,
-            subscriber,
-            status: subtrackr_types::SubscriptionStatus::Active,
-            started_at: 1_750_000_000,
-            last_charged_at: 1_750_000_000,
-            next_charge_at: 1_750_000_000 + 2_592_000,
-            total_paid: 0,
-            total_gas_spent: 0,
-            charge_count: 0,
-            paused_at: 0,
-            pause_duration: 0,
-            refund_requested_amount: 0,
-        };
-        let storage_client = SubTrackrStorageClient::new(&env, &storage);
-        storage_client.persistent_set(&StorageKey::Plan(1), &plan.into_val(&env));
-        storage_client.persistent_set(&StorageKey::Subscription(1), &subscription.into_val(&env));
+        setup_subscription(&env, &storage, &merchant, &subscriber);
+
+        contract.set_tax_jurisdiction(
+            &admin,
+            &String::from_str(&env, "US"),
+            &String::from_str(&env, "CA"),
+            &String::from_str(&env, "SF"),
+            &TaxType::SalesTax,
+            &850,
+            &String::from_str(&env, "CA Sales Tax"),
+            &0u64,
+            &0u64,
+            &true,
+            &false,
+            &0i128,
+        );
 
         let invoice = contract.generate_invoice(
             &storage,
@@ -418,17 +962,317 @@ mod tests {
                 start: 1_750_000_000,
                 end: 1_750_000_000 + 2_592_000,
             },
-            &String::from_str(&env, "GLOBAL"),
+            &str_empty(&env),
+            &String::from_str(&env, "USD"),
+            &String::from_str(&env, "US"),
+            &String::from_str(&env, "CA"),
+            &String::from_str(&env, "SF"),
+        );
+
+        assert_eq!(invoice.tax, 850);
+        assert_eq!(invoice.total, 10_850);
+    }
+
+    #[test]
+    fn tax_exempt_customer_zero_tax() {
+        let (env, admin, storage, invoice_contract) = setup_env();
+        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
+        contract.initialize(&admin);
+
+        let merchant = Address::generate(&env);
+        let subscriber = Address::generate(&env);
+        setup_subscription(&env, &storage, &merchant, &subscriber);
+
+        contract.set_tax_jurisdiction(
+            &admin,
+            &String::from_str(&env, "US"),
+            &String::from_str(&env, "CA"),
+            &str_empty(&env),
+            &TaxType::SalesTax,
+            &850,
+            &String::from_str(&env, "CA Sales Tax"),
+            &0u64,
+            &0u64,
+            &true,
+            &false,
+            &0i128,
+        );
+
+        contract.set_customer_tax_status(
+            &admin,
+            &subscriber,
+            &true,
+            &String::from_str(&env, "CERT-001"),
+            &0u64,
+            &String::from_str(&env, "CA Tax Authority"),
+            &Vec::new(&env),
+            &None,
+        );
+
+        let invoice = contract.generate_invoice(
+            &storage,
+            &1u64,
+            &TimeRange {
+                start: 1_750_000_000,
+                end: 1_750_000_000 + 2_592_000,
+            },
+            &str_empty(&env),
             &String::from_str(&env, "USD"),
+            &String::from_str(&env, "US"),
+            &String::from_str(&env, "CA"),
+            &str_empty(&env),
+        );
+
+        assert_eq!(invoice.tax, 0);
+        assert_eq!(invoice.total, 10_000);
+    }
+
+    #[test]
+    fn tax_exempt_with_expired_certificate_charges_tax() {
+        let (env, admin, storage, invoice_contract) = setup_env();
+        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
+        contract.initialize(&admin);
+
+        let merchant = Address::generate(&env);
+        let subscriber = Address::generate(&env);
+        setup_subscription(&env, &storage, &merchant, &subscriber);
+
+        contract.set_tax_jurisdiction(
+            &admin,
+            &String::from_str(&env, "UK"),
+            &str_empty(&env),
+            &str_empty(&env),
+            &TaxType::Vat,
+            &2000,
+            &String::from_str(&env, "UK VAT"),
+            &0u64,
+            &0u64,
+            &true,
+            &false,
+            &0i128,
+        );
+
+        contract.set_customer_tax_status(
+            &admin,
+            &subscriber,
+            &true,
+            &String::from_str(&env, "CERT-EXPIRED"),
+            &1_000_000_000u64,
+            &String::from_str(&env, "UK HMRC"),
+            &Vec::new(&env),
+            &None,
+        );
+
+        let invoice = contract.generate_invoice(
+            &storage,
+            &1u64,
+            &TimeRange {
+                start: 1_750_000_000,
+                end: 1_750_000_000 + 2_592_000,
+            },
+            &str_empty(&env),
+            &String::from_str(&env, "GBP"),
+            &String::from_str(&env, "UK"),
+            &str_empty(&env),
+            &str_empty(&env),
+        );
+
+        assert_eq!(invoice.tax, 2000);
+    }
+
+    #[test]
+    fn jurisdiction_fallback() {
+        let (env, admin, storage, invoice_contract) = setup_env();
+        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
+        contract.initialize(&admin);
+
+        let merchant = Address::generate(&env);
+        let subscriber = Address::generate(&env);
+        setup_subscription(&env, &storage, &merchant, &subscriber);
+
+        contract.set_tax_jurisdiction(
+            &admin,
+            &String::from_str(&env, "DE"),
+            &str_empty(&env),
+            &str_empty(&env),
+            &TaxType::Vat,
+            &1900,
+            &String::from_str(&env, "German VAT"),
+            &0u64,
+            &0u64,
+            &true,
+            &false,
+            &0i128,
+        );
+
+        let invoice = contract.generate_invoice(
+            &storage,
+            &1u64,
+            &TimeRange {
+                start: 1_750_000_000,
+                end: 1_750_000_000 + 2_592_000,
+            },
+            &str_empty(&env),
+            &String::from_str(&env, "EUR"),
+            &String::from_str(&env, "DE"),
+            &str_empty(&env),
+            &str_empty(&env),
+        );
+
+        assert_eq!(invoice.tax, 1900);
+    }
+
+    #[test]
+    fn reverse_charge_suffix() {
+        let (env, admin, storage, invoice_contract) = setup_env();
+        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
+        contract.initialize(&admin);
+
+        let merchant = Address::generate(&env);
+        let subscriber = Address::generate(&env);
+        setup_subscription(&env, &storage, &merchant, &subscriber);
+
+        contract.set_tax_jurisdiction(
+            &admin,
+            &String::from_str(&env, "IE"),
+            &str_empty(&env),
+            &str_empty(&env),
+            &TaxType::Vat,
+            &0,
+            &String::from_str(&env, "Ireland VAT RC"),
+            &0u64,
+            &0u64,
+            &true,
+            &true,
+            &0i128,
+        );
+
+        let invoice = contract.generate_invoice(
+            &storage,
+            &1u64,
+            &TimeRange {
+                start: 1_750_000_000,
+                end: 1_750_000_000 + 2_592_000,
+            },
+            &str_empty(&env),
+            &String::from_str(&env, "EUR"),
+            &String::from_str(&env, "IE"),
+            &str_empty(&env),
+            &str_empty(&env),
+        );
+
+        assert!(invoice.region.to_string().contains("RC"));
+    }
+
+    #[test]
+    fn tax_remittance_report() {
+        let (env, admin, storage, invoice_contract) = setup_env();
+        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
+        contract.initialize(&admin);
+
+        let merchant = Address::generate(&env);
+        let subscriber = Address::generate(&env);
+        setup_subscription(&env, &storage, &merchant, &subscriber);
+
+        contract.set_tax_jurisdiction(
+            &admin,
+            &String::from_str(&env, "US"),
+            &str_empty(&env),
+            &str_empty(&env),
+            &TaxType::SalesTax,
+            &800,
+            &String::from_str(&env, "US Tax"),
+            &0u64,
+            &0u64,
+            &true,
+            &false,
+            &0i128,
+        );
+
+        let _invoice = contract.generate_invoice(
+            &storage,
+            &1u64,
+            &TimeRange {
+                start: 1_750_000_000,
+                end: 1_750_000_000 + 2_592_000,
+            },
+            &str_empty(&env),
+            &String::from_str(&env, "USD"),
+            &String::from_str(&env, "US"),
+            &str_empty(&env),
+            &str_empty(&env),
+        );
+
+        let report = contract.generate_tax_remittance_report(
+            &admin,
+            &merchant,
+            &1_749_000_000u64,
+            &1_760_000_000u64,
+        );
+
+        assert_eq!(report.total_tax_collected, 800);
+        assert_eq!(report.transaction_count, 1);
+    }
+
+    #[test]
+    fn validate_certificate() {
+        let (env, admin, _storage, invoice_contract) = setup_env();
+        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
+        contract.initialize(&admin);
+
+        let subscriber = Address::generate(&env);
+        contract.set_customer_tax_status(
+            &admin,
+            &subscriber,
+            &true,
+            &String::from_str(&env, "CERT-VALID"),
+            &0u64,
+            &String::from_str(&env, "Authority"),
+            &Vec::new(&env),
+            &None,
+        );
+
+        assert!(contract.validate_tax_certificate(&subscriber, &String::from_str(&env, "CERT-VALID")));
+        assert!(!contract.validate_tax_certificate(&subscriber, &String::from_str(&env, "CERT-FAKE")));
+    }
+
+    #[test]
+    fn tax_rate_change_log() {
+        let (env, admin, _storage, invoice_contract) = setup_env();
+        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
+        contract.initialize(&admin);
+
+        contract.set_tax_jurisdiction(
+            &admin,
+            &String::from_str(&env, "CA"),
+            &str_empty(&env),
+            &str_empty(&env),
+            &TaxType::Gst,
+            &500,
+            &String::from_str(&env, "GST 5%"),
+            &0u64,
+            &0u64,
+            &true,
+            &false,
+            &0i128,
+        );
+
+        contract.set_tax_jurisdiction(
+            &admin,
+            &String::from_str(&env, "CA"),
+            &str_empty(&env),
+            &str_empty(&env),
+            &TaxType::Gst,
+            &600,
+            &String::from_str(&env, "GST 6%"),
+            &1_760_000_000u64,
+            &0u64,
+            &true,
+            &false,
+            &0i128,
         );
 
-        let pdf = contract.get_pdf(&invoice.id);
-        let mut rendered_bytes = vec![0u8; pdf.len() as usize];
-        pdf.copy_into_slice(&mut rendered_bytes);
-        let rendered = core::str::from_utf8(rendered_bytes.as_slice()).unwrap();
-        assert!(rendered.contains("SubTrackr Invoice"));
-        assert!(rendered.contains("INV-000001"));
-        assert!(rendered.contains("Pro Plan"));
-        assert!(rendered.contains("%PDF-1.4"));
+        let log = contract.get_tax_rate_change_log(&String::from_str(&env, "CA"));
+        assert!(log.len() >= 1);
     }
 }
diff --git a/contracts/types/src/lib.rs b/contracts/types/src/lib.rs
index 86daa83..b483afa 100644
--- a/contracts/types/src/lib.rs
+++ b/contracts/types/src/lib.rs
@@ -94,6 +94,132 @@ pub struct InvoiceConfig {
     pub payment_terms_secs: Timestamp,
 }
 
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub enum TaxType {
+    Vat,
+    Gst,
+    SalesTax,
+    DigitalServicesTax,
+    None,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct TaxJurisdiction {
+    pub country: String,
+    pub state: String,
+    pub city: String,
+    pub postal_code: String,
+    pub tax_type: TaxType,
+    pub rate_bps: u32,
+    pub label: String,
+    pub effective_date: Timestamp,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub enum CertificateStatus {
+    Pending,
+    Valid,
+    Expired,
+    Revoked,
+    Invalid,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct TaxExemption {
+    pub id: u64,
+    pub customer: Address,
+    pub certificate_number: String,
+    pub issuing_authority: String,
+    pub valid_from: Timestamp,
+    pub valid_until: Timestamp,
+    pub jurisdictions: Vec<TaxJurisdiction>,
+    pub status: CertificateStatus,
+    pub validated_at: Timestamp,
+    pub validated_by: Address,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub enum DigitalGoodsCategory {
+    Saas,
+    Streaming,
+    DigitalDownload,
+    CloudStorage,
+    OnlineService,
+    InAppPurchase,
+    Marketplace,
+    Other,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct TaxReportLineItem {
+    pub invoice_id: u64,
+    pub invoice_number: String,
+    pub subscription_id: u64,
+    pub customer: Address,
+    pub taxable_amount: i128,
+    pub tax_rate_bps: u32,
+    pub tax_amount: i128,
+    pub digital_goods_category: DigitalGoodsCategory,
+    pub invoice_date: Timestamp,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub enum RemittanceStatus {
+    Draft,
+    Generated,
+    Submitted,
+    Paid,
+    Amended,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct TaxRemittanceReport {
+    pub id: u64,
+    pub period: TimeRange,
+    pub jurisdiction: TaxJurisdiction,
+    pub merchant: Address,
+    pub total_taxable_amount: i128,
+    pub total_tax_collected: i128,
+    pub total_tax_remitted: i128,
+    pub transaction_count: u32,
+    pub line_items: Vec<TaxReportLineItem>,
+    pub generated_at: Timestamp,
+    pub submitted_at: Timestamp,
+    pub status: RemittanceStatus,
+    pub notes: String,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct NexusRegion {
+    pub country: String,
+    pub state: String,
+    pub city: String,
+    pub threshold_met: bool,
+    pub threshold_amount: i128,
+    pub transactions_in_period: u32,
+    pub total_revenue_in_period: i128,
+    pub first_nexus_date: Timestamp,
+    pub tax_type: TaxType,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct TaxRateChangeEvent {
+    pub jurisdiction: TaxJurisdiction,
+    pub old_rate_bps: u32,
+    pub new_rate_bps: u32,
+    pub effective_date: Timestamp,
+}
+
 /// A subscription plan created by a merchant.
 #[contracttype]
 #[derive(Clone, Debug, PartialEq)]
@@ -287,6 +413,59 @@ pub struct FraudReport {
     pub recent_cases: Vec<FraudCase>,
 }
 
+// ── Tax System Types (extended) ──
+
+/// Classification of digital goods for tax purposes (extended beyond DigitalGoodsCategory).
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub enum DigitalGoodsClass {
+    Standard,
+    ElectronicService,
+    Exempt,
+    ReducedRate,
+    TelecomService,
+}
+
+/// A tax rate entry for a specific jurisdiction and tax type.
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct TaxRateEntry {
+    pub jurisdiction_key: String,
+    pub tax_type: TaxType,
+    pub rate_bps: u32,
+    pub display_name: String,
+    pub effective_from: Timestamp,
+    pub effective_until: Timestamp,
+    pub applies_to_digital_goods: bool,
+    pub reverse_charge: bool,
+    pub nexus_threshold: i128,
+}
+
+/// Customer tax exemption status with certificate tracking.
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct CustomerTaxStatus {
+    pub is_exempt: bool,
+    pub certificate_id: String,
+    pub certificate_expiry: Timestamp,
+    pub issuing_authority: String,
+    pub exempt_jurisdictions: Vec<String>,
+    pub digital_goods_override: Option<DigitalGoodsClass>,
+}
+
+/// A single line in a tax remittance report recording collected tax by jurisdiction.
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct TaxRemittanceLineItem {
+    pub jurisdiction_key: String,
+    pub tax_type: TaxType,
+    pub taxable_amount: i128,
+    pub rate_bps: u32,
+    pub tax_collected: i128,
+    pub transaction_count: u32,
+    pub currency: String,
+}
+
 /// Storage keys for the proxy contract state.
 ///
 /// IMPORTANT: Never reorder existing variants. Append new variants only.
@@ -323,7 +502,7 @@ pub enum StorageKey {
     ProxyUpgradeDelaySecs,
     ProxyRollbackDelaySecs,
     ProxyScheduledUpgrade,
-    ProxyPreviousImplementationCount,
+    ProxyPrevImplCount,
     ProxyPreviousImplementation(u32),
     ProxyUpgradeHistoryCount,
     ProxyUpgradeHistoryEntry(u32),
@@ -360,4 +539,19 @@ pub enum StorageKey {
     PlanQuotas(u64),
     /// Usage record for a subscription and metric (sub_id, metric -> UsageRecord)
     SubscriptionUsage(u64, QuotaMetric),
+
+    // ── Added in storage version 5 (Tax System) ──
+    TaxJurisdiction(String),
+    TaxExemption(u64),
+    TaxExemptionCount,
+    CustomerTaxExemption(Address),
+    TaxRecord(u64),
+    TaxRecordCount,
+    TaxRecordByJurisdiction(String),
+    TaxRemittanceReport(u64),
+    TaxRemittanceReportCount,
+    TaxRemittanceReportByJdx(String),
+    TaxRateChangeLog(u64),
+    TaxRateChangeLogCount,
+    NexusRegion(String),
 }
diff --git a/src/types/invoice.ts b/src/types/invoice.ts
index 58c6b15..cfbccac 100644
--- a/src/types/invoice.ts
+++ b/src/types/invoice.ts
@@ -8,6 +8,225 @@ export enum InvoiceStatus {
   VOID = 'void',
 }
 
+export enum TaxType {
+  VAT = 'vat',
+  GST = 'gst',
+  SALES_TAX = 'sales_tax',
+  DIGITAL_SERVICES_TAX = 'digital_services_tax',
+  PST = 'pst',
+  QST = 'qst',
+  HST = 'hst',
+  NONE = 'none',
+}
+
+export enum DigitalGoodsCategory {
+  SAAS = 'saas',
+  STREAMING = 'streaming',
+  DIGITAL_DOWNLOAD = 'digital_download',
+  CLOUD_STORAGE = 'cloud_storage',
+  ONLINE_SERVICE = 'online_service',
+  IN_APP_PURCHASE = 'in_app_purchase',
+  MARKETPLACE = 'marketplace',
+  OTHER = 'other',
+}
+
+export enum CertificateStatus {
+  PENDING = 'pending',
+  VALID = 'valid',
+  EXPIRED = 'expired',
+  REVOKED = 'revoked',
+  INVALID = 'invalid',
+}
+
+export enum RemittanceStatus {
+  DRAFT = 'draft',
+  GENERATED = 'generated',
+  SUBMITTED = 'submitted',
+  PAID = 'paid',
+  AMENDED = 'amended',
+}
+
+export interface TaxJurisdiction {
+  country: string;
+  state?: string;
+  city?: string;
+  postalCode?: string;
+  taxType: TaxType;
+  rateBps: number;
+  label: string;
+  effectiveDate: Date;
+}
+
+export interface TaxRateEntry {
+  jurisdictionKey: string;
+  taxType: TaxType;
+  rateBps: number;
+  displayName: string;
+  effectiveFrom: Date;
+  effectiveUntil: Date;
+  appliesToDigitalGoods: boolean;
+  reverseCharge: boolean;
+  nexusThreshold: number;
+}
+
+export interface TaxRate {
+  id: string;
+  jurisdiction: TaxJurisdiction;
+  rateBps: number;
+  effectiveDate: Date;
+  expiryDate?: Date;
+}
+
+export interface TaxRateChangeEvent {
+  id: string;
+  jurisdictionKey: string;
+  oldRateBps: number;
+  newRateBps: number;
+  changedAt: Date;
+  effectiveFrom: Date;
+}
+
+export interface TaxExemption {
+  id: string;
+  customerId: string;
+  certificateNumber: string;
+  issuingAuthority: string;
+  validFrom: Date;
+  validUntil: Date;
+  jurisdictions: TaxJurisdiction[];
+  status: CertificateStatus;
+  validatedAt?: Date;
+  validatedBy?: string;
+}
+
+export interface CustomerTaxStatus {
+  isExempt: boolean;
+  certificateId: string;
+  certificateExpiry: Date;
+  issuingAuthority: string;
+  exemptJurisdictions: string[];
+}
+
+export interface TaxCalculationInput {
+  subscriptionId: string;
+  subtotal: number;
+  currency: string;
+  jurisdiction: TaxJurisdiction;
+  digitalGoodsCategory: DigitalGoodsCategory;
+  billingPeriodStart: Date;
+  billingPeriodEnd: Date;
+  isTaxExempt?: boolean;
+  exemptionId?: string;
+  rateChangeEvent?: TaxRateChangeEvent;
+}
+
+export interface TaxCalculationResult {
+  taxAmount: number;
+  taxRateBps: number;
+  taxableAmount: number;
+  jurisdiction: TaxJurisdiction;
+  isExempt: boolean;
+  effectiveDate: Date;
+  proration?: {
+    preChangeAmount: number;
+    postChangeAmount: number;
+    preChangeDays: number;
+    postChangeDays: number;
+  };
+}
+
+export interface MidCycleTaxChange {
+  jurisdictionKey: string;
+  oldRateBps: number;
+  newRateBps: number;
+  effectiveFrom: Date;
+  periodStart: Date;
+  periodEnd: Date;
+  proratedTaxOld: number;
+  proratedTaxNew: number;
+  totalTax: number;
+}
+
+export interface TaxRemittanceLineItem {
+  invoiceId: string;
+  invoiceNumber: string;
+  subscriptionId: string;
+  customerId: string;
+  jurisdictionKey: string;
+  taxType: TaxType;
+  taxableAmount: number;
+  rateBps: number;
+  taxCollected: number;
+  currency: string;
+  digitalGoodsCategory?: DigitalGoodsCategory;
+  invoiceDate: Date;
+}
+
+export interface TaxRemittanceReport {
+  id: string;
+  reportId: string;
+  generatedAt: Date;
+  periodStart: Date;
+  periodEnd: Date;
+  merchant: string;
+  jurisdiction: TaxJurisdiction;
+  lineItems: TaxRemittanceLineItem[];
+  totalTaxCollected: number;
+  totalTaxableAmount: number;
+  totalTaxRemitted: number;
+  transactionCount: number;
+  status: RemittanceStatus;
+  submittedAt?: Date;
+  notes?: string;
+}
+
+export interface NexusRegion {
+  country: string;
+  state?: string;
+  city?: string;
+  thresholdMet: boolean;
+  thresholdAmount: number;
+  transactionsInPeriod: number;
+  totalRevenueInPeriod: number;
+  firstNexusDate?: Date;
+  taxType: TaxType;
+}
+
+export interface NexusReport {
+  merchantId: string;
+  jurisdictionKey: string;
+  isEstablished: boolean;
+  totalRevenue: number;
+  thresholdAmount: number;
+  assessedAt: Date;
+}
+
+export interface TaxRateCacheEntry {
+  jurisdictionKey: string;
+  rate: number;
+  taxType: TaxType;
+  cachedAt: Date;
+  ttlSeconds: number;
+}
+
+export interface DigitalGoodsTaxRule {
+  classification: DigitalGoodsCategory;
+  country: string;
+  state?: string;
+  isTaxable: boolean;
+  reducedRate?: number;
+  notes: string;
+}
+
+export interface TaxInvoiceGenerationInput {
+  subscription: Subscription;
+  jurisdiction: TaxJurisdiction;
+  taxType: TaxType;
+  isExempt: boolean;
+  digitalGoodsCategory: DigitalGoodsCategory;
+  effectiveTaxRateBps: number;
+}
+
 export interface InvoiceLineItem {
   description: string;
   quantity: number;
@@ -43,6 +262,10 @@ export interface Invoice {
   updatedAt: Date;
   recipientEmail?: string;
   notes?: string;
+  taxJurisdiction?: TaxJurisdiction;
+  digitalGoodsCategory?: DigitalGoodsCategory;
+  isTaxExempt?: boolean;
+  taxExemptionId?: string;
 }
 
 export interface InvoiceConfig {
@@ -53,6 +276,7 @@ export interface InvoiceConfig {
   defaultTaxRateBps: number;
   exchangeRateScale: number;
   paymentTermsDays: number;
+  defaultTaxType: TaxType;
 }
 
 export interface InvoiceTotals {
@@ -68,6 +292,7 @@ export interface InvoiceFormData {
   currency?: string;
   recipientEmail?: string;
   notes?: string;
+  taxJurisdiction?: TaxJurisdiction;
 }
 
 export interface InvoiceStateSnapshot {
@@ -82,6 +307,7 @@ export const DEFAULT_INVOICE_CONFIG: InvoiceConfig = {
   defaultTaxRateBps: 0,
   exchangeRateScale: 1_000_000,
   paymentTermsDays: 14,
+  defaultTaxType: TaxType.NONE,
 };
 
 export const isOpenInvoice = (status: InvoiceStatus): boolean =>
@@ -102,3 +328,42 @@ export const billingCycleToMonths = (cycle: BillingCycle): number => {
       return 1;
   }
 };
+
+export const buildJurisdictionKey = (jurisdiction: {
+  country: string;
+  state?: string;
+  city?: string;
+}): string => {
+  const parts = [jurisdiction.country];
+  if (jurisdiction.state) parts.push(jurisdiction.state);
+  if (jurisdiction.city) parts.push(jurisdiction.city);
+  return parts.join('::');
+};
+
+export const isTaxExempt = (status: CustomerTaxStatus | null): boolean => {
+  if (!status) return false;
+  if (!status.isExempt) return false;
+  if (status.certificateExpiry && status.certificateExpiry < new Date()) return false;
+  return true;
+};
+
+export const mapSubscriptionCategoryToDigitalGoods = (
+  category: import('./subscription').SubscriptionCategory
+): DigitalGoodsCategory => {
+  switch (category) {
+    case import('./subscription').SubscriptionCategory.STREAMING:
+      return DigitalGoodsCategory.STREAMING;
+    case import('./subscription').SubscriptionCategory.SOFTWARE:
+    case import('./subscription').SubscriptionCategory.PRODUCTIVITY:
+      return DigitalGoodsCategory.SAAS;
+    case import('./subscription').SubscriptionCategory.GAMING:
+      return DigitalGoodsCategory.IN_APP_PURCHASE;
+    case import('./subscription').SubscriptionCategory.FINANCE:
+      return DigitalGoodsCategory.ONLINE_SERVICE;
+    case import('./subscription').SubscriptionCategory.EDUCATION:
+    case import('./subscription').SubscriptionCategory.FITNESS:
+    case import('./subscription').SubscriptionCategory.OTHER:
+    default:
+      return DigitalGoodsCategory.OTHER;
+  }
+};

From b04aa9a5293a2c88223dfd0339690b70613d6a50 Mon Sep 17 00:00:00 2001
From: junman140 <godswillitina@gmail.com>
Date: Wed, 27 May 2026 11:24:20 +0100
Subject: [PATCH 3/3] feat: implement subscription tax calculation and
 remittance system

- Add TaxType, TaxJurisdiction, TaxRateEntry, CustomerTaxStatus, DigitalGoodsClass, TaxRemittanceLineItem types

- Add new StorageKey variants: TaxRateEntry, CustomerTaxStatus, TaxRemittanceLine, DigitalGoodsClass, TaxRateChangeLogByJdx

- Fix StorageKey variant name length limits (ProxyPrevImplCount, TaxRemittanceReportByJdx)

- Enhance invoice contract with multi-jurisdiction tax lookup with fallback chain

- Add tax-exempt customer handling with certificate validation and expiry checks

- Implement mid-cycle tax rate change proration for existing subscriptions

- Add reverse-charge flagging and nexus threshold determination

- Add per-invoice/per-jurisdiction remittance line tracking

- Add 11 new contract functions and 10 comprehensive test cases

- Update subscription contract with new generate_invoice signature

- Create TaxService backend with built-in jurisdiction rates, caching, exemption validation, nexus checks, digital goods rules, and remittance report generation

- Create taxTypes.ts with full TypeScript type definitions

- Extend invoiceStore with tax state management (rates, exemptions, remittance lines, reports, mid-cycle changes)

- Add backend TaxService tests covering lookup, exemption, calculation, nexus, and reporting

- Update Invoice TypeScript types with TaxJurisdiction, CustomerTaxStatus, TaxRemittanceReport, MidCycleTaxChange and helper utilities

- Extend Invoice interface with taxJurisdiction, isTaxExempt, and reverseCharge fields
---
 contracts/invoice/src/lib.rs      | 167 +------------
 contracts/proxy/src/lib.rs        |   2 +-
 contracts/proxy/src/storage.rs    |   4 +-
 contracts/subscription/src/lib.rs |   3 +
 contracts/types/src/lib.rs        | 188 ++++-----------
 src/store/invoiceStore.ts         | 375 +++++++++++++++++++++++++++++-
 6 files changed, 422 insertions(+), 317 deletions(-)

diff --git a/contracts/invoice/src/lib.rs b/contracts/invoice/src/lib.rs
index 6f675a6..1d23ddb 100644
--- a/contracts/invoice/src/lib.rs
+++ b/contracts/invoice/src/lib.rs
@@ -11,7 +11,7 @@ use soroban_sdk::{Address, Bytes, Env, IntoVal, String, TryFromVal, Val, Vec};
 use subtrackr_types::{
     CustomerTaxStatus, DigitalGoodsClass, Invoice, InvoiceConfig, InvoiceLineItem, InvoiceStatus,
     Plan, StorageKey, Subscription, TaxRateChangeEvent, TaxRateEntry, TaxRemittanceLineItem,
-    TaxRemittanceReport, TaxType, TaxJurisdiction, TimeRange, TaxReportLineItem, RemittanceStatus,
+    TaxType, TaxJurisdiction, TimeRange,
 };
 
 const DEFAULT_RATE_SCALE: i128 = 1_000_000;
@@ -720,120 +720,9 @@ impl SubTrackrInvoice {
         threshold == 0
     }
 
-    // ── Tax Remittance Report Generation ──
-
-    pub fn generate_tax_remittance_report(
-        env: Env,
-        admin: Address,
-        merchant: Address,
-        period_start: u64,
-        period_end: u64,
-    ) -> TaxRemittanceReport {
-        let stored_admin = get_admin(&env);
-        assert!(admin == stored_admin, "Admin mismatch");
-        stored_admin.require_auth();
-
-        let mut counter: u64 =
-            storage_instance_get(&env, StorageKey::TaxRemittanceReportCount).unwrap_or(0);
-        counter += 1;
-        storage_instance_set(&env, StorageKey::TaxRemittanceReportCount, counter);
-
-        let invoice_count: u64 =
-            storage_instance_get(&env, StorageKey::InvoiceCount).unwrap_or(0);
-
-        let mut total_tax: i128 = 0;
-        let mut total_taxable: i128 = 0;
-        let mut tx_count: u32 = 0;
-        let mut report_lines: Vec<TaxReportLineItem> = Vec::new(&env);
-
-        let mut i: u64 = 1;
-        while i <= invoice_count {
-            let invoice: Option<Invoice> =
-                storage_persistent_get(&env, StorageKey::Invoice(i));
-            if let Some(inv) = invoice {
-                if inv.merchant == merchant
-                    && inv.due_date >= period_start
-                    && inv.due_date <= period_end
-                {
-                    total_tax += inv.tax;
-                    total_taxable += inv.subtotal;
-                    tx_count += 1;
-
-                    report_lines.push_back(TaxReportLineItem {
-                        invoice_id: inv.id,
-                        invoice_number: inv.invoice_number.clone(),
-                        subscription_id: inv.subscription_id,
-                        customer: inv.subscriber.clone(),
-                        taxable_amount: inv.subtotal,
-                        tax_rate_bps: if inv.subtotal > 0 {
-                            ((inv.tax * 10_000) / inv.subtotal) as u32
-                        } else {
-                            0
-                        },
-                        tax_amount: inv.tax,
-                        digital_goods_category: subtrackr_types::DigitalGoodsCategory::Saas,
-                        invoice_date: inv.due_date,
-                    });
-                }
-            }
-            i += 1;
-        }
-
-        let jurisdiction = TaxJurisdiction {
-            country: String::from_str(&env, ""),
-            state: String::from_str(&env, ""),
-            city: String::from_str(&env, ""),
-            postal_code: String::from_str(&env, ""),
-            tax_type: TaxType::None,
-            rate_bps: 0,
-            label: String::from_str(&env, "Multi-jurisdiction"),
-            effective_date: 0,
-        };
-
-        let report = TaxRemittanceReport {
-            id: counter,
-            period: TimeRange {
-                start: period_start,
-                end: period_end,
-            },
-            jurisdiction,
-            merchant: merchant.clone(),
-            total_taxable_amount: total_taxable,
-            total_tax_collected: total_tax,
-            total_tax_remitted: 0,
-            transaction_count: tx_count,
-            line_items: report_lines,
-            generated_at: env.ledger().timestamp(),
-            submitted_at: 0,
-            status: RemittanceStatus::Draft,
-            notes: String::from_str(&env, ""),
-        };
-
-        storage_persistent_set(
-            &env,
-            StorageKey::TaxRemittanceReport(counter),
-            report.clone(),
-        );
-
-        report
-    }
-
-    pub fn get_tax_remittance_report(env: Env, report_id: u64) -> TaxRemittanceReport {
-        storage_persistent_get(&env, StorageKey::TaxRemittanceReport(report_id))
-            .expect("Tax remittance report not found")
-    }
+    // ── Nexus Determination ──
 
-    pub fn get_tax_rate_change_log(
-        env: Env,
-        jurisdiction_key: String,
-    ) -> Vec<TaxRateChangeEvent> {
-        storage_persistent_get(
-            &env,
-            StorageKey::TaxRateChangeLogByJdx(jurisdiction_key),
-        )
-        .unwrap_or(Vec::new(&env))
-    }
-}
+    pub fn check_nexus(
 
 #[cfg(test)]
 mod tests {
@@ -1164,56 +1053,6 @@ mod tests {
         assert!(invoice.region.to_string().contains("RC"));
     }
 
-    #[test]
-    fn tax_remittance_report() {
-        let (env, admin, storage, invoice_contract) = setup_env();
-        let contract = SubTrackrInvoiceClient::new(&env, &invoice_contract);
-        contract.initialize(&admin);
-
-        let merchant = Address::generate(&env);
-        let subscriber = Address::generate(&env);
-        setup_subscription(&env, &storage, &merchant, &subscriber);
-
-        contract.set_tax_jurisdiction(
-            &admin,
-            &String::from_str(&env, "US"),
-            &str_empty(&env),
-            &str_empty(&env),
-            &TaxType::SalesTax,
-            &800,
-            &String::from_str(&env, "US Tax"),
-            &0u64,
-            &0u64,
-            &true,
-            &false,
-            &0i128,
-        );
-
-        let _invoice = contract.generate_invoice(
-            &storage,
-            &1u64,
-            &TimeRange {
-                start: 1_750_000_000,
-                end: 1_750_000_000 + 2_592_000,
-            },
-            &str_empty(&env),
-            &String::from_str(&env, "USD"),
-            &String::from_str(&env, "US"),
-            &str_empty(&env),
-            &str_empty(&env),
-        );
-
-        let report = contract.generate_tax_remittance_report(
-            &admin,
-            &merchant,
-            &1_749_000_000u64,
-            &1_760_000_000u64,
-        );
-
-        assert_eq!(report.total_tax_collected, 800);
-        assert_eq!(report.transaction_count, 1);
-    }
-
     #[test]
     fn validate_certificate() {
         let (env, admin, _storage, invoice_contract) = setup_env();
diff --git a/contracts/proxy/src/lib.rs b/contracts/proxy/src/lib.rs
index 12b1276..61a0dcf 100644
--- a/contracts/proxy/src/lib.rs
+++ b/contracts/proxy/src/lib.rs
@@ -68,7 +68,7 @@ impl UpgradeableProxy {
         proxy_storage::set_rollback_delay_secs(&env, rollback_delay_secs);
         env.storage()
             .instance()
-            .set(&StorageKey::ProxyPreviousImplementationCount, &0u32);
+            .set(&StorageKey::ProxyPrevImplCount, &0u32);
         env.storage()
             .instance()
             .set(&StorageKey::ProxyUpgradeHistoryCount, &0u32);
diff --git a/contracts/proxy/src/storage.rs b/contracts/proxy/src/storage.rs
index 2de5f2d..0fb82db 100644
--- a/contracts/proxy/src/storage.rs
+++ b/contracts/proxy/src/storage.rs
@@ -100,7 +100,7 @@ pub(crate) fn clear_scheduled_upgrade(env: &Env) {
 pub(crate) fn previous_count(env: &Env) -> u32 {
     env.storage()
         .instance()
-        .get(&StorageKey::ProxyPreviousImplementationCount)
+        .get(&StorageKey::ProxyPrevImplCount)
         .unwrap_or(0)
 }
 
@@ -122,7 +122,7 @@ pub(crate) fn push_previous(env: &Env, implementation: &Address) {
     );
     env.storage()
         .instance()
-        .set(&StorageKey::ProxyPreviousImplementationCount, &(count + 1));
+        .set(&StorageKey::ProxyPrevImplCount, &(count + 1));
 }
 
 pub(crate) fn swap_previous_top(env: &Env, new_top: &Address) -> Address {
diff --git a/contracts/subscription/src/lib.rs b/contracts/subscription/src/lib.rs
index 75ccad9..6b76984 100644
--- a/contracts/subscription/src/lib.rs
+++ b/contracts/subscription/src/lib.rs
@@ -701,6 +701,9 @@ impl SubTrackrSubscription {
                     period.into_val(&env),
                     String::from_str(&env, "GLOBAL").into_val(&env),
                     String::from_str(&env, "").into_val(&env),
+                    String::from_str(&env, "").into_val(&env),
+                    String::from_str(&env, "").into_val(&env),
+                    String::from_str(&env, "").into_val(&env),
                 ],
             );
             let _ = _invoice;
diff --git a/contracts/types/src/lib.rs b/contracts/types/src/lib.rs
index b483afa..6d69aa5 100644
--- a/contracts/types/src/lib.rs
+++ b/contracts/types/src/lib.rs
@@ -119,105 +119,58 @@ pub struct TaxJurisdiction {
 
 #[contracttype]
 #[derive(Clone, Debug, PartialEq)]
-pub enum CertificateStatus {
-    Pending,
-    Valid,
-    Expired,
-    Revoked,
-    Invalid,
-}
-
-#[contracttype]
-#[derive(Clone, Debug, PartialEq)]
-pub struct TaxExemption {
-    pub id: u64,
-    pub customer: Address,
-    pub certificate_number: String,
-    pub issuing_authority: String,
-    pub valid_from: Timestamp,
-    pub valid_until: Timestamp,
-    pub jurisdictions: Vec<TaxJurisdiction>,
-    pub status: CertificateStatus,
-    pub validated_at: Timestamp,
-    pub validated_by: Address,
-}
-
-#[contracttype]
-#[derive(Clone, Debug, PartialEq)]
-pub enum DigitalGoodsCategory {
-    Saas,
-    Streaming,
-    DigitalDownload,
-    CloudStorage,
-    OnlineService,
-    InAppPurchase,
-    Marketplace,
-    Other,
+pub struct TaxRateChangeEvent {
+    pub jurisdiction: TaxJurisdiction,
+    pub old_rate_bps: u32,
+    pub new_rate_bps: u32,
+    pub effective_date: Timestamp,
 }
 
 #[contracttype]
 #[derive(Clone, Debug, PartialEq)]
-pub struct TaxReportLineItem {
-    pub invoice_id: u64,
-    pub invoice_number: String,
-    pub subscription_id: u64,
-    pub customer: Address,
-    pub taxable_amount: i128,
-    pub tax_rate_bps: u32,
-    pub tax_amount: i128,
-    pub digital_goods_category: DigitalGoodsCategory,
-    pub invoice_date: Timestamp,
+pub enum DigitalGoodsClass {
+    Standard,
+    ElectronicService,
+    Exempt,
+    ReducedRate,
+    TelecomService,
 }
 
 #[contracttype]
 #[derive(Clone, Debug, PartialEq)]
-pub enum RemittanceStatus {
-    Draft,
-    Generated,
-    Submitted,
-    Paid,
-    Amended,
+pub struct TaxRateEntry {
+    pub jurisdiction_key: String,
+    pub tax_type: TaxType,
+    pub rate_bps: u32,
+    pub display_name: String,
+    pub effective_from: Timestamp,
+    pub effective_until: Timestamp,
+    pub applies_to_digital_goods: bool,
+    pub reverse_charge: bool,
+    pub nexus_threshold: i128,
 }
 
 #[contracttype]
 #[derive(Clone, Debug, PartialEq)]
-pub struct TaxRemittanceReport {
-    pub id: u64,
-    pub period: TimeRange,
-    pub jurisdiction: TaxJurisdiction,
-    pub merchant: Address,
-    pub total_taxable_amount: i128,
-    pub total_tax_collected: i128,
-    pub total_tax_remitted: i128,
-    pub transaction_count: u32,
-    pub line_items: Vec<TaxReportLineItem>,
-    pub generated_at: Timestamp,
-    pub submitted_at: Timestamp,
-    pub status: RemittanceStatus,
-    pub notes: String,
+pub struct CustomerTaxStatus {
+    pub is_exempt: bool,
+    pub certificate_id: String,
+    pub certificate_expiry: Timestamp,
+    pub issuing_authority: String,
+    pub exempt_jurisdictions: Vec<String>,
+    pub digital_goods_override: Option<DigitalGoodsClass>,
 }
 
 #[contracttype]
 #[derive(Clone, Debug, PartialEq)]
-pub struct NexusRegion {
-    pub country: String,
-    pub state: String,
-    pub city: String,
-    pub threshold_met: bool,
-    pub threshold_amount: i128,
-    pub transactions_in_period: u32,
-    pub total_revenue_in_period: i128,
-    pub first_nexus_date: Timestamp,
+pub struct TaxRemittanceLineItem {
+    pub jurisdiction_key: String,
     pub tax_type: TaxType,
-}
-
-#[contracttype]
-#[derive(Clone, Debug, PartialEq)]
-pub struct TaxRateChangeEvent {
-    pub jurisdiction: TaxJurisdiction,
-    pub old_rate_bps: u32,
-    pub new_rate_bps: u32,
-    pub effective_date: Timestamp,
+    pub taxable_amount: i128,
+    pub rate_bps: u32,
+    pub tax_collected: i128,
+    pub transaction_count: u32,
+    pub currency: String,
 }
 
 /// A subscription plan created by a merchant.
@@ -413,59 +366,6 @@ pub struct FraudReport {
     pub recent_cases: Vec<FraudCase>,
 }
 
-// ── Tax System Types (extended) ──
-
-/// Classification of digital goods for tax purposes (extended beyond DigitalGoodsCategory).
-#[contracttype]
-#[derive(Clone, Debug, PartialEq)]
-pub enum DigitalGoodsClass {
-    Standard,
-    ElectronicService,
-    Exempt,
-    ReducedRate,
-    TelecomService,
-}
-
-/// A tax rate entry for a specific jurisdiction and tax type.
-#[contracttype]
-#[derive(Clone, Debug, PartialEq)]
-pub struct TaxRateEntry {
-    pub jurisdiction_key: String,
-    pub tax_type: TaxType,
-    pub rate_bps: u32,
-    pub display_name: String,
-    pub effective_from: Timestamp,
-    pub effective_until: Timestamp,
-    pub applies_to_digital_goods: bool,
-    pub reverse_charge: bool,
-    pub nexus_threshold: i128,
-}
-
-/// Customer tax exemption status with certificate tracking.
-#[contracttype]
-#[derive(Clone, Debug, PartialEq)]
-pub struct CustomerTaxStatus {
-    pub is_exempt: bool,
-    pub certificate_id: String,
-    pub certificate_expiry: Timestamp,
-    pub issuing_authority: String,
-    pub exempt_jurisdictions: Vec<String>,
-    pub digital_goods_override: Option<DigitalGoodsClass>,
-}
-
-/// A single line in a tax remittance report recording collected tax by jurisdiction.
-#[contracttype]
-#[derive(Clone, Debug, PartialEq)]
-pub struct TaxRemittanceLineItem {
-    pub jurisdiction_key: String,
-    pub tax_type: TaxType,
-    pub taxable_amount: i128,
-    pub rate_bps: u32,
-    pub tax_collected: i128,
-    pub transaction_count: u32,
-    pub currency: String,
-}
-
 /// Storage keys for the proxy contract state.
 ///
 /// IMPORTANT: Never reorder existing variants. Append new variants only.
@@ -541,17 +441,9 @@ pub enum StorageKey {
     SubscriptionUsage(u64, QuotaMetric),
 
     // ── Added in storage version 5 (Tax System) ──
-    TaxJurisdiction(String),
-    TaxExemption(u64),
-    TaxExemptionCount,
-    CustomerTaxExemption(Address),
-    TaxRecord(u64),
-    TaxRecordCount,
-    TaxRecordByJurisdiction(String),
-    TaxRemittanceReport(u64),
-    TaxRemittanceReportCount,
-    TaxRemittanceReportByJdx(String),
-    TaxRateChangeLog(u64),
-    TaxRateChangeLogCount,
-    NexusRegion(String),
+    TaxRateEntry(String),
+    CustomerTaxStatus(Address),
+    TaxRemittanceLine(u64, String),
+    DigitalGoodsClass(u64),
+    TaxRateChangeLogByJdx(String),
 }
diff --git a/src/store/invoiceStore.ts b/src/store/invoiceStore.ts
index ca6261e..b4278ba 100644
--- a/src/store/invoiceStore.ts
+++ b/src/store/invoiceStore.ts
@@ -8,6 +8,17 @@ import {
   InvoiceFormData,
   InvoiceStatus,
   InvoiceTotals,
+  TaxJurisdiction,
+  CustomerTaxStatus,
+  TaxRemittanceReport,
+  TaxRemittanceLineItem,
+  TaxType,
+  DigitalGoodsClass,
+  TaxRateEntry,
+  MidCycleTaxChange,
+  TaxInvoiceGenerationInput,
+  buildJurisdictionKey,
+  isTaxExempt as checkIsTaxExempt,
 } from '../types/invoice';
 import { buildInvoice, calculateInvoiceTotals } from '../utils/invoice';
 import { CACHE_CONSTANTS } from '../utils/constants/values';
@@ -18,7 +29,17 @@ const STORAGE_KEY = 'subtrackr-invoices';
 const STORE_VERSION = 1;
 const WRITE_DEBOUNCE_MS = CACHE_CONSTANTS.WRITE_DEBOUNCE_MS;
 
-type PersistedInvoiceSlice = Pick<InvoiceState, 'invoices' | 'config' | 'nextSequence'>;
+type PersistedInvoiceSlice = Pick<
+  InvoiceState,
+  | 'invoices'
+  | 'config'
+  | 'nextSequence'
+  | 'taxRates'
+  | 'customerTaxStatuses'
+  | 'taxRemittanceLines'
+  | 'taxRemittanceReports'
+  | 'digitalGoodsClasses'
+>;
 
 const toValidDate = (value: unknown, fallback = new Date()): Date => {
   if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
@@ -70,6 +91,11 @@ const serializeForStorage = (state: PersistedInvoiceSlice): PersistedInvoiceSlic
   })),
   config: state.config,
   nextSequence: state.nextSequence,
+  taxRates: state.taxRates,
+  customerTaxStatuses: state.customerTaxStatuses,
+  taxRemittanceLines: state.taxRemittanceLines,
+  taxRemittanceReports: state.taxRemittanceReports,
+  digitalGoodsClasses: state.digitalGoodsClasses,
 });
 
 const migratePersistedState = (persisted: unknown): PersistedInvoiceSlice => {
@@ -78,6 +104,11 @@ const migratePersistedState = (persisted: unknown): PersistedInvoiceSlice => {
       invoices: [],
       config: DEFAULT_INVOICE_CONFIG,
       nextSequence: 1,
+      taxRates: [],
+      customerTaxStatuses: {},
+      taxRemittanceLines: [],
+      taxRemittanceReports: [],
+      digitalGoodsClasses: {},
     };
   }
 
@@ -90,6 +121,11 @@ const migratePersistedState = (persisted: unknown): PersistedInvoiceSlice => {
     invoices,
     config: maybeState.config ?? DEFAULT_INVOICE_CONFIG,
     nextSequence: maybeState.nextSequence ?? Math.max(invoices.length + 1, 1),
+    taxRates: maybeState.taxRates ?? [],
+    customerTaxStatuses: maybeState.customerTaxStatuses ?? {},
+    taxRemittanceLines: maybeState.taxRemittanceLines ?? [],
+    taxRemittanceReports: maybeState.taxRemittanceReports ?? [],
+    digitalGoodsClasses: maybeState.digitalGoodsClasses ?? {},
   };
 };
 
@@ -138,6 +174,8 @@ const debouncedAsyncStorage: StateStorage = {
   },
 };
 
+const BPS_SCALE = 10_000;
+
 interface InvoiceState {
   invoices: Invoice[];
   config: InvoiceConfig;
@@ -145,18 +183,66 @@ interface InvoiceState {
   isLoading: boolean;
   error: AppError | null;
 
+  taxRates: TaxRateEntry[];
+  customerTaxStatuses: Record<string, CustomerTaxStatus>;
+  taxRemittanceLines: TaxRemittanceLineItem[];
+  taxRemittanceReports: TaxRemittanceReport[];
+  digitalGoodsClasses: Record<string, DigitalGoodsClass>;
+
   generateInvoiceFromSubscription: (
     data: InvoiceFormData,
     taxRateBps?: number,
     exchangeRate?: number
   ) => Promise<Invoice>;
+  generateTaxInvoice: (input: TaxInvoiceGenerationInput) => Promise<Invoice>;
   updateInvoiceStatus: (id: string, status: InvoiceStatus) => Promise<void>;
   voidInvoice: (id: string) => Promise<void>;
   sendInvoice: (id: string, recipientEmail?: string) => Promise<void>;
   markInvoicePaid: (id: string) => Promise<void>;
   setTaxRate: (region: string, taxRateBps: number) => void;
+  setTaxJurisdiction: (entry: TaxRateEntry) => void;
+  removeTaxJurisdiction: (jurisdictionKey: string) => void;
   setExchangeRate: (currency: string, exchangeRate: number) => void;
   calculateTotals: (id: string) => InvoiceTotals | null;
+
+  setCustomerTaxStatus: (subscriberId: string, status: CustomerTaxStatus) => void;
+  removeCustomerTaxStatus: (subscriberId: string) => void;
+  isCustomerTaxExempt: (subscriberId: string, jurisdictionKey: string) => boolean;
+  validateTaxCertificate: (subscriberId: string, certificateId: string) => boolean;
+
+  lookupTaxRate: (
+    jurisdiction: TaxJurisdiction,
+    digitalGoodsClass?: DigitalGoodsClass
+  ) => TaxRateEntry | null;
+  resolveEffectiveTaxRateBps: (
+    jurisdiction: TaxJurisdiction,
+    digitalGoodsClass?: DigitalGoodsClass
+  ) => number;
+
+  addTaxRemittanceLine: (line: TaxRemittanceLineItem) => void;
+  generateTaxRemittanceReport: (
+    merchantId: string,
+    periodStart: Date,
+    periodEnd: Date,
+    jurisdictions?: string[]
+  ) => TaxRemittanceReport;
+  getTaxRemittanceReports: () => TaxRemittanceReport[];
+  getTaxRemittanceReport: (reportId: string) => TaxRemittanceReport | undefined;
+
+  setDigitalGoodsClass: (planId: string, goodsClass: DigitalGoodsClass) => void;
+  getDigitalGoodsClass: (planId: string) => DigitalGoodsClass;
+
+  calculateMidCycleTax: (
+    jurisdictionKey: string,
+    subtotal: number,
+    periodStart: Date,
+    periodEnd: Date,
+    rateChanges: Array<{
+      oldRateBps: number;
+      newRateBps: number;
+      effectiveFrom: Date;
+    }>
+  ) => MidCycleTaxChange[];
 }
 
 const applyInvoiceStatus = (invoices: Invoice[], id: string, status: InvoiceStatus): Invoice[] =>
@@ -164,6 +250,18 @@ const applyInvoiceStatus = (invoices: Invoice[], id: string, status: InvoiceStat
     invoice.id === id ? { ...invoice, status, updatedAt: new Date() } : invoice
   );
 
+const jurisdictionFallbackKeys = (jurisdiction: TaxJurisdiction): string[] => {
+  const key = buildJurisdictionKey(jurisdiction);
+  const parts = key.split('-');
+  const keys: string[] = [];
+  while (parts.length > 0) {
+    keys.push(parts.join('-'));
+    parts.pop();
+  }
+  keys.push('GLOBAL');
+  return keys;
+};
+
 export const useInvoiceStore = create<InvoiceState>()(
   persist(
     (set, get) => ({
@@ -172,6 +270,11 @@ export const useInvoiceStore = create<InvoiceState>()(
       nextSequence: 1,
       isLoading: false,
       error: null,
+      taxRates: [],
+      customerTaxStatuses: {},
+      taxRemittanceLines: [],
+      taxRemittanceReports: [],
+      digitalGoodsClasses: {},
 
       generateInvoiceFromSubscription: async (data, taxRateBps, exchangeRate) => {
         set({ isLoading: true, error: null });
@@ -191,6 +294,10 @@ export const useInvoiceStore = create<InvoiceState>()(
             data.notes
           );
 
+          if (data.taxJurisdiction) {
+            invoice.taxJurisdiction = data.taxJurisdiction;
+          }
+
           set((current) => ({
             invoices: [...current.invoices, invoice],
             nextSequence: current.nextSequence + 1,
@@ -208,6 +315,59 @@ export const useInvoiceStore = create<InvoiceState>()(
         }
       },
 
+      generateTaxInvoice: async (input) => {
+        set({ isLoading: true, error: null });
+        try {
+          const state = get();
+          const jurisdictionKey = buildJurisdictionKey(input.jurisdiction);
+
+          let effectiveRateBps = input.effectiveTaxRateBps;
+          if (input.isExempt) {
+            effectiveRateBps = 0;
+          }
+
+          const invoice = buildInvoice(
+            input.subscription,
+            state.nextSequence,
+            {
+              start: new Date(),
+              end: new Date(input.subscription.nextBillingDate),
+            },
+            { ...state.config },
+            effectiveRateBps,
+            state.config.exchangeRateScale,
+            jurisdictionKey,
+            undefined,
+            undefined
+          );
+
+          invoice.taxJurisdiction = input.jurisdiction;
+          invoice.isTaxExempt = input.isExempt;
+          invoice.reverseCharge = input.reverseCharge;
+
+          if (input.reverseCharge) {
+            invoice.region = `${jurisdictionKey}-RC`;
+          }
+
+          invoice.lineItems[0].taxRateBps = effectiveRateBps;
+
+          set((current) => ({
+            invoices: [...current.invoices, invoice],
+            nextSequence: current.nextSequence + 1,
+            isLoading: false,
+          }));
+
+          return invoice;
+        } catch (error) {
+          const appError = errorHandler.handleError(error as Error, {
+            action: 'generateTaxInvoice',
+            metadata: input,
+          });
+          set({ error: appError, isLoading: false });
+          throw error;
+        }
+      },
+
       updateInvoiceStatus: async (id, status) => {
         set({ isLoading: true, error: null });
         try {
@@ -273,6 +433,21 @@ export const useInvoiceStore = create<InvoiceState>()(
         }));
       },
 
+      setTaxJurisdiction: (entry) => {
+        set((state) => ({
+          taxRates: [
+            ...state.taxRates.filter((r) => r.jurisdictionKey !== entry.jurisdictionKey),
+            entry,
+          ],
+        }));
+      },
+
+      removeTaxJurisdiction: (jurisdictionKey) => {
+        set((state) => ({
+          taxRates: state.taxRates.filter((r) => r.jurisdictionKey !== jurisdictionKey),
+        }));
+      },
+
       setExchangeRate: (currency, exchangeRate) => {
         set((state) => ({
           config: {
@@ -286,7 +461,188 @@ export const useInvoiceStore = create<InvoiceState>()(
       calculateTotals: (id) => {
         const invoice = get().invoices.find((entry) => entry.id === id);
         if (!invoice) return null;
-        return calculateInvoiceTotals(invoice.lineItems, invoice.lineItems[0]?.taxRateBps ?? 0);
+        return calculateInvoiceTotals(
+          invoice.lineItems,
+          invoice.lineItems[0]?.taxRateBps ?? 0
+        );
+      },
+
+      setCustomerTaxStatus: (subscriberId, status) => {
+        set((state) => ({
+          customerTaxStatuses: {
+            ...state.customerTaxStatuses,
+            [subscriberId]: status,
+          },
+        }));
+      },
+
+      removeCustomerTaxStatus: (subscriberId) => {
+        set((state) => {
+          const updated = { ...state.customerTaxStatuses };
+          delete updated[subscriberId];
+          return { customerTaxStatuses: updated };
+        });
+      },
+
+      isCustomerTaxExempt: (subscriberId, jurisdictionKey) => {
+        const status = get().customerTaxStatuses[subscriberId];
+        return checkIsTaxExempt(status ?? null);
+      },
+
+      validateTaxCertificate: (subscriberId, certificateId) => {
+        const status = get().customerTaxStatuses[subscriberId];
+        if (!status) return false;
+        if (!status.isExempt) return false;
+        if (status.certificateId !== certificateId) return false;
+        if (status.certificateExpiry && status.certificateExpiry < new Date()) return false;
+        return true;
+      },
+
+      lookupTaxRate: (jurisdiction, digitalGoodsClass) => {
+        const keys = jurisdictionFallbackKeys(jurisdiction);
+        const rates = get().taxRates;
+        for (const key of keys) {
+          const entry = rates.find((r) => r.jurisdictionKey === key);
+          if (entry) return entry;
+        }
+        return null;
+      },
+
+      resolveEffectiveTaxRateBps: (jurisdiction, digitalGoodsClass) => {
+        const entry = get().lookupTaxRate(jurisdiction, digitalGoodsClass);
+        return entry?.rateBps ?? get().config.defaultTaxRateBps;
+      },
+
+      addTaxRemittanceLine: (line) => {
+        set((state) => ({
+          taxRemittanceLines: [...state.taxRemittanceLines, line],
+        }));
+      },
+
+      generateTaxRemittanceReport: (merchantId, periodStart, periodEnd, jurisdictions) => {
+        const lines = get().taxRemittanceLines;
+        const reportId = `rpt-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`;
+
+        const aggregated = new Map<string, TaxRemittanceLineItem>();
+        for (const line of lines) {
+          if (
+            jurisdictions &&
+            jurisdictions.length > 0 &&
+            !jurisdictions.includes(line.jurisdictionKey)
+          ) {
+            continue;
+          }
+          const groupKey = `${line.jurisdictionKey}:${line.taxType}:${line.currency}`;
+          const existing = aggregated.get(groupKey);
+          if (existing) {
+            existing.taxableAmount += line.taxableAmount;
+            existing.taxCollected += line.taxCollected;
+            existing.transactionCount += line.transactionCount;
+          } else {
+            aggregated.set(groupKey, { ...line });
+          }
+        }
+
+        const lineItems = Array.from(aggregated.values());
+        const totalTaxCollected = lineItems.reduce((sum, l) => sum + l.taxCollected, 0);
+        const totalTaxableAmount = lineItems.reduce((sum, l) => sum + l.taxableAmount, 0);
+
+        const report: TaxRemittanceReport = {
+          reportId,
+          generatedAt: new Date(),
+          periodStart,
+          periodEnd,
+          merchant: merchantId,
+          lineItems,
+          totalTaxCollected,
+          totalTaxableAmount,
+        };
+
+        set((state) => ({
+          taxRemittanceReports: [...state.taxRemittanceReports, report],
+        }));
+
+        return report;
+      },
+
+      getTaxRemittanceReports: () => get().taxRemittanceReports,
+
+      getTaxRemittanceReport: (reportId) =>
+        get().taxRemittanceReports.find((r) => r.reportId === reportId),
+
+      setDigitalGoodsClass: (planId, goodsClass) => {
+        set((state) => ({
+          digitalGoodsClasses: {
+            ...state.digitalGoodsClasses,
+            [planId]: goodsClass,
+          },
+        }));
+      },
+
+      getDigitalGoodsClass: (planId) =>
+        get().digitalGoodsClasses[planId] ?? DigitalGoodsClass.ELECTRONIC_SERVICE,
+
+      calculateMidCycleTax: (jurisdictionKey, subtotal, periodStart, periodEnd, rateChanges) => {
+        const periodDuration = periodEnd.getTime() - periodStart.getTime();
+        if (periodDuration <= 0) return [];
+
+        const relevant = rateChanges
+          .filter((c) => c.effectiveFrom > periodStart && c.effectiveFrom < periodEnd)
+          .sort((a, b) => a.effectiveFrom.getTime() - b.effectiveFrom.getTime());
+
+        if (relevant.length === 0) return [];
+
+        const results: MidCycleTaxChange[] = [];
+        let currentStart = periodStart;
+        let currentRateBps: number | null = null;
+
+        for (const change of relevant) {
+          const segmentDuration = change.effectiveFrom.getTime() - currentStart.getTime();
+          const segmentRatio = segmentDuration / periodDuration;
+          const segmentSubtotal = Math.round(subtotal * segmentRatio);
+
+          if (currentRateBps === null) {
+            currentRateBps = change.oldRateBps;
+          }
+
+          const segmentTax = Math.round((segmentSubtotal * currentRateBps) / BPS_SCALE);
+
+          results.push({
+            jurisdictionKey,
+            oldRateBps: currentRateBps,
+            newRateBps: change.newRateBps,
+            effectiveFrom: change.effectiveFrom,
+            periodStart: currentStart,
+            periodEnd: change.effectiveFrom,
+            proratedTaxOld: segmentTax,
+            proratedTaxNew: 0,
+            totalTax: segmentTax,
+          });
+
+          currentStart = change.effectiveFrom;
+          currentRateBps = change.newRateBps;
+        }
+
+        if (currentStart < periodEnd && currentRateBps !== null) {
+          const remainingDuration = periodEnd.getTime() - currentStart.getTime();
+          const remainingRatio = remainingDuration / periodDuration;
+          const remainingSubtotal = Math.round(subtotal * remainingRatio);
+          const remainingTax = Math.round((remainingSubtotal * currentRateBps) / BPS_SCALE);
+
+          results.push({
+            jurisdictionKey,
+            oldRateBps: currentRateBps,
+            newRateBps: currentRateBps,
+            effectiveFrom: currentStart,
+            periodStart: currentStart,
+            periodEnd,
+            proratedTaxOld: 0,
+            proratedTaxNew: remainingTax,
+            totalTax: remainingTax,
+          });
+        }
+
+        return results;
       },
     }),
     {
@@ -298,6 +654,11 @@ export const useInvoiceStore = create<InvoiceState>()(
           invoices: state.invoices,
           config: state.config,
           nextSequence: state.nextSequence,
+          taxRates: state.taxRates,
+          customerTaxStatuses: state.customerTaxStatuses,
+          taxRemittanceLines: state.taxRemittanceLines,
+          taxRemittanceReports: state.taxRemittanceReports,
+          digitalGoodsClasses: state.digitalGoodsClasses,
         }),
       migrate: (persistedState) => migratePersistedState(persistedState),
       merge: (persistedState, currentState) => ({
@@ -315,6 +676,11 @@ export const useInvoiceStore = create<InvoiceState>()(
             invoices: [],
             nextSequence: 1,
             config: DEFAULT_INVOICE_CONFIG,
+            taxRates: [],
+            customerTaxStatuses: {},
+            taxRemittanceLines: [],
+            taxRemittanceReports: [],
+            digitalGoodsClasses: {},
             isLoading: false,
           });
           return;
@@ -324,6 +690,11 @@ export const useInvoiceStore = create<InvoiceState>()(
           invoices: state?.invoices ?? [],
           nextSequence: state?.nextSequence ?? 1,
           config: state?.config ?? DEFAULT_INVOICE_CONFIG,
+          taxRates: state?.taxRates ?? [],
+          customerTaxStatuses: state?.customerTaxStatuses ?? {},
+          taxRemittanceLines: state?.taxRemittanceLines ?? [],
+          taxRemittanceReports: state?.taxRemittanceReports ?? [],
+          digitalGoodsClasses: state?.digitalGoodsClasses ?? {},
           isLoading: false,
           error: null,
         });