Make bare-label resolution configurable, default ENS

Bare labels (no dot) are ambiguous now that GNS (.gwei) and WNS (.wei) both
accept them and can point to different owners. Route them to a configurable
`bareLabel` system instead of guessing.

- New `bareLabel` option ('ens' | 'gns' | 'wns'), default 'ens'
- detectSystem(input, bareLabel?) takes an optional second arg
- Behavior change from 0.2.0: bare labels resolved as .gwei; now default to
  ENS (which has no bare-label namespace, so resolve('alice') is null unless
  bareLabel is set to 'gns'/'wns' or an explicit suffix is used)
- Docs, tests, changeset

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jwahdatehagh

.changeset/bare-label-system.md

@@ -0,0 +1,10 @@
+---
+"@1001-digital/ethereum-names": minor
+---
+
+Make bare-label resolution configurable and default it to ENS.
+
+Bare labels (no dot, e.g. `alice`) are ambiguous now that both GNS (`.gwei`) and WNS (`.wei`) accept them — and they can point to different owners. Rather than silently guess, `detectSystem` and the client now route bare labels to a configurable `bareLabel` system.
+
+- New `bareLabel` option (`'ens' | 'gns' | 'wns'`), defaulting to `'ens'`. `detectSystem(input, bareLabel?)` takes an optional second argument.
+- **Behavior change:** in `0.2.0` a bare label resolved as `.gwei`; it now resolves against ENS by default. Since ENS has no bare-label namespace, `resolve('alice')` returns `null` unless you set `bareLabel: 'gns'` or `'wns'` (or pass an explicit `alice.gwei` / `alice.wei`).

README.md

@@ -27,7 +27,7 @@ const names = createEthereumNames()
 await names.resolve('vitalik.eth')    // ENS → '0xd8dA...' | null
 await names.resolve('alice.gwei')     // GNS → '0x...'    | null
 await names.resolve('alice.wei')      // WNS → '0x...'    | null
-await names.resolve('alice')          // bare label → treated as alice.gwei
+await names.resolve('alice')          // bare label → ENS by default (see bareLabel)
 await names.resolve('0xd8dA...')      // address → returned checksummed
 
 // Reverse: address → primary name (tries ENS, then GNS, then WNS)
@@ -58,10 +58,16 @@ names.system('foo.eth')    // 'ens'
 | --------------------------- | ------ |
 | `*.wei`                     | WNS    |
 | `*.gwei`                    | GNS    |
-| bare label (no dot)         | GNS    |
 | any other dotted name `*.eth`, `*.box`, … | ENS |
+| bare label (no dot)         | `bareLabel` option (default ENS) |
 | `0x…` address               | passed through (checksummed) |
 
+A bare label like `alice` is ambiguous — GNS (`.gwei`) and WNS (`.wei`) both accept bare
+labels, and they can point to different owners. Rather than guess, it resolves against the
+`bareLabel` system, which defaults to `ens`. Since ENS has no bare-label namespace, bare
+labels resolve to `null` by default; set `bareLabel: 'gns'` or `'wns'` to opt a label like
+`alice` into that registry.
+
 Reverse lookups try each system in order (ENS first by default) and return the first
 match. Configure the order with `reversePriority`, or use `reverseAll` to get the primary
 name from **all** systems at once.
@@ -87,6 +93,10 @@ const quick = createEthereumNames({ rpcUrl: 'https://my-rpc' })
 
 // Prefer GNS names on reverse lookups
 const gnsFirst = createEthereumNames({ reversePriority: ['gns', 'ens', 'wns'] })
