Fuels-ts

Appearance

Provider Options ​

You can provide various options on Provider instantiation to modify its behavior.

retryOptions ​

Calls to a fuel node via the Provider will fail if a connection cannot be established. Specifying retry options allows you to customize the way you want to handle that failure scenario before ultimately throwing an error.

NOTE: retrying is only done when a connection cannot be established. If the connection is established and the node throws an error, no retry will happen.

You can provide the following settings:

  • maxRetries - Amount of attempts to retry after initial attempt before failing the call.
  • backoff - Strategy used to define the intervals between attempts.
    • exponential (default): Doubles the delay with each attempt.
    • linear - Increases the delay linearly with each attempt.
    • fixed: Uses a constant delay between attempts.
  • baseDelay (default 150ms) - Base time in milliseconds for the backoff strategy.
ts
await Provider.create(FUEL_NETWORK_URL, {
  retryOptions: {
    maxRetries: 5,
    baseDelay: 100,
    backoff: 'linear',
  },
});
See code in context

requestMiddleware ​

Allows you to modify the request object to add additional headers, modify the request's body, and much more.

ts
// synchronous request middleware
await Provider.create(FUEL_NETWORK_URL, {
  requestMiddleware: (request: RequestInit) => {
    request.credentials = 'omit';

    return request;
  },
});

// asynchronous request middleware
await Provider.create(FUEL_NETWORK_URL, {
  requestMiddleware: async (request: RequestInit) => {
    const credentials = await fetchSomeExternalCredentials();
    request.headers ??= {};
    (request.headers as Record<string, string>).auth = credentials;

    return request;
  },
});
See code in context

timeout ​

Specify the timeout in milliseconds after which every request will be aborted.

ts
await Provider.create(FUEL_NETWORK_URL, {
  timeout: 30000, // will abort if request takes 30 seconds to complete
});
See code in context

fetch ​

Provide a custom fetch function that'll replace the default fetch call.

Note: If defined, requestMiddleware, timeout and retryOptions are applied to this custom fetch function as well.

ts
await Provider.create(FUEL_NETWORK_URL, {
  fetch: async (url: string, requestInit: RequestInit | undefined) => {
    // do something
    await sleep(100);

    // native fetch
    const response = await fetch(url, requestInit);

    const updatedResponse = decorateResponseWithCustomLogic(response);

    return updatedResponse;
  },
});
See code in context

cacheUtxo ​

When using the SDK, it may be necessary to submit multiple transactions from the same account in a short period. In such cases, the SDK creates and funds these transactions, then submits them to the node.

However, if a second transaction is created before the first one is processed, there is a chance of using the same UTXO(s) for both transactions. This happens because the UTXO(s) used in the first transaction are still unspent until the transaction is fully processed.

If the second transaction attempts to use the same UTXO(s) that the first transaction has already spent, it will result in the following error:

console
Transaction is not inserted. UTXO does not exist: 0xf5...

This error indicates that the UTXO(s) used by the second transaction no longer exist, as the first transaction already spent them.

To prevent this issue, you can use the cacheUtxo flag. This flag sets a TTL (Time-To-Live) for caching UTXO(s) used in a transaction, preventing them from being reused in subsequent transactions within the specified time.

ts
const provider = await Provider.create(FUEL_NETWORK_URL, {
  cacheUtxo: 5000, // cache UTXO for 5 seconds
});
See code in context

Note:

If you would like to submit multiple transactions without waiting for each transaction to be completed, your account must have multiple UTXOs available. If you only have one UTXO, the first transaction will spend it, and any remaining amount will be converted into a new UTXO with a different ID.

By ensuring your account has multiple UTXOs, you can effectively use the cacheUtxo flag to manage transactions without conflicts. For more information on UTXOs, refer to the UTXOs guide.