Skip to main content

Best Practices

The purpose of this guide is to show the best practices in regards of Web3Wallet client usage. The goal is to provide the best user experience that just works in every circumstances.

note

In order to ensure the best user experience and flawless connection flow, please make sure that Web3Wallet SDK is initialized immediately after your app launch, especially if launched via a WalletConnect Deep Link. It guarantees that websocket connection is opened immediately and all requests are received by your wallet

Pairing​

A pairing is a connection between a wallet and a dapp that has fixed permissions to only allow a dapp to propose a session through it. Dapp can propose infinite number of sessions on one pairing. Wallet must use a pair method from Web3Wallet client to pair with dapp.

const uri = 'xxx'; // pairing uri
try {
    await web3Wallet.pair({ uri });
} catch (error) {
    // some error happens while pairing - check Expected errors section
}

Pairing State​

A pairing state is a primitive exposed by Web3Wallet client for a wallet to indicate whether it should await a session proposal. The pairing state is true when a wallet scans a QR and awaits a session proposal. Once the session proposal is received by the wallet, the pairing state is changed to false. When true wallet should show a loading indicator awaiting a session proposal, when changed to false a proposal dialog should be displayed.

Web3Wallet.instance.pairingStatePublisher
    .receive(on: DispatchQueue.main)
    .sink { [weak self] isPairing in
    self?.showPairingLoading = isPairing
}.store(in: &disposeBag)

Pairing Expiry​

A pairing expiry event is triggered whenever a pairing is expired. The expiry for inactive pairing is 5 mins, whereas for active pairing is 30 days. A pairing becomes active when a session proposal is received and user successfully approves it. This event helps to know when given pairing expires and update UI accordingly.

core.pairing.events.on("pairing_expire", (event) => {
    // pairing expired before user approved/rejected a session proposal
    const { topic } = topic;
});

Expected User flow​

Pairing Flow​

Pairing Error​

Expected Errors​

While pairing the following errors might occur:

  • No Internet connection error or pairing timeout when scanning QR with no Internet connection
    • User should pair again with Internet connection
  • Pairing expired error when scanning a QR code with expired pairing
    • User should refresh a QR code and scan again
  • Pairing with existing pairing is not allowed
    • User should refresh a QR code and scan again. I usually happens when user scans an already paired QR code.

Session Proposal​

A session proposal is a handshake sent by a dapp and it's purpose is to define a session rules. Whenever a user wants to establish a connection between a wallet and a dapp, one should approve a session proposal.

User Action Feedback​

Whenever user approves or rejects a session proposal, wallet should show loading indicators in a moment of the button press until Relay acknowledgement is received for any of this actions.

Approving session

    try {
        await web3Wallet.approveSession(params);
        // update UI -> remove the loader
    } catch (error) {
        // present error to the user
    }

Rejecting session

    try {
        await web3Wallet.rejectSession(params);
        // update UI -> remove the loader
    } catch (error) {
        // present error to the user
    }

Session Proposal Expiry​

A session proposal expiry is 5 mins. It means a given proposal is stored for 5 mins in the SDK storage and user has 5 mins for approval or rejection decision. After that time the below event is emitted and proposal modal should be removed from the app's UI.

web3wallet.on("proposal_expire", (event) => {
    // proposal expired and any modal displaying it should be removed
    const { id } = event;
});

Expected User flow​

Approve or Reject Session Proposal​

Error Handling​

Expected Errors​

While approving or rejecting a session proposal the following errors might occurs:

  • No Internet connection
    • It happens when a user tries to approve or reject session proposal with no Internet connection
  • Session proposal expired
    • It happens when users tries to approve or reject expired session proposal
  • Invalid namespaces
    • It happens when a validation of session namespaces fails
  • Timeout
    • It happens when Relay doesn't acknowledge session settle publish within 10s

Session Request​

A session request represents the request sent by a dapp to a wallet.

User Action Feedback​

Whenever user approves or rejects a session request, wallet should show loading indicators in a moment of the button press until Relay acknowledgement is received for any of this actions.

    try {
        await web3Wallet.respondSessionRequest(params);
        // update UI -> remove the loader
    } catch (error) {
        // present error to the user
    }

Session Request Expiry​

A session request expiry is defined by a dapp. It's value must be between now() + 5mins and now() + 7 days. After the session request expires the below event is emitted and session request modal should be removed from the app's UI.

web3wallet.on("session_request_expire", (event) => {
    // request expired and any modal displaying it should be removed
    const { id } = event;
});

Expected User flow​

Approve or Reject Session Proposal​

Error Handling​

Expected Errors​

While approving or rejecting a session request the following error might occur:

  • Invalid session
    • This error might happen when user approves or rejects a session request on expired session
  • Session request expired
    • This error might happen when user approves or rejects a session request that already expires
  • Timeout
    • It happens when Relay doesn't acknowledge session settle publish within 10s

Web Socket Connection State​

The Web Socket connection state tracks the connection with the relay server, event is emitted whenever a connection state changes.

core.relayer.on("relayer_connect", () => {
    // connection to the relay server is established
})

core.relayer.on("relayer_disconnect", () => {
// connection to the relay server is lost
})

Expected User flow​

Connection State​