reordering

critesjosh · critesjosh · commit c2a4d3168e58 · 2025-08-22T12:03:45.000-04:00
diff --git a/docs/docs-words.txt b/docs/docs-words.txt
@@ -325,6 +325,7 @@ undeflow
 Undercollateralized
 underconstrained
 unleaked
+unlinkability
 unncessary
 unreverted
 unrleated
diff --git a/docs/docs/aztec/concepts/pxe/index.md b/docs/docs/aztec/concepts/pxe/index.md
@@ -106,4 +106,4 @@ Oracles are pieces of data that are injected into a smart contract function from
 To learn how to develop on top of the PXE, refer to these guides:
 
 - [Run more than one PXE on your local machine](../../../developers/guides/local_env/sandbox.md#running-multiple-pxes-in-the-sandbox)
-- [Use in-built oracles including oracles for arbitrary data](../../../developers/guides/smart_contracts/how_to_use_capsules.md)
+- [Use in-built oracles including oracles for arbitrary data](../../../developers/guides/smart_contracts/advanced/how_to_use_capsules.md)
diff --git a/docs/docs/aztec/smart_contracts/oracles/index.md b/docs/docs/aztec/smart_contracts/oracles/index.md
@@ -7,7 +7,7 @@ description: Learn about oracles in Aztec, which provide external data to smart
 
 This page goes over what oracles are in Aztec and how they work.
 
-Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../developers/guides/smart_contracts/how_to_use_capsules.md).
+Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../developers/guides/smart_contracts/advanced/how_to_use_capsules.md).
 
 An oracle is something that allows us to get data from the outside world into our contracts. The most widely-known types of oracles in blockchain systems are probably Chainlink price feeds, which allow us to get the price of an asset in USD taking non-blockchain data into account.
 
