Struct Authenticator 

pub struct Authenticator {
    pub config: Config,
    pub packed_account_data: Uint<256, 4>,
    /* private fields */
}

An Authenticator is the agent of a user interacting with the World ID Protocol.

Definition

A software or hardware agent (e.g., app, device, web client, or service) that controls a set of authorized keypairs for a World ID Account and is functionally capable of interacting with the Protocol, and is therefore permitted to act on that account’s behalf. An Authenticator is the agent of users/holders. Each Authenticator is registered in the WorldIDRegistry through their authorized keypairs.

For example, an Authenticator can live in a mobile wallet or a web application.

Fields

config: Config

General configuration for the Authenticator.

packed_account_data: Uint<256, 4>

The packed account data for the holder’s World ID is a uint256 defined in the WorldIDRegistry contract as: recovery_counter (32 bits) | pubkey_id (commitment to all off-chain public keys) (32 bits) | leaf_index (192 bits)

Implementations

impl Authenticator

pub async fn init( seed: &[u8], config: Config, ) -> Result<Authenticator, AuthenticatorError>

Initialize an Authenticator from a seed and config.

This method requires the authenticator address derived from seed to already be present on-chain in the WorldIDRegistry.

If no account exists for that authenticator, it returns AuthenticatorError::AccountDoesNotExist. The same error can also occur transiently while a create-account or authenticator-management operation is still pending on-chain and the authenticator address has not been registered yet. Consumers that are coordinating such operations should poll the gateway request and retry initialization after finalization.

Indexer DB catch-up is separate and does not block initialization, since packed account data is read from the registry (directly or via the indexer’s chain-backed packed-account endpoint).

Errors

• Will error if the provided seed is invalid (not 32 bytes).
• Will error if the RPC URL is invalid.
• Will error if there are contract call failures.
• Will return AuthenticatorError::AccountDoesNotExist if the authenticator address derived from seed is not currently registered on-chain, whether permanently or because a relevant on-chain operation has not finalized yet.

pub fn with_proof_materials( self, query_material: Arc<CircomGroth16Material>, nullifier_material: Arc<CircomGroth16Material>, ) -> Authenticator

Sets the proof materials for the Authenticator, returning a new instance.

Proof materials are required for proof generation, blinding factors and starting sessions. Given the proof circuits are large, this may be loaded only when necessary.

pub async fn register( seed: &[u8], config: Config, recovery_address: Option<Address>, ) -> Result<InitializingAuthenticator, AuthenticatorError>

Registers a new World ID in the WorldIDRegistry.

Given the registration process is asynchronous, this method will return a InitializingAuthenticator object.

Errors

• See init for additional error details.

pub async fn init_or_register( seed: &[u8], config: Config, recovery_address: Option<Address>, ) -> Result<Authenticator, AuthenticatorError>

Initializes (if the World ID already exists in the registry) or registers a new World ID.

The registration process is asynchronous and may take some time. This method will block the thread until the registration is in a final state (success or terminal error). For better user experience in end authenticator clients, it is recommended to implement custom polling logic.

Explicit init or register calls are also recommended as the authenticator should know if a new World ID should be truly created. For example, an authenticator may have been revoked access to an existing World ID.

Errors

• See init for additional error details.

pub async fn fetch_packed_account_data( &self, ) -> Result<Uint<256, 4>, AuthenticatorError>

Fetches the packed account data for this authenticator from the indexer or registry without mutating local state.

Errors

Will error if the network call fails or if the account does not exist.

pub async fn refresh_packed_account_data( &mut self, ) -> Result<Uint<256, 4>, AuthenticatorError>

Re-fetches the packed account data for this authenticator and updates local state.

Errors

Will error if the network call fails or if the account does not exist.

pub const fn onchain_address(&self) -> Address

Returns the k256 public key of the Authenticator signer which is used to verify on-chain operations, chiefly with the WorldIdRegistry contract.

pub fn offchain_pubkey(&self) -> EdDSAPublicKey

Returns the EdDSA public key of the Authenticator signer which is used to verify off-chain operations. For example, the Nullifier Oracle uses it to verify requests for nullifiers.

pub fn offchain_pubkey_compressed( &self, ) -> Result<Uint<256, 4>, AuthenticatorError>

Returns the compressed EdDSA public key of the Authenticator signer which is used to verify off-chain operations. For example, the Nullifier Oracle uses it to verify requests for nullifiers.

Errors

Will error if the public key cannot be serialized.

pub fn registry(&self) -> Option<Arc<WorldIdRegistryInstance<DynProvider>>>

Returns a reference to the WorldIdRegistry contract instance.

pub fn leaf_index(&self) -> u64

Returns the index for the holder’s World ID.

