feat: merge-train/fairies-v5 (#24580)

BEGIN_COMMIT_OVERRIDE
fix: preload txe with protocol contracts (#24574)
test(e2e): onchain message delivery harness (#24373)
feat(pxe): recipient-side interactive handshake registration (#24514)
feat(aztec-nr): sender-side support for interactive handshakes (#24522)
test(txe): struct support in oracle serialization roundtrip tests
(#24588)
refactor(aztec-nr): drop unused HandshakeNote fields (#24595)
END_COMMIT_OVERRIDE

Author: AztecBot

docs/docs-developers/docs/aztec-nr/framework-description/note_delivery.md

@@ -167,17 +167,19 @@ Onchain delivery tags every message so the recipient can find it efficiently (se
 2. Otherwise, when an onchain handshake has been registered for the pair, the secret derived from it is reused directly.
 3. Otherwise, the wallet decides how to proceed, since it knows which secrets it holds and how it wants to reach the recipient.
 
-The wallet's answer is a **tagging secret strategy**: it expresses *which* secret to use, and if necessary, PXE performs a [Diffie-Hellman key exchange](https://www.geeksforgeeks.org/computer-networks/diffie-hellman-key-exchange-and-perfect-forward-secrecy/) and/or app-siloing before handing the ready-to-use secret to the contract. Wallets therefore never reimplement that derivation. There are three strategies today:
+The wallet's answer is a **tagging secret strategy**: it expresses *which* secret to use, and if necessary, PXE performs a [Diffie-Hellman key exchange](https://www.geeksforgeeks.org/computer-networks/diffie-hellman-key-exchange-and-perfect-forward-secrecy/) and/or app-siloing before handing the ready-to-use secret to the contract. Wallets therefore never reimplement that derivation. There are four strategies today:
 
 - **Non-interactive handshake**: the secret comes from a handshake published onchain that the recipient can derive. A non-recipient can at most learn that a sender did a handshake with the recipient, not the message itself, but the recipient discovers it without any prior coordination. Works for both constrained and unconstrained delivery.
+- **Interactive handshake**: the secret comes from a handshake the recipient authorizes with a signature, which the registry requests through the custom request oracle and verifies in-circuit. Nothing announcing the handshake is published onchain (the recipient learns the secret while signing), but the recipient must be reachable to answer the request, or the send fails. Works for both constrained and unconstrained delivery.
 - **Address-derived secret**: the PXE derives the secret from the sender's and recipient's address keys via Diffie-Hellman. The wallet supplies no material, only the choice. It leaves no onchain trace, but the recipient only finds the message if they registered the sender in their PXE. Unconstrained delivery only.
 - **Arbitrary secret**: a raw secret point the two parties already share offchain, having coordinated out of band to agree on it. The wallet supplies the point and the PXE app-silos it. It leaves no onchain trace, but no onchain handshake backs the secret. Unconstrained delivery only.
 
-| | Non-interactive handshake | Address-derived secret | Arbitrary secret |
-|---|---|---|---|
-| Onchain footprint when establishing | A handshake revealing information about the recipient | None | None |
-| Who provides the material | The onchain registry | Nobody (PXE computes it) | The wallet (a raw point) |
-| Constrained delivery | Supported | Not sound: not backed by an onchain handshake | Not sound: not backed by an onchain handshake |
+| | Non-interactive handshake | Interactive handshake | Address-derived secret | Arbitrary secret |
+|---|---|---|---|---|
+| Onchain footprint when establishing | A handshake revealing information about the recipient | None | None | None |
+| Who provides the material | The onchain registry | The onchain registry, with the recipient's signed authorization | Nobody (PXE computes it) | The wallet (a raw point) |
+| Recipient coordination | None | The recipient must answer the signature request | The recipient must have registered the sender | Agreed out of band |
+| Constrained delivery | Supported | Supported | Not sound: not backed by an onchain handshake | Not sound: not backed by an onchain handshake |
 
 ### Defaults
 
@@ -186,6 +188,8 @@ When no `resolveTaggingSecretStrategy` hook is configured, the PXE applies a def
 - **Unconstrained delivery**: a non-interactive handshake when the recipient is external, so the recipient discovers the message without having registered the sender in advance. When the recipient is one of the wallet's own accounts (a self-send), an address-derived secret is used instead: the wallet holds both sides' keys, so no handshake is needed and nothing is revealed onchain.
 - **Constrained delivery**: a non-interactive handshake (constrained delivery must be backed by a handshake).
 
+An interactive handshake is never the default, since it fails when the recipient cannot be reached: a wallet opts in through the hook when it knows how to reach them.
+
 ### Configuring the strategy
 
 Wallets provide the strategy through the `resolveTaggingSecretStrategy` [execution hook](../../foundational-topics/pxe/execution_hooks.md) when creating their PXE. The hook receives the message context (executing contract, sender, recipient and delivery mode), so a wallet can answer per message instead of with a fixed value. That page also covers how to configure a strategy in Noir tests.
@@ -198,7 +202,7 @@ A contract can fix the derivation at the point of delivery with the builder's `v
 MessageDelivery::onchain_unconstrained().via_address_derived_secret()
 ```
 
-Unconstrained delivery exposes `via_non_interactive_handshake()` and `via_address_derived_secret()`. Constrained delivery exposes only `via_non_interactive_handshake()`, since an address-derived secret cannot back constrained delivery.
+Unconstrained delivery exposes `via_non_interactive_handshake()`, `via_interactive_handshake()` and `via_address_derived_secret()`. Constrained delivery exposes only `via_non_interactive_handshake()` and `via_interactive_handshake()`, since an address-derived secret cannot back constrained delivery.
 
 ## Note Discovery and the Sender
 

docs/docs-developers/docs/foundational-topics/advanced/storage/note_discovery.md

@@ -27,7 +27,7 @@ Every tag is derived the same way: `poseidon2(secret, index)`.
 
 What varies is how the sender and recipient come to share `secret`. This is the [tagging secret strategy](../../../aztec-nr/framework-description/note_delivery.md#tagging-secret-strategy), chosen by the wallet by default, though a contract can [override it at delivery](../../../aztec-nr/framework-description/note_delivery.md#overriding-the-strategy-from-the-contract).
 
-There are three strategies, described below. They differ only in how `secret` is established. Once `secret` exists, the tag is derived from it the same way for all three.
+There are four strategies, described below. They differ only in how `secret` is established. Once `secret` exists, the tag is derived from it the same way for all four.
 
 ##### Arbitrary secret
 
@@ -43,6 +43,12 @@ To establish a handshake, the sender publishes an ephemeral public key onchain,
 
 This lets the recipient discover messages from a sender they never registered, at the cost of publishing onchain that a handshake was made with them. It is the default for reaching a new external recipient, and unlike an address-derived or arbitrary secret it can back [constrained delivery](../../../aztec-nr/framework-description/note_delivery.md#tagging-secret-strategy).
 
+##### Interactive handshake
+
+An interactive handshake derives the same kind of shared secret from an ephemeral key, but the ephemeral key is never published: instead of announcing it onchain, the recipient must be reachable at send time to sign it. The registry requests that signature through the custom request oracle and verifies it in-circuit, so the send fails if the recipient does not answer. The recipient learns the ephemeral key while signing and registers the resulting secret with their PXE so it can scan for the tags. As with a non-interactive handshake, the secret is app-siloed to the contract but left bare, with no directional fold.
+
+This reveals nothing onchain about the recipient, and like a non-interactive handshake it can back [constrained delivery](../../../aztec-nr/framework-description/note_delivery.md#tagging-secret-strategy). Because it requires the recipient's cooperation at send time, it is never the default: a wallet or contract opts in explicitly.
+
 ##### Deriving the tag from the secret
 
 Whichever strategy produced it, the resulting app-siloed tagging secret is turned into a tag the same way:
@@ -110,7 +116,7 @@ There are three broad families of solutions to this problem:
 
 **b) Tagging with known sender** - You know who will send you messages and search for those specifically. This is very fast and allows you to remove senders who spam you. However, it cannot be constrained, i.e., it cannot guarantee that the recipient will find the message. It also requires registering each sender's address in advance with `wallet.registerSender(address)`, so you must learn that address first.
 
-**c) Tagging with a handshake** - The sender and recipient execute a handshake to agree on a tagging secret, after which regular tagging works, so the recipient can discover messages without having registered the sender in advance. A handshake can be interactive (the two coordinate offchain) or non-interactive (published onchain, which needs no prior coordination but reveals a sender has done a handshake with the recipient). By default the wallet determines the type of handshake to use, though a contract can override the choice at delivery (see [tagging secret strategy](../../../aztec-nr/framework-description/note_delivery.md#tagging-secret-strategy)).
+**c) Tagging with a handshake** - The sender and recipient establish a handshake to agree on a tagging secret, after which regular tagging works: the recipient can discover messages without having registered the sender in advance. A non-interactive handshake is published onchain, so it needs nothing from the recipient, but it reveals that someone did a handshake with them. An interactive handshake reveals nothing onchain; in exchange, the recipient must sign it at send time. By default the wallet determines the type of handshake to use, though a contract can override the choice at delivery (see [tagging secret strategy](../../../aztec-nr/framework-description/note_delivery.md#tagging-secret-strategy)).
 
 See the [Note Delivery](../../../aztec-nr/framework-description/note_delivery.md) documentation for more details on how the sender is used when delivering notes.
 

docs/docs-developers/docs/foundational-topics/pxe/execution_hooks.md

@@ -96,6 +96,8 @@ Pass a `resolveTaggingSecretStrategy` hook when [creating the PXE](#configuring-
 
 When the hook is absent, the PXE applies a default: both delivery modes use a [non-interactive handshake](../../aztec-nr/framework-description/note_delivery.md#tagging-secret-strategy) so the recipient can discover the message without prior coordination.
 
+Returning `{ type: 'interactive-handshake' }` makes the handshake registry request the recipient's signed authorization through the [`resolveCustomRequest`](#resolvecustomrequest) hook (see the [example](#example-interactive-handshakes) below), so a wallet should only choose it when that request can be served.
+
 ## `resolveCustomRequest`
 
 A general-purpose hook for *custom*, caller-defined requests. A contract reaches for it when it needs something it cannot get on its own: not from its local notes, not from the protocol's existing oracles. The contract gives the request a `kind` and an opaque `payload`, and the wallet returns an opaque response. Because the request is caller-defined, the wallet decides per `kind` how to answer, whether by reading state it holds, contacting another party, or fetching offchain data.

noir-projects/aztec-nr/aztec/src/context/utility_context.nr

@@ -1,4 +1,4 @@
-use crate::oracle::{execution::get_utility_context, storage::storage_read};
+use crate::oracle::{execution::{get_utility_context, UtilityContextData}, storage::storage_read};
 use crate::protocol::{
     abis::block_header::BlockHeader, address::AztecAddress, constants::NULL_MSG_SENDER_CONTRACT_ADDRESS,
     traits::Packable,
@@ -11,6 +11,12 @@ pub struct UtilityContext {
     msg_sender: AztecAddress,
 }
 
+impl From<UtilityContextData> for UtilityContext {
+    fn from(data: UtilityContextData) -> Self {
+        Self { block_header: data.block_header, contract_address: data.contract_address, msg_sender: data.msg_sender }
+    }
+}
+
 impl UtilityContext {
     pub unconstrained fn new() -> Self {
         get_utility_context()