feat(agglayer): add faucet deregistration

Adds a bridge-admin-gated `deregister_faucet` MASM procedure that revokes a
faucet, clearing every entry registration wrote for it: the `faucet_registry_map`,
`token_registry_map`, and all four `faucet_metadata_map` sub-keys. Wired through a
new `DEREGISTER_AGG_BRIDGE` note script and a `DeregisterAggBridgeNote` Rust
builder. After deregistration, in-flight B2AGG and CLAIM notes referencing the
cleared faucet fail their existing registration checks.

The token registry is pair-keyed on (origin_token_address, origin_network). Rather
than trusting note-supplied values, `deregister_faucet` reads the faucet's
registered address and network back from its own `faucet_metadata_map` (via
`get_faucet_conversion_info`) and recomputes the key, so the cleared token-registry
entry is provably the one `register_faucet` wrote and the two registries cannot
desynchronize. The note therefore carries only the faucet id (2 felts).

- bridge_config.masm: new `deregister_faucet` proc reusing
  `assert_sender_is_bridge_admin`, `assert_faucet_registered`,
  `get_faucet_conversion_info`, and `hash_token_address`.
- components/bridge.masm: re-export `deregister_faucet`.
- note_scripts/deregister_agg_bridge.masm: new note script.
- src/deregister_note.rs: new `DeregisterAggBridgeNote` builder.
- bridge.rs: add the DEREGISTER script root to the network-account note allowlist.
- tests/agglayer/config_bridge.rs: round-trip test verifying all three maps are
  cleared, an end-to-end test proving the faucet is revoked, and negative tests for
  `ERR_FAUCET_NOT_REGISTERED` and `ERR_SENDER_NOT_BRIDGE_ADMIN`.
- SPEC.md, CHANGELOG.md: documentation updates.

Author: partylikeits1983

CHANGELOG.md

