refactor: move registerContractFunctionSignatures to the node debug API (#24066)

Fixes A-1220

## Why

`node.registerContractFunctionSignatures` was an always-on,
unauthenticated write on the main `AztecNode` JSON-RPC surface. It
populates a per-node, in-memory, non-gossiped selector→name map used
only to name public-execution stack traces, so it has no business on a
prod node's public API (anyone can spam it up to the cap, and you'd have
to keep talking to the same node for it to mean anything). Decoding
traces should be a client concern.

## What

Relocate the method from the always-on `AztecNode` interface to the
existing, gated `AztecNodeDebug` interface (served under the
`nodeDebug_` namespace, only mounted when the node runs with debug
endpoints enabled — always on in the in-process sandbox, off by default
on standalone nodes). The node-side read path (`getDebugFunctionName` →
AVM trace naming) is unchanged; only the RPC write moves.

The PXE now calls it through an **optional** `nodeDebug` client and
skips registration entirely when the node does not expose the debug API.
PXE-side simulation errors keep named traces regardless, via the
existing ABI-based enrichment in `pxe/src/error_enriching.ts`.

- **stdlib**: removed `registerContractFunctionSignatures` from
`AztecNode` + `AztecNodeApiSchema`; added it (and the length/count caps)
to `AztecNodeDebug` + `AztecNodeDebugApiSchema`.
- **aztec-node**: server impl unchanged — `AztecNodeService` already
implements `AztecNodeDebug`, so the method now satisfies that interface
and is served under `nodeDebug_`.
- **pxe**: optional `nodeDebug?: AztecNodeDebug` on
`PXECreateArgs`/constructor; both registration call sites become
`this.nodeDebug?.registerContractFunctionSignatures(...)`. Threaded
`options.nodeDebug` through all three `createPXE` entrypoints (option A
— explicit injection).
- **e2e**: wired `nodeDebug` in `end-to-end/src/fixtures/setup.ts` for
both PXE-creation paths — `setup()` passes the in-process node service
directly; `setupPXEAndGetWallet()` passes it via an `isAztecNodeDebug`
type guard (one caller types its node loosely).
- **tests**: moved the schema round-trip case from the node interface
test to the debug interface test; retargeted the PXE registration tests
to the `nodeDebug` mock; updated the `node_rpc_perf` benchmark.
- **docs**: dropped the moved method from the generated node API
reference (the generator only documents `node_`/`nodeAdmin_`), and added
a migration note.

## Breaking change

`node_registerContractFunctionSignatures` is removed from the main node
RPC. Callers must use `nodeDebug_registerContractFunctionSignatures`
against a debug-enabled node. See the migration note.

## Verification

Local build could not be run here: the workspace is a cold checkout
(noir submodule packages absent, no Rust/Docker), so `yarn
install`/`yarn build` cannot bootstrap. The change is a contained
TypeScript interface relocation + optional-client wiring; relying on CI
for the full build/lint/test. A follow-up could wire
`createAztecNodeDebugClient(nodeUrl)` into the URL-based PXE creators
(bot/embedded wallet) if named traces are wanted against a debug-enabled
remote node.

