Mirroring APIs Business Logic
In general
Default Blockchain Selection
The Freename Mirroring APIs (Webunited) back end selects the blockchain to use by default for all Web3 domains. Registries do not have the option to choose the blockchain unless they specifically request this customization.
Billing and Lifecycle of Web3 Domains
From a billing perspective, the lifecycle of a Web3 domain is tied to the lifecycle of its associated Web2 domain. This means that the expiration date of the Web3 domain will automatically match the expiration date of the Web2 domain it is associated with.
Invoicing for Web3 Domains
If a Web3 domain is enabled for an existing Web2 domain, the invoicing process will charge the full fee regardless of the remaining time between the minting of the Web3 domain and the next renewal date of the Web2 domain.
Incentives for Activations
To encourage activations of Web3 domains, we offer marketing plans that offset the cost of the first year’s registration. These offsets are treated as credit notes, providing an incentive for users to activate their Web3 domains.
Charges for Extended Expiry Dates
If a Web2 domain has more than a year left before its next expiration date, the "create" fee for the Web3 domain will be charged upfront for all the years needed to match the expiration date of the Web3 domain with that of the Web2 domain. For example, if a Web3 domain is created on April 15, 2024, for a Web2 domain expiring on October 6, 2026, the system will charge the equivalent of 3 years of the registration fee.
Processing Orders via API
Orders received through the API are queued for processing. Registrars can poll a dedicated message queue to receive updates on their requests and to fetch messages related to activities such as incoming transfers. This system ensures that registrars are kept informed about the status of their orders in real-time.
Key Operations for Registrars
Create
Request Submission
Registrars initiate the process by sending a "create" request via the API.
Verification Process
Upon receiving a "create" request, the system performs several checks to ensure the legitimacy and accuracy of the request:
Registrar Verification: Confirm that the registrar issuing the create command is the same entity listed as the Registrar of Record for the Web2 domain. This ensures that only authorized parties can create a corresponding Web3 domain.
Domain Status Check: Verify that the Web2 domain is active and not currently involved in any disputes by checking the domain status. This prevents the creation of Web3 domains for domains that may be problematic.
Expiry Date Retrieval: Fetch the current expiry date of the Web2 domain to synchronize the billing and creation of the Web3 domain. This ensures that the Web3 domain will have an expiration date aligned with the Web2 domain.
Handling Resellers
If the system decides to allow Resellers to access Webunited for their domains without going through their upstream provider, an alternative authentication method is required due to the lack of Reseller information in WHOIS/Registry APIs. This method involves using tokens placed in a TXT record of the Web2 domain:
Create Request: The Reseller sends a "create" request for a domain (e.g., example.ws).
Token Generation: The system responds with a unique token in the API response payload.
Transaction Hold: The "create" transaction is put on hold by the system.
DNS Check: The system regularly checks the DNS of the domain (example.ws) until the TXT record containing the token appears.
Validation and Processing: Once the token is detected, the order is validated and processed.
Transaction and Queuing
After successful verification, a transaction ID is returned to the requesting registrar, and the minting operation is placed in a processing queue.
Registrars can poll the system for updates on the operation’s status until it is marked as SUCCESS or FAILED.
Existing Domains and Holding Wallet
The system checks if the Web3 domain already exists or is in a holding wallet:
Non-Existent Domain: If the Web3 domain does not exist, it is queued for creation.
Holding Wallet Domain: If the domain exists in the holding wallet, it is reassigned to the new owner.
Recent Deletion: If the create command is issued by the same registrar that deleted the Web3 domain within the past 7 days, the domain is restored with its original expiration date without incurring a new registration fee.
Transfer
Monitoring and Detection
The system continuously monitors Web2 domains, performing checks every 24 hours.
When a transfer to a new registrar is detected, the system takes the following actions:
Registrar Signed Up for Webunited:
The Web3 domain is automatically transferred to the new registrar's account.
A message is added to the receiving registrar’s "poll" queue, informing them of the transfer and providing them 7 calendar days to issue a "delete" command for the Web3 domain if the registrant does not wish to retain it.
If no delete command is issued within 7 days, the renewal fee is billed to the new registrar’s account, and the domain’s expiry date is updated accordingly.
Registrar Not Signed Up for Webunited:
The Web3 domain is moved to the holding account and wiped clean, similar to the deletion process.
Transfer Process for Resellers
For transfers involving Resellers, a "transfer" API command can be used to manage the process:
Token Generation: The system returns a token to be added as a DNS TXT record to authorize the transfer.
Charge Acceptance: This method ensures that the Reseller or Registrar explicitly accepts any charges associated with the Web3 domain before the transfer is completed.
Renewals
Automatic Synchronization
Explicit renewals are not supported for Web3 domains as their expiry dates are designed to match those of their Web2 counterparts.
When a Web2 domain is renewed, or a renewal charge is triggered by a transfer, the system automatically charges the corresponding fee for the Web3 domain to ensure synchronized expiry dates.
Billing Cycle
Renewals are processed and billed 45 days after the Web2 domain’s expiration date to account for the Renewal Grace Period (RGP). This period allows for auto-renewal while giving registrars the flexibility to delete renewed domains within 45 days and receive a full refund. By processing renewals after this period, the need for issuing refunds for deleted domains is minimized.
Deletion
Deletion Process
When a Web2 domain is deleted, either explicitly or due to non-renewal, the associated Web3 domain is also wiped and moved to a holding wallet controlled by Webunited.
Registrars can issue a Delete command via the API to disable a Web3 domain while retaining the Web2 domain. The Web3 domain is then wiped and placed in the holding wallet.
Restoration
Registrars have a 7-day window to restore the Web3 domain without incurring a new registration fee by issuing a new create command. This window expires at midnight UTC on the 7th day following the deletion. Create commands sent after this period will incur a new registration fee.
Handling Orphaned Domains
In cases where the Web2 domain is transferred, but the Web3 domain is not, the losing registrar should issue a "delete Web3 domain" command to the API to relinquish control and avoid being charged.
Ownership Changes
Webunited does not collect registrant data and follows the principle that the Web3 domain mirrors the Web2 domain’s ownership.
It is the responsibility of the registrar to ensure the new registrant agrees to the terms and conditions regulating Web3 domains and to update the Web3 domain to reflect any change in ownership.
Last updated