From c00b89436da621243c55c3dd4b202076bb381e2f Mon Sep 17 00:00:00 2001
From: Govard Barkhatov <gbarkhatov@gmail.com>
Date: Tue, 17 Dec 2024 22:27:35 +0200
Subject: [PATCH] initial wallet integration docs

---
 .changeset/six-boxes-add.md |   5 ++
 README.md                   | 113 ++++++++++++++++++++++++++++++++++++
 2 files changed, 118 insertions(+)
 create mode 100644 .changeset/six-boxes-add.md

diff --git a/.changeset/six-boxes-add.md b/.changeset/six-boxes-add.md
new file mode 100644
index 0000000..6cf1797
--- /dev/null
+++ b/.changeset/six-boxes-add.md
@@ -0,0 +1,5 @@
+---
+"@babylonlabs-io/bbn-wallet-connect": patch
+---
+
+docs: add wallet integration guide
diff --git a/README.md b/README.md
index 6d15c18..f7ada93 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,10 @@
 </p>
 <br/>
 
+## Overview
+
+The Babylon Wallet Connector provides a unified interface for integrating both Bitcoin (BTC) and Babylon (BBN) wallets into Babylon dApp. It supports both native wallet extensions and injectable mobile wallets.
+
 ## Installation
 
 ```console
@@ -22,3 +26,112 @@ Stable release versions are manually released from the main branch.
 ```console
 npm run storybook
 ```
+
+## Wallet Integration
+
+This guide explains how to integrate wallets with the Babylon staking dApp. The dApp supports both Bitcoin (BTC) and Babylon (BBN) wallets through a unified interface.
+
+### Supported Wallet Types
+
+#### Bitcoin (BTC) Wallets
+
+Both native and injectable wallets require implementing `IBTCProvider` interface
+
+1. Native Wallets
+
+- Must submit a PR to add the implementation
+- Examples: `OKX` and `OneKey` Chrome Extensions, `Keystone` Hardware Wallet
+
+2. Injectable Wallets
+
+- No PR required
+- Must inject implementation into `window.btcwallet`
+- Common in mobile wallet browsers
+
+#### Babylon (BBN) Wallets
+
+Both native and injectable wallets require implementing `IBBNProvider` interface
+
+1. Native Wallets
+
+- Must submit a PR to add the implementation
+- Example: `Keplr`
+
+2. Injectable Wallets
+
+- No PR required
+- Must inject implementation into `window.bbnwallet`
+- Common in mobile wallet browsers
+
+### Integration Process
+
+#### 1. Implement Provider Interface
+
+Choose the appropriate interface based on your wallet type:
+
+```ts
+// For BTC wallets
+interface IBTCProvider {
+  connectWallet(): Promise<void>;
+  getAddress(): Promise<string>;
+  getPublicKeyHex(): Promise<string>;
+  signPsbt(psbtHex: string): Promise<string>;
+  signPsbts(psbtsHexes: string[]): Promise<string[]>;
+  getNetwork(): Promise<Network>;
+  signMessage(message: string, type: "ecdsa"): Promise<string>;
+  getInscriptions(): Promise<InscriptionIdentifier[]>;
+  on(eventName: string, callBack: () => void): void;
+  off(eventName: string, callBack: () => void): void;
+  getWalletProviderName(): Promise<string>;
+  getWalletProviderIcon(): Promise<string>;
+}
+
+// For BBN wallets
+interface IBBNProvider {
+  connectWallet(): Promise<void>;
+  getAddress(): Promise<string>;
+  getPublicKeyHex(): Promise<string>;
+  getOfflineSigner(): Promise<OfflineAminoSigner & OfflineDirectSigner>;
+  getWalletProviderName(): Promise<string>;
+  getWalletProviderIcon(): Promise<string>;
+}
+```
+
+#### 2. Integration Method
+
+For Native Wallets:
+
+1. Create wallet provider implementation
+2. Create wallet metadata file
+3. Submit PR to add your wallet
+
+Example metadata for BTC wallet:
+
+```ts
+const metadata: WalletMetadata<IBTCProvider, BTCConfig> = {
+  id: "wallet-id",
+  name: WALLET_PROVIDER_NAME,
+  icon: logo,
+  docs: "https://docs.example.com",
+  wallet: "window-key", // Global window key to detect wallet
+  createProvider: (wallet, config) => new WalletProvider(wallet, config),
+  networks: [Network.MAINNET, Network.SIGNET], // Supported networks
+};
+```
+
+For Injectable Wallets:
+
+1. Implement provider interface
+2. Inject into `window` before loading dApp:
+
+```ts
+// For BTC wallets
+window.btcwallet = new BTCWalletImplementation();
+
+// For BBN wallets
+window.bbnwallet = new BBNWalletImplementation();
+```
+
+### Integration Through Tomo Connect SDK Lite
+
+In addition to direct integration, wallets can also be integrated through [Tomo Connect SDK Lite](https://docs.tomo.inc/tomo-sdk/tomo-connect-sdk-lite).