@hashgraph/hedera-wallet-connect 1.5.2-canary.8dde86c.0 → 1.5.2-canary.90511fb.0

package/README.md

@@ -1,70 +1,238 @@
-# Overview
+# Background
+
+This library provides tools and recommendations on how to integrate Hedera into an application
+that requires communication with a wallet that supports Hedera. There are 2 different paths to
+integrate Hedera in this context. Both approaches use the
+[WalletConnect](https://walletconnect.network/) network to send messages from apps to wallets
+and back.
+
+## Hedera APIs
+
+Hedera natively operates using a gRPC API for write transactions and by default, a REST API for
+read transactions. Hedera implements EVM compatible smart contracts using
+[Hyperledger Besu](https://besu.hyperledger.org/) under the hood.
+
+Ethereum developers and toolsets often expect to interact with Ethereum compatible chains using
+the [Ethereum JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/). To acheive
+compatibility with this API,
+[Hedera JSON-RPC Providers](https://docs.hedera.com/hedera/core-concepts/smart-contracts/json-rpc-relay#community-hosted-json-rpc-relays)
+operate a software middlelayer that translates Ethereum JSON-RPC compatible API calls into
+Hedera gRPC and REST API calls.
 
-This library is the result of Hedera community collaboration to bring Hedera into the
-WalletConnect ecosystem and vice versa.
+## Ethereum JSON-RPC vs. Hedera JSON-RPC vs. Hedera JSON-RPC Relay
 
-The goal of this repository is to be a reference for wallets and dApps integrating the
-WalletConnect <> Hedera JSON-RPC reference. Additionally, this library is meant to be included
-in projects supporting WalletConnect and Hedera, providing utility functions useful to
-validating requests and resposes in both the WalletConnect JSON-RPC context as well as the
-Hedera context.
+When integrating, app developers can choose to use the Hedera native approach and send
+transactions to wallets over the WalletConnect network using the JSON-RPC spec defined for
+Hedera native transactions or use Ethereum JSON-RPC calls sent to a Hedera JSON-RPC Relay
+provider which then communicates with Hedera consensus and mirror nodes.
 
-A few useful resources include:
+On a high level, JSON-RPC is a type of API stucture, such as SOAP, gRPC, REST, GraphQL, etc. In
+the Hedera ecosystem, there are distinct concepts regarding JSON-RPC APIs to consider:
 
-- [HIP-820](https://hips.hedera.com/hip/hip-820)
-- [WalletConnect <> Hedera JSON-RPC spec](https://specs.walletconnect.com/2.0/blockchain-rpc/hedera-rpc).
+- Ethereum JSON-RPC spec defines how to interact with Ethereum compatible networks
+- Hedera JSON-RPC Relay implements the Ethereum JSON-RPC spec for Hedera
+- Wallets in the Hedera ecosystem also support a separate specification that defines how to send
+  transactions and messages to wallets over the WalletConnect network without relying on a
+  Hedera JSON-RPC Relay provider. This is a Hedera specific specification defined for utilizing
+  the WalletConnect network distict from other JSON-RPC specs such as the one defined by the
+  Ethereum network.
 
-> WalletConnect brings the ecosystem together by enabling wallets and apps to securely connect
-> and interact.
->
-> -- <cite> https://walletconnect.com
+For more information see:
 
-Hedera aims to be:
-
-> The open source public ledger for everyone
->
-> -- <cite> https://hedera.com
-
----
-
-This package managed by the Hedera community and is intended to be a standard for ecosystem
-wallets and dApp providers utilizing [WalletConnect](https://walletconnect.com) as a their
-communications protocol. It utilizes the
-[`@hashgraph/sdk`](https://www.npmjs.com/package/@hashgraph/sdk) and provides functions to
-facilitate implementing the
-[WalletConnect <> Hedera JSON-RPC spec](https://specs.walletconnect.com/2.0/blockchain-rpc/hedera-rpc)
-which has been defined through the collaborative HIP process in
-[HIP-820](https://hips.hedera.com/hip/hip-820).
-
-This library facilitates the implementation of the **WalletConnect <> Hedera Spec** which allows
-wallets and dApps to natively integrate with Hedera. It provides additional, out of network
-functionality with the `hedera_signMessage` function.
-
-In short, it uses the Hedera javascript SDK to build transactions, serialize them, send to
-wallets for processing and return responses back to dApps.
-
-_Please note, this is distinct from the
-[Implementation of Ethereum JSON-RPC APIs for Hedera](https://github.com/hashgraph/hedera-json-rpc-relay).
-At the time of this writing, "the Hedera JSON-RPC relay implementation is in beta, offers
-limited functionality today, and is only available to developers."_
-
-_The relay and this library have different intentions and serve different purposes - namely
-native Hedera integration vs. Ethereum compatability layers to ease developer onboarding for
-those more familiar with the Ethereum ecosystem._
-
-# Documentation
-
-WalletConnect <> Hedera docs are fully hosted on [https://hwc-docs.hgraph.app/](https://hwc-docs.hgraph.app/)
-
-- [Installation](/docs/docs/installation.md)
-- [dApp Guide](/docs/docs/dapp-guide.md)
-- [Wallet Guide](/docs/docs/wallet-guide.md)
-- [Signing Messages](/docs/docs/sign-messages.md)
-- [Demos](/docs/docs/demos.md)
-
-# Accessing the docs locally
-
-- `cd docs`
-- `npm install`
-- `npm run docs`
-- Navigating to `localhost:3000`
+- [Ethereum JSON-RPC Specification ](https://ethereum.github.io/execution-apis/api-documentation/)
+- [Hedera JSON-RPC relay](https://docs.hedera.com/hedera/core-concepts/smart-contracts/json-rpc-relay)
+- [Hedera Native JSON-RPC spec for WalletConnect](https://docs.reown.com/advanced/multichain/rpc-reference/hedera-rpc)
+- [Hedera Javascript SDK](https://www.npmjs.com/package/@hashgraph/sdk)
+- [Reown Docs](https://docs.reown.com/overview)
+- [WalletConnect Network](https://walletconnect.network/)
+
+# Getting started
+
+In addition to choosing between the Hedera native JSON-RPC spec and the Ethereum JSON-RPC spec,
+when building with javascript/typescript, there are 2 supported options to utilize the
+WalletConnect network to send information from apps to wallets and back.
+
+This README assumes an understanding of Hedera as well as the WalletConnect network and focusses
+on how to send a payload to a wallet for processing and presentation to an end user that is a
+Hedera account holder. We recommend reviewing the [Hedera Docs](https://docs.hedera.com/) and
+first submitting transactions directly to the Hedera network without requiring interaction with
+a [Wallet](#hedera-wallets) when integrating Hedera for the first time. We also recommend
+reviewing the [Reown docs](https://docs.reown.com/overview).
+
+## Using this library and underlying WalletConnect libraries directly
+
+1. Add Hedera dependencies to your project:
+
+```sh
+npm install @hashgraph/hedera-wallet-connect@2.0.0-canary.811af2f.0 @hashgraph/sdk @walletconnect/modal
+```
+
+2. Initialize dApp Connector
+
+```typescript
+import {
+  HederaSessionEvent,
+  HederaJsonRpcMethod,
+  DAppConnector,
+  HederaChainId,
+} from '@hashgraph/hedera-wallet-connect'
+import { LedgerId } from '@hashgraph/sdk'
+
+const metadata = {
+  name: 'Hedera Integration using Hedera DAppConnector - v1 approach',
+  description: 'Hedera dAppConnector Example',
+  url: 'https://example.com', // origin must match your domain & subdomain
+  icons: ['https://avatars.githubusercontent.com/u/31002956'],
+}
+
+const dAppConnector = new DAppConnector(
+  metadata,
+  LedgerId.Mainnet,
+  projectId,
+  Object.values(HederaJsonRpcMethod),
+  [HederaSessionEvent.ChainChanged, HederaSessionEvent.AccountsChanged],
+  [HederaChainId.Mainnet, HederaChainId.Testnet],
+)
+
+await dAppConnector.init({ logger: 'error' })
+```
+
+3. Connect to a wallet
+
+```typescript
+await dAppConnector.openModal()
+```
+
+4. Handle sessions, events, and payloads.
+
+- See: [DAppConnector](./src/lib/dapp/index.ts)
+
+### Examples, demos, and tools
+
+- [Hashgraph React Wallets by Buidler Labs](https://github.com/buidler-labs/hashgraph-react-wallets)
+- [Hashgraph Online's WalletConnect SDK](https://github.com/hashgraph-online/hashinal-wc)
+- <em>[Add an example, demo, or tool here](https://github.com/hashgraph/hedera-wallet-connect/pulls)</em>
+
+## Using Reown's AppKit
+
+1. Follow one of the quickstart instructions at
+   https://docs.reown.com/appkit/overview#quickstart
+
+2. Add Hedera dependencies to your project:
+
+```sh
+npm install @hashgraph/hedera-wallet-connect@2.0.1-canary.24fffa7.0 @hashgraph/sdk @walletconnect/universal-provider
+```
+
+3. Update `createAppKit` with adapters and a universal provider for Hedera. Note the
+   HederaAdapter will need to come before the WagmiAdapter in the adapters array.
+
+```typescript
+import type UniversalProvider from '@walletconnect/universal-provider'
+
+import {
+  HederaProvider,
+  HederaAdapter,
+  HederaChainDefinition,
+  hederaNamespace,
+} from '@hashgraph/hedera-wallet-connect'
+
+const metadata = {
+  name: 'AppKit w/ Hedera',
+  description: 'Hedera AppKit Example',
+  url: 'https://example.com', // origin must match your domain & subdomain
+  icons: ['https://avatars.githubusercontent.com/u/179229932']
+}
+
+const hederaEVMAdapter = new HederaAdapter({
+  projectId,
+  networks: [
+    HederaChainDefinition.EVM.Mainnet,
+    HederaChainDefinition.EVM.Testnet,
+],
+  namespace: 'eip155',
+})
+
+const universalProvider = (await HederaProvider.init({
+  projectId: "YOUR_PROJECT_ID"
+  metadata,
+})) as unknown as UniversalProvider, // avoid type mismatch error due to missing of private properties in HederaProvider
+
+// ...
+createAppKit({
+  adapters: [ hederaEVMAdapter ],
+  //@ts-expect-error expected type error
+  universalProvider,
+  projectId,
+  metadata,
+  networks: [
+    // EVM
+    HederaChainDefinition.EVM.Mainnet,
+    HederaChainDefinition.EVM.Testnet,
+  ],
+})
+
+// ...
+```
+
+4. Recommended: Add Hedera Native WalletConnect Adapter
+
+```typescript
+import { HederaChainDefinition, hederaNamespace } from '@hashgraph/hedera-wallet-connect'
+
+// ...
+
+const hederaNativeAdapter = new HederaAdapter({
+  projectId,
+  networks: [HederaChainDefinition.Native.Mainnet, HederaChainDefinition.Native.Testnet],
+  namespace: hederaNamespace, // 'hedera' as CaipNamespace,
+})
+
+// ...
+
+createAppKit({
+  adapters: [hederaEVMAdapter, hederaNativeAdapter],
+  projectId,
+  metadata,
+  networks: [
+    // EVM
+    HederaChainDefinition.EVM.Mainnet,
+    HederaChainDefinition.EVM.Testnet,
+    // Native
+    HederaChainDefinition.Native.Mainnet,
+    HederaChainDefinition.Native.Testnet,
+  ],
+})
+```
+
+### Examples, demos, and tools
+
+- [Hedera App Example by Hgraph](https://github.com/hgraph-io/hedera-app)
+- [Hedera Wallet Example by Hgraph](https://github.com/hgraph-io/hedera-wallet)
+- <em>[Add an example, demo, or tool here](https://github.com/hashgraph/hedera-wallet-connect/pulls)</em>
+
+# Hedera Wallets
+
+- [Hashpack](https://hashpack.app/)
+- [Kabila](https://wallet.kabila.app/)
+- [Blade](https://bladewallet.io/)
+- [Dropp](https://dropp.cc/)
+
+# Upgrading from v1 to v2
+
+Upgrading from v1 to v2 should be fairly straightforward. We have maintained compatibility with
+the v1 structure, while deprecating a few methods marked as deprecated. The v1 library did not
+explicitly offer support for Ethereum JSON-RPC function calls, so the only breaking changes
+refer to how to send transactions to wallets using the `hedera:(mainnet|testnet)` namespace.
+While minimal, the main breaking changes are:
+
+- remove WalletConnect v1 modals
+
+  - these are very old, though in the spirit of semver, we kept the dependency until this
+    library's v2 release
+
+- remove setting node id's within this library for transactions
+
+  - initially, a transaction created by the Hedera Javascript SDK needed to have one or more
+    consensus node ids set to be able to serialize into bytes, sent over a network, and
+    deserialized by the SDK

package/dist/lib/shared/utils.d.ts

@@ -30,9 +30,10 @@ export declare function transactionToBase64String<T extends Transaction>(transac
 export declare function base64StringToTransaction<T extends Transaction>(transactionBytes: string): T;
 /**
  * @param transaction - a base64 encoded string of proto.TransactionBody.encode().finish()
+ * @param nodeAccountId - an optional `AccountId` to set the node account ID for the transaction
  * @returns `string`
  * */
-export declare function transactionToTransactionBody<T extends Transaction>(transaction: T): any;
+export declare function transactionToTransactionBody<T extends Transaction>(transaction: T, nodeAccountId?: AccountId | null): proto.ITransactionBody;
 export declare function transactionBodyToBase64String(transactionBody: proto.ITransactionBody): string;
 /**
  * @param transactionList - a proto.TransactionList object

package/dist/lib/shared/utils.js

@@ -55,12 +55,13 @@ export function base64StringToTransaction(transactionBytes) {
 }
 /**
  * @param transaction - a base64 encoded string of proto.TransactionBody.encode().finish()
+ * @param nodeAccountId - an optional `AccountId` to set the node account ID for the transaction
  * @returns `string`
  * */
-export function transactionToTransactionBody(transaction) {
+export function transactionToTransactionBody(transaction, nodeAccountId = null) {
     // This is a private function, though provides the capabilities to construct a proto.TransactionBody
     //@ts-ignore
-    return transaction._makeTransactionBody(null);
+    return transaction._makeTransactionBody(nodeAccountId);
 }
 export function transactionBodyToBase64String(transactionBody) {
     return Uint8ArrayToBase64String(proto.TransactionBody.encode(transactionBody).finish());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashgraph/hedera-wallet-connect",
-  "version": "1.5.2-canary.8dde86c.0",
+  "version": "1.5.2-canary.90511fb.0",
   "description": "A library to facilitate integrating Hedera with WalletConnect",
   "repository": {
     "type": "git",
@@ -22,8 +22,8 @@
     "@hashgraph/hedera-wallet-connect": "^1.5.0",
     "@swc/core": "^1.7.40",
     "@swc/jest": "^0.2.36",
-    "@types/jest": "^29.5.3",
-    "@types/node": "^22.5.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.3",
     "@types/react-dom": "^19.0.3",
     "@walletconnect/modal": "^2.7.0",
     "@walletconnect/sign-client": "^2.19.1",
@@ -32,9 +32,7 @@
     "esbuild": "^0.25.0",
     "esbuild-plugin-copy": "^2.1.1",
     "eslint-plugin-tsdoc": "^0.4.0",
-    "husky": "^9.0.6",
-    "jest": "^29.7.0",
-    "lint-staged": "^15.1.0",
+    "jest": "^30.0.0",
     "lokijs": "^1.5.12",
     "long": "^5.2.3",
     "nodemon": "^3.0.3",
@@ -44,29 +42,18 @@
     "rimraf": "^5.0.5",
     "ts-node": "^10.9.2",
     "tweetnacl": "^1.0.3",
-    "typedoc": "^0.27.6",
-    "typedoc-theme-hierarchy": "^5.0.0",
     "typescript": "^5.2.2"
   },
   "scripts": {
     "build": "rimraf dist && tsc",
-    "build:ts-demo": "node scripts/demos/typescript/build.mjs",
-    "build:react-demo": "node scripts/demos/react/build.mjs",
-    "build:docs": "typedoc --options typedoc.json",
     "watch": "nodemon --watch src/lib/ --ext ts --exec \"npm run build\"",
-    "dev": "npm run dev:ts-demo",
-    "dev:docs": "cd docs && npm run start",
-    "dev:ts-demo": "rimraf dist && npm run build && concurrently --raw \"npm run watch\" \"node scripts/demos/typescript/dev.mjs\"",
-    "dev:react-demo": "rimraf dist && npm run build && concurrently --raw \"npm run watch\" \"node scripts/demos/react/dev.mjs\"",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:connect": "jest --testMatch '**/DAppConnector.test.ts' --verbose",
     "test:signer": "jest --testMatch '**/DAppSigner.test.ts' --verbose",
     "prepublishOnly": "rm -Rf dist && npm run build",
-    "prepare": "husky install",
     "prettier:check": "prettier --check ./src/",
     "prettier:fix": "prettier --write ./src/",
-    "prod:docs-docker": "sh docker-run.sh",
     "test:sigMap": "jest --testMatch '**/SignatureMapHelpers.test.ts' --verbose",
     "test:coverage": "jest --coverage",
     "test:coverage:html": "jest --coverage --coverageReporters='text-summary' --coverageReporters='html'"