From 0ab0de70142b07186502c6457933858ccec6e23e Mon Sep 17 00:00:00 2001 From: Peterson_dt <168048103+petersdt@users.noreply.github.com> Date: Mon, 29 Apr 2024 11:29:00 +0100 Subject: [PATCH] chore: add examples to JsDoc for transaction.ts file (#1105) --- src/utils/transaction.ts | 179 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 173 insertions(+), 6 deletions(-) diff --git a/src/utils/transaction.ts b/src/utils/transaction.ts index 308290223..8ed2ad0fa 100644 --- a/src/utils/transaction.ts +++ b/src/utils/transaction.ts @@ -19,6 +19,33 @@ import { randomAddress } from './stark'; /** * Transforms a list of Calls, each with their own calldata, into * two arrays: one with the entry points, and one with the concatenated calldata + * @param calls - The list of calls to transform. + * @returns An object containin two arrays: callArray and calldata. + * @example + * ```typescript + * const calls: Call[] = [ + * { + * contractAddress: "0x1234567890123456789012345678901234567890", + * entrypoint: "functionName", + * calldata: [1,2,3] + * }, + * { + * contractAddress: "0x0987654321098765432109876543210987654321", + * entrypoint: "anotherFunction", + * calldata: [4,5,6] + * } + * ]; + * const transformedData = transformCallsToMulticallArrays(calls); + * console.log(transformedData); + * // { + * // callArray: [ + * // { to: "0x1234567890123456789012345678901234567890", selector: "1234567890", + * // data_offset: "0", data_len: "3" }, + * // { to: "0x0987654321098765432109876543210987654321", selector: "1234567890", + * // data_offset: "0987654321", data_offset: "3", data_len: "3"} + * // ], calldata: [1, 2, 3, 4, 5, 6] + * // } + * ``` */ export const transformCallsToMulticallArrays = (calls: Call[]) => { const callArray: ParsedStruct[] = []; @@ -41,6 +68,26 @@ export const transformCallsToMulticallArrays = (calls: Call[]) => { /** * Transforms a list of calls into the Cairo 0 `__execute__` calldata. + * @param calls - The list of calls to transform. + * @returns The Cairo 0 `__execute__` calldata. + * @example + * ```typescript + * const calls: Call[] = [ + * { + * contractAddress: "0x1234567890123456789012345678901234567890", + * entrypoint: "functionName", + * calldata: [1, 2, 3] + * }, + * { + * contractAddress: "0x0987654321098765432109876543210987654321", + * entrypoint: "anotherFunction", + * calldata: [4, 5, 6] + * } + * ]; + * const executeCalldata = fromCallsToExecuteCalldata(calls); + * console.log(executeCalldata); + * // [1234567890, 0987654321, 0, 6, 1, 2, 3, 4, 5, 6] + * ``` */ export const fromCallsToExecuteCalldata = (calls: Call[]) => { const { callArray, calldata } = transformCallsToMulticallArrays(calls); @@ -50,8 +97,29 @@ export const fromCallsToExecuteCalldata = (calls: Call[]) => { /** * Transforms a list of calls into the Cairo 0 `__execute__` calldata including nonce. - * + * @param calls - The list of calls to transform. + * @param nonce - The nonce to include in the calldata. + * @returns The Cairo 0 `__execute__` calldata including the nonce. * @deprecated + * @example + * ```typescript + * const calls: Call[] = [ + * { + * contractAddress: "0x1234567890123456789012345678901234567890", + * entrypoint: "functionName", + * calldata: [1, 2, 3] + * }, + * { + * contractAddress: "0x0987654321098765432109876543210987654321", + * entrypoint: "anotherFunction", + * calldata: [4, 5, 6] + * } + * ]; + * const nonce = 123; + * const result = fromCallsToExecuteCalldataWithNonce(calls, nonce); + * console.log(result); + * // [1234567890, 0987654321, 0, 6, 1, 2, 3, 4, 5, 6, "123"] + * ``` */ export const fromCallsToExecuteCalldataWithNonce = (calls: Call[], nonce: BigNumberish) => { return [...fromCallsToExecuteCalldata(calls), toBigInt(nonce).toString()] as Calldata; @@ -59,8 +127,38 @@ export const fromCallsToExecuteCalldataWithNonce = (calls: Call[], nonce: BigNum /** * Format Data inside Calls - * + * @param calls - The list of calls to transform. * @deprecated Not required for getting execute Calldata + * @returns An array of formatted call data. + * @example + * ```typescript + * const calls: Call[] = [ + * { + * contractAddress: "0x1234567890123456789012345678901234567890" + * entrypoint: "functionName", + * calldata: [1, 2, 3] + * }, + * { + * contractAddress: "0x0987654321098765432109876543210987654321", + * entrypoint: "anotherFunction", + * calldata: [4, 5, 6] + * } + * ]; + * const result = transformCallsToMulticallArrays_cairo1(calls); + * console.log(formattedCalls); + * // [ + * // { + * // to: "1234567890123456789012345678901234567890", + * // selector: "1234567890", + * // calldata: [1, 2, 3] + * // }, + * // { + * // to: "0987654321098765432109876543210987654321", + * // selector: "0987654321", + * // calldata: [4, 5, 6] + * // } + * // ] + * ``` */ export const transformCallsToMulticallArrays_cairo1 = (calls: Call[]) => { const callArray = calls.map((call) => ({ @@ -73,6 +171,26 @@ export const transformCallsToMulticallArrays_cairo1 = (calls: Call[]) => { /** * Transforms a list of calls into the Cairo 1 `__execute__` calldata. + * @param calls - The list of calls to transform. + * @returns The Cairo 1 `__execute__` calldata. + * @example + * ```typescript + * const calls: Call[] = [ + * { + * contractAddress: "0x1234567890123456789012345678901234567890", + * entrypoint: "functionName", + * calldata: [1, 2, 3] + * }, + * { + * contractAddress: "0x0987654321098765432109876543210987654321", + * entrypoint: "anotherFunction", + * calldata: [4, 5, 6] + * } + * ]; + * const result = fromCallsToExecuteCalldata_cairo1(calls); + * console.log(result); + * // [1234567890, 0987654321, 0, 6, 1, 2, 3, 4, 5, 6] + * ``` */ export const fromCallsToExecuteCalldata_cairo1 = (calls: Call[]) => { // ensure property order @@ -89,7 +207,28 @@ export const fromCallsToExecuteCalldata_cairo1 = (calls: Call[]) => { }; /** - * Create `__execute__` Calldata from Calls based on Cairo versions + * Create `__execute__` Calldata from Calls based on Cairo versions. + * @param calls - The list of calls to transform. + * @param cairoVersion - The Cairo version. + * @returns The `__execute__` calldata. + * @example + * ```typescript + * const calls: Call[] = [ + * { + * contractAddress: "0x1234567890123456789012345678901234567890", + * entrypoint: "functionName", + * calldata: [1, 2, 3] + * }, + * { + * contractAddress: "0x0987654321098765432109876543210987654321", + * entrypoint: "anotherFunction", + * calldata: [4, 5, 6] + * } + * ]; + * const result = getExecuteCalldata(calls, '1'); + * console.log(result); + * // [1234567890, 0987654321, 0, 6, 1, 2, 3, 4, 5, 6] + * ``` */ export const getExecuteCalldata = (calls: Call[], cairoVersion: CairoVersion = '0') => { if (cairoVersion === '1') { @@ -101,10 +240,30 @@ export const getExecuteCalldata = (calls: Call[], cairoVersion: CairoVersion = ' /** * Builds a UDCCall object. * - * @param {UniversalDeployerContractPayload | UniversalDeployerContractPayload[]} payload - The payload data for the UDCCall. Can be a single payload object or an array of payload objects - *. + * @param {UniversalDeployerContractPayload | UniversalDeployerContractPayload[]} payload - The payload data for the UDCCall. Can be a single payload object or an array of payload objects. * @param {string} address - The address to be used in the UDCCall. * @returns {{ calls: Array, addresses: Array }} - The UDCCall object containing an array of calls and an array of addresses. + * @example + * ```typescript + * const payload: UniversalDeployerContractPayload = { + * classHash: "0x1234567890123456789012345678901234567890", + * salt: "0x0987654321098765432109876543210987654321", + * unique:true, + * constructCalldata: [1, 2, 3] + * }; + * const address = "0xABCDEF1234567890ABCDEF1234567890ABCDEF12", + * const udcall = buildUDCCall(payload, address); + * console.log(udccall); + * // { + * // calls: [ + * { + * // contractAddress: "0xABCDEF1234567890ABCDEF1234567890ABCDEF12", + * // entrypoint: "functionName", + * // calldata: [classHash, salt, true, 3, 1, 2, 3] + * // }], + * // addresses: ["0x6fD084B56a7EDc5C06B3eB40f97Ae5A0C707A865"] + * // } + * ``` */ export function buildUDCCall( payload: UniversalDeployerContractPayload | UniversalDeployerContractPayload[], @@ -149,7 +308,15 @@ export function buildUDCCall( } /** - * Return transaction versions based on version type, default version type is 'transaction' + * Return transaction versions based on version type, default version type is 'transaction'. + * @param versionType - The type of version ("fee" or "transaction"). + * @returns An object containing transaction versions. + * @example + * ```typescript + * const transactionVersions = getVersionsByType('fee'); + * console.log(transactionVersions); + * // { v1: 1, v2: 2, v3: 3 } + * ``` */ export function getVersionsByType(versionType?: 'fee' | 'transaction') { return versionType === 'fee'