Add unit tests examples suite organization

.gitignore

@@ -0,0 +1,12 @@
+# General
+.dart_tool/
+.packages
+build/
+doc/api/
+
+# IDE 
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -1,107 +1,100 @@
 
-# Accumulate Dart Client
+# Accumulate Dart SDK
 
 
-![Pub Version](https://img.shields.io/pub/v/accumulate_api)
-![GitHub](https://img.shields.io/github/license/kompendium-ano/accumulate-dart-client)
-[![Tests](https://github.com/kompendium-ano/accumulate-dart-client/actions/workflows/dart.yml/badge.svg)](https://github.com/kompendium-ano/accumulate-dart-client/actions/workflows/dart.yml)
+[![Pub Version](https://img.shields.io/pub/v/accumulate_api)](https://pub.dev/packages/accumulate_api)
+[![GitHub License](https://img.shields.io/github/license/kompendium-ano/accumulate-dart-client)](LICENSE)
+[![Build Status](https://github.com/kompendium-ano/accumulate-dart-client/actions/workflows/dart.yml/badge.svg)](https://github.com/kompendium-ano/accumulate-dart-client/actions/workflows/dart.yml)
 
-Dart client for [Accumulate](https://github.com/AccumulateNetwork/accumulate) blockchain, a novel blockchain network designed to be hugely scalable while maintaining security.
-This library supports all API class and basic data types that reflect network types and structures and utility functions to ease up creation of specific requests.
+The Dart SDK for the Accumulate blockchain provides developers with the tools needed to interact with the Accumulate network. This SDK supports all Accumulate API classes, basic data types, and utility functions for creating specific requests, aiming to simplify the development process for applications leveraging the Accumulate blockchain's scalable and secure infrastructure.
 
-Full API reference available here: https://docs.accumulatenetwork.io/accumulate/developers/api/api-reference
+The Accumulate Dart SDK repositiory is organized with three main strucutres:
+ - Client library: [lib](/lib/src/)
+ - Test Suite: [tests](/test/README.md/)
+ - Accumulate Usage Examples Collection: [examples](/examples/SDK_Usage_Examples/README.md/)  
 
 ## Installation
 
-With Dart:
-```
-$ dart pub add accumulate_api
-```
+### Dart
 
-With Flutter:
-```
-$ flutter pub add accumulate_api
+```bash
+dart pub add accumulate_api
 ```
 
-This will add a line like this to your package's pubspec.yaml (and run an implicit dart pub get):
+This adds `accumulate_api` to your package's `pubspec.yaml` file and runs an implicit `dart pub get`.
 
-```
-dependencies:
-  accumulate_api: any
-```
-Alternatively, your editor might support dart pub get or flutter pub get. Check the docs for your editor to learn more.
-Import it
+### Flutter
 
-Now in your Dart code, you can use:
+```bash
+flutter pub add accumulate_api
 ```
-import 'package:accumulate_api/accumulate_api.dart';
-```
-
-## Usage
 
+For both Dart and Flutter, ensure your `pubspec.yaml` reflects the correct dependency:
 
+```yaml
+dependencies:
+  accumulate_api: ^version
+```
 
-### 1. Generate Lite Identity
+Replace `^version` with the latest version of `accumulate_api`.
 
-```dart
-ACMEClient client = ACMEClient("https://testnet.accumulatenetwork.io/v2");
-var lid = LiteIdentity(Ed25519KeypairSigner.generate());
-```
+### Import the SDK
 
-### 2. Add ACME token from Faucet
+In your Dart code, import the package with:
 
 ```dart
-ACMEClient client = ACMEClient("https://testnet.accumulatenetwork.io/v2");
-var lid = LiteIdentity(Ed25519KeypairSigner.generate());
-final res = await client.faucet(lid.acmeTokenAccount);
+import 'package:accumulate_api/accumulate_api.dart';
 ```
 
+## Practical Usage Examples
 
-### 3. Add Credits to Lite Identity
+The Accumulate Dart SDK enables you to access nearly all the features and fucnitonality that accumualte offers.
+Explore practical examples in the [Examples](/examples/SDK_Usage_Examples/) section to start building with the Accumulate Dart SDK. This repository provides a suite of examples designed to demonstrate the capabilities and functionalities of the Accumulate protocol, offering developers a hands-on experience to better understand how to interact with the network effectively.
 
-```dart
-int creditAmount = 60000;
-AddCreditsParam addCreditsParam = AddCreditsParam();  
-addCreditsParam.recipient = lid.url;  
-addCreditsParam.amount = (creditAmount * pow(10, 8)) ~/ oracle;  
-addCreditsParam.oracle = await client.valueFromOracle();  
-await client.addCredits(lid.url, addCreditsParam, lid);
-```
+The Usage Example Suite currently consists of 6 collections of example sets:
+#### 1. Lite Identities and Lite Token Accounts
+- Create/manage Lite Identities/Accounts for ACME tokens
+- Acquire testnet ACME tokens via faucet
+- Add credits to Lite Identities
+- Create Lite Token Accounts for ACME
+- Transfer ACME tokens between Lite Accounts
 
+#### 2. Accumulate Digital Identifier (ADI)
+- Create ADI Identity
+- Add credits to Key Page
 
-### 4. Send ACME token to another Lite ACME token account
+#### 3. ADI Token Accounts
+- Create ADI Token Accounts for ACME
+- Transfer ACME tokens between ADI Accounts and to Lite Accounts
 
-```dart
-int sendToken = 10000;
-final recipient =  
-    LiteIdentity(Ed25519KeypairSigner.generate()).acmeTokenAccount;  
-SendTokensParam sendTokensParam = SendTokensParam();  
-TokenRecipientParam tokenRecipientParam = TokenRecipientParam();  
-tokenRecipientParam.amount = sendToken * pow(10, 8);  
-tokenRecipientParam.url = recipient;  
-sendTokensParam.to = List<TokenRecipientParam>.from([tokenRecipientParam]);  
-await client.sendTokens(lid.acmeTokenAccount, sendTokensParam, lid);
+#### 4. ADI Data Accounts
+- Create/manage ADI Data Accounts
+- Write/manage data entries
+- Utilize scratch data entries and lite data accounts
 
-```
+#### 5. Custom Tokens
+- Create custom tokens under ADI
+- Create custom token accounts and issue tokens
+- Transfer custom tokens between ADI Custom Token Accounts
 
-### 5. Create ADI
-```dart
-final identitySigner = Ed25519KeypairSigner.generate();  
-var identityUrl = "acc://custom-adi-name";  
-final bookUrl = identityUrl + "/custom-book-name";  
-
-CreateIdentityParam createIdentityParam = CreateIdentityParam();  
-createIdentityParam.url = identityUrl;  
-createIdentityParam.keyBookUrl = bookUrl;  
-createIdentityParam.keyHash = identitySigner.publicKeyHash();  
-await client.createIdentity(lid.url, createIdentityParam, lid);
-```
+#### 6. Key Management
+- Manage keys for security/identity (ADI)
+- Create/additional/custom Key Books/Pages
+- Update Key Page (add keys)
 
 
 ## Contributions
-The Library developed by Kompendium, LLC in partnership with [Kelecorix, Inc](https://github.com/kelecorix) and [Sergey Bushnyak](https://github.com/sigrlami). Contributions are welcome, open new PR or submit new issue.
 
-#### Library developers:
-* Sergey Bushnyak <[email protected]>
-* Jimmy Jose <[email protected]>
+We welcome contributions from the community. To contribute, please submit a pull request or open an issue for discussion.
+
+### Maintainers
+
+- Sergey Bushnyak ([email protected])
+- Jimmy Jose ([email protected])
+- Jason Gregoire ([email protected])
+
+This library is developed by Kompendium, LLC in partnership with Kelecorix, Inc, and individual contributors like Sergey Bushnyak. Your contributions and feedback are welcome.
+
+## License
 
+This project is licensed under the [MIT License](LICENSE).

examples/SDK_Usage_Examples/README.md

@@ -0,0 +1,126 @@
+# Accumulate SDK Examples for Dart
+
+This repository provides a suite of examples for using the Dart SDK with the Accumulate network. These examples are designed to demonstrate the capabilities and functionalities of the Accumulate protocol, offering developers a hands-on experience to better understand how to interact with the network effectively.
+
+The Usage Example Suite currently consists of 6 example sets:
+- SDK_Examples_file_1_lite_identities.dart
+- SDK_Examples_file_2_Accumulate_Identities_(ADI).dart
+- SDK_Examples_file_3_ADI_Token_Accounts.dart
+- SDK_Examples_file_4_Data_Accounts_and_Entries.dart
+- SDK_Examples_file_5_Custom_Tokens.dart
+- SDK_Examples_file_6_Key_Management.dart
+
+## 🚀 Getting Started
+
+To get started with these examples, ensure that Dart is installed on your system. These standalone examples demonstrate various features of the Accumulate protocol, enabling safe interactions with the blockchain through the Accumulate testnet.
+
+Accumulate maintains multiple testnets (stable and developmental). This example suite was tested against the Accumulate Kermit testnet (stable) in February 2024, using the endpoint `https://testnet.accumulatenetwork.io/v2`.
+
+### Prerequisites
+
+- **Dart SDK**: Required to run the examples. If you haven't already, [install Dart](https://dart.dev/get-dart).
+- **Accumulate Testnet**: The examples are configured for the Accumulate testnet environment to minimize risks while exploring the functionalities.
+
+## 📁 Example Files Overview
+
+Each file in the suite is designed to introduce different aspects of the Accumulate protocol.
+
+### 1. **Lite Identities and Accounts**
+
+**File**: `SDK_Examples_file_1_lite_identities.dart`
+
+Lite identities serve as the entry point into the Accumulate network, offering a traditional blockchain address format. Lite identities can hold data and credits, which are used as a "gas-like" mechanism to pay for network transactions. Additionally, a lite identity can manage a lite token account for ACME tokens, the native token of the Accumulate network.
+
+**Highlights**:
+- Creation and management of Lite Identities and Accounts
+- Acquiring and transferring ACME tokens
+- Adding credits to Lite Token Accounts
+
+To run Lite Identities and Accounts examples
+```bash
+dart run SDK_Examples_file_1_lite_identities.dart
+```
+
+### 2. **ADI Identity**
+
+**File**: `SDK_Examples_file_2_Accumulate_Identities_(ADI).dart`
+
+Accumulate Digital Identifiers (ADIs) are versatile and dynamic, allowing comprehensive management and authorization functionalities. ADIs can control various account types, including token accounts, data accounts, and custom tokens, offering a broad range of business and data functionalities.
+
+**Focuses on**:
+- Creation of ADI identities
+- Management of key books and key pages
+- Adding credits to key pages
+
+To run ADI Identity examples
+```bash
+dart run SDK_Examples_file_2_Accumulate_Identities_(ADI).dart
+```
+
+### 3. **ADI Token Accounts**
+
+**File**: `SDK_Examples_file_3_ADI_Token_Accounts.dart`
+
+ADI Token Accounts are human-readable and controlled by an ADI's key book, facilitating ACME token transactions in a secure and efficient manner.
+
+**Teaches**:
+- Creation and management of ADI Token Accounts
+- Transactions between ADI Token Accounts and Lite Token Accounts
+
+To run ADI Token Accounts
+```bash
+dart run SDK_Examples_file_3_ADI_Token_Accounts.dart
+```
+
+### 4. **ADI Data Accounts**
+
+**File**: `SDK_Examples_file_4_Data_Accounts_and_Entries.dart`
+
+Accumulate's unique data account features enable easy data entry into the blockchain, supporting both legacy data constructs from the Factom Protocol and new scratch data entries for temporary storage.
+
+**Covers**:
+- Creation of ADI Data Accounts
+- Data entry management within Data Accounts
+
+To run Data and Lite Data Account Examples
+```bash
+dart run SDK_Examples_file_4_Data_Accounts_and_Entries.dart
+```
+
+### 5. **Custom Tokens**
+
+**File**: `SDK_Examples_file_5_Custom_Tokens.dart`
+
+Creating, issuing, and transferring custom tokens is simplified with Accumulate, requiring no smart contracts and offering flexibility for both business and personal use.
+
+**Explores**:
+- Custom token creation under an ADI
+- Account management and token issuance
+
+To run Custom Tokens Examples
+```bash
+dart run SDK_Examples_file_5_Custom_Tokens.dart
+```
+
+### 6. **Key Management**
+
+**File**: `SDK_Examples_file_6_Key_Management.dart`
+
+This example demonstrates key management functionalities essential for security and identity management within the Accumulate network.
+
+**Explores**:
+- Creation and management of Key Books and Key Pages
+- Addition and updating of keys for enhanced security
+
+To run ADI Key Management Examples
+```bash
+dart run SDK_Examples_file_6_Key_Management.dart
+```
+
+## 🤝 Support
+
+For support or further clarification, consult the [Accumulate official documentation](https://docs.accumulatenetwork.io/) or join the Accumulate community on [Discord](https://discord.gg/2kBcaxrB).
+
+## 📄 License
+
+These examples are shared under the MIT License, encouraging open and collaborative development.