refactor: forbid globally scoped capsules by mverzilli · Pull Request #21614 · AztecProtocol/aztec-packages

mverzilli · 2026-03-16T17:07:18Z

Depends on #21588

Uses the new scoped functionalities of capsules from as many places in the codebase as possible

Note: this PR makes the distinction between stored capsules and volatile arrays even more painfully clear, as capsules used just for rpc comms between Aztec.nr and PXE don't really need a scope but at the same time would be better off not being global to remove concurrency constraints

Closes F-459

…apsules

…arrays-scope-up-1

mverzilli · 2026-03-16T17:24:16Z

noir-projects/aztec-nr/aztec/src/messages/processing/offchain.nr

+        let inbox: CapsuleArray<PendingOffchainMsg> =
+            CapsuleArray::at(contract_address, OFFCHAIN_INBOX_SLOT, msg.recipient);


This is not super elegant but it doesn't seem like a costly abstraction, so leaving it like that

…arrays-scope-up-1

mverzilli · 2026-03-16T17:49:04Z

yarn-project/pxe/src/pxe.ts

      node,
      contractStore,
      noteStore,
+      () => keyStore.getAccounts(),


I would like to kill the "ALL_SCOPES" idea and get rid of this

I support you in this endeavor. We got to ALL_SCOPES through "evolution" and not through designing.

mverzilli · 2026-03-16T17:57:51Z

yarn-project/pxe/src/contract_sync/contract_sync_service.ts

