This library is a work in progress and open for contribution. The final destination for the
community supported and governed helper library implementing WalletConnect will be
@hashgraph/walletconnect
.
The main branch of this library is deprecated and was originally built utilizing the spec set out by the Hedera <> WalletConnect JSON-RPC spec.
There is an active discussion surrounding standardizing the "Integration of Wallet Connect 2.0 Protocol for Wallets and dApps on Hedera" via the HIP-820 discussion.
The release/hip-820
branch of this repo is the upstream branch of this repository as we
migrate to this spec.
We are working on this library as well as the WalletConnect Spec PR based on the results of HIP-820.
Please join the discussion!
This package managed by the Hedera community and is intended to be a standard for ecosystem
wallets and dApp providers utilizing WalletConnect as a their
communications protocol. It utilizes the
@hashgraph/sdk
and provides functions to
facilitate implementing the
Hedera <> WalletConnect JSON-RPC spec.
WalletConnect brings the ecosystem together by enabling wallets and apps to securely connect and interact.
This library facilitates the implementation of the Hedera <> WalletConnect 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 "them over the wire" to wallets for processing and return responses back to dApps.
A message could be one of:
- a Hedera network response
- an error message
- signed transaction bytes
- signed arbitrary set of bytes
Please note, this is distinct from the Implementation of Ethereum JSON-RPC APIs for Hedera. 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.
To start using WalletConnect, sign up for an account at https://cloud.walletconnect.com. You will use your project id when initializing client libraries.
It is important to understand core WalletConnect concepts when integrating this library. Please reference the WalletConnect documentation.
Upon successfully configuring your dApp and/or wallet to manage WalletConnect sessions, you can use this library’s functions to easily create and handle requests for the Hedera network.
This library provides a Wallet class that extends the Web3Wallet class provided by WalletConnect class provided by WalletConnect
WalletConnect emits various events during a session. Listen to these events to synchronize the state of your application:
// Handle pairing proposals
signClient.on('session_proposal', (event) => {
// Display session proposal to the user and decide to approve or reject
})
// Handle session requests, like signing transactions or messages
signClient.on('session_request', (event) => {
// Process the session request
})
// Handle session deletions
signClient.on('session_delete', (event) => {
// React to session termination
})
Pairing establishes a connection between the wallet and a dApp. Once paired, the dApp can send session requests to the wallet.
If a dApp shares a URI for pairing:
await signClient.core.pairing.pair({ uri: 'RECEIVED_URI' })
Upon successful pairing, the session_proposal
event will be triggered.
For a better user experience, dApps often share QR codes that wallets can scan to establish a pairing. Use a QR code scanning library to scan and obtain the URI, then proceed with pairing:
const scannedUri = '...' // URI obtained from scanning the QR code
await signClient.core.pairing.pair({ uri: scannedUri })
Upon receiving a session_proposal
event, display the proposal details to the user. Allow them
to approve or reject the session:
Upon receiving a session_request
event, process the request. For instance, if the dApp
requests a transaction to be signed: