devchenyan commented 1 year ago

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.

https://github.com/Magickbase/neuron-public-issues/assets/11756869/50deb328-171a-4237-985d-daa85238b9d2

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

UX/UI

https://github.com/Magickbase/neuron-public-issues/assets/11756869/4626f2fb-3fb2-4692-a48c-2f2389180384

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 commented 1 year ago

here is a PoC to show

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

https://github.com/Magickbase/neuron-public-issues/assets/7511174/7d034afe-0260-479d-a211-8fa3653c0df2

Sven-TBD commented 1 year ago

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 commented 9 months ago

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

Magickbase / neuron-public-issues

integrating with WalletConnect to work with dapp #144

Table of Contents