cake-tech · T145 · Aug 29, 2025
diff --git a/cw_bitcoin/README.md b/cw_bitcoin/README.md
@@ -1,14 +1,40 @@
 # cw_bitcoin
 
-A new Flutter package project.
+Bitcoin-family Electrum wallet implementation used by Cake Wallet (BTC, LTC and derivatives).
 
-## Getting Started
+## Features
 
-This project is a starting point for a Dart
-[package](https://flutter.dev/developing-packages/),
-a library module containing code that can be shared easily across
-multiple Flutter or Dart projects.
+- Electrum client and wallet with address/UTXO management and snapshots.
+- Derivation via BIP‑39; receive/change chains with per-coin configs.
+- Create/sign/broadcast transactions; PSBT helpers and payjoin support.
+- Transaction history, priorities, and size-based fee calculations.
+- Hardware wallet support for BTC/LTC.
 
-For help getting started with Flutter, view our 
-[online documentation](https://flutter.dev/docs), which offers tutorials, 
-samples, guidance on mobile development, and a full API reference.
+## Getting started
+
+Use the module via app services (see `bitcoin_wallet_service.dart`, `litecoin_wallet_service.dart`). Ensure Electrum nodes are configured for the target coin.
+
+```dart
+final wallet = await BitcoinWallet.create(
+  mnemonic: '...',
+  password: 'secret',
+  walletInfo: walletInfo,
+  unspentCoinsInfo: unspentCoinsBox,
+  encryptionFileUtils: encryption,
+);
+```
+
+## Usage
+
+Send BTC with medium priority:
+
+```dart
+final feeRate = wallet.feeRate(BitcoinTransactionPriority.medium);
+final pending = await wallet.createTransaction(
+  outputs: [BitcoinTransactionOutput(address: 'bc1...', amount: 50000)],
+  feeRate: feeRate,
+);
+final txHash = await pending.commit();
+```
+
+See `lib/` for wallet/services, PSBT, and payjoin utilities.
diff --git a/cw_bitcoin_cash/README.md b/cw_bitcoin_cash/README.md
@@ -1,39 +1,49 @@
-<!--
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
+## cw_bitcoin_cash
 
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/guides/libraries/writing-package-pages).
+Bitcoin Cash wallet module using the shared Electrum implementation configured for BCH mainnet. Includes CashAddr handling and BCH-specific fee/priority presets.
 
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-library-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/developing-packages).
--->
+### Features
 
-TODO: Put a short description of the package here that helps potential users
-know whether this package might be useful for them.
+- Derive keys via BIP‑39; maintain receive/change address chains.
+- Load/save snapshots of addresses, indices, and balances.
+- Electrum connectivity and UTXO management.
+- Create/sign/broadcast BCH transactions; calculate size-based fees by priority.
+- CashAddr compatibility for addresses; migration of legacy snapshots.
+- Message signing and verification.
 
-## Features
+### Getting started
 
-TODO: List what your package can do. Maybe include images, gifs, or videos.
+Create/open via the app’s wallet service using `WalletType.bitcoinCash`. Ensure BCH Electrum nodes are configured.
 
-## Getting started
-
-TODO: List prerequisites and provide or point to information on how to
-start using the package.
+```dart
+final wallet = await BitcoinCashWallet.create(
+  mnemonic: '...',
+  password: 'secret',
+  walletInfo: walletInfo,
+  unspentCoinsInfo: unspentCoinsBox,
+  encryptionFileUtils: encryption,
+);
+```
 
-## Usage
+### Usage
 
-TODO: Include short and useful examples for package users. Add longer examples
-to `/example` folder.
+Fee calculation and send:
 
 ```dart
-const like = 'sample';
+final feeRate = wallet.feeRate(BitcoinCashTransactionPriority.medium);
+final pending = await wallet.createTransaction(
+  outputs: [
+    BitcoinTransactionOutput(
+      address: 'bitcoincash:qq...',
+      amount: 10000, // satoshis
+    ),
+  ],
+  feeRate: feeRate,
+);
+final txHash = await pending.commit();
 ```
 
-## Additional information
+### Additional information
 
-TODO: Tell users more about the package: where to find more information, how to
-contribute to the package, how to file issues, what response they can expect
-from the package authors, and more.
+- See `lib/src/` for: `BitcoinCashWallet`, `BitcoinCashWalletAddresses`, and helpers in `bitcoin_cash_base.dart`.
+- Snapshot migration and CashAddr normalization are handled during open.
diff --git a/cw_core/README.md b/cw_core/README.md
@@ -1,14 +1,22 @@
 # cw_core
 
