From 9d90f2244ec02ab5206c9cb160dc6bafcf4b46f8 Mon Sep 17 00:00:00 2001 From: yuunlimm Date: Fri, 17 Jan 2025 10:12:52 -0800 Subject: [PATCH 1/2] generating test transactions with move script --- apps/nextra/next.config.mjs | 7 ++ .../indexer-sdk/advanced-tutorials/_meta.tsx | 3 + .../advanced-tutorials/txn-importer.mdx | 2 +- .../advanced-tutorials/txn-script.mdx | 105 ++++++++++++++++++ 4 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-script.mdx diff --git a/apps/nextra/next.config.mjs b/apps/nextra/next.config.mjs index 1bd9784d9..52d9e9e20 100644 --- a/apps/nextra/next.config.mjs +++ b/apps/nextra/next.config.mjs @@ -466,6 +466,13 @@ export default withBundleAnalyzer( "/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/txn-importer", permanent: true, }, + { + source: + "/indexer/indexer-sdk/documentation/advanced-tutorials/txn-script", + destination: + "/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/txn-script", + permanent: true, + }, { source: "/indexer/txn-stream/labs-hosted", destination: "/en/build/indexer/api/labs-hosted", diff --git a/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/_meta.tsx b/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/_meta.tsx index fec98c5c6..9b2d4f4db 100644 --- a/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/_meta.tsx +++ b/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/_meta.tsx @@ -5,4 +5,7 @@ export default { "txn-importer": { title: "Importing Transactions", }, + "txn-script": { + title: "Generating Transactions with Move Scripts", + }, }; diff --git a/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-importer.mdx b/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-importer.mdx index 3875b1135..55dbc8580 100644 --- a/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-importer.mdx +++ b/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-importer.mdx @@ -1,5 +1,5 @@ --- -title: "Aptos Transaction Import" +title: "Importing Transactions" --- ## Overview diff --git a/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-script.mdx b/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-script.mdx new file mode 100644 index 000000000..0e1afba84 --- /dev/null +++ b/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-script.mdx @@ -0,0 +1,105 @@ +--- +title: "Generating Transactions with Move Scripts" +--- + +import { Callout, Steps } from "nextra/components" + +## Overview: + +This section outlines how to create test transactions with Move scripts. + +## Prerequisites + +1. Clone the [aptos-core](https://github.com/aptos-labs/aptos-core) repository: + - Navigate to the `aptos-core/ecosystem/indexer-grpc/indexer-transaction-generator` directory. + +## How to Generate Test Transactions using Move Script + +### Set up `move_fixtures` folder +Before proceeding, ensure you have the `move_fixtures` folder set up in the appropriate location: +1. Location: + The `move_fixtures` folder should be created in the `aptos-core/ecosystem/indexer-grpc/indexer-transaction-generator/imported_transactions` directory. This is the folder where Move scripts and their configurations for test transactions will be stored. + + **Note:** Do not create the `move_fixtures` folder in your processor repository. All Move-related files should reside in the `aptos-core` repository under the specified directory. +2. Steps to set up the folder: + - if starting fresh, remove all existing files and projects in the `move_fixtures` folder in the aptos-core repo + - Create your own Move projects/scripts in the move_fixtures folder (detailed in the next step) + + ### Create Your Move Project and Write your Move Script + + Create your Move project and write a module to output the scenario that you would like to test in your processor. You can refer to an example [here](https://github.com/aptos-labs/aptos-core/tree/main/ecosystem/indexer-grpc/indexer-transaction-generator/imported_transactions/move_fixtures). + + ### Set Up Test Accounts + + 1. These accounts will be used to deploy your module. + 2. Set up as many accounts as you need. These accounts will be used to send the scripted transactions. Refer to the guide [here](https://aptos.dev/en/build/cli/setup-cli) to create accounts. + 3. Update [`aptos-core/ecosystem/indexer-grpc/indexer-transaction-generator/imported_transactions/testing_accounts.yaml`](https://github.com/aptos-labs/aptos-core/blob/main/ecosystem/indexer-grpc/indexer-transaction-generator/imported_transactions/testing_accounts.yaml) with your accounts. + + **Note:** Do not use real accounts here. Only use **test accounts** created in the CLI specifically for testing. Always select **devnet** when setting up a test account, as it will be required later in the script to configure the account profile and fund it using the faucet. + + ### Create a Configuration File +Each configuration file defines a sequences of transactions for a test scenario. + 1. Create a configuration file in the `move_fixtures` [directory](https://github.com/aptos-labs/aptos-core/blob/main/ecosystem/indexer-grpc/indexer-transaction-generator/imported_transactions/move_fixtures). Name the configuration file according to the test scenario it corresponds to. + 2. This configuration file should contain unique transaction names and details for each transaction. The transactions should be listed in the order they are to be executed. + The configuration file should be structured like this: + - output_name: This field specifies the name of the output file where the results of the transaction will be saved. + - script_path: This field holds the path to the Move script file that will be executed as part of the transaction. + - sender_address: : This field contains the address of the account that will send the transaction. + + ```yaml + transactions: + - output_name: simple_user_script1 + script_path: simple_user_script + sender_address: + - output_name: simple_user_script2 + script_path: simple_user_script2 + sender_address: + ``` + + ### Generate JSON Files and Rust File + + Once the Move files and configuration are set up, run the same command used to import transactions but with extra flag `mode`: + - testing-folder is where your Move files are stored. + - output-folder can be set to any folder where you want to store the generated files. + - The `--mode=script` flag specifies that the transaction generator should operate in script mode, meaning it will execute Move scripts and generate corresponding transaction data. By default, the mode is set to import, which fetches transactions from the network. + + ```bash + cd ~/aptos-core/ecosystem/indexer-grpc/indexer-transaction-generator + cargo run -- --testing-folder ./imported_transactions --output-folder ../indexer-test-transactions/src/ --script + ``` + + This command will: + + 1. Read the configuration in the `move_fixtures` folder. + 2. Execute the specified Move scripts. + 3. Output the generated JSON files to the designated folder (`~/aptos-core/ecosystem/indexer-grpc/indexer-transaction-generator/json_transactions`). + 4. Overwrite `generated_transactions.rs` with the new transaction data based on the generated JSON files. This file contains the transaction constants that can be used in tests. + +### Verification + +Verify that the json_transactions folder in the target directory contains the generated JSON files with the specified names from the configuration file, and ensure that generated_transactions.rs has been updated accordingly. + + + +## How to Use Test Transactions + +### Export the Generated File + +Update the `mod.rs` file to include the generated Rust file containing the transaction constants. If `mod.rs` doesn’t exist, create one in the target folder: + +[Reference mod.rs](https://github.com/aptos-labs/aptos-indexer-processor-example/blob/main/test-transactions-example/src/json_transactions/mod.rs). + +### Export the `json_transactions` Folder + +Since the `generated_transactions.rs` relies on the `json_transactions` Ensure the `json_transactions` folder is properly exported in the library file for your tests have direct access to the transaction data. + +[Reference lib.rs](https://github.com/aptos-labs/aptos-indexer-processor-example/blob/main/test-transactions-example/src/lib.rs). + +### Integrate into Test Cases + +Use the exported transaction constants directly in your test cases to simulate real transactions and validate processing logic. + +[Example Crate](https://github.com/aptos-labs/aptos-indexer-processor-example/tree/main/test-transactions-example). + +## Next Steps +Once the transaction constants are integrated, you can use them in processor tests to validate functionality. For detailed instructions on writing processor tests, refer to Writing Processor Tests. \ No newline at end of file From 1f3dfde9db232f5727bd8ff31f543ff9eeb95345 Mon Sep 17 00:00:00 2001 From: yuunlimm Date: Mon, 24 Feb 2025 11:40:16 -0800 Subject: [PATCH 2/2] update links --- .../indexer-sdk/advanced-tutorials/txn-script.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-script.mdx b/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-script.mdx index 0e1afba84..04dfa2bae 100644 --- a/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-script.mdx +++ b/apps/nextra/pages/en/build/indexer/indexer-sdk/advanced-tutorials/txn-script.mdx @@ -46,6 +46,7 @@ Each configuration file defines a sequences of transactions for a test scenario. - script_path: This field holds the path to the Move script file that will be executed as part of the transaction. - sender_address: : This field contains the address of the account that will send the transaction. + The number of output is totally up to you, but the output name should be unique for each transaction. Add as many transactions as you need to test your processor. ```yaml transactions: - output_name: simple_user_script1 @@ -72,7 +73,7 @@ Each configuration file defines a sequences of transactions for a test scenario. 1. Read the configuration in the `move_fixtures` folder. 2. Execute the specified Move scripts. - 3. Output the generated JSON files to the designated folder (`~/aptos-core/ecosystem/indexer-grpc/indexer-transaction-generator/json_transactions`). + 3. Output the generated JSON files to the designated folder (`~/aptos-core/ecosystem/indexer-grpc/indexer-test-transactions/src/json_transactions`). 4. Overwrite `generated_transactions.rs` with the new transaction data based on the generated JSON files. This file contains the transaction constants that can be used in tests. ### Verification @@ -85,7 +86,7 @@ Verify that the json_transactions folder in the target directory contains the ge ### Export the Generated File -Update the `mod.rs` file to include the generated Rust file containing the transaction constants. If `mod.rs` doesn’t exist, create one in the target folder: +Update the `mod.rs` file to include the generated Rust file containing the transaction constants. If `mod.rs` doesn't exist, create one in the target folder: [Reference mod.rs](https://github.com/aptos-labs/aptos-indexer-processor-example/blob/main/test-transactions-example/src/json_transactions/mod.rs). @@ -97,9 +98,10 @@ Since the `generated_transactions.rs` relies on the `json_transactions` Ensure t ### Integrate into Test Cases -Use the exported transaction constants directly in your test cases to simulate real transactions and validate processing logic. - -[Example Crate](https://github.com/aptos-labs/aptos-indexer-processor-example/tree/main/test-transactions-example). +If you decided to output the rust file in a different crate, you can update you cargo.toml to import the crate containing the generated file as a dependency. Otherwise, you can simply import the generated file directly in your test file. +[Example](https://github.com/aptos-labs/aptos-indexer-processors-v2/blob/main/integration-tests/Cargo.toml#L19). ## Next Steps -Once the transaction constants are integrated, you can use them in processor tests to validate functionality. For detailed instructions on writing processor tests, refer to Writing Processor Tests. \ No newline at end of file +Once the transaction constants are integrated, you can use them in processor tests to validate functionality. For detailed instructions on writing processor tests, refer to Writing Processor Tests. + +[Example](https://github.com/aptos-labs/aptos-indexer-processors-v2/blob/main/integration-tests/src/sdk_tests/events_processor_tests.rs) \ No newline at end of file