diff --git a/apps/nextra/next.config.mjs b/apps/nextra/next.config.mjs index ca3ccc19b..3accb7c64 100644 --- a/apps/nextra/next.config.mjs +++ b/apps/nextra/next.config.mjs @@ -441,6 +441,19 @@ export default withBundleAnalyzer( "/en/build/indexer/indexer-sdk/documentation/run-processor", permanent: true, }, + { + source: "/indexer/indexer-sdk/documentation/advanced-tutorials", + destination: + "/en/build/indexer/indexer-sdk/documentation/advanced-tutorials", + permanent: true, + }, + { + source: + "/indexer/indexer-sdk/documentation/advanced-tutorials/txn-importer", + destination: + "/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/txn-importer", + 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/documentation/_meta.tsx b/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/_meta.tsx index e1e57a819..3bf178da3 100644 --- a/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/_meta.tsx +++ b/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/_meta.tsx @@ -15,4 +15,7 @@ export default { "connect-steps": { title: "Connecting Steps", }, + "advanced-tutorials": { + title: "Advanced Tutorials", + }, }; diff --git a/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials.mdx b/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials.mdx new file mode 100644 index 000000000..de883b7e8 --- /dev/null +++ b/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials.mdx @@ -0,0 +1,5 @@ +--- +title: "Advanced Tutorials" +--- + +# Documentation diff --git a/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/_meta.tsx b/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/_meta.tsx new file mode 100644 index 000000000..bf8590451 --- /dev/null +++ b/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/_meta.tsx @@ -0,0 +1,6 @@ +export default { + // setup: { title: "Initial Setup" }, + "txn-importer": { + title: "Importing Transactions", + }, +}; diff --git a/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/txn-importer.mdx b/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/txn-importer.mdx new file mode 100644 index 000000000..c5311f942 --- /dev/null +++ b/apps/nextra/pages/en/build/indexer/indexer-sdk/documentation/advanced-tutorials/txn-importer.mdx @@ -0,0 +1,92 @@ +--- +title: "Aptos Transaction Import" +--- + +## Overview + +This will guide how to generate test transactions using the `importer` tool for Aptos networks (Devnet/Testnet/Mainnet). These transactions are then used in automated tests, local development, or regression checks. + +## General Flow of Transaction Importing + +First, identify the transaction versions you need to fetch from the Aptos network. This tool interacts with the Aptos gRPC endpoint 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 a testing framework. 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 schema. + +## Prerequisites + +1. Access to a Network (Testnet/Mainnet): + - A valid API key for the gRPC endpoint. ([Refer here](https://developers.aptoslabs.com/docs/api-access)) +2. Clone the [aptos-core](https://github.com/aptos-labs/aptos-core) repository: + - Navigate to the `aptos-core/ecosystem/indexer-grpc/indexer-transaction-generator` directory. + +## Steps + +### 1. Specify Versions to Import + +Locate and open the file: + +```bash +ecosystem/indexer-grpc/indexer-transaction-generator/imported_transactions/imported_transactions.yaml +``` + +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: + +```yaml +testnet: + transaction_stream_endpoint: https://grpc.testnet.aptoslabs.com:443 + api_key: TESTNET_API_KEY # <--- Replace this with your API key to generate files locally + versions_to_import: + 1: 1_genesis + 2: 2_new_block_event + 3: 3_empty_txn + 278556781: 278556781_v1_coin_register_fa_metadata + 1255836496: 1255836496_v2_fa_metadata_ + 5979639459: 5979639459_coin_register + 5992795934: 5992795934_fa_activities + 5523474016: 5523474016_validator_txn + +mainnet: + transaction_stream_endpoint: https://grpc.mainnet.aptoslabs.com:443 + api_key: MAINNET_API_KEY + versions_to_import: + 308783012: 308783012_fa_transfer +``` + +### 2. Run the Command to Import Transactions + +To import the specified transaction versions, execute the following command: + +```bash +cargo run -- --testing-folder ./imported_transactions --output-folder ../indexer-test-transactions/src/ +``` + +This command will: + +1. Read the configuration from the `imported_transactions.yaml` file. +2. Fetch the specified transaction versions from the selected network (Testnet or Mainnet). +3. Store the resulting JSON files in the specified output folder (`../indexer-test-transactions/src/json_transactions`). +4. Generate a Rust file (`generated_transactions.rs`) that converts the generated transaction JSON files into constant variables for use in tests. + +## How to Use the Testing Transactions + +### Export the Generated File + +Update the `mod.rs` file to include the generated Rust file containing the transaction constants. + +[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 + +Ensure the `json_transactions` folder is properly exported in the library file. + +[Reference lib.rs](https://github.com/aptos-labs/aptos-indexer-processor-example/blob/main/test-transactions-example/src/lib.rs). + +### Add as a Dependency + +Include the crate containing the generated transactions as a dependency in the `Cargo.toml` file of your test crate. (Internally, we store transactions in `aptos-core` and use them in the [processor repo](https://github.com/aptos-labs/aptos-indexer-processors/blob/0c92d323b0f560b5f8601a831a36520ad9b72d68/rust/Cargo.toml#L34)). + +### Integrate into Test Cases + +Use the exported transaction constants directly in your test cases to simulate real transactions and validate processing logic. + +Example usage: + +[Example Crate](https://github.com/aptos-labs/aptos-indexer-processor-example/tree/main/test-transactions-example).