Is your feature request related to a problem? Please describe.

Currently, managing addresses in rolod0x requires manual editing in the text editor format or copy-pasting. While fetching from external sources is possible via URL boxes, this functionality is per-section only, not for the entire address book.

For users who maintain large address books organized into sections (e.g., tracking accounts across multiple projects, managing team addresses, security research), the current workflow is tedious and error-prone.

Users often maintain their address lists in spreadsheet tools (CSV files, Google Sheets, Excel) where they can:

• Easily add/remove/edit multiple entries
• Use spreadsheet features like filtering, sorting, and bulk operations
• Collaborate with team members
• Keep additional metadata that may not fit rolod0x's current format

The current workflow forces users to:

1. Manually convert spreadsheet data to rolod0x text format
2. Copy-paste into the text editor
3. Fix any format errors
4. Repeat the entire process when they need to update their external spreadsheet

This creates friction that discourages users from maintaining their address books in both places, leading to data silos.

While the existing JSON export functionality is helpful for backup purposes, JSON is not compatible with common spreadsheet editing tools, limiting its usefulness for bulk address management workflows.

Describe the solution you'd like

Add CSV import and export capabilities that make it trivial to synchronize address data between rolod0x and external spreadsheet tools.

CSV Structure

While the sections feature in rolod0x is excellent for organization, it currently creates friction for simple bulk import and export operations. This feature request proposes adding CSV import/export functionality to complement the existing JSON import/export, providing a spreadsheet-friendly format for bulk address management.

Support a CSV format with the following columns:

Required columns:

• address - Ethereum address (0x-prefixed, 40 hex characters)
• label - Human-readable label for the address

Optional columns:

• group or section - Which section to place the address in. (This is title in the json.) This would enable organization into different sections in the Rolod0x UI.

Nice-to-have columns:

• type - Address type (e.g., "eoa", "contract", "safe", "exchange", "personal")
• chains - Comma-separated list of chains where this address is deployed
• note or comment - Additional notes about the address

Example CSV:

address,label,group,type,chains,note
0x1803982898d6a8E832177Fca8fD763B9060C3050,Vitalik,Personal,eoa,ethereum,Ethereum Foundation
0xe3D82337F79306712477b642EF59B75dD62eF109,My Safe,Work,contract,"ethereum,polygon,arbitrum",Multi-sig wallet
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb,Exchange Deposit,Exchanges,eoa,ethereum,Coinbase deposit address

Export Functionality

1. Export Current Section - Export addresses from the currently selected section to CSV
2. Export All Sections - Export all addresses from all sections, with a section column indicating which section each address belongs to
3. Export Options:
   • Include/exclude empty optional fields
   • Choose delimiter (comma, semicolon, tab)
   • Option to include only basic fields (address, label) for compatibility with current format

UI Location: Add export buttons to the SectionToolbar component, next to existing import options.

Import Functionality

1. Import from CSV file - File picker to select local CSV file, or one online
2. Import from CSV text - Paste CSV text directly into a dialog
3. Column Mapping UI:
   • Auto-detect standard column names (address, label, group, etc.)
   • Allow manual mapping if column names don't match
   • Preview first 5-10 rows with mapped columns
   • Show validation warnings/errors before import
4. Import Options:
   • Choose target section based on group/section column, or create new sections
   • Duplicate handling:
     • Skip duplicates (keep existing)
     • Update duplicates (overwrite with CSV data)
     • Append as new entry (create duplicate label with " / " separator, following current behavior)
   • Validate addresses (ERC-55 checksum)
   • Show summary before confirming import (X addresses to add, Y duplicates found, Z errors)

UI Location: A top-level UI area for managing the entire address book would be ideal. Currently, there is no header area above all sections—only individual section headings. Adding a global import/export control panel would enable users to work with their entire address book at once, while still maintaining the option for per-section operations.

Data Mapping to Current Format

The CSV import should map to rolod0x's current text format:

