Skip to content
Hélcio Franco edited this page Oct 11, 2024 · 3 revisions

Fuel Connectors

Objective

Enable varied types of connectors to seamlessly integrate with Fuel Wallet's multiple connector standard, thus enhancing application-DApp interoperability.

This layer aims to improve flexibility and allow any type of connector to create their own methods, enabling applications that are not browser extensions to also be a connector in fuel ecosystem.

Combined with fuel predicates, this layer enables a lot of UX cases, like

  • connecting with eth-compatible wallets
  • connecting with sol-compatible wallets
  • connecting through mobile signature
  • any other way of connection that an application can imagine 💡

Background

As blockchain Wallet evolved, each wallet chose its protocol, combining different integration methods. To solve these problems, we saw many abstractions tooling to make a single interface to integrate with multiple Wallet types.

On Fuel, we start with a Connectors protocol to enable multiple Wallet Providers, removing the need for other abstractions when developing Applications.

Definitions

  • Fuel SDK: Manager component used for developers to integrate with the Fuel Wallet Connectors.
  • Fuel Connector: Component provided by a Wallet Application that implements the logic for the communication between the Fuel SDK and the Wallet Application.

Goals

  • Implement a set of methods and events that will standardize interactions between applications and connectors.
  • Enable application information and installation instructions through connector metadata.
  • Allow Fuel SDK to detect installed Connectors automatically.
  • Remove abstractions for the communication between SDK and Fuel Connectors.

System Overview

Components

Methods

  • The system will expose methods like ping, version, isConnected, etc. to enable standardized interaction.

Events

  • Events like accounts, currentAccount, connection, etc., will be emitted to communicate changes.

Connector Metadata

  • A metadata field for connectors will store name, image, and installation instructions.

Fuel SDK

  • The SDK connects the connectors, to invoke the exposed methods and listen to various events.

Detailed Design

Connector

Method list

Method Description Params Return
ping It should return true if the connector is loaded in less than one second. boolean
version The current version and the network that this connector supports. Application and network version
isConnected The status of the current connection from the origin to the connector. connection status
accounts Accounts available to the authorized to the current connection. Account address list
connect Start the authorization flow for the current connection. connection status
disconnect Removes the authorization of the current connection. connection status
signMessage Start signMessage flow for the current connection. address and message message signature
sendTransaction Start to send transaction flow for the current connection. address, transaction, and network transaction ID
currentAccount Return the default account if the account is authorized to the connection. address
addAssets Add assets metadata to the current connection. Assets metadata success or failure
assets Return assets metadata available to all accounts, even the ones out of the connection. Assets metadata asset list
addNetwork Start to add network flow for the current connection. Network success or failure
selectNetwork Request the user to change the network inside the wallet. Network success or failure
networks Return network list available to all the accounts from the connector. Network list
addABI Add ABI information. This is a purely metadata endpoint and does not require an authorized connection. contract id and ABI boolean
getABI Return ABI information. contract id FuelABI
hasABI Return true if an ABI is available. contract id success if ABI returns

Event list

Event Description Value
accounts Emitted every time the accounts available to this connection change Addresses
currentAccount Emitted every time the current account on the connector is changed if the account is not available to the current it should be triggered with a null value Address or null if no defined
connection Emitted every time the connection status changes Connection status
network Emitted every time the network selected on the connector is updated Network url and chainId
assets Emitted every time the asset's metadata of the connector is changed Update asset list

Connector metadata

Enable application to have information and instructions on how to install the connector application.

class FuelWalletConnector extends FuelConnector {
  metadata = {
    name: 'Fuel Wallet',
    image: '/connectors/fuel-wallet.svg',
    install: {
      action: 'Install',
      description: 'To connect your Fuel Wallet, install the browser extension.',
      link: 'https://chrome.google.com/webstore/detail/fuel-wallet/dldjpboieedgcmpkchcjcbijingjcgok',
    }
  }
}

Fuel SDK

Method list

Method Description Params Return
connectors List all connectors available for the instance A list of Connectors
getConnector Return a single connector connector name Connector instance
hasConnector Return true if the SDK has a connector available boolean
selectConnector Change the connector, return true if the connector is available and connected connector name Connector instance
currentConnector Return the current connector selected Connector instance
getWallet Return a instance of Fuel Wallet Locked address and provider instance (optional) Wallet instance
clean Cleans the data saved on the storage
unsubscribe Remove all open listeners
destroy Remove all open listeners and data stored

Event list

Event Description Value
connectors Emitted every time the accounts available to this connection change Addresses
currentConnector Emitted every time the current account on the connector is changed if the account is not available to the current it should be triggered with a null value Address or null if no defined

