-
Notifications
You must be signed in to change notification settings - Fork 39
Home
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 💡
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.
- 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.
- 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.
- The system will expose methods like ping, version, isConnected, etc. to enable standardized interaction.
- Events like
accounts
,currentAccount
,connection
, etc., will be emitted to communicate changes.
- A metadata field for connectors will store name, image, and installation instructions.
- The SDK connects the connectors, to invoke the exposed methods and listen to various events.
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 | 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 |
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',
}
}
}
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 | 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 |
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);
});
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
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.
- Actors: DApp (A), Fuel Connect (B)
-
Flow:
- The DApp queries Fuel Connect to list available connectors.
- Fuel Connect returns a list of available connectors to the DApp.
- Actors: DApp (A), Fuel Connect (B), Wallet XW Connector (C), Wallet Application (D)
-
Flow:
- The DApp selects a connector, in this case, Wallet XW Connector (XW).
- Fuel Connect initiates a
ping
call to verify if the Wallet Application for the selected connector is available. - The
ping
is forwarded from the Wallet XW Connector to the Wallet Application. - The Wallet Application responds to the
ping
. - The Wallet XW Connector confirms the availability back to Fuel Connect.
- Fuel Connect saves the selected connector and notifies the DApp of the success or failure of the operation.
- Actors: DApp (A), Fuel Connect (B), Wallet XW Connector (C), Wallet Application (D)
-
Flow:
- The DApp requests to establish a connection using the selected connector.
- Fuel Connect calls the
connect
method on the Wallet XW Connector. - The Wallet XW Connector initiates the connection process with the Wallet Application.
- The Wallet Application returns the connection status.
- The Wallet XW Connector communicates the connection status back to Fuel Connect.
- 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.