suaveplan/openspec/archive/2026-05-17-add-cryptocurrency/tasks.md

# Tasks — cryptocurrency

> Every checkbox MUST reflect work actually done in this change.

## 1. Spec authoring

- [x] 1.1 Read `openspec/AGENTS.md` §0, §0a, §0b, §0c, §6a, §7, §13, §14 end-to-end
- [x] 1.2 Read `../suaveplan/packages/finance/cryptocurrency/src/` — all 8 implementation files + 7 test files
- [x] 1.3 Read `../suaveplan/enterprise/cryptocurrency.md` in full
- [x] 1.4 Read `openspec/archive/2026-05-16-add-seed/` as the closest precedent (universal-tier, error-coded migration)
- [x] 1.5 Draft `proposal.md` with parity checklist, source mapping, affected dependents
- [x] 1.6 Draft `design.md` covering layout, error-code map, EIP-55 algorithm preservation, LoggerLike injection, tier purity
- [x] 1.7 Draft `specs/cryptocurrency/spec.md` in OpenSpec `### Requirement: / #### Scenario:` form
- [x] 1.8 Every requirement carries a `**Verified by:**` line naming concrete planned `it(...)` titles

## 2. Scaffolding

- [x] 2.1 Create `packages/finance/cryptocurrency/` mirroring the database/seed layout
- [x] 2.2 Write `package.json` v0.0.0, `"sideEffects": false`, subpath exports for the 11 modules listed in design.md §2
- [x] 2.3 Wire deps: `@suaveplan/error: workspace:^`, `@suaveplan/types: workspace:^`, `tslib: catalog:build`
- [x] 2.4 Wire devDeps: `@suaveplan/testing: workspace:^`, `@vitest/coverage-istanbul: catalog:testing`, `typescript: catalog:`, `vite: catalog:build`, `vite-plugin-dts: catalog:build`, `vitest: catalog:testing`, `@types/node: catalog:`
- [x] 2.5 Write `tsconfig.json`, `tsconfig.lib.json` extending the repo base
- [x] 2.6 Write `vite.config.ts` (preserveModules build for every subpath export)
- [x] 2.7 Write `vitest.config.ts` (Istanbul, 100/100/100/100 thresholds, forks pool)
- [x] 2.8 Write `tests/setup/polyfills.ts` (empty — universal-tier needs no polyfills)
- [x] 2.9 Write `README.md` (≥ 200 words, required sections per CLAUDE.md docs gate)

## 3. Implementation — types

- [x] 3.1 `src/types/crypto.types.ts` — every public type from upstream preserved verbatim
- [x] 3.2 `src/types/crypto.types.md` — co-located doc per docs-coverage gate

## 4. Implementation — error codes

- [x] 4.1 `src/error-codes/error-codes.ts` — `defineCodes("CRYPTOCURRENCY", [5 codes])` registry, `CryptocurrencyError extends SuaveplanError<CryptocurrencyErrorCode>` with `chainId?` / `currency?` / `unit?` discriminants
- [x] 4.2 `src/error-codes/error-codes.test.ts` — every code reachable via `CryptocurrencyError` construction; cause-chain preservation verified
- [x] 4.3 `src/error-codes/error-codes.md`
- [x] 4.4 `src/error-codes/index.ts` — explicit named re-exports

## 5. Implementation — address validation

- [x] 5.1 `src/address/validator.ts` — `validateAddress`, `validateAddressForChain`, `validateTxHash`, internal positional EIP-55 checksum (preserve upstream behaviour bit-for-bit)
- [x] 5.2 `src/address/validator.test.ts` — port every upstream test case + tier-purity assertion
- [x] 5.3 `src/address/validator.md`
- [x] 5.4 `src/address/index.ts` — explicit named re-exports

## 6. Implementation — chain data + registries

- [x] 6.1 `src/chains/chain-data.ts` — `CHAINS: Record<ChainId, ChainInfo>` with 15 entries (preserve upstream verbatim)
- [x] 6.2 `src/chains/chain-data.test.ts` — assert 15 entries, EVM-id correctness
- [x] 6.3 `src/chains/chain-data.md`
- [x] 6.4 `src/chains/registry.ts` — synchronous getters
- [x] 6.5 `src/chains/registry.test.ts` — port upstream test cases
- [x] 6.6 `src/chains/registry.md`
- [x] 6.7 `src/chains/chain-registry.ts` — `MemoryChainRegistry` + `ChainRegistry`; throws → `CryptocurrencyError({ code: CRYPTOCURRENCY.UNKNOWN_CHAIN, chainId })`; constructor gains optional `LoggerLike`; emits `chain.registered` / `chain.lookup.miss` events
- [x] 6.8 `src/chains/chain-registry.test.ts` — port upstream tests; add `UNKNOWN_CHAIN` rejection test; add LoggerLike recording test; add tier-purity assertion
- [x] 6.9 `src/chains/chain-registry.md`
- [x] 6.10 `src/chains/index.ts` — explicit named re-exports

