Provider API

Fluent injects an API provider into websites visited by its user at window.conflux. This API allows websites to request users' wallet accounts, read data from blockchains and suggest that the user sign message and transactions.

⚠️ Fluent will "hijack" the window.conflux injected by ConfluxPortal. Dapp won't be able to call ConfluxPortal Provider API once Fluent is installed.

We might add an option to enable user to disable the "hijack" in the future.

Properties

conflux.isFluent

⚠️ This property is non-standard. Non-Fluent providers may also set this prop to true .

⚠️ Fluent also set conflux.isConfluxPortal to true for compatibility reason. (We'll remove this in the future)

true if the user has Fluent installed.

Methods

conflux.isConnected()

Returns true if the provider is connected to the blockchain.

If the provider is not connected, the page will have to be reloaded in order for connection to be re-established. Please see the connect and disconnect events for more information.

conflux.request()

interface RequestArguments {
  method: string;
  params?: unknown[] | object;
}

conflux.request(args: RequestArguments): Promise<unknown>;

Use request to submit RPC requests to blockchain via Fluent. It returns a Promise that resolves to the result of the RPC method call.
The params and return value will vary by RPC method. In practice, if a method has any params, they are almost always of type Array<any> or Object. Empty params can be specified as undefined or empty array.
If the request fails for any reason, the Promise will reject with an RPC Error.
Fluent supports most standardized Conflux RPC methods, in addition to a number of methods that may not be supported by other wallets. See the Fluent RPC API documentation for details.

Example:

params: [
  {
    from: 'cfx:aana7ds0dvsxftyanc727snuu6husj3vmyc3f1ay93',
    to: 'cfx:aana7ds0dvsxftyanc727snuu6husj3vmyc3f1ay93',
    gas: '0x5208', // 21000
    gasPrice: '0x7530', // 30000
    value: '0x1'
  },
];

conflux
  .request({
    method: 'cfx_sendTransaction',
    params,
  })
  .then((result) => {
    // The result varies by RPC method.
    // For example, this method will return a transaction hash hexadecimal string on success.
  })
  .catch((error) => {
    // If the request fails, the Promise will reject with an error.
  });

Events

Fluent provider implements the Node.js EventEmitter API. Check here for more detail about the event emitter.

connect

The Fluent provider emits this event when it first becomes able to submit RPC requests to a chain. We recommend using a connect event handler and the conflux.isConnected() method in order to determine when/if the provider is connected.

disconnect

The Fluent provider emits this event if it becomes unable to submit RPC requests to any chain. In general, this will only happen due to network connectivity issues or some unforeseen error.

Once disconnect has been emitted, the provider will not accept any new requests until the connection to the chain has been reestablished, which requires reloading the page. You can also use the conflux.isConnected() method to determine if the provider is disconnected.

accountsChanged

The Fluent provider emits this event whenever the return value of the cfx_accounts RPC method changes. cfx_accounts returns an array that is either empty or contains a single account address. The returned address, if any, is the address of the most recently used account that the caller is permitted to access. Callers are identified by their URL origin, which means that all sites with the same origin share the same permissions.

This means that accountsChanged will be emitted whenever the user's exposed account address changes.

ℹ️ We plan to allow the cfx_accounts array to be able to contain multiple addresses in the near future.

chainChanged

The Fluent provider emits this event when the currently connected chain changes.

All RPC requests are submitted to the currently connected chain. Therefore, it's critical to keep track of the current chain ID by listening for this event.

ℹ️ We plan to allow the website to connect multiple chains at the same time in the future.

message

The Fluent provider emits this event when it receives some message that the consumer should be notified of. The kind of message is identified by the type string.