feat: update docs, add security audit, and implement persistent form wrapper

Author: elizabetheonoja-art

README.md

@@ -181,11 +181,18 @@ We welcome contributions from the community! Please see our [Contributing Guidel
 
 This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
 
+## Resources and Documentation
+
+- [Architecture Overview](./docs/architecture.md)
+- [Architectural Decision Records (ADRs)](./docs/adr/README.md)
+- [Security Audit Report](./docs/security/AUDIT_REPORT.md)
+- [Contract Documentation](./contract/README.md)
+
 ## Community
 
 - [Discord](https://discord.gg/gathera)
 - [Twitter](https://twitter.com/gathera)
-- [Documentation](https://docs.gathera.io)
+- [Official Documentation](https://docs.gathera.io)
 
 ## Acknowledgments
 

app/frontend/components/forms/PersistentFormWrapper.tsx

@@ -0,0 +1,220 @@
+'use client';
+
+import React, { useEffect, useRef, useCallback } from 'react';
+
+/**
+ * Persistence storage type
+ */
+type StorageType = 'local' | 'session';
+
+/**
+ * Props for the PersistentFormWrapper component
+ */
+interface PersistentFormWrapperProps {
+  /** The form elements to wrap */
+  children: React.ReactNode;
+  /** Unique key for storage */
+  persistenceKey: string;
+  /** Storage medium (local for persistent across sessions, session for current session) */
+  storageType?: StorageType;
+  /** Optional form ID to target if multiple forms exist in children */
+  formId?: string;
+  /** Enable automatic restoration of values on mount */
+  autoRestore?: boolean;
+  /** Callback triggered when state is restored, useful for react-hook-form reset() */
+  onRestore?: (data: Record<string, string | boolean | string[]>) => void;
+  /** Debounce time in ms to avoid excessive storage writes */
+  debounceTime?: number;
+}
+
+/**
+ * PersistentFormWrapper
+ * 
+ * A wrapper component that automatically saves form input state to browser storage
+ * and restores it across page refreshes or navigations.
+ * 
+ * Works with native HTML forms and provides callbacks for React-based form libraries.
+ */
+export const PersistentFormWrapper: React.FC<PersistentFormWrapperProps> = ({
+  children,
+  persistenceKey,
+  storageType = 'local',
+  formId,
+  autoRestore = true,
+  onRestore,
+  debounceTime = 500,
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const debounceTimer = useRef<NodeJS.Timeout | null>(null);
+
+  // Helper to get storage engine safely (SSR check)
+  const getStorage = useCallback((): Storage | null => {
+    if (typeof window === 'undefined') return null;
+    return storageType === 'local' ? window.localStorage : window.sessionStorage;
+  }, [storageType]);
+
+  /**
+   * Captures the current state of the form
+   */
+  const captureFormState = useCallback(() => {
+    const container = containerRef.current;
+    if (!container) return null;
+
+    const form = formId 
+      ? (container.querySelector(`#${formId}`) as HTMLFormElement) 
+      : container.querySelector('form');
+
+    if (!form) return null;
+
+    const formData = new FormData(form);
+    const data: Record<string, any> = {};
+
+    formData.forEach((value, key) => {
+      // Handle multi-value fields (like checkboxes or multiple selects)
+      if (data[key]) {
+        if (Array.isArray(data[key])) {
+          data[key].push(value);
+        } else {
+          data[key] = [data[key], value];
+        }
+      } else {
+        data[key] = value;
+      }
+    });
+
+    // Special handling for checkboxes that are NOT checked (they don't show up in FormData)
+    const checkboxes = form.querySelectorAll('input[type="checkbox"]');
+    checkboxes.forEach((cb: any) => {
+      if (!cb.checked && !data[cb.name]) {
+        data[cb.name] = false;
+      } else if (cb.checked && !Array.isArray(data[cb.name])) {
+        // Ensure singular checkboxes are booleans if they don't have a value set
+        if (!cb.getAttribute('value') || cb.getAttribute('value') === 'on') {
+            data[cb.name] = true;
+        }
+      }
+    });
+
+    return data;
+  }, [formId]);
+
+  /**
+   * Restores state to the DOM elements
+   */
+  const restoreDOMState = useCallback((data: Record<string, any>) => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const form = formId 
+      ? (container.querySelector(`#${formId}`) as HTMLFormElement) 
+      : container.querySelector('form');
+
+    if (!form) return;
+
+    Object.entries(data).forEach(([name, value]) => {
+      const elements = form.elements.namedItem(name);
+      if (!elements) return;
+
+      if (elements instanceof HTMLInputElement) {
+        if (elements.type === 'checkbox') {
+          elements.checked = Boolean(value);
+        } else if (elements.type === 'radio') {
+            if (elements.value === String(value)) elements.checked = true;
+        } else {
+          elements.value = String(value);
+        }
+      } else if (elements instanceof RadioNodeList) {
+          // Handle radio groups or multiple checkboxes with same name
+          const nodeList = elements as unknown as NodeListOf<HTMLInputElement>;
+          nodeList.forEach((el) => {
+              if (el.type === 'radio') {
+                  el.checked = el.value === String(value);
+              } else if (el.type === 'checkbox') {
+                  if (Array.isArray(value)) {
+                      el.checked = value.includes(el.value);
+                  } else {
+                      el.checked = Boolean(value);
+                  }
+              }
+          });
+      } else if (elements instanceof HTMLTextAreaElement || elements instanceof HTMLSelectElement) {
+          elements.value = String(value);
+      }
+    });
+  }, [formId]);
+
+  /**
+   * Persist current state to storage
+   */
+  const persistState = useCallback(() => {
+    const data = captureFormState();
+    if (!data) return;
+
+    const storage = getStorage();
+    if (storage) {
+      storage.setItem(persistenceKey, JSON.stringify(data));
+    }
+  }, [captureFormState, getStorage, persistenceKey]);
+
+  // Handle restoration on mount
+  useEffect(() => {
+    if (!autoRestore) return;
+
+    const storage = getStorage();
+    if (!storage) return;
+
+    const saved = storage.getItem(persistenceKey);
+    if (saved) {
+      try {
+        const parsedData = JSON.parse(saved);
+        
+        // Use callback if provided
+        if (onRestore) {
+          onRestore(parsedData);
+        } else {
+          // Fallback to direct DOM manipulation
+          // Wait a tick for children to be fully rendered
+          const timer = setTimeout(() => {
+            restoreDOMState(parsedData);
+          }, 0);
+          return () => clearTimeout(timer);
+        }
+      } catch (err) {
+        console.error(`Error restoring form state for key "${persistenceKey}":`, err);
+      }
+    }
+  }, [autoRestore, getStorage, persistenceKey, onRestore, restoreDOMState]);
+
+  // Handle captures on input
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const handleInput = () => {
+      if (debounceTimer.current) clearTimeout(debounceTimer.current);
+      
+      debounceTimer.current = setTimeout(() => {
+        persistState();
+      }, debounceTime);
+    };
+
+    container.addEventListener('input', handleInput);
+    container.addEventListener('change', handleInput);
+
+    return () => {
+      container.removeEventListener('input', handleInput);
+      container.removeEventListener('change', handleInput);
+      if (debounceTimer.current) clearTimeout(debounceTimer.current);
+    };
+  }, [debounceTime, persistState]);
+
+  return (
+    <div 
+      ref={containerRef} 
+      className="persistent-form-wrapper"
+      data-persistence-key={persistenceKey}
+    >
+      {children}
+    </div>
+  );
+};

app/frontend/components/forms/index.ts

@@ -19,3 +19,4 @@ export * from './exampleSchemas';
 export { default as ErrorSummary } from './ErrorSummary';
 
 export { default as CreateEventForm } from './CreateEventForm';
+export { PersistentFormWrapper } from './PersistentFormWrapper';

contract/README.md

@@ -12,6 +12,9 @@ contract/
 ├── ticket_contract/          # Soulbound ticket system
 ├── escrow_contract/         # Secure escrow services
 ├── multisig_wallet_contract/ # Multi-signature wallet
+├── dutch_auction_contract/  # Dutch auction for tickets
+├── zk_ticket_contract/      # Zero-knowledge ticketing
+├── cross_contract_contract/ # Cross-contract operations
 ├── contracts/               # Integration layer
 └── test/                    # Testing utilities
 ```
@@ -66,6 +69,40 @@ contract/
 
 **Dependencies**: `gathera-common`
 
+### 💰 `dutch_auction_contract`
+
+**Purpose**: Implements a Dutch auction mechanism for ticket sales, ensuring fair price discovery.
+
+**Key Features**:
+- Linear price decay
+- Real-time bidding
+- Automatic fulfillment
+- Integration with `ticket_contract`
+
+**Dependencies**: `gathera-common`, `ticket_contract`
+
+### 🕶️ `zk_ticket_contract`
+
+**Purpose**: Enables privacy-preserving ticket verification using Zero-Knowledge Proofs.
+
+**Key Features**:
+- On-chain ZK verification
+- Private attendance logs
+- Proof of eligibility without revealing identity
+
+**Dependencies**: `gathera-common`
+
+### 🔀 `cross_contract_contract`
+
+**Purpose**: Orchestrates complex operations involving multiple Gathera contracts.
+
+**Key Features**:
+- Atomic multi-contract execution
+- Shared state synchronization
+- Rollback mechanisms for failed multi-step operations
+
+**Dependencies**: All other contracts
+
 ### 🔗 `contracts` (Integration Layer)
 
 **Purpose**: Provides orchestration and unified interfaces for cross-contract operations.
@@ -195,6 +232,30 @@ When contributing to the Gathera contract suite:
 4. **Check Gas Usage**: Verify gas efficiency of changes
 5. **Run CI**: Ensure all tests pass before submitting
 
+## Troubleshooting
+
+### Common Build Issues
+
+- **WASM Target Missing**: Ensure the `wasm32-unknown-unknown` target is installed:
+  ```bash
+  rustup target add wasm32-unknown-unknown
+  ```
+- **Outdated CLI**: If contract deployment fails, update the Soroban CLI:
+  ```bash
+  cargo install --locked soroban-cli
+  ```
+
+### Testing Issues
+
+- **Time-based Proofs Fail**: Some tests depend on network time. Ensure your environment matches the expected time parameters in `test/src/utils.rs`.
+- **Insufficient Gas**: For complex transactions, increase the gas limit in the `soroban contract invoke` flags.
+
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.
+
+---
+
+**Gathera Smart Contract Team** 🛡️
+
+For support, please open an issue in the main repository or contact us on Discord.

contract/common/README.md

@@ -0,0 +1,33 @@
+# Gathera Common Utility Library
+
+The `gathera-common` module provides shared data structures, constants, and utilities used throughout the Gathera smart contract ecosystem.
+
+## Features
+
+- **Standard Types**: Consistent definitions for addresses, ticket IDs, and statuses.
+- **Gas Measurement**: Utility traits and macros for benchmarking contract efficiency.
+- **Errors**: Centralized error mapping for clear cross-contract debugging.
+- **Math Ops**: Safe arithmetic helpers with platform-optimized checks.
+
+## Getting Started
+
+### Prerequisites
+
+- Rust 1.74+
+
+### Building
+
+```bash
+cargo build --release
+```
+
+This is a library crate and should be referenced in other contracts' `Cargo.toml`.
+
+## Dependencies
+
+- `soroban-sdk`: Core Soroban development kit.
+
+## Troubleshooting
+
+- **Symbol Collision**: Ensure all macros are imported with the `gathera_common::` prefix.
+- **Workspace Link Errors**: Verify that the `Cargo.toml` workspace configuration matches the project layout.