Skip to content

Commit 0ab0de7

Browse files
petersdtpetersdt
authored
chore: add examples to JsDoc for transaction.ts file (#1105)
1 parent 0b25aba commit 0ab0de7

File tree

1 file changed

+173
-6
lines changed

1 file changed

+173
-6
lines changed

‎src/utils/transaction.ts

Lines changed: 173 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,33 @@ import { randomAddress } from './stark';
1919
/**
2020
* Transforms a list of Calls, each with their own calldata, into
2121
* two arrays: one with the entry points, and one with the concatenated calldata
22+
* @param calls - The list of calls to transform.
23+
* @returns An object containin two arrays: callArray and calldata.
24+
* @example
25+
* ```typescript
26+
* const calls: Call[] = [
27+
* {
28+
* contractAddress: "0x1234567890123456789012345678901234567890",
29+
* entrypoint: "functionName",
30+
* calldata: [1,2,3]
31+
* },
32+
* {
33+
* contractAddress: "0x0987654321098765432109876543210987654321",
34+
* entrypoint: "anotherFunction",
35+
* calldata: [4,5,6]
36+
* }
37+
* ];
38+
* const transformedData = transformCallsToMulticallArrays(calls);
39+
* console.log(transformedData);
40+
* // {
41+
* // callArray: [
42+
* // { to: "0x1234567890123456789012345678901234567890", selector: "1234567890",
43+
* // data_offset: "0", data_len: "3" },
44+
* // { to: "0x0987654321098765432109876543210987654321", selector: "1234567890",
45+
* // data_offset: "0987654321", data_offset: "3", data_len: "3"}
46+
* // ], calldata: [1, 2, 3, 4, 5, 6]
47+
* // }
48+
* ```
2249
*/
2350
export const transformCallsToMulticallArrays = (calls: Call[]) => {
2451
const callArray: ParsedStruct[] = [];
@@ -41,6 +68,26 @@ export const transformCallsToMulticallArrays = (calls: Call[]) => {
4168

4269
/**
4370
* Transforms a list of calls into the Cairo 0 `__execute__` calldata.
71+
* @param calls - The list of calls to transform.
72+
* @returns The Cairo 0 `__execute__` calldata.
73+
* @example
74+
* ```typescript
75+
* const calls: Call[] = [
76+
* {
77+
* contractAddress: "0x1234567890123456789012345678901234567890",
78+
* entrypoint: "functionName",
79+
* calldata: [1, 2, 3]
80+
* },
81+
* {
82+
* contractAddress: "0x0987654321098765432109876543210987654321",
83+
* entrypoint: "anotherFunction",
84+
* calldata: [4, 5, 6]
85+
* }
86+
* ];
87+
* const executeCalldata = fromCallsToExecuteCalldata(calls);
88+
* console.log(executeCalldata);
89+
* // [1234567890, 0987654321, 0, 6, 1, 2, 3, 4, 5, 6]
90+
* ```
4491
*/
4592
export const fromCallsToExecuteCalldata = (calls: Call[]) => {
4693
const { callArray, calldata } = transformCallsToMulticallArrays(calls);
@@ -50,17 +97,68 @@ export const fromCallsToExecuteCalldata = (calls: Call[]) => {
5097

5198
/**
5299
* Transforms a list of calls into the Cairo 0 `__execute__` calldata including nonce.
53-
*
100+
* @param calls - The list of calls to transform.
101+
* @param nonce - The nonce to include in the calldata.
102+
* @returns The Cairo 0 `__execute__` calldata including the nonce.
54103
* @deprecated
104+
* @example
105+
* ```typescript
106+
* const calls: Call[] = [
107+
* {
108+
* contractAddress: "0x1234567890123456789012345678901234567890",
109+
* entrypoint: "functionName",
110+
* calldata: [1, 2, 3]
111+
* },
112+
* {
113+
* contractAddress: "0x0987654321098765432109876543210987654321",
114+
* entrypoint: "anotherFunction",
115+
* calldata: [4, 5, 6]
116+
* }
117+
* ];
118+
* const nonce = 123;
119+
* const result = fromCallsToExecuteCalldataWithNonce(calls, nonce);
120+
* console.log(result);
121+
* // [1234567890, 0987654321, 0, 6, 1, 2, 3, 4, 5, 6, "123"]
122+
* ```
55123
*/
56124
export const fromCallsToExecuteCalldataWithNonce = (calls: Call[], nonce: BigNumberish) => {
57125
return [...fromCallsToExecuteCalldata(calls), toBigInt(nonce).toString()] as Calldata;
58126
};
59127

60128
/**
61129
* Format Data inside Calls
62-
*
130+
* @param calls - The list of calls to transform.
63131
* @deprecated Not required for getting execute Calldata
132+
* @returns An array of formatted call data.
133+
* @example
134+
* ```typescript
135+
* const calls: Call[] = [
136+
* {
137+
* contractAddress: "0x1234567890123456789012345678901234567890"
138+
* entrypoint: "functionName",
139+
* calldata: [1, 2, 3]
140+
* },
141+
* {
142+
* contractAddress: "0x0987654321098765432109876543210987654321",
143+
* entrypoint: "anotherFunction",
144+
* calldata: [4, 5, 6]
145+
* }
146+
* ];
147+
* const result = transformCallsToMulticallArrays_cairo1(calls);
148+
* console.log(formattedCalls);
149+
* // [
150+
* // {
151+
* // to: "1234567890123456789012345678901234567890",
152+
* // selector: "1234567890",
153+
* // calldata: [1, 2, 3]
154+
* // },
155+
* // {
156+
* // to: "0987654321098765432109876543210987654321",
157+
* // selector: "0987654321",
158+
* // calldata: [4, 5, 6]
159+
* // }
160+
* // ]
161+
* ```
64162
*/
65163
export const transformCallsToMulticallArrays_cairo1 = (calls: Call[]) => {
66164
const callArray = calls.map<CallStruct>((call) => ({
@@ -73,6 +171,26 @@ export const transformCallsToMulticallArrays_cairo1 = (calls: Call[]) => {
73171

74172
/**
75173
* Transforms a list of calls into the Cairo 1 `__execute__` calldata.
174+
* @param calls - The list of calls to transform.
175+
* @returns The Cairo 1 `__execute__` calldata.
176+
* @example
177+
* ```typescript
178+
* const calls: Call[] = [
179+
* {
180+
* contractAddress: "0x1234567890123456789012345678901234567890",
181+
* entrypoint: "functionName",
182+
* calldata: [1, 2, 3]
183+
* },
184+
* {
185+
* contractAddress: "0x0987654321098765432109876543210987654321",
186+
* entrypoint: "anotherFunction",
187+
* calldata: [4, 5, 6]
188+
* }
189+
* ];
190+
* const result = fromCallsToExecuteCalldata_cairo1(calls);
191+
* console.log(result);
192+
* // [1234567890, 0987654321, 0, 6, 1, 2, 3, 4, 5, 6]
193+
* ```
76194
*/
77195
export const fromCallsToExecuteCalldata_cairo1 = (calls: Call[]) => {
78196
// ensure property order
@@ -89,7 +207,28 @@ export const fromCallsToExecuteCalldata_cairo1 = (calls: Call[]) => {
89207
};
90208

91209
/**
92-
* Create `__execute__` Calldata from Calls based on Cairo versions
210+
* Create `__execute__` Calldata from Calls based on Cairo versions.
211+
* @param calls - The list of calls to transform.
212+
* @param cairoVersion - The Cairo version.
213+
* @returns The `__execute__` calldata.
214+
* @example
215+
* ```typescript
216+
* const calls: Call[] = [
217+
* {
218+
* contractAddress: "0x1234567890123456789012345678901234567890",
219+
* entrypoint: "functionName",
220+
* calldata: [1, 2, 3]
221+
* },
222+
* {
223+
* contractAddress: "0x0987654321098765432109876543210987654321",
224+
* entrypoint: "anotherFunction",
225+
* calldata: [4, 5, 6]
226+
* }
227+
* ];
228+
* const result = getExecuteCalldata(calls, '1');
229+
* console.log(result);
230+
* // [1234567890, 0987654321, 0, 6, 1, 2, 3, 4, 5, 6]
231+
* ```
93232
*/
94233
export const getExecuteCalldata = (calls: Call[], cairoVersion: CairoVersion = '0') => {
95234
if (cairoVersion === '1') {
@@ -101,10 +240,30 @@ export const getExecuteCalldata = (calls: Call[], cairoVersion: CairoVersion = '
101240
/**
102241
* Builds a UDCCall object.
103242
*
104-
* @param {UniversalDeployerContractPayload | UniversalDeployerContractPayload[]} payload - The payload data for the UDCCall. Can be a single payload object or an array of payload objects
105-
*.
243+
* @param {UniversalDeployerContractPayload | UniversalDeployerContractPayload[]} payload - The payload data for the UDCCall. Can be a single payload object or an array of payload objects.
106244
* @param {string} address - The address to be used in the UDCCall.
107245
* @returns {{ calls: Array, addresses: Array }} - The UDCCall object containing an array of calls and an array of addresses.
246+
* @example
247+
* ```typescript
248+
* const payload: UniversalDeployerContractPayload = {
249+
* classHash: "0x1234567890123456789012345678901234567890",
250+
* salt: "0x0987654321098765432109876543210987654321",
251+
* unique:true,
252+
* constructCalldata: [1, 2, 3]
253+
* };
254+
* const address = "0xABCDEF1234567890ABCDEF1234567890ABCDEF12",
255+
* const udcall = buildUDCCall(payload, address);
256+
* console.log(udccall);
257+
* // {
258+
* // calls: [
259+
* {
260+
* // contractAddress: "0xABCDEF1234567890ABCDEF1234567890ABCDEF12",
261+
* // entrypoint: "functionName",
262+
* // calldata: [classHash, salt, true, 3, 1, 2, 3]
263+
* // }],
264+
* // addresses: ["0x6fD084B56a7EDc5C06B3eB40f97Ae5A0C707A865"]
265+
* // }
266+
* ```
108267
*/
109268
export function buildUDCCall(
110269
payload: UniversalDeployerContractPayload | UniversalDeployerContractPayload[],
@@ -149,7 +308,15 @@ export function buildUDCCall(
149308
}
150309

151310
/**
152-
* Return transaction versions based on version type, default version type is 'transaction'
311+
* Return transaction versions based on version type, default version type is 'transaction'.
312+
* @param versionType - The type of version ("fee" or "transaction").
313+
* @returns An object containing transaction versions.
314+
* @example
315+
* ```typescript
316+
* const transactionVersions = getVersionsByType('fee');
317+
* console.log(transactionVersions);
318+
* // { v1: 1, v2: 2, v3: 3 }
319+
* ```
153320
*/
154321
export function getVersionsByType(versionType?: 'fee' | 'transaction') {
155322
return versionType === 'fee'

0 commit comments

Comments
 (0)