@@ -33,4 +33,4 @@ Oracles introduce **non-determinism** into a circuit, and thus are `unconstraine
 
 Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr/aztec/src/oracle).
 
-Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [capsules](../../../developers/guides/smart_contracts/how_to_use_capsules.md).
+Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [capsules](../../../developers/guides/smart_contracts/advanced/how_to_use_capsules.md).
diff --git a/docs/docs/developers/guides/local_env/sandbox.md b/docs/docs/developers/guides/local_env/sandbox.md
@@ -205,7 +205,7 @@ Note that you do not need to restart the sandbox in order to start sending prove
 If this is the first time you are sending transactions with proving enabled, it will take a while to download a CRS file (which is several MBs) that is required for proving.
 
 :::note
-You can also profile your transactions to get gate count, if you don't want to prove your transactions but check how many constraints it is. Follow the [guide here](../../guides/smart_contracts/profiling_transactions.md)
+You can also profile your transactions to get gate count, if you don't want to prove your transactions but check how many constraints it is. Follow the [guide here](../../guides/smart_contracts/advanced/profiling_transactions.md)
 :::
 
 ## Running Multiple PXEs in the Sandbox
diff --git a/docs/docs/developers/guides/smart_contracts/advanced/_category_.json b/docs/docs/developers/guides/smart_contracts/advanced/_category_.json
@@ -0,0 +1,6 @@
+{
+  "position": 11,
+  "collapsible": true,
+  "collapsed": true,
+  "label": "Advanced Topics"
+}
diff --git a/docs/docs/developers/guides/smart_contracts/advanced/common_patterns.md b/docs/docs/developers/guides/smart_contracts/advanced/common_patterns.md
@@ -39,7 +39,7 @@ Note - you could also create a note and send it to the user. The problem is ther
 
 ### Reading public storage in private
 
-You can read public storage in private domain by leveraging the private getters of `PublicImmutable` (for values that never change) and `DelayedPublicMutable` (for values that change infrequently, see [delayed public mutable state](./storage_types.md#delayed-public-mutable) for details) state variables.
+You can read public storage in private domain by leveraging the private getters of `PublicImmutable` (for values that never change) and `DelayedPublicMutable` (for values that change infrequently, see [delayed public mutable state](../storage_types.md#delayed-public-mutable) for details) state variables.
 Values that change frequently (`PublicMutable`) cannot be read in private as for those we need access to the tip of the chain and only a sequencer has access to that (and sequencer executes only public functions).
 
 E.g. when using `PublicImmutable`
@@ -75,13 +75,13 @@ In this situation, try to mark the public function as `internal`. This ensures y
 
 ### Moving public data into the private domain
 
-See [partial notes](../../../aztec/concepts/advanced/storage/partial_notes.md). Partial notes are how public balances are transferred to private [in the NFT contract](../../tutorials/codealong/contract_tutorials/nft_contract.md).
+See [partial notes](../../../../aztec/concepts/advanced/storage/partial_notes.md). Partial notes are how public balances are transferred to private [in the NFT contract](../../../tutorials/codealong/contract_tutorials/nft_contract.md).
 
 ### Discovering my notes
 
 When you send someone a note, the note hash gets added to the note hash tree. To spend the note, the receiver needs to get the note itself (the note hash preimage). There are two ways you can get a hold of your notes:
 
-1. When sending someone a note, emit the note log to the recipient (the function encrypts the log in such a way that only a recipient can decrypt it). PXE then tries to decrypt all the encrypted logs, and stores the successfully decrypted one. [More info here](./how_to_emit_event.md)
+1. When sending someone a note, emit the note log to the recipient (the function encrypts the log in such a way that only a recipient can decrypt it). PXE then tries to decrypt all the encrypted logs, and stores the successfully decrypted one. [More info here](../how_to_emit_event.md)
 2. Manually delivering it via a custom contract method, if you choose to not emit logs to save gas or when creating a note in the public domain and want to consume it in private domain (`encrypt_and_emit_note` shouldn't be called in the public domain because everything is public), like in the previous section where we created a note in public that doesn't have a designated owner.
 
 #include_code offchain_delivery yarn-project/end-to-end/src/composed/e2e_persistence.test.ts typescript
@@ -110,7 +110,7 @@ Hence, it's necessary to add a "randomness" field to your note to prevent such a
 
 ### L1 -- L2 interactions
 
-Refer to [Token Portal codealong tutorial on bridging tokens between L1 and L2](../../tutorials/codealong/js_tutorials/token_bridge.md) and/or [Uniswap smart contract example that shows how to swap on L1 using funds on L2](../../tutorials/codealong/js_tutorials/uniswap/index.md). Both examples show how to:
+Refer to [Token Portal codealong tutorial on bridging tokens between L1 and L2](../../../tutorials/codealong/js_tutorials/token_bridge.md) and/or [Uniswap smart contract example that shows how to swap on L1 using funds on L2](../../../tutorials/codealong/js_tutorials/uniswap/index.md). Both examples show how to:
 
 1. L1 -> L2 message flow
 2. L2 -> L1 message flow
@@ -124,7 +124,7 @@ To send a note to someone, they need to have a key which we can encrypt the note
 There are several patterns here:
 
 1. Give the contract a key and share it amongst all participants. This leaks privacy, as anyone can see all the notes in the contract.
-2. `transfer_to_public` funds into the contract - this is used in the [Uniswap smart contract example where a user sends private funds into a Uniswap Portal contract which eventually withdraws to L1 to swap on L1 Uniswap](../../tutorials/codealong/js_tutorials/uniswap/index.md). This works like Ethereum - to achieve contract composability, you move funds into the public domain. This way the contract doesn't even need keys.
+2. `transfer_to_public` funds into the contract - this is used in the [Uniswap smart contract example where a user sends private funds into a Uniswap Portal contract which eventually withdraws to L1 to swap on L1 Uniswap](../../../tutorials/codealong/js_tutorials/uniswap/index.md). This works like Ethereum - to achieve contract composability, you move funds into the public domain. This way the contract doesn't even need keys.
 
 There are several other designs we are discussing through [in this discourse post](https://discourse.aztec.network/t/how-to-handle-private-escrows-between-two-parties/2440) but they need some changes in the protocol or in our demo contract. If you are interested in this discussion, please participate in the discourse post!
 
@@ -146,7 +146,7 @@ PS: when calling from private to public, `msg_sender` is the contract address wh
 
 In the [Prevent the same user flow from happening twice using nullifier](#prevent-the-same-user-flow-from-happening-twice-using-nullifiers), we recommended using nullifiers. But what you put in the nullifier is also as important.
 
-E.g. for a voting contract, if your nullifier simply emits just the `user_address`, then privacy can easily be leaked via a preimage attack as nullifiers are deterministic (have no randomness), especially if there are few users of the contract. So you need some kind of randomness. You can add the user's secret key into the nullifier to add randomness. We call this "nullifier secrets" as explained [here](../../../aztec/concepts/accounts/keys.md#nullifier-keys).
+E.g. for a voting contract, if your nullifier simply emits just the `user_address`, then privacy can easily be leaked via a preimage attack as nullifiers are deterministic (have no randomness), especially if there are few users of the contract. So you need some kind of randomness. You can add the user's secret key into the nullifier to add randomness. We call this "nullifier secrets" as explained [here](../../../../aztec/concepts/accounts/keys.md#nullifier-keys).
 
 Here is an example from the voting contract:
 
diff --git a/docs/docs/developers/guides/smart_contracts/advanced/get_notes.md b/docs/docs/developers/guides/smart_contracts/advanced/get_notes.md
@@ -1,6 +1,5 @@
 ---
 title: Get Notes
-sidebar_position: 4
 tags: [private-state, smart-contracts, notes]
 description: Learn how to get notes from a data oracle in Aztec.nr.
 ---
diff --git a/docs/docs/developers/guides/smart_contracts/advanced/how_to_use_capsules.md b/docs/docs/developers/guides/smart_contracts/advanced/how_to_use_capsules.md
diff --git a/docs/docs/developers/guides/smart_contracts/advanced/profiling_transactions.md b/docs/docs/developers/guides/smart_contracts/advanced/profiling_transactions.md
@@ -9,13 +9,13 @@ An Aztec transaction typically consists of a private and a public part. The priv
 
 Since proof generation is an expensive operation that needs to be done on the client side, it is important to optimize the private contract logic. It is desirable to keep the gate count of circuits representing the private contract logic as low as possible.
 
-A private transaction can involve multiple function calls. It starts with an account `entrypoint()` which may call several private functions to execute the application logic, which in turn might call other functions. Moreover, every private function call has to go through a round of kernel circuits. Read more about the transaction lifecycle [here](../../../aztec/concepts/transactions.md).
+A private transaction can involve multiple function calls. It starts with an account `entrypoint()` which may call several private functions to execute the application logic, which in turn might call other functions. Moreover, every private function call has to go through a round of kernel circuits. Read more about the transaction lifecycle [here](../../../../aztec/concepts/transactions.md).
 
 In this guide, we will look at how to profile the private execution of a transaction, allowing you to get the gate count of each private function within the transaction, including the kernel circuits.
 
 ## Prerequisites
 
-- `aztec-nargo` installed (go to [Sandbox section](../../reference/environment_reference/sandbox-reference.md) for installation instructions)
+- `aztec-nargo` installed (go to [Sandbox section](../../../reference/environment_reference/sandbox-reference.md) for installation instructions)
 - `aztec-wallet` installed (installed as part of the Sandbox)
 
 ## Profiling using aztec-wallet
diff --git a/docs/docs/developers/guides/smart_contracts/authwit.md b/docs/docs/developers/guides/smart_contracts/authwit.md
@@ -5,17 +5,15 @@ tags: [accounts, authwit]
 sidebar_position: 7
 ---
 
-This page introduces the authwit library and how you can use it in your Aztec.nr smart contracts. [Skip to the usage](#usage).
+This page introduces the authwit library and how you can use it in your Aztec.nr smart contracts.
 
-For a guide on using authwit in Aztec.js, [read this](../js_apps/authwit.md).
+For a conceptual overview of authwits, see [Authentication Witnesses](../../../aztec/concepts/advanced/authwit.md).
 
-## Prerequisite reading
-
-- [Authwit](../../../aztec/concepts/advanced/authwit.md)
+Read more about how to use authwits in Aztec.js [here](../js_apps/authwit.md).
 
 ## Introduction
 
-Authentication Witness (authwit) is a scheme for authentication actions on Aztec, so users can allow third-parties (eg other contracts) to execute an action on their behalf. Authwits can only authorize actions for contracts that your account is calling, they cannot be used to permit other users to take actions on your behalf.
+Authentication Witness (authwit) is a scheme for authentication actions on Aztec, so users can allow third-parties (e.g. other contracts) to execute an action on their behalf. Authwits can only authorize actions for contracts that your account is calling, they cannot be used to permit other users to take actions on your behalf.
 
 How it works logically is explained in the [concepts](../../../aztec/concepts/advanced/authwit.md) but we will do a short recap here.
 
diff --git a/docs/docs/developers/guides/smart_contracts/cross_chain_communication.md b/docs/docs/developers/guides/smart_contracts/cross_chain_communication.md
@@ -1,10 +1,62 @@
 ---
-title: Communicating with L1
+title: Cross-Chain Communication
 tags: [contracts, portals]
+sidebar_position: 7
 description: Learn how to communicate with L1 contracts through portals in your Aztec smart contracts.
 ---
 
-Follow the [token bridge tutorial](../../../tutorials/codealong/js_tutorials/token_bridge.md) for hands-on experience writing and deploying a Portal contract.
+- **What portals are**: An L1-side component (contract or EOA) associated with a specific L2 address. Portals bridge messaging between L1 and Aztec L2, enabling public L1 functions and private/public L2 functions to communicate.
+
+- **Why portals exist**: Direct, synchronous L1↔L2 calls would leak private inputs and conflict with Aztec’s execution model (users pre-prove private calls; public state executes at chain head). Portals enable asynchronous, unilateral message passing that preserves privacy.
+
+- **Objectives**
+  - **L2→L1**: L2 functions can call L1.
+  - **L1→L2**: L1 functions can call L2.
+  - **Efficiency**: Limit rollup-block size impact from messages.
+
+### Components and actors
+
+- **Portal (L1)**: The L1 part of an app linked to an L2 address; origin/target for cross-domain messages.
+- **Message Boxes**: One-way queues with pending and ready sets moving messages across domains via the rollup. Messages are “pulled” by recipients (not “pushed” as calldata) to avoid revealing private inputs.
+- **Rollup Contract (L1)**:
+  - Maintains L2 rollup state root, verifies proofs, ensures data availability.
+  - Moves messages pending→ready and publishes L2→L1 messages on-chain.
+- **Kernel Circuit (L2)**:
+  - For L2→L1: enforces messages have valid sender/recipient pairs present in the contracts tree and that sender is the emitting L2 contract.
+  - For L1→L2: creates nullifiers when consuming messages.
+- **Rollup Circuit (L2)**:
+  - Enforces state transition T(S, B) → S′.
+  - Inserts/nullifies L1→L2 messages in trees; publishes L2→L1 messages.
+  - Validates sender/recipient pairs exist in the contracts tree.
+
+### Message model and privacy
+
+- **Payload size**: Up to 32 bytes. If larger, send `sha256(content)` (fits ~254-bit field). The sender can reveal or log the full content on L2 as needed.
+- **Actors**:
+  - `L1Actor { address, chainId }`
+  - `L2Actor { actor (bytes32), version }`
+  - `L1ToL2Msg { sender(L1), recipient(L2), content(bytes32), secretHash(bytes32) }`
+  - `L2ToL1Msg { sender(L2), recipient(L1), content(bytes32) }`
+- **Commitment**: Only `sha256(LxToLyMsg)` is stored on-chain/in trees (single storage slot update).
+- **Duplicates & unlinkability**:
+  - Nullifier includes the message’s index to allow duplicates (e.g., repeated deposits).
+  - `secretHash` in `L1ToL2Msg` hides when a specific message is consumed; the `secretPreimage` participates in nullifier computation.
+
+### Ordering and flow
+
+- **Private→Public execution on L2**: Private functions first; public later at chain head.
+- **Unilateral, async**: Callers don’t know outcomes within the same rollup.
+- **Inclusion timing**:
+  - L1→L2 messages emitted on L1 can be ready at the start of a rollup and consumed in that same block.
+  - L2→L1 messages are added as they’re emitted; a response from L1 could appear by rollup n+1.
+- **Asymmetry**: The L2→L1 “pending” set is logical only; changes to L2 state are reflected directly on L1.
+
+### Developer implications
+
+- **Failure handling**: Apps must handle asynchronous failures and recovery paths (critical for bridges where funds may lock on one side).
+- **Contracts tree constraint**: Only messages whose sender/recipient pair exists in the contracts tree are valid and movable/consumable.
+
+For a deeper conceptual overview of cross-chain communication, see [Cross-Chain Communication](../../../aztec/concepts/communication/cross_chain_calls.md).
 
 ## Passing data to the rollup
 
@@ -42,10 +94,14 @@ Note that while the `secret` and the `content` are both hashed, they are actuall
 
 ### Token bridge example
 
+<<<<<<< HEAD:docs/docs/developers/guides/smart_contracts/portals/communicate_with_portal.md
 <<<<<<< HEAD:docs/docs/developers/guides/smart_contracts/writing_contracts/portals/communicate_with_portal.md
 Computing the `content` must currently be done manually, as we are still adding a number of bytes utilities. A good example exists within the [Token bridge example (codealong tutorial)](../../../../../developers/tutorials/js_tutorials/token_bridge.md).
 =======
 Computing the `content` must currently be done manually, as we are still adding a number of bytes utilities. A good example exists within the [Token bridge example (codealong tutorial)](../../../tutorials/codealong/js_tutorials/token_bridge.md).
+=======
+Computing the `content` must currently be done manually, as we are still adding a number of bytes utilities. A good example exists within the [Token bridge example (codealong tutorial)](../../tutorials/codealong/js_tutorials/token_bridge.md).
+>>>>>>> 684308a759 (reordering):docs/docs/developers/guides/smart_contracts/cross_chain_communication.md
 
 #include_code claim_public /noir-projects/noir-contracts/contracts/app/token_bridge_contract/src/main.nr rust
 
@@ -187,3 +243,7 @@ Designated callers are enforced at the contract level for contracts that are not
 - Token bridge (Portal contract built for L1 to L2, i.e., a non-native L2 asset)
   - [Portal contract (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/l1-contracts/test/portals/TokenPortal.sol)
   - [Aztec contract (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-contracts/contracts/app/token_bridge_contract/src/main.nr)
+
+## Further reading
+
+Follow the [token bridge tutorial](../../tutorials/codealong/js_tutorials/token_bridge.md) for hands-on experience writing and deploying a Portal contract.
diff --git a/docs/docs/developers/guides/smart_contracts/how_to_compile_contract.md b/docs/docs/developers/guides/smart_contracts/how_to_compile_contract.md
@@ -1,6 +1,7 @@
 ---
 title: Compile Contracts
 tags: [contracts]
+sidebar_position: 9
 description: Learn how to compile your Noir smart contracts for deployment on Aztec.
 ---
 
diff --git a/docs/docs/developers/guides/smart_contracts/how_to_emit_event.md b/docs/docs/developers/guides/smart_contracts/how_to_emit_event.md
@@ -1,6 +1,7 @@
 ---
 title: Emitting Events
-tags: [contracts]
+tags: [contracts, events]
+sidebar_position: 6
 description: Learn how to emit events from your Aztec smart contracts for off-chain applications to consume.
 ---
 
diff --git a/docs/docs/developers/guides/smart_contracts/how_to_prove_history.md b/docs/docs/developers/guides/smart_contracts/how_to_prove_history.md
@@ -1,6 +1,6 @@
 ---
 title: Prove Historic State
-sidebar_position: 7
+sidebar_position: 8
 tags: [contracts]
 description: Learn how to prove historical state transitions in your Aztec smart contracts.
 ---
diff --git a/docs/docs/developers/guides/smart_contracts/portals/index.md b/docs/docs/developers/guides/smart_contracts/portals/index.md
diff --git a/docs/docs/developers/guides/smart_contracts/storage.md b/docs/docs/developers/guides/smart_contracts/storage.md
diff --git a/docs/docs/developers/guides/smart_contracts/testing.md b/docs/docs/developers/guides/smart_contracts/testing.md
diff --git a/docs/docs/developers/tutorials/contract_tutorials/counter_contract.md b/docs/docs/developers/tutorials/contract_tutorials/counter_contract.md