+    // Resolve ALL_SCOPES to actual registered accounts, since sync_state must be called once per account.
+    const scopeAddresses = scopes === 'ALL_SCOPES' ? await this.getRegisteredAccounts() : scopes;
+
    await Promise.all([


ideally we could get rid of plural scopes throughout the systems, which would let us simplify this and the code below

"get rid of plural scopes throughout the system" is too much, there are legitimate use cases (such as getting notes scoped to multiple accounts at once).

mverzilli · 2026-03-16T19:12:45Z

noir-projects/aztec-nr/aztec/src/messages/processing/offchain.nr

    let context_resolution_requests: CapsuleArray<Field> =
-        CapsuleArray::at_global_scope(address, OFFCHAIN_CONTEXT_REQUESTS_SLOT);
+        CapsuleArray::at(contract_address, OFFCHAIN_CONTEXT_REQUESTS_SLOT, scope);
    let resolved_contexts: CapsuleArray<Option<MessageTxContext>> =
-        CapsuleArray::at_global_scope(address, OFFCHAIN_CONTEXT_RESPONSES_SLOT);
+        CapsuleArray::at(contract_address, OFFCHAIN_CONTEXT_RESPONSES_SLOT, scope);
    let ready_to_process: CapsuleArray<OffchainMessageWithContext> =
-        CapsuleArray::at_global_scope(address, OFFCHAIN_READY_MESSAGES_SLOT);
+        CapsuleArray::at(contract_address, OFFCHAIN_READY_MESSAGES_SLOT, scope);


These could technically be global scope capsules if we left the scope param out of resolve_message_contexts, but given there is no legacy here I preferred to scope them and gain some extra isolation points.

We should eventually replace this with volatile arrays which are the right idea to use here

…apsules

…arrays-scope-up-1

…s' into martin/capsule-arrays-scope-up-1

noir-projects/aztec-nr/aztec/src/macros/aztec.nr

mverzilli · 2026-03-19T11:56:18Z

noir-projects/aztec-nr/aztec/src/macros/aztec.nr


        /// Receives offchain messages into this contract's offchain inbox for subsequent processing.
        ///
+        /// Each message is routed to the inbox scoped to its `recipient` field.


This is one decision open to debate, I went for this initially because I had the "scoped sync_state" refactor ahead of me, but now I'm wondering if offchain_receive shouldn't explicitly receive an array of scopes and place each message in each scope regardless of who is each message's specific recipient

I see scopes as an implementation detail of PXE. The message was sent to X, it is processed as received by X. How it is stored in the db etc feels divorced from this.

Aren't messages generally destined for 1 scope?

Yes, each message has one recipient, but as we've been discussing in other chats, there's a bit of chaos to tame here:

offchain_receive is a utility

it needs to be run with from, which will become its scope

but it can receive multiple messages, each with its own recipient

that opens the door to multiple possible behaviors. if the recipients != scope, what do we do? ignore? throw? route them to their inbox? something else?

moreover, there's the concept of additionalScopes when running private functions:

Will we ever want to support additionalScopes from utilities as well?

How does that behave in combination with message recipients (same questions as above)?

Why is it a problem to have multiple recipients? Are we not allowed to store something in a scope that is not currently open?

To clarify what I mean, the from in an utility fn is a mistake, it's just a simple way to specify the scopes to use. We use from to not expose this complexity to the app, and the wallet does from -> scopes. But that's just a shortcut.

Conceptually there is no problem in procesing multiple messages to different recipients, though if they are not in scope then msg processing may fail (e.g. we may not be able to read their keys).

There is no inherent problem, just a degree of freedom that I haven't seen in other of our contract APIs so I thought worth explicitly mentioning

mverzilli · 2026-03-19T12:01:43Z

noir-projects/aztec-nr/aztec/src/messages/discovery/private_events.nr


 pub(crate) unconstrained fn process_private_event_msg(
    contract_address: AztecAddress,
-    recipient: AztecAddress,


another debatable change: I removed the recipient params from all process_*_msg variants, though it might in the future be useful to have access to that info when processing. I chose to remove them nevertheless because it's not used, YMMV.

The recipient is the scope here so you should always have that info during processing just by the fact that you are able to load the thing from the correct scope, no?

Yes, correct. When I wrote this I wasn't 100% sure that always the scope is the recipient

Whoa I'm not sure about this. Why does the scope pop up here? It is because of the capsule oracle? If so this is news conceptually - the fact that the scope is the recipient used to be a pxe detail, but now this leaks into nr.

noir-projects/aztec-nr/aztec/src/macros/aztec.nr

benesjan · 2026-03-22T08:23:47Z

noir-projects/aztec-nr/aztec/src/macros/aztec.nr


        /// Receives offchain messages into this contract's offchain inbox for subsequent processing.
        ///
+        /// Each message is routed to the inbox scoped to its `recipient` field.


Aren't messages generally destined for 1 scope?

benesjan · 2026-03-22T08:30:49Z

noir-projects/aztec-nr/aztec/src/messages/processing/mod.nr

-pub(crate) unconstrained fn get_private_logs(contract_address: AztecAddress) -> CapsuleArray<PendingTaggedLog> {
+///
+/// Note that eventually it would make sense to make this function accept an array of addresses as of scopes, since it
+/// might be useful to integrate all private logs known to a set of accounts. However, this function is currently only


integrate all private logs known to a set of accounts

WDYM by this? Loading logs "into" multiple scopes at once?

Yes, maybe this is too much philosophizing on my end. This function as is just fetches logs, one could imagine a version of this that fetches logs from multiple scopes at once and does something with them, but currently there's no use for that. Maybe I should just remove this comment which ends up adding more noise than clarity

benesjan · 2026-03-22T12:13:03Z

noir-projects/aztec-nr/aztec/src/messages/discovery/private_events.nr


 pub(crate) unconstrained fn process_private_event_msg(
    contract_address: AztecAddress,
-    recipient: AztecAddress,


The recipient is the scope here so you should always have that info during processing just by the fact that you are able to load the thing from the correct scope, no?

benesjan · 2026-03-22T12:13:14Z

noir-projects/aztec-nr/aztec/src/test/helpers/test_environment.nr

                process_custom_message,
                message_plaintext,
                message_context,
+                message_context.recipient,


Somewhat unrelated but above we have this comment:

// Real messages would also have a recipient, a concept which is currently half-supported in `TestEnvironment` // as events are properly scoped by recipient, but notes use a global scope instead. We therefore simply set // the zero address as the recipient if one is not supplied, which PXE accepts as a scope despite this not // being a registered account.

The zero address seems to act here as somewhat of a global scope. Do you know if there is some plan to purge that? And do you know if the notes truly still use global scope? I am worried that we will forget about this.

Will review that comment. I think notes no longer use global scope, especially after this change

I think we should remove that recipient=ZERO line and make sure we're using a proper recipient. I'm surprised this hasn't caused issues so far.

Cool cool, please link the issues here then. Thanks

benesjan · 2026-03-22T12:13:44Z

yarn-project/end-to-end/src/e2e_offchain_effect.test.ts

+      .simulate({ from: recipient });
+
+    // Force a block so PXE re-syncs and processes the offchain-delivered message
+    await forceEmptyBlock();


Doesn't this indicate that the current offchain_receive flow is cumbersome in the real world as we might want to have a flow in which we would want to fully process an offchain message and then we would need to wait for a new block? Shouldn't we have the ability to trigger re-sync at the same anchor block somehow exposed?

I see there is already this issue for it. Would link it in the comment of forceEmptyBlock

Will do. There's actually a new oracle to invalidate the cache for the given contract+scope combination, I just need to use it for this hack to be gone.

benesjan · 2026-03-22T12:14:24Z

yarn-project/pxe/src/contract_function_simulator/oracle/utility_execution_oracle.ts

+      // At the same time, we don't want allow any global scope access other than where backwards compatibility forces
+      // us to, so we need scope to be here artificially.


Suggested change

// At the same time, we don't want allow any global scope access other than where backwards compatibility forces

// us to, so we need scope to be here artificially.

// At the same time, we don't want to allow any global scope access other than where backwards compatibility forces

// us to. Hence the scope here is "artifical".

The wording seemed cumbersome.

yarn-project/pxe/src/logs/log_service.ts

benesjan · 2026-03-22T12:15:35Z

yarn-project/pxe/src/pxe.ts

      node,
      contractStore,
      noteStore,
+      () => keyStore.getAccounts(),


I support you in this endeavor. We got to ALL_SCOPES through "evolution" and not through designing.

yarn-project/pxe/src/storage/capsule_store/capsule_store.ts

…tin/capsule-arrays-scope-up-1

mverzilli · 2026-03-23T13:17:25Z

noir-projects/aztec-nr/aztec/src/messages/discovery/mod.nr

@@ -141,6 +143,7 @@ pub unconstrained fn do_sync_state<CustomMessageHandlerEnv>(
                process_custom_message,
                message_ciphertext,
                pending_tagged_log.context,


Maybe for an upcoming refactor:

pending_tagged_log.context is a MessageContext.

MessageContext has a recipient.

The recipient is, by definition, the scope, because that's what we're filtering by in the get_private_logs call above

This is a remnant from before introducing scope to sync_state, when get_private_logs was expected to include messages aimed at different recipients.

Carrying the recipient through this introduces some noise, since now process_message_ciphertext will have the scope or the recipient to pick from.

-> We should remove recipient from MessageContext.

Decided to tackle said refactor now, because it impacts oracle interfaces, so it's better to include it in the next release to avoid unnecessary version bumps

nventuro · 2026-03-19T13:31:28Z

noir-projects/aztec-nr/aztec/src/macros/aztec.nr


        /// Receives offchain messages into this contract's offchain inbox for subsequent processing.
        ///
+        /// Each message is routed to the inbox scoped to its `recipient` field.


I see scopes as an implementation detail of PXE. The message was sent to X, it is processed as received by X. How it is stored in the db etc feels divorced from this.

noir-projects/aztec-nr/aztec/src/capsules/mod.nr

mverzilli added 5 commits March 16, 2026 12:01

scoped capsule arrays

f28eeb5

migration notes

8c82f1e

port implementations to scoped capsule arrays

952a340

Merge branch 'martin/scoped-capsules' into martin/default-to-scoped-c…

9fa7584

…apsules

Merge branch 'martin/default-to-scoped-capsules' into martin/capsule-…

1e3b341

…arrays-scope-up-1

mverzilli changed the title ~~Martin/capsule arrays scope up 1~~ refactor: default to scoped capsule arrays Mar 16, 2026

mverzilli marked this pull request as ready for review March 16, 2026 17:15

mverzilli requested a review from nventuro as a code owner March 16, 2026 17:15

mverzilli removed the request for review from nventuro March 16, 2026 17:15

mverzilli commented Mar 16, 2026

View reviewed changes

mverzilli added 2 commits March 16, 2026 17:33

pass new capsule params through for txe

1fed051

Merge branch 'martin/default-to-scoped-capsules' into martin/capsule-…

15acc46

…arrays-scope-up-1

mverzilli commented Mar 16, 2026

View reviewed changes

mverzilli added 4 commits March 16, 2026 18:31

fix offchain tests

d7979cf

remove unused import

6d9044c

update oracle hash

207eb78

use scoped capsule arrays in custom message handler

089a31f

mverzilli commented Mar 16, 2026

View reviewed changes

mverzilli added 9 commits March 16, 2026 19:18

fix compile error

9a8304a

Alice and Bob sides both coherent

000a07d

fix reorg test

078189c

Merge branch 'martin/scoped-capsules' into martin/default-to-scoped-c…

4d15105

…apsules

Merge branch 'martin/default-to-scoped-capsules' into martin/capsule-…

87af2e4

…arrays-scope-up-1

fix tests

a9fdc1a

fix lint

79b9dea

fix utility execution tests

a8cc169

use keystore to provide scopes from txe

9806851

mverzilli requested review from nventuro and removed request for nventuro March 17, 2026 12:04

mverzilli mentioned this pull request Mar 18, 2026

feat!: scoped capsule arrays #21588

Merged

mverzilli added 3 commits March 18, 2026 12:39

fix reorg flake

b1a28d4

Merge remote-tracking branch 'origin/martin/default-to-scoped-capsule…

59a5240

…s' into martin/capsule-arrays-scope-up-1

torch at_global_scope

99021e4

mverzilli commented Mar 19, 2026

View reviewed changes

noir-projects/aztec-nr/aztec/src/macros/aztec.nr Show resolved Hide resolved

mverzilli commented Mar 19, 2026

View reviewed changes

mverzilli added 2 commits March 19, 2026 12:03

typo

bbf8d88

remove scope optionality in message context resolution oracle

e377325

mverzilli changed the title ~~refactor: default to scoped capsule arrays~~ refactor: forbid globally scoped capsules Mar 19, 2026

mverzilli added 6 commits March 19, 2026 13:47

update oracle version hash

b6841d9

update oracle hash

f055902

fix oracle unit tests

a190ad6

remove at_global_scope

87ed982

fix tests

2080f7c

make scope non-optional for capsulearray

469a3d2

benesjan reviewed Mar 22, 2026

View reviewed changes

Base automatically changed from martin/default-to-scoped-capsules to martin/scoped-capsules March 23, 2026 11:31

mverzilli added 4 commits March 23, 2026 12:13

Merge remote-tracking branch 'origin/martin/scoped-capsules' into mar…

942fc88

…tin/capsule-arrays-scope-up-1

remove bad comment

3874e28

fix comment

3ce1ad2

remove unnecessary legacy oracle mappings

b40472c

mverzilli commented Mar 23, 2026

View reviewed changes

mverzilli added 5 commits March 23, 2026 13:52

remove recipient from msg context

c201638

make capsules always scoped

8ff53ae

fix txe

92e5449

fix sublib capsules

3b4df4f

update oracle hash

fac1f2c

nventuro reviewed Mar 23, 2026

View reviewed changes

remove redundant tests

2339aff

		let inbox: CapsuleArray<PendingOffchainMsg> =
		CapsuleArray::at(contract_address, OFFCHAIN_INBOX_SLOT, msg.recipient);

		// At the same time, we don't want allow any global scope access other than where backwards compatibility forces
		// us to, so we need scope to be here artificially.

Conversation

mverzilli commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

mverzilli Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

mverzilli commented Mar 16, 2026 •

edited

Loading

mverzilli Mar 16, 2026 •

edited

Loading