AztecProtocol · mverzilli · Mar 11, 2026 · Feb 18, 2026 · Feb 17, 2026 · Feb 17, 2026
diff --git a/docs/netlify.toml b/docs/netlify.toml
@@ -796,3 +796,7 @@
     from = "/errors/6"
     to = "/developers/docs/aztec-nr/framework-description/calling_contracts"
 
+[[redirects]]
+    # Aztec-nr: user-defined 'offchain_receive' is not allowed
+    from = "/errors/7"
+    to = "/aztec-nr-api/nightly/noir_aztec/messages/processing/offchain/fn.receive.html"
@@ -46,7 +46,7 @@ impl AztecConfig {
     /// This enables contracts to process non-standard messages (i.e. any with a message type that is not in
     /// [`crate::messages::msg_type`]).
     ///
-    /// `handler` must be a `#[contract_library_method]` function that conforms to the
+    /// `handler` must be a function that conforms to the
     /// [`crate::messages::discovery::CustomMessageHandler`] type signature.
     pub comptime fn custom_message_handler(_self: Self, handler: CustomMessageHandler<()>) -> Self {
         Self { custom_message_handler: Option::some(handler) }
@@ -115,12 +115,23 @@ pub comptime fn aztec(m: Module, args: [AztecConfig]) -> Quoted {
         quote { Option::<aztec::messages::discovery::CustomMessageHandler<()>>::none() }
     };
 
+    let offchain_inbox_sync_option = quote {
+        Option::some(aztec::messages::processing::offchain::sync_inbox)
+    };
+
     let sync_state_fn_and_abi_export = if !m.functions().any(|f| f.name() == quote { sync_state }) {
-        generate_sync_state(process_custom_message_option)
+        generate_sync_state(process_custom_message_option, offchain_inbox_sync_option)
     } else {
         quote {}
     };
 
+    if m.functions().any(|f| f.name() == quote { offchain_receive }) {
+        panic(
+            "User-defined 'offchain_receive' is not allowed. The function is auto-injected by the #[aztec] macro. See https://docs.aztec.network/errors/7",
+        );
+    }
+    let offchain_receive_fn_and_abi_export = generate_offchain_receive();
+
     let process_message_fn_and_abi_export = if !m.functions().any(|f| f.name() == quote { process_message }) {
         generate_process_message(process_custom_message_option)
     } else {
@@ -138,6 +149,7 @@ pub comptime fn aztec(m: Module, args: [AztecConfig]) -> Quoted {
         $public_dispatch
         $sync_state_fn_and_abi_export
         $process_message_fn_and_abi_export
+        $offchain_receive_fn_and_abi_export
     }
 }
 
@@ -337,7 +349,7 @@ comptime fn generate_contract_library_method_compute_note_hash_and_nullifier() -
 }
 
 /// Generates the `sync_state` utility function that performs message discovery.
-comptime fn generate_sync_state(process_custom_message_option: Quoted) -> Quoted {
+comptime fn generate_sync_state(process_custom_message_option: Quoted, offchain_inbox_sync_option: Quoted) -> Quoted {
     quote {
         pub struct sync_state_parameters {}
 
@@ -353,6 +365,7 @@ comptime fn generate_sync_state(process_custom_message_option: Quoted) -> Quoted
                 address,
                 _compute_note_hash_and_nullifier,
                 $process_custom_message_option,
+                $offchain_inbox_sync_option,
             );
         }
     }
@@ -393,6 +406,41 @@ comptime fn generate_process_message(process_custom_message_option: Quoted) -> Q
     }
 }
 
