Home

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.