Skip to content

Commit

Permalink
chore: add examples to JsDoc for transaction.ts file (starknet-io#1105)
Browse files Browse the repository at this point in the history
  • Loading branch information
@petersdt
petersdt committed Apr 29, 2024
1 parent 0b25aba commit 0ab0de7
Showing 1 changed file with 173 additions and 6 deletions.
179 changes: 173 additions & 6 deletions src/utils/transaction.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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[] = [];
Expand All @@ -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);
Expand All @@ -50,17 +97,68 @@ 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;
};

/**
* 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<CallStruct>((call) => ({
Expand All @@ -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
Expand All @@ -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') {
Expand All @@ -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[],
Expand Down Expand Up @@ -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'
Expand Down

0 comments on commit 0ab0de7

Please sign in to comment.