Skip to content

Commit

Permalink
updated docs and readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@ArturLevchuk
ArturLevchuk committed Sep 25, 2024
1 parent ba387cc commit 546a5c5
Show file tree
Hide file tree
Showing 3 changed files with 460 additions and 103 deletions.
193 changes: 90 additions & 103 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1,25 @@
# Flutter Chain
<div align="center">

Flutterchain is a library that provides developers with a simple API to communicate with different blockchains and call smart contracts. It allows developers to easily integrate popular cryptocurrencies into their web 3.0 projects. By leveraging Flutterchain, developers can build powerful decentralized applications without needing to have an in-depth understanding of the underlying blockchain technology. With Flutterchain, developers can easily interact with smart contracts , send transfers , etc. It's an easy-to-use and flexible solution for developers looking to build blockchain-based applications.
![](https://i.ibb.co/zx28GX3/Flutter-Chain-Logo.png)

## Prerequisites
</div>

List any dependencies or prerequisites needed before getting started with this library.
- [About FlutterChain](#about-get)
- [Installing](#installing)
- [How To Use](#how-to-use)
- [Important Notes and Tips](#important-notes-and-tips)
- [Running Examples](#running-examples)
- [Contributing](#contributing)

- Node JS
- Installed webpack (js package)
- Installed watch (js package)
- Flutter
- Installed Android Studio and Android SDK (For Android dev)
- Installed Xcode (For IOS, Mac OS dev)

## Building
# About FlutterChain
FlutterChain is a library that provides developers with a simple API to communicate with different blockchains. It allows developers to easily integrate popular cryptocurrencies into their web 3.0 projects without needing to have an in-depth understanding of the underlying blockchain technology. With FlutterChain, developers can easily interact with smart contracts, send transfers, and perform various transaction types. It's an easy-to-use and flexible solution for developers looking to build blockchain-based applications.

Instructions for building the library from source code.
## Installing

1. Clone this repository: `git clone https://github.com/vlmoon99/flutterchain`
2. Navigate to the project root directory: `cd flutterchain`
3. Run `bash dev_build.sh` or `bash prod_build.sh` for building flutterchain lib
1. Add This code to the index.html For Web project

## How to use

1. Add This code to the head tag For Web project

```
```html
<head>
<!-- other head elements -->
<script type="application/javascript" src="flutter.js" defer></script>
Expand Down Expand Up @@ -58,108 +52,91 @@ Instructions for building the library from source code.
</body>
```

2. Set Android: minSdkVersion >= 19, compileSdk >= 34, AGP version >= 7.3.0 in the android/app/build.gradle file and add android:usesCleartextTraffic="true" in manifest
3. Add network permission to android manifest -
```
2. Set Android: minSdkVersion >= 19, compileSdk >= 34, AGP version >= 7.3.0 in the android/app/build.gradle file and add to the AndroidManifest.xml `usesCleartextTraffic` param and Internet permission:
```xml
<manifest> ...
<application> ...
android:usesCleartextTraffic="true"
</application>
<uses-permission android:name="android.permission.INTERNET"/>
```
4. Inject all dependencies as in a example with Modular or Get it , etc.
or use default constructor in provided classes (Not recommended)
5. Initialize the flutterchain library after WidgetsFlutterBinding.ensureInitialized() in the main function.
WidgetsFlutterBinding.ensureInitialized();
await initFlutterChainLib();
To perform all operations with the blockchain, you need to create a private and public key.
For this task, you have two options:
</manifest>
```

1.Creating the wallet with generated mnemonic (Using Trust Wallet Core) :
Wallet wallet = await cryptoLibrary.createWalletWithGeneratedMnemonic(walletName: walletName);
Alternatively, if you want to import a mnemonic from somewhere, you can use the following code:
Wallet wallet = await cryptoLibrary.createWalletByImportedMnemonic(mnemonic: mnemonic!, walletName: walletName);
4. Initialize the flutterchain library after WidgetsFlutterBinding.ensureInitialized() in the main function.
```dart
void main() {
WidgetsFlutterBinding.ensureInitialized();
initFlutterChainLib();
...
runApp(MyApp());
}
```

2.If you are only using services for signing and sending transactions, you can generate blockchainData using the following methods (In this example, I will be using the Near Blockchain):
final nearBlockChainService = NearBlockChainService.defaultInstance();
NearBlockChainData blockchainData = nearBlockChainService.getBlockChainDataFromMnemonic(your_mnemonic,your_passphrase);
## How to use

Once you have obtained the blockchainData containing the private and public key, you can easily communicate with the blockchain.
This library provides interfaces to interact with various blockchains. You can achieve this by using an implementation of `BlockChainService` or `BlockchainServiceWithSmartContractCallSupport` for your selected blockchain. For example:

You can use my library in a few ways. First of all, you can use it just for signing transactions. To sign any transaction, you need to use BlockchainServices. Currently, I only have support for the Near blockchain.
```dart
final service = NearBlockChainService.defaultInstance(); // NearBlockChainService implements BlockchainServiceWithSmartContractCallSupport
final amount = await service
.getWalletBalance(NearAccountInfoRequest(accountId: "test.near"));
```

final nearBlockChainService = NearBlockChainService.defaultInstance();
The library also includes its own wallet controller (`FlutterChainLibrary`), allowing you to create wallets for different blockchains simultaneously, securely store them and manage, and execute standardized operations like transferring coins or interacting with smart contracts (where supported by the blockchain). It also provides access to the blockchain specific methods interface. For example:

```dart
final flutterChainLibrary = FlutterChainLibrary.defaultInstance();
Retrieve all the necessary information for making a signed transaction:
// 1. Get Nonce and Blockhash information from the Near blockchain (or you can use your own implementation of this method).
final transactionInfo = await nearBlockChainService.getNonceAndBlockHashInfo(
accountId: fromAddress,
publicKey: publicKey,
);
final wallet = await flutterChainLibrary.createWalletWithGeneratedMnemonic(
walletName: "my wallet");
//2.Retrieve gas information.
final gas = BlockchainGas.gas[BlockChains.near];
final derivationPathData =
wallet.blockchainsData?[BlockChains.near]?.first.derivationPath;
//3.Define actions. All possible actions can be found in my assets/crypto-lib (JS project inside my library) NearBlockchain class
final actions = [
{
"type": "transfer",
"data": {"amount": NearFormatter.nearToYoctoNear(transferAmount)}
}
];
// call from FlutterChainLibrary
//4.Sign the action
final response = await flutterChainLibrary.sendTransferNativeCoin(
blockchainType: BlockChains.near,
derivationPathData: derivationPathData!,
walletId: wallet.id,
toAddress: "someAddress",
transferAmount: "1000",
);
final signedAction = await nearBlockChainService.signNearActions(
fromAddress: fromAddress,
toAddress: toAdress,
transferAmount: NearFormatter.nearToYoctoNear(transferAmount),
privateKey: privateKey,
gas: gas,
nonce: transactionInfo.nonce,
blockHash: transactionInfo.blockHash,
actions: actions,
);
//call from blockchainService interface
log("Result of signed the tx ${signedAction}");
final NearBlockChainService nearBlockChainService = flutterChainLibrary
.blockchainService
.blockchainServices[BlockChains.near] as NearBlockChainService;
//5.Send the transaction to the Near Blockchain and get the response (or use your own Near RPC network client).
final res = await nearBlockChainService.nearRpcClient.sendSyncTx([signedAction]);
log("Result of transaction executing -> ${res.toJson().toString()}");
// final NearBlockChainData blockChainData = wallet.blockchainsData![BlockChains.near]?.first as NearBlockChainData;
final NearBlockChainData blockChainData = await nearBlockChainService
.getBlockChainData(mnemonic: wallet.mnemonic) as NearBlockChainData;
Alternatively, you can use the entire library together. You can see the architecture in the draw.io file flutterchain_arch.drawio inside the library.
final response2 = await nearBlockChainService.sendTransferNativeCoin(
NearTransferRequest(
publicKey: blockChainData.publicKey,
privateKey: blockChainData.privateKey,
toAddress: "someAddress",
transferAmount: "1000",
),
);
(Important) To use my library together, make sure you are familiar with the DI (Dependency Injection) principles.
First, you can see an example inside my example folder at modules folder (example/lib/modules).
You can see how I initialized my dependencies in the .module.dart files.
After this, you can go to the components and pages (example/lib/modules/home/components/chains/near) and see how I use my library.
await flutterChainLibrary.deleteAllWallets();
```

In a nutshell, I have a library that contains BlockchainServices and some Repositories (currently only for the Wallet model).
I also have a stream with the current wallets.
The FlutterChainLibrary class provides a high level of API for using WEB 3.0. You can send transfers in native tokens, make smart contract calls, and more.
## Important Notes and Tips

For Example :
final response = cryptoLibrary.sendTransferNativeCoin(
walletId: walletId,
typeOfBlockchain: typeOfBlockchain,
toAddress: toAddress,
currentDerivationPath: currentDerivationPath,
transferAmount: NearFormatter.nearToYoctoNear(transferAmount),
);
`FlutterChainLibrary` and `BlockchainServiceWithSmartContractCallSupport`/`BlockchainService` implementations aren't singletons. Each time a new instance is created, a `jsVMService` (a service that handles blockchain operations behind the scenes) is also instantiated. For optimal performance, it is recommended to reuse the same instance of the blockchain service throughout your app. This can be easily managed by using dependency injection libraries like [flutter_modular](https://pub.dev/packages/flutter_modular) or [get_it](https://pub.dev/packages/get_it).

log(response.toJson().toString());
For more detailed information, refer to the [documentation](https://github.com/vlmoon99/flutterchain/tree/main/documentation) and tests. You'll find guidance on how to use FlutterChainLibrary or various BlockchainServices. Additionally, you can explore different use cases through the examples provided:

//The walletId is the wallet ID of wallets inside a walletsStream.
You take a wallet from there and also provide the blockchain
type and derivation path of the wallet (https://github.com/satoshilabs/slips/blob/master/slip-0044.md ,
https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki).
If you need some specific functionality for some blockchains - take it from FlutterChainService :
- [General example (FlutterChainLibrary wallet; Near, Bitcoin, Concordium blockchain services)](https://github.com/vlmoon99/flutterchain/tree/main/example)
- [Near Chain Signatures](https://github.com/vlmoon99/flutterchain/tree/main/chain_signatures_example)
- [Near Mintbase](https://github.com/vlmoon99/flutterchain/tree/main/mintbase_example)

final nearBlockChainService = cryptoLibrary.blockchainService
.blockchainServices[BlockChains.near] as NearBlockChainService?;

and use functions inside NearBlockChainService.
All data which this library collect saved in flutter_secure_storage package , you can read about it here(https://github.com/mogol/flutter_secure_storage).
You can easy implement your own repository using extends Repository<Wallet> on your class and make your own data storage.
You can see the architecture in the draw.io file flutterchain_arch.drawio inside the library.

## Running Examples

Expand All @@ -171,14 +148,24 @@ Instructions for running the included examples.

## Contributing

Instructions for contributing to this library.
Instructions for contributing to this library:

1. Fork this repository
2. Create a new branch: `git checkout -b my-new-branch`
3. Make changes and commit them: `git commit -m "My message"`
4. Push to the remote branch: `git push origin my-new-branch`
5. Create a pull request

## License
List any dependencies or prerequisites needed before getting started with editing this library:

- Node JS
- Flutter
- Installed Android Studio and Android SDK (For Android dev)
- Installed Xcode (For IOS, Mac OS dev)

Instructions for building the library from source code:

1. Clone this repository: `git clone https://github.com/vlmoon99/flutterchain`
2. Navigate to the project root directory: `cd flutterchain`
3. Run `bash build.sh` for building flutterchain lib

This project is licensed under the MIT License
Loading

0 comments on commit 546a5c5

Please sign in to comment.