-A new Flutter package project.
+Core abstractions and shared types for Cake Wallet modules.
 
-## Getting Started
+## Highlights
 
-This project is a starting point for a Dart
-[package](https://flutter.dev/developing-packages/),
-a library module containing code that can be shared easily across
-multiple Flutter or Dart projects.
+- Wallet primitives: `WalletBase`, `WalletService`, `WalletInfo`, `WalletAddresses`.
+- Transaction primitives: `TransactionInfo`, `TransactionHistoryBase`, directions/priorities.
+- Currency models: `CryptoCurrency`, `Erc20Token`, SPL/TRON token types.
+- Persistence helpers: Hive adapters, path helpers (`pathForWallet`), encrypted storage utils.
+- Node representation (`Node`) and sync status types.
 
-For help getting started with Flutter, view our 
-[online documentation](https://flutter.dev/docs), which offers tutorials, 
-samples, guidance on mobile development, and a full API reference.
+## Usage
+
+Extend `WalletBase` for a new chain and provide a `WalletService` implementation to create/open/restore wallets.
+
+```dart
+class MyChainWallet extends WalletBase<MyBalance, MyHistory, MyTxInfo> { /* ... */ }
+class MyChainWalletService extends WalletService<New, FromSeed, FromKeys, FromHardware> { /* ... */ }
+```
+
+See the chain modules (e.g., `cw_bitcoin`, `cw_evm`) for complete examples.
diff --git a/cw_decred/README.md b/cw_decred/README.md
@@ -1,3 +1,47 @@
 # cw_decred
 
-TODO: Fill this out.
+Decred wallet module that bridges to the native `libdcrwallet` via FFI. Provides high‑level methods to create/load wallets, sync, query balances/transactions, build and broadcast transactions, and sign/verify messages.
+
+## Features
+
+- FFI bindings to `libdcrwallet` with an isolate‑based request/response model.
+- Initialize, create, load, close wallets; watch‑only creation.
+- Start sync with optional peer list; query sync status and best block.
+- Query balances, list transactions and unspents, rescan from height.
+- Create signed transactions and broadcast raw transactions.
+- Export wallet seed; change wallet password.
+- Address management (new external address, default pubkey, address lists).
+- Message signing and verification.
+
+## Getting started
+
+Ensure the platform library is available:
+
+- Android/Linux: `libdcrwallet.so`
+- Apple: embedded `cw_decred.framework/cw_decred`
+
+Initialize and load a wallet:
+
+```dart
+final lib = await Libwallet.spawn();
+await lib.initLibdcrwallet('', 'info');
+await lib.loadWallet(jsonEncode({ /* libdcrwallet config */ }));
+await lib.startSync('wallet.db', '');
+final status = await lib.syncStatus('wallet.db');
+```
+
+## Usage
+
+Create, sign, and broadcast a transaction:
+
+```dart
+final signed = await lib.createSignedTransaction('wallet.db', jsonEncode({
+  // inputs/outputs and policy for libdcrwallet
+}));
+final txid = await lib.sendRawTransaction('wallet.db', signed);
+```
+
+## Additional information
+
+- See `lib/api/` for the isolate wrapper (`libdcrwallet.dart`) and low‑level bindings.
+- Errors are surfaced via the `PayloadResult` struct; some calls support `throwOnError` in higher‑level wrappers.
diff --git a/cw_dogecoin/README.md b/cw_dogecoin/README.md
@@ -1,39 +1,48 @@
-<!--
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
+## cw_dogecoin
 
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/tools/pub/writing-package-pages).
+Dogecoin wallet module using the shared Bitcoin Electrum implementation (`cw_bitcoin`) configured for Dogecoin mainnet.
 
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/to/develop-packages).
--->
+### Features
 
-TODO: Put a short description of the package here that helps potential users
-know whether this package might be useful for them.
+- Derive keys via BIP‑39; Dogecoin HD paths using `bitcoin_base`.
+- Connect to Electrum nodes; maintain address sets and UTXOs.
+- Create/sign/broadcast DOGE transactions with configurable fee rate.
+- Address book and index management (receive/change, auto-generate settings).
+- Message signing and verification.
 
-## Features
+### Getting started
 
-TODO: List what your package can do. Maybe include images, gifs, or videos.
+Create/open via `DogecoinWalletService` in the app using `WalletType.dogecoin`. Ensure Electrum nodes are configured for Dogecoin.
 
