docs: add essentials section for Transactions

.changeset/late-books-juggle.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs: add essentials section for Transactions

apps/docs-snippets/package.json

@@ -12,7 +12,8 @@
     "@fuel-ts/errors": "workspace:*",
     "@fuel-ts/utils": "workspace:*",
     "ethers": "^6.7.1",
-    "fuels": "workspace:*"
+    "fuels": "workspace:*",
+    "vitest": "^1.1.3"
   },
   "keywords": [],
   "author": "",

apps/docs-snippets/src/guide/transactions/transaction-parameters.test.ts

@@ -0,0 +1,83 @@
+import type { Contract, Provider, TxParams } from 'fuels';
+import { BN, PolicyType, ScriptTransactionRequest, bn } from 'fuels';
+import { expectTypeOf } from 'vitest';
+
+import {
+  DocSnippetProjectsEnum,
+  getDocsSnippetsForcProject,
+} from '../../../test/fixtures/forc-projects';
+import { createAndDeployContractFromProject } from '../../utils';
+
+/**
+ * @group node
+ */
+describe(__filename, () => {
+  let contract: Contract;
+  let provider: Provider;
+  let gasPrice: BN;
+
+  const { binHexlified: scriptBytecode } = getDocsSnippetsForcProject(
+    DocSnippetProjectsEnum.SUM_SCRIPT
+  );
+
+  beforeAll(async () => {
+    contract = await createAndDeployContractFromProject(DocSnippetProjectsEnum.COUNTER);
+    provider = contract.provider;
+    gasPrice = provider.getGasConfig().minGasPrice;
+  });
+
+  it('matches tx param types', () => {
+    // #region transaction-parameters-1
+    // import { TxParams, bn };
+
+    const txParams: TxParams = {
+      gasPrice: bn(1), // BigNumberish or undefined
+      gasLimit: bn(1), // BigNumberish or undefined
+      maturity: 1, // number or undefined
+      maxFee: bn(1), // BigNumberish or undefined
+      witnessLimit: bn(1), // BigNumberish or undefined
+      variableOutputs: 1, // number or undefined
+    };
+    // #endregion transaction-parameters-1
+
+    expectTypeOf(txParams).toMatchTypeOf<TxParams>();
+  });
+
+  it('executes a script transaction request with txParams', () => {
+    // #region transaction-parameters-2
+    // #import { ScriptTransactionRequest };
+
+    // Instantiate the transaction request using a ScriptTransactionRequest
+    // We can set txParams in the request constructor
+    const transactionRequest = new ScriptTransactionRequest({
+      script: scriptBytecode,
+      gasLimit: 100,
+      gasPrice,
+    });
+    // #endregion transaction-parameters-2
+
+    expect(transactionRequest.gasLimit.toNumber()).toBe(100);
+    expect(transactionRequest.gasPrice.toNumber()).toBe(gasPrice.toNumber());
+  });
+
+  it('executes contract call with txParams', async () => {
+    // #region transaction-parameters-3
+    const { transactionResult } = await contract.functions
+      .increment_count(15)
+      .txParams({
+        gasLimit: 10_000,
+        variableOutputs: 1,
+      })
+      .call();
+    // #endregion transaction-parameters-3
+
+    const { transaction } = transactionResult;
+
+    const gasLimitPolicy = transaction.policies?.find(
+      (policy) => policy.type === PolicyType.GasPrice
+    );
+
+    expect(new BN(transaction.scriptGasLimit).toNumber()).toBe(10_000);
+    expect(new BN(gasLimitPolicy?.data).toNumber()).toBe(gasPrice.toNumber());
+  });
+});

apps/docs-snippets/src/guide/transactions/transaction-policies.test.ts