Definition

The leaf_index is the main (internal) identifier of a World ID. It is registered in the WorldIDRegistry and represents the index at the Merkle tree where the World ID resides.

Notes

• The leaf_index is used as input in the nullifier generation, ensuring a nullifier will always be the same for the same RP context and the same World ID (allowing for uniqueness).
• The leaf_index is generally not exposed outside Authenticators. It is not a secret because it’s not exposed to RPs outside ZK-circuits, but the only acceptable exposure outside an Authenticator is to fetch Merkle inclusion proofs from an indexer or it may create a pseudonymous identifier.
• The leaf_index is stored as a uint64 inside packed account data.

pub fn recovery_counter(&self) -> Uint<256, 4>

Returns the recovery counter for the holder’s World ID.

The recovery counter is used to efficiently invalidate all the old keys when an account is recovered.

pub fn pubkey_id(&self) -> Uint<256, 4>

Returns the pubkey id (or commitment) for the holder’s World ID.

This is a commitment to all the off-chain public keys that are authorized to act on behalf of the holder.

pub async fn fetch_inclusion_proof( &self, ) -> Result<AccountInclusionProof<world_id_authenticator::::authenticator::{impl#1}::fetch_inclusion_proof::{constant#1}>, AuthenticatorError>

Fetches a Merkle inclusion proof for the holder’s World ID given their account index.

Errors

• Will error if the provided indexer URL is not valid or if there are HTTP call failures.
• Will error if the user is not registered on the WorldIDRegistry.

pub async fn fetch_authenticator_pubkeys( &self, ) -> Result<AuthenticatorPublicKeySet, AuthenticatorError>

Fetches the current authenticator public key set for the account.

This is used by mutation operations to compute old/new offchain signer commitments without requiring Merkle proof generation.

Errors

• Will error if the provided indexer URL is not valid or if there are HTTP call failures.
• Will error if the user is not registered on the WorldIDRegistry.

pub async fn signing_nonce(&self) -> Result<Uint<256, 4>, AuthenticatorError>

Returns the signing nonce for the holder’s World ID.

Errors

Will return an error if the registry contract call fails.

pub fn danger_sign_challenge( &self, challenge: &[u8], ) -> Result<Signature, AuthenticatorError>

Signs an arbitrary challenge with the authenticator’s on-chain key following ERC-191.

Warning

This is considered a dangerous operation because it leaks the user’s on-chain key, hence its leaf_index. The only acceptable use is to prove the user’s leaf_index to a Recovery Agent. The Recovery Agent is the only party beyond the user who needs to know the leaf_index.

Use

• This method is used to prove ownership over a leaf index only for Recovery Agents.

impl Authenticator

pub async fn insert_authenticator( &self, new_authenticator_pubkey: EdDSAPublicKey, new_authenticator_address: Address, ) -> Result<GatewayRequestId, AuthenticatorError>

Inserts a new authenticator to the account.

Errors

Will error if the provided RPC URL is not valid or if there are HTTP call failures.

Note

Inserting another authenticator changes the account’s off-chain signer commitment, but does not change this authenticator’s own packed_account_data. Indexer-backed account views may remain stale until the gateway request finalizes and the indexer catches up.

pub async fn update_authenticator( &self, old_authenticator_address: Address, new_authenticator_address: Address, new_authenticator_pubkey: EdDSAPublicKey, index: u32, ) -> Result<GatewayRequestId, AuthenticatorError>

Updates an existing authenticator slot with a new authenticator.

Errors

Returns an error if the gateway rejects the request or a network error occurs.

Note

After this request finalizes on-chain, the current Authenticator may become unusable if it corresponds to the authenticator being updated. Consumers should poll the gateway request and re-initialize the appropriate authenticator as needed.

pub async fn remove_authenticator( &self, authenticator_address: Address, index: u32, ) -> Result<GatewayRequestId, AuthenticatorError>

Removes an authenticator from the account.

Errors

Returns an error if the gateway rejects the request or a network error occurs.

Note

After this request finalizes on-chain, the current Authenticator may become unusable if it corresponds to the authenticator being removed. Consumers should poll the gateway request and re-initialize or discard this authenticator as needed.

pub async fn poll_status( &self, request_id: &GatewayRequestId, ) -> Result<GatewayRequestState, AuthenticatorError>

Polls the gateway for the current status of a previously submitted request.

Use the GatewayRequestId returned by insert_authenticator, update_authenticator, or remove_authenticator to track the operation.

Errors

• Will error if the network request fails.
• Will error if the gateway returns an error response (e.g. request not found).

impl Authenticator

pub async fn generate_nullifier( &self, proof_request: &ProofRequest, account_inclusion_proof: Option<AccountInclusionProof<world_id_authenticator::::prove::{impl#0}::generate_nullifier::{constant#0}>>, ) -> Result<FullOprfOutput, AuthenticatorError>

Generates a nullifier for a World ID Proof (through OPRF Nodes).

A Nullifier is a unique, one-time use, anonymous identifier for a World ID on a specific RP context. See Nullifier for more details.

Arguments

• proof_request: the request received from the RP.
• account_inclusion_proof: an optionally cached object can be passed to avoid an additional network call. If not passed, it’ll be fetched from the indexer.

A Nullifier takes an action as input:

• If proof_request is for a Session Proof, a random internal action is generated. This is opaque to RPs, and verified internally in the verification contract.
• If proof_request is for a Uniqueness Proof, the action is provided by the RP, if not provided a default of FieldElement::ZERO is used.

Errors

• Will raise a ProofError if there is any issue generating the nullifier. For example, network issues, unexpected incorrect responses from OPRF Nodes.
• Raises an error if the OPRF Nodes configuration is not correctly set.

pub async fn generate_credential_blinding_factor( &self, issuer_schema_id: u64, ) -> Result<FieldElement, AuthenticatorError>

Generates a blinding factor for a Credential sub (through OPRF Nodes). The credential blinding factor enables every credential to have a different subject identifier, see Credential::sub for more details.

Errors

• Will raise a ProofError if there is any issue generating the blinding factor. For example, network issues, unexpected incorrect responses from OPRF Nodes.
• Raises an error if the OPRF Nodes configuration is not correctly set.

pub async fn build_session_id( &self, proof_request: &ProofRequest, session_id_r_seed: Option<FieldElement>, account_inclusion_proof: Option<AccountInclusionProof<world_id_authenticator::::prove::{impl#0}::build_session_id::{constant#0}>>, ) -> Result<(SessionId, FieldElement), AuthenticatorError>

Builds or resolves a SessionId object which can be used for Session Proofs. This has two uses:

1. Creating a new Session, i.e. generating a SessionId for the first time.
2. Reconstructing a session for a Session Proof, particularly if the session_id_r_seed is not cached.

Internally, this derives the session randomness (r) using OPRF Nodes. For existing sessions this re-derives the same r from SessionId::oprf_seed; it does not mint a new session. The seed is used to compute the SessionId::commitment for Session Proofs.

Arguments

• proof_request: the request received from the RP to create or prove a session id.
• session_id_r_seed: the seed (see below) if it was already generated previously and it’s cached.
• account_inclusion_proof: an optionally cached object can be passed to avoid an additional network call. If not passed, it’ll be fetched from the indexer.

Returns

• session_id: The generated or resolved SessionId.
• session_id_r_seed: The r value used for this session so the Authenticator can cache it.

Seed (session_id_r_seed)

• If a session_id_r_seed (r) is not provided, it’ll be derived/re-derived with the OPRF nodes.
• Even if r has been generated before, the same r will be computed again for the same context (i.e. rpId, SessionId::oprf_seed). This means caching r is optional but RECOMMENDED.
• Caching behavior is the responsibility of the Authenticator (and/or its relevant SDKs), not this crate.
• More information about the seed can be found in SessionId::from_r_seed.

pub async fn generate_proof( &self, proof_request: &ProofRequest, nullifier: FullOprfOutput, credentials: &[CredentialInput], account_inclusion_proof: Option<AccountInclusionProof<world_id_authenticator::::prove::{impl#0}::generate_proof::{constant#0}>>, session_id_r_seed: Option<FieldElement>, ) -> Result<ProofResult, AuthenticatorError>

Generates a complete ProofResponse for the given ProofRequest to respond to an RP request.

This orchestrates session resolution, per-credential proof generation, response assembly, and self-validation.

Typical flow

// <- check request can be fulfilled with available credentials
let nullifier = authenticator.generate_nullifier(&request, None).await?;
// <- check replay guard using nullifier.oprf_output()
let (response, meta) = authenticator.generate_proof(&request, nullifier, &creds, ...).await?;
// <- cache `session_id_r_seed` (to speed future proofs) and `nullifier` (to prevent replays)

Arguments

• proof_request — the RP’s full request.
• nullifier — the OPRF nullifier output, obtained from generate_nullifier. The caller MUST check for replays before calling this method to avoid wasted computation.
• credentials — one CredentialInput per credential to prove, matched to request items by issuer_schema_id.
• account_inclusion_proof — a cached inclusion proof if available (a fresh one will be fetched otherwise)
• session_id_r_seed — a cached session r seed for Session Proofs. If not available, it will be re-computed.

Caller Responsibilities

1. The caller must ensure the request can be fulfilled with the credentials which the user has available, and provide such credentials.
2. The caller must ensure the nullifier has not been used before.

Errors

• AuthenticatorError::UnfullfilableRequest if the provided credentials cannot satisfy the request (including constraints).
• Other AuthenticatorError variants on proof circuit or validation failures.

pub async fn prove_credential_sub( &self, nonce: FieldElement, credential_blinding_factor: FieldElement, sub: FieldElement, account_inclusion_proof: Option<AccountInclusionProof<world_id_authenticator::::prove::{impl#0}::prove_credential_sub::{constant#0}>>, ) -> Result<OwnershipProof, AuthenticatorError>

Generates an Ownership Proof (WIP-103) over a Credential’s sub.

This proof MUST only be shared with each relevant issuer. This is the responsibility of Authenticators.

Arguments

• nonce: The nonce of the request provided by the Issuer.
• credential_blinding_factor: The blinding factor generated for the credential.
• sub: The expected sub of the Credential in question.
• account_inclusion_proof: An optionally cached account inclusion proof. If not provided, a new inclusion proof will be fetched.

Returns

The OwnershipProof containing the ZKP and Merkle root.

impl Authenticator

pub async fn initiate_recovery_agent_update( &self, new_recovery_agent: Address, ) -> Result<GatewayRequestId, AuthenticatorError>

👎Deprecated:

WIP-102: use update_recovery_agent. The legacy URL still works against a V2-upgraded gateway, but the V2 contract changes the agent immediately (with a revert window) instead of starting a cooldown.

Initiates a recovery agent update for the holder’s World ID.

This begins a time-locked process to change the recovery agent. The update must be executed after a cooldown period using execute_recovery_agent_update, or it can be cancelled using cancel_recovery_agent_update.

Errors

Returns an error if the gateway rejects the request or a network error occurs.

pub async fn danger_sign_initiate_recovery_agent_update( &self, new_recovery_agent: Address, ) -> Result<(Signature, Uint<256, 4>), AuthenticatorError>

Signs the EIP-712 InitiateRecoveryAgentUpdate payload and returns the signature without submitting anything to the gateway.

This is the signing-only counterpart of Self::initiate_recovery_agent_update. Callers can use the returned signature to build and submit the gateway request themselves.

Warning

This method uses the onchain_signer (secp256k1 ECDSA) and produces a recoverable signature. Any holder of the signature together with the EIP-712 parameters can call ecrecover to obtain the onchain_address, which can then be looked up in the registry to derive the user’s leaf_index. Only expose the output to trusted parties (e.g. a Recovery Agent).

Errors

Returns an error if the nonce fetch or signing step fails.

pub async fn update_recovery_agent( &self, new_recovery_agent: Address, ) -> Result<GatewayRequestId, AuthenticatorError>

Updates the holder’s recovery agent (WIP-102).

On a V2 registry the new agent becomes effective immediately, but for a revert window (getRecoveryAgentUpdateCooldown seconds) any authenticator can call Self::revert_recovery_agent_update to roll back. During that window the previous agent remains the only valid signer for recoverAccount, which mitigates a compromised authenticator silently swapping in an attacker-controlled recovery address.

Errors

Returns an error if the gateway rejects the request or a network error occurs.

pub async fn execute_recovery_agent_update( &self, ) -> Result<GatewayRequestId, AuthenticatorError>

👎Deprecated:

WIP-102: this operation no longer exists. On a V2-upgraded gateway the call is a no-op (returns Finalized without touching chain). Remove the call from your flow.

Executes a pending recovery agent update for the holder’s World ID.

This is a permissionless operation that can be called by anyone after the cooldown period has elapsed. No signature is required.

Errors

Returns an error if the gateway rejects the request or a network error occurs.

pub async fn cancel_recovery_agent_update( &self, ) -> Result<GatewayRequestId, AuthenticatorError>

👎Deprecated:

WIP-102: use revert_recovery_agent_update. The legacy URL still works against a V2-upgraded gateway, but the new method name reflects WIP-102 semantics: the operation can only succeed within the revert window after update_recovery_agent.

Cancels a pending recovery agent update for the holder’s World ID.

Errors

Returns an error if the gateway rejects the request or a network error occurs.

pub async fn revert_recovery_agent_update( &self, ) -> Result<GatewayRequestId, AuthenticatorError>

Reverts an in-flight recovery agent update during the revert window (WIP-102).

Errors

Returns an error if the gateway rejects the request or a network error occurs.

Trait Implementations

impl Debug for Authenticator

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl ProtocolSigner for Authenticator

fn sign(&self, message: FieldElement) -> EdDSASignature

Signs a message with the protocol signer using the EdDSA scheme (off-chain signer), for use with the Protocol ZK circuits.