-## Getting started
-
-TODO: List prerequisites and provide or point to information on how to
-start using the package.
+```dart
+final wallet = await DogeCoinWallet.create(
+  mnemonic: '...',
+  password: 'secret',
+  walletInfo: walletInfo,
+  unspentCoinsInfo: unspentCoinsBox,
+  encryptionFileUtils: encryption,
+);
+```
 
-## Usage
+### Usage
 
-TODO: Include short and useful examples for package users. Add longer examples
-to `/example` folder.
+Estimate fee and send:
 
 ```dart
-const like = 'sample';
+final feeRate = wallet.feeRate(BitcoinCashTransactionPriority.medium); // example priority mapping
+final pending = await wallet.createTransaction(
+  outputs: [
+    BitcoinTransactionOutput(
+      address: 'D...',
+      amount: 1 * 100000000, // 1 DOGE in koinu
+    ),
+  ],
+  feeRate: feeRate,
+);
+final txHash = await pending.commit();
 ```
 
-## Additional information
+### Additional information
 
-TODO: Tell users more about the package: where to find more information, how to
-contribute to the package, how to file issues, what response they can expect
-from the package authors, and more.
+- See `lib/src/` for classes: `DogeCoinWallet`, `DogeCoinWalletAddresses`.
+- Relies on core Electrum features in `cw_bitcoin` for UTXO selection and persistence.
diff --git a/cw_ethereum/README.md b/cw_ethereum/README.md
@@ -1,39 +1,64 @@
-<!--
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
+## cw_ethereum
 
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/guides/libraries/writing-package-pages).
+Ethereum wallet module built on `cw_evm`. Supports native ETH and ERC‑20 tokens, with history fetched via Etherscan.
 
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-library-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/developing-packages).
--->
+### Features
 
-TODO: Put a short description of the package here that helps potential users
-know whether this package might be useful for them.
+- EVM client specialized for Ethereum mainnet (chainId 1).
+- Default ERC‑20 token list and wallet‑scoped token storage/migration.
+- History via Etherscan v2 API (external, internal, and token transfers).
+- EIP‑1559 fee support; gas estimation per transaction intent.
+- Create/sign native and ERC‑20 transfers; approvals; broadcast.
+- Manage ERC‑20 tokens and balances; metadata lookup when needed.
+- Message signing and verification.
+- Node health checks for native and USDC token balance.
 
-## Features
+### Getting started
 
-TODO: List what your package can do. Maybe include images, gifs, or videos.
+Add shared EVM secrets (see `cw_evm` README):
 
-## Getting started
+```dart
+// cw_evm/lib/.secrets.g.dart   (DO NOT COMMIT)
+const String etherScanApiKey = 'YOUR_ETHERSCAN_KEY';
+const String nowNodesApiKey = 'YOUR_NOWNODES_KEY'; // if using eth.nownodes.io
+const String moralisApiKey = 'YOUR_MORALIS_KEY';   // optional
+```
+
+Connect and sync:
 
-TODO: List prerequisites and provide or point to information on how to
-start using the package.
+```dart
+final service = EthereumWalletService(walletInfoBox, true, client: EthereumClient());
+final wallet = await service.create(EVMChainNewWalletCredentials(name: 'My ETH', password: 'secret'));
+await wallet.connectToNode(node: Node(uriRaw: 'eth.llamarpc.com', isSSL: true));
+await wallet.startSync();
+```
 
-## Usage
+### Usage
+
+Send ETH:
+
+```dart
+final pending = await wallet.createTransaction(
+  EVMChainTransactionCredentials.single(
+    address: '0x...',
+    cryptoAmount: '0.05',
+    currency: CryptoCurrency.eth,
+    priority: EVMChainTransactionPriority.medium,
+  ),
+);
+final hash = await pending.commit();
+```
 
-TODO: Include short and useful examples for package users. Add longer examples
-to `/example` folder.
+Add an ERC‑20 token and refresh balance:
 
 ```dart
-const like = 'sample';
+final token = await wallet.getErc20Token('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', 'eth'); // USDC
+if (token != null) {
+  await wallet.addErc20Token(token);
+}
 ```
 
-## Additional information
+### Additional information
 
-TODO: Tell users more about the package: where to find more information, how to
-contribute to the package, how to file issues, what response they can expect
-from the package authors, and more.
+- Toggle Etherscan usage via shared preferences key `use_etherscan`.
+- See `lib/` for APIs: `EthereumClient`, `EthereumWallet`, `EthereumWalletService`.