Initial Commit

openspec/changes/enterprise-cryptocurrency/tasks.md

@@ -0,0 +1,96 @@
+# Tasks: enterprise-cryptocurrency
+
+**Change ID**: enterprise-cryptocurrency
+**Package**: `@suaveplan/cryptocurrency`
+**Target path**: `finance/crypto/cryptocurrency`
+**Prerequisites on Verdaccio**: `zod`, `tslib`
+
+---
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Scaffold
+
+- [ ] Create full directory tree per `proposal.md`.
+- [ ] `package.json` at `0.1.0`, `"sideEffects": false`, exports `"."` + per-feature subpaths + `"./chains/testnet-data"`.
+- [ ] Deps: `zod catalog:forms`, `tslib catalog:build`. No workspace runtime deps.
+- [ ] DevDeps: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `fast-check catalog:testing`, `mitata catalog:testing`, `@suaveplan/testing workspace:^`.
+- [ ] `tsconfig.json` extending `library.json`; `vitest.config.ts` with `createTestConfig()`.
+- [ ] Scripts: `lint`, `typecheck`, `test`, `test:coverage`, `build`, `bench`, `docs:check`.
+
+## 2. Error hierarchy
+
+- [ ] Implement `CryptoError`, `UnknownChainError`, `InvalidAddressError`, `InvalidTxHashError`, `UnsupportedUnitError` in `src/errors/crypto-error/crypto-error.ts`.
+- [ ] Mirror `@suaveplan/error` shape (`.code`, `.message`, `.cause`) without importing it.
+- [ ] Write `crypto-error.test.ts`: instanceof chain, code discrimination.
+
+## 3. Address validator
+
+- [ ] Implement `validateAddress` and `validateAddressForChain` in `src/address/validator/validator.ts`:
+  - EVM: EIP-55 checksum; hex + 0x prefix + 40 chars.
+  - Bitcoin: Base58Check (P2PKH/P2SH) + Bech32 (P2WPKH/P2WSH) + Bech32m (P2TR).
+  - Solana: Base58, 32–44 chars.
+  - Cardano: Bech32 `addr1` prefix.
+  - Others: per-chain regex patterns from `CHAINS` data.
+  - Auto-detect chain when not specified.
+- [ ] Write `validator.test.ts` (≤500 lines): valid + invalid per chain; EIP-55 case sensitivity; auto-detect.
+
+## 4. Chain data + testnet data
+
+- [ ] Implement `src/chains/chain-data/chain-data.ts` with 15+ mainnet chain entries.
+- [ ] Implement `src/chains/testnet-data/testnet-data.ts` with Sepolia, Holesky, Base Sepolia, Arbitrum Sepolia, OP Sepolia.
+- [ ] `src/chains/chain-registry/chain-registry.ts`: `MemoryChainRegistry` with add/remove/list.
+- [ ] `src/chains/registry/registry.ts`: pure getter helpers using global registry.
+- [ ] Write tests for all chain registry operations.
+
+## 5. Gas estimators
+
+- [ ] Implement EIP-1559 helpers in `src/gas/gas-estimator/gas-estimator.ts`.
+- [ ] Implement EIP-4844 blob-gas helpers in `src/gas/blob-gas-estimator/blob-gas-estimator.ts`:
+  - `calculateBlobGasPrice(excessBlobGas)`: `MIN_BLOB_GWEI_PER_GAS * e^(excessBlobGas / BLOB_GAS_UPDATE_FRACTION)`.
+  - `estimateBlobTxCost(params)`: include blob-fee component.
+- [ ] Write tests against known EIP-4844 spec test vectors.
+
+## 6. Tokens
+
+- [ ] `src/tokens/token-data/token-data.ts`: common ERC-20 + native tokens.
+- [ ] `src/tokens/token-registry/token-registry.ts`: `TokenRegistry` with get/register/list.
+- [ ] `formatTokenBalance` with locale option.
+- [ ] Write tests.
+
+## 7. Transaction decode
+
+- [ ] Implement ABI-aware `decodeCalldata` in `src/transaction/tx-decoder/tx-decoder.ts`:
+  - Accept `FunctionSignature` with typed parameters; decode fixed types (uint, int, bool, address, bytes, bytesN) and dynamic types (string, bytes, array).
+  - Keep `decodeTxHash` / `extractSelector` / `lookupSelector` / `KNOWN_SELECTORS` from main.
+- [ ] `src/transaction/selector-resolver/selector-resolver.ts`: `SelectorResolver` interface with injectable async lookup.
+- [ ] Write `tx-decoder.test.ts`: each ABI type decoded correctly against known calldata fixtures.
+
+## 8. Unit converter
+
+- [ ] Implement all unit helpers in `src/units/converter/converter.ts`.
+- [ ] Ensure no float-precision loss for large values; use BigInt throughout for integer types.
+- [ ] Write `converter.test.ts`.
+
+## 9. Property-based + benchmarks
+
+- [ ] `tests/property.test.ts` (fast-check, `{ timeout: 30000 }`):
+  - `etherToWei` / `weiToEther` round-trip for arbitrary ether values (string decimal).
+  - `bitcoinToSatoshi` / `satoshiToBitcoin` round-trip.
+  - `validateAddress(addr).chain` is consistent with `validateAddressForChain(addr, detected)`.
+  - EIP-55 checksum is idempotent.
+- [ ] `src/__benchmarks__/hot-paths.bench.ts`: EIP-55 checksum throughput, bech32 decode, address validation throughput.
+
+## 10. Docs + verify + publish
+
+- [ ] All `.md` files per layout; root `README.md` with chain table, quick-start validation + unit conversion + ABI decode, API table.
+- [ ] `bunx turbo lint --filter=@suaveplan/cryptocurrency` — zero errors.
+- [ ] `bunx turbo typecheck --filter=@suaveplan/cryptocurrency` — zero errors.
+- [ ] `bunx turbo test --filter=@suaveplan/cryptocurrency` — all pass.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/cryptocurrency` — 100%.
+- [ ] `bun scripts/publish.ts --package @suaveplan/cryptocurrency`.
+- [ ] Update `CLAUDE.md`; archive to `openspec/archive/2026-04-24-enterprise-cryptocurrency/`.