BNS on Clarity
BNS support was added to the Stacks blockchain with the release of Stacks 2.0. Just like Stacking, BNS is implemented through the Clarity smart contracting language itself. The BNS contract provides a set of public and read-only methods to interact with the naming system.
Users can register usernames
Stacks users can interact with the BNS contract to register usernames (e.g. alex.id.stx) for any number of available namespaces such as .id.stx. Name registrars can also interact with the contract to add new namespaces, which are similar to top-level domains in the traditional Domain Name System (DNS).
For instance, the recently launched BTC.us service enables users to create .btc usernames such as muneeb.btc. Users have to pay with STX for username operations, as defined by the rules of the namespace owner.
Unlike with other authenticators previously released by Hiro (such as Blockstack Connect or the Blockstack Browser), users cannot register usernames for free using the newer Stacks Web Wallet browser extension. They will need to pay a registration and transaction fee using STX, and use an app that integrates registration via BNS smart contract calls like BTC.us.
However, the extension does show free usernames that were registered previously, and we’re considering the reintroduction of free username registration to the Stacks Wallet as a future enhancement.
To access your previously registered usernames, simply sign into the browser extension with the same underlying Secret Key (previously known as “Secret Recovery Key”) that you used before to manage them.
Developers can use a BNS package and the API to integrate name operations
- Fetch or register namespaces (for instance .id)
- Fetch or register usernames for a specific namespace (for instance alex.id)
- Fetch all username details (for instance Stacks address or expiration date)
- Fetch the history of name operations for a specific username
- Fetch all available subdomains (for instance personal.id)
With BNS tooling, developers can build full-featured naming capabilities inside their apps. For example, apps could enable interaction with other users by username - sending tokens from one account to another with human-readable addresses. Apps could also display the username instead of the account address in their app - this will help users recognize that they are using the right account for. These are only a few examples! We cannot wait to see developers using the naming system to build better user experiences on the user-owned internet.
We are currently working on more advanced documentation for BNS. In the meantime, there are several resources to help you get started today:
- Learn more about BNS and how it works
- For React apps: Sample code for reading usernames inside your app
- For name operations in JS: Review the BNS JS library references
- For Clarity contracts: Review the BNS contract references
- For direct API usage: Review the BNS API endpoints