Querying the Chain

Once you have set up a provider, you're ready to interact with the Fuel blockchain.

We can connect to either a local or an external node:

1. Running a local node
2. Connecting to an external node

Let's look at a few examples below.

getBaseAssetId

The base asset is the underlying asset used to perform any transaction on a chain. This should be fetched from a provider to then be used in transactions.

import { FUEL_NETWORK_URL, Provider, ScriptTransactionRequest } from 'fuels';

// Fetch the base asset ID using the provider
const provider = await Provider.create(FUEL_NETWORK_URL);
const baseAssetId = provider.getBaseAssetId();
// 0x...

// Create a transaction request
const transactionRequest = new ScriptTransactionRequest();
// Use the base asset for an operation
transactionRequest.addCoinOutput(recipientAddress, 100, baseAssetId);

See code in context

getCoins

Returns UTXOs coins from an account address, optionally filtered by asset ID. This method supports pagination.

import { FUEL_NETWORK_URL, Provider } from 'fuels';
import { generateTestWallet } from 'fuels/test-utils';

const provider = await Provider.create(FUEL_NETWORK_URL);
const assetIdA = '0x0101010101010101010101010101010101010101010101010101010101010101';
const baseAssetId = provider.getBaseAssetId();

const wallet = await generateTestWallet(provider, [
  [42, baseAssetId],
  [100, assetIdA],
]);

// fetches up to 100 coins from baseAssetId
const { coins, pageInfo } = await provider.getCoins(wallet.address, baseAssetId);
// [
//   { amount: bn(42), assetId: baseAssetId },
//   ...
// ]

// fetches up to 100 coins from all assets
await provider.getCoins(wallet.address);
// [
//   { amount: bn(42), assetId: baseAssetId }
//   { amount: bn(100), assetId: assetIdA }
//   ...
// ]

See code in context

---

This method is also implemented on the Account class and can be used without providing the address:

await wallet.getCoins(baseAssetId);

See code in context

getResourcesToSpend

Returns spendable resources (coins or messages) for a transaction request. It accepts an optional third parameter, excludedIds, to exclude specific UTXO IDs or coin message nonces:

import type { CoinQuantityLike, ExcludeResourcesOption } from 'fuels';
import { FUEL_NETWORK_URL, Provider, ScriptTransactionRequest } from 'fuels';
import { generateTestWallet } from 'fuels/test-utils';

const provider = await Provider.create(FUEL_NETWORK_URL);
const assetIdA = '0x0101010101010101010101010101010101010101010101010101010101010101';
const baseAssetId = provider.getBaseAssetId();

const wallet = await generateTestWallet(provider, [
  [42, baseAssetId],
  [100, assetIdA],
]);

const quantities: CoinQuantityLike[] = [
  { amount: 32, assetId: baseAssetId, max: 42 },
  { amount: 50, assetId: assetIdA },
];

const utxoId = '0x00000000000000000000000000000000000000000000000000000000000000010001';
const messageNonce = '0x381de90750098776c71544527fd253412908dec3d07ce9a7367bd1ba975908a0';
const excludedIds: ExcludeResourcesOption = {
  utxos: [utxoId],
  messages: [messageNonce],
};

const spendableResources = await provider.getResourcesToSpend(
  wallet.address,
  quantities,
  excludedIds
);

const tx = new ScriptTransactionRequest();
tx.addResources(spendableResources);

See code in context

---

This method is also available in the Account class and can be used without providing the address:

await wallet.getResourcesToSpend(spendableResources, excludedIds);

See code in context

getBalances

Returns the sum of all UTXOs coins and unspent message coins amounts for all assets. Unlike getCoins, it only returns the total amounts, not the individual coins:

import { FUEL_NETWORK_URL, Provider } from 'fuels';
import { generateTestWallet } from 'fuels/test-utils';

const provider = await Provider.create(FUEL_NETWORK_URL);
const assetIdA = '0x0101010101010101010101010101010101010101010101010101010101010101';
const baseAssetId = provider.getBaseAssetId();

const wallet = await generateTestWallet(provider, [
  [42, baseAssetId],
  [100, assetIdA],
]);

const { balances } = await provider.getBalances(wallet.address);
// [
//   { amount: bn(42), assetId: baseAssetId } // total amount of baseAssetId
//   { amount: bn(100), assetId: assetIdA } // total amount of assetIdA
// ]

