feat(storage): add Account Alias Storage plugin

[pasevin]

Summary

Add the Account Alias Storage plugin to @openzeppelin/ui-storage, providing address-to-alias mapping for blockchain addresses.

• New AliasStorage class with full CRUD operations for address aliases
• Multi-network support - same address can have different aliases per network (using networkId matching NetworkConfig.id)
• Configurable duplicate handling - 'strict', 'warn', or 'allow' modes
• React hook integration via createUseAliasStorage with live reactive updates using useLiveQuery
• Import/export functionality for backup and migration (JSON format)
• Comprehensive error handling with typed error codes (AliasStorageError)
• Full TypeScript support with JSDoc documentation

Key Features

Feature	Description
Core CRUD	save, update, get, delete operations
Address lookup	getByAddress, getByAddressAndNetwork, findByAddress
Alias lookup	getByAlias, findByAlias, resolveAlias, resolveAddress
Bulk operations	bulkSave, bulkDelete, exportJson, importJson
React hooks	Live reactive queries with error handling
Configuration	Duplicate modes, alias length limits, logging options

Example Usage

import { ALIAS_SCHEMA, createAliasStorage, createDexieDatabase } from '@openzeppelin/ui-storage';

const db = createDexieDatabase('MyApp', [{ version: 1, stores: ALIAS_SCHEMA }]);
const aliasStorage = createAliasStorage(db);

await aliasStorage.save({ address: '0x742d35Cc...', alias: 'Treasury' });
const record = await aliasStorage.getByAddress('0x742d35Cc...');
console.log(record?.alias); // 'Treasury'

Test plan

• 208 tests passing (106 for AliasStorage, 28 for React hooks)
• TypeScript strict mode compilation passes
• ESLint passes with no warnings
• Bundle builds successfully (ESM + CJS)
• Performance verified: <1ms lookups with 1000 aliases
• All pre-existing tests continue to pass

[Copilot]

Pull request overview

This PR adds a new Account Alias Storage plugin to @openzeppelin/ui-storage, providing a typed, multi-network alias store for blockchain addresses with React hook integration and import/export support.

Changes:

• Introduces the AliasStorage class, Dexie schema helpers, error types, and configuration options for address-to-alias mappings, including multi-network support and duplicate-mode handling.
• Adds a React hook factory (createUseAliasStorage) and comprehensive Vitest suites for both the core storage class and the React integration, plus test infrastructure based on fake-indexeddb and jsdom.
• Updates storage package exports, README documentation, and changeset metadata to surface the plugin as a first-class part of @openzeppelin/ui-storage.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
specs/002-account-alias-storage/tasks.md	Task breakdown for designing and implementing the alias storage plugin, tests, hooks, and documentation.
specs/002-account-alias-storage/spec.md	Functional and non-functional spec for the alias plugin, including user stories, requirements, error codes, logging, React behavior, and import/export schema.
specs/002-account-alias-storage/research.md	Design decisions and rationale for architecture, schema, duplicate detection, React integration, and network handling.
specs/002-account-alias-storage/quickstart.md	Feature-specific quickstart guide showing how to create the DB, use AliasStorage, and integrate with React.
specs/002-account-alias-storage/plan.md	Implementation plan describing structure, constraints, and constitution checks for the feature.
specs/002-account-alias-storage/data-model.md	Data model definition for AliasRecord, options, Dexie schema, validation rules, error codes, and query patterns.
specs/002-account-alias-storage/contracts/types.ts	Type-level API contract for alias types, options, import/export formats, and error codes at the spec level.
specs/002-account-alias-storage/contracts/alias-storage-api.ts	Spec API contract for AliasStorage, factory, and React hook return type and options.
specs/002-account-alias-storage/contracts/README.md	Brief index of the spec contracts for the alias plugin.
specs/002-account-alias-storage/checklists/requirements.md	High-level requirements completeness checklist for the spec.
specs/002-account-alias-storage/checklists/full-spec.md	Detailed checklist validating that the spec covers scenarios, edge cases, NFRs, dependencies, and API quality.
pnpm-lock.yaml	Adds testing-related dependencies (@testing-library/react, jsdom, updated @babel/runtime, etc.) and locks their resolved versions.
packages/storage/src/plugins/account-alias/types.ts	Runtime alias types (AliasRecord, AliasInput, AliasUpdate), configuration (AliasStorageOptions, DuplicateMode, LogLevel), import/export types, and DEFAULT_OPTIONS.
packages/storage/src/plugins/account-alias/schema.ts	Dexie schema constants and helpers (ALIAS_SCHEMA, createAliasSchema, getAliasSchema) for the alias table.
packages/storage/src/plugins/account-alias/react.ts	React hook factory createUseAliasStorage, hook return types, error-handling wrapper, file import/export helpers, and getAliasStorageInstance.
packages/storage/src/plugins/account-alias/index.ts	Public plugin entry point re-exporting alias types, errors, schema helpers, storage factory, and React hooks.
packages/storage/src/plugins/account-alias/errors.ts	Alias-specific error codes, human-readable messages, AliasStorageError class, and helper constructors for common error cases.
packages/storage/src/plugins/account-alias/__tests__/setup.ts	Test utilities for alias plugin, including fake-indexeddb setup, logger mocking, and Dexie test DB lifecycle helpers.
packages/storage/src/plugins/account-alias/__tests__/react.test.tsx	Vitest+Testing Library tests for the React hook: creation, live updates, CRUD, error handling, file I/O, and multi-instance behavior.
packages/storage/src/plugins/account-alias/__tests__/AliasStorage.test.ts	Comprehensive tests for AliasStorage covering CRUD, config, lookups, multi-network behavior, delete/list, bulk ops, and import/export.
packages/storage/src/plugins/account-alias/AliasStorage.ts	Core AliasStorage implementation with validation, duplicate handling, multi-network support, CRUD, list/count, bulk ops, import/export, quota handling, and logging.
packages/storage/src/index.ts	Wires the alias plugin into the root storage package exports (types, constants, storage class, factories, errors, and React hooks).
packages/storage/package.json	Adds dev-time dependencies needed for the new tests (@testing-library/react, @types/react, jsdom).
packages/storage/README.md	Extends package README with an “Account Alias Plugin” section explaining setup, usage, React integration, import/export, and error handling.
.changeset/account-alias-storage-plugin.md	Changeset entry declaring a minor release for @openzeppelin/ui-storage and summarizing the new plugin’s capabilities.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.