Applications

With this new change, Connectors will not be required to inject objects into the application window. Instead, the application will be required to install the @fuels/connectors to interact with the Connectors.

import { Fuel } from 'fuels';
import { FuelWalletConnector } from '@fuels/connectors';
import { ThirdyPartyConnector } from '@thirdy-party/connector';

// Fuel SDK instance
const fuel = new Fuel({
  connectors: [
     new FuelWalletConnectors(),
     new ThirdyPartyConnector(),
  ]
});

// Wait for the connection response
await fuel.selectConnector('Fuel Wallet');
await fuel.connect();

// Event based way
fuel.on('connection', (isConnected) => {
  console.log(isConnected);
});

Or as an automatic injection, this enables user Wallets that are not installed by the application to be visible on the Connector List.

import { Fuel } from 'fuels';
import { FuelWalletConnector } from '@fuels/connectors';
import { ThirdyPartyConnector } from '@thirdy-party/connector';

// Fuel SDK instance
const fuel = new Fuel({
  connectors: [
    new FuelWalletConnector()
  ]
});

// Manual dispatch of the event on the window
window.dispatchEvent(new CustomEvent('FuelConnector', {
  detail: new ThirdyPartyConnector()
}));

// Promise way
await fuel.connect();

// Event based way
fuel.on('connection', (isConnected) => {
  console.log(isConnected);
});

Fuel Wallet Connector

The Connector implements an interface compatible with the FuelConnector. Once the connector is connected to the Fuel SDK instance, which is the main entry point for the application, the FuelConnect controller will target the instance of the Connector and call the methods directly.

This opens better integration possibilities by enabling more customization for Connectors to use WebSockets, events, etc.

Below is a sequence diagram explaining the information flow for a Connection Request (method: 'connect'):

sequenceDiagram
    title Fuel Connect Manager

    participant A as Dapp
    participant B as Fuel Connect
    participant C as Wallet XW Connector (XW)
    participant D as Wallet Application

    A->>B: List connectors
    B-->>A: Receive connectors
    note over A,B: Select connector
    A->>B: Select Connector (XW)
    note over B,D: Check if Wallet application is available
    B->>C:Call ping on (XW) connector
    C->>D:Ping application
    D-->>C:Respond ping
    C-->>B:Receive ping response from (XW)
    B->>B:Save selected Connector (XW)
    B-->>A:Receive success or failure
    note over A,D: Authorize connection (on selected connector)
    A->>B:Ask for connection
    B->>C:Call connect on (XW) connector
    C->>D:Call connect
    D-->>C:Respond with connection status
    C-->>B:Receive connection status from (XW)
    B-->>A:Receive connection status
Loading

Fuel Connect Manager Flows

The Fuel Connect Manager oversees the interactions between a decentralized application (DApp), the Fuel Connect layer, and the wallet's connectors. The sequence diagram delineates the flow of events and method calls that occur during the various stages of a connector's lifecycle, from listing to connection establishment.

1. List Connectors

  • Actors: DApp (A), Fuel Connect (B)
  • Flow:
    1. The DApp queries Fuel Connect to list available connectors.
    2. Fuel Connect returns a list of available connectors to the DApp.

2. Select Connector

  • Actors: DApp (A), Fuel Connect (B), Wallet XW Connector (C), Wallet Application (D)
  • Flow:
    1. The DApp selects a connector, in this case, Wallet XW Connector (XW).
    2. Fuel Connect initiates a ping call to verify if the Wallet Application for the selected connector is available.
    3. The ping is forwarded from the Wallet XW Connector to the Wallet Application.
    4. The Wallet Application responds to the ping.
    5. The Wallet XW Connector confirms the availability back to Fuel Connect.
    6. Fuel Connect saves the selected connector and notifies the DApp of the success or failure of the operation.

3. Authorize Connection

  • Actors: DApp (A), Fuel Connect (B), Wallet XW Connector (C), Wallet Application (D)
  • Flow:
    1. The DApp requests to establish a connection using the selected connector.
    2. Fuel Connect calls the connect method on the Wallet XW Connector.
    3. The Wallet XW Connector initiates the connection process with the Wallet Application.
    4. The Wallet Application returns the connection status.
    5. The Wallet XW Connector communicates the connection status back to Fuel Connect.
    6. Fuel Connect relays the connection status back to the DApp.

Each of these flows opens up opportunities for customization, such as utilizing WebSockets for more real-time interactions or leveraging events for enhanced UX features.

Understanding these flows provides foundational knowledge to implement, debug, and extend the capabilities of the Fuel Connect Manager within the ecosystem.