From 893041768f32f6b92a7996378480755eebbf6175 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter@blueoceancomputing.co.uk>
Date: Fri, 20 Sep 2024 14:39:19 +0100
Subject: [PATCH] docs: added assets guide (#3189)

* docs: added asset docs

* chore: changeset

* chore: lint

* docs: added further docs
---
 .changeset/serious-carrots-nail.md            |  4 ++
 .../src/guide/utilities/using-assets.test.ts  | 39 +++++++++++++++++++
 apps/docs/.vitepress/config.ts                |  4 ++
 apps/docs/spell-check-custom-words.txt        |  6 ++-
 apps/docs/src/guide/utilities/using-assets.md | 14 +++++++
 5 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/serious-carrots-nail.md
 create mode 100644 apps/docs-snippets/src/guide/utilities/using-assets.test.ts
 create mode 100644 apps/docs/src/guide/utilities/using-assets.md

diff --git a/.changeset/serious-carrots-nail.md b/.changeset/serious-carrots-nail.md
new file mode 100644
index 00000000000..c759d08a004
--- /dev/null
+++ b/.changeset/serious-carrots-nail.md
@@ -0,0 +1,4 @@
+---
+---
+
+docs: added assets guide
diff --git a/apps/docs-snippets/src/guide/utilities/using-assets.test.ts b/apps/docs-snippets/src/guide/utilities/using-assets.test.ts
new file mode 100644
index 00000000000..a28120c48fa
--- /dev/null
+++ b/apps/docs-snippets/src/guide/utilities/using-assets.test.ts
@@ -0,0 +1,39 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import type { Asset, AssetFuel } from 'fuels';
+import { assets, CHAIN_IDS, getAssetFuel, Wallet } from 'fuels';
+import { launchTestNode } from 'fuels/test-utils';
+
+/**
+ * @group node
+ * @group browser
+ */
+describe('using-assets', () => {
+  it('should be able to use `getAssetFuel`', async () => {
+    using launched = await launchTestNode();
+    const {
+      provider,
+      wallets: [sender],
+    } = launched;
+
+    // #region using-assets-1
+    // #import { Wallet, Asset, AssetFuel, assets, getAssetFuel };
+
+    const recipient = Wallet.generate({ provider });
+
+    // Find the asset with symbol 'ETH'
+    const assetEth: Asset = assets.find((asset) => asset.symbol === 'ETH')!;
+
+    // Get all the metadata for ETH on Fuel Test Network
+    const chainId: number = CHAIN_IDS.fuel.testnet;
+    const assetEthOnFuel: AssetFuel = getAssetFuel(assetEth, chainId)!;
+
+    // Send a transaction (using the asset on Fuel Test Network)
+    const transaction = await sender.transfer(recipient.address, 100, assetEthOnFuel.assetId);
+    const result = await transaction.waitForResult();
+    // #endregion using-assets-1
+
+    expect(result.isStatusSuccess).toBe(true);
+    expect(assetEthOnFuel).toBeDefined();
+    expect(assetEthOnFuel).toBeDefined();
+  });
+});
diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts
index b1fd455e50c..95748187e19 100644
--- a/apps/docs/.vitepress/config.ts
+++ b/apps/docs/.vitepress/config.ts
@@ -367,6 +367,10 @@ export default defineConfig({
                 text: 'Unit conversion',
                 link: '/guide/utilities/unit-conversion',
               },
+              {
+                text: 'Using assets',
+                link: '/guide/utilities/using-assets',
+              },
             ],
           },
           {
diff --git a/apps/docs/spell-check-custom-words.txt b/apps/docs/spell-check-custom-words.txt
index 4a4dfb9a2da..c9860e98217 100644
--- a/apps/docs/spell-check-custom-words.txt
+++ b/apps/docs/spell-check-custom-words.txt
@@ -333,4 +333,8 @@ incentivise
 URI
 walletsConfig
 reuploaded
-Vite
\ No newline at end of file
+Vite
+USDT
+USD
+USDC
+WETH
\ No newline at end of file
diff --git a/apps/docs/src/guide/utilities/using-assets.md b/apps/docs/src/guide/utilities/using-assets.md
new file mode 100644
index 00000000000..0a48219d8e7
--- /dev/null
+++ b/apps/docs/src/guide/utilities/using-assets.md
@@ -0,0 +1,14 @@
+# Assets
+
+We export an array of [`Asset`](https://docs.fuel.network/docs/fuels-ts/account/#asset) objects, that can be useful when creating your dApp. The `Asset` object has useful metadata about the different assets that are available on blockchain networks (Fuel and Ethereum).
+
+Included assets such as:
+
+- Ethereum (ETH)
+- Tether (USDT)
+- USD Coin (USDC)
+- Wrapped ETH (WETH)
+
+The helper functions `getAssetFuel` and `getAssetEth` can be used to get an asset's details relative to each network. These return a combination of the asset, and network information (the return types are [`AssetFuel`](../../api/Account/index.md#assetfuel) and [`AssetEth`](../../api/Account/index.md#asseteth) respectively).
+
+<<< @/../../docs-snippets/src/guide/utilities/using-assets.test.ts#using-assets-1{ts:line-numbers}