Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore: add examples to JsDoc for transaction.ts file #1105

Merged
merged 1 commit into from
Apr 29, 2024
Merged

chore: add examples to JsDoc for transaction.ts file #1105

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 173 additions & 6 deletions src/utils/transaction.ts
View file
Open in desktop
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",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reverted PR: these are ethereum addresses

* 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