docs: 📝 Connecting & watching account.

archethic-foundation · Dec 4, 2024 · 6c36367 · 6c36367
1 parent 9307bdf
commit 6c36367
Show file tree

Hide file tree

Showing 10 changed files with 451 additions and 244 deletions.
diff --git a/docs/build/dapp/01-introduction.md b/docs/build/dapp/01-introduction.md
@@ -0,0 +1,53 @@
+---
+id: introduction
+title: Howto create a DApp
+sidebar_label: Introduction
+---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+This documentation aims to guide beginner and intermediate developers in integrating with **Archethic Wallet** (**aeWallet**). It explains various communication methods and includes code snippets in **Dart (Flutter)** and **TypeScript**.
+
+
+## Introduction
+
+Archethic wallets enable **DApps (Decentralized Applications)** to interact with the Archethic blockchain. This interaction is essential for:
+
+- Signing transactions.
+- Managing accounts.
+
+While keeping your secrets protected in **aeWallet**.
+
+
+## Communication Channels
+
+Below are the supported communication methods with Archethic wallets:
+
+| **DApp platform**         | **aeWallet platform**     | **Channel**                   | **Typescript Lib**    | **Flutter Lib**          |
+|---------------------------|---------------------------|-------------------------------|-----------------------|-----------------------|
+| Web (Desktop browser)     | Desktop                   | WebSocket                     | ✅                    | ✅                     |
+| Web (aeWallet browser)    | Mobile                    | Web Message Channel           | ⛔️ Not implemented yet| ⛔️ Not implemented yet |
+| Web (Desktop browser)     | Chrome Extension          | Web Message Channel           | ✅                    | ✅                     |
+| Desktop                   | Desktop                   | WebSocket                     | ✅                    | ✅                     |
+| Mobile                    | Mobile                    | DeepLink                      | ⛔️                    | ✅                     |
+
+
+:::info
+Currently, the primary use case is **web desktop DApps** running in browsers like Chrome. In the future, a mobile wallet will support DApps through an embedded browser.
+:::
+
+
+
+## Tools and Libraries
+
+- **Flutter/Dart:** [archethic_lib_dart](https://pub.dev/packages/archethic_lib_dart)
+- **TypeScript:** [@archethicjs/sdk](https://www.npmjs.com/package/@archethicjs/sdk)
+
+
+## Additional Resources
+
+- [archethic_wallet_client on pub.dev](https://pub.dev/packages/archethic_wallet_client)
+- [archethic_lib_dart on pub.dev](https://pub.dev/packages/archethic_lib_dart)
+- [@archethicjs/sdk on npm](https://www.npmjs.com/package/@archethicjs/sdk)
+
diff --git a/docs/build/dapp/02-getting-started.md b/docs/build/dapp/02-getting-started.md
@@ -0,0 +1,37 @@
+---
+id: getting-started
+title: Installation/Connection
+sidebar_label: Getting started
+---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Installing library
+
+<Tabs groupId="sdk">
+<TabItem value="typescript" label="TypeScript" >
+
+```shell
+npm install @archethicjs/sdk
+```
+
+</TabItem>
+<TabItem value="flutter" label="Flutter">
+
+```shell 
+flutter pub add archethic_wallet_client
+```
+
+</TabItem>
+</Tabs>
+
+## Setup Deeplink channel
+
+:::note
+For a **mobile DApp** to communicate with **aeWallet mobile**, the only communication channel is the deeplink.
+:::
+
+:::tip
+This is required only if your **DApp** is an Android or iOS application.
+:::
+
diff --git a/docs/build/dapp/03-connecting.md b/docs/build/dapp/03-connecting.md
@@ -0,0 +1,120 @@
+---
+id: connecting
+title: Connecting aeWallet
+sidebar_label: Connecting aeWallet
+---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+
+This example attempts to connect to **aeWallet** and writes a log when connection status is updated.
+
+:::tip
+Ensure that the **aeWallet** application is **running and unlocked** before attempting connection.
+:::
+
+<Tabs groupId="sdk">
+<TabItem value="typescript" label="TypeScript" >
+
+```html title="index.html"
+<html>
+  <head>
+    <script type="module" src="main.js"/>
+  </head>
+</html>
+```
+
+```typescript title="main.js"
+import Archethic, { ConnectionState } from "https://esm.sh/@archethicjs/sdk";
+
+/// Creates an Archethic client.
+/// This checks aeWallet RPC available transport methods and creates 
+/// an ArchethicWalletClient accordingly.
+///  - If Archethic Wallet desktop is running and unlocked, Websocket will be used
+///  - If Archethic Wallet Chrome extension is installed, it will be opened
+const archethicClient = new Archethic()
+
+/// Listen to rpc wallet connection status changes
+archethicClient.rpcWallet.onconnectionstatechange(async (state) => {
+    switch (state) {
+        case ConnectionState.Connecting:
+            console.log("Connecting  ...")
+            break
+        case ConnectionState.Closed:
+            console.log("Connection closed")
+            break
+        case ConnectionState.Closing:
+            console.log("Disconnecting ...")
+            break
+        case ConnectionState.Open:
+            const { endpointUrl } = await archethicClient.rpcWallet.getEndpoint()
+            const walletAccount = await archethicClient.rpcWallet.getCurrentAccount()
+            console.log(`Connected as ${walletAccount.shortName} to ${endpointUrl}`)
+            break
+    }
+})
+
+/// Connect to aeWallet to check the selected chain.
+/// That chain will then be used by `archethicClient`.
+await archethicClient.connect()
+```
+
+</TabItem>
+<TabItem value="flutter" label="Flutter">
+
+By default, `ArchethicDAppClient` will check available communication channels, and choose the most appropriate one.
+
+Alternatively, you may force `ArchethicDAppClient` to use a specific communication channel using the dedicated factory (`ArchethicDAppClient.messageChannel()`, `ArchethicDAppClient.websocket()` ...).
+
+
+```dart
+import 'dart:developer';
+
+import 'package:archethic_wallet_client/archethic_wallet_client.dart';
+
+Future<void> main() async {
+  final aewalletClient = await ArchethicDAppClient.auto(
+    origin: const RequestOrigin(
+      name: 'FlutterDappExample',
+    ),
+    replyBaseUrl: 'flutterdappexample://dapp.example',
+  );
+
+  /// Do not forget to close that subscription later.
+  final connectionStateSubscription =
+      aewalletClient.connectionStateStream.listen((event) {
+    event.when(
+      connecting: () {
+        log('Connecting ...');
+      },
+      disconnected: () {
+        log('Connection closed');
+      },
+      disconnecting: () {
+        log('Disconnecting ...');
+      },
+      connected: () async {
+        final walletAccount =
+            await aewalletClient.getCurrentAccount().valueOrThrow;
+        final endpoint = await aewalletClient.getEndpoint().valueOrThrow;
+        log('Connected as ${walletAccount.shortName} to ${endpoint.endpointUrl}');
+      },
+    );
+  });
+
+  await aewalletClient.connect();
+
+  await Future.delayed(Duration(seconds: 1));
+
+  await aewalletClient.close();
+  connectionStateSubscription.cancel();
+}
+```
+
+</TabItem>
+</Tabs>
+
+
+
+
diff --git a/docs/build/dapp/04-watching-account.md b/docs/build/dapp/04-watching-account.md
@@ -0,0 +1,97 @@
+---
+id: watch-balance
+title: Watching account
+sidebar_label: Watching account
+---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+This example connects to **aeWallet** and watches any update to selected account.
+
+:::tip
+Ensure that the **aeWallet** application is **running and unlocked** before attempting connection.
+:::
+
+<Tabs groupId="sdk">
+<TabItem value="typescript" label="TypeScript" >
+
+```html title="index.html"
+<html>
+  <head>
+    <script type="module" src="main.js"/>
+  </head>
+</html>
+```
+
+```typescript title="main.js"
+import Archethic, { ConnectionState } from "https://esm.sh/@archethicjs/sdk";
+
+/// Creates an Archethic client.
+/// This checks aeWallet RPC available transport methods and creates 
+/// an ArchethicWalletClient accordingly.
+const archethicClient = new Archethic()
+
+/// Listen to rpc wallet connection status changes
+archethicClient.rpcWallet.onconnectionstatechange(async (state) => {
+    switch (state) {
+        case ConnectionState.Connecting:
+            console.log("Connecting  ...")
+            break
+        case ConnectionState.Closed:
+            console.log("Connection closed")
+            break
+        case ConnectionState.Closing:
+            console.log("Disconnecting ...")
+            break
+        case ConnectionState.Open:
+            const { endpointUrl } = await archethicClient.rpcWallet.getEndpoint()
+            const walletAccount = await archethicClient.rpcWallet.getCurrentAccount()
+            console.log(`Connected as ${walletAccount.shortName} to ${endpointUrl}`)
+            break
+    }
+})
+
+/// Connect to aeWallet to check the selected chain.
+/// That chain will then be used by `archethicClient`.
+await archethicClient.connect()
+```
+
+</TabItem>
+<TabItem value="flutter" label="Flutter">
+
+
+```dart
+import 'dart:convert';
+import 'dart:developer';
+
+import 'package:archethic_wallet_client/archethic_wallet_client.dart';
+
+Future<void> main() async {
+  final aewalletClient = await ArchethicDAppClient.auto(
+    origin: const RequestOrigin(
+      name: 'FlutterDappExample',
+    ),
+    replyBaseUrl: 'flutterdappexample://dapp.example',
+  );
+
+  final subscription =
+      await aewalletClient.subscribeCurrentAccount().valueOrThrow;
+  subscription.updates.listen((account) {
+    log('Account updated : ${jsonEncode(account.toJson())} ...');
+  });
+  await aewalletClient.connect();
+
+  await Future.delayed(Duration(seconds: 10));
+
+  await aewalletClient.unsubscribeCurrentAccount(subscription.id);
+  await aewalletClient.close();
+}
+```
+
+</TabItem>
+</Tabs>
+
+
+
+