Ordinals Primary Name Protocol (Solution B, Beta)

1. Background

The Bitcoin ecosystem currently lacks a primary name protocol, so the related blockchain explorers, third-party NFT markets, and DApp websites for Bitcoin have not been able to display users' wallet addresses as a more readable name, unlike Ethereum. If there were a primary name protocol in the Bitcoin ecosystem, it could allow some wallet addresses to be disseminated in a more user-friendly form within the Bitcoin community and further spread to non-Bitcoin communities, enhancing the influence of the Bitcoin community.

There are already multiple Ordinals name protocols, with typical examples being .btc Name and .sats Name. It is hoped that there can be a rule that accommodates the mainstream Ordinals name protocols, reducing the development and integration costs for all parties involved.

2. Core Rules

2.1 Ordinals Primary Name Definition

For an Ordinals name (such as abc.btc) transfer event, there are "from address" and "to address". After an Ordinals name be transferred to a wallet and "from address" equals "to address", the Ordinals name will become the Primary Name of the wallet.

2.2 Last is the New

The Primary Name of a wallet maybe changed, and there is only one Primary Name for a wallet , so the old Primary Name should be overwritten by the new Primary Name.

For example, Wallet A owns a.btc and b.btc, Wallet A first transfer "a.btc" to itself, then transfer "b.btc" to itself, finally "b.btc" is thePrimary Name of Wallet A.

2.3 Block Height

The block height this solution takes effect.

Block Height: 840000

2.4 Max Primary Name Length

Primary Name mainly used for display name instead of wallet address. A very long name is not suitable for Primary Name.

We set the max Primary Name length as 128. If the length of a BtcName is greater than 128, it can not be used as Primary Name. For example, the length of "a.btc" is 5.

2.5 Address Type Supported

Native Segwit( starts with bc1q) and Taproot( starts with bc1p).

In theory, all BTC wallet address can be supported, but in order to reduce unintentional settings, only Native Segwit and Taproot wallet address are currently supported.

3. Some Cases

• case 1: Wallet A owns "a.btc". Wallet A transfer a.btc to itself. At this point, the Primary Name of wallet A is "a.btc".

• case 2: Wallet A owns "a.btc", "b.btc". Wallet A first transfer a.btc to itself, then transfer "b.btc" to itself. At this point, the Primary Name of wallet A is "b.btc".

• case 3: Wallet A owns "a.btc". Wallet A first transfer "a.btc" to itself, then transfer "a.btc" to Wallet B, Wallet B transfer "a.btc" to Wallet A. At this point, wallet A does not have a Primary Name.

• case 4: Wallet A owns "a.btc", "b.btc". Wallet A first transfer a.btc to itself, then transfer "b.btc" to itself, then transfer "b.btc" to Wallet B. At this point, Wallet A does not have a Primary Name.

4. Engineering Implementation Reference

Create a new table primary_name:

CREATE TABLE `tb_primary_name` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT 'id',
  `wallet_address` varchar(62)NOT NULL COMMENT 'wallet address',
  `primary_name` varchar(128) DEFAULT NULL COMMENT 'primary name',
  PRIMARY KEY (`id`) USING BTREE,
  UNIQUE KEY `uk_wallet_address` (`wallet_address`) USING BTREE,
  UNIQUE KEY `uk_primay_name` (`primay_name`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4 COMMENT='primary name'; 

Monitor Ordinals domain name transfer event from old to new and update the table "tb_primay_name". Take transfer $btcname for example:

if( $btcname in  table `primary_name` && $from_address !=  $to_address) 
{
    $sql = "update tb_primary_name set primary_name = NULL where primary_name = $btcname ";
    // exexute SQL 
}

if($from_address ==  $to_address 
  &&(substr($from_address,0,4) == 'bc1q' || substr($from_address,0,4) == 'bc1p') 
  && length($btcname) <= 128 ) 
{
    $sql = "update tb_primary_name set primary_name = $btc_name where wallet_address = $from_address ";
    // exexute SQL 
}

Query Primary Name of a wallet address :

$sql = "select primary_name from tb_primary_name where wallet_address = $wallet_address"
$row = // exexute SQL 
$primary_name = '';
if($row && $row.primary_name) 
{
    $primary_name = $row.primaray_name;
}

5. API

Query the primary name of a wallet address:

• URL: https://btcnameapi.com/api/v1/primary_name/query?address={wallet_address}
• HTTP method: Get

• Supports Ordinal Names: BtcName (.btc)

A example that returns a primary name:

https://btcnameapi.com/api/v1/primary_name/query?address=bc1pw9e4d928rsw2x4ma0f9z9kvptt0ycypsyuc9s049y4usha3w946snqc5yh

{
    "code": "0",
    "msg": "success",
    "data": {
        "primary_name": "163.btc"
    }
}

A example that returns empty:

https://btcnameapi.com/api/v1/primary_name/query?address=bc1pwp3aycchale8k9l6d9kquxhj86ze4dsqmkre7ufqymrq87uw66xs5us7w4

{
    "code": "0",
    "msg": "success",
    "data": {
        "primary_name": ""
    }
}

6. Further Discussion

The Ordinals Primary Name Protocol is currently in draft status. You are welcome to join the .btc name Discord #primary-name channel to discuss and help refine this protocol.

BtcName Discord : https://discord.gg/eNERqJU85x