Merge branch 'main' into 1662-en_7

docs/contracts.md

@@ -37,8 +37,7 @@ const transferVetClause = Clause.transferVET(
 
 // 2. Transfer VTHO
 
-const transferVTHOClause = Clause.transferToken(
-    Address.of(VTHO_ADDRESS),
+const transferVTHOClause = Clause.transferVTHOToken(
     Address.of('0xf02f557c753edf5fcdcbfe4c1c3a448b3cc84d54'),
     VTHO.of(300n, Units.wei)
 );
@@ -203,22 +202,21 @@ You can specify revisions (`best` or `finalized`) for read functions, similar to
 
 ## Delegating a Contract Call
 
-VeChain supports delegated contract calls where fees are paid by the delegator.
+VeChain supports delegated contract calls where fees are paid by the gas-payer.
 
 ```typescript { name=contract-delegation-erc20, category=example }
 const thorSoloClient = ThorClient.at(THOR_SOLO_URL);
 const provider = new VeChainProvider(
     thorSoloClient,
     new ProviderInternalBaseWallet([deployerAccount], {
+        // The term `delegator` will be deprecated soon and renamed `gasPayer`.
         delegator: {
-            delegatorPrivateKey: delegatorAccount.privateKey
+            delegatorPrivateKey: gasPayerAccount.privateKey
         }
     }),
     true
 );
-const signer = (await provider.getSigner(
-    deployerAccount.address
-)) as VeChainSigner;
+const signer = await provider.getSigner(deployerAccount.address);
 
 // Defining a function for deploying the ERC20 contract
 const setupERC20Contract = async (): Promise<Contract<typeof ERC20_ABI>> => {
@@ -245,8 +243,7 @@ const transferResult = await contract.transact.transfer(
 );
 
 // Wait for the transfer transaction to complete and obtain its receipt
-const transactionReceiptTransfer =
-    (await transferResult.wait()) as TransactionReceipt;
+const transactionReceiptTransfer = await transferResult.wait();
 
 // Asserting that the transaction has not been reverted
 expect(transactionReceiptTransfer.reverted).toEqual(false);

docs/examples/contracts/contract-clauses.ts

@@ -18,8 +18,7 @@ const transferVetClause = Clause.transferVET(
 
 // 2. Transfer VTHO
 
-const transferVTHOClause = Clause.transferToken(
-    Address.of(VTHO_ADDRESS),
+const transferVTHOClause = Clause.transferVTHOToken(
     Address.of('0xf02f557c753edf5fcdcbfe4c1c3a448b3cc84d54'),
     VTHO.of(300n, Units.wei)
 );

docs/examples/contracts/contract-delegation-ERC20.ts

@@ -1,4 +1,4 @@
-import { ERC20_ABI, Hex, HexUInt } from '@vechain/sdk-core';
+import { ERC20_ABI, HexUInt } from '@vechain/sdk-core';
 import {
     type Contract,
     ProviderInternalBaseWallet,
@@ -23,8 +23,8 @@ const deployerAccount: ProviderInternalWalletAccount = {
     address: '0xf02f557c753edf5fcdcbfe4c1c3a448b3cc84d54'
 };
 
-// Defining the delegator account, which has VTHO for transaction costs
-const delegatorAccount = {
+// Defining the gas-payer account, which has VTHO for transaction costs
+const gasPayerAccount = {
     privateKey:
         '521b7793c6eb27d137b617627c6b85d57c0aa303380e9ca4e30a30302fbc6676',
     address: '0x062F167A905C1484DE7e75B88EDC7439f82117DE'
@@ -36,15 +36,14 @@ const thorSoloClient = ThorClient.at(THOR_SOLO_URL);
 const provider = new VeChainProvider(
     thorSoloClient,
     new ProviderInternalBaseWallet([deployerAccount], {
+        // The term `delegator` will be deprecated soon and renamed `gasPayer`.
         delegator: {
-            delegatorPrivateKey: delegatorAccount.privateKey
+            delegatorPrivateKey: gasPayerAccount.privateKey
         }
     }),
     true
 );
-const signer = (await provider.getSigner(
-    deployerAccount.address
-)) as VeChainSigner;
+const signer = await provider.getSigner(deployerAccount.address);
 
 // Defining a function for deploying the ERC20 contract
 const setupERC20Contract = async (): Promise<Contract<typeof ERC20_ABI>> => {
@@ -71,8 +70,7 @@ const transferResult = await contract.transact.transfer(
 );
 
 // Wait for the transfer transaction to complete and obtain its receipt
-const transactionReceiptTransfer =
-    (await transferResult.wait()) as TransactionReceipt;
+const transactionReceiptTransfer = await transferResult.wait();
 
 // Asserting that the transaction has not been reverted
 expect(transactionReceiptTransfer.reverted).toEqual(false);

docs/examples/transactions/fee-delegation.ts

@@ -61,17 +61,17 @@ const body: TransactionBody = {
 // 4 - Create private keys of sender and delegate
 
 const nodeDelegate = HDKey.fromMnemonic(Mnemonic.of());
-const delegatorPrivateKey = nodeDelegate.privateKey;
+const gasPayerPrivateKey = nodeDelegate.privateKey;
 
 // 5 - Get address of delegate
 
-const delegatorAddress = Address.ofPublicKey(nodeDelegate.publicKey).toString();
+const gasPayerAddress = Address.ofPublicKey(nodeDelegate.publicKey).toString();
 
 // 6 - Sign transaction as sender and delegate
 
 const signedTransaction = Transaction.of(body).signAsSenderAndGasPayer(
     HexUInt.of(senderAccount.privateKey).bytes,
-    HexUInt.of(delegatorPrivateKey).bytes
+    HexUInt.of(gasPayerPrivateKey).bytes
 );
 
 // 7 - Encode transaction
@@ -85,4 +85,4 @@ const decodedTx = Transaction.decode(encodedRaw, true);
 // END_SNIPPET: FeeDelegationSnippet
 
 expect(decodedTx.isDelegated).toBeTruthy();
-expect(decodedTx.gasPayer.toString()).toBe(delegatorAddress);
+expect(decodedTx.gasPayer.toString()).toBe(gasPayerAddress);

docs/examples/transactions/full-flow-delegator-private-key.ts

@@ -29,8 +29,8 @@ const senderAccount: { privateKey: string; address: string } = {
     address: '0x7a28e7361fd10f4f058f9fefc77544349ecff5d6'
 };
 
-// Delegator account with private key
-const delegatorAccount: { privateKey: string; address: string } = {
+// Gas-payer account with private key
+const gasPayerAccount: { privateKey: string; address: string } = {
     privateKey:
         '521b7793c6eb27d137b617627c6b85d57c0aa303380e9ca4e30a30302fbc6676',
     address: '0x062F167A905C1484DE7e75B88EDC7439f82117DE'
@@ -50,8 +50,9 @@ const providerWithDelegationEnabled = new VeChainProvider(
             }
         ],
         {
+            // The term `delegator` will be deprecated soon and renamed `gasPayer`.
             delegator: {
-                delegatorPrivateKey: delegatorAccount.privateKey
+                delegatorPrivateKey: gasPayerAccount.privateKey
             }
         }
     ),
@@ -119,7 +120,7 @@ const txReceipt = await thorSoloClient.transactions.waitForTransaction(
 // Check the signed transaction
 expect(delegatedSigned.isSigned).toEqual(true);
 expect(delegatedSigned.isDelegated).toEqual(true);
-expect(delegatedSigned.gasPayer.toString()).toEqual(delegatorAccount.address);
+expect(delegatedSigned.gasPayer.toString()).toEqual(gasPayerAccount.address);
 
 // Check the transaction receipt
 expect(txReceipt).toBeDefined();

docs/examples/transactions/full-flow-delegator-url.ts

@@ -35,8 +35,8 @@ const senderAccount: {
     address: '0x571E3E1fBE342891778151f037967E107fb89bd0'
 };
 
-// Delegator account with private key
-const delegatorAccount = {
+// Gas-payer account with private key
+const gasPayerAccount = {
     URL: 'https://sponsor-testnet.vechain.energy/by/269'
 };
 
@@ -54,8 +54,9 @@ const providerWithDelegationEnabled = new VeChainProvider(
             }
         ],
         {
+            // The term `delegator` will be deprecated soon and renamed `gasPayer`.
             delegator: {
-                delegatorUrl: delegatorAccount.URL
+                delegatorUrl: gasPayerAccount.URL
             }
         }
     ),
@@ -123,7 +124,7 @@ const txReceipt = await thorClient.transactions.waitForTransaction(
 // Check the signed transaction
 expect(delegatedSigned.isSigned).toEqual(true);
 expect(delegatedSigned.isDelegated).toEqual(true);
-// expect(signedTx.delegator).toEqual(delegatorAccount.address); ---
+// expect(signedTx.delegator).toEqual(gasPayerAccount.address); ---
 
 // Check the transaction receipt
 expect(txReceipt).toBeDefined();

docs/examples/transactions/multiple-clauses.ts

@@ -21,8 +21,7 @@ const clauses: TransactionClause[] = [
         Address.of('0x7567d83b7b8d80addcb281a71d54fc7b3364ffed'),
         VET.of(10000)
     ) as TransactionClause,
-    Clause.transferToken(
-        Address.of(VTHO_ADDRESS),
+    Clause.transferVTHOToken(
         Address.of('0x7567d83b7b8d80addcb281a71d54fc7b3364ffed'),
         VTHO.of(10000)
     ) as TransactionClause

docs/templates/contracts.md

@@ -70,6 +70,6 @@ You can specify revisions (`best` or `finalized`) for read functions, similar to
 
 ## Delegating a Contract Call
 
-VeChain supports delegated contract calls where fees are paid by the delegator.
+VeChain supports delegated contract calls where fees are paid by the gas-payer.
 
 [ERC20FunctionCallDelegatedSnippet](examples/contracts/contract-delegation-ERC20.ts)

docs/transactions.md

@@ -74,8 +74,7 @@ const clauses: TransactionClause[] = [
         Address.of('0x7567d83b7b8d80addcb281a71d54fc7b3364ffed'),
         VET.of(10000)
     ) as TransactionClause,
-    Clause.transferToken(
-        Address.of(VTHO_ADDRESS),
+    Clause.transferVTHOToken(
         Address.of('0x7567d83b7b8d80addcb281a71d54fc7b3364ffed'),
         VTHO.of(10000)
     ) as TransactionClause
@@ -164,17 +163,17 @@ const body: TransactionBody = {
 // 4 - Create private keys of sender and delegate
 
 const nodeDelegate = HDKey.fromMnemonic(Mnemonic.of());
-const delegatorPrivateKey = nodeDelegate.privateKey;
+const gasPayerPrivateKey = nodeDelegate.privateKey;
 
 // 5 - Get address of delegate
 
-const delegatorAddress = Address.ofPublicKey(nodeDelegate.publicKey).toString();
+const gasPayerAddress = Address.ofPublicKey(nodeDelegate.publicKey).toString();
 
 // 6 - Sign transaction as sender and delegate
 
 const signedTransaction = Transaction.of(body).signAsSenderAndGasPayer(
     HexUInt.of(senderAccount.privateKey).bytes,
-    HexUInt.of(delegatorPrivateKey).bytes
+    HexUInt.of(gasPayerPrivateKey).bytes
 );
 
 // 7 - Encode transaction
@@ -464,8 +463,8 @@ const senderAccount: { privateKey: string; address: string } = {
     address: '0x7a28e7361fd10f4f058f9fefc77544349ecff5d6'
 };
 
-// Delegator account with private key
-const delegatorAccount: { privateKey: string; address: string } = {
+// Gas-payer account with private key
+const gasPayerAccount: { privateKey: string; address: string } = {
     privateKey:
         '521b7793c6eb27d137b617627c6b85d57c0aa303380e9ca4e30a30302fbc6676',
     address: '0x062F167A905C1484DE7e75B88EDC7439f82117DE'
@@ -485,8 +484,9 @@ const providerWithDelegationEnabled = new VeChainProvider(
             }
         ],
         {
+            // The term `delegator` will be deprecated soon and renamed `gasPayer`.
             delegator: {
-                delegatorPrivateKey: delegatorAccount.privateKey
+                delegatorPrivateKey: gasPayerAccount.privateKey
             }
         }
     ),
@@ -571,8 +571,8 @@ const senderAccount: {
     address: '0x571E3E1fBE342891778151f037967E107fb89bd0'
 };
 
-// Delegator account with private key
-const delegatorAccount = {
+// Gas-payer account with private key
+const gasPayerAccount = {
     URL: 'https://sponsor-testnet.vechain.energy/by/269'
 };
 
@@ -590,8 +590,9 @@ const providerWithDelegationEnabled = new VeChainProvider(
             }
         ],
         {
+            // The term `delegator` will be deprecated soon and renamed `gasPayer`.
             delegator: {
-                delegatorUrl: delegatorAccount.URL
+                delegatorUrl: gasPayerAccount.URL
             }
         }
     ),

packages/core/src/transaction/Clause.ts

@@ -3,10 +3,10 @@ import { ERC721_ABI, VIP180_ABI } from '../utils';
 import {
     ABI,
     ABIContract,
+    Address,
     FixedPointNumber,
     VET,
     type ABIFunction,
-    type Address,
     type HexUInt,
     type VTHO
 } from '../vcdm';
@@ -15,6 +15,7 @@ import { HexInt } from '../vcdm/HexInt';
 import type { ClauseOptions } from './ClauseOptions';
 import type { DeployParams } from './DeployParams';
 import type { TransactionClause } from './TransactionClause';
+import { VTHO_ADDRESS } from '../utils/const/network';
 
 /**
  * This class represent a transaction clause.
@@ -43,7 +44,7 @@ class Clause implements TransactionClause {
     private static readonly TRANSFER_NFT_FUNCTION = 'transferFrom';
 
     /**
-     * Used internally in {@link Clause.transferToken} method.
+     * Used internally in {@link Clause.transferVTHOToken} method.
      */
     private static readonly TRANSFER_TOKEN_FUNCTION = 'transfer';
 
@@ -59,7 +60,7 @@ class Clause implements TransactionClause {
      * token in {@link Units.wei} to transfer to the destination.
      *
      * @see {Clause.callFunction}
-     * @see {Clause.transferToken}
+     * @see {Clause.transferVTHOToken}
      * @see {Clause.transferVET}
      */
     readonly value: string;
@@ -215,9 +216,7 @@ class Clause implements TransactionClause {
     }
 
     /**
-     * Return a new clause to transfers the specified amount of
-     * [VIP180](https://docs.vechain.org/introduction-to-vechain/dual-token-economic-model/vethor-vtho#vip180-vechains-fungible-token-standard)
-     * token.
+     * Return a new clause to transfers the specified amount of VTHO
      *
      * @param {Address} tokenAddress - The address of the VIP180 token.
      * @param {Address} recipientAddress - The address of the recipient.
@@ -228,25 +227,24 @@ class Clause implements TransactionClause {
      *
      * @see VTHO.transferTokenTo
      */
-    public static transferToken(
-        tokenAddress: Address,
+    public static transferVTHOToken(
         recipientAddress: Address,
-        amount: VTHO,
-        clauseOptions?: ClauseOptions
+        amount: VTHO
     ): Clause {
         if (amount.value.isFinite() && amount.value.isPositive()) {
+            const vthoAddress = Address.of(VTHO_ADDRESS);
             return this.callFunction(
-                tokenAddress,
+                vthoAddress,
                 ABIContract.ofAbi(VIP180_ABI).getFunction(
                     Clause.TRANSFER_TOKEN_FUNCTION
                 ),
                 [recipientAddress.toString(), amount.wei],
                 undefined,
-                clauseOptions
+                { comment: 'Transfer VTHO' }
             );
         }
         throw new InvalidDataType(
-            'Clause.transferToken',
+            'Clause.transferVTHOToken',
             'not positive integer amount',
             { amount: `${amount.value}` }
         );