See code in context

---

This method is also available in the Account class and can be used without providing the address parameter:

await wallet.getBalances();

See code in context

getBlocks

The getBlocks method returns blocks from the blockchain matching the given paginationArgs parameter, supporting pagination. The below code snippet shows how to get the last 10 blocks.

import { FUEL_NETWORK_URL, Provider } from 'fuels';

const provider = await Provider.create(FUEL_NETWORK_URL);
const blockToProduce = 3;

// Force-producing some blocks to make sure that 10 blocks exist
await provider.produceBlocks(blockToProduce);

const { blocks } = await provider.getBlocks({
  last: blockToProduce,
});

See code in context

getMessageByNonce

You can use the getMessageByNonce method to retrieve a message by its nonce.

import { FUEL_NETWORK_URL, Provider } from 'fuels';

const provider = await Provider.create(FUEL_NETWORK_URL);

const nonce = '0x381de90750098776c71544527fd253412908dec3d07ce9a7367bd1ba975908a0';
const message = await provider.getMessageByNonce(nonce);

See code in context

getMessages

You can use the getMessages method to retrieve a list of messages from the blockchain.

import { TestMessage, launchTestNode } from 'fuels/test-utils';

// Creates a test message with an amount of 100
const testMessage = new TestMessage({ amount: 100 });

// Launches a test node with the test message configured
using launched = await launchTestNode({ walletsConfig: { messages: [testMessage] } });
const {
  wallets: [wallet],
} = launched;

// Retrieves messages from the wallet
const { messages } = await wallet.getMessages();

See code in context

getMessageProof

A message proof is a cryptographic proof that a message was included in a block. You can use the getMessageProof method to retrieve a message proof for a given transaction ID and message ID.

You can retrieve a message proof by either using it's block ID:

import type { TransactionResultMessageOutReceipt } from 'fuels';
import { launchTestNode } from 'fuels/test-utils';

// Launches a test node
using launched = await launchTestNode({
  nodeOptions: {
    args: ['--poa-instant', 'false', '--poa-interval-period', '1s'],
  },
});

const {
  wallets: [sender, recipient],
  provider,
} = launched;

// Performs a withdrawal transaction from sender to recipient, thus generating a message
const withdrawTx = await sender.withdrawToBaseLayer(recipient.address.toB256(), 100);
const result = await withdrawTx.waitForResult();

// Waiting for a new block to be commited (1 confirmation block)
await new Promise((resolve) => {
  setTimeout(() => {
    resolve(true);
  }, 1000);
});

// Retrives the latest block
const latestBlock = await provider.getBlock('latest');

// Retrieves the `nonce` via message out receipt from the initial transaction result
const { nonce } = result.receipts[0] as TransactionResultMessageOutReceipt;

// Retrieves the message proof for the transaction ID and nonce using the next block Id
const messageProof = await provider.getMessageProof(
  result.gqlTransaction.id,
  nonce,
  latestBlock?.id
);

See code in context

---

Or by it's block height:

import type { TransactionResultMessageOutReceipt } from 'fuels';
import { launchTestNode } from 'fuels/test-utils';

// Launches a test node
using launched = await launchTestNode({
  nodeOptions: {
    args: ['--poa-instant', 'false', '--poa-interval-period', '1s'],
  },
});

const {
  wallets: [sender, recipient],
  provider,
} = launched;

// Performs a withdrawal transaction from sender to recipient, thus generating a message
const withdrawTx = await sender.withdrawToBaseLayer(recipient.address.toB256(), 100);
const result = await withdrawTx.waitForResult();

// Waiting for a new block to be commited (1 confirmation block)
await new Promise((resolve) => {
  setTimeout(() => {
    resolve(true);
  }, 1000);
});

// Retrieves the `nonce` via message out receipt from the initial transaction result
const { nonce } = result.receipts[0] as TransactionResultMessageOutReceipt;

// Retrives the latest block
const latestBlock = await provider.getBlock('latest');

// Retrieves the message proof for the transaction ID and nonce using the block height
const messageProof = await provider.getMessageProof(
  result.gqlTransaction.id,
  nonce,
  undefined,
  latestBlock?.height
);

See code in context