+/// Generates an `offchain_receive` utility function that lets callers add messages to the offchain message inbox.
+///
+/// For more details, see `aztec::messages::processing::offchain::receive`.
+comptime fn generate_offchain_receive() -> Quoted {
+    quote {
+        pub struct offchain_receive_parameters {
+            pub messages: BoundedVec<
+                aztec::messages::processing::offchain::OffchainMessage,
+                aztec::messages::processing::offchain::MAX_OFFCHAIN_MESSAGES_PER_RECEIVE_CALL,
+            >,
+        }
+
+        #[abi(functions)]
+        pub struct offchain_receive_abi {
+            parameters: offchain_receive_parameters,
+        }
+
+        /// Receives offchain messages into this contract's offchain inbox for subsequent processing.
+        ///
+        /// For more details, see `aztec::messages::processing::offchain::receive`.
+        ///
+        /// This function is automatically injected by the `#[aztec]` macro.
+        #[aztec::macros::internals_functions_generation::abi_attributes::abi_utility]
+        unconstrained fn offchain_receive(
+            messages: BoundedVec<
+                aztec::messages::processing::offchain::OffchainMessage,
+                aztec::messages::processing::offchain::MAX_OFFCHAIN_MESSAGES_PER_RECEIVE_CALL,
+            >,
+        ) {
+            let address = aztec::context::UtilityContext::new().this_address();
+            aztec::messages::processing::offchain::receive(address, messages);
+        }
+    }
+}
+
 /// Checks that all functions in the module have a context macro applied.
 ///
 /// Non-macroified functions are not allowed in contracts. They must all be one of

@@ -8,13 +8,14 @@ pub mod private_notes;
 pub mod process_message;
 
 use crate::{
+    capsules::CapsuleArray,
     messages::{
         discovery::process_message::process_message_ciphertext,
         encoding::MAX_MESSAGE_CONTENT_LEN,
         logs::note::MAX_NOTE_PACKED_LEN,
         processing::{
-            get_private_logs, MessageContext, pending_tagged_log::PendingTaggedLog,
-            validate_and_store_enqueued_notes_and_events,
+            get_private_logs, MessageContext, offchain::OffchainInboxSync, OffchainMessageWithContext,
+            pending_tagged_log::PendingTaggedLog, validate_and_store_enqueued_notes_and_events,
         },
     },
     utils::array,
@@ -107,6 +108,7 @@ pub unconstrained fn do_sync_state<ComputeNoteHashAndNullifierEnv, CustomMessage
     contract_address: AztecAddress,
     compute_note_hash_and_nullifier: ComputeNoteHashAndNullifier<ComputeNoteHashAndNullifierEnv>,
     process_custom_message: Option<CustomMessageHandler<CustomMessageHandlerEnv>>,
+    offchain_inbox_sync: Option<OffchainInboxSync<()>>,
 ) {
     aztecnr_debug_log!("Performing state synchronization");
 
@@ -134,6 +136,22 @@ pub unconstrained fn do_sync_state<ComputeNoteHashAndNullifierEnv, CustomMessage
         logs.remove(i);
     });
 
+    if offchain_inbox_sync.is_some() {
+        let msgs: CapsuleArray<OffchainMessageWithContext> = offchain_inbox_sync.unwrap()(contract_address);
+        msgs.for_each(|i, msg| {
+            process_message_ciphertext(
+                contract_address,
+                compute_note_hash_and_nullifier,
+                process_custom_message,
+                msg.message_ciphertext,
+                msg.message_context,
+            );
+            // The inbox sync returns _a copy_ of messages to process, so we clear them as we do so. This is a
+            // volatile array with the to-process message, not the actual persistent storage of them.
+            msgs.remove(i);
+        });
+    }
+
     // Then we process all pending partial notes, regardless of whether they were found in the current or previous
     // executions.
     partial_notes::fetch_and_process_partial_note_completion_logs(contract_address, compute_note_hash_and_nullifier);

@@ -1,18 +1,32 @@
-use crate::protocol::{address::AztecAddress, constants::MAX_NOTE_HASHES_PER_TX, traits::Deserialize};
+use crate::protocol::{address::AztecAddress, constants::MAX_NOTE_HASHES_PER_TX, traits::{Deserialize, Serialize}};
 
 /// Additional information needed to process a message.
 ///
 /// All messages exist in the context of a transaction, and information about that transaction is typically required in
 /// order to perform validation, store results, etc. For example, messages containing notes require knowledge of note
 /// hashes and the first nullifier in order to find the note's nonce.
-#[derive(Deserialize, Eq)]
+#[derive(Serialize, Deserialize, Eq)]
 pub struct MessageContext {
     pub tx_hash: Field,
     pub unique_note_hashes_in_tx: BoundedVec<Field, MAX_NOTE_HASHES_PER_TX>,
     pub first_nullifier_in_tx: Field,
     pub recipient: AztecAddress,
 }
 