• address → Address field (with ERC-55 validation)
• label → Label field
• note/comment → Appended as comment (after //)
• type, chains → Could be appended to comment as structured data, e.g., // type: eoa, chains: ethereum,polygon
• group/section → Determines which section the address is added to (create section if it doesn't exist)

Example mapping:

CSV row: 0x1803982898d6a8E832177Fca8fD763B9060C3050,Vitalik,Personal,eoa,ethereum,Ethereum Foundation
↓
rolod0x format: 0x1803982898d6a8E832177Fca8fD763B9060C3050 Vitalik // Ethereum Foundation (type: eoa, chains: ethereum)
Section: Personal

Technical Implementation Considerations

1. CSV Parsing: Use a robust CSV parser like Papa Parse to handle:

   • Various delimiters
   • Quoted fields
   • Escaped characters
   • Large files (streaming for performance)

2. Validation:

   • Address format and checksum validation (reuse existing parser logic from src/shared/parser.ts)
   • Required field validation
   • Duplicate detection across sections

3. Error Handling:

   • Clear error messages with row numbers
   • Allow partial imports (skip invalid rows, import valid ones)
   • Export error report as CSV for users to fix and re-import

4. UI/UX:

   • Show progress indicator for large imports
   • Provide undo capability (or confirmation dialog with preview)
   • Remember last used import/export settings

Describe alternatives you've considered

Alternative 1: External Conversion Tool

Create a separate CLI tool or web app that converts between CSV and rolod0x text format.

Pros: Doesn't add complexity to main extension
Cons: Extra step in workflow, requires context switching, harder to discover

Alternative 2: Enhanced Text Format

Extend the current text format to support additional metadata in structured comments.

Example:

0x1803982898d6a8E832177Fca8fD763B9060C3050 Vitalik // note: Ethereum Foundation | type: eoa | chains: ethereum

Pros: Maintains single text-based format
Cons: Still doesn't solve the spreadsheet integration problem, harder to edit in bulk

Alternative 3: API/URL-based Sync

Allow users to specify a URL pointing to a CSV file (similar to current URL fetch for text format).

Pros: Enables live sync with Google Sheets (via publish to web), supports collaboration
Cons: More complex, security considerations, requires stable hosting

Alternative 4: JSON Import/Export

Use JSON instead of CSV for structured data with better type support.

Pros: Better for nested data, type safety
Cons: Not compatible with spreadsheet tools, higher barrier for non-technical users

Additional context

Use Cases

1. Security Researcher (from user feedback):

   • Tracks 100+ addresses across multiple security audits
   • Manages addresses in Google Sheets with team members
   • Needs to categorize by project, address type, deployed chains
   • Currently writing custom scripts to convert between formats

2. DeFi Power User:

   • Maintains personal address book with 50+ protocols and team members
   • Uses Excel to track which addresses are on which chains
   • Wants to quickly add new protocol addresses from public lists

3. Organization/DAO:

   • Maintains shared address book for team (multisigs, contributor addresses, partner addresses)
   • Collaborates in Google Sheets
   • Wants each team member to import the latest address book into their extension

Current Codebase Structure (for implementation)

Relevant files to modify:

• /src/pages/options/AddressesSettings/SectionToolbar.tsx - Add import/export buttons
• /src/shared/parser.ts - Extend to support CSV parsing (or create new csv-parser.ts)
• /src/shared/types.ts - May need to extend types to support additional metadata
• /src/shared/options-storage.ts - Section management for group/section mapping

Current data flow:

1. Text format → Parser (parser.ts) → LabelMap (Map<Address, LabelComment>)
2. LabelMap → Stored in sections as text strings (options-storage.ts)
3. UI displays sections in CodeMirror editor (CodeMirrorTextAddresses.tsx)

Related Issues

This feature would complement:

• Any existing issues about bulk address management
• Any issues about collaboration features
• Any issues about supporting additional metadata per address

Privacy Considerations

Since rolod0x is a privacy-focused tool:

• CSV import/export should happen entirely client-side
• No data sent to external servers
• Files saved/loaded using browser's file picker API
• Consider adding encryption option for exported CSV files (password-protected)

Backward Compatibility

• Existing text format should continue to work
• CSV is an additional import/export option, not a replacement
• Users can continue using current workflow without any changes
• If CSV adds metadata fields, they should gracefully degrade to comments in text format

Implementation Priority Suggestion

Phase 1 (MVP):

• Basic CSV export (address, label, section columns only)
• Basic CSV import with auto-mapping
• Simple duplicate handling (skip or error)

Phase 2 (Enhanced):

• Column mapping UI for custom CSV formats
• Additional metadata fields (type, chains, note)
• Advanced duplicate handling options
• Import preview

Phase 3 (Advanced):

• URL-based CSV sync (fetch from Google Sheets public URL)
• Scheduled auto-refresh from URL
• Export/import presets
• Validation rules configuration