docs: add further snippets with new infrastructure

.eslintignore

@@ -13,6 +13,7 @@ apps/demo-react-cra
 apps/demo-react-vite
 apps/create-fuels-counter-guide
 apps/docs-snippets2/src/typegend
+apps/docs-snippets2/src/**/*.test.ts
 
 packages/fuels/src/cli/commands/deploy/proxy
 packages/fuels/test/fixtures/project

apps/docs-snippets2/README.md

@@ -0,0 +1,27 @@
+# `docs-snippets`
+
+**docs-snippets** is a private package for generating snippets for the Fuel documentation site.
+
+
+# Table of contents
+
+- [`docs-snippets`](#docs-snippets)
+- [Table of contents](#table-of-contents)
+	- [Building](#building)
+	- [Testing](#testing)
+## Building
+
+This builds the snippets into testable scripts from the `src` folder and generates the Typegen `types` in the `typegend` folder. All test scripts end with a `.test.ts` suffix.
+```sh
+pnpm build
+```
+
+## Testing
+
+This will build the snippets and run the generated tests. To specific a particular environment for a test, the snippet should be named as `{name}.{environment}.test.ts`. e.g. `deploy-contract.node.test.ts`
+
+If no environment is specified, it will run in the browser and node environments by default.
+
+```sh
+pnpm test
+```

apps/docs-snippets2/scripts/test-template.ts

@@ -8,10 +8,7 @@ afterAll(() => {
   console = { ...consoleBkp };
 });
 
-/**
- * @group node
- * @group browser
- */
+// %TEST_ENVIRONMENT%
 test('%NAME%', async () => {
   // TEST NODE LAUNCHER ———>>>
   // %NODE_LAUNCHER%

apps/docs-snippets2/scripts/wrap-snippets.ts

@@ -12,6 +12,20 @@ const wrapperFnContents = readFileSync(wrapperFnFilepath, 'utf-8');
 export const wrapSnippet = (filepath: string) => {
   const snippetContents = readFileSync(filepath, 'utf8');
 
+  /**
+   * Test environment
+   */
+  let testEnvironments = '';
+
+  // Check if the filepath includes '.node' or '.browser'
+  if (filepath.includes('.node')) {
+    testEnvironments = '/**\n * @group node\n */';
+  } else if (filepath.includes('.browser')) {
+    testEnvironments = '/**\n * @group browser\n */';
+  } else {
+    testEnvironments = '/**\n * @group node\n * @group browser\n */';
+  }
+
   /*
     Filter all imports from file.
   */
@@ -74,6 +88,7 @@ export const wrapSnippet = (filepath: string) => {
   const wrappedSnippet =
     // eslintDisableRule +
     wrapperFnContents
+      .replace('// %TEST_ENVIRONMENT%', testEnvironments)
       .replace('// %IMPORTS%', imports)
       .replace('%NAME%', basename(filepath))
       .replace('// %SNIPPET%', indented)

apps/docs-snippets2/src/create-fuels/decrement-counter.ts

@@ -0,0 +1,44 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+// #region full
+import { Wallet, Provider } from 'fuels';
+
+import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from '../env';
+import { CounterFactory } from '../typegend/contracts';
+
+// Let's create our provider from the network URL.
+const provider = await Provider.create(LOCAL_NETWORK_URL);
+// Let's create our wallet from the private key.
+const wallet = Wallet.fromPrivateKey(WALLET_PVT_KEY, provider);
+
+// Then we can deploy the contract.
+const { waitForResult } = await CounterFactory.deploy(wallet);
+const { contract } = await waitForResult();
+
+// Lets setup some values to use in our example.
+const initialCount = 0;
+const incrementedValue = 5;
+const decrementedValue = 2;
+
+// We can now call the contract functions and test the results. Lets assert the initial value of the counter.
+const { waitForResult: getCountWaitForResult } = await contract.functions
+  .get_count()
+  .call();
+const { value: initialGetCountValue } = await getCountWaitForResult();
+// Next we'll increment the counter, so that we can decrement it.
+const { waitForResult: incWaitForResult } = await contract.functions
+  .increment_count(5)
+  .call();
+const { value: incValue } = await incWaitForResult();
+
+// Next, we'll decrement the counter by 3 and assert the new value.
+const { waitForResult: decWaitForResult } = await contract.functions
+  .decrement_count(3)
+  .call();
+const { value: decValue } = await decWaitForResult();
+
+// Finally, we'll test the get count function again to ensure parity.
+const { waitForResult: finalWaitForResult } = await contract.functions
+  .get_count()
+  .call();
+const { value: finalValue } = await finalWaitForResult();
+// #endregion full

apps/docs-snippets2/src/encoding/encode-and-decode.ts

@@ -0,0 +1,103 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+// #region full
+import type { JsonAbi, TransactionResultReturnDataReceipt } from 'fuels';
+import {
+  buildFunctionResult,
+  ReceiptType,
+  arrayify,
+  Script,
+  Interface,
+  Provider,
+  Wallet,
+} from 'fuels';
+
+// #region encode-and-decode-3
+import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from '../env';
+import { ScriptSum } from '../typegend';
+
+const provider = await Provider.create(LOCAL_NETWORK_URL);
+const wallet = Wallet.fromPrivateKey(WALLET_PVT_KEY, provider);
+
+// First we need to build out the transaction via the script that we want to encode.
+// For that we'll need the ABI and the bytecode of the script
+const abi: JsonAbi = ScriptSum.abi;
+const bytecode = ScriptSum.bytecode;
+
+// Create the invocation scope for the script call, passing the initial
+// value for the configurable constant
+const script = new Script(bytecode, abi, wallet);
+const initialValue = 10;
+script.setConfigurableConstants({ AMOUNT: initialValue });
+const invocationScope = script.functions.main(0);
+
+// Create the transaction request, this can be picked off the invocation
+// scope so the script bytecode is preset on the transaction
+const request = await invocationScope.getTransactionRequest();
+// #endregion encode-and-decode-3
+
+// #region encode-and-decode-4
+
+// Now we can encode the argument we want to pass to the function. The argument is required
+// as a function parameter for all abi functions and we can extract it from the ABI itself
+const argument = abi.functions
+  .find((f) => f.name === 'main')
+  ?.inputs.find((i) => i.name === 'inputted_amount')?.concreteTypeId as string;
+
+// The `Interface` class (imported from `fuels`) is the entry point for encoding and decoding all things abi-related.
+// We will use its `encodeType` method and create the encoding required for
+// a u32 which takes 4 bytes up of property space.
+
+const abiInterface = new Interface(abi);
+const argumentToAdd = 10;
+const encodedArguments = abiInterface.encodeType(argument, [argumentToAdd]);
+// Therefore the value of 10 will be encoded to:
+// Uint8Array([0, 0, 0, 10]
+
+// The encoded value can now be set on the transaction via the script data property
+request.scriptData = encodedArguments;
+
+// Now we can build out the rest of the transaction and then fund it
+const txCost = await wallet.getTransactionCost(request);
+request.maxFee = txCost.maxFee;
+request.gasLimit = txCost.gasUsed;
+await wallet.fund(request, txCost);
+
+// Finally, submit the built transaction
+const response = await wallet.sendTransaction(request);
+await response.waitForResult();
+// #endregion encode-and-decode-4
+
+// #region encode-and-decode-5
+
+// Get result of the transaction, including the contract call result. For this we'll need
+// the previously created invocation scope, the transaction response and the script
+const invocationResult = await buildFunctionResult({
+  funcScope: invocationScope,
+  isMultiCall: false,
+  program: script,
+  transactionResponse: response,
+});
+
+// The decoded value can be destructured from the `FunctionInvocationResult`
+const { value } = invocationResult;
+
+// Or we can decode the returned bytes ourselves, by retrieving the return data
+// receipt that contains the returned bytes. We can get this by filtering on
+// the returned receipt types
+const returnDataReceipt = invocationResult.transactionResult.receipts.find(
+  (r) => r.type === ReceiptType.ReturnData
+) as TransactionResultReturnDataReceipt;
+
+// The data is in hex format so it makes sense to use arrayify so that the data
+// is more human readable
+const returnData = arrayify(returnDataReceipt.data);
+// returnData = new Uint8Array([0, 0, 0, 20]
+
+// And now we can decode the returned bytes in a similar fashion to how they were
+// encoded, via the `Interface`
+const [decodedReturnData] = abiInterface.decodeType(argument, returnData);
+// 20
+
+const totalValue = argumentToAdd + initialValue;
+// #endregion encode-and-decode-5
+// #endregion full

apps/docs-snippets2/src/encoding/working-with-bytes.ts

@@ -0,0 +1,88 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+// #region full
+import { randomBytes } from 'crypto';
+import {
+  ArrayCoder,
+  B256Coder,
+  B512Coder,
+  BigNumberCoder,
+  BooleanCoder,
+  EnumCoder,
+  NumberCoder,
+  RawSliceCoder,
+  StdStringCoder,
+  StringCoder,
+  StructCoder,
+  TupleCoder,
+  VecCoder,
+  hexlify,
+} from 'fuels';
+
+// #region working-with-bytes-1
+const u8Coder = new NumberCoder('u8');
+const encodedU8 = u8Coder.encode(255);
+
+const u16Coder = new NumberCoder('u16');
+const encodedU16 = u16Coder.encode(255);
+
+const u32Coder = new NumberCoder('u32');
+const encodedU32 = u32Coder.encode(255);
+
+const u64Coder = new BigNumberCoder('u64');
+const encodedU64 = u64Coder.encode(255);
+
+const u256Coder = new BigNumberCoder('u256');
+const encodedU256 = u256Coder.encode(255);
+// #endregion working-with-bytes-1
+
+// #region working-with-bytes-2
+const booleanCoder = new BooleanCoder();
+const encodedTrue = booleanCoder.encode(true);
+
+const encodedFalse = booleanCoder.encode(false);
+
+// #endregion working-with-bytes-2
+
+// #region working-with-bytes-3
+const stringCoder = new StringCoder(5);
+const encoded = stringCoder.encode('hello');
+// #endregion working-with-bytes-3
+
+// #region working-with-bytes-4
+const b256Coder = new B256Coder();
+const encodedB256 = b256Coder.encode(hexlify(randomBytes(32)));
+const b512Coder = new B512Coder();
+const encodedB512 = b512Coder.encode(hexlify(randomBytes(64)));
+// #endregion working-with-bytes-4
+
+// #region working-with-bytes-5
+const tupleCoder = new TupleCoder([
+  new NumberCoder('u8'),
+  new NumberCoder('u16'),
+]);
+const encodedTuple = tupleCoder.encode([255, 255]);
+
+const structCoder = new StructCoder('struct', {
+  a: new NumberCoder('u8'),
+  b: new NumberCoder('u16'),
+});
+const encodedStruct = structCoder.encode({ a: 255, b: 255 });
+
+const arrayCoder = new ArrayCoder(new NumberCoder('u8'), 4);
+const encodedArray = arrayCoder.encode([255, 0, 255, 0]);
+
+const enumCoder = new EnumCoder('enum', { a: new NumberCoder('u32') });
+const encodedEnum = enumCoder.encode({ a: 255 });
+// #endregion working-with-bytes-5
+
+// #region working-with-bytes-6
+const vecCoder = new VecCoder(new NumberCoder('u8'));
+const encodedVec = vecCoder.encode([255, 0, 255]);
+
+const stdStringCoder = new StdStringCoder();
+const encodedStdString = stdStringCoder.encode('hello');
+
+const rawSliceCoder = new RawSliceCoder();
+const encodedRawSlice = rawSliceCoder.encode([1, 2, 3, 4]);
+// #endregion working-with-bytes-6
+// #endregion full

apps/docs-snippets2/src/scripts/script-custom-transaction.ts

@@ -0,0 +1,66 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+// #region full
+import { BN, ScriptTransactionRequest, coinQuantityfy } from 'fuels';
+import { ASSET_A, ASSET_B, launchTestNode } from 'fuels/test-utils';
+
+import { EchoValuesFactory } from '../typegend/contracts/EchoValuesFactory';
+import { ScriptTransferToContract } from '../typegend/scripts/ScriptTransferToContract';
+
+using launched = await launchTestNode({
+  contractsConfigs: [{ factory: EchoValuesFactory }],
+});
+const {
+  contracts: [contract],
+  wallets: [wallet],
+} = launched;
+
+const defaultTxParams = {
+  gasLimit: 10000,
+};
+
+// #region custom-transactions-2
+
+// 1. Create a script transaction using the script binary
+const request = new ScriptTransactionRequest({
+  ...defaultTxParams,
+  gasLimit: 3_000_000,
+  script: ScriptTransferToContract.bytecode,
+});
+
+// 2. Instantiate the script main arguments
+const scriptArguments = [
+  contract.id.toB256(),
+  { bits: ASSET_A },
+  new BN(1000),
+  { bits: ASSET_B },
+  new BN(500),
+];
+
+// 3. Populate the script data and add the contract input and output
+request
+  .setData(ScriptTransferToContract.abi, scriptArguments)
+  .addContractInputAndOutput(contract.id);
+
+// 4. Get the transaction resources
+const quantities = [
+  coinQuantityfy([1000, ASSET_A]),
+  coinQuantityfy([500, ASSET_B]),
+];
+
+// 5. Calculate the transaction fee
+const txCost = await wallet.getTransactionCost(request, { quantities });
+
+request.gasLimit = txCost.gasUsed;
+request.maxFee = txCost.maxFee;
+
+await wallet.fund(request, txCost);
+
+// 6. Send the transaction
+const tx = await wallet.sendTransaction(request);
+await tx.waitForResult();
+
+const contractFinalBalanceAssetA = await contract.getBalance(ASSET_A);
+const contractFinalBalanceAssetB = await contract.getBalance(ASSET_B);
+// #endregion custom-transactions-2
+
+// #endregion full