@@ -0,0 +1,95 @@
+import type { WalletUnlocked, TransactionResponse, Policy } from 'fuels';
+import { BaseAssetId, ScriptTransactionRequest, bn, PolicyType } from 'fuels';
+
+import {
+  DocSnippetProjectsEnum,
+  getDocsSnippetsForcProject,
+} from '../../../test/fixtures/forc-projects';
+import { getTestWallet } from '../../utils';
+
+/**
+ * @group node
+ */
+describe('Transaction Policies', () => {
+  let wallet: WalletUnlocked;
+
+  const { abiContents: scriptAbi, binHexlified: scriptBytecode } = getDocsSnippetsForcProject(
+    DocSnippetProjectsEnum.SUM_SCRIPT
+  );
+
+  beforeAll(async () => {
+    wallet = await getTestWallet();
+  });
+
+  it('sets policies', () => {
+    // #region transaction-policies-1
+    // #import { ScriptTransactionRequest };
+
+    const transactionRequest = new ScriptTransactionRequest({
+      gasPrice: bn(1), // Sets the gas price policy
+      witnessLimit: bn(1), // Sets the witness limit policy
+      maturity: 1, // Sets the maturity policy
+      maxFee: bn(1), // Sets the max fee policy
+    });
+    // #endregion transaction-policies-1
+
+    const { policyTypes, policies } = ScriptTransactionRequest.getPolicyMeta(transactionRequest);
+
+    expect(policyTypes).toBe(15);
+    expect(policies?.[0].type).toBe(PolicyType.GasPrice);
+    expect(bn(policies?.[0].data).eq(transactionRequest.gasPrice)).toBeTruthy();
+    expect(policies?.[1].type).toBe(PolicyType.WitnessLimit);
+    expect(bn(policies?.[1].data).eq(bn(transactionRequest.witnessLimit))).toBeTruthy();
+    expect(policies?.[2].type).toBe(PolicyType.Maturity);
+    expect(policies?.[2]?.data).toBe(transactionRequest.maturity);
+    expect(policies?.[3].type).toBe(PolicyType.MaxFee);
+    expect(bn(policies?.[3].data).eq(bn(transactionRequest.maxFee))).toBeTruthy();
+  });
+
+  it('gets transaction response from tx id', async () => {
+    const scriptMainFunctionArguments = [1];
+    const resources = await wallet.getResourcesToSpend([{ amount: 1000, assetId: BaseAssetId }]);
+
+    // #region transaction-policies-2
+    // #import { ScriptTransactionRequest, TransactionResponse, Policy };
+
+    // Instantiate the transaction request with transaction parameters that would
+    // set the respective policies.
+    const transactionRequest = new ScriptTransactionRequest({
+      script: scriptBytecode,
+      gasLimit: bn(1_000),
+      maturity: 2,
+      gasPrice: bn(3),
+      witnessLimit: 900,
+      maxFee: bn(10_000),
+    });
+
+    // Set the script main function arguments
+    transactionRequest.setData(scriptAbi, scriptMainFunctionArguments);
+
+    // Fund the transaction
+    transactionRequest.addResources(resources);
+
+    // Submit the transaction and retrieve the transaction response
+    const tx: TransactionResponse = await wallet.sendTransaction(transactionRequest);
+    const response = await tx.waitForResult();
+
+    // Retrieve the policies from the transaction response. The policies property
+    // is undefined if the transaction had no policies applied.
+    const policies: Policy[] | undefined = response.transaction.policies;
+    // #endregion transaction-policies-2
+
+    if (!policies) {
+      throw new Error('No policies found');
+    }
+
+    expect(policies?.[0].type).toBe(PolicyType.GasPrice);
+    expect(bn(policies?.[0].data).eq(transactionRequest.gasPrice)).toBeTruthy();
+    expect(policies?.[1].type).toBe(PolicyType.WitnessLimit);
+    expect(bn(policies?.[1].data).eq(bn(transactionRequest.witnessLimit))).toBeTruthy();
+    expect(policies?.[2].type).toBe(PolicyType.Maturity);
+    expect(policies?.[2]?.data).toBe(transactionRequest.maturity);
+    expect(policies?.[3].type).toBe(PolicyType.MaxFee);
+    expect(bn(policies?.[3].data).eq(bn(transactionRequest.maxFee))).toBeTruthy();
+  });
+});