integrating with WalletConnect to work with dapp

[devchenyan]

Table of Contents

• Overview of WalletConnect
  • WalletConnect Workflow
  • Resources
  • WalletConnect Cloud
  • WalletConnect SDK
• Expected Workflow
• UX/UI
• Design Decisions
  • Namepaces
• Roadmap

Currently, Neuron supports signing/sending transaction directly. But it can't give support to dApps on the CKB Network.

Overview of WalletConnect

WalletConnect is an open-source protocol that enables secure and seamless communication between decentralized applications (dApps) and wallets on various blockchains. By establishing a remote connection using end-to-end encryption, WalletConnect allows users to interact with dApps through their preferred wallet without exposing their private keys.

So we consider integrating WalletConnect to achieve collaboration with dapp quickly.

WalletConnect Workflow

User visits a new website that requires a Sign session for submitting transactions and Auth for authentication

• dApp displays QRCode or deep link
  • A connection is established with a Relay server and a topic is subscribed
  • A session_proposal message is sent on the channel
• User scans QRCode or redirects to wallet (deep-link)
  • The wallet connects to the same relay server and the same topic is subscribed
• Popup with session proposal and authentication request appears on the Wallet
  • The wallet can either accept or reject the proposal
• User approves session request and authenticates
• User returns to website after prompt success
• User is now authenticated and has a sign session established with the dApp

Once the connection is established, the Dapp will be able to send any JSON-RPC call requests to be handled by the Wallet either to read data from its node or make signing requests for transactions or messages.

Resources

Github: https://github.com/WalletConnect
Docs: https://docs.walletconnect.com/2.0/
Sign Reference API: https://docs.walletconnect.com/2.0/specs/clients/sign/client-api

WalletConnect Cloud

The javascript SDK requires a projectId which is supposed to be registered at their WalletConnect cloud.

WalletConnect SDK

WalletConnect consists of two SDKs available for both the dApps and the Wallets: Web3Modal and Web3Wallet:

Web3Modal is a library that makes it easy to connect users to your dApp and interact with the blockchain

It's used to display a HTML popup with the QRCode containing the URI for the peering, it uses the core library to generate the necessary attributes.

Web3Wallet simplifies the process of integrating wallets into dApps by combining the Sign and Auth APIs into a single module

The web3wallet library is used on the Wallets for the pairing and message exchange

Web3Wallet SDK

The Web3Wallet SDK allows you to easily connect your Web3 wallet with dApps. It provides a simple and intuitive interface for dApps to request actions such as signing transactions and interacting with smart contracts on the blockchain. The SDK is designed to work with any blockchain, making it easy to support multiple chains without the need for separate integration code. (https://docs.walletconnect.com/2.0/web3wallet/about)

It's basically a library that provides a single API for the Sign API and the Auth API

Expected Workflow

User is able to connect to a WalletConnect wallet supporting ckb blockchain from a dapp using the ckb provider.

User should be able:

• getAddresses- User can expose Wallet addresses to the Dapps
• signTransaction - Dapp can request User to sign transactions from Wallet
• signMessage - Dapp can request User to sign messages from Wallet

These are the core user flows that is expected to support through WalletConnect protocol. Any other JSON-RPC methods should be able to be proxied either directly through the wallet or routed directly to a remote node.

Screen-2023-07-26-.124753.mp4

sequenceDiagram
    Dapp ->> + Wallet : connect
    Wallet ->> + User : request authorization
    User -->> Wallet : User approved
    Wallet -->> Dapp : Connect Success

    Dapp ->> + Wallet : sign login message
    Wallet ->> + User : request authorization
    User -->> Wallet : User approved
    Wallet -->> Dapp : signature

    par sign Transaction
        Dapp ->> + Wallet : sign transaction
        Wallet ->> + User : request authorization
        User -->> Wallet : User approved
        Wallet -->> Dapp : transaction
    and get addresses
        Dapp ->> + Wallet : get addresses
        Wallet -->> Dapp : address[]
    end

    Dapp ->> + Wallet : disconnect
        Wallet -->> Dapp : disconnected

Loading

UX/UI

Screen-2023-10-11-095209.mp4

UX Design

https://vs0cjf.axshare.com/#id=psrijc&p=walletconnect-general&g=1

UI Design

TBD

Design Decisions

Namepaces

A namespace is a standardized object defined by the Chain Agnostic Improvement Proposal (CAIP) that ensures a common industry standard for chain agnostic purposes. You will encounter two namespaces: the proposal namespace and the session namespace when connects wallets and dapps.

Namespaces for WalletConnect was created and can be read (and reviewed) .

Here is an example of a session approval message, passing the namespace.

{
  ...
    "namespaces": {
      "ckb": {
        "accounts": [ "ckb:mainnet:xxxxx..." ]
        "chains": [ "ckb:mainnet" ],
        "events": [],
        "methods": [
          "ckb_signTransaction"
        ]
      }
    }
  ...
}

Roadmap

Task	Duraion	Timeline
Wallet Reference Document	3 weeks	5.9 - 5.31
Wallet Document/UX Design	5 weeks	5.17 - 5.31
Communicate & QA	6 weeks	5.31 - 7.6
Dapp & Neuron Demo Design	1 week	7.6 - 7.13
Dapp & Neuron Demo Development	2 weeks	7.14 - 7.28
Communicate & QA	1 week	7.28 - 8.4
Documents（rfc, UX, sdk）	2 weeks	8.9 - 8.25
WalletConnect Wallet SDK Development	2 weeks	8.28 - 9.11
WalletConnect Wallet SDK review & test	1 week	9.4 - 9.18
WalletConnect SDK Development	1 week	9.19 - 9.26
WalletConnect SDK review & test	1 week	9.27 - 10.13
Wallet UI Design	3 weeks	8.29 - 9.19
Neuron Development	2 weeks	10.16 - 10.30
Neuron review & test	2 week	10.31 - 11.14
dApp Development	TBD	TBD
Testing & QA	TBD	TBD

[homura]

here is a PoC to show

• connect and fetch the first address
• sign custom message with the first address

neuron-walletconect.mov

[Sven-TBD]

I've designed a prototype for this integration including establishing a connection and initializing a transaction. The prototype links is below: https://vs0cjf.axshare.com/#id=oodwon&p=walletconnect&g=1

[homura]

There is a brand-new protocol with a set of contracts created that attempts to create an authentication pattern between dApp and wallets.

The new lock defines a new witness shape that introduces a human-readable object called BuildingPacked.

{
  message: {
    actions: [
      {
        data: {
          type: 'Transfer',
          value: {
            nftID: '/* NFT ID */',
            to: {
              type: 'Script',
              value: {
                /* the transfer target script */
              },
            },
          },
        },
        scriptInfoHash: '0x...',
      },
    ],
  },
}

This brings some benefits for wallets, such as

• rendering understandable information for end users while signing a transaction instead of a UTxO transaction graphic with a set of inputs and outputs
• standardizing the digest generation process even with different signature/hash algorithms to reduce the implementation complexity