@@ -53,6 +53,7 @@
 - [BREAKING] Removed `AccountStorageMode::Network`; network accounts are now identified via `NetworkAccountNoteAllowlist` ([#2900](https://github.com/0xMiden/protocol/pull/2900)).
 - Added `PswapAttachment` scheme and `PswapNote::payback_note` / `remainder_note` discovery helpers so creators can reconstruct private paybacks from on-chain commitments ([#2909](https://github.com/0xMiden/protocol/pull/2909)).
 - Added benchmark for ECDSA signed transaction ([#2967](https://github.com/0xMiden/protocol/pull/2967)).
+- [agglayer] Added `bridge_config::deregister_faucet` MASM procedure, `DEREGISTER_AGG_BRIDGE` note script, and `DeregisterAggBridgeNote` Rust builder, enabling the bridge admin to revoke a faucet's authorization by clearing its `faucet_registry_map`, `token_registry_map`, and `faucet_metadata_map` entries. The token-registry key is recomputed from the faucet's stored metadata so the cleared key always matches what registration wrote, rather than trusting note-supplied values. `bridge_in::claim` now also re-checks `assert_faucet_registered` after the token lookup, making deregistration an unconditional revocation even if a stale token-registry key survives a re-registration ([#2838](https://github.com/0xMiden/protocol/pull/2838)).
 
 ### Changes
 

crates/miden-agglayer/SPEC.md

@@ -49,7 +49,7 @@ asset and the destination network/address. The bridge account consumes this note
 5. Computes the Keccak-256 leaf value and appends it to the Local Exit Tree (LET).
 6. Dispatches on the faucet's `is_native` flag (also read from the registry):
    - **Wrapped faucet (`is_native = false`):** the bridge does not hold the asset onchain; it
-     emits a public [`BURN`](#45-burn-generated) note targeting the faucet, which the faucet
+     emits a public [`BURN`](#46-burn-generated) note targeting the faucet, which the faucet
      consumes to burn the asset and decrement the faucet's token supply.
    - **Miden-native faucet (`is_native = true`):** the bridge does not hold mint/burn authority
      for the faucet, so it cannot emit a `BURN`. Instead it locks the asset by adding it to
@@ -81,12 +81,13 @@ The `CLAIM` note is consumed by the bridge account:
    `NEW_CGI = Keccak256(OLD_CGI, Keccak256(GLOBAL_INDEX, LEAF_VALUE))`.
 5. Checks and sets the claim nullifier to prevent double-claiming.
 6. Looks up the faucet from the `(origin_token_address, origin_network)` pair via the token
-   registry.
+   registry, then asserts the resolved faucet is still registered (`assert_faucet_registered`) so a
+   deregistered faucet reachable via a stale token key cannot mint.
 7. Verifies the claim amount against the leaf's U256 amount and the faucet's scale factor.
 8. Dispatches on the faucet's `is_native` flag:
-   - **Wrapped faucet (`is_native = false`):** the bridge emits a [`MINT`](#47-mint-generated)
+   - **Wrapped faucet (`is_native = false`):** the bridge emits a [`MINT`](#48-mint-generated)
      note targeting the faucet. The faucet consumes the `MINT` note, mints the specified amount,
-     and creates a [`P2ID`](#46-p2id-generated) note delivering the minted assets to the
+     and creates a [`P2ID`](#47-p2id-generated) note delivering the minted assets to the
      recipient's Miden account.
    - **Miden-native faucet (`is_native = true`):** the bridge cannot mint via the faucet, so
      it removes the asset from its own vault (`native_account::remove_asset`) and emits a
@@ -107,7 +108,7 @@ TODO: Claims cannot be reversed once the nullifier is set
 ![GER injection flow](diagrams/ger-injection.png)
 
 Global Exit Roots represent a snapshot of exit tree roots across all AggLayer-connected
-chains. A GER Manager observes L1 GER updates and creates [`UPDATE_GER`](#44-update_ger) notes
+chains. A GER Manager observes L1 GER updates and creates [`UPDATE_GER`](#45-update_ger) notes
 on Miden. The bridge consumes these notes:
 
 1. Asserts the note sender is the designated GER manager.
@@ -165,7 +166,7 @@ The bridge has two administrative roles set at account creation time:
 
 - **Bridge admin** (`admin_account_id`): authorizes faucet registration via
   [`CONFIG_AGG_BRIDGE`](#43-config_agg_bridge) notes.
-- **GER manager** (`ger_manager_account_id`): authorizes GER updates via [`UPDATE_GER`](#44-update_ger)
+- **GER manager** (`ger_manager_account_id`): authorizes GER updates via [`UPDATE_GER`](#45-update_ger)
   notes.
 
 Both roles are verified by checking the note sender against the stored account ID.
@@ -186,6 +187,7 @@ The bridge account has a single unified `bridge` component (`components/bridge.m
 which is a thin wrapper that re-exports procedures from the `agglayer` library modules:
 
 - `bridge_config::register_faucet`
+- `bridge_config::deregister_faucet`
 - `bridge_config::update_ger`
 - `bridge_in::claim`
 - `bridge_out::bridge_out`
@@ -234,6 +236,44 @@ Asserts the note sender matches the bridge admin stored in
    the address alone would let a CLAIM bound to one origin network resolve to the faucet of
    the same address on another network.
 
+#### `bridge_config::deregister_faucet`
+
+| | |
+|-|-|
+| **Invocation** | `call` |
+| **Inputs** | `[faucet_id_suffix, faucet_id_prefix, pad(14)]` |
+| **Outputs** | `[pad(16)]` |
+| **Context** | Consuming a `DEREGISTER_AGG_BRIDGE` note on the bridge account |
+| **Panics** | Note sender is not the bridge admin; faucet is not currently registered |
+
+Asserts the note sender matches the bridge admin stored in
+`agglayer::bridge::admin_account_id` and the faucet is currently registered (via
+`assert_faucet_registered`), then clears every entry `register_faucet` wrote for the faucet:
+
+1. Writes `[0, 0, faucet_id_suffix, faucet_id_prefix] -> [0, 0, 0, 0]` into the
+   `faucet_registry_map` map slot.
+2. Reads the faucet's registered `origin_token_addr` and `origin_network` back from
+   `faucet_metadata_map` (via `get_faucet_conversion_info`), byte-swaps `origin_network`, hashes
+   `origin_token_addr` (5 felts) concatenated with the swapped network using
+   `Poseidon2::hash_elements`, and writes `hash(origin_token_addr || origin_network) -> [0, 0, 0, 0]`
+   into the `token_registry_map` map slot. Reading the address/network from on-chain metadata
+   (rather than from the note) guarantees the cleared key is byte-identical to the one
+   `register_faucet` wrote for the faucet's current registration, so a note cannot direct the clear
+   at the wrong key. (Caveat: `register_faucet` does not clear a faucet's prior `token_registry`
+   key when the same faucet is re-registered under a different token identity, so a stale token key
+   can survive deregistration. That stale entry is inert: `claim` re-checks
+   `assert_faucet_registered` after the token lookup and `bridge_out` already does, so a
+   deregistered faucet can never mint or unlock through it. Deregistration is an unconditional
+   revocation.)
+3. Clears all four `faucet_metadata_map` sub-keys (origin-address lo/hi, network, scale, and
+   metadata hash lo/hi) for the faucet, so no stale conversion data is left behind.
+
+After deregistration, both `bridge_out` (which calls `assert_faucet_registered`)
+and `claim` (which calls `lookup_faucet_by_token_address`) will fail for any
+in-flight notes referencing the deregistered faucet. The bridge admin should
+warn users before deregistering a faucet that has unprocessed B2AGG or CLAIM
+notes in flight.
+
 #### `bridge_config::update_ger`
 
 | | |
@@ -287,7 +327,7 @@ Validates a bridge-in claim and creates a MINT note targeting the faucet:
 7. Verifies the `faucet_mint_amount` against the leaf data's U256 amount and the
    faucet's scale factor (via FPI to `agglayer_faucet::get_scale`), using
    `asset_conversion::verify_u256_to_native_amount_conversion`.
-8. Builds a MINT output note targeting the faucet (see [Section 4.7](#47-mint-generated)).
+8. Builds a MINT output note targeting the faucet (see [Section 4.8](#48-mint-generated)).
 
 #### Bridge Account Storage
 
@@ -598,7 +638,61 @@ two-step registration into `faucet_registry_map` and `token_registry_map`).
 | **Issuer** | Bridge admin only -- **enforced** by `bridge_config::register_faucet` procedure |
 | **Consumer** | Bridge account -- **enforced** via `NetworkAccountTarget` attachment |
 
-### 4.4 UPDATE_GER
+### 4.4 DEREGISTER_AGG_BRIDGE
+
+**Purpose:** Deregisters a faucet from the bridge's faucet and token registries.
+
+**`NoteHeader`**
+
+*`NoteMetadata`:*
+
+| Field | Value |
+|-------|-------|
+| `sender` | Bridge admin (sender authorization enforced by the bridge's `deregister_faucet` procedure) |
+| `note_type` | `NoteType::Public` |
+| `tag` | `NoteTag::default()` |
+| `attachment` | `NetworkAccountTarget` -- target is the bridge account; execution hint: Always |
+
+**`NoteDetails`**
+
+*`NoteAssets`:* None (empty).
+
+*`NoteRecipient`:*
+
+| Field | Value |
+|-------|-------|
+| `serial_num` | Random (`rng.draw_word()`) |
+| `script` | `deregister_agg_bridge.masm` |
+| `storage` | 2 felts -- the faucet id |
+
+**Storage layout (2 felts):**
+
+| Index | Field | Encoding |
+|-------|-------|----------|
+| 0 | `faucet_id_suffix` | Felt (AccountId suffix of the faucet to deregister) |
+| 1 | `faucet_id_prefix` | Felt (AccountId prefix of the faucet to deregister) |
+
+The origin token address and origin network are not carried by the note; the bridge reads them
+back from its own `faucet_metadata_map` when clearing the token registry.
+
+**Consumption:** Script validates attachment target, loads storage, and calls
+`bridge_config::deregister_faucet` (which asserts sender is bridge admin, asserts
+the faucet is currently registered, and clears the `faucet_registry_map`,
+`token_registry_map`, and `faucet_metadata_map` entries).
+
+After consumption, in-flight B2AGG / CLAIM notes referencing the deregistered
+faucet will fail their `assert_faucet_registered` / `lookup_faucet_by_token_address`
+checks. The bridge admin should drain or otherwise warn users about pending
+notes before sending a `DEREGISTER_AGG_BRIDGE`.
+
+#### Permissions
+
+| Role | Enforcement |
+|------|------------|
+| **Issuer** | Bridge admin only -- **enforced** by `bridge_config::deregister_faucet` procedure |
+| **Consumer** | Bridge account -- **enforced** via `NetworkAccountTarget` attachment |
+
+### 4.5 UPDATE_GER
 
 **Purpose:** Stores a new Global Exit Root (GER) in the bridge account so that subsequent
 CLAIM notes can be verified against it.
@@ -644,7 +738,7 @@ CLAIM notes can be verified against it.
 | **Issuer** | GER manager only -- **enforced** by `bridge_config::update_ger` procedure |
 | **Consumer** | Bridge account -- **enforced** via `NetworkAccountTarget` attachment |
 
-### 4.5 BURN (generated)
+### 4.6 BURN (generated)
 
 **Purpose:** Created by `bridge_out::bridge_out` to burn the bridged asset on the faucet.
 
@@ -688,7 +782,7 @@ decreases the faucet's total token supply by the burned amount.
 | **Issuer** | Bridge account (created by `bridge_out::bridge_out`) |
 | **Consumer** | Target faucet only -- **enforced** via `NetworkAccountTarget` attachment |
 
-### 4.6 P2ID (generated)
+### 4.7 P2ID (generated)
 
 **Purpose:** Created by the faucet (via `mint_and_send`) when consuming a MINT note, to
 deliver minted assets to the recipient.
@@ -736,7 +830,7 @@ script). All note assets are added to the consuming account via
 | **Issuer** | Faucet account (created by `mint_and_send`) |
 | **Consumer** | Destination account only -- **enforced** by P2ID script (checks `target_account_id`) |
 
-### 4.7 MINT (generated)
+### 4.8 MINT (generated)
 
 **Purpose:** Created by `bridge_in::claim` on the bridge account. Consumed by the faucet
 to mint and distribute assets to the recipient.
@@ -1111,6 +1205,19 @@ The bridge admin is a trusted role, and is the sole entity that can register fau
 the Miden side (enforced by the caller restriction on
 [`bridge_config::register_faucet`](#bridge_configregister_faucet)).
 
+The bridge admin can also revoke a faucet's authorization via a
+[`DEREGISTER_AGG_BRIDGE`](#44-deregister_agg_bridge) note, which carries only the faucet id and
+calls [`bridge_config::deregister_faucet`](#bridge_configderegister_faucet) to clear every entry
+the faucet's current registration wrote: the `faucet_registry_map`, `token_registry_map`, and
+`faucet_metadata_map`. The token-registry key is recomputed from the faucet's own stored metadata,
+so a note cannot direct the clear at the wrong key. Deregistration is an unconditional revocation:
+`claim` re-checks `assert_faucet_registered` after the token lookup, so even a stale token key left
+by a re-registration cannot mint through a deregistered faucet. This is useful for retiring
+compromised, broken, or deprecated faucets without redeploying the bridge. Note that
+in-flight `B2AGG` and `CLAIM` notes referencing the deregistered faucet will fail
+their existing registration checks after deregistration, so users should be warned
+before a deregistration is performed.
+
 #### Wrapped (`is_native = false`) vs Miden-native (`is_native = true`) faucets
 
 The difference between the two kinds is what they represent and how the bridge dispatches

crates/miden-agglayer/asm/agglayer/bridge/bridge_config.masm

@@ -42,6 +42,10 @@ const REG_SCALE_LOC = 6
 const REG_ORIGIN_NETWORK_LOC = 7
 const REG_IS_NATIVE_LOC = 8
 
+# Local memory slot offsets used inside the `deregister_faucet` procedure
+const DEREG_FAUCET_ID_SUFFIX_LOC = 0
+const DEREG_FAUCET_ID_PREFIX_LOC = 1
+
 # faucet_metadata_map sub-keys (used as the first element of the 4-felt KEY).
 # Each sub-key indexes a different word of metadata for a given faucet ID.
 const FAUCET_METADATA_SUBKEY_ADDR_LO = 0  # [addr0, addr1, addr2, addr3]
@@ -282,6 +286,122 @@ pub proc store_faucet_metadata_hash
     # => [pad(16)]
 end
 
+#! Deregisters a faucet, clearing every entry `register_faucet` wrote for it.
+#!
+#! Asserts the faucet is currently registered, then clears it from the `faucet_registry`,
+#! `token_registry`, and `faucet_metadata` maps. After this call, subsequent
+#! `assert_faucet_registered` and `lookup_faucet_by_token_address` calls panic, so any in-flight
+#! notes (B2AGG / CLAIM) targeting the deregistered faucet fail their existing registration checks.
+#!
+#! The origin token address and origin network are NOT taken from the note: they are read back
+#! from the faucet's own `faucet_metadata_map` entry (written by `register_faucet`) via
+#! `get_faucet_conversion_info`. This guarantees the `token_registry` key cleared here is exactly
+#! the one `register_faucet` wrote for this faucet's *current* registration, so a note cannot point
+#! the clear at the wrong key.
+#!
+#! Caveat: `register_faucet` does not clear a faucet's previous `token_registry` key when the same
+#! faucet ID is re-registered under a different (origin token address, origin network). Such a
+#! re-registered faucet therefore has a stale `token_registry` entry that this procedure does not
+#! reach (it only clears the key derived from the latest metadata). That stale entry is inert,
+#! however: `bridge_in::claim` re-checks `assert_faucet_registered` after the token lookup, and
+#! `bridge_out` already does, so a deregistered faucet can never mint or unlock even via a stale
+#! key. Deregistration is therefore an unconditional revocation of the faucet.
+#!
+#! 1. Writes `[0, 0, faucet_id_suffix, faucet_id_prefix] -> [0, 0, 0, 0]` into `faucet_registry`.
+#! 2. Writes `hash(tokenAddress[5] || origin_network) -> [0, 0, 0, 0]` into `token_registry`, where
+#!    the address/network come from `faucet_metadata` and origin_network is byte-swapped before
+#!    hashing (matching `register_faucet` Step 4 and `lookup_faucet_by_token_address`).
+#! 3. Clears all four `faucet_metadata` sub-keys (addr-lo, addr-hi/network/scale, hash-lo, hash-hi).
+#!
+#! Inputs:  [faucet_id_suffix, faucet_id_prefix, pad(14)]
+#! Outputs: [pad(16)]
+#!
+#! Panics if:
+#! - the note sender is not the bridge admin.
+#! - the faucet is not currently registered in the faucet registry.
+#!
+#! Invocation: call
+@locals(2)
+pub proc deregister_faucet
+    # assert the note sender is the bridge admin.
+    exec.assert_sender_is_bridge_admin
+    # => [faucet_id_suffix, faucet_id_prefix, pad(14)]
+
+    # Stash the faucet ID; it is needed for every map key below.
+    dup.0 loc_store.DEREG_FAUCET_ID_SUFFIX_LOC
+    dup.1 loc_store.DEREG_FAUCET_ID_PREFIX_LOC
+    # => [faucet_id_suffix, faucet_id_prefix, pad(14)]
+
+    # --- 1. Assert faucet is currently registered (consumes [suffix, prefix]) ---
+    exec.assert_faucet_registered
+    # => [pad(16)]
+
+    # --- 2. Clear token_registry ---
+    # Read the faucet's registered (origin_token_addr, origin_network) from faucet_metadata so the
+    # cleared key is provably the one register_faucet wrote. Drop the scale we don't need.
+    loc_load.DEREG_FAUCET_ID_PREFIX_LOC loc_load.DEREG_FAUCET_ID_SUFFIX_LOC
+    exec.get_faucet_conversion_info
+    # => [origin_token_addr(5), origin_network, scale, pad(8)]
+
+    movup.6 drop
+    # => [origin_token_addr(5), origin_network, pad(9)]
+
+    # Byte-swap origin_network so the hash input matches register_faucet's convention
+    # (`claim_note.rs` LE-packs the leaf's origin_network felt).
+    movup.5 exec.utils::swap_u32_bytes movdn.5
+    # => [origin_token_addr(5), origin_network_swapped, pad(9)]
+
+    exec.hash_token_address
+    # => [TOKEN_ADDR_HASH, pad(12)]
+
+    push.0.0.0.0 swapw
+    # => [TOKEN_ADDR_HASH, 0, 0, 0, 0, pad(12)]
+
+    push.TOKEN_REGISTRY_MAP_SLOT[0..2]
+    exec.native_account::set_map_item
+    dropw
+    # => [pad(16)]
+
+    # --- 3. Clear faucet_registry: KEY=[0,0,suffix,prefix], VALUE=[0,0,0,0] ---
+    push.0.0.0.0
+    loc_load.DEREG_FAUCET_ID_PREFIX_LOC loc_load.DEREG_FAUCET_ID_SUFFIX_LOC push.0.0
+    # => [[0, 0, suffix, prefix], [0, 0, 0, 0], pad(16)]
+    push.FAUCET_REGISTRY_MAP_SLOT[0..2]
+    exec.native_account::set_map_item
+    dropw
+    # => [pad(16)]
+
+    # --- 4. Clear all four faucet_metadata sub-keys for this faucet ---
+    # Each sub-key KEY = [sub_key, 0, suffix, prefix] is cleared to VALUE = [0, 0, 0, 0].
+    push.0.0.0.0
+    loc_load.DEREG_FAUCET_ID_PREFIX_LOC loc_load.DEREG_FAUCET_ID_SUFFIX_LOC push.0.FAUCET_METADATA_SUBKEY_ADDR_LO
+    push.FAUCET_METADATA_MAP_SLOT[0..2]
+    exec.native_account::set_map_item
+    dropw
+    # => [pad(16)]
+
+    push.0.0.0.0
+    loc_load.DEREG_FAUCET_ID_PREFIX_LOC loc_load.DEREG_FAUCET_ID_SUFFIX_LOC push.0.FAUCET_METADATA_SUBKEY_ADDR_HI
+    push.FAUCET_METADATA_MAP_SLOT[0..2]
+    exec.native_account::set_map_item
+    dropw
+    # => [pad(16)]
+
+    push.0.0.0.0
+    loc_load.DEREG_FAUCET_ID_PREFIX_LOC loc_load.DEREG_FAUCET_ID_SUFFIX_LOC push.0.FAUCET_METADATA_SUBKEY_HASH_LO
+    push.FAUCET_METADATA_MAP_SLOT[0..2]
+    exec.native_account::set_map_item
+    dropw
+    # => [pad(16)]
+
+    push.0.0.0.0
+    loc_load.DEREG_FAUCET_ID_PREFIX_LOC loc_load.DEREG_FAUCET_ID_SUFFIX_LOC push.0.FAUCET_METADATA_SUBKEY_HASH_HI
+    push.FAUCET_METADATA_MAP_SLOT[0..2]
+    exec.native_account::set_map_item
+    dropw
+    # => [pad(16)]
+end
+
 #! Asserts that a faucet is registered in the bridge's faucet registry.
 #!
 #! Looks up the faucet ID in the faucet registry map and asserts the registration flag is set.

crates/miden-agglayer/asm/agglayer/bridge/bridge_in.masm

@@ -212,6 +212,14 @@ pub proc claim
     exec.bridge_config::lookup_faucet_by_token_address
     # => [faucet_id_suffix, faucet_id_prefix, pad(16)]
 
+    # Assert the resolved faucet is still registered. `lookup_faucet_by_token_address` only proves
+    # the token route exists, but a faucet that was re-registered under a different token identity
+    # and then deregistered can leave a stale `token_registry` key pointing at it (`register_faucet`
+    # does not clear the prior key). Re-checking `faucet_registry` here makes deregistration an
+    # unconditional revocation: a deregistered faucet can never mint or unlock through CLAIM.
+    dup.1 dup.1 exec.bridge_config::assert_faucet_registered
+    # => [faucet_id_suffix, faucet_id_prefix, pad(16)]
+
     dup.1 dup.1
     # => [faucet_id_suffix, faucet_id_prefix, faucet_id_suffix, faucet_id_prefix, pad(16)]