fix: remove [warning] from typedoc for external usage (starknet-io#1095)

* test: Improve tests performance (starknet-io#1121)

* test: fix transaction retry interval fallback for devnet tests

* test: remove test.only

* Update _test.yml (starknet-io#1126)

* fix: rename the @param to match the definitions

this commit changes the typedoc that do not match the function declaration

* fix: add a space before typedoc <br/> so that it catches the name

when a @param contains an html tag, it should not be attached to the parameter
name otherwise it does consider the tag is part of the name. This commit
detaches the name from the tag

* fix: improve function declaration so that typedoc matches it

this is a specific case when a function has several declarations and the first
one does not match the typedoc because the parameter is optional. This commit
simplifies the declaration by making the comment optional with a ?.

* fix: reintroduce the parameter name

change the declaration of a function so that the parameter name appears.
To do so it moves the assignement in the function.

* fix: remove unused type declaration and export

removes a declaration from account that is not used in the code and
redundant with the exact same one in the provider file. export the
declaration that is the one really used.

---------

Co-authored-by: Luka Saric <32763694+lukasaric@users.noreply.github.com>
Co-authored-by: Ivan Pavičić <ivan.pavicic@live.com>

__tests__/config/fixtures.ts

@@ -2,12 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { Account, Provider, ProviderInterface, RpcProvider, json } from '../../src';
-import {
-  CompiledSierra,
-  CompiledSierraCasm,
-  LegacyCompiledContract,
-  waitForTransactionOptions,
-} from '../../src/types';
+import { CompiledSierra, CompiledSierraCasm, LegacyCompiledContract } from '../../src/types';
 import { ETransactionVersion } from '../../src/types/api';
 import { toHex } from '../../src/utils/num';
 import { wait } from '../../src/utils/provider';
@@ -74,22 +69,18 @@ export const compiledTestRejectSierra = readContractSierra('cairo/testReject/tes
 export const compiledTestRejectCasm = readContractSierraCasm('cairo/testReject/test_reject');
 export const compiledSidMulticall = readContractSierra('starknetId/multicall/multicall.sierra');
 export const compiledSidMulticallCasm = readContractSierraCasm('starknetId/multicall/multicall');
+
 export function getTestProvider(isProvider?: true): ProviderInterface;
 export function getTestProvider(isProvider?: false): RpcProvider;
 export function getTestProvider(isProvider: boolean = true): ProviderInterface | RpcProvider {
-  const provider = isProvider
-    ? new Provider({ nodeUrl: process.env.TEST_RPC_URL })
-    : new RpcProvider({ nodeUrl: process.env.TEST_RPC_URL });
+  const isDevnet = process.env.IS_DEVNET === 'true';
 
-  if (process.env.IS_DEVNET === 'true') {
+  const providerOptions = {
+    nodeUrl: process.env.TEST_RPC_URL,
     // accelerate the tests when running locally
-    const originalWaitForTransaction = provider.waitForTransaction.bind(provider);
-    provider.waitForTransaction = (txHash: string, options: waitForTransactionOptions = {}) => {
-      return originalWaitForTransaction(txHash, { retryInterval: 1000, ...options });
-    };
-  }
-
-  return provider;
+    ...(isDevnet && { transactionRetryIntervalFallback: 1000 }),
+  };
+  return isProvider ? new Provider(providerOptions) : new RpcProvider(providerOptions);
 }
 
 export const TEST_TX_VERSION = process.env.TX_VERSION === 'v3' ? ETransactionVersion.V3 : undefined;

src/account/interface.ts

@@ -147,11 +147,11 @@ export abstract class AccountInterface extends ProviderInterface {
    * Estimate Fee for executing a list of transactions on starknet
    * Contract must be deployed for fee estimation to be possible
    *
-   * @param transactions array of transaction object containing :
+   * @param invocations array of transaction object containing :
    * - type - the type of transaction : 'DECLARE' | (multi)'DEPLOY' | (multi)'INVOKE_FUNCTION' | 'DEPLOY_ACCOUNT'
    * - payload - the payload of the transaction
    *
-   *  @param estimateFeeDetails -
+   *  @param details -
    * - blockIdentifier?
    * - nonce?
    * - skipValidate? - default true
@@ -344,34 +344,34 @@ export abstract class AccountInterface extends ProviderInterface {
   ): Promise<DeployContractResponse>;
 
   /**
-   * Signs a JSON object for off-chain usage with the Starknet private key and returns the signature
+   * Signs a TypedData object for off-chain usage with the Starknet private key and returns the signature
    * This adds a message prefix so it can't be interchanged with transactions
    *
-   * @param json - JSON object to be signed
-   * @returns the signature of the JSON object
-   * @throws {Error} if the JSON object is not a valid JSON
+   * @param typedData - TypedData object to be signed
+   * @returns the signature of the TypedData object
+   * @throws {Error} if typedData is not a valid TypedData
    */
   public abstract signMessage(typedData: TypedData): Promise<Signature>;
 
   /**
-   * Hash a JSON object with Pedersen hash and return the hash
+   * Hash a TypedData object with Pedersen hash and return the hash
    * This adds a message prefix so it can't be interchanged with transactions
    *
-   * @param json - JSON object to be hashed
-   * @returns the hash of the JSON object
-   * @throws {Error} if the JSON object is not a valid JSON
+   * @param typedData - TypedData object to be hashed
+   * @returns the hash of the TypedData object
+   * @throws {Error} if typedData is not a valid TypedData
    */
   public abstract hashMessage(typedData: TypedData): Promise<string>;
 
   /**
-   * Verify a signature of a JSON object
+   * Verify a signature of a TypedData object
    *
-   * @param typedData - JSON object to be verified
-   * @param signature - signature of the JSON object
+   * @param typedData - TypedData object to be verified
+   * @param signature - signature of the TypedData object
    * @param signatureVerificationFunctionName - optional account contract verification function name override
    * @param signatureVerificationResponse - optional response override { okResponse: string[]; nokResponse: string[]; error: string[] }
    * @returns true if the signature is valid, false otherwise
-   * @throws {Error} if the JSON object is not a valid JSON or the signature is not a valid signature
+   * @throws {Error} if typedData is not a valid TypedData or the signature is not a valid signature
    */
   public abstract verifyMessage(typedData: TypedData, signature: Signature): Promise<boolean>;
 

src/channel/rpc_0_6.ts

@@ -222,12 +222,13 @@ export class RpcChannel {
    */
   public simulateTransaction(
     invocations: AccountInvocations,
-    {
+    simulateTransactionOptions: getSimulateTransactionOptions = {}
+  ) {
+    const {
       blockIdentifier = this.blockIdentifier,
       skipValidate = true,
       skipFeeCharge = true,
-    }: getSimulateTransactionOptions = {}
-  ) {
+    } = simulateTransactionOptions;
     const block_id = new Block(blockIdentifier).identifier;
     const simulationFlags: RPC.ESimulationFlag[] = [];
     if (skipValidate) simulationFlags.push(RPC.ESimulationFlag.SKIP_VALIDATE);

src/channel/rpc_0_7.ts

@@ -50,11 +50,21 @@ export class RpcChannel {
 
   private specVersion?: string;
 
+  private transactionRetryIntervalFallback?: number;
+
   readonly waitMode: Boolean; // behave like web2 rpc and return when tx is processed
 
   constructor(optionsOrProvider?: RpcProviderOptions) {
-    const { nodeUrl, retries, headers, blockIdentifier, chainId, specVersion, waitMode } =
-      optionsOrProvider || {};
+    const {
+      nodeUrl,
+      retries,
+      headers,
+      blockIdentifier,
+      chainId,
+      specVersion,
+      waitMode,
+      transactionRetryIntervalFallback,
+    } = optionsOrProvider || {};
     if (Object.values(NetworkName).includes(nodeUrl as NetworkName)) {
       this.nodeUrl = getDefaultNodeUrl(nodeUrl as NetworkName, optionsOrProvider?.default);
     } else if (nodeUrl) {
@@ -69,6 +79,11 @@ export class RpcChannel {
     this.specVersion = specVersion;
     this.waitMode = waitMode || false;
     this.requestId = 0;
+    this.transactionRetryIntervalFallback = transactionRetryIntervalFallback;
+  }
+
+  private get transactionRetryIntervalDefault() {
+    return this.transactionRetryIntervalFallback ?? 5000;
   }
 
   public setChainId(chainId: StarknetChainId) {
@@ -227,12 +242,13 @@ export class RpcChannel {
    */
   public simulateTransaction(
     invocations: AccountInvocations,
-    {
+    simulateTransactionOptions: getSimulateTransactionOptions = {}
+  ) {
+    const {
       blockIdentifier = this.blockIdentifier,
       skipValidate = true,
       skipFeeCharge = true,
-    }: getSimulateTransactionOptions = {}
-  ) {
+    } = simulateTransactionOptions;
     const block_id = new Block(blockIdentifier).identifier;
     const simulationFlags: RPC.ESimulationFlag[] = [];
     if (skipValidate) simulationFlags.push(RPC.ESimulationFlag.SKIP_VALIDATE);
@@ -250,7 +266,7 @@ export class RpcChannel {
     let { retries } = this;
     let onchain = false;
     let isErrorState = false;
-    const retryInterval = options?.retryInterval ?? 5000;
+    const retryInterval = options?.retryInterval ?? this.transactionRetryIntervalDefault;
     const errorStates: any = options?.errorStates ?? [
       RPC.ETransactionStatus.REJECTED,
       // TODO: commented out to preserve the long-standing behavior of "reverted" not being treated as an error by default

src/provider/interface.ts

@@ -61,8 +61,7 @@ export abstract class ProviderInterface {
    * @param blockIdentifier block identifier
    * @returns the block object
    */
-  public abstract getBlock(): Promise<PendingBlock>;
-  public abstract getBlock(blockIdentifier: 'pending'): Promise<PendingBlock>;
+  public abstract getBlock(blockIdentifier?: 'pending'): Promise<PendingBlock>;
   public abstract getBlock(blockIdentifier: 'latest'): Promise<Block>;
   public abstract getBlock(blockIdentifier: BlockIdentifier): Promise<GetBlockResponse>;
 
@@ -147,15 +146,15 @@ export abstract class ProviderInterface {
   /**
    * Gets the transaction information from a tx id.
    *
-   * @param txHash
+   * @param transactionHash
    * @returns the transaction object \{ transaction_id, status, transaction, block_number?, block_number?, transaction_index?, transaction_failure_reason? \}
    */
   public abstract getTransaction(transactionHash: BigNumberish): Promise<GetTransactionResponse>;
 
   /**
    * Gets the transaction receipt from a tx hash.
    *
-   * @param txHash
+   * @param transactionHash
    * @returns the transaction receipt object
    */
   public abstract getTransactionReceipt(

src/provider/rpc.ts

@@ -247,7 +247,7 @@ export class RpcProvider implements ProviderInterface {
 
   /**
    * @param invocations AccountInvocations
-   * @param simulateTransactionOptions blockIdentifier and flags to skip validation and fee charge<br/>
+   * @param options blockIdentifier and flags to skip validation and fee charge<br/>
    * - blockIdentifier<br/>
    * - skipValidate (default false)<br/>
    * - skipFeeCharge (default true)<br/>
@@ -270,6 +270,7 @@ export class RpcProvider implements ProviderInterface {
       txHash,
       options
     )) as GetTxReceiptResponseWithoutHelper;
+
     return new ReceiptTx(receiptWoHelper) as GetTransactionReceiptResponse;
   }
 

src/signer/interface.ts

@@ -47,7 +47,7 @@ export abstract class SignerInterface {
   /**
    * Signs a DEPLOY_ACCOUNT transaction with the Starknet private key and returns the signature
    *
-   * @param transaction<br/>
+   * @param transaction <br/>
    * - contractAddress<br/>
    * - chainId<br/>
    * - classHash<br/>
@@ -64,7 +64,7 @@ export abstract class SignerInterface {
   /**
    * Signs a DECLARE transaction with the Starknet private key and returns the signature
    *
-   * @param transaction<br/>
+   * @param transaction <br/>
    * - classHash<br/>
    * - compiledClassHash? - used for Cairo1<br/>
    * - senderAddress<br/>

src/types/account.ts

@@ -76,11 +76,6 @@ export type SimulateTransactionDetails = {
   skipExecute?: boolean;
 } & Partial<V3TransactionDetails>;
 
-export enum SIMULATION_FLAG {
-  SKIP_VALIDATE = 'SKIP_VALIDATE',
-  SKIP_EXECUTE = 'SKIP_EXECUTE',
-}
-
 export type EstimateFeeAction =
   | {
       type: TransactionType.INVOKE;

src/types/provider/configuration.ts

@@ -6,6 +6,7 @@ export interface ProviderOptions extends RpcProviderOptions {}
 export type RpcProviderOptions = {
   nodeUrl?: string | NetworkName;
   retries?: number;
+  transactionRetryIntervalFallback?: number;
   headers?: object;
   blockIdentifier?: BlockIdentifier;
   chainId?: StarknetChainId;

src/types/provider/response.ts

@@ -137,6 +137,7 @@ export type Storage = FELT;
 
 export type Nonce = string;
 
+export type { SIMULATION_FLAG };
 export type SimulationFlags = Array<SIMULATION_FLAG>;
 
 export type SimulatedTransaction = SimulateTransaction & {

src/utils/calldata/byteArray.ts

@@ -32,7 +32,7 @@ export function stringFromByteArray(myByteArray: ByteArray): string {
 
 /**
  * convert a JS string to a Cairo ByteArray
- * @param myString a JS string
+ * @param targetString a JS string
  * @returns Cairo representation of a LongString
  * @example
  * ```typescript

src/utils/calldata/index.ts

@@ -104,7 +104,7 @@ export class CallData {
    * Compile contract callData with abi
    * Parse the calldata by using input fields from the abi for that method
    * @param method string - method name
-   * @param args RawArgs - arguments passed to the method. Can be an array of arguments (in the order of abi definition), or an object constructed in conformity with abi (in this case, the parameter can be in a wrong order).
+   * @param argsCalldata RawArgs - arguments passed to the method. Can be an array of arguments (in the order of abi definition), or an object constructed in conformity with abi (in this case, the parameter can be in a wrong order).
    * @return Calldata - parsed arguments in format that contract is expecting
    * @example
    * ```typescript

src/wallet/connect.ts

@@ -121,7 +121,8 @@ export function addDeclareTransaction(
 
 /**
  * Sign typed data using the wallet.
- * @param params The typed data to sign.
+ * @param swo the starknet (wallet) window object to request the signature.
+ * @param typedData The typed data to sign.
  * @returns An array of signatures as strings.
  */
 export function signMessage(swo: StarknetWindowObject, typedData: TypedData) {