> For the complete documentation index, see [llms.txt](https://snowball-mns.gitbook.io/snowball/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://snowball-mns.gitbook.io/snowball/decentralized-identity-layer/technical-documentation/reverse-lookup.md).

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