feat(standards): add guardian component

CHANGELOG.md

@@ -23,6 +23,7 @@
 - [BREAKING] Removed `AuthMethod` enum, `AccountAuthComponent` / `AccountAuthScheme`, and the `AccessControl::AuthControlled` variant. Faucet and wallet factories now take concrete auth-component types so invalid configurations are rejected at compile time ([#2944](https://github.com/0xMiden/protocol/pull/2944)).
 - [BREAKING] Split `create_fungible_faucet` into `create_user_fungible_faucet(auth_component: AuthSingleSigAcl, ...)` (installs `Authority::AuthControlled` directly) and the opinionated `create_network_fungible_faucet(access_control, ...)` (always `AccountType::Public`, builds the `AuthNetworkAccount` allowlist internally from `MintNote` + `BurnNote` script roots with an empty tx-script allowlist). Other auth schemes / shapes are no longer supported through these helpers — fall back to `AccountBuilder` directly. A `user_faucet_single_sig_acl` testing helper is provided behind the `testing` feature ([#2944](https://github.com/0xMiden/protocol/pull/2944)).
 - Added `create_multisig_wallet` and `create_guarded_wallet` helpers for `BasicWallet` accounts authenticated by `AuthMultisig` and `AuthGuardedMultisig` respectively ([#2944](https://github.com/0xMiden/protocol/pull/2944)).
+- Added a standalone `Guardian` account component storing a single guardian account ID, with `get_guardian` / `set_guardian` procedures and `is_sender_guardian` / `assert_sender_is_guardian` authorization primitives ([#3125](https://github.com/0xMiden/protocol/pull/3125)).
 - [BREAKING] `create_basic_wallet` now takes `AuthSingleSig` directly and returns `AccountError` instead of the removed `BasicWalletError` ([#2944](https://github.com/0xMiden/protocol/pull/2944)).
 - [BREAKING] Removed `AccountInterface::auth()` and `AccountComponentInterface::auth_scheme()`. Auth components are now discovered via `AccountInterface::auth_components()`, which iterates `AccountComponentInterface` variants flagged by `is_auth_component()` ([#2944](https://github.com/0xMiden/protocol/pull/2944)).
 - [BREAKING] `FungibleFaucet` no longer installs the `is_paused` storage slot itself. Faucet factories (`create_user_fungible_faucet` / `create_network_fungible_faucet`) now bundle the `Pausable` component (slot + `is_paused()` view procedure) alongside `PausableManager`. Callers using `AccountBuilder` directly must also install `Pausable` or the faucet's mint / burn / transfer / metadata-setter procedures will panic at runtime ([#2944](https://github.com/0xMiden/protocol/pull/2944)).

crates/miden-protocol/asm/shared_modules/account_id.masm

@@ -39,6 +39,23 @@ pub proc is_equal
     # => [is_id_equal]
 end
 
+#! Returns a boolean indicating whether the given account ID is the zero address `(0, 0)`, without
+#! consuming the ID.
+#!
+#! The zero address is not a valid account ID, so this can be used to detect an unassigned or
+#! cleared account ID.
+#!
+#! Inputs:  [account_id_suffix, account_id_prefix]
+#! Outputs: [is_zero, account_id_suffix, account_id_prefix]
+#!
+#! Where:
+#! - account_id_{suffix,prefix} are the suffix and prefix felts of the account ID.
+#! - is_zero is a boolean indicating whether the account ID is the zero address.
+pub proc testz
+    dup.1 eq.0 dup.1 eq.0 and
+    # => [is_zero, account_id_suffix, account_id_prefix]
+end
+
 #! Validates an account ID.
 #!
 #! Note that this does not validate anything about the account type, since any 1-bit pattern is a

crates/miden-standards/asm/account_components/access/guardian.masm

@@ -0,0 +1,6 @@
+# The MASM code of the Guardian Account Component.
+#
+# See the `Guardian` Rust type's documentation for more details.
+
+pub use ::miden::standards::access::guardian::get_guardian
+pub use ::miden::standards::access::guardian::set_guardian

crates/miden-standards/asm/standards/access/guardian.masm

@@ -0,0 +1,182 @@
+# miden::standards::access::guardian
+#
+# Provides a standalone "guardian" actor for account components: a single guardian account ID
+# stored in one value slot, and account-ID equality authorization primitives.
+#
+# The guardian is a second privileged actor, distinct from the owner, intended as a safety brake:
+# other components consult `assert_sender_is_guardian` / `is_sender_guardian` to authorize
+# some actions (e.g. an emergency freeze, or cancelling a scheduled operation). The guardian
+# can never grant roles, move assets, or perform owner-only actions. It is purely an authorization
+# subject checked by the procedures that opt into it.
+#
+# Authorization is a plain account-ID equality check, so this component needs no RBAC
+# infrastructure and behaves the same across all authority modes. If no guardian is assigned the
+# stored ID is the zero address `(0, 0)`, and the equality check returns 0 for every real sender,
+# yielding "no guardian => nobody passes the guardian check" for free.
+#
+# Storage layout (single slot):
+#   Word:  [guardian_suffix, guardian_prefix, 0, 0]
+
+use miden::protocol::active_account
+use miden::protocol::account_id
+use miden::protocol::active_note
+use miden::protocol::native_account
+use miden::standards::access::authority
+
+# CONSTANTS
+# ================================================================================================
+
+# The slot in this component's storage layout where the guardian account ID is stored.
+const GUARDIAN_SLOT = word("miden::standards::access::guardian::guardian_id")
+
+# ERRORS
+# ================================================================================================
+
+const ERR_SENDER_NOT_GUARDIAN = "note sender is not the guardian"
+
+# INTERNAL PROCEDURES
+# ================================================================================================
+
+#! Returns the guardian account ID from storage.
+#!
+#! Inputs:  []
+#! Outputs: [guardian_suffix, guardian_prefix]
+#!
+#! Where:
+#! - guardian_{suffix, prefix} are the suffix and prefix felts of the guardian account ID. Both
+#!   are zero if no guardian is assigned.
+proc get_guardian_internal
+    push.GUARDIAN_SLOT[0..2] exec.active_account::get_item
+    # => [guardian_suffix, guardian_prefix, 0, 0]
+
+    movup.2 drop movup.2 drop
+    # => [guardian_suffix, guardian_prefix]
+end
+
+#! Builds the guardian word, writes it to storage and drops the old value.
+#!
+#! Inputs:  [guardian_suffix, guardian_prefix]
+#! Outputs: []
+proc save_guardian_info
+    push.0.0 movup.3 movup.3
+    # => [guardian_suffix, guardian_prefix, 0, 0]
+
+    push.GUARDIAN_SLOT[0..2]
+    # => [slot_suffix, slot_prefix, guardian_suffix, guardian_prefix, 0, 0]
+
+    exec.native_account::set_item
+    # => [OLD_GUARDIAN_WORD]
+
+    dropw
+    # => []
+end
+
+#! Checks if the given account ID is the guardian.
+#!
+#! Inputs:  [account_id_suffix, account_id_prefix]
+#! Outputs: [is_guardian]
+#!
+#! Where:
+#! - account_id_{suffix, prefix} are the suffix and prefix felts of the account ID to check.
+#! - is_guardian is 1 if the account is the guardian, 0 otherwise.
+proc is_guardian_internal
+    exec.get_guardian_internal
+    # => [guardian_suffix, guardian_prefix, account_id_suffix, account_id_prefix]
+
+    exec.account_id::is_equal
+    # => [is_guardian]
+end
+
+# PUBLIC INTERFACE
+# ================================================================================================
+
+#! Returns 1 if the note sender is the guardian, otherwise 0.
+#!
+#! Inputs:  []
+#! Outputs: [is_sender_guardian]
+#!
+#! Where:
+#! - is_sender_guardian is 1 if the note sender is the guardian, otherwise 0.
+#!
+#! Invocation: exec
+pub proc is_sender_guardian
+    exec.active_note::get_sender
+    # => [sender_suffix, sender_prefix]
+
+    exec.is_guardian_internal
+    # => [is_sender_guardian]
+end
+
+#! Asserts that the note sender is the guardian.
+#!
+#! Inputs:  []
+#! Outputs: []
+#!
+#! Panics if:
+#! - the note sender is not the guardian.
+#!
+#! Invocation: exec
+pub proc assert_sender_is_guardian
+    exec.is_sender_guardian
+    # => [is_sender_guardian]
+
+    assert.err=ERR_SENDER_NOT_GUARDIAN
+    # => []
+end
+
+#! Returns the guardian account ID.
+#!
+#! Inputs:  [pad(16)]
+#! Outputs: [guardian_suffix, guardian_prefix, pad(14)]
+#!
+#! Where:
+#! - guardian_{suffix, prefix} are the suffix and prefix felts of the guardian account ID. Both
+#!   are zero if no guardian is assigned.
+#!
+#! Invocation: call
+pub proc get_guardian
+    exec.get_guardian_internal
+    # => [guardian_suffix, guardian_prefix, pad(16)]
+
+    movup.2 drop movup.2 drop
+    # => [guardian_suffix, guardian_prefix, pad(14)]
+end
+
+#! Sets or clears the guardian account ID.
+#!
+#! Authorized through `authority::assert_authorized`, so the gate is mode-aware. The owner under
+#! `OwnerControlled`, the configured role (or the owner fallback) under `RbacControlled`, and the
+#! account's auth component under `AuthControlled`. Requires the [`Authority`] component to be
+#! installed on the account.
+#!
+#! Clearing behaviour:
+#! - If `new_guardian` is the zero address `(0, 0)`, the guardian is cleared. The zero address is
+#!   treated as a clear value and is not validated as an account ID.
+#! - Otherwise, `new_guardian` is validated and stored as the guardian.
+#!
+#! Inputs:  [new_guardian_suffix, new_guardian_prefix, pad(14)]
+#! Outputs: [pad(16)]
+#!
+#! Panics if:
+#! - the sender is not authorized.
+#! - new_guardian is non-zero and the account ID is invalid.
+#!
+#! Invocation: call
+pub proc set_guardian
+    exec.authority::assert_authorized
+    # => [new_guardian_suffix, new_guardian_prefix, pad(14)]
+
+    # Detect explicit clear via the zero address. The zero address is not a valid account ID, so
+    # we must check for it before validating.
+    exec.account_id::testz
+    # => [is_zero_address, new_guardian_suffix, new_guardian_prefix, pad(14)]
+
+    if.false
+        # Non-zero new guardian: validate before storing.
+        dup.1 dup.1 exec.account_id::validate
+    end
+    # => [new_guardian_suffix, new_guardian_prefix, pad(14)]
+
+    exec.save_guardian_info
+    # => [pad(16)]
+end