---
*Created by
[claudebox](https://claudebox.work/v2/sessions/b8d3c4fab6c0225a) ·
group: `slackbot`*

Author: AztecBot

docs/docs-developers/docs/resources/migration_notes.md

@@ -93,6 +93,12 @@ All Aztec node JSON-RPC method prefixes have changed:
 If you call the node RPC directly (e.g. via `curl` or a custom client), update all method names accordingly.
 Clients created via `createAztecNodeClient`, `createAztecNodeAdminClient`, and `createAztecNodeDebugClient` are updated automatically.
 
+### [Node RPC] `registerContractFunctionSignatures` moved to the debug API
+
+`registerContractFunctionSignatures` is no longer part of the main node JSON-RPC API (`aztec_` namespace). It is now a debug-only method exposed under the `aztecDebug_` namespace, which is only mounted when the node runs with debug endpoints enabled (`--node-debug`, always on in the in-process sandbox). This removes an unauthenticated write to node memory from prod-like nodes.
+
+Clients that registered public function signatures over `aztec_registerContractFunctionSignatures` should call `aztecDebug_registerContractFunctionSignatures` against a debug-enabled node instead. In the PXE, this is now driven by an optional debug client: pass a `nodeDebug` client (e.g. `createAztecNodeDebugClient(nodeUrl)`) when creating the PXE to keep named public-execution traces; when it is absent, signature registration is skipped. Client-side error enrichment from the contract ABI is unaffected.
+
 ### [Aztec.nr] `get_pending_tagged_logs` oracle interface updated (oracle version 28)
 
 The `aztec_utl_getPendingTaggedLogs` oracle now takes an additional `provided_secrets` parameter of type `EphemeralArray<ProvidedSecret>`. This lets apps pass tagging secrets that PXE cannot derive on its own (e.g. handshake-derived secrets) alongside the secrets PXE manages internally.

docs/scripts/node_api_reference_generation/generate_node_api_reference.ts

@@ -606,7 +606,7 @@ const METHOD_GROUPS: { heading: string; namespace: string; methods: string[] }[]
   {
     heading: 'Debug operations',
     namespace: 'aztec',
-    methods: ['registerContractFunctionSignatures', 'getAllowedPublicSetup'],
+    methods: ['getAllowedPublicSetup'],
   },
   {
     heading: 'Admin API',

yarn-project/end-to-end/src/bench/node_rpc_perf.test.ts

@@ -15,6 +15,7 @@ import { BlockNumber, EpochNumber } from '@aztec/foundation/branded-types';
 import { Timer } from '@aztec/foundation/timer';
 import { TokenContract } from '@aztec/noir-contracts.js/Token';
 import { BlockHash } from '@aztec/stdlib/block';
+import type { AztecNodeDebug } from '@aztec/stdlib/interfaces/client';
 import { SiloedTag, Tag } from '@aztec/stdlib/logs';
 import { MerkleTreeId } from '@aztec/stdlib/trees';
 import type { Tx, TxHash } from '@aztec/stdlib/tx';
@@ -98,7 +99,7 @@ describe('e2e_node_rpc_perf', () => {
   jest.setTimeout(10 * 60 * 1000); // 10 minutes
 
   let logger: Logger;
-  let aztecNode: AztecNode;
+  let aztecNode: AztecNode & AztecNodeDebug;
   let wallet: TestWallet;
   let ownerAddress: AztecAddress;
   let rollupCheatCodes: RollupCheatCodes;

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

@@ -6,6 +6,7 @@ import type { Logger } from '@aztec/aztec.js/log';
 import type { AztecNode } from '@aztec/aztec.js/node';
 import { TokenContract } from '@aztec/noir-contracts.js/Token';
 import { ChildContract } from '@aztec/noir-test-contracts.js/Child';
+import type { AztecNodeDebug } from '@aztec/stdlib/interfaces/client';
 
 import { expect, jest } from '@jest/globals';
 
@@ -19,7 +20,7 @@ const TIMEOUT = 300_000;
 describe('e2e_2_pxes', () => {
   jest.setTimeout(TIMEOUT);
 
-  let aztecNode: AztecNode;
+  let aztecNode: AztecNode & AztecNodeDebug;
   let walletA: TestWallet;
   let walletB: TestWallet;
   let accountAAddress: AztecAddress;
@@ -30,12 +31,12 @@ describe('e2e_2_pxes', () => {
   let teardownB: () => Promise<void>;
 
   async function setupSecondaryPXE(
-    node: AztecNode,
+    node: AztecNode & AztecNodeDebug,
     fundedAccounts: InitialAccountData[],
     accountIndex: number,
     pxeName: string,
   ) {
-    const { wallet, teardown } = await setupPXEAndGetWallet(node, {}, undefined, pxeName);
+    const { wallet, teardown } = await setupPXEAndGetWallet(node, node, {}, undefined, pxeName);
     const accountManager = await wallet.createSchnorrAccount(
       fundedAccounts[accountIndex].secret,
       fundedAccounts[accountIndex].salt,

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

@@ -559,7 +559,7 @@ describe('e2e_synching', () => {
             const aztecNode = await AztecNodeService.createAndSync(opts.config!, {}, { genesis: opts.genesis });
             const sequencer = aztecNode.getSequencer();
 
-            const { wallet } = await setupPXEAndGetWallet(aztecNode!);
+            const { wallet } = await setupPXEAndGetWallet(aztecNode!, aztecNode!);
             variant.setWallet(wallet);
             const defaultAccountAddress = (await variant.deployAccounts(opts.initialFundedAccounts!.slice(0, 1)))[0];
 
@@ -700,7 +700,7 @@ describe('e2e_synching', () => {
           expect(await aztecNode.getBlockNumber()).toBeLessThan(blockBeforePrune);
 
           // We need to start the pxe after the re-org for now, because it won't handle it otherwise
-          const { wallet } = await setupPXEAndGetWallet(aztecNode!);
+          const { wallet } = await setupPXEAndGetWallet(aztecNode!, aztecNode!);
           variant.setWallet(wallet);
 
           const blockBefore = await aztecNode.getBlock(await aztecNode.getBlockNumber());
@@ -751,7 +751,7 @@ describe('e2e_synching', () => {
           const aztecNode = await AztecNodeService.createAndSync(opts.config!, {}, { genesis: opts.genesis });
           const sequencer = aztecNode.getSequencer();
 
-          const { wallet: newWallet } = await setupPXEAndGetWallet(aztecNode!);
+          const { wallet: newWallet } = await setupPXEAndGetWallet(aztecNode!, aztecNode!);
           variant.setWallet(newWallet);
 
           const blockBefore = await aztecNode.getBlock(await aztecNode.getBlockNumber());

yarn-project/end-to-end/src/fixtures/e2e_prover_test.ts

@@ -186,6 +186,7 @@ export class FullProverTest {
     this.logger.verbose(`Main setup completed, initializing full prover PXE, Node, and Prover Node`);
     const { wallet: provenWallet, teardown: provenTeardown } = await setupPXEAndGetWallet(
       this.aztecNode,
+      this.context.aztecNode,
       { proverEnabled: this.realProofs },
       undefined,
       'pxe-proven',

yarn-project/end-to-end/src/fixtures/setup.ts

@@ -119,13 +119,16 @@ export async function setupSharedBlobStorage(config: { dataDirectory?: string }
 /**
  * Sets up Private eXecution Environment (PXE) and returns the corresponding test wallet.
  * @param aztecNode - An instance of Aztec Node.
+ * @param nodeDebug - The node's debug API, used to register public function signatures for named traces; pass
+ *   `undefined` when the node does not expose it.
  * @param opts - Partial configuration for the PXE.
  * @param logger - The logger to be used.
  * @param actor - Actor label to include in log output (e.g., 'pxe-test').
  * @returns A test wallet, logger and teardown function.
  */
 export async function setupPXEAndGetWallet(
   aztecNode: AztecNode,
+  nodeDebug: AztecNodeDebug | undefined,
   opts: Partial<PXEConfig> = {},
   logger = getLogger(),
   actor?: string,
@@ -146,7 +149,10 @@ export async function setupPXEAndGetWallet(
 
   const teardown = configuredDataDirectory ? () => Promise.resolve() : () => tryRmDir(PXEConfig.dataDirectory!);
 
-  const wallet = await TestWallet.create(aztecNode, PXEConfig, { loggerActorLabel: actor });
+  const wallet = await TestWallet.create(aztecNode, PXEConfig, {
+    loggerActorLabel: actor,
+    nodeDebug,
+  });
 
   return {
     wallet,
@@ -609,6 +615,8 @@ export async function setup(
     pxeConfig.proverEnabled = !!pxeOpts.proverEnabled;
     const wallet = await TestWallet.create(aztecNodeService, pxeConfig, {
       loggerActorLabel: 'pxe-0',
+      // In-process node implements the debug API, so register public function signatures for named traces.
+      nodeDebug: aztecNodeService,
       ...opts.pxeCreationOptions,
     });
 

yarn-project/pxe/src/entrypoints/client/bundle/utils.ts

@@ -63,6 +63,7 @@ export async function createPXE(
   const pxeLogger = loggers.pxe ?? createLogger('pxe:service', { actor });
   const pxe = await PXE.create({
     node: aztecNode,
+    nodeDebug: options.nodeDebug,
     store,
     proofCreator: prover,
     simulator,

yarn-project/pxe/src/entrypoints/client/lazy/utils.ts

@@ -63,6 +63,7 @@ export async function createPXE(
   const pxeLogger = loggers.pxe ?? createLogger('pxe:service', { actor });
   const pxe = await PXE.create({
     node: aztecNode,
+    nodeDebug: options.nodeDebug,
     store,
     proofCreator: prover,
     simulator,

yarn-project/pxe/src/entrypoints/pxe_creation_options.ts

@@ -2,7 +2,7 @@ import type { BBPrivateKernelProverOptions } from '@aztec/bb-prover/client';
 import type { Logger } from '@aztec/foundation/log';
 import type { AztecAsyncKVStore } from '@aztec/kv-store';
 import type { CircuitSimulator } from '@aztec/simulator/client';
-import type { PrivateKernelProver } from '@aztec/stdlib/interfaces/client';
+import type { AztecNodeDebug, PrivateKernelProver } from '@aztec/stdlib/interfaces/client';
 
 import type { ExecutionHooks } from '../hooks/index.js';
 import type { PreloadedContractsProvider } from '../pxe.js';
@@ -18,6 +18,12 @@ export type PXECreationOptions = {
   hooks?: ExecutionHooks;
   /** Contracts to preload on startup. Replaces the default when set. */
   preloadedContractsProvider?: PreloadedContractsProvider;
+  /**
+   * Optional debug API client for the same node. When provided, public function signatures are registered so the
+   * node can produce named public-execution stack traces. Only available on nodes started with debug endpoints
+   * enabled; omitted in prod-like setups.
+   */
+  nodeDebug?: AztecNodeDebug;
 };
 
 /** Checks if the given value implements the PrivateKernelProver interface via duck-typing. */