feat: create v2-prep branch with comprehensive planning

Restructured project for V2 refactor:

**Structure Changes:**
- Moved all V1 code to orig/ folder (preserved with git mv)
- Created docs/planning/ directory
- Added orig/README_V1.md explaining V1 preservation

**Planning Documents:**
- 00_V2_MASTER_PLAN.md: Complete architecture overview
  - Executive summary of critical V1 issues
  - High-level component architecture diagrams
  - 5-phase implementation roadmap
  - Success metrics and risk mitigation

- 07_TASK_BREAKDOWN.md: Atomic task breakdown
  - 99+ hours of detailed tasks
  - Every task < 2 hours (atomic)
  - Clear dependencies and success criteria
  - Organized by implementation phase

**V2 Key Improvements:**
- Per-exchange parsers (factory pattern)
- Multi-layer strict validation
- Multi-index pool cache
- Background validation pipeline
- Comprehensive observability

**Critical Issues Addressed:**
- Zero address tokens (strict validation + cache enrichment)
- Parsing accuracy (protocol-specific parsers)
- No audit trail (background validation channel)
- Inefficient lookups (multi-index cache)
- Stats disconnection (event-driven metrics)

Next Steps:
1. Review planning documents
2. Begin Phase 1: Foundation (P1-001 through P1-010)
3. Implement parsers in Phase 2
4. Build cache system in Phase 3
5. Add validation pipeline in Phase 4
6. Migrate and test in Phase 5

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

orig/pkg/lifecycle/error_enrichment.go

@@ -0,0 +1,109 @@
+package lifecycle
+
+import (
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+var txHashPattern = regexp.MustCompile(`0x[a-fA-F0-9]{64}`)
+
+type RecordedError struct {
+	Err    error
+	TxHash string
+}
+
+func (re RecordedError) Error() string {
+	if re.Err == nil {
+		return ""
+	}
+	return re.Err.Error()
+}
+
+func enrichErrorWithTxHash(message string, err error, attrs []interface{}) (error, string, []interface{}) {
+	txHash, attrsWithTx := ensureTxHash(attrs, err)
+	wrapped := fmt.Errorf("%s: %w", message, err)
+	if txHash != "" {
+		wrapped = fmt.Errorf("%s [tx_hash=%s]: %w", message, txHash, err)
+	}
+	return wrapped, txHash, attrsWithTx
+}
+
+func ensureTxHash(attrs []interface{}, err error) (string, []interface{}) {
+	txHash := extractTxHashFromAttrs(attrs)
+	if txHash == "" {
+		txHash = extractTxHashFromError(err)
+	}
+
+	if txHash == "" {
+		return "", attrs
+	}
+
+	hasTxAttr := false
+	for i := 0; i+1 < len(attrs); i += 2 {
+		key, ok := attrs[i].(string)
+		if !ok {
+			continue
+		}
+		if key == "tx_hash" || key == "transaction_hash" || key == "tx" {
+			hasTxAttr = true
+			break
+		}
+	}
+
+	if !hasTxAttr {
+		attrs = append(attrs, "tx_hash", txHash)
+	}
+
+	return txHash, attrs
+}
+
+func extractTxHashFromAttrs(attrs []interface{}) string {
+	for i := 0; i+1 < len(attrs); i += 2 {
+		key, ok := attrs[i].(string)
+		if !ok {
+			continue
+		}
+		if key == "tx_hash" || key == "transaction_hash" || key == "tx" {
+			if value, ok := attrs[i+1].(string); ok && isValidTxHash(value) {
+				return strings.ToLower(value)
+			}
+		}
+	}
+	return ""
+}
+
+func extractTxHashFromError(err error) string {
+	for err != nil {
+		if match := txHashPattern.FindString(err.Error()); match != "" {
+			return strings.ToLower(match)
+		}
+		err = errors.Unwrap(err)
+	}
+	return ""
+}
+
+func isValidTxHash(value string) bool {
+	if value == "" {
+		return false
+	}
+	if len(value) != 66 {
+		return false
+	}
+	if !strings.HasPrefix(value, "0x") {
+		return false
+	}
+	for _, r := range value[2:] {
+		if !isHexChar(r) {
+			return false
+		}
+	}
+	return true
+}
+
+func isHexChar(r rune) bool {
+	return (r >= '0' && r <= '9') ||
+		(r >= 'a' && r <= 'f') ||
+		(r >= 'A' && r <= 'F')
+}