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: AuthenticatorConfig, ) -> Result<Authenticator, AuthenticatorError>

Initialize an Authenticator from a seed and config.

This method will error if the World ID account does not exist on the registry.

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 error if the account does not exist (AccountDoesNotExist).

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: AuthenticatorConfig, 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: AuthenticatorConfig, 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 refresh_packed_account_data( &self, ) -> Result<Uint<256, 4>, AuthenticatorError>

Re-fetches the packed account data for this authenticator from the indexer or registry.

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#3}::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

TODO: After successfully inserting an authenticator, the packed_account_data should be refreshed from the registry to reflect the new pubkey_id commitment.

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

TODO: After successfully updating an authenticator, the packed_account_data should be refreshed from the registry to reflect the new pubkey_id commitment.

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

TODO: After successfully removing an authenticator, the packed_account_data should be refreshed from the registry to reflect the new pubkey_id commitment.

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 a SessionId object which can be used for Session Proofs. This has two uses:

1. Creating a new Sesssion, 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 generates the session’s random seed (r) using OPRF Nodes. This seed is used to compute the SessionId::commitment for Session Proofs.

Arguments

• proof_request: the request received from the RP to initialize 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 SessionId to be shared with the requesting RP.
• 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.

impl Authenticator

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

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 execute_recovery_agent_update( &self, ) -> Result<GatewayRequestId, AuthenticatorError>

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>

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.

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.