diff --git a/README.md b/README.md index 904637b0..3f6d42ba 100644 --- a/README.md +++ b/README.md @@ -4,126 +4,91 @@

-# Komodo Defi Framework SDK for Flutter +# Komodo DeFi SDK for Flutter -This is a series of Flutter packages for integrating the [Komodo DeFi Framework](https://komodoplatform.com/en/komodo-defi-framework.html) into Flutter applications. This enhances devex by providing an intuitive abstraction layer and handling all binary/media file fetching, reducing what previously would have taken months to understand the API and build a Flutter dApp with KDF integration into a few days. +Komodo’s Flutter SDK lets you build cross-platform DeFi apps on top of the Komodo DeFi Framework (KDF) with a few lines of code. The SDK provides a high-level, batteries-included developer experience while still exposing the low-level framework and RPC methods when you need them. -See the Komodo DeFi Framework (API) source repository at [KomodoPlatform/komodo-defi-framework](https://github.com/KomodoPlatform/komodo-defi-framework) and view the demo site (source in [example](./example)) project at [https://komodo-playground.web.app](https://komodo-playground.web.app). +- Primary entry point: see `packages/komodo_defi_sdk`. +- Full KDF access: see `packages/komodo_defi_framework`. +- RPC models and namespaces: see `packages/komodo_defi_rpc_methods`. +- Core types: see `packages/komodo_defi_types`. +- Coins metadata utilities: see `packages/komodo_coins`. +- Market data: see `packages/komodo_cex_market_data`. +- UI widgets: see `packages/komodo_ui`. +- Build hooks and artifacts: see `packages/komodo_wallet_build_transformer`. -The recommended entry point ([komodo_defi_sdk](/packages/komodo_defi_sdk/README.md)) is a high-level opinionated library that provides a simple way to build cross-platform Komodo Defi Framework applications (primarily focused on wallets). This repository consists of multiple other child packages in the [packages](./packages) folder, which is orchestrated by the [komodo_defi_sdk](/packages/komodo_defi_sdk/README.md) package. +Supported platforms: Android, iOS, macOS, Windows, Linux, and Web (WASM). -Note: Most of this README focuses on the lower-level `komodo-defi-framework` package and still needs to be updated to focus on the primary package, `komodo_defi_sdk`. +See the Komodo DeFi Framework (API) source at `https://github.com/KomodoPlatform/komodo-defi-framework` and a hosted demo at `https://komodo-playground.web.app`. -This project supports building for macOS (more native platforms coming soon) and the web. KDF can either be run as a local Rust binary or you can connect to a remote instance. 1-Click setup for DigitalOcean and AWS deployment is in progress. +## Quick start (SDK) -From v2.5.0-beta, seed nodes configuration is required for KDF to function properly. The `seednodes` parameter must be specified unless `disable_p2p` is set to true. See the [configuration documentation](https://docs.komodefi.com/komodo-defi-framework/setup/configure-mm2-json/) for more details. +Add the SDK to your app and initialize it: -Use the [komodo_defi_framework](packages/komodo_defi_sdk) package for an unopinionated implementation that gives access to the underlying KDF methods. - -The structure for this repository is inspired by the [Flutter BLoC](https://github.com/felangel/bloc) project. - -This project generally follows the guidelines and high standards set by [Very Good Ventures](https://vgv.dev/). - -TODO: Add a comprehensive README - -TODO: Contribution guidelines and architecture overview +```dart +import 'package:komodo_defi_sdk/komodo_defi_sdk.dart'; + +void main() async { + final sdk = KomodoDefiSdk( + // Local by default; use RemoteConfig to connect to a remote node + host: LocalConfig(https: false, rpcPassword: 'your-secure-password'), + config: const KomodoDefiSdkConfig( + defaultAssets: {'KMD', 'BTC', 'ETH'}, + ), + ); + + await sdk.initialize(); + + // Register or sign in + await sdk.auth.register(walletName: 'my_wallet', password: 'strong-pass'); + + // Activate assets and get a balance + final btc = sdk.assets.findAssetsByConfigId('BTC').first; + await sdk.assets.activateAsset(btc).last; + final balance = await sdk.balances.getBalance(btc.id); + print('BTC balance: ${balance.total}'); + + // Direct RPC access when needed + final myKmd = await sdk.client.rpc.wallet.myBalance(coin: 'KMD'); + print('KMD: ${myKmd.balance}'); +} +``` -## Example +## Architecture overview -Below is an extract from the [example project](https://github.com/KomodoPlatform/komodo-defi-sdk-flutter/blob/dev/example/lib/main.dart) showing the straightforward integration. Note that this is for the [komodo_defi_framework](packages/komodo_defi_framework), and the [komodo_defi_sdk](/packages/komodo_defi_sdk/README.md) will provide a higher-layer abstraction. +- `komodo_defi_sdk`: High-level orchestration (auth, assets, balances, tx history, withdrawals, signing, market data). +- `komodo_defi_framework`: Platform client for KDF with multiple backends (native/WASM/local process, remote). Provides the `ApiClient` used by the SDK. +- `komodo_defi_rpc_methods`: Typed RPC request/response models and method namespaces available via `client.rpc.*`. +- `komodo_defi_types`: Shared, lightweight domain types (e.g., `Asset`, `AssetId`, `BalanceInfo`, `WalletId`). +- `komodo_coins`: Fetch/transform Komodo coins metadata, filtering strategies, seed-node utilities. +- `komodo_cex_market_data`: Price providers (Komodo, Binance, CoinGecko) with repository selection and fallbacks. +- `komodo_ui`: Reusable, SDK-friendly Flutter UI components. +- `komodo_wallet_build_transformer`: Build-time artifact & assets fetcher (KDF binaries, coins, icons) integrated via Flutter’s asset transformers. -Create the configuration for the desired runtime: +## Remote vs Local -```dart - switch (_selectedHostType) { - case 'remote': - config = RemoteConfig( - userpass: _userpassController.text, - ipAddress: '$_selectedProtocol://${_ipController.text}', - port: int.parse(_portController.text), - ); - break; - case 'aws': - config = AwsConfig( - userpass: _userpassController.text, - region: _awsRegionController.text, - accessKey: _awsAccessKeyController.text, - secretKey: _awsSecretKeyController.text, - instanceType: _awsInstanceTypeController.text, - ); - break; - case 'local': - config = LocalConfig(userpass: _userpassController.text); - break; - default: - throw Exception( - 'Invalid/unsupported host type: $_selectedHostType', - ); - } -``` +- Local (default): Uses native FFI on desktop/mobile and WASM in Web builds. The SDK handles artifact provisioning via the build transformer. +- Remote: Connect with `RemoteConfig(ipAddress: 'host', port: 7783, rpcPassword: '...', https: true/false)`. You manage the remote KDF lifecycle. -Start KDF: +Seed nodes: From KDF v2.5.0-beta, `seednodes` are required unless `disable_p2p` is `true`. The framework includes a validator and helpers. See `packages/komodo_defi_framework/README.md`. -```dart -void _startKdf(String passphrase) async { - _statusMessage = null; - - if (_kdfFramework == null) { - _showMessage('Please configure the framework first.'); - return; - } - - try { - final result = await _kdfFramework!.startKdf(passphrase); - setState(() { - _statusMessage = 'KDF running: $result'; - _isRunning = true; - }); - - if (!result.isRunning()) { - _showMessage('Failed to start KDF: $result'); - // return; - } - } catch (e) { - _showMessage('Failed to start KDF: $e'); - } - - await _saveData(); - } -``` +## Packages in this monorepo -Execute RPC requests: +- `packages/komodo_defi_sdk` – High-level SDK (start here) +- `packages/komodo_defi_framework` – Low-level KDF client + lifecycle +- `packages/komodo_defi_rpc_methods` – Typed RPC surfaces +- `packages/komodo_defi_types` – Shared domain types +- `packages/komodo_coins` – Coins metadata + filters +- `packages/komodo_cex_market_data` – CEX price data +- `packages/komodo_ui` – UI widgets +- `packages/dragon_logs` – Cross-platform logging +- `packages/komodo_wallet_build_transformer` – Build artifacts/hooks +- `packages/dragon_charts_flutter` – Lightweight charts (moved here) -```dart -executeRequest: (rpcInput) async { - if (_kdfFramework == null || !_isRunning) { - _showMessage('KDF is not running.'); - throw Exception('KDF is not running.'); - } - return (await _kdfFramework!.executeRpc(rpcInput)).toString(); - }, -``` +## Contributing -Stop KDF: +We follow practices inspired by Flutter BLoC and Very Good Ventures’ standards. Please open PRs and issues in this repository. -```dart +## License - void _stopKdf() async { - if (_kdfFramework == null) { - _showMessage('Please configure the framework first.'); - return; - } - - try { - final result = await _kdfFramework!.kdfStop(); - setState(() { - _statusMessage = 'KDF stopped: $result'; - _isRunning = false; - }); - - _checkStatus().ignore(); - } catch (e) { - _showMessage('Failed to stop KDF: $e'); - } - } -``` +MIT. See individual package LICENSE files where present. diff --git a/packages/dragon_charts_flutter/README.md b/packages/dragon_charts_flutter/README.md index 3f5b6bbf..e8f7348c 100644 --- a/packages/dragon_charts_flutter/README.md +++ b/packages/dragon_charts_flutter/README.md @@ -1,18 +1,6 @@ -# 🚚 Repository Moved +# Dragon Charts Flutter -> **⚠️ This repository has been migrated to the Komodo DeFi SDK Flutter monorepo.** -> -> 📍 **New location:** [packages/dragon_charts_flutter](https://github.com/KomodoPlatform/komodo-defi-sdk-flutter/tree/main/packages/dragon_charts_flutter) -> -> 🔄 **Active development** continues in the monorepo. Please update your forks, bookmarks, and links. -> -> 💡 **For issues, PRs, and contributions**, please use the [main monorepo](https://github.com/KomodoPlatform/komodo-defi-sdk-flutter). - ---- - -# Dragon Charts Flutter (Archived) - -Dragon Charts Flutter is a lightweight, declarative, and highly customizable charting library for Flutter. It provides a simple yet powerful way to create various types of charts, with a focus on ease of use and flexibility. +Lightweight, declarative, and customizable charting library for Flutter with minimal dependencies. This package now lives in the Komodo DeFi SDK monorepo. ## Features @@ -33,16 +21,6 @@ Run this command: flutter pub add dragon_charts_flutter ``` -### From GitHub - -```yaml -dependencies: - dragon_charts_flutter: - git: - url: https://github.com/your_username/dragon_charts_flutter.git - ref: main # or a specific tag/branch/commit -``` - Then, run `flutter pub get` to install the package. ## Usage @@ -148,31 +126,12 @@ The main widget for displaying a line chart. - `rangeExtent`: `ChartExtent` - The extent of the range (y-axis). - `backgroundColor`: `Color` - The background color of the chart. -## Roadmap - -### ✅ v0.1.0 (Done) - - - ✅ Initial release with support for line charts. - -### v0.2.0 - -- Add pie charts support. -- Improve documentation and add more examples. - -### v0.3.0 - -- Add bar charts support. -- Implement interactive legends. - -### v0.4.0 - -- Add scatter plots support. -- Enhance performance for large datasets. - -### v1.0.0 +## Roadmap (high level) -- Full documentation and stable release. -- Add support for exporting charts as images. +- Additional chart types (bar, pie, scatter) +- Legends and interactions +- Large dataset performance +- Export as image ## Why Dragon Charts Flutter? @@ -185,8 +144,8 @@ Dragon Charts Flutter is an excellent solution for your charting needs because: ## Contributing -Contributions are welcome! Please read the [contributing guidelines](CONTRIBUTING.md) first. +Contributions are welcome! Please open issues/PRs in the monorepo. ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. \ No newline at end of file +MIT \ No newline at end of file diff --git a/packages/dragon_logs/README.md b/packages/dragon_logs/README.md index 7d51ee22..6072ebfd 100644 --- a/packages/dragon_logs/README.md +++ b/packages/dragon_logs/README.md @@ -29,17 +29,8 @@ Your feedback and contributions to help achieve these features would be much app ## Installation -To use Dragon Logs, add it as a dependency in your `pubspec.yaml` file: - -```yaml -dependencies: - dragon_logs: ^1.0.4 -``` - -Then, run: - -``` -flutter pub get +```sh +flutter pub add dragon_logs ``` # Dragon Logs API Documentation and Usage diff --git a/packages/komodo_cex_market_data/CHANGELOG.md b/packages/komodo_cex_market_data/CHANGELOG.md index b78d64c6..60ce72a5 100644 --- a/packages/komodo_cex_market_data/CHANGELOG.md +++ b/packages/komodo_cex_market_data/CHANGELOG.md @@ -1,3 +1,7 @@ ## 0.0.1 - Initial version. + +## 0.0.2 + +- docs: README with bootstrap, config, and SDK integration examples diff --git a/packages/komodo_cex_market_data/README.md b/packages/komodo_cex_market_data/README.md index 9f9acf04..434797de 100644 --- a/packages/komodo_cex_market_data/README.md +++ b/packages/komodo_cex_market_data/README.md @@ -1,22 +1,83 @@ # Komodo CEX Market Data -Provide a consistent interface through which to access multiple CEX market data APIs. +Composable repositories and strategies to fetch cryptocurrency prices from multiple sources with fallbacks and health-aware selection. -## Features +Sources supported: -- [x] Implement a consistent interface for accessing market data from multiple CEX APIs -- [x] Get market data from multiple CEX APIs +- Komodo price service +- Binance +- CoinGecko -## Getting started +## Install -- Flutter Stable +```sh +dart pub add komodo_cex_market_data +``` -## Usage +## Concepts -TODO: Add usage examples +- Repositories implement a common interface to fetch prices and lists +- A selection strategy chooses the best repository per request +- Failures trigger temporary backoff; callers transparently fall back -## Additional information +## Quick start (standalone) -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. +```dart +import 'package:get_it/get_it.dart'; +import 'package:komodo_cex_market_data/komodo_cex_market_data.dart'; + +final di = GetIt.asNewInstance(); + +// Configure providers/repos/strategy +await MarketDataBootstrap.register(di, config: const MarketDataConfig()); + +final repos = await MarketDataBootstrap.buildRepositoryList( + di, + const MarketDataConfig(), +); + +final manager = CexMarketDataManager( + priceRepositories: repos, + selectionStrategy: di(), +); +await manager.init(); + +// Fetch current price (see komodo_defi_types AssetId for details) +// In practice, you will receive an AssetId from the SDK or coins package +final price = await manager.fiatPrice( + AssetId.parse({ + 'coin': 'KMD', + 'protocol': {'type': 'UTXO'}, + }), + quoteCurrency: Stablecoin.usdt, +); +``` + +## With the SDK + +`KomodoDefiSdk` wires this package for you. Use `sdk.marketData`: + +```dart +final price = await sdk.marketData.fiatPrice(asset.id); +final change24h = await sdk.marketData.priceChange24h(asset.id); +``` + +## Customization + +```dart +const cfg = MarketDataConfig( + enableKomodoPrice: true, + enableBinance: true, + enableCoinGecko: true, + repositoryPriority: [ + RepositoryType.komodoPrice, + RepositoryType.binance, + RepositoryType.coinGecko, + ], + customRepositories: [], +); +``` + +## License + +MIT diff --git a/packages/komodo_cex_market_data/pubspec.yaml b/packages/komodo_cex_market_data/pubspec.yaml index b73e4a7c..e0d7fad4 100644 --- a/packages/komodo_cex_market_data/pubspec.yaml +++ b/packages/komodo_cex_market_data/pubspec.yaml @@ -1,6 +1,6 @@ name: komodo_cex_market_data -description: A starting point for Dart libraries or applications. -version: 0.0.1 +description: CEX market data repositories and strategies with fallbacks for Komodo SDK apps. +version: 0.0.2 publish_to: none # publishable packages should not have git dependencies environment: diff --git a/packages/komodo_coin_updates/README.md b/packages/komodo_coin_updates/README.md index 7ab7e208..dce9736a 100644 --- a/packages/komodo_coin_updates/README.md +++ b/packages/komodo_coin_updates/README.md @@ -1,70 +1,52 @@ -# Komodo Coin Updater +# Komodo Coin Updates -This package provides the functionality to update the coins list and configuration files for the Komodo Platform at runtime. -## Usage +Runtime updater for the Komodo coins list, coin configs, and seed nodes with local persistence. Useful for apps that need to refresh coin metadata without shipping a new app build. -To use this package, you need to add `komodo_coin_updater` to your `pubspec.yaml` file. +## Install -```yaml -dependencies: - komodo_coin_updater: ^1.0.0 +```sh +dart pub add komodo_coin_updates ``` -### Initialize the package - -Then you can use the `KomodoCoinUpdater` class to initialize the package. +## Initialize ```dart -import 'package:komodo_coin_updater/komodo_coin_updater.dart'; +import 'package:flutter/widgets.dart'; +import 'package:komodo_coin_updates/komodo_coin_updates.dart'; -void main() async { - await KomodoCoinUpdater.ensureInitialized("path/to/komodo/coin/files"); +Future main() async { + WidgetsFlutterBinding.ensureInitialized(); + await KomodoCoinUpdater.ensureInitialized('/path/to/app/data'); } ``` -### Provider - -The coins provider is responsible for fetching the coins list and configuration files from GitHub. +## Provider (fetch from GitHub) ```dart -import 'package:komodo_coin_updater/komodo_coin_updater.dart'; - -Future main() async { - WidgetsFlutterBinding.ensureInitialized(); - await KomodoCoinUpdater.ensureInitialized("path/to/komodo/coin/files"); - - final provider = const CoinConfigProvider(); - final coins = await provider.getLatestCoins(); - final coinsConfigs = await provider.getLatestCoinConfigs(); -} +final provider = const CoinConfigProvider(); +final coins = await provider.getLatestCoins(); +final coinConfigs = await provider.getLatestCoinConfigs(); ``` -### Repository - -The repository is responsible for managing the coins list and configuration files, fetching from GitHub and persisting to storage. +## Repository (manage + persist) ```dart -import 'package:komodo_coin_updater/komodo_coin_updater.dart'; - -Future main() async { - WidgetsFlutterBinding.ensureInitialized(); - await KomodoCoinUpdater.ensureInitialized("path/to/komodo/coin/files"); - - final repository = CoinConfigRepository( - api: const CoinConfigProvider(), - storageProvider: CoinConfigStorageProvider.withDefaults(), - ); - - // Load the coin configuration if it is saved, otherwise update it - if(await repository.coinConfigExists()) { - if (await repository.isLatestCommit()) { - await repository.loadCoinConfigs(); - } else { - await repository.updateCoinConfig(); - } - } - else { - await repository.updateCoinConfig(); - } +final repo = CoinConfigRepository( + api: const CoinConfigProvider(), + storageProvider: CoinConfigStorageProvider.withDefaults(), +); + +if (await repo.coinConfigExists()) { + if (await repo.isLatestCommit()) { + await repo.loadCoinConfigs(); + } else { + await repo.updateCoinConfig(); + } +} else { + await repo.updateCoinConfig(); } ``` + +## License + +MIT diff --git a/packages/komodo_coins/README.md b/packages/komodo_coins/README.md index 6777a781..b3f4a92e 100644 --- a/packages/komodo_coins/README.md +++ b/packages/komodo_coins/README.md @@ -1,44 +1,52 @@ -This package was init'd with the following command: -```bash -flutter create komodo_coins -t package --org com.komodoplatform --description 'A package for fetching managing Komodo Platform coin configuration data storage, runtime updates, and queries.' -``` +# Komodo Coins + +Fetch and transform the Komodo coins registry for use across Komodo SDK packages and apps. Provides filtering strategies and helpers to work with coin/asset metadata. - +## Quick start -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. +```dart +import 'package:komodo_coins/komodo_coins.dart'; +import 'package:komodo_defi_types/komodo_defi_types.dart'; -## Features +final coins = KomodoCoins(); +await coins.init(); -TODO: List what your package can do. Maybe include images, gifs, or videos. +// All assets, keyed by AssetId +final all = coins.all; -## Getting started +// Find a specific ticker variant +final btcVariants = coins.findVariantsOfCoin('BTC'); -TODO: List prerequisites and provide or point to information on how to -start using the package. +// Get child assets for a platform id (e.g. tokens on a chain) +final erc20 = coins.findChildAssets( + AssetId.parse({'coin': 'ETH', 'protocol': {'type': 'ETH'}}), +); +``` -## Usage +## Filtering strategies -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. +Use strategies to filter the visible set of assets for a given context (e.g., hardware wallet support): ```dart -const like = 'sample'; +final filtered = coins.filteredAssets(const TrezorAssetFilterStrategy()); ``` -## Additional information +Included strategies: +- `NoAssetFilterStrategy` (default) +- `TrezorAssetFilterStrategy` +- `UtxoAssetFilterStrategy` +- `EvmAssetFilterStrategy` + +## With the SDK + +`KomodoDefiSdk` uses this package under the hood for asset discovery, ordering, and historical/custom tokens. + +## License -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. +MIT \ No newline at end of file diff --git a/packages/komodo_defi_framework/CHANGELOG.md b/packages/komodo_defi_framework/CHANGELOG.md index 41cc7d81..5d7a8ca9 100644 --- a/packages/komodo_defi_framework/CHANGELOG.md +++ b/packages/komodo_defi_framework/CHANGELOG.md @@ -1,3 +1,7 @@ ## 0.0.1 * TODO: Describe initial release. + +## 0.3.0+0 + +* Documentation overhaul: comprehensive README covering local/remote setup, seed nodes, logging, direct RPC usage, and build transformer integration. diff --git a/packages/komodo_defi_framework/README.md b/packages/komodo_defi_framework/README.md index 65075e28..306b1d38 100644 --- a/packages/komodo_defi_framework/README.md +++ b/packages/komodo_defi_framework/README.md @@ -1,101 +1,119 @@ -# Komodo Defi Framework Flutter Package +# Komodo DeFi Framework (Flutter) -This package provides a high-level opinionated framework for interacting with the Komodo Defi API and manages/automates the process of fetching the binary libraries. +Low-level Flutter client for the Komodo DeFi Framework (KDF). This package powers the high-level SDK and can also be used directly for custom integrations or infrastructure tooling. +It supports multiple backends: -TODO: Add a proper description and documentation for the package. Below is the default README.md content for a Flutter FFI plugin. +- Local Native (FFI) on desktop/mobile +- Local Web (WASM) in the browser +- Remote RPC (connect to an external KDF node) +## Install +```sh +flutter pub add komodo_defi_framework +``` -# komodo_defi_framework - -A new Flutter FFI plugin project. +## Create a client + +```dart +import 'package:komodo_defi_framework/komodo_defi_framework.dart'; + +// Local (FFI/WASM) +final framework = KomodoDefiFramework.create( + hostConfig: LocalConfig(https: false, rpcPassword: 'your-secure-password'), + externalLogger: print, // optional +); + +// Or remote +final remote = KomodoDefiFramework.create( + hostConfig: RemoteConfig( + ipAddress: 'example.org', + port: 7783, + rpcPassword: '...', + https: true, + ), +); +``` -## Getting Started +## Starting and stopping KDF (local mode) -This project is a starting point for a Flutter -[FFI plugin](https://flutter.dev/to/ffi-package), -a specialized package that includes native code directly invoked with Dart FFI. +```dart +// Build a startup configuration (no wallet, for diagnostics) +final startup = await KdfStartupConfig.noAuthStartup( + rpcPassword: 'your-secure-password', +); -## Project structure +final result = await framework.startKdf(startup); +if (!result.isStartingOrAlreadyRunning()) { + throw StateError('Failed to start KDF: $result'); +} -This template uses the following structure: +final status = await framework.kdfMainStatus(); +final version = await framework.version(); -* `src`: Contains the native source code, and a CmakeFile.txt file for building - that source code into a dynamic library. +await framework.kdfStop(); +``` -* `lib`: Contains the Dart code that defines the API of the plugin, and which - calls into the native code using `dart:ffi`. +## Direct RPC access -* platform folders (`android`, `ios`, `windows`, etc.): Contains the build files - for building and bundling the native code library with the platform application. +The framework exposes `ApiClient` with typed RPC namespaces: -## Building and bundling native code +```dart +final client = framework.client; +final balance = await client.rpc.wallet.myBalance(coin: 'KMD'); +final check = await client.rpc.address.validateAddress( + coin: 'BTC', + address: 'bc1q...', +); +``` -The `pubspec.yaml` specifies FFI plugins as follows: +## Logging -```yaml - plugin: - platforms: - some_platform: - ffiPlugin: true -``` +- Pass `externalLogger: print` when creating the framework to receive log lines +- Toggle verbosity via `KdfLoggingConfig.verboseLogging = true` +- Listen to `framework.logStream` -This configuration invokes the native build for the various target platforms -and bundles the binaries in Flutter applications using these FFI plugins. +## Seed nodes and P2P -This can be combined with dartPluginClass, such as when FFI is used for the -implementation of one platform in a federated plugin: +From KDF v2.5.0-beta, seed nodes are required unless P2P is disabled. Use `SeedNodeService.fetchSeedNodes()` to fetch defaults and `SeedNodeValidator.validate(...)` to validate your config. Errors are thrown for invalid combinations (e.g., bootstrap without seed, disable P2P with seed nodes, etc.). -```yaml - plugin: - implements: some_other_plugin - platforms: - some_platform: - dartPluginClass: SomeClass - ffiPlugin: true -``` +## Build artifacts and coins at build time -A plugin can have both FFI and method channels: +This package integrates with a Flutter asset transformer to fetch the correct KDF binaries, coins, seed nodes, and icons at build time. Add the following to your app’s `pubspec.yaml`: ```yaml - plugin: - platforms: - some_platform: - pluginClass: SomeName - ffiPlugin: true +flutter: + assets: + - assets/config/ + - assets/coin_icons/png/ + - app_build/build_config.json + - path: assets/.transformer_invoker + transformers: + - package: komodo_wallet_build_transformer + args: + [ + --fetch_defi_api, + --fetch_coin_assets, + --copy_platform_assets, + --artifact_output_package=komodo_defi_framework, + --config_output_path=app_build/build_config.json, + ] ``` -The native build systems that are invoked by FFI (and method channel) plugins are: - -* For Android: Gradle, which invokes the Android NDK for native builds. - * See the documentation in android/build.gradle. -* For iOS and MacOS: Xcode, via CocoaPods. - * See the documentation in ios/komodo_defi_framework.podspec. - * See the documentation in macos/komodo_defi_framework.podspec. -* For Linux and Windows: CMake. - * See the documentation in linux/CMakeLists.txt. - * See the documentation in windows/CMakeLists.txt. - -## Binding to native code - -To use the native code, bindings in Dart are needed. -To avoid writing these by hand, they are generated from the header file -(`src/komodo_defi_framework.h`) by `package:ffigen`. -Regenerate the bindings by running `dart run ffigen --config ffigen.yaml`. +You can customize sources and checksums via `app_build/build_config.json` in this package. See `packages/komodo_wallet_build_transformer/README.md` for CLI flags, environment variables, and troubleshooting. -## Invoking native code +## Web (WASM) -Very short-running native functions can be directly invoked from any isolate. -For example, see `sum` in `lib/komodo_defi_framework.dart`. +On Web, the plugin registers a WASM implementation automatically (see `lib/web/kdf_plugin_web.dart`). The WASM bundle and bootstrap scripts are provided via the build transformer. -Longer-running functions should be invoked on a helper isolate to avoid -dropping frames in Flutter applications. -For example, see `sumAsync` in `lib/komodo_defi_framework.dart`. +## APIs and enums -## Flutter help +- `IKdfHostConfig` with `LocalConfig`, `RemoteConfig` (and WIP: `AwsConfig`, `DigitalOceanConfig`) +- `KdfStartupConfig` helpers: `generateWithDefaults(...)`, `noAuthStartup(...)` +- Lifecycle: `startKdf`, `kdfMainStatus`, `kdfStop`, `version`, `logStream` +- Errors: `JsonRpcErrorResponse`, `ConnectionError` -For help getting started with Flutter, view our -[online documentation](https://docs.flutter.dev), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +## License +MIT diff --git a/packages/komodo_defi_framework/app_build/BUILD_CONFIG_README.md b/packages/komodo_defi_framework/app_build/BUILD_CONFIG_README.md new file mode 100644 index 00000000..09a658a7 --- /dev/null +++ b/packages/komodo_defi_framework/app_build/BUILD_CONFIG_README.md @@ -0,0 +1,47 @@ +# Build Config Guide + +This directory contains the artifact configuration used by `komodo_wallet_build_transformer` to fetch KDF binaries/WASM and coin assets at build time. + +## Files + +- `build_config.json` – canonical configuration used by the transformer +- `build_config.yaml` – reference YAML form (not currently consumed by the tool) + +## Key fields (JSON) + +- `api.api_commit_hash` – commit hash of the KDF artifacts to fetch +- `api.source_urls` – list of base URLs to download from (GitHub API, CDN) +- `api.platforms.*.matching_pattern` – regex to match artifact names per platform +- `api.platforms.*.valid_zip_sha256_checksums` – allow-list of artifact checksums +- `api.platforms.*.path` – destination relative to artifact output package +- `coins.bundled_coins_repo_commit` – commit of Komodo coins registry +- `coins.mapped_files` – mapping of output paths to source files in coins repo +- `coins.mapped_folders` – mapping of output dirs to repo folders (e.g. icons) + +## Where artifacts are stored + +Artifacts are downloaded into the package specified by the transformer flag: + +``` +--artifact_output_package=komodo_defi_framework +``` + +Paths in the config are relative to that package directory. + +## Updating artifacts + +1. Update `api_commit_hash` and (optionally) checksums +2. Run the build transformer (via Flutter asset transformers or CLI) +3. Commit the updated artifacts if your workflow requires vendoring + +## Tips + +- Set `GITHUB_API_PUBLIC_READONLY_TOKEN` to increase GitHub API rate limits +- Use `--concurrent` for faster downloads in development +- Override behavior per build via env `OVERRIDE_DEFI_API_DOWNLOAD=true|false` + +## Troubleshooting + +- Missing files: verify `config_output_path` points to this folder and the file exists +- Checksum mismatch: update checksums to match newly published artifacts +- Web CORS: ensure WASM bundle and bootstrap JS are present under `web/kdf/bin` diff --git a/packages/komodo_defi_local_auth/README.md b/packages/komodo_defi_local_auth/README.md index 1a488235..bf0f564c 100644 --- a/packages/komodo_defi_local_auth/README.md +++ b/packages/komodo_defi_local_auth/README.md @@ -1,67 +1,59 @@ -# Komodo Defi Local Auth +# Komodo DeFi Local Auth -[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link] -[![Powered by Mason](https://img.shields.io/endpoint?url=https%3A%2F%2Ftinyurl.com%2Fmason-badge)](https://github.com/felangel/mason) -[![License: MIT][license_badge]][license_link] - -A package responsible for managing and abstracting out an authentication service on top of the API's methods - -## Installation 💻 +Authentication and wallet management on top of the Komodo DeFi Framework. This package powers the `KomodoDefiSdk.auth` surface and can be used directly for custom flows. -**❗ In order to start using Komodo Defi Local Auth you must have the [Flutter SDK][flutter_install_link] installed on your machine.** +[![License: MIT][license_badge]][license_link] -Install via `flutter pub add`: +## Install ```sh dart pub add komodo_defi_local_auth ``` ---- +## Getting started -## Continuous Integration 🤖 +```dart +import 'package:komodo_defi_framework/komodo_defi_framework.dart'; +import 'package:komodo_defi_local_auth/komodo_defi_local_auth.dart'; -Komodo Defi Local Auth comes with a built-in [GitHub Actions workflow][github_actions_link] powered by [Very Good Workflows][very_good_workflows_link] but you can also add your preferred CI/CD solution. +final framework = KomodoDefiFramework.create( + hostConfig: LocalConfig(https: false, rpcPassword: 'your-secure-password'), +); -Out of the box, on each pull request and push, the CI `formats`, `lints`, and `tests` the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses [Very Good Analysis][very_good_analysis_link] for a strict set of analysis options used by our team. Code coverage is enforced using the [Very Good Workflows][very_good_coverage_link]. +final auth = KomodoDefiLocalAuth( + kdf: framework, + hostConfig: LocalConfig(https: false, rpcPassword: 'your-secure-password'), +); +await auth.ensureInitialized(); ---- +// Register or sign in (HD wallet by default) +await auth.register(walletName: 'my_wallet', password: 'strong-pass'); +``` -## Running Tests 🧪 +## API highlights -For first time users, install the [very_good_cli][very_good_cli_link]: +- `signIn` / `register` (+ `signInStream` / `registerStream` for progress and HW flows) +- `authStateChanges` and `watchCurrentUser()` +- `currentUser`, `getUsers()`, `signOut()` +- Mnemonic management: `getMnemonicEncrypted()`, `getMnemonicPlainText()`, `updatePassword()` +- Wallet admin: `deleteWallet(...)` +- Trezor flows (PIN entry etc.) via streaming API -```sh -dart pub global activate very_good_cli -``` +HD is enabled by default via `AuthOptions(derivationMethod: DerivationMethod.hdWallet)`. Override if you need legacy (Iguana) mode. -To run all unit tests: +## With the SDK -```sh -very_good test --coverage -``` +Prefer using `KomodoDefiSdk` which wires and scopes auth, assets, balances, and the rest for you: -To view the generated coverage report you can use [lcov](https://github.com/linux-test-project/lcov). +```dart +final sdk = KomodoDefiSdk(); +await sdk.initialize(); +await sdk.auth.signIn(walletName: 'my_wallet', password: 'pass'); +``` -```sh -# Generate Coverage Report -genhtml coverage/lcov.info -o coverage/ +## License -# Open Coverage Report -open coverage/index.html -``` +MIT -[flutter_install_link]: https://docs.flutter.dev/get-started/install -[github_actions_link]: https://docs.github.com/en/actions/learn-github-actions [license_badge]: https://img.shields.io/badge/license-MIT-blue.svg [license_link]: https://opensource.org/licenses/MIT -[logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only -[logo_white]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_white.png#gh-dark-mode-only -[mason_link]: https://github.com/felangel/mason -[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg -[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis -[very_good_cli_link]: https://pub.dev/packages/very_good_cli -[very_good_coverage_link]: https://github.com/marketplace/actions/very-good-coverage -[very_good_ventures_link]: https://verygood.ventures -[very_good_ventures_link_light]: https://verygood.ventures#gh-light-mode-only -[very_good_ventures_link_dark]: https://verygood.ventures#gh-dark-mode-only -[very_good_workflows_link]: https://github.com/VeryGoodOpenSource/very_good_workflows diff --git a/packages/komodo_defi_rpc_methods/CHANGELOG.md b/packages/komodo_defi_rpc_methods/CHANGELOG.md index 5221ac3c..ff6a5d9e 100644 --- a/packages/komodo_defi_rpc_methods/CHANGELOG.md +++ b/packages/komodo_defi_rpc_methods/CHANGELOG.md @@ -1,3 +1,7 @@ # 0.1.0+1 - feat: initial commit 🎉 + +## 0.1.1 + +- docs: README with usage examples for client.rpc namespaces diff --git a/packages/komodo_defi_rpc_methods/README.md b/packages/komodo_defi_rpc_methods/README.md index cb4a7c1d..f940bae1 100644 --- a/packages/komodo_defi_rpc_methods/README.md +++ b/packages/komodo_defi_rpc_methods/README.md @@ -1,62 +1,53 @@ -# Komodo Defi Rpc Methods +# Komodo DeFi RPC Methods -[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link] -[![Powered by Mason](https://img.shields.io/endpoint?url=https%3A%2F%2Ftinyurl.com%2Fmason-badge)](https://github.com/felangel/mason) -[![License: MIT][license_badge]][license_link] - -A package containing the RPC methods and responses for the Komodo DeFi Framework API +Typed RPC request/response models and method namespaces for the Komodo DeFi Framework API. This package is consumed by the framework (`ApiClient`) and the high-level SDK. -## Installation 💻 - -**❗ In order to start using Komodo Defi Rpc Methods you must have the [Dart SDK][dart_install_link] installed on your machine.** +[![License: MIT][license_badge]][license_link] -Install via `dart pub add`: +## Install ```sh dart pub add komodo_defi_rpc_methods ``` ---- +## Usage -## Continuous Integration 🤖 +RPC namespaces are exposed as extensions on `ApiClient` via `client.rpc` when using either the framework or the SDK. -Komodo Defi Rpc Methods comes with a built-in [GitHub Actions workflow][github_actions_link] powered by [Very Good Workflows][very_good_workflows_link] but you can also add your preferred CI/CD solution. +```dart +import 'package:komodo_defi_framework/komodo_defi_framework.dart'; -Out of the box, on each pull request and push, the CI `formats`, `lints`, and `tests` the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses [Very Good Analysis][very_good_analysis_link] for a strict set of analysis options used by our team. Code coverage is enforced using the [Very Good Workflows][very_good_coverage_link]. +final framework = KomodoDefiFramework.create( + hostConfig: LocalConfig(https: false, rpcPassword: '...'), +); ---- +final client = framework.client; -## Running Tests 🧪 +// Wallet +final names = await client.rpc.wallet.getWalletNames(); +final kmdBalance = await client.rpc.wallet.myBalance(coin: 'KMD'); -To run all unit tests: +// Addresses +final v = await client.rpc.address.validateAddress( + coin: 'BTC', + address: 'bc1q...', +); -```sh -dart pub global activate coverage 1.2.0 -dart test --coverage=coverage -dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info +// General activation +final enabled = await client.rpc.generalActivation.getEnabledCoins(); + +// Message signing +final signed = await client.rpc.utility.signMessage( + coin: 'BTC', + message: 'Hello, Komodo!' +); ``` -To view the generated coverage report you can use [lcov](https://github.com/linux-test-project/lcov). +Explore exported modules in `lib/src/rpc_methods` for the full surface (activation, wallet, utxo/eth/trezor, trading, orderbook, transaction history, withdrawal, etc.). -```sh -# Generate Coverage Report -genhtml coverage/lcov.info -o coverage/ +## License -# Open Coverage Report -open coverage/index.html -``` +MIT -[dart_install_link]: https://dart.dev/get-dart -[github_actions_link]: https://docs.github.com/en/actions/learn-github-actions [license_badge]: https://img.shields.io/badge/license-MIT-blue.svg [license_link]: https://opensource.org/licenses/MIT -[logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only -[logo_white]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_white.png#gh-dark-mode-only -[mason_link]: https://github.com/felangel/mason -[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg -[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis -[very_good_coverage_link]: https://github.com/marketplace/actions/very-good-coverage -[very_good_ventures_link]: https://verygood.ventures -[very_good_ventures_link_light]: https://verygood.ventures#gh-light-mode-only -[very_good_ventures_link_dark]: https://verygood.ventures#gh-dark-mode-only -[very_good_workflows_link]: https://github.com/VeryGoodOpenSource/very_good_workflows diff --git a/packages/komodo_defi_sdk/CHANGELOG.md b/packages/komodo_defi_sdk/CHANGELOG.md index 5221ac3c..1f7edbf3 100644 --- a/packages/komodo_defi_sdk/CHANGELOG.md +++ b/packages/komodo_defi_sdk/CHANGELOG.md @@ -1,3 +1,7 @@ # 0.1.0+1 - feat: initial commit 🎉 + +## 0.1.1 + +- docs: comprehensive README with quick start, config, tasks, and advanced RPC diff --git a/packages/komodo_defi_sdk/README.md b/packages/komodo_defi_sdk/README.md index 5ad8012c..97a3c4ab 100644 --- a/packages/komodo_defi_sdk/README.md +++ b/packages/komodo_defi_sdk/README.md @@ -1,65 +1,199 @@ -# Komodo Defi Sdk +# Komodo DeFi SDK (Flutter) +High-level, opinionated SDK for building cross-platform Komodo DeFi wallets and apps. The SDK orchestrates authentication, asset activation, balances, transaction history, withdrawals, message signing, and price data while exposing a typed RPC client for advanced use. -TODO: Replace auto-generated content below with a comprehensive README. +[![License: MIT][license_badge]][license_link] [![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link] -[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link] -[![Powered by Mason](https://img.shields.io/endpoint?url=https%3A%2F%2Ftinyurl.com%2Fmason-badge)](https://github.com/felangel/mason) -[![License: MIT][license_badge]][license_link] +## Features -A high-level opinionated library that provides a simple way to build cross-platform Komodo Defi Framework applications (primarily focused on wallets). This package consists of multiple sub-packages in the packages folder which are orchestrated by this package (komodo_defi_sdk) +- Authentication and wallet lifecycle (HD by default, hardware wallets supported) +- Asset discovery and activation (with historical/custom token pre-activation) +- Balances and pubkeys (watch/stream and on-demand) +- Transaction history (paged + streaming sync) +- Withdrawals with progress and cancellation +- Message signing and verification +- CEX market data integration (Komodo, Binance, CoinGecko) with fallbacks +- Typed RPC namespaces via `client.rpc.*` -## Installation 💻 - -**❗ In order to start using Komodo Defi Sdk you must have the [Dart SDK][dart_install_link] installed on your machine.** - -Install via `dart pub add`: +## Install ```sh dart pub add komodo_defi_sdk ``` ---- +## Quick start -## Continuous Integration 🤖 +```dart +import 'package:komodo_defi_sdk/komodo_defi_sdk.dart'; -Komodo Defi Sdk comes with a built-in [GitHub Actions workflow][github_actions_link] powered by [Very Good Workflows][very_good_workflows_link] but you can also add your preferred CI/CD solution. +final sdk = KomodoDefiSdk( + host: LocalConfig(https: false, rpcPassword: 'your-secure-password'), + config: const KomodoDefiSdkConfig( + defaultAssets: {'KMD', 'BTC', 'ETH'}, + ), +); -Out of the box, on each pull request and push, the CI `formats`, `lints`, and `tests` the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses [Very Good Analysis][very_good_analysis_link] for a strict set of analysis options used by our team. Code coverage is enforced using the [Very Good Workflows][very_good_coverage_link]. +await sdk.initialize(); ---- +// Register or sign in +await sdk.auth.register(walletName: 'my_wallet', password: 'strong-pass'); -## Running Tests 🧪 +// Activate an asset and read a balance +final btc = sdk.assets.findAssetsByConfigId('BTC').first; +await sdk.assets.activateAsset(btc).last; +final balance = await sdk.balances.getBalance(btc.id); -To run all unit tests: +// Direct RPC when needed +final kmd = await sdk.client.rpc.wallet.myBalance(coin: 'KMD'); +``` -```sh -dart pub global activate coverage 1.2.0 -dart test --coverage=coverage -dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info +## Configuration + +```dart +// Host selection: local (default) or remote +final local = LocalConfig(https: false, rpcPassword: '...'); +final remote = RemoteConfig( + ipAddress: 'example.org', + port: 7783, + rpcPassword: '...', + https: true, +); + +// SDK behavior +const config = KomodoDefiSdkConfig( + defaultAssets: {'KMD', 'BTC', 'ETH', 'DOC'}, + preActivateDefaultAssets: true, + preActivateHistoricalAssets: true, + preActivateCustomTokenAssets: true, + marketDataConfig: MarketDataConfig( + enableKomodoPrice: true, + enableBinance: true, + enableCoinGecko: true, + ), +); ``` -To view the generated coverage report you can use [lcov](https://github.com/linux-test-project/lcov). +## Common tasks -```sh -# Generate Coverage Report -genhtml coverage/lcov.info -o coverage/ +### Authentication + +```dart +await sdk.auth.signIn(walletName: 'my_wallet', password: 'pass'); +// Streams for progress/2FA/hardware interactions are also available +``` + +### Assets + +```dart +final eth = sdk.assets.findAssetsByConfigId('ETH').first; +await for (final p in sdk.assets.activateAsset(eth)) { + // p: ActivationProgress +} +final activated = await sdk.assets.getActivatedAssets(); +``` + +### Pubkeys and addresses + +```dart +final asset = sdk.assets.findAssetsByConfigId('BTC').first; +final pubkeys = await sdk.pubkeys.getPubkeys(asset); +final newAddr = await sdk.pubkeys.createNewPubkey(asset); +``` + +### Balances + +```dart +final info = await sdk.balances.getBalance(asset.id); +final sub = sdk.balances.watchBalance(asset.id).listen((b) { + // update UI +}); +``` + +### Transaction history + +```dart +final page = await sdk.transactions.getTransactionHistory(asset); +await for (final batch in sdk.transactions.getTransactionsStreamed(asset)) { + // append to list +} +``` -# Open Coverage Report -open coverage/index.html +### Withdrawals + +```dart +final stream = sdk.withdrawals.withdraw( + WithdrawParameters( + asset: 'BTC', + toAddress: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', + amount: Decimal.parse('0.001'), + // feePriority optional until fee estimation endpoints are available + ), +); +await for (final progress in stream) { + // status / tx hash +} ``` -[dart_install_link]: https://dart.dev/get-dart -[github_actions_link]: https://docs.github.com/en/actions/learn-github-actions +### Message signing + +```dart +final signature = await sdk.messageSigning.signMessage( + coin: 'BTC', + message: 'Hello, Komodo!', + address: 'bc1q...', +); +final ok = await sdk.messageSigning.verifyMessage( + coin: 'BTC', + message: 'Hello, Komodo!', + signature: signature, + address: 'bc1q...', +); +``` + +### Market data + +```dart +final price = await sdk.marketData.fiatPrice( + asset.id, + quoteCurrency: Stablecoin.usdt, +); +``` + +## UI helpers + +This package includes lightweight adapters for `komodo_ui`. For example: + +```dart +// Displays and live-updates an asset balance using the SDK +AssetBalanceText(asset.id) +``` + +## Advanced: direct RPC + +The underlying `ApiClient` exposes typed RPC namespaces: + +```dart +final resp = await sdk.client.rpc.address.validateAddress( + coin: 'BTC', + address: 'bc1q...', +); +``` + +## Lifecycle and disposal + +Call `await sdk.dispose()` when you’re done to free resources and stop background timers. + +## Platform notes + +- Web uses the WASM build of KDF automatically via the framework plugin. +- Remote mode connects to an external KDF node you run and manage. +- From KDF v2.5.0-beta, seed nodes are required unless P2P is disabled. The framework handles validation and defaults; see its README for details. + +## License + +MIT + [license_badge]: https://img.shields.io/badge/license-MIT-blue.svg [license_link]: https://opensource.org/licenses/MIT -[logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only -[logo_white]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_white.png#gh-dark-mode-only -[mason_link]: https://github.com/felangel/mason [very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg [very_good_analysis_link]: https://pub.dev/packages/very_good_analysis -[very_good_coverage_link]: https://github.com/marketplace/actions/very-good-coverage -[very_good_ventures_link]: https://verygood.ventures -[very_good_ventures_link_light]: https://verygood.ventures#gh-light-mode-only -[very_good_ventures_link_dark]: https://verygood.ventures#gh-dark-mode-only -[very_good_workflows_link]: https://github.com/VeryGoodOpenSource/very_good_workflows diff --git a/packages/komodo_defi_types/README.md b/packages/komodo_defi_types/README.md index a76d08ab..cc025747 100644 --- a/packages/komodo_defi_types/README.md +++ b/packages/komodo_defi_types/README.md @@ -1,30 +1,47 @@ # Komodo DeFi Types -A shared library for common types/entities used in the Komodo DeFi Framework. **NB: They should be kept lightweight and agnostic to the context in which they are used.** E.g. A `Coin` type should not contain the balance or contract address information. +Lightweight, shared domain types used across the Komodo DeFi SDK and Framework. These types are UI- and storage-agnostic by design. -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. +## Install -## Features +```sh +dart pub add komodo_defi_types +``` -TODO: List what your package can do. Maybe include images, gifs, or videos. +## What’s inside -## Getting started +Exports (selection): -TODO: List prerequisites and provide or point to information on how to -start using the package. +- API: `ApiClient` (+ `client.rpc` extension) +- Assets: `Asset`, `AssetId`, `AssetPubkeys`, `AssetValidation` +- Public keys: `BalanceStrategy`, `PubkeyInfo` +- Auth: `KdfUser`, `AuthOptions` +- Fees: `FeeInfo`, `WithdrawalFeeOptions` +- Trading/Swaps: common high-level types +- Transactions: `Transaction`, pagination helpers -## Usage +These types are consumed by higher-level managers in `komodo_defi_sdk`. -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. +## Example ```dart -const like = 'sample'; +import 'package:komodo_defi_types/komodo_defi_types.dart'; + +// Create an AssetId (normally parsed/built by coins package/SDK) +final id = AssetId.parse({'coin': 'KMD', 'protocol': {'type': 'UTXO'}}); + +// Work with typed RPC via ApiClient extension +Future printBalance(ApiClient client) async { + final resp = await client.rpc.wallet.myBalance(coin: id.id); + print(resp.balance); +} ``` -## Additional information +## Guidance + +- Keep these types free of presentation or persistence logic +- Prefer explicit, well-named fields and immutability + +## License -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. +MIT diff --git a/packages/komodo_symbol_converter/README.md b/packages/komodo_symbol_converter/README.md index 280b8f54..b4e3b6b3 100644 --- a/packages/komodo_symbol_converter/README.md +++ b/packages/komodo_symbol_converter/README.md @@ -1,62 +1,22 @@ # Komodo Symbol Converter -[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link] -[![Powered by Mason](https://img.shields.io/endpoint?url=https%3A%2F%2Ftinyurl.com%2Fmason-badge)](https://github.com/felangel/mason) -[![License: MIT][license_badge]][license_link] +Lightweight utilities to convert symbols/tickers and related display helpers. Intended for small formatting/translation tasks in apps built on the Komodo SDK. -A lightweight package to convert fiat/crypto prices and charts - -## Installation 💻 - -**❗ In order to start using Komodo Symbol Converter you must have the [Dart SDK][dart_install_link] installed on your machine.** - -Install via `dart pub add`: +## Install ```sh dart pub add komodo_symbol_converter ``` ---- - -## Continuous Integration 🤖 - -Komodo Symbol Converter comes with a built-in [GitHub Actions workflow][github_actions_link] powered by [Very Good Workflows][very_good_workflows_link] but you can also add your preferred CI/CD solution. - -Out of the box, on each pull request and push, the CI `formats`, `lints`, and `tests` the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses [Very Good Analysis][very_good_analysis_link] for a strict set of analysis options used by our team. Code coverage is enforced using the [Very Good Workflows][very_good_coverage_link]. - ---- +## Usage -## Running Tests 🧪 +```dart +import 'package:komodo_symbol_converter/komodo_symbol_converter.dart'; -To run all unit tests: - -```sh -dart pub global activate coverage 1.2.0 -dart test --coverage=coverage -dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info +const converter = KomodoSymbolConverter(); +// Extend with your own mapping/format logic as needed ``` -To view the generated coverage report you can use [lcov](https://github.com/linux-test-project/lcov). - -```sh -# Generate Coverage Report -genhtml coverage/lcov.info -o coverage/ - -# Open Coverage Report -open coverage/index.html -``` +## License -[dart_install_link]: https://dart.dev/get-dart -[github_actions_link]: https://docs.github.com/en/actions/learn-github-actions -[license_badge]: https://img.shields.io/badge/license-MIT-blue.svg -[license_link]: https://opensource.org/licenses/MIT -[logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only -[logo_white]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_white.png#gh-dark-mode-only -[mason_link]: https://github.com/felangel/mason -[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg -[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis -[very_good_coverage_link]: https://github.com/marketplace/actions/very-good-coverage -[very_good_ventures_link]: https://verygood.ventures -[very_good_ventures_link_light]: https://verygood.ventures#gh-light-mode-only -[very_good_ventures_link_dark]: https://verygood.ventures#gh-dark-mode-only -[very_good_workflows_link]: https://github.com/VeryGoodOpenSource/very_good_workflows +MIT diff --git a/packages/komodo_ui/CHANGELOG.md b/packages/komodo_ui/CHANGELOG.md new file mode 100644 index 00000000..559ba6af --- /dev/null +++ b/packages/komodo_ui/CHANGELOG.md @@ -0,0 +1,3 @@ +## 0.3.0+0 + +- docs: README with highlights, usage, and relation to SDK adapters diff --git a/packages/komodo_ui/README.md b/packages/komodo_ui/README.md index ef184ee0..dae58fee 100644 --- a/packages/komodo_ui/README.md +++ b/packages/komodo_ui/README.md @@ -1,67 +1,44 @@ -# Komodo Ui +# Komodo UI -[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link] -[![Powered by Mason](https://img.shields.io/endpoint?url=https%3A%2F%2Ftinyurl.com%2Fmason-badge)](https://github.com/felangel/mason) -[![License: MIT][license_badge]][license_link] - -A high-level widget catalog relevant to building Flutter UI apps which consume Komodo DeFi Framework - -## Installation 💻 +Reusable Flutter widgets for DeFi apps built on the Komodo DeFi SDK and Framework. Focused, production-ready components that pair naturally with the SDK’s managers. -**❗ In order to start using Komodo Ui you must have the [Flutter SDK][flutter_install_link] installed on your machine.** +[![License: MIT][license_badge]][license_link] -Install via `flutter pub add`: +## Install ```sh -dart pub add komodo_ui +flutter pub add komodo_ui ``` ---- - -## Continuous Integration 🤖 - -Komodo Ui comes with a built-in [GitHub Actions workflow][github_actions_link] powered by [Very Good Workflows][very_good_workflows_link] but you can also add your preferred CI/CD solution. +## Highlights -Out of the box, on each pull request and push, the CI `formats`, `lints`, and `tests` the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses [Very Good Analysis][very_good_analysis_link] for a strict set of analysis options used by our team. Code coverage is enforced using the [Very Good Workflows][very_good_coverage_link]. +- Core inputs and displays: address fields, fee info, transaction formatting +- DeFi flows: withdraw form primitives, asset cards, trend text, icons +- Utilities: debouncer, formatters, QR code scanner ---- +## Usage -## Running Tests 🧪 +Widgets are framework-agnostic and can be used directly. When used with the SDK, adapter widgets are available from `komodo_defi_sdk` to bind to SDK streams, e.g.: -For first time users, install the [very_good_cli][very_good_cli_link]: - -```sh -dart pub global activate very_good_cli +```dart +// From komodo_defi_sdk: live balance text bound to BalanceManager +AssetBalanceText(assetId) ``` -To run all unit tests: +Withdraw UI example scaffolding is provided: -```sh -very_good test --coverage +```dart +// Example only, see source for a complete form demo +WithdrawalFormExample(asset: asset) ``` -To view the generated coverage report you can use [lcov](https://github.com/linux-test-project/lcov). +## Formatting helpers -```sh -# Generate Coverage Report -genhtml coverage/lcov.info -o coverage/ +Utilities to format addresses, assets, fees and transaction details are available under `src/utils/formatters`. -# Open Coverage Report -open coverage/index.html -``` +## License + +MIT -[flutter_install_link]: https://docs.flutter.dev/get-started/install -[github_actions_link]: https://docs.github.com/en/actions/learn-github-actions [license_badge]: https://img.shields.io/badge/license-MIT-blue.svg [license_link]: https://opensource.org/licenses/MIT -[logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only -[logo_white]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_white.png#gh-dark-mode-only -[mason_link]: https://github.com/felangel/mason -[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg -[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis -[very_good_cli_link]: https://pub.dev/packages/very_good_cli -[very_good_coverage_link]: https://github.com/marketplace/actions/very-good-coverage -[very_good_ventures_link]: https://verygood.ventures -[very_good_ventures_link_light]: https://verygood.ventures#gh-light-mode-only -[very_good_ventures_link_dark]: https://verygood.ventures#gh-dark-mode-only -[very_good_workflows_link]: https://github.com/VeryGoodOpenSource/very_good_workflows diff --git a/packages/komodo_wallet_build_transformer/README.md b/packages/komodo_wallet_build_transformer/README.md index b7639b54..5e1cd449 100644 --- a/packages/komodo_wallet_build_transformer/README.md +++ b/packages/komodo_wallet_build_transformer/README.md @@ -1 +1,78 @@ -A sample command-line application providing basic argument parsing with an entrypoint in `bin/`. +# Komodo Wallet Build Transformer + +Flutter asset transformer and CLI to fetch KDF artifacts (binaries/WASM), coins config, seed nodes, and icons at build time, and to copy platform-specific assets. + +This package powers the build hooks used by `komodo_defi_framework` and the SDK to make local (FFI/WASM) usage seamless. + +## How it works + +- Runs as a Flutter asset transformer via a special asset file entry +- Executes configured build steps: + - `fetch_defi_api`: download KDF artifacts for target platforms + - `fetch_coin_assets`: download coins list/config, seed nodes, and icons + - `copy_platform_assets`: copy platform assets into the consuming app + +## Add to your app’s pubspec + +Add this under `flutter/assets`: + +```yaml +flutter: + assets: + - assets/config/ + - assets/coin_icons/png/ + - app_build/build_config.json + - path: assets/.transformer_invoker + transformers: + - package: komodo_wallet_build_transformer + args: + [ + --fetch_defi_api, + --fetch_coin_assets, + --copy_platform_assets, + --artifact_output_package=komodo_defi_framework, + --config_output_path=app_build/build_config.json, + ] +``` + +Artifacts and checksums are configured in `packages/komodo_defi_framework/app_build/build_config.json`. + +## CLI + +You can run the transformer directly for local testing: + +```sh +dart run packages/komodo_wallet_build_transformer/bin/komodo_wallet_build_transformer.dart \ + --all \ + --artifact_output_package=komodo_defi_framework \ + --config_output_path=app_build/build_config.json \ + -i /tmp/input_marker.txt -o /tmp/output_marker.txt +``` + +Flags: + +- `--all` to run all steps, or select specific steps with: + - `--fetch_defi_api` + - `--fetch_coin_assets` + - `--copy_platform_assets` +- `--artifact_output_package` The package receiving downloaded artifacts +- `--config_output_path` Path to config JSON relative to artifact package +- `-i/--input` and `-o/--output` Required by Flutter’s asset transformer interface +- `-l/--log_level` One of: `finest,finer,fine,config,info,warning,severe,shout` +- `-v/--verbose` Verbose output +- `--concurrent` Run steps concurrently when safe + +Environment: + +- `GITHUB_API_PUBLIC_READONLY_TOKEN` Optional; increases rate limits +- `OVERRIDE_DEFI_API_DOWNLOAD` Force `true` (always fetch) or `false` (always skip) regardless of state + +## Troubleshooting + +- Missing config: ensure the `--config_output_path` file exists in `artifact_output_package` +- CORS on Web: the KDF WASM and bootstrap files must be present under `web/kdf/bin` in the artifact package +- Checksums mismatch: update `build_config.json` to the new artifact checksums and commit hash + +## License + +MIT diff --git a/packages/komodo_wallet_cli/README.md b/packages/komodo_wallet_cli/README.md index fcca56e4..5271d709 100644 --- a/packages/komodo_wallet_cli/README.md +++ b/packages/komodo_wallet_cli/README.md @@ -1 +1,101 @@ -A package which will be used as a utility for managing build and other general dev tools \ No newline at end of file +# Komodo Wallet CLI + +Developer CLI wrapper for Komodo wallet tooling. Currently forwards to the build transformer to simplify local usage. + +## Install + +Run directly via Dart: + +```sh +dart run packages/komodo_wallet_cli/bin/komodo_wallet_cli.dart --help +``` + +## Commands + +### 1) Build transformer wrapper (`get`) + +Runs the build transformer to fetch KDF artifacts (binaries/WASM), coins config, seed nodes, and icons, and to copy platform assets. + +Example: + +```sh +dart run packages/komodo_wallet_cli/bin/komodo_wallet_cli.dart get \ + --all \ + --artifact_output_package=komodo_defi_framework \ + --config_output_path=app_build/build_config.json \ + -i /tmp/input_marker.txt -o /tmp/output_marker.txt +``` + +Flags (proxied to build transformer): + +- `--all` – Run all steps +- `--fetch_defi_api` – Fetch KDF artifacts +- `--fetch_coin_assets` – Fetch coins list/config, seed nodes, icons +- `--copy_platform_assets` – Copy platform assets into the app +- `--artifact_output_package=` – Target package for artifacts +- `--config_output_path=` – Path to build config in target package +- `-i/--input` and `-o/--output` – Required by Flutter asset transformers +- `-l/--log_level=finest|...` – Verbosity +- `--concurrent` – Run steps concurrently + +Notes: + +- Set `GITHUB_API_PUBLIC_READONLY_TOKEN` to increase GitHub API rate limits +- `OVERRIDE_DEFI_API_DOWNLOAD=true|false` can force update/skip at build time + +### 2) Update API config (`update_api_config` executable) + +Fetches the latest commit from a branch (GitHub or mirror), locates matching artifacts, computes their SHA-256 checksums, and updates the build config JSON in place. Use when bumping the KDF artifact version/checksums. + +Run (direct): + +```sh +dart run packages/komodo_wallet_cli/bin/update_api_config.dart \ + --branch dev \ + --source mirror \ + --config packages/komodo_defi_framework/app_build/build_config.json \ + --output-dir packages/komodo_defi_framework/app_build/temp_downloads \ + --verbose +``` + +If activated globally: + +```sh +komodo_wallet_cli update_api_config --branch dev --source mirror --config packages/komodo_defi_framework/app_build/build_config.json +``` + +Options: + +- `-b, --branch ` – Branch to fetch commit from (default: master) +- `--repo ` – Repository (default: KomodoPlatform/komodo-defi-framework) +- `-c, --config ` – Path to build_config.json (default: build_config.json) +- `-o, --output-dir ` – Temp download dir (default: temp_downloads) +- `-t, --token ` – GitHub token (or env `GITHUB_API_PUBLIC_READONLY_TOKEN`) +- `-p, --platform ` – Specific platform to update or `all` (default: all) +- `-s, --source ` – Source for artifacts (default: github) +- `--mirror-url ` – Mirror base URL (default: https://sdk.devbuilds.komodo.earth) +- `-v, --verbose` – Verbose logging +- `-h, --help` – Show help + +### 3) Upgrade nested Flutter projects (`flutter_upgrade_nested` executable) + +Recursively finds Flutter projects (by `pubspec.yaml`) and runs `flutter pub upgrade` in each. + +Run: + +```sh +flutter_upgrade_nested --dir /path/to/projects --major-versions --unlock-transitive +``` + +Options: + +- `-d, --dir ` – Root directory to search (default: current directory) +- `-m, --major-versions` – Allow major version upgrades +- `-t, --unlock-transitive` – Allow upgrading transitive dependencies +- `-h, --help` – Show help + +Use `-v/--verbose` (where available) for additional output. + +## License + +MIT