## 7. Implementation — gas

- [x] 7.1 `src/gas/gas-estimator.ts` — preserve upstream verbatim
- [x] 7.2 `src/gas/gas-estimator.test.ts` — port upstream cases
- [x] 7.3 `src/gas/gas-estimator.md`
- [x] 7.4 `src/gas/index.ts` — explicit named re-exports

## 8. Implementation — tokens

- [x] 8.1 `src/tokens/token-data.ts` — preserve upstream `COMMON_TOKENS` verbatim
- [x] 8.2 `src/tokens/token-data.test.ts` — assert 8 tokens present + shape invariants
- [x] 8.3 `src/tokens/token-data.md`
- [x] 8.4 `src/tokens/token-registry.ts` — preserve `TokenRegistry` + `formatTokenBalance`
- [x] 8.5 `src/tokens/token-registry.test.ts` — port upstream cases
- [x] 8.6 `src/tokens/token-registry.md`
- [x] 8.7 `src/tokens/index.ts` — explicit named re-exports

## 9. Implementation — transaction

- [x] 9.1 `src/transaction/tx-decoder.ts` — preserve upstream verbatim
- [x] 9.2 `src/transaction/tx-decoder.test.ts` — port upstream cases
- [x] 9.3 `src/transaction/tx-decoder.md`
- [x] 9.4 `src/transaction/index.ts` — explicit named re-exports

## 10. Implementation — units

- [x] 10.1 `src/units/converter.ts` — preserve upstream conversion logic; replace plain `throw new Error(...)` with `CryptocurrencyError({ code: CRYPTOCURRENCY.UNKNOWN_CURRENCY | UNKNOWN_UNIT })`
- [x] 10.2 `src/units/converter.test.ts` — port upstream cases + error-code assertions + tier-purity assertion
- [x] 10.3 `src/units/converter.md`
- [x] 10.4 `src/units/index.ts` — explicit named re-exports

## 11. Root barrel & exports test

- [x] 11.1 `src/index.ts` — explicit named re-export of every symbol listed in design.md §2 (no `export *`)
- [x] 11.2 `tests/exports.test.ts` — assert every advertised subpath export resolves at runtime

## 12. Pre-archive gates

- [x] 12.1 `bunx turbo lint --filter=@suaveplan/cryptocurrency` green; zero biome suppressions
- [x] 12.2 `bunx turbo typecheck --filter=@suaveplan/cryptocurrency` green
- [x] 12.3 `bunx turbo test --filter=@suaveplan/cryptocurrency` green; zero `.skip` / `.only` / `it.todo`
- [x] 12.4 `bunx turbo test:coverage --filter=@suaveplan/cryptocurrency` green at 100/100/100/100 (Istanbul)
- [x] 12.5 `bun scripts/openspec-conformance.ts @suaveplan/cryptocurrency` — exit 0
- [x] 12.6 `bunx turbo build --filter=@suaveplan/cryptocurrency` green
- [x] 12.7 `grep -rnE "from ['\"](vitest|bun:test)['\"]" packages/finance/cryptocurrency/src/` → zero matches (rule §11 / §7)
- [x] 12.8 Feature-barrel `export *` scan — zero matches outside exempt forms (rule §6a)
- [x] 12.9 `grep -rnE "from ['\"](node:|bun:|fs|path|stream|net|http|crypto)['\"]" packages/finance/cryptocurrency/src/` → zero matches (tier purity)
- [x] 12.10 Banned-pattern scan zero matches (`@deprecated`, `TODO`, `FIXME`, `ts-ignore`, `ts-expect-error`, `.skip`, `.only`, `any`, `console.log`)
- [x] 12.11 Every `### Requirement` in `specs/cryptocurrency/spec.md` checked off against the implementation
- [x] 12.12 `bun scripts/folder-reorg/generate-manifest.ts` run; `MANIFEST.md` includes `@suaveplan/cryptocurrency`
- [x] 12.13 `STATUS.md` `@suaveplan/cryptocurrency` row flipped from `–` to `✅`
- [x] 12.14 `SUMMARY.md` updated with per-package paragraph

## 13. Fold + archive

- [x] 13.1 Fold `specs/cryptocurrency/spec.md` into `openspec/specs/cryptocurrency/spec.md` (canonical file created here for the first time)
- [x] 13.2 Move `openspec/changes/add-cryptocurrency/` to `openspec/archive/2026-05-17-add-cryptocurrency/`