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

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

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

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

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

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