# Reverse Lookup

**Overview**

The `reverse lookup` feature in the `movement_names` module allows an address to be associated with a specific domain name, also known as a "primary name." This enables decentralized applications (dApps) and users to identify an account by its chosen name rather than its address.

**Key Structures and Events**

1. **SetReverseLookupEvent**: This event is triggered when a reverse lookup name is set or cleared for an address.
   * **Fields**:
     * `account_addr`: The address for which the reverse lookup is set.
     * `prev_domain_name`, `prev_domain_suffix`, `prev_subdomain_name`, `prev_expiration_time_secs`: Capture the previous state of the reverse lookup, if it existed.
     * `curr_domain_name`, `curr_domain_suffix`, `curr_subdomain_name`, `curr_expiration_time_secs`: Capture the current reverse lookup name and expiration time, if set.

**Main Functions for Reverse Lookup**

**Registering and Updating Names**

1. **register\_domain**: Registers a new domain or updates an existing one if expired. It clears any existing reverse lookup associated with the domain before registering.
2. **register\_name\_internal**: Called internally by `register_domain`, this function updates or sets new details for a domain, including expiration time.
   * **Process**:
     * Checks if the domain is available and valid.
     * Clears any reverse lookup if the name is a primary name for any address.
     * Sets expiration time and registers the domain.
     * Emits a `RegisterNameEvent` to log the action.

**Renewing Domains**

3. **renew\_domain**: Renews an existing domain by extending its expiration time.
   * If the domain is a primary name, it verifies that the reverse lookup points back to this domain for consistency.
   * Emits a `RenewNameEvent` to log the renewal action.

**Setting Target Address**

4. **set\_target\_address**: Associates a domain with a specific target address, allowing dApps to route requests to this address.
   * **Reverse Lookup Check**: If this domain is the primary name (reverse lookup) for the signer's address, and a new address is assigned, it clears the current reverse lookup.
   * Emits a `SetTargetAddressEvent` for tracking changes.
5. **clear\_target\_address**: Clears the target address for a domain if the signer is authorized. This also clears the reverse lookup if the domain was associated as a primary name for the address.
   * Emits a `SetTargetAddressEvent` when cleared.

**Setting and Clearing Reverse Lookup (Primary Name)**

6. **set\_reverse\_lookup**: Sets a specified domain as the "primary name" (reverse lookup) for a user's address.
   * **Parameters**:
     * `account`: Signer account.
     * `subdomain_name`, `domain_suffix`, `domain_name`: Components of the domain to set as the primary name.
   * **Behavior**: Links the signer’s address with the specified domain. If a reverse lookup was already set, it will be overwritten.
   * Emits a `SetReverseLookupEvent`.
7. **clear\_reverse\_lookup**: Removes the reverse lookup association for a user's address.
   * **Behavior**: This operation clears the primary name for the address, allowing the address to remain unidentified until another primary name is set.
   * Emits a `SetReverseLookupEvent`.

**Example Workflow**

1. **Registering a Domain**: A user registers a domain, setting it as their primary name.
   * **Events**: `RegisterNameEvent`, `SetReverseLookupEvent`.
2. **Updating a Target Address**: The user associates their domain with a new address. If this domain was previously a primary name, the reverse lookup will be cleared.
   * **Events**: `SetTargetAddressEvent`, `SetReverseLookupEvent`.
3. **Clearing Primary Name**: If the user decides to remove their primary name, they call `clear_reverse_lookup`.
   * **Events**: `SetReverseLookupEvent`.

This mechanism allows addresses to dynamically manage their identities, enabling domain and address associations to change as needed.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://snowball-mns.gitbook.io/snowball/decentralized-identity-layer/technical-documentation/reverse-lookup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.