Events Documentation

This guide describes the events emitted by the DiD Protocol smart contracts that integrators can use for indexing.

Events Overview

Events in DiD Protocol provide real-time updates about changes to names, ownership, addresses, and other state changes in the system. This allows integrators to maintain accurate, up-to-date indexes of the naming system.

Core Events

Registration Events

RegisterNameEvent

Emitted when a name (domain or subdomain) is registered.

struct RegisterNameEvent has drop, store {
    owner: address,
    domain_name: String,
    domain_suffix: Option<String>,
    subdomain_name: Option<String>,
    registration_fee_octas: u64,
    expiration_time_secs: u64,
    registration_duration_secs: u64
}

• owner: Address of the new name owner

• domain_name: The registered domain name

• domain_suffix: Optional domain suffix (e.g., "move")

• subdomain_name: Optional subdomain name if registering a subdomain

• registration_fee_octas: Registration fee paid in Octas

• expiration_time_secs: Unix timestamp when the registration expires

• registration_duration_secs: Duration of the registration in seconds

RenewNameEvent

Emitted when a name's registration is renewed.

struct RenewNameEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>,
    subdomain_name: Option<String>,
    renewal_fee_octas: u64,
    expiration_time_secs: u64,
    renewal_duration_secs: u64,
    target_address: Option<address>,
    is_primary_name: bool
}

• domain_name: The renewed domain name

• domain_suffix: Optional domain suffix

• subdomain_name: Optional subdomain name

• renewal_fee_octas: Renewal fee paid in Octas

• expiration_time_secs: New expiration timestamp

• renewal_duration_secs: Duration of renewal in seconds

• target_address: Current target address of the name

• is_primary_name: Whether this name is set as primary name for its target address

Transfer Events

TransferNameEvent

Emitted when a name is transferred to a new owner.

struct TransferNameEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>, 
    subdomain_name: Option<String>,
    from_addr: address,
    to_addr: address
}

• domain_name: The transferred domain name

• domain_suffix: Optional domain suffix

• subdomain_name: Optional subdomain name

• from_addr: Previous owner's address

• to_addr: New owner's address

Address Resolution Events

SetTargetAddressEvent

Emitted when a name's target address is updated.

struct SetTargetAddressEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>,
    subdomain_name: Option<String>,
    expiration_time_secs: u64,
    new_address: Option<address>
}

• domain_name: The domain name

• domain_suffix: Optional domain suffix

• subdomain_name: Optional subdomain name

• expiration_time_secs: Current expiration timestamp

• new_address: New target address (None if cleared)

SetTargetAddressByCAIPEvent

Emitted when a cross-chain address is set for a name.

struct SetTargetAddressByCAIPEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>,
    subdomain_name: Option<String>,
    new_address: Option<String>,
    caip: String
}

• domain_name: The domain name

• domain_suffix: Optional domain suffix

• subdomain_name: Optional subdomain name

• new_address: New target address in string format

• caip: CAIP identifier for the chain

Reverse Resolution Events

SetReverseLookupEvent

Emitted when a reverse lookup (primary name) is set or cleared for an address.

struct SetReverseLookupEvent has drop, store {
    account_addr: address,
    prev_domain_name: Option<String>,
    prev_domain_suffix: Option<String>, 
    prev_subdomain_name: Option<String>,
    prev_expiration_time_secs: Option<u64>,
    curr_domain_name: Option<String>,
    curr_domain_suffix: Option<String>,
    curr_subdomain_name: Option<String>,
    curr_expiration_time_secs: Option<u64>
}

• account_addr: Address whose primary name is being set/cleared

• prev_*: Previous name details (if any)

• curr_*: New name details (None if clearing)

Metadata Events

SetAvatarUrlEvent

Emitted when an avatar URL is set for a name.

struct SetAvatarUrlEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>,
    subdomain_name: Option<String>,
    avatar_ipfs_hash: Option<String>
}

• domain_name: The domain name

• domain_suffix: Optional domain suffix

• subdomain_name: Optional subdomain name

• avatar_ipfs_hash: IPFS hash of the avatar (None if cleared)

SetKeyValueRecordEvent

Emitted when a key-value record is set for a name.

struct SetKeyValueRecordEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>,
    subdomain_name: Option<String>,
    key: String,
    value: Option<String>
}

• domain_name: The domain name

• domain_suffix: Optional domain suffix

• subdomain_name: Optional subdomain name

• key: Record key

• value: Record value (None if cleared)

Marketplace Events

ListDomainForSaleEvent

Emitted when a domain is listed for sale.

struct ListDomainForSaleEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>,
    price: u64,
    duration_secs: u64,
    expiration_time: u64,
    seller: address
}

• domain_name: The listed domain name

• domain_suffix: Optional domain suffix

• price: Listing price in Octas

• duration_secs: Duration of the listing

• expiration_time: When the listing expires

• seller: Address of the seller

ListingUpdatedEvent

Emitted when a domain listing is updated.

struct ListingUpdatedEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>,
    old_price: u64,
    new_price: u64,
    old_expiration_time: u64,
    new_expiration_time: u64,
    duration_secs: u64,
    seller: address
}

ListingBuyEvent

Emitted when a listed domain is purchased.

struct ListingBuyEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>,
    price: u64,
    seller: address,
    buyer: address
}

ListingCancelledEvent

Emitted when a domain listing is cancelled.

struct ListingCancelledEvent has drop, store {
    domain_name: String,
    domain_suffix: Option<String>,
    price: u64,
    seller: address
}

Best Practices for Indexing

1. Handle Reorgs: Always be prepared for blockchain reorganizations by implementing proper reorg handling in your indexer.

2. Process Events in Order: Events should be processed in the order they appear in blocks to maintain consistency.

3. State Validation: Periodically validate your indexed state against on-chain data to ensure accuracy.

4. Handle Missing Events: Implement retry logic for missed events and periodic state reconciliation.

5. Track Event Versions: If the event structure changes in future updates, maintain version compatibility in your indexer.

Technical Considerations

• All timestamps are in Unix seconds

• Fees and prices are in Octas (1 APT = 100000000 Octas)

• String values for names should be stored as normalized lowercase

• CAIP IDs follow the CAIP-2 specification for chain identification

• Handle Option types appropriately - they may be None/null