Struct Authenticator 

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

An Authenticator is the base layer with which a user interacts with the Protocol.

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 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: 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 get_packed_account_data( onchain_signer_address: Address, registry: Option<&WorldIdRegistryInstance<DynProvider>>, config: &Config, http_client: &Client, ) -> Result<Uint<256, 4>, AuthenticatorError>

Returns the packed account data for the holder’s World ID.

The packed account data is a 256 bit integer which includes the World ID’s leaf index, their recovery counter, and their pubkey id/commitment.

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<(MerkleInclusionProof<world_id_authenticator::::authenticator::{impl#1}::fetch_inclusion_proof::{constant#1}>, AuthenticatorPublicKeySet), 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.

pub async fn generate_nullifier( &self, proof_request: &ProofRequest, inclusion_proof: MerkleInclusionProof<world_id_authenticator::::authenticator::{impl#1}::generate_nullifier::{constant#0}>, key_set: AuthenticatorPublicKeySet, ) -> 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.

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).

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 generate_session_id( &self, proof_request: &ProofRequest, session_id_r_seed: Option<FieldElement>, ) -> Result<(SessionId, FieldElement), AuthenticatorError>

Creates a Session for a World ID with an RP.

Internally, this generates the session’s random seed (r) using OPRF Nodes. This seed is used to compute the SessionId::commitment for Session Proofs.

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 agaian 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 fn generate_single_proof( &self, oprf_nullifier: FullOprfOutput, request_item: &RequestItem, credential: &Credential, credential_sub_blinding_factor: FieldElement, session_id_r_seed: FieldElement, session_id: Option<SessionId>, request_timestamp: u64, ) -> Result<ResponseItem, AuthenticatorError>

Generates a single World ID Proof from a provided [ProofRequest] and [Credential]. This method generates the raw proof to be translated into a Uniqueness Proof or a Session Proof for the RP.

This assumes the RP’s [ProofRequest] has already been parsed to determine which [Credential] is appropriate for the request. This method responds to a specific [RequestItem] (a [ProofRequest] may contain multiple items).

Arguments

• oprf_nullifier: The output representing the nullifier, generated from the generate_nullifier function. All proofs require this attribute.
• request_item: The specific RequestItem that is being resolved from the RP’s ProofRequest.
• credential: The Credential to be used for the proof that fulfills the RequestItem.
• credential_sub_blinding_factor: The blinding factor for the Credential’s sub.
• session_id_r_seed: The session ID random seed, obtained via generate_session_id. For Uniqueness Proofs (when session_id is None), this value is ignored by the circuit but must still be provided.
• session_id: The expected session ID provided by the RP. Only needed for Session Proofs. Obtained from the RP’s ProofRequest.
• request_timestamp: The timestamp of the request. Obtained from the RP’s ProofRequest.

Errors

• Will error if the any of the provided parameters are not valid.
• Will error if any of the required network requests fail.
• Will error if the user does not have a registered World ID.

pub async fn insert_authenticator( &self, new_authenticator_pubkey: EdDSAPublicKey, new_authenticator_address: Address, ) -> Result<String, 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<String, 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<String, 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.

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.