Skip to content

Commit aeacbb0

Browse files
yuunlimmyuunlimm
committed
importing test transactions
1 parent e69ef98 commit aeacbb0

File tree

5 files changed

+135
-0
lines changed

5 files changed

+135
-0
lines changed

‎apps/nextra/next.config.mjs

+13
Original file line numberDiff line numberDiff line change
@@ -447,6 +447,19 @@ export default withBundleAnalyzer(
447447
"/en/build/indexer/indexer-sdk/documentation/run-processor",
448448
permanent: true,
449449
},
450+
{
451+
source: "/indexer/indexer-sdk/documentation/advanced-tutorials",
452+
destination:
453+
"/en/build/indexer/indexer-sdk/documentation/advanced-tutorials",
454+
permanent: true,
455+
},
456+
{
457+
source:
458+
"/indexer/indexer-sdk/documentation/advanced-tutorials/txn-importer",
459+
destination:
460+
"/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/txn-importer",
461+
permanent: true,
462+
},
450463
{
451464
source: "/indexer/txn-stream/labs-hosted",
452465
destination: "/en/build/indexer/api/labs-hosted",

‎apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/_meta.tsx

+3
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,7 @@ export default {
1818
"version-tracking": {
1919
title: "Version Tracking",
2020
},
21+
"advanced-tutorials": {
22+
title: "Advanced Tutorials",
23+
},
2124
};

‎apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials.mdx

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "Advanced Tutorials"
3+
---
4+
5+
# Advanced Tutorials

‎apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/_meta.tsx

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
export default {
2+
"txn-importer": {
3+
title: "Importing Transactions",
4+
},
5+
};

‎apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/txn-importer.mdx

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: "Aptos Transaction Import"
3+
---
4+
5+
## Overview
6+
7+
This guide explains how to import Aptos transactions for testing using the `aptos-indexer-transaction-generator` tool. These test transactions can be used to test your custom processors and support their local development.
8+
9+
## General Flow of Transaction Importing
10+
11+
First, identify the transaction versions you need to fetch from the Aptos network. This tool interacts with the [Transaction Stream](https://aptos.dev/en/build/indexer/txn-stream) to retrieve transaction data in JSON format. The transactions are then consolidated into a Rust file, where each transaction is represented as a constant variable. These constants can be seamlessly used as mocked inputs in processor automated tests. During testing, the processor fetches the specified transactions, processes them, and writes the results to a database. You can then verify the outcomes by loading the written data and validating it against the expected data.
12+
13+
## Prerequisites
14+
15+
1. A valid API key to connect to [Transaction Stream](https://aptos.dev/en/build/indexer/txn-stream/aptos-hosted-txn-stream)
16+
2. Clone the [aptos-core](https://github.com/aptos-labs/aptos-core) repository:
17+
- Navigate to the `aptos-core/ecosystem/indexer-grpc/indexer-transaction-generator` directory.
18+
19+
## How to Import Test Transactions
20+
21+
### 1. Specify Versions to Import
22+
23+
Locate and make a copy of the file:
24+
25+
```bash
26+
ecosystem/indexer-grpc/indexer-transaction-generator/imported_transactions/imported_transactions.yaml
27+
```
28+
29+
In this file, specify the versions to import from Devnet|Testnet|Mainnet by configuring the appropriate endpoint, API key, and mapping version numbers to descriptive output names. An example configuration is shown below:
30+
31+
```yaml
32+
testnet:
33+
transaction_stream_endpoint: https://grpc.testnet.aptoslabs.com:443
34+
api_key: TESTNET_API_KEY # <--- Replace this with your API key to generate files locally
35+
versions_to_import:
36+
# Replace these with the versions you want to import
37+
1: 1_genesis
38+
2: 2_new_block_event
39+
3: 3_empty_txn
40+
278556781: 278556781_v1_coin_register_fa_metadata
41+
1255836496: 1255836496_v2_fa_metadata
42+
5979639459: 5979639459_coin_register
43+
5992795934: 5992795934_fa_activities
44+
5523474016: 5523474016_validator_txn
45+
46+
mainnet:
47+
transaction_stream_endpoint: https://grpc.mainnet.aptoslabs.com:443
48+
api_key: MAINNET_API_KEY
49+
versions_to_import:
50+
308783012: 308783012_fa_transfer
51+
```
52+
53+
### 2. Run the Command to Import Transactions
54+
55+
Navigate to the `indexer-transaction-generator` directory:
56+
57+
```bash
58+
cd aptos-core/ecosystem/indexer-grpc/indexer-transaction-generator
59+
```
60+
61+
To import the specified transaction versions, execute the following command:
62+
63+
```bash
64+
cargo run -- --testing-folder /path/to/your/imported_transactions.yaml --output-folder /path/to/your/processor-repo/src
65+
```
66+
67+
This command will:
68+
69+
1. Read the configuration from the `imported_transactions.yaml` file located in the folder specified by the --testing-folder flag.
70+
2. Fetch the specified transaction versions from the selected network (Devnet, Testnet or Mainnet).
71+
3. Store the resulting JSON files in the specified output folder (/path/to/your/processor-repo/src/json_transactions).
72+
4. Generate a Rust file (`generated_transactions.rs`) that converts the generated transaction JSON files into constant variables for use in tests.
73+
74+
Note: Replace /path/to/your/processor-repo with the path to your processor repository or preferred storage location.
75+
76+
**Explanation of Command Flags**
77+
1. `--testing-folder`
78+
What is the --testing-folder flag?
79+
The --testing-folder flag specifies the directory containing the imported_transactions.yaml configuration file. The tool uses this folder to read versions you wish to import.
80+
- Ensure the folder path matches the location of your imported_transactions.yaml file.
81+
- By default, this guide assumes the configuration is stored in ./imported_transactions. Adjust the flag value if you place the file elsewhere.
82+
83+
2. `--output-folder`
84+
Specifies the destination directory where the generated transaction JSON files and Rust constants will be saved.
85+
- Replace /path/to/your/processor-repo with your processor repository src directory or desired storage location.
86+
- Ensure this folder is part of your version control setup if these files need to be shared.
87+
88+
## How to Use the Testing Transactions
89+
90+
### Export the Generated File
91+
92+
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:
93+
94+
[Reference mod.rs](https://github.com/aptos-labs/aptos-indexer-processor-example/blob/main/test-transactions-example/src/json_transactions/mod.rs).
95+
96+
### Export the `json_transactions` Folder
97+
98+
Since the `generated_transactions.rs` reles 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.
99+
100+
[Reference lib.rs](https://github.com/aptos-labs/aptos-indexer-processor-example/blob/main/test-transactions-example/src/lib.rs).
101+
102+
### Integrate into Test Cases
103+
104+
Use the exported transaction constants directly in your test cases to simulate real transactions and validate processing logic.
105+
106+
[Example Crate](https://github.com/aptos-labs/aptos-indexer-processor-example/tree/main/test-transactions-example).
107+
108+
## Next Steps
109+
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]().

0 commit comments

Comments
 (0)