feat: Added examples package with commands and flashloan examples

.github/workflows/examples.yml

@@ -0,0 +1,34 @@
+permissions:
+  contents: read
+
+name: Examples
+
+on:
+  pull_request:
+  merge_group:
+    branches:
+      - main
+
+env:
+  CARGO_TERM_COLOR: always
+  GITHUB_ACTIONS: true
+  MOVE_VERSION: 2.1
+  COMPILER_VERSION: 2.0
+  ARTIFACTS_LEVEL: all
+
+jobs:
+  compile-examples:
+    name: Compile All Examples
+    runs-on: Larger-Github-Runners
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Aptos CLI
+        uses: ./.github/actions/install-aptos-cli
+        with:
+          version: "7.7.0"
+
+      - name: Run Aptos Compile All Examples
+        working-directory: examples
+        run: make compile

README.md

@@ -218,8 +218,8 @@ All audit reports related to Aave's Move implementation on Aptos are stored in t
 /audits
 ├── Certora Aave Aptos Core V3.0.2 Report.pdf
 ├── Certora Aave Aptos Core V3.1-V3.3 Report.pdf
-└── Certora Aave Aptos Periphery V3.0.2 Report.pdf
-└── Ottersec Aave Aptos V3.1-V3.3 Report.pdf
+├── Certora Aave Aptos Periphery V3.0.2 Report.pdf
+├── Ottersec Aave Aptos V3.1-V3.3 Report.pdf
 ├── Spearbit Aave Aptos Core V3.0.2 Report.pdf
 ├── Spearbit Aave Aptos Core V3.1-V3.3 Report.pdf
 └── Spearbit Aave Aptos Periphery V3.0.2 Report.pdf
