feat(docs): add aave tutorial by sklppy88 · Pull Request #21048 · AztecProtocol/aztec-packages

sklppy88 · 2026-03-03T12:04:16Z

title

critesjosh

Overall looking good! Some recommendations to improve the flow and some hiccups that I ran into as I tried to follow along.

also, once this PR (#20113) is merged, merge next into this branch and set up the index.ts file to run as part of the CI.

critesjosh · 2026-03-03T19:26:59Z

docs/examples/contracts/aave_bridge/src/main.nr

+
+use aztec::macros::aztec;
+
+// docs:start:bridge_setup


should this be moved to line 1, so that the mod and imports are included?

critesjosh · 2026-03-03T19:27:44Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+Add the Aztec dependencies:
+
+```bash
+yarn add @aztec/aztec.js@#include_version_without_prefix @aztec/accounts@#include_version_without_prefix @aztec/stdlib@#include_version_without_prefix @aztec/wallets@#include_version_without_prefix tsx


the TS script also imports from @aztec/ethereum, @aztec/foundation, and @aztec/viem which aren't listed

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

docs/examples/ts/aave_bridge/index.ts

critesjosh · 2026-03-03T19:33:15Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+        Token["🪙 Token"]
+    end
+
+    Token -->|"1. Burn"| Bridge


I think the numbering is messed up here. I don't think we start with burning tokens.

Oh i see, this is the flow, assuming you already have tokens on Aztec. It'd be worth clarifying that

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

critesjosh · 2026-03-03T20:50:39Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+
+The public variants are straightforward. `claim_public` consumes an L1→L2 message and mints tokens. `exit_to_l1_public` burns tokens and sends an L2→L1 message:
+
+#include_code claim_public /docs/examples/contracts/aave_bridge/src/main.nr rust


make it more clear that these functions should be inserted into the body of the contract (if the reader is following along and building the contract)

critesjosh · 2026-03-03T20:55:24Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+
+#include_code claim_public /docs/examples/contracts/aave_bridge/src/main.nr rust
+
+#include_code exit_to_l1_public /docs/examples/contracts/aave_bridge/src/main.nr rust


I see syntax errors when adding these functions. I am running through the tutorial on version v5.0.0-nightly.20260303

claude says this is the issue (and it does indeed fix it):
The token contract uses path = "../../../../aztec-nr/aztec" (within the aztec-packages monorepo), but our contract pulls aztec from a different git URL (aztec-nr repo). This creates a diamond dependency — two different copies of PrivateCall/PublicCall types that the compiler treats as distinct.

The fix is to source our aztec dependency from aztec-packages (same as the token contract resolves to), not from the separate aztec-nr repo.

wdyt about using the defi wonderland token?

I think if we integrate it it should be in a downstream pr ! there are separate considerations to make if using that token

critesjosh · 2026-03-03T21:11:13Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+### Compile
+
+```bash
+aztec compile


aztec new also sets up a test dir, so either we need to tell readers to delete it, or set some up. Claude update the test file to this

use aztec::protocol::address::{AztecAddress, EthAddress}; use aztec::protocol::traits::FromField; use aztec::test::helpers::test_environment::TestEnvironment; use aave_bridge::AaveBridge; #[test] unconstrained fn test_constructor() { let mut env = TestEnvironment::new(); let deployer = env.create_light_account(); let token = AztecAddress::from_field(1); let portal = EthAddress::from_field(2); let initializer = AaveBridge::interface().constructor(token, portal); let _contract_address = env.deploy("@aave_bridge/AaveBridge").with_public_initializer(deployer, initializer); }

critesjosh · 2026-03-03T21:13:02Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+
+:::
+
+Create the mock contracts in `contracts/`:


Make it clear what the exact names of these files should be

critesjosh

i went through it and ended up with working code with help from claude. there are comments about several of the issues that i had to work through. it worked some magic on index.ts to make type errors go away, you can see the project that I ended up with here: critesjosh/hardhat-aztec-example#2

critesjosh · 2026-03-12T00:36:19Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+    subgraph Ethereum["Ethereum (L1)"]
+        Portal["🌉 AavePortal"]
+        Aave["🏦 Aave Pool"]
+        ERC20["💰 ERC20 Token"]


This box isnt used in the diagram, maybe just remove it?

critesjosh · 2026-03-12T00:36:49Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+
+## Prerequisites
+
+- [Aztec local network running at version #include_aztec_version](../../../getting_started_on_local_network.md) (includes Aztec CLI and Node.js v18+)


Suggested change

- [Aztec local network running at version #include_aztec_version](../../../getting_started_on_local_network.md) (includes Aztec CLI and Node.js v18+)

- [Aztec local network running at version #include_aztec_version](../../../getting_started_on_local_network.md) (includes Aztec CLI and Node.js v24)

node 24?

critesjosh · 2026-03-12T00:38:14Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+    User->>Bridge: exit_to_l1_public(amount)
+    Bridge->>Outbox: message_portal(content)
+    Bridge->>Token: burn_public(user, amount)
+    Note over Outbox: Wait for block proof


Do we have a time estimate we could share on this, or a heuristic so readers can get a sense for how long it might take?

critesjosh · 2026-03-12T00:49:50Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+
+:::note
+
+This template is a community-maintained starter. If the repository is unavailable, you can set up a Hardhat project manually and add the `@aztec/*` Solidity remappings from the [cross-chain messaging docs](../../foundational-topics/ethereum-aztec-messaging/index.md).


add a note that they might just need to update the tag on @aztec/l1-contracts in this referenced repo's package.json

e.g.

"@aztec/l1-contracts": "git+https://github.com/AztecProtocol/l1-contracts.git#v5.0.0-nightly.20260311",

critesjosh · 2026-03-12T00:51:00Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+    MockAavePool.sol
+    AavePortal.sol
+  contracts/aztec/               # Noir contracts
+    aave_bridge/


there is a test folder as well

├── aave_bridge_test │ ├── Nargo.toml │ └── src │ └── lib.nr

critesjosh · 2026-03-12T01:20:52Z

docs/examples/solidity/aave_bridge/AavePortal.sol

+import {IERC20} from "@oz/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@oz/token/ERC20/utils/SafeERC20.sol";
+
+import {IRegistry} from "@aztec/governance/interfaces/IRegistry.sol";


I was also struggling with the remappings here. Claude worked around it by importing directly from the npm packages

import {IRegistry} from "@aztec/l1-contracts/src/governance/interfaces/IRegistry.sol"; import {IInbox} from "@aztec/l1-contracts/src/core/interfaces/messagebridge/IInbox.sol"; import {IOutbox} from "@aztec/l1-contracts/src/core/interfaces/messagebridge/IOutbox.sol"; import {IRollup} from "@aztec/l1-contracts/src/core/interfaces/IRollup.sol"; import {DataStructures} from "@aztec/l1-contracts/src/core/libraries/DataStructures.sol"; import {Hash} from "@aztec/l1-contracts/src/core/libraries/crypto/Hash.sol"; import {Epoch} from "@aztec/l1-contracts/src/core/libraries/TimeLib.sol";

critesjosh · 2026-03-12T01:26:14Z

docs/examples/ts/aave_bridge/index.ts

+// docs:end:fund_user
+
+// docs:start:mine_blocks
+// On the local sandbox, L2 blocks are only produced when transactions are submitted.


Suggested change

// On the local sandbox, L2 blocks are only produced when transactions are submitted.

// On the local network, L2 blocks are only produced when transactions are submitted.

critesjosh · 2026-03-12T01:28:05Z

docs/examples/ts/aave_bridge/index.ts

+import { EmbeddedWallet } from "@aztec/wallets/embedded";
+import { decodeEventLog, pad, toFunctionSelector } from "@aztec/viem";
+import { foundry } from "@aztec/viem/chains";
+import AavePortal from "../../../target/solidity/aave_bridge/AavePortal.sol/AavePortal.json" with { type: "json" };


following along, this is actually the relative path

Suggested change

import AavePortal from "../../../target/solidity/aave_bridge/AavePortal.sol/AavePortal.json" with { type: "json" };

import AavePortal from "../target/solidity/aave_bridge/AavePortal.sol/AavePortal.json" with { type: "json" };

critesjosh · 2026-03-12T01:31:27Z

docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md

+Add the Aztec dependencies:
+
+```bash
+yarn add @aztec/aztec.js@#include_version_without_prefix @aztec/accounts@#include_version_without_prefix @aztec/wallets@#include_version_without_prefix @aztec/stdlib@#include_version_without_prefix @aztec/foundation@#include_version_without_prefix @aztec/ethereum@#include_version_without_prefix @aztec/noir-contracts.js@#include_version_without_prefix @aztec/viem@#include_version_without_prefix tsx


i dont think this gets the right version. @aztec/viem@#include_version_without_prefix, @aztec/viem only has version 2.38.2

Suggested change

yarn add @aztec/aztec.js@#include_version_without_prefix @aztec/accounts@#include_version_without_prefix @aztec/wallets@#include_version_without_prefix @aztec/stdlib@#include_version_without_prefix @aztec/foundation@#include_version_without_prefix @aztec/ethereum@#include_version_without_prefix @aztec/noir-contracts.js@#include_version_without_prefix @aztec/viem@#include_version_without_prefix tsx

yarn add @aztec/aztec.js@#include_version_without_prefix @aztec/accounts@#include_version_without_prefix @aztec/wallets@#include_version_without_prefix @aztec/stdlib@#include_version_without_prefix @aztec/foundation@#include_version_without_prefix @aztec/ethereum@#include_version_without_prefix @aztec/noir-contracts.js@#include_version_without_prefix @aztec/viem@2.38.2 tsx

critesjosh · 2026-03-12T01:33:06Z

docs/examples/ts/aave_bridge/index.ts

+import MockAToken from "../../../target/solidity/aave_bridge/MockAToken.sol/MockAToken.json" with { type: "json" };
+import MockAavePool from "../../../target/solidity/aave_bridge/MockAavePool.sol/MockAavePool.json" with { type: "json" };
+import { TokenContract } from "@aztec/noir-contracts.js/Token";
+import { AaveBridgeContract } from "./artifacts/AaveBridge.js";


also had to update this path to import { AaveBridgeContract } from "../contracts/aztec/artifacts/AaveBridge.js";

sklppy88 force-pushed the ek/feat/aave-tutorial branch 2 times, most recently from 06010f3 to 28a33bd Compare March 3, 2026 12:41

sklppy88 marked this pull request as ready for review March 3, 2026 12:47

sklppy88 requested a review from a team as a code owner March 3, 2026 12:47

sklppy88 requested a review from critesjosh March 3, 2026 14:40

critesjosh requested changes Mar 3, 2026

View reviewed changes

sklppy88 added the ci-squash-and-merge label Mar 4, 2026

AztecBot force-pushed the ek/feat/aave-tutorial branch from f1a1a62 to 292a4ab Compare March 4, 2026 23:29

AztecBot removed the ci-squash-and-merge label Mar 4, 2026

AztecBot enabled auto-merge March 4, 2026 23:29

sklppy88 disabled auto-merge March 4, 2026 23:37

sklppy88 force-pushed the ek/feat/aave-tutorial branch 3 times, most recently from 6bed2cb to 3e75121 Compare March 6, 2026 14:09

sklppy88 added the ci-squash-and-merge label Mar 6, 2026

sklppy88 force-pushed the ek/feat/aave-tutorial branch 3 times, most recently from 67b9da7 to 6be716f Compare March 10, 2026 17:58

AztecBot force-pushed the ek/feat/aave-tutorial branch from 5704f6b to 70bee50 Compare March 10, 2026 18:35

AztecBot removed the ci-squash-and-merge label Mar 10, 2026

AztecBot enabled auto-merge March 10, 2026 18:35

feat(docs): add aave tutorial

18c1708

sklppy88 force-pushed the ek/feat/aave-tutorial branch from 70bee50 to 18c1708 Compare March 10, 2026 18:41

sklppy88 requested a review from critesjosh March 10, 2026 18:42

critesjosh requested changes Mar 12, 2026

View reviewed changes

sklppy88 disabled auto-merge March 12, 2026 19:15

critesjosh approved these changes Mar 12, 2026

View reviewed changes


		The public variants are straightforward. `claim_public` consumes an L1→L2 message and mints tokens. `exit_to_l1_public` burns tokens and sends an L2→L1 message:

		#include_code claim_public /docs/examples/contracts/aave_bridge/src/main.nr rust


		#include_code claim_public /docs/examples/contracts/aave_bridge/src/main.nr rust

		#include_code exit_to_l1_public /docs/examples/contracts/aave_bridge/src/main.nr rust


		## Prerequisites

		- [Aztec local network running at version #include_aztec_version](../../../getting_started_on_local_network.md) (includes Aztec CLI and Node.js v18+)


		:::note

		This template is a community-maintained starter. If the repository is unavailable, you can set up a Hardhat project manually and add the `@aztec/*` Solidity remappings from the [cross-chain messaging docs](../../foundational-topics/ethereum-aztec-messaging/index.md).

	// On the local sandbox, L2 blocks are only produced when transactions are submitted.
	// On the local network, L2 blocks are only produced when transactions are submitted.

	import AavePortal from "../../../target/solidity/aave_bridge/AavePortal.sol/AavePortal.json" with { type: "json" };
	import AavePortal from "../target/solidity/aave_bridge/AavePortal.sol/AavePortal.json" with { type: "json" };

Conversation

sklppy88 commented Mar 3, 2026

Uh oh!

critesjosh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

critesjosh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants