walletconnect_qrcode_modal_dart 0.3.1

Provides UI for DApps to easily connect to a supported Wallet apps through open WalletConnect protocol.

Wallet Connect

WalletConnect is an open-source protocol for connecting decentralised applications to mobile wallets with QR code scanning or deep linking. A user can interact securely with any Dapp from their mobile phone, making WalletConnect wallets a safer choice compared to desktop or browser extension wallets.

Introduction

This package provides UX for dApp to seamlessly connect to a wallet app. On iOS list of wallet apps is provided for the user to select from, on Android there is one click connect. QR code option is also provided.

The package uses walletconnect-dart package for underlying WalletConnect communication.

Usage

Once installed, you can simply connect your application to a wallet.

Initiate connection - show QR code modal

// Create a connector
final qrCodeModal = WalletConnectQrCodeModal(
   connector: WalletConnect(
     bridge: 'https://bridge.walletconnect.org',
     clientMeta: const PeerMeta( // <-- Meta data of your app appearing in the wallet when connecting
       name: 'QRCodeModalExampleApp',
       description: 'WalletConnect Developer App',
       url: 'https://walletconnect.org',
       icons: [
         'https://gblobscdn.gitbook.com/spaces%2F-LJJeCjcLrr53DcT1Ml7%2Favatar.png?alt=media'
       ],
     ),
   ),
 );

// Subscribe to events
qrCodeModal.registerListeners(
  onConnect: (session) => print('Connected: $session'),
  onSessionUpdate: (response) => print('Session updated: $response'),
  onDisconnect: () => print('Disconnected'),
);

// Create QR code modal and connect to a wallet, connector returns WalletConnect
// session which can be saved and restored.
final session = await qrCodeModal.connect(context, chainId: 2)
    // Errors can also be caught from connector, eg. session cancelled
    .catchError((error) {
        // Handle error here
        debugPrint(error);
        return null;
    });

Send transaction

Example of Ethereum transaction:

final provider = EthereumWalletConnectProvider(connector);
final ethereum = Web3Client('https://goerli.infura.io/', Client());
final sender = EthereumAddress.fromHex(session.accounts[0]);

final transaction = Transaction(
  to: sender,
  from: sender,
  gasPrice: EtherAmount.inWei(BigInt.one),
  maxGas: 100000,
  value: EtherAmount.fromUnitAndValue(EtherUnit.finney, 1),
);

final credentials = WalletConnectEthereumCredentials(provider: provider);

// Send the transaction
final txBytes = await ethereum.sendTransaction(credentials, transaction);

Kill session

await qrCodeModal.killSession();

Customizations

The library UI is completely customizable through its modalBuilder builder. It lets you either customize existing UI elements or replace them with your own.

Each builder needs to return a Widget to be used by the package. For convenience defaultWidget is always provided in the builder to either be customised using its copyWith method or replaced completely with another widget.

For example, if you want to change the card color of the modal:

WalletConnectQrCodeModal(
  connector: WalletConnect(
    ...
  ),
  modalBuilder: (context, uri, callback, defaultModalWidget) {
    return defaultModalWidget.copyWith(
      cardColor: Colors.pink,
    );
  });

You could also return your custom widget in the builder rather than the defaultModalWidget if the level of customization is not sufficient. All the necessary data to build your own widget are either passed in through the builder arguments or can be obtained from the default...Widget.

For example, the main modalBuilder passes through the uri which is the WalletConnect URI and walletCallback which should be called when the Wallet is selected.

Various UI elements are accessible through different builders which allows you to mix and match which bits you want to customize or which to replace.

Builders

• modalBuilder - the main builder representing the whole modal, provides default ModalWidget

ModalWidget builders:

• selectorBuilder - represents the Wallet list or QR code selector
• walletButtonBuilder - represents Android modal content (single button with 'Connect')
• walletListBuilder - represents iOS/Desktop modal content (list of wallets)
• qrCodeBuilder - represents QR Code content

ModalSelectorWidget builder:

• walletSegmentThumbBuilder - represents the Wallet/Desktop segmented control thumb
• qrSegmentThumbBuilder - represents the QR Code segmented control thumb

ModalWalletListWidget builders:

• rowBuilder - represents a Wallet row in the Wallet list

Properties

List of customisable widgets:

• ModalWidget - represents the whole modal
• ModalSelectorWidget - represents the segmented control widget for choosing between list and QR code
• ModalSegmentThumbWidget - represents a segment in the main segmented control widget
• ModalWalletButtonWidget - represents the single button widget (for Android)
• ModalWalletListWidget - represents the list of wallets (for iOS and desktop)
• ModalQrCodeWidget - represents the QR code widget

Platform overrides

It is possible override the default behavior on certain platform to customize the platform experience. For example you can override for Android to show the wallet list rather than a single button. It is recommended to stick with platform defaults.

Example:

modalBuilder: (context, uri, callback, defaultModalWidget) {
  return defaultModalWidget.copyWith(
    platformOverrides: const ModalWalletPlatformOverrides(
      android: ModalWalletType.listMobile,
    ),
  );
}

This would force the library to use walletListBuilder on the Android platform. There are 3 types of types available:

• button - shows single button (default for Android), walletButtonBuilder is used
• listMobile - shows list of possible wallets which can be linked on the mobile platform (default for iOS), walletListBuilder is used
• listDesktop - shows list of possible wallets which can be linked on the desktop platform (default for desktop), walletListBuilder is used

Platform can be overriden to use any of the above types, the default functionality is not guaranteed (due to restriction on some platforms) but it allows more customization on each platform.

Example

The aim of the example app is to demonstrate simple transaction using QR code modal. The connected wallet has to be configured for Ethereum (Goerli) or Algorand test network with at least 0.001 tokens available (plus fee amount for the transaction). After connecting to the wallet the app would try to transfer 0.001 Eth/Algo from the wallet account to the same account (you should see some fee being deducted as well).

Migration guide

0.1.x to 0.2.x

selectorBuilder was added to add more flexibility to customize the whole selector segmented control. ModalSelectorWidget now represents this widget.

• walletSegmentThumbBuilder and qrSegmentThumbBuilder was moved into the new ModalSelectorWidget
• segmentedControlBackgroundColor was renamed to backgroundColor and moved to ModalSelectorWidget
• segmentedControlPadding was renamed to padding and moved to ModalSelectorWidget
• cardShape was added to ModalWidget to represent card shape parameter

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Tom Friml
• elliotsayes
• All Contributors

License

The MIT License (MIT). Please see License File for more information.