@@ -241,3 +241,37 @@ The docs are auto-generated from each package and published using [MkDocs Materi
 Browse all modules, structs, functions, and events used across Aave's V3 Aptos packages.
 
 ---
+
+## 📜 Running Examples
+
+In addition to Move unit tests and integration tests, this repository contains **example scripts** (such as flashloans) that demonstrate how to interact with the deployed protocol on Aptos. They are all located under the `./examples` packages at root level.
+
+### 🛠️ Compile Example Scripts
+
+Example are compiled separately via calling the main commands listed under `./examples/Makefile`:
+
+```bash
+# For testnet
+make compile-scripts-testnet
+
+# For mainnet
+make compile-scripts-mainnet
+```
+
+### 🚀 Execute Example Scripts
+
+Once compiled, scripts can be executed against the target network compiled above. For example:
+
+```bash
+# Simple flashloan example
+make execute-flashloan-simple
+
+# Complex flashloan example
+make execute-flashloan-complex
+```
+
+Each script corresponds to a .mv compiled Move script under `./examples/build/AaveScripts/bytecode_scripts/`. They are executed via aptos move run-script, with arguments such as asset addresses and flashloan amounts passed in from the Makefile.
+
+🔍 These scripts are primarily intended as examples and tests of protocol functionality, such as taking and repaying flashloans.
+
+---

examples/Makefile

@@ -0,0 +1,84 @@
+# Conditionally include .env file if not running in CI/CD environment
+ifndef GITHUB_ACTIONS
+  -include ../.env
+endif
+
+compile-scripts-testnet:
+		aptos move compile \
+		--included-artifacts none \
+		--save-metadata \
+		--skip-fetch-latest-git-deps \
+		--language-version "$(MOVE_VERSION)" \
+		--compiler-version "$(COMPILER_VERSION)" \
+		--named-addresses "aave_acl=0xb23539ad6490a465e92e751943a3eaedf4b48d7d844ff59adf2ae66bcb09f53d,aave_config=0x4fb5d8348c8873295f97136bbe1c43d976fb18a4a966a85e21d16958eaecef99,aave_math=0xf6f896cefd7b1b1e85ff56033981cf92dcd5d6e93b1349a7ab5003761c52498d,aave_oracle=0xcb9eb79a52f41933192c2e1e37a9e72bfd726fdb9a687cd6cfe45527e52f4e41,aave_pool=0xbd7912c555a06809c2e385eab635ff0ef52b1fa062ce865c785c67694a12bb12,aave_large_packages=0x0e1ca3011bdd07246d4d16d909dbb2d6953a86c4735d5acf5865d962c630cce7,aave_mock_underlyings=0xe2b42cab2f84bf57edaf87bcaffee409c2b3d5243e3def00d9d2f7dec568d867,aave_data=0xb0ec364235f47ad2a8eb52d639c80579b11497d0711879840f1ce51c885b165f,data_feeds=0xf1099f135ddddad1c065203431be328a408b0ca452ada70374ce26bd2b32fdd3,platform=0x516e771e1b4a903afe74c27d057c65849ecc1383782f6642d7ff21425f4f9c99,aave_oracle_racc_address=0x3836084d178459c08f27620462d531f5b5b23d14ddbf4f47c4a72d404d87bcb4"
+
+compile-scripts-mainnet:
+		aptos move compile \
+		--included-artifacts none \
+		--save-metadata \
+		--skip-fetch-latest-git-deps \
+		--language-version "$(MOVE_VERSION)" \
+		--compiler-version "$(COMPILER_VERSION)" \
+		--named-addresses "aave_acl=0x34c3e6af238f3a7fa3f3b0088cbc4b194d21f62e65a15b79ae91364de5a81a3a,aave_config=0x531069f4741cdead39d70b76e5779863864654fae6db8a752a244ff2f9916c15,aave_math=0xc0338eea778de2a5348824ddbfcec033c7f7cbe18da6da40869562906b63c78c,aave_oracle=0x249676f3faddb83d64fd101baa3f84a171ae02505d796e3edbf4861038a4b5cc,aave_pool=0x39ddcd9e1a39fa14f25e3f9ec8a86074d05cc0881cbf667df8a6ee70942016fb,aave_large_packages=0x0e1ca3011bdd07246d4d16d909dbb2d6953a86c4735d5acf5865d962c630cce7,aave_mock_underlyings=0x12b05c42ac3209a3c6ffadff4ebb6c3e983e5115f26031d56652815b49a14245,aave_data=0x5eb5cc775c5a446db0f3a1c944e11563b97e6a7e1387b9fb459aa26168f738dc,data_feeds=0x3f985798ce4975f430ef5c75776ff98a77b9f9d0fb38184d225adc9c1cc6b79b,platform=0x9976bb288ed9177b542d568fa1ac386819dc99141630e582315804840f41928a,aave_oracle_racc_address=0x3836084d178459c08f27620462d531f5b5b23d14ddbf4f47c4a72d404d87bcb4"
+
+execute-flashloan-simple-dry-run:
+	aptos move run-script \
+	--local \
+	--assume-yes \
+	--compiled-script-path ./build/Examples/bytecode_scripts/flashloan_simple.mv \
+	--language-version "$(MOVE_VERSION)" \
+	--compiler-version "$(COMPILER_VERSION)" \
+	--sender-account "$(FLASHLOANER)" \
+	--profile "$(FLASHLOANER)" \
+	--args address:$(FLASHLOAN_ASSET) u256:$(FLASHLOAN_AMOUNT)
+
+execute-flashloan-complex-dry-run:
+	aptos move run-script \
+	--local \
+	--assume-yes \
+	--compiled-script-path ./build/Examples/bytecode_scripts/flashloan_complex.mv \
+	--language-version "$(MOVE_VERSION)" \
+	--compiler-version "$(COMPILER_VERSION)" \
+	--sender-account "$(FLASHLOANER)" \
+	--profile "$(FLASHLOANER)" \
+	--args address:$(FLASHLOAN_ASSET) u256:$(FLASHLOAN_AMOUNT)
+
+execute-flashloan-simple:
+	aptos move run-script \
+	--assume-yes \
+	--compiled-script-path ./build/Examples/bytecode_scripts/flashloan_simple.mv \
+	--language-version "$(MOVE_VERSION)" \
+	--compiler-version "$(COMPILER_VERSION)" \
+	--sender-account "$(FLASHLOANER)" \
+	--profile "$(FLASHLOANER)" \
+	--args address:$(FLASHLOAN_ASSET) u256:$(FLASHLOAN_AMOUNT)
+
+execute-flashloan-complex:
+	aptos move run-script \
+	--assume-yes \
+	--compiled-script-path ./build/Examples/bytecode_scripts/flashloan_complex.mv \
+	--language-version "$(MOVE_VERSION)" \
+	--compiler-version "$(COMPILER_VERSION)" \
+	--sender-account "$(FLASHLOANER)" \
+	--profile "$(FLASHLOANER)" \
+	--args address:$(FLASHLOAN_ASSET) u256:$(FLASHLOAN_AMOUNT)
+
+fmt-scripts:
+	aptos move fmt \
+	--package-path "." \
+	--config-path ../movefmt.toml \
+	--emit-mode "overwrite" \
+	-v
+
+# ------------------------------------------------------------
+# Common
+# ------------------------------------------------------------
+
+compile:
+	make compile-scripts-testnet
+	make compile-scripts-mainnet
+
+fmt:
+	make fmt-scripts
+
+clean: rm -rf build

examples/Move.toml

@@ -0,0 +1,22 @@
+[package]
+name = "Examples"
+version = "1.1.0"
+upgrade_policy = "compatible"
+authors = []
+
+[addresses]
+
+[dev-addresses]
+
+[dependencies]
+AptosStdlib = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-stdlib", rev = "mainnet" }
+AptosFramework = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-framework/", rev = "mainnet" }
+AptosToken = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-token", rev = "mainnet" }
+AptosTokenObjects = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-token-objects", rev = "mainnet" }
+AaveAcl = { local = "../aave-core/aave-acl" }
+AaveConfig = { local = "../aave-core/aave-config" }
+AaveOracle = { local = "../aave-core/aave-oracle" }
+AaveData = { local = "../aave-core/aave-data" }
+AavePool = { local = "../aave-core" }
+
+[dev-dependencies]

examples/sources/flashloan_complex.move

@@ -0,0 +1,150 @@
+// @title Complex Flashloans Test Script
+// @author Aave
+// @notice Script to test complex flashloans functionality in the Aave protocol
+script {
+    // imports
+    // std
+    use std::signer;
+    use std::vector;
+    use aptos_std::debug::print;
+    use aptos_std::string_utils::format1;
+    use aave_pool::fungible_asset_manager::Self;
+    // locals
+    use aave_pool::flashloan_logic::Self;
+
+    // Constants
+    // @notice Success code for successful execution
+    const SUCCESS: u64 = 1;
+
+    // @notice Failure code for failed execution
+    const FAILURE: u64 = 2;
+
+    /// @notice Test script for executing a complex flashloan
+    /// @param borrower The signer account executing the script (must be the borrower)
+    /// @param asset The address of the asset to be borrowed in the flashloan
+    /// @param amount The amount of the asset to be borrowed in the flashloan
+    fun flashloan_complex(
+        borrower: &signer, asset: address, amount: u256
+    ) {
+
+        let flashloan_borrower_address = signer::address_of(borrower);
+        let flashloan_asset = asset;
+        let flashloan_amount = amount;
+
+        // check the balance of the borrower before the flashloan is taken
+        let flashloaner_initial_balance =
+            fungible_asset_manager::balance_of(
+                flashloan_borrower_address, flashloan_asset
+            );
+        print(&format1(&b"Flashloaner initial balance: {}", flashloaner_initial_balance));
+
+        // user prepares to take a flashloan
+        let flashloan_receipts =
+            flashloan_logic::flash_loan(
+                borrower,
+                flashloan_borrower_address,
+                vector[flashloan_asset],
+                vector[flashloan_amount],
+                vector[2],
+                flashloan_borrower_address,
+                0 // no referral code
+            );
+
+        // assert that the flashloan receipts is not empty and it has only 1 item
+        assert!(vector::length(&flashloan_receipts) == 1, SUCCESS);
+
+        let first_flashloan_receipt = vector::borrow(&flashloan_receipts, 0);
+
+        // check the balance of the borrower after the flashloan
+        let flashloaner_postloan_balance =
+            fungible_asset_manager::balance_of(
+                flashloan_borrower_address, flashloan_asset
+            );
+        print(
+            &format1(&b"Flashloaner post-loan balance: {}", flashloaner_postloan_balance)
+        );
+
+        assert!(
+            (flashloaner_postloan_balance as u256)
+                == (flashloaner_initial_balance as u256) + flashloan_amount,
+            SUCCESS
+        );
+
+        // do assertion to check if the flashloan was successful
+        assert!(
+            flashloan_logic::get_complex_flashloan_current_amount(first_flashloan_receipt) ==
+            flashloan_amount,
+            SUCCESS
+        );
+        assert!(
+            flashloan_logic::get_complex_flashloan_current_asset(first_flashloan_receipt) ==
+            flashloan_asset,
+            SUCCESS
+        );
+        assert!(
+            flashloan_logic::get_complex_flashloan_on_behalf_of(first_flashloan_receipt)
+                == flashloan_borrower_address,
+            SUCCESS
+        );
+        assert!(
+            flashloan_logic::get_complex_flashloan_receipt_index(first_flashloan_receipt) ==
+            0,
+            SUCCESS
+        );
+        assert!(
+            flashloan_logic::get_complex_flashloan_receipt_receiver(
+                first_flashloan_receipt
+            ) == flashloan_borrower_address,
+            SUCCESS
+        );
+        assert!(
+            flashloan_logic::get_complex_flashloan_referral_code(first_flashloan_receipt) ==
+            0,
+            SUCCESS
+        );
+        assert!(
+            flashloan_logic::get_complex_flashloan_receipt_sender(first_flashloan_receipt) ==
+            flashloan_borrower_address,
+            SUCCESS
+        );
+
+        print(
+            &format1(
+                &b"flashloan_premium_total: {}",
+                flashloan_logic::get_complex_flashloan_premium_total(
+                    first_flashloan_receipt
+                )
+            )
+        );
+        print(
+            &format1(
+                &b"flashloan_premium_to_protocol: {}",
+                flashloan_logic::get_complex_flashloan_premium_to_protocol(
+                    first_flashloan_receipt
+                )
+            )
+        );
+        print(
+            &format1(
+                &b"flashloan_total_premium: {}",
+                flashloan_logic::get_complex_flashloan_total_premium(
+                    first_flashloan_receipt
+                )
+            )
+        );
+
+        // pay back the flashloans
+        flashloan_logic::pay_flash_loan_complex(borrower, flashloan_receipts);
+
+        // check the balance of the borrower after the flashloans have been paid back
+        let flashloaner_postrepay_balance =
+            fungible_asset_manager::balance_of(
+                flashloan_borrower_address, flashloan_asset
+            );
+        print(
+            &format1(
+                &b"Flashloaner post-repay balance: {}", flashloaner_postrepay_balance
+            )
+        );
+    }
+}