+/// Transaction context needed to process a message.
+///
+/// Like [`MessageContext`], but `MessageTxContext` does not include the recipient. MessageTxContext's are kind of
+/// adhoc: they are just the minimal data structure that the contract needs to get from a PXE oracle to prepare
+/// offchain messages to be processed. We reify it with a type just because it crosses Noir<->TS boundaries.
+/// The contract knows how to pair the context data with a recipient: then it is able to build a `MessageContext` for
+/// subsequent processing.
+#[derive(Serialize, Deserialize, Eq)]
+pub(crate) struct MessageTxContext {
+    pub tx_hash: Field,
+    pub unique_note_hashes_in_tx: BoundedVec<Field, MAX_NOTE_HASHES_PER_TX>,
+    pub first_nullifier_in_tx: Field,
+}
+
 mod test {
     use crate::messages::processing::MessageContext;
     use crate::protocol::{address::AztecAddress, traits::{Deserialize, FromField}};

@@ -1,7 +1,9 @@
 pub(crate) mod event_validation_request;
+pub mod offchain;
 
 mod message_context;
 pub use message_context::MessageContext;
+pub(crate) use message_context::MessageTxContext;
 
 pub(crate) mod note_validation_request;
 pub(crate) mod log_retrieval_request;
@@ -13,6 +15,7 @@ use crate::{
     event::EventSelector,
     messages::{
         discovery::partial_notes::DeliveredPendingPartialNote,
+        encoding::MESSAGE_CIPHERTEXT_LEN,
         logs::{event::MAX_EVENT_SERIALIZED_LEN, note::MAX_NOTE_PACKED_LEN},
         processing::{
             log_retrieval_request::LogRetrievalRequest, log_retrieval_response::LogRetrievalResponse,
@@ -21,7 +24,7 @@ use crate::{
     },
     oracle,
 };
-use crate::protocol::{address::AztecAddress, hash::sha256_to_field};
+use crate::protocol::{address::AztecAddress, hash::sha256_to_field, traits::{Deserialize, Serialize}};
 use event_validation_request::EventValidationRequest;
 
 // Base slot for the pending tagged log array to which the fetch_tagged_logs oracle inserts found private logs.
@@ -44,6 +47,13 @@ global LOG_RETRIEVAL_RESPONSES_ARRAY_BASE_SLOT: Field = sha256_to_field(
     "AZTEC_NR::LOG_RETRIEVAL_RESPONSES_ARRAY_BASE_SLOT".as_bytes(),
 );
 
+/// An offchain-delivered message with resolved context, ready for processing during sync.
+#[derive(Serialize, Deserialize)]
+pub struct OffchainMessageWithContext {
+    pub message_ciphertext: BoundedVec<Field, MESSAGE_CIPHERTEXT_LEN>,
+    pub message_context: MessageContext,
+}
+
 /// Searches for private logs emitted by `contract_address` that might contain messages for one of the local accounts,
 /// and stores them in a `CapsuleArray` which is then returned.
 pub(crate) unconstrained fn get_private_logs(contract_address: AztecAddress) -> CapsuleArray<PendingTaggedLog> {
@@ -159,6 +169,23 @@ pub unconstrained fn validate_and_store_enqueued_notes_and_events(contract_addre
     );
 }
 
+/// Resolves message contexts for a list of tx hashes stored in a CapsuleArray.
+///
+/// The `message_context_requests_array_base_slot` must point to a CapsuleArray<Field> containing tx hashes.
+/// PXE will store `Option<MessageContextResponse>` values into the responses array at
+/// `message_context_responses_array_base_slot`.
+pub unconstrained fn resolve_message_contexts(
+    contract_address: AztecAddress,
+    message_context_requests_array_base_slot: Field,
+    message_context_responses_array_base_slot: Field,
+) {
+    oracle::message_processing::resolve_message_contexts(
+        contract_address,
+        message_context_requests_array_base_slot,
+        message_context_responses_array_base_slot,
+    );
+}
+
 /// Efficiently queries the node for logs that result in the completion of all `DeliveredPendingPartialNote`s stored in
 /// a `CapsuleArray` by performing all node communication concurrently. Returns a second `CapsuleArray` with Options
 /// for the responses that correspond to the pending partial notes at the same index.