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:
- Running a local node
- 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 { Provider, ScriptTransactionRequest } from 'fuels';
const FUEL_NETWORK_URL = 'http://127.0.0.1:4000/v1/graphql';
// 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);2
3
4
5
6
7
8
9
10
11
12
13
getCoins
Returns UTXOs coins from an account address, optionally filtered by asset ID. This method supports pagination.
import { Provider } from 'fuels';
const provider = await Provider.create(FUEL_NETWORK_URL);
const assetIdA = '0x0101010101010101010101010101010101010101010101010101010101010101';
const baseAssetId = provider.getBaseAssetId();
// fetches up to 100 coins from baseAssetId
const { coins, pageInfo } = await provider.getCoins(wallet.address, baseAssetId);
// [
// { amount: bn(100), assetId: baseAssetId },
// ...
// ]
// fetches up to 100 coins from all assets
await provider.getCoins(wallet.address);
// [
// { amount: bn(100), assetId: baseAssetId }
// { amount: bn(100), assetId: assetIdA }
// ...
// ]2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
This method is also implemented on the Account class and can be used without providing the address:
await wallet.getCoins(baseAssetId);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 { ScriptTransactionRequest, Provider } from 'fuels';
const provider = await Provider.create(FUEL_NETWORK_URL);
const assetIdA = '0x0101010101010101010101010101010101010101010101010101010101010101';
const baseAssetId = provider.getBaseAssetId();
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);2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
This method is also available in the Account class and can be used without providing the address:
await wallet.getResourcesToSpend(spendableResources, excludedIds);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 { Provider } from 'fuels';
const provider = await Provider.create(FUEL_NETWORK_URL);
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
// ]2
3
4
5
6
7
8
9
This method is also available in the Account class and can be used without providing the address parameter:
await wallet.getBalances();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 { 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,
});2
3
4
5
6
7
8
9
10
11
12
getMessageByNonce
You can use the getMessageByNonce method to retrieve a message by its nonce.
import { Provider } from 'fuels';
const provider = await Provider.create(FUEL_NETWORK_URL);
const nonce = '0x381de90750098776c71544527fd253412908dec3d07ce9a7367bd1ba975908a0';
const message = await provider.getMessageByNonce(nonce);2
3
4
5
6
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();2
3
4
5
6
7
8
9
10
11
12
13
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.id, nonce, latestBlock?.id);2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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.id,
nonce,
undefined,
latestBlock?.height
);2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
getTransactions
You can use the getTransactions method to retrieve a list of transactions from the blockchain. This is limited to 30 transactions per page.
import { Provider } from 'fuels';
const provider = await Provider.create(FUEL_NETWORK_URL);
const { transactions } = await provider.getTransactions();2
3
4
5