chore(docs): refactoring cross-chain tutorial (#17799)

# Bridge Your NFT to Aztec: A Private NFT Bridge Tutorial

This PR completely revamps the token bridge tutorial to focus on NFTs
with privacy at the core. The new tutorial guides developers through
building a complete private NFT bridge between Ethereum and Aztec.

## Key improvements:

- Creates a more engaging narrative around bridging CryptoPunks with
private ownership
- Builds a complete end-to-end solution with 4 contracts (2 on L1, 2 on
L2)
- Introduces privacy concepts like `PrivateSet` and custom notes for
encrypted ownership
- Provides detailed explanations of cross-chain messaging between L1 and
L2
- Includes complete code examples with step-by-step instructions

The tutorial now follows a more logical flow:
1. Building the L2 NFT contract with private ownership
2. Creating the L2 bridge contract for claiming messages
3. Implementing the L1 contracts (NFT and portal)
4. Deploying and testing the full bridging flow

This approach gives developers a deeper understanding of Aztec's privacy
features while building something practical and useful.

Author: signorecello

docs/docs/developers/docs/tutorials/js_tutorials/token_bridge.md

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.27;
+
+// docs:start:portal_setup
+import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
+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";
+
+contract NFTPortal {
+    IRegistry public registry;
+    IERC721 public nftContract;
+    bytes32 public l2Bridge;
+
+    IRollup public rollup;
+    IOutbox public outbox;
+    IInbox public inbox;
+    uint256 public rollupVersion;
+
+    function initialize(address _registry, address _nftContract, bytes32 _l2Bridge) external {
+        registry = IRegistry(_registry);
+        nftContract = IERC721(_nftContract);
+        l2Bridge = _l2Bridge;
+
+        rollup = IRollup(address(registry.getCanonicalRollup()));
+        outbox = rollup.getOutbox();
+        inbox = rollup.getInbox();
+        rollupVersion = rollup.getVersion();
+    }
+    // docs:end:portal_setup
+
+    // docs:start:portal_deposit_and_withdraw
+    // Lock NFT and send message to L2
+    function depositToAztec(uint256 tokenId, bytes32 secretHash) external returns (bytes32, uint256) {
+        // Lock the NFT
+        nftContract.transferFrom(msg.sender, address(this), tokenId);
+
+        // Prepare L2 message - just a naive hash of our tokenId
+        DataStructures.L2Actor memory actor = DataStructures.L2Actor(l2Bridge, rollupVersion);
+        bytes32 contentHash = Hash.sha256ToField(abi.encode(tokenId));
+
+        // Send message to Aztec
+        (bytes32 key, uint256 index) = inbox.sendL2Message(actor, contentHash, secretHash);
+        return (key, index);
+    }
+
+    // Unlock NFT after L2 burn
+    function withdraw(
+        uint256 tokenId,
+        uint256 l2BlockNumber,
+        uint256 leafIndex,
+        bytes32[] calldata path
+    ) external {
+        // Verify message from L2
+        DataStructures.L2ToL1Msg memory message = DataStructures.L2ToL1Msg({
+            sender: DataStructures.L2Actor(l2Bridge, rollupVersion),
+            recipient: DataStructures.L1Actor(address(this), block.chainid),
+            content: Hash.sha256ToField(abi.encodePacked(tokenId, msg.sender))
+        });
+
+        outbox.consume(message, l2BlockNumber, leafIndex, path);
+
+        // Unlock NFT
+        nftContract.transferFrom(address(this), msg.sender, tokenId);
+    }
+}
+// docs:end:portal_deposit_and_withdraw

docs/examples/tutorials/token_bridge_contract/contracts/NFTPortal.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: Apache-2.0
+// docs:start:simple_nft
+pragma solidity >=0.8.27;
+
+import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
+
+contract SimpleNFT is ERC721 {
+    uint256 private _currentTokenId;
+
+    constructor() ERC721("SimplePunk", "SPUNK") {}
+
+    function mint(address to) external returns (uint256) {
+        uint256 tokenId = _currentTokenId++;
+        _mint(to, tokenId);
+        return tokenId;
+    }
+}
+// docs:end:simple_nft

docs/examples/tutorials/token_bridge_contract/contracts/SimpleNFT.sol

@@ -0,0 +1,6 @@
+[package]
+name = "nft"
+type = "contract"
+
+[dependencies]
+aztec = { path = "../../../../noir-projects/aztec-nr/aztec" }

docs/examples/tutorials/token_bridge_contract/contracts/aztec/nft/Nargo.toml

@@ -0,0 +1,82 @@
+// docs:start:contract_setup
+use aztec::macros::aztec;
+pub mod nft;
+
+#[aztec]
+pub contract NFTPunk {
+    use dep::aztec::{
+        macros::{storage::storage, functions::{utility, private, public, initializer, internal}},
+        protocol_types::{address::AztecAddress},
+        state_vars::{PrivateSet, PublicImmutable, delayed_public_mutable::DelayedPublicMutable, Map}
+    };
+    use crate::nft::NFTNote;
+    use dep::aztec::messages::message_delivery::MessageDelivery;
+    use aztec::note::{note_getter_options::NoteGetterOptions, note_interface::NoteProperties, note_viewer_options::NoteViewerOptions};
+    use aztec::utils::comparison::Comparator;
+
+    #[storage]
+    struct Storage<Context> {
+        admin: PublicImmutable<AztecAddress, Context>,
+        minter: PublicImmutable<AztecAddress, Context>,
+        nfts: Map<Field, DelayedPublicMutable<bool, 2, Context>, Context>,
+        owners: Map<AztecAddress, PrivateSet<NFTNote, Context>, Context>,
+    }
+    #[public]
+    #[initializer]
+    fn constructor(admin: AztecAddress) {
+        storage.admin.initialize(admin);
+    }
+    // docs:end:contract_setup
+
+    // docs:start:set_minter
+    #[public]
+    fn set_minter(minter: AztecAddress) {
+        assert(storage.admin.read().eq(context.msg_sender().unwrap()), "caller is not admin");
+        storage.minter.initialize(minter);
+    }
+    // docs:end:set_minter
+
+    // docs:start:mark_nft_exists
+    #[public]
+    #[internal]
+    fn _mark_nft_exists(token_id: Field, exists: bool) {
+        storage.nfts.at(token_id).schedule_value_change(exists);
+    }
+    // docs:end:mark_nft_exists
+
+    // docs:start:mint
+    #[private]
+    fn mint(to: AztecAddress, token_id: Field) {
+        assert(storage.minter.read().eq(context.msg_sender().unwrap()), "caller is not the authorized minter");
+
+        // we create an NFT note and insert it to the PrivateSet - a collection of notes meant to be read in private
+        let new_nft = NFTNote::new(to, token_id);
+        storage.owners.at(to).insert(new_nft).emit(&mut context, to, MessageDelivery.CONSTRAINED_ONCHAIN);
+
+        // calling the internal public function above to indicate that the NFT is taken
+        NFTPunk::at(context.this_address())._mark_nft_exists(token_id, true).enqueue(&mut context);
+    }
+    // docs:end:mint
+
+    // docs:start:notes_of
+    #[utility]
+    unconstrained fn notes_of(from: AztecAddress) -> Field {
+        let notes = storage.owners.at(from).view_notes(NoteViewerOptions::new());
+        notes.len() as Field
+    }
+    // docs:end:notes_of
+
+    // docs:start:burn
+    #[private]
+    fn burn(from: AztecAddress, token_id: Field) {
+        assert(storage.minter.read().eq(context.msg_sender().unwrap()), "caller is not the authorized minter");
+
+        // from the NFTNote properties, selects token_id and compares it against the token_id to be burned
+        let options = NoteGetterOptions::new().select(NFTNote::properties().token_id, Comparator.EQ, token_id).set_limit(1);
+        let notes = storage.owners.at(from).pop_notes(options);
+        assert(notes.len() == 1, "NFT not found");
+
+        NFTPunk::at(context.this_address())._mark_nft_exists(token_id, false).enqueue(&mut context);
+    }
+    // docs:end:burn
+}

docs/examples/tutorials/token_bridge_contract/contracts/aztec/nft/src/main.nr

@@ -0,0 +1,27 @@
+// docs:start:nft_note_struct
+use dep::aztec::{
+    macros::notes::note,
+    protocol_types::{
+        address::AztecAddress,
+        traits::Packable,
+    },
+    oracle::random::random,
+};
+
+#[derive(Eq, Packable)]
+#[note]
+pub struct NFTNote {
+    owner: AztecAddress,
+    randomness: Field,
+    token_id: Field,
+}
+// docs:end:nft_note_struct
+
+// docs:start:nft_note_new
+impl NFTNote {
+    pub fn new(owner: AztecAddress, token_id: Field) -> Self {
+        // The randomness preserves privacy by preventing brute-forcing
+        NFTNote { owner, randomness: unsafe { random() }, token_id }
+    }
+}
+// docs:end:nft_note_new

docs/examples/tutorials/token_bridge_contract/contracts/aztec/nft/src/nft.nr

@@ -0,0 +1,7 @@
+[package]
+name = "nft_bridge"
+type = "contract"
+
+[dependencies]
+aztec = { path = "../../../../noir-projects/aztec-nr/aztec" }
+NFTPunk = { path = "../nft" }

docs/examples/tutorials/token_bridge_contract/contracts/aztec/nft_bridge/Nargo.toml

@@ -0,0 +1,69 @@
+// docs:start:bridge_setup
+use aztec::macros::aztec;
+
+#[aztec]
+pub contract NFTBridge {
+    use dep::aztec::{
+        macros::{storage::storage, functions::{public, initializer, private}},
+        protocol_types::{address::AztecAddress, address::EthAddress, hash::sha256_to_field},
+        state_vars::{PublicImmutable},
+    };
+    use dep::NFTPunk::NFTPunk;
+    
+    #[storage]
+    struct Storage<Context> {
+        nft: PublicImmutable<AztecAddress, Context>,
+        portal: PublicImmutable<EthAddress, Context>,
+    }
+    
+    #[public]
+    #[initializer]
+    fn constructor(nft: AztecAddress) {
+        storage.nft.initialize(nft);
+    }
+    
+    #[public]
+    fn set_portal(portal: EthAddress) {
+        storage.portal.initialize(portal);
+    }
+    // docs:end:bridge_setup
+
+    // docs:start:claim
+    #[private]
+    fn claim(to: AztecAddress, token_id: Field, secret: Field, message_leaf_index: Field) {
+        // Compute the message hash that was sent from L1
+        let token_id_bytes: [u8; 32] = (token_id as Field).to_be_bytes();
+        let content_hash = sha256_to_field(token_id_bytes);
+
+        // Consume the L1 -> L2 message
+        context.consume_l1_to_l2_message(
+            content_hash,
+            secret,
+            storage.portal.read(),
+            message_leaf_index
+        );
+
+        // Mint the NFT on L2
+        let nft = storage.nft.read();
+        NFTPunk::at(nft).mint(to, token_id).call(&mut context);
+    }
+    // docs:end:claim
+
+    // docs:start:exit
+    #[private]
+    fn exit(
+        token_id: Field,
+        recipient: EthAddress
+    ) {
+        // Create L2->L1 message to unlock NFT on L1
+        let token_id_bytes: [u8; 32] = token_id.to_be_bytes();
+        let recipient_bytes: [u8; 20] = recipient.to_be_bytes();
+        let content = sha256_to_field(token_id_bytes.concat(recipient_bytes));
+        context.message_portal(storage.portal.read(), content);
+
+        // Burn the NFT on L2
+        let nft = storage.nft.read();
+        NFTPunk::at(nft).burn(context.msg_sender().unwrap(), token_id).call(&mut context);
+    }
+    // docs:end:exit
+}