+
+// Treat bare labels (e.g. `alice`) as `.gwei` names
+const gwei = createEthereumNames({ bareLabel: 'gns' })
+await gwei.resolve('alice') // → resolves alice.gwei
 ```
 
 | Option            | Type                  | Description                                                           |
@@ -96,6 +106,7 @@ const gnsFirst = createEthereumNames({ reversePriority: ['gns', 'ens', 'wns'] })
 | `chain`           | `Chain`               | Chain used when no `client` is given. Defaults to `mainnet`.         |
 | `gnsContract`     | `Address`             | Override the GNS contract address.                                   |
 | `wnsContract`     | `Address`             | Override the WNS contract address.                                   |
+| `bareLabel`       | `'ens' \| 'gns' \| 'wns'` | System a bare label (no dot) resolves against. Defaults to `'ens'`. |
 | `reversePriority` | `('ens' \| 'gns' \| 'wns')[]` | Order reverse lookups try each system. Defaults to `['ens', 'gns', 'wns']`. |
 | `verify`          | `boolean`             | Forward-verify reverse lookups before trusting them. Defaults to `true`. |
 

src/client.ts

@@ -53,6 +53,7 @@ export function createEthereumNames(config: EthereumNamesConfig = {}): EthereumN
 
   const reversePriority: NameSystem[] = config.reversePriority ?? ['ens', 'gns', 'wns']
   const verify = config.verify ?? true
+  const bareLabel: NameSystem = config.bareLabel ?? 'ens'
 
   /** GNS and WNS share a registry interface — only the contract and suffix differ. */
   const registries = {
@@ -99,13 +100,13 @@ export function createEthereumNames(config: EthereumNamesConfig = {}): EthereumN
     client,
 
     system(name) {
-      return detectSystem(name)
+      return detectSystem(name, bareLabel)
     },
 
     async resolve(nameOrAddress) {
       if (!nameOrAddress) return null
       if (isAddress(nameOrAddress)) return getAddress(nameOrAddress)
-      const system = detectSystem(nameOrAddress)
+      const system = detectSystem(nameOrAddress, bareLabel)
       if (!system) return null
       return resolveName(nameOrAddress, system)
     },
@@ -141,14 +142,14 @@ export function createEthereumNames(config: EthereumNamesConfig = {}): EthereumN
         return { input, name: null, address, system: null }
       }
 
-      const system = detectSystem(input)
+      const system = detectSystem(input, bareLabel)
       if (!system) return { input, name: null, address: null, system: null }
       const address = await resolveName(input, system)
       return { input, name: canonical(input, system), address, system }
     },
 
     async getAvatar(name) {
-      const system = detectSystem(name)
+      const system = detectSystem(name, bareLabel)
       try {
         if (system === 'ens') return await ensAvatar(client, name)
         if (system === 'gns' || system === 'wns') {
@@ -162,7 +163,7 @@ export function createEthereumNames(config: EthereumNamesConfig = {}): EthereumN
     },
 
     async getText(name, key) {
-      const system = detectSystem(name)
+      const system = detectSystem(name, bareLabel)
       try {
         if (system === 'ens') return await ensText(client, name, key)
         if (system === 'gns' || system === 'wns') {

src/ethereum-names.test.ts

@@ -13,17 +13,26 @@ test('detectSystem routes names to the right system', () => {
   assert.equal(detectSystem('ALICE.WEI'), 'wns')
   // .gwei must not be mistaken for .wei
   assert.equal(detectSystem('gm.gwei'), 'gns')
-  // bare labels are treated as .gwei
-  assert.equal(detectSystem('alice'), 'gns')
+  // bare labels default to ENS, and route to the configured system otherwise
+  assert.equal(detectSystem('alice'), 'ens')
+  assert.equal(detectSystem('alice', 'gns'), 'gns')
+  assert.equal(detectSystem('alice', 'wns'), 'wns')
+  // suffixed names ignore the bareLabel override
+  assert.equal(detectSystem('alice.wei', 'gns'), 'wns')
   assert.equal(detectSystem(''), null)
   assert.equal(detectSystem('   '), null)
 })
 
-test('system() mirrors detectSystem without a network call', () => {
+test('system() mirrors detectSystem, honoring bareLabel config', () => {
   const names = createEthereumNames()
   assert.equal(names.system('vitalik.eth'), 'ens')
   assert.equal(names.system('alice.gwei'), 'gns')
   assert.equal(names.system('alice.wei'), 'wns')
+  // bare label defaults to ENS
+  assert.equal(names.system('alice'), 'ens')
+  // …and follows the bareLabel option
+  assert.equal(createEthereumNames({ bareLabel: 'gns' }).system('alice'), 'gns')
+  assert.equal(createEthereumNames({ bareLabel: 'wns' }).system('alice'), 'wns')
 })
 
 test('resolve passes addresses through, checksummed', async () => {

src/types.ts

@@ -40,6 +40,14 @@ export interface EthereumNamesConfig {
   gnsContract?: Address
   /** Override the WNS contract address. Defaults to the canonical deployment. */
   wnsContract?: Address
+  /**
+   * Which system a bare label (no dot, e.g. `alice`) is resolved against.
+   * Bare labels are ambiguous — GNS (`.gwei`) and WNS (`.wei`) both accept
+   * them — so this picks one deterministically instead of guessing an owner.
+   * Defaults to `'ens'`; note ENS has no bare-label namespace, so bare labels
+   * resolve to `null` unless you set this to `'gns'` or `'wns'`.
+   */
+  bareLabel?: NameSystem
   /** Order in which reverse lookups try each system. Defaults to `['ens', 'gns', 'wns']`. */
   reversePriority?: NameSystem[]
   /**

src/utils.ts

@@ -6,18 +6,20 @@ import type { NameSystem } from './types.js'
  * network calls.
  *
  * - `*.wei` → `wns`
- * - `*.gwei` and bare labels (no dot) → `gns`
+ * - `*.gwei` → `gns`
  * - any other dotted name (`*.eth`, `*.box`, …) → `ens`
+ * - a bare label (no dot) → `bareLabel` (default `'ens'`), since it is
+ *   ambiguous between the GNS/WNS bare-label namespaces
  * - empty input → `null`
  */
-export function detectSystem(input: string): NameSystem | null {
+export function detectSystem(input: string, bareLabel: NameSystem = 'ens'): NameSystem | null {
   const value = input.trim().toLowerCase()
   if (!value) return null
   if (value.endsWith('.wei')) return 'wns'
   if (value.endsWith('.gwei')) return 'gns'
   if (value.includes('.')) return 'ens'
-  // A bare label is treated as a `.gwei` name, matching the GNS convention.
-  return 'gns'
+  // A bare label (no dot) is ambiguous across systems; route it per config.
+  return bareLabel
 }
 
 /** Normalize an ENS name (ENSIP-15), returning `null` if it is invalid. */