Skip to main content

Managing Subdomains

Subdomains are a special class of ArchID domains with some special rules. Owners of both top-level domains and subdomains can Update Domain Data using the same entry point (UpdateUserDomainData); but, unlike top-level domains, subdomains cannot Update Name Resolution.

If a subdomain's Name Resolution is invalid, or otherwise needs to be updated, the top-level domain owner must Remove it and Register it again for the changes to be applied. These restrictions are a security measure, because subdomains can be owned and updated by owners who are not the top-level domain owner. Subdomain owners who do not also own the top-level domain should be aware that the top-level owner has the ability to burn their subdomain.

Subdomain lifetimes can also be extended.

Renewing a Subdomain

Owners can extend the lifetimes of subdomains by calling the ExtendSubdomainExpiry entry point. It is free to extend the lifetime of a subdomain, minus the cost of gas fees.

ExtendSubdomainExpiry is an entry point that takes three parameters, which are the top-level domain (domain), the subdomain to be extended (subdomain) and the new expiration date (expiration).

Here's an example of how we could call ExtendSubdomainExpiry, and extend the lifetime of a subdomain.

/**
* Extend subdomain expiry
* @param {String} domain : Registered top level domain
* @param {String} subdomain : Registered sub-domain to be revoked
* @param {Number} expiration : New expiry timestamp
* @returns {ExecuteResult}
*/
async function extendSubdomainExpiry (domain = null, subdomain = null, expiration = null) {
if (!domain || !subdomain || !expiration) return;
// CW Client
let client = await getClient();
// Sender
let accounts = await getAccounts();
try {
let entrypoint = {
extend_subdomain_expiry : {
domain: domain,
subdomain: subdomain,
expiration: expiration
}
};

let tx = await client.execute(
accounts[0].address,
REGISTRY_CONTRACT,
entrypoint,
"auto",
"Renewing subdomain"
);
// Tx result
return tx;
} catch (e) {
console.error(e);
return {
error: String(e)
};
}
}

async function resolveRecord(name = null) {
if (!name) return;
let client = await getClient();
try {
let entrypoint = {resolve_record: {name: name}};
let query = await client.queryClient.wasm.queryContractSmart(REGISTRY_CONTRACT,entrypoint);
return query;
} catch(e) {
return {error: e};
}
}

async function doSubdomainRenewal() {
// Do not add the `.arch` suffix
let domain = "archid";
// Add only subdomain prefix
let subdomain = "dapp";
// After updating the top level domain, e.g.
// let years = 1
// let renewal = await renewRegistration(domain, years);
// console.log(renewal);
let domain_record = resolveRecord(domain);
let subdomain_renewal = await extendSubdomainExpiry(domain, subdomain, domain_record.expiration);
console.log(subdomain_renewal);
return subdomain_renewal;
}
Expiration

expiration is a value, denominated in seconds, that must be larger than a subdomain's current expiration, and cannot exceed the expiration of its top-level domain.

Removing a Subdomain

There are two cases when you may want to remove a subdomain.

  1. Subdomain is expired and won't be renewed, but the top-level domain will be renewed
  2. Subdomain Name Resolution needs to be changed

Top-level domain owners can remove a subdomain using the RemoveSubdomain entry point which takes domain and a subdomain as it's arguments.

Here's an example of how a subdomain can be removed.

/**
* Burn a subdomain
* @param {String} domain : Registered top level domain
* @param {String} subdomain : Registered sub-domain to be revoked
* @returns {ExecuteResult}
*/
async function RemoveSubdomain(domain = null, subdomain = null) {
if (!domain || !subdomain) return;
// CW Client
let client = await getClient();
// Sender
let accounts = await getAccounts();
try {
let entrypoint = {
remove_subdomain: {
domain: domain,
subdomain: subdomain
}
};

let tx = await client.execute(
accounts[0].address,
REGISTRY_CONTRACT,
entrypoint,
"auto",
"Removing subdomain"
);
// Tx result
return tx;
} catch (e) {
console.error(e);
return {
error: String(e)
};
}
}

async function doRemoveSubdomain() {
// Do not add the `.arch` suffix
let domain = "archid";
// Add only subdomain prefix
let subdomain = "dapp";
let removal = await renewRegistration(domain, subdomain);
console.log(removal);
return removal;
}
caution

Removing a subdomain will burn the subdomain ownership NFT. This action cannot be undone, but it is possible to register the same subdomain name again.