# Oniym

> One name, all chains. Multichain-native naming service.

## How it works

### System overview

![Oniym system overview](/architecture/system-overview.png)

### Name structure

Every Oniym name is a two-part label: `<label>.<tld>` — for example `kyy.web3` or `alice.id`.

* **Label** — the unique identifier you register (e.g. `kyy`)
* **TLD** — one of 65 protocol-managed top-level domains (e.g. `web3`)

Subnames (`sub.kyy.web3`) are not supported in v1.

### Namehash

Oniym uses [ENSIP-1](https://docs.ens.domains/ensip/1) namehash to derive a deterministic 32-byte node for any name:

```
namehash("") = 0x00...00
namehash("web3") = keccak256(namehash("") ‖ keccak256("web3"))
namehash("kyy.web3") = keccak256(namehash("web3") ‖ keccak256("kyy"))
```

The node is the canonical on-chain identifier for a name — used as the primary key in the Registry and all resolver records.

### Registration flow

Registration uses a **commit-reveal** scheme to prevent frontrunning:

![Oniym registration flow](/architecture/registration-flow.png)

The `req` encodes name, TLD, owner, duration, a random secret, and optional resolver data. Because the commitment is a hash of all fields including the secret, nobody can copy your transaction and steal the name before you.

### Multichain addresses

Addresses are stored per coin type following [ENSIP-9](https://docs.ens.domains/ensip/9) / SLIP-0044:

| Chain                 | Coin type |
| --------------------- | --------- |
| Ethereum / Base / EVM | 60        |
| Bitcoin               | 0         |
| Solana                | 501       |
| Sui                   | 784       |
| BNB                   | 714       |

### Resolution flow

![Oniym resolution flow](/architecture/resolution-flow.png)

### Reverse resolution

When registering with `reverseRecord: true`, the `ReverseRegistrar` contract sets a reverse record mapping `address → name`. This lets wallets and dapps display `kyy.web3` instead of `0x1170...`.

Callers should always verify the forward resolution matches before displaying a reverse name as a verified identity.

### Expiry and renewal

Names expire after their registration duration. A **90-day grace period** follows expiry during which only the original owner can renew. After the grace period the name becomes available for anyone to register.


## Supported TLDs

Oniym supports 65 top-level domains across four categories. All TLDs are equal — any resolves to any chain.

### General identity

| TLD    | Node              |
| ------ | ----------------- |
| `.id`  | `namehash("id")`  |
| `.one` | `namehash("one")` |
| `.me`  | `namehash("me")`  |
| `.co`  | `namehash("co")`  |

### Web3 / tech

| TLD                                                    |
| ------------------------------------------------------ |
| `.xyz` `.web3` `.io` `.pro` `.app` `.dev` `.onm` `.go` |

### Crypto culture

| TLD                                                               |
| ----------------------------------------------------------------- |
| `.ape` `.fud` `.hodl` `.fomo` `.moon` `.rekt` `.wagmi` `.ngmi`    |
| `.degen` `.whale` `.buidl` `.dyor` `.pump` `.alpha` `.safu` `.l2` |
| `.gm` `.lfg` `.ser` `.fren` `.goat` `.cope` `.pepe` `.wen`        |

### DeFi / Finance

| TLD                                                              |
| ---------------------------------------------------------------- |
| `.mint` `.bear` `.gas` `.dao` `.ath` `.dex` `.cex` `.burn`       |
| `.node` `.swap` `.yield` `.bag` `.bags` `.seed` `.drop` `.stake` |
| `.pool` `.wrap` `.farm` `.shill`                                 |

### Misc

| TLD                                                                   |
| --------------------------------------------------------------------- |
| `.xxx` `.regs` `.main` `.test` `.exit` `.fair` `.guh` `.bots` `.keys` |

### Constraints

* Max **65** TLDs total (enforced on-chain by `ITLDManager`)
* Max **5** characters per TLD label
* Labels are lowercase ASCII only

### Computing TLD nodes

TLD nodes follow ENSIP-1 namehash from the root:

```ts
import { namehash } from "@oniym/sdk";

const web3Node = namehash("web3");
// 0x587d09fe5fa45354680537d38145a28b772971e0f293af3ee0c536fc919710fb
```


## Getting started

### Installation

:::code-group
```bash [npm]
npm install @oniym/sdk viem
```

```bash [pnpm]
pnpm add @oniym/sdk viem
```

```bash [yarn]
yarn add @oniym/sdk viem
```
:::

### Initialise

```ts
import { Oniym } from "@oniym/sdk";

const oniym = new Oniym({
    indexerUrl: "https://api.oniym.xyz", // fast reads
    rpcUrl: "https://mainnet.base.org", // fallback / write calls
});
```

#### Config options

| Option       | Type            | Description                                                                                           |
| ------------ | --------------- | ----------------------------------------------------------------------------------------------------- |
| `indexerUrl` | `string`        | Base URL of the Oniym indexer API. Defaults to `https://api.oniym.xyz`.                               |
| `rpcUrl`     | `string`        | Base RPC URL for direct contract reads and write calls. Defaults to the public Base Sepolia endpoint. |
| `chainId`    | `84532 \| 8453` | Chain to use. Defaults to `84532` (Base Sepolia).                                                     |

### Read a name

```ts
import { Oniym } from "@oniym/sdk";
const oniym = new Oniym({ indexerUrl: "https://api.oniym.xyz" });
// All records for a name
const result = await oniym.resolve("kyy.web3");
console.log(result?.owner); // "0x..."
console.log(result?.expiresAt); // unix timestamp string
console.log(result?.addresses); // { "60": "0x..." }
console.log(result?.texts); // { "twitter": "..." }

// Just one chain's address
const eth = await oniym.getAddress("kyy.web3", "eth");

// All chain addresses at once
const all = await oniym.getAddresses("kyy.web3");
// { eth: "0x...", sol: "...", btc: "..." }

// Reverse: address → name
const name = await oniym.getName("0x11702b...");
```

### Check availability & price

Pricing is two-tier: **$3/month** or **$15/year** for any name length. Pay with ETH or USDC.

```ts
import { Oniym } from "@oniym/sdk";
const oniym = new Oniym({ indexerUrl: "https://api.oniym.xyz" });
const isAvailable = await oniym.available("alice", "web3");

// ETH price — fluctuates with Chainlink feed
const monthly = await oniym.rentPrice("alice", "web3", 30 * 24 * 60 * 60); // ~$3
const annual = await oniym.rentPrice("alice", "web3", 365 * 24 * 60 * 60); // ~$15
console.log(`Monthly: ${Number(monthly) / 1e18} ETH`);
console.log(`Annual:  ${Number(annual) / 1e18} ETH`);
```

### Register a name

Registration requires a connected [viem](https://viem.sh) `WalletClient`. Pay with ETH (default) or USDC.

```ts
import { Oniym } from "@oniym/sdk";
import { createWalletClient, custom } from "viem";
import { baseSepolia } from "viem/chains";

const oniym = new Oniym({ indexerUrl: "https://api.oniym.xyz" });
const walletClient = createWalletClient({
    chain: baseSepolia,
    transport: custom(window.ethereum),
});

// Pay with ETH (default)
const hash = await oniym.register(
    {
        name: "alice",
        tld: "web3",
        duration: 365 * 24 * 60 * 60,
        reverseRecord: true,
        addresses: { eth: "0x11702b8eF5F882191Af862a7e27096C44A5e2B37" },
        onCommit: (hash) => console.log("Committed:", hash),
        onWaiting: (ms) => console.log(`Waiting ${ms / 1000}s...`),
    },
    walletClient,
);

// Pay with USDC — SDK approves + registers automatically (2 txs)
const hash = await oniym.register(
    {
        name: "alice",
        tld: "web3",
        duration: 365 * 24 * 60 * 60,
        paymentToken: "usdc",
    },
    walletClient,
);
```

The SDK handles the full commit → wait → reveal flow automatically.


## Oniym class

The `Oniym` class is the main entry point for the SDK.

### Constructor

```ts
import { Oniym } from "@oniym/sdk";

const oniym = new Oniym(config?: OniymConfig);
```

#### OniymConfig

```ts
interface OniymConfig {
    indexerUrl?: string; // default: "https://api.oniym.xyz"
    rpcUrl?: string; // default: public Base Sepolia RPC
    chainId?: 84532 | 8453; // default: 84532 (Base Sepolia)
}
```

### Read methods

| Method                                                        | Description              |
| ------------------------------------------------------------- | ------------------------ |
| [`resolve(name)`](/sdk/resolution#resolve)                    | All records for a name   |
| [`getName(address)`](/sdk/resolution#getname)                 | Reverse lookup           |
| [`getAddress(name, chain)`](/sdk/resolution#getaddress)       | Single chain address     |
| [`getAddresses(name)`](/sdk/resolution#getaddresses)          | All chain addresses      |
| [`available(name, tld)`](/sdk/resolution#available)           | Availability check (RPC) |
| [`rentPrice(name, tld, duration)`](/sdk/resolution#rentprice) | Price in wei (RPC)       |
| [`getTLDs()`](/sdk/utilities#gettlds)                         | List all supported TLDs  |

### Write methods

| Method                                                                           | Description                     |
| -------------------------------------------------------------------------------- | ------------------------------- |
| [`register(options, walletClient)`](/sdk/registration)                           | Full commit-reveal registration |
| [`setAddress(name, chain, address, walletClient)`](/sdk/registration#setaddress) | Set a chain address             |
| [`setText(name, key, value, walletClient)`](/sdk/registration#settext)           | Set a text record               |
| [`setResolver(name, resolver, walletClient)`](/sdk/registration#setresolver)     | Set the resolver                |

### Utility methods

| Method                                                   | Description          |
| -------------------------------------------------------- | -------------------- |
| [`namehash(name)`](/sdk/utilities#namehash)              | ENSIP-1 namehash     |
| [`labelhash(label)`](/sdk/utilities#labelhash)           | keccak256 of a label |
| [`makeNode(parentNode, label)`](/sdk/utilities#makenode) | Subdomain node       |
| [`parseName(name)`](/sdk/utilities#parsename)            | Split label + TLD    |
| [`coinTypeFor(chain)`](/sdk/utilities#cointypefor)       | SLIP-0044 coin type  |


## Registration

Write methods require a connected [viem](https://viem.sh) `WalletClient` passed as the last argument.

### register

Registers a name via the commit-reveal flow. The SDK handles the full sequence automatically:

1. Generates a random secret
2. Calls `commit(makeCommitment(req))`
3. Waits `MIN_COMMITMENT_AGE` (60 seconds + 5s buffer)
4. Collects payment and calls `register(req, paymentToken)`

#### Pay with ETH (default)

```ts
import { createWalletClient, custom } from "viem";
import { baseSepolia } from "viem/chains";

const walletClient = createWalletClient({
  chain: baseSepolia,
  transport: custom(window.ethereum),
});

const hash = await oniym.register(
  {
    name: "alice",
    tld: "web3",
    duration: 30 * 24 * 60 * 60,  // 30 days ($3); use 365 * 24 * 60 * 60 for 1 year ($15)
    owner: "0x...",               // defaults to walletClient.account.address
    reverseRecord: true,
    addresses: {
      eth: "0x11702b8eF5F882191Af862a7e27096C44A5e2B37",
    },
    texts: {
      twitter: "@alice",
    },
    onCommit: (hash) => console.log("Committed:", hash),
    onWaiting: (ms) => console.log(`Waiting ${ms / 1000}s...`),
  },
  walletClient,
);
```

#### Pay with USDC

Pass `paymentToken: "usdc"` to pay the exact USD amount with no ETH price exposure. The SDK automatically:

1. Calls `PriceOracle.priceUsdc()` to get the exact USDC amount (e.g. `3_000000` for 30 days)
2. Calls `USDC.approve(controller, amount)` — one extra transaction
3. Calls `register(req, usdcAddress)` — no `msg.value` needed

```ts
const hash = await oniym.register(
  {
    name: "alice",
    tld: "web3",
    duration: 365 * 24 * 60 * 60,  // 1 year = exactly $15.00 USDC
    paymentToken: "usdc",
    reverseRecord: true,
  },
  walletClient,
);
```

#### RegisterOptions

```ts
interface RegisterOptions {
  name: string;                    // label only, e.g. "alice"
  tld: string;                     // TLD label, e.g. "web3"
  duration?: number;               // seconds — 30 days ($3/month), 365 days ($15/year)
  owner?: Address;                 // default: walletClient.account.address
  resolver?: Address;              // default: PublicResolver
  reverseRecord?: boolean;         // default: false
  paymentToken?: "eth" | "usdc";   // default: "eth"
  addresses?: Partial<Record<SupportedChain, string>>;
  texts?: Record<string, string>;
  onCommit?: (hash: Hash) => void;
  onWaiting?: (remainingMs: number) => void;
}
```

**Returns:** `Hash` — transaction hash of the `register()` call

### renew

Renews an existing registration. No commit-reveal required.

#### Pay with ETH

```ts
const hash = await oniym.renew(
  {
    name: "alice",
    tld: "web3",
    duration: 365 * 24 * 60 * 60,  // 1 year
  },
  walletClient,
);
```

#### Pay with USDC

```ts
const hash = await oniym.renew(
  {
    name: "alice",
    tld: "web3",
    duration: 365 * 24 * 60 * 60,
    paymentToken: "usdc",
  },
  walletClient,
);
```

#### RenewOptions

```ts
interface RenewOptions {
  name: string;                    // label only, e.g. "alice"
  tld: string;                     // TLD label, e.g. "web3"
  duration?: number;               // seconds — default: 365 days
  paymentToken?: "eth" | "usdc";   // default: "eth"
}
```

**Returns:** `Hash` — transaction hash of the `renew()` call

### setAddress

Set a chain address on an existing name.

```ts
const hash = await oniym.setAddress("kyy.web3", "sol", "solanaAddress...", walletClient);
```

**Supported chains:** `"btc" | "eth" | "sol" | "sui" | "bnb"`

### setText

Set a text record on an existing name.

```ts
const hash = await oniym.setText("kyy.web3", "twitter", "@kyy", walletClient);
```

Common text record keys: `twitter`, `github`, `url`, `email`, `avatar`, `description`

### setResolver

Set the resolver contract for a name. Requires owning the name.

```ts
const hash = await oniym.setResolver(
  "kyy.web3",
  "0xcdE3eD98423FbE098E24Bba9B634dFC3b449AC1C",
  walletClient,
);
```


## Resolution

All read methods use the indexer API for fast off-chain queries. Set `indexerUrl` in the config to point to a deployed indexer.

### resolve

Returns all on-chain records for a name, or `null` if not found.

```ts
const result = await oniym.resolve("kyy.web3");
```

**Returns:** `ResolveResult | null`

```ts
interface ResolveResult {
  name: string;
  node: string;           // ENSIP-1 namehash
  owner: string;          // current owner address
  resolver: string | null;
  expiresAt: string;      // unix timestamp
  expired: boolean;
  addresses: Record<string, string>; // SLIP-0044 coinType → human-readable address
  texts: Record<string, string>;     // key → value
  contenthash: string | null;
}
```

### getName

Reverse lookup — resolve an address to its primary name.

```ts
const name = await oniym.getName("0x11702b8eF5F882191Af862a7e27096C44A5e2B37");
// "kyy.web3" or null
```

:::warning
This returns the **claimed** name. Always verify forward resolution matches before displaying it as a verified identity.
:::

**Returns:** `string | null`

### getAddress

Resolve a name to an address on a specific chain.

```ts
const eth = await oniym.getAddress("kyy.web3", "eth");
const sol = await oniym.getAddress("kyy.web3", "sol");
```

**Supported chains:** `"btc" | "eth" | "sol" | "sui" | "bnb"`

**Returns:** `string | null`

### getAddresses

Resolve a name to all registered chain addresses at once.

```ts
const all = await oniym.getAddresses("kyy.web3");
// { eth: "0x...", sol: "...", btc: "..." }
```

**Returns:** `Partial<Record<SupportedChain, string>>`

### available

Check if a name is available for registration. Makes a direct RPC call to `RegistrarController.available()`.

```ts
const isAvailable = await oniym.available("alice", "web3");
```

**Returns:** `boolean`

### rentPrice

Get the registration price in wei for a name and duration. Makes a direct RPC call to `RegistrarController.rentPrice()`.

```ts
const price = await oniym.rentPrice("alice", "web3", 365 * 24 * 60 * 60);
console.log(`${Number(price) / 1e18} ETH`);
```

**Parameters:**

* `name` — label only (e.g. `"alice"`)
* `tld` — TLD label (e.g. `"web3"`)
* `duration` — duration in seconds

**Returns:** `bigint` (base + premium combined)


## Utilities

### namehash

Compute an ENSIP-1 namehash for any name.

```ts
oniym.namehash("kyy.web3");
// 0xf7d7c4fb47297d0f2106ac50d24c93063bc0fe50d559ed65e99edb91cc86f8a2

oniym.namehash(""); // 0x0000...0000 (root)
```

Also exported as a standalone function:

```ts
import { namehash } from "@oniym/sdk";
```

### labelhash

keccak256 of a single label string.

```ts
oniym.labelhash("kyy");
// 0x...
```

### makeNode

Compute a child node from a parent node and label. Equivalent to `keccak256(parentNode ‖ labelhash(label))`.

```ts
const web3Node = oniym.namehash("web3");
const kyyWeb3 = oniym.makeNode(web3Node, "kyy");
// same as oniym.namehash("kyy.web3")
```

### parseName

Split a full name into its label and TLD parts. Returns `null` for invalid names.

```ts
oniym.parseName("kyy.web3");   // { label: "kyy", tld: "web3" }
oniym.parseName("kyy");        // null — no TLD
oniym.parseName("sub.kyy.id"); // null — subnames not supported
oniym.parseName(".web3");      // null — empty label
```

### coinTypeFor

Get the SLIP-0044 coin type for a supported chain.

```ts
oniym.coinTypeFor("eth");  // 60
oniym.coinTypeFor("btc");  // 0
oniym.coinTypeFor("sol");  // 501
oniym.coinTypeFor("sui");  // 784
oniym.coinTypeFor("bnb");  // 714
```

### getTLDs

List all 65 supported TLDs with their namehash nodes.

```ts
const tlds = oniym.getTLDs();
// [{ label: "id", node: "0x...", active: true }, ...]
```

### Exported constants

```ts
import {
  COIN_TYPES,       // { btc: 0, eth: 60, sol: 501, ... }
  SUPPORTED_TLDS,   // readonly string[] of all 65 TLD labels
  MAX_TLD_COUNT,    // 65
  MAX_TLD_LENGTH,   // 5
  CHAIN_IDS,        // { baseSepolia: 84532, base: 8453 }
  CONTRACT_ADDRESSES, // deployed addresses per chain
} from "@oniym/sdk";
```


## Getting started

### Installation

:::code-group
```bash [npm]
npm install @oniym/react @oniym/sdk @tanstack/react-query viem
```

```bash [pnpm]
pnpm add @oniym/react @oniym/sdk @tanstack/react-query viem
```
:::

### Setup

Wrap your app with `OniymProvider` and `QueryClientProvider`:

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { OniymProvider } from "@oniym/react";

const queryClient = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <OniymProvider config={{ indexerUrl: "https://api.oniym.xyz" }}>
        {/* your app */}
      </OniymProvider>
    </QueryClientProvider>
  );
}
```

### Usage

```tsx
import { useResolve, useName, useAvailable, useRegister } from "@oniym/react";

function Profile({ address }: { address: string }) {
  const { data: name } = useName(address);
  const { data: result } = useResolve(name ?? undefined);

  return (
    <div>
      <p>{name ?? address}</p>
      <p>Expires: {result?.expiresAt}</p>
    </div>
  );
}

function Register() {
  const { data: available } = useAvailable("alice", "web3");
  const { mutate: register, isPending } = useRegister(undefined); // pass walletClient

  return (
    <button
      disabled={!available || isPending}
      onClick={() => register({ name: "alice", tld: "web3", reverseRecord: true })}
    >
      {isPending ? "Registering..." : "Register alice.web3"}
    </button>
  );
}
```


## useAddresses

Fetch all registered chain addresses for a name.

### Usage

```tsx
import { useAddresses } from "@oniym/react";

function AddressList({ name }: { name: string }) {
  const { data: addresses = {} } = useAddresses(name);

  return (
    <ul>
      {Object.entries(addresses).map(([chain, addr]) => (
        <li key={chain}>{chain}: {addr}</li>
      ))}
    </ul>
  );
}
```

### Parameters

| Parameter | Type                  | Description                                          |
| --------- | --------------------- | ---------------------------------------------------- |
| `name`    | `string \| undefined` | Full name with TLD. Query disabled when `undefined`. |

### Returns

`UseQueryResult<Partial<Record<SupportedChain, string>>>`

Only chains with a record set on-chain are present in the result.

### Query key

`["oniym", "addresses", name]`

***

## useAddress

Fetch the address for a single chain.

### Usage

```tsx
import { useAddress } from "@oniym/react";

function EthAddress({ name }: { name: string }) {
  const { data: address } = useAddress(name, "eth");
  return <span>{address ?? "not set"}</span>;
}
```

### Parameters

| Parameter | Type                  | Description                                 |
| --------- | --------------------- | ------------------------------------------- |
| `name`    | `string \| undefined` | Full name with TLD.                         |
| `chain`   | `SupportedChain`      | `"btc" \| "eth" \| "sol" \| "sui" \| "bnb"` |

### Returns

`UseQueryResult<string | null>`

### Query key

`["oniym", "address", name, chain]`


## useAvailable

Check if a name is available for registration. Makes a live RPC call to `RegistrarController.available()`.

### Usage

```tsx
import { useAvailable } from "@oniym/react";

function AvailabilityBadge({ name, tld }: { name: string; tld: string }) {
  const { data: available, isLoading } = useAvailable(name, tld);

  if (isLoading) return <span>Checking...</span>;
  return <span>{available ? "Available" : "Taken"}</span>;
}
```

### Parameters

| Parameter | Type                  | Description                                                   |
| --------- | --------------------- | ------------------------------------------------------------- |
| `name`    | `string \| undefined` | Label only (e.g. `"alice"`). Query disabled when `undefined`. |
| `tld`     | `string \| undefined` | TLD label (e.g. `"web3"`). Query disabled when `undefined`.   |

### Returns

`UseQueryResult<boolean>`

### Query key

`["oniym", "available", name, tld]`

Stale time is 10 seconds (shorter than other queries since availability can change quickly).


## useName

Reverse lookup — resolve an address to its primary name.

### Usage

```tsx
import { useName } from "@oniym/react";

function Avatar({ address }: { address: string }) {
  const { data: name } = useName(address);

  return <span>{name ?? address}</span>;
}
```

### Parameters

| Parameter | Type                  | Description                                   |
| --------- | --------------------- | --------------------------------------------- |
| `address` | `string \| undefined` | EVM address. Query disabled when `undefined`. |

### Returns

`UseQueryResult<string | null>`

Returns the claimed primary name, or `null` if no reverse record is set.

:::warning
Always verify forward resolution matches before displaying a reverse name as a verified identity.
:::

### Query key

`["oniym", "name", address]`


## useNames

Fetch all names owned by an Ethereum address.

### Usage

```tsx
import { useNames } from "@oniym/react";

function OwnedNames({ address }: { address: string }) {
  const { data: names, isLoading } = useNames(address);

  if (isLoading) return <span>Loading...</span>;

  return (
    <ul>
      {names?.map((n) => (
        <li key={n.node}>{n.name}</li>
      ))}
    </ul>
  );
}
```

### Parameters

| Parameter | Type                  | Description                                   |
| --------- | --------------------- | --------------------------------------------- |
| `address` | `string \| undefined` | EVM address. Query disabled when `undefined`. |

### Returns

`UseQueryResult<OwnedName[]>`

```ts
interface OwnedName {
  name: string;
  node: string;
  expiresAt: string;
  expired: boolean;
}
```

### Query key

`["oniym", "names", address]`


## useRegister

Mutation hook for registering a name. Wraps the full commit-reveal flow from `oniym.register()`.

### Usage

```tsx
import { useRegister, useAvailable, useRentPrice } from "@oniym/react";
import { useWalletClient } from "wagmi"; // or your wallet library

function RegisterForm() {
  const { data: walletClient } = useWalletClient();
  const { data: available } = useAvailable("alice", "web3");
  const { data: price } = useRentPrice("alice", "web3", 365 * 24 * 60 * 60);

  const {
    mutate: register,
    isPending,
    isSuccess,
    error,
  } = useRegister(walletClient);

  return (
    <div>
      <p>Price: {price ? `${Number(price) / 1e18} ETH` : "—"}</p>
      <button
        disabled={!available || isPending || !walletClient}
        onClick={() =>
          register({
            name: "alice",
            tld: "web3",
            duration: 365 * 24 * 60 * 60,
            reverseRecord: true,
            onCommit: (hash) => console.log("Committed:", hash),
            onWaiting: (ms) => console.log(`Waiting ${ms / 1000}s...`),
          })
        }
      >
        {isPending ? "Registering..." : "Register alice.web3"}
      </button>
      {isSuccess && <p>Registered!</p>}
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}
```

### Parameters

| Parameter      | Type                        | Description                                         |
| -------------- | --------------------------- | --------------------------------------------------- |
| `walletClient` | `WalletClient \| undefined` | viem wallet client. Mutation throws if `undefined`. |

### Returns

`UseMutationResult<Hash, Error, RegisterOptions>`

* `mutate(options)` — start registration
* `isPending` — `true` while committing or waiting or registering
* `isSuccess` — `true` after `register()` tx is submitted
* `data` — transaction hash of the `register()` call
* `error` — error if any step failed

### RegisterOptions

See [RegisterOptions](/sdk/registration#registeroptions) in the SDK docs.


## useRentPrice

Fetch the registration price in wei for a name and duration. Makes a live RPC call to `RegistrarController.rentPrice()`.

### Usage

```tsx
import { useRentPrice } from "@oniym/react";
import { formatEther } from "viem";

function PriceDisplay({ name, tld }: { name: string; tld: string }) {
  const duration = 365 * 24 * 60 * 60; // 1 year
  const { data: price } = useRentPrice(name, tld, duration);

  return (
    <span>
      {price !== undefined ? `${formatEther(price)} ETH` : "—"}
    </span>
  );
}
```

### Parameters

| Parameter  | Type                  | Description                                                   |
| ---------- | --------------------- | ------------------------------------------------------------- |
| `name`     | `string \| undefined` | Label only (e.g. `"alice"`). Query disabled when `undefined`. |
| `tld`      | `string \| undefined` | TLD label (e.g. `"web3"`). Query disabled when `undefined`.   |
| `duration` | `number`              | Registration duration in seconds.                             |

### Returns

`UseQueryResult<bigint>`

Returns the total price (base + premium) in wei.

### Query key

`["oniym", "rentPrice", name, tld, duration]`


## useResolve

Fetch all on-chain records for a name.

### Usage

```tsx
import { useResolve } from "@oniym/react";

function NameCard({ name }: { name: string }) {
  const { data, isLoading, error } = useResolve(name);

  if (isLoading) return <p>Loading...</p>;
  if (!data) return <p>Name not found</p>;

  return (
    <div>
      <p>Owner: {data.owner}</p>
      <p>Expires: {new Date(Number(data.expiresAt) * 1000).toLocaleDateString()}</p>
      <p>ETH: {data.addresses["60"] ?? "not set"}</p>
    </div>
  );
}
```

### Parameters

| Parameter | Type                  | Description                                          |
| --------- | --------------------- | ---------------------------------------------------- |
| `name`    | `string \| undefined` | Full name with TLD. Query disabled when `undefined`. |

### Returns

`UseQueryResult<ResolveResult | null>`

See [ResolveResult](/sdk/resolution#resolve) for the full type.

### Query key

`["oniym", "resolve", name]`

Invalidate with `queryClient.invalidateQueries({ queryKey: ["oniym", "resolve", name] })`.


## Architecture

Oniym's contract system follows an ENS-inspired layered architecture adapted for multi-TLD, multichain registration.

### Contract layers

```
┌─────────────────────────────────────────┐
│           RegistrarController           │  ← public entry point
│         (commit-reveal, pricing)        │
└────────────────────┬────────────────────┘
                     │ registers via
         ┌───────────▼───────────┐
         │      TLDManager       │  ← manages all TLD registrars
         └───────────┬───────────┘
                     │ one per TLD
         ┌───────────▼───────────┐
         │    TLDRegistrar(s)    │  ← ERC-721 NFT + expiry
         └───────────┬───────────┘
                     │ setSubnodeRecord
┌────────────────────▼────────────────────┐
│              Registry                   │  ← canonical owner/resolver store
└───────────┬─────────────────────────────┘
            │ resolves via
┌───────────▼───────────┐  ┌──────────────────────┐
│    PublicResolver     │  │   ReverseRegistrar   │
│  (addr, text, hash)   │  │  (address → name)    │
└───────────────────────┘  └──────────────────────┘
```

### Key relationships

* **Registry** is the single source of truth for `node → owner` and `node → resolver`
* **TLDRegistrar** is an ERC-721 where each token = one registered name. Transfer of the NFT triggers a registry sync hook
* **TLDManager** owns the TLD nodes in the registry and deploys a new `TLDRegistrar` for each TLD
* **RegistrarController** is the only address allowed to call `TLDRegistrar.register()` and `TLDRegistrar.renew()`
* **PublicResolver** stores address records, text records, and contenthash per nameNode
* **ReverseRegistrar** owns the `reverse` top-level node and maps `addr.reverse → name`

### Name lifecycle

```
commit() → wait 60s → register() → active → [renew] → expired → grace(90d) → available
```

### Design decisions

See [ADR-001](/adr/001) through [ADR-007](/adr/007) for the reasoning behind each major architectural choice.


## Deployments

### Base Sepolia (testnet)

Chain ID: `84532` · Deployed: 2026-04-28

| Contract             | Address                                      |
| -------------------- | -------------------------------------------- |
| Registry             | `0xc937e37c1FA78b78b154BA5a76249e58C7d9d694` |
| TLDManager           | `0x4A32296ce23155093E94d71A26ffB8617A44baf6` |
| PriceOracle          | `0x7Ff70eA1a39FB0B46e986f6C8AaE5F9Dc9c11E28` |
| RegistrarController  | `0xb0d499a5c8E3Dc9Db30b7c3F685b2D5D8D62F69a` |
| PublicResolver       | `0xE951cE73Da1d75730e56Df79844BFA745FA589D3` |
| ReverseRegistrar     | `0x15536F4306C06Cf14fbD1b76385Ea35Fb31F4FA4` |
| USDC (Circle native) | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |

All 72 contracts (6 core + 1 USDC reference + 65 TLD registrars) deployed on Base Sepolia.

:::info
This deployment includes **ADR-008 dual-payment support** — both ETH and native USDC are accepted for registration and renewal.
:::

### Base Mainnet

Coming in Sprint 8.


## PublicResolver

Stores address records, text records, and contenthash for registered names. Implements ENSIP-9 multichain addressing.

**Address (Base Sepolia):** `0xA37eD413181537c60586317a70f612a304EB0681`

### Address records

Addresses are stored per SLIP-0044 coin type.

```solidity
// Write
function setAddr(bytes32 node, uint256 coinType, bytes calldata addr) external;

// Read
function addr(bytes32 node, uint256 coinType) external view returns (bytes memory);
```

Common coin types:

| Chain           | Coin type |
| --------------- | --------- |
| Ethereum / Base | `60`      |
| Bitcoin         | `0`       |
| Solana          | `501`     |
| Sui             | `784`     |
| BNB             | `714`     |

### Text records

```solidity
// Write
function setText(bytes32 node, string calldata key, string calldata value) external;

// Read
function text(bytes32 node, string calldata key) external view returns (string memory);
```

Common keys: `avatar`, `description`, `url`, `twitter`, `github`, `email`

### Contenthash

```solidity
function setContenthash(bytes32 node, bytes calldata hash) external;
function contenthash(bytes32 node) external view returns (bytes memory);
```

### Events

| Event                               | When                   |
| ----------------------------------- | ---------------------- |
| `AddrChanged(node, coinType, addr)` | Address record updated |
| `TextChanged(node, key, value)`     | Text record updated    |
| `ContenthashChanged(node, hash)`    | Contenthash updated    |


## RegistrarController

The public entry point for name registration. Enforces commit-reveal, pricing, and name validation. Accepts ETH or USDC as payment.

**Address (Base Sepolia):** `0x8CaD65fb525D709fF32Ec96b020Eb90e3Cb212F0`

### Constants

| Constant             | Value        |
| -------------------- | ------------ |
| `MIN_COMMITMENT_AGE` | 60 seconds   |
| `MAX_COMMITMENT_AGE` | 24 hours     |
| `MIN_NAME_LENGTH`    | 3 characters |

### Registration flow

```
1. makeCommitment(req)            → bytes32 commitment hash (pure, off-chain)
2. commit(commitment)             → stores timestamp on-chain
3. wait ≥ 60 seconds
4. register(req, paymentToken)   → mints name, sets resolver data, transfers NFT
```

### Payment

Pass `paymentToken` to choose how to pay:

| `paymentToken` | Behaviour                                                                      |
| -------------- | ------------------------------------------------------------------------------ |
| `address(0)`   | ETH — `msg.value` must cover quoted price; excess refunded                     |
| USDC address   | USDC — caller must `approve` first; exact USD amount pulled via `transferFrom` |

USDC price is exact (no Chainlink feed needed) — `$3.000000` for 30 days, `$15.000000` for 1 year.

### Key functions

```solidity
struct RegisterRequest {
    string name;          // label only, e.g. "alice"
    bytes32 tld;          // namehash of TLD, e.g. namehash("web3")
    address owner;
    uint256 duration;     // seconds
    bytes32 secret;       // random 32 bytes
    address resolver;
    bytes[] resolverData; // encoded setAddr/setText calls
    bool reverseRecord;   // set reverse record at registration
}

// paymentToken: address(0) = ETH, USDC address = stablecoin
function register(RegisterRequest calldata req, address paymentToken) external payable;
function renew(string calldata name, bytes32 tld, uint256 duration, address paymentToken)
    external payable;

function makeCommitment(RegisterRequest calldata req) external pure returns (bytes32);
function commit(bytes32 commitment) external;
function rentPrice(string calldata name, bytes32 tld, uint256 duration)
    external view returns (uint256 base, uint256 premium);
function available(string calldata name, bytes32 tld) external view returns (bool);

// Owner only
function withdrawEth(address to) external;
function withdrawToken(address token, address to) external;

// Immutable
function USDC_TOKEN() external view returns (address);
```

### Name validation

* Minimum 3 characters
* Lowercase ASCII letters (`a-z`), digits (`0-9`), and hyphens (`-`)
* No leading or trailing hyphens


## Registry

The Registry is the canonical on-chain store mapping name nodes to owners and resolvers.

**Address (Base Sepolia):** `0x4d0203cf6188247c282f1ee1b866ea55f71aabe4`

### Key functions

```solidity
// Read
function owner(bytes32 node) external view returns (address);
function resolver(bytes32 node) external view returns (address);
function ttl(bytes32 node) external view returns (uint64);

// Write (owner only)
function setOwner(bytes32 node, address owner) external;
function setResolver(bytes32 node, address resolver) external;
function setSubnodeOwner(bytes32 node, bytes32 label, address owner) external returns (bytes32);
function setSubnodeRecord(bytes32 node, bytes32 label, address owner, address resolver, uint64 ttl) external returns (bytes32);
```

### Access control

Each node is controlled by its owner. Only the owner of a node can:

* Transfer ownership (`setOwner`)
* Change the resolver (`setResolver`)
* Create subnodes (`setSubnodeOwner`, `setSubnodeRecord`)

### Events

| Event                          | When              |
| ------------------------------ | ----------------- |
| `Transfer(node, owner)`        | Ownership changes |
| `NewResolver(node, resolver)`  | Resolver changes  |
| `NewOwner(node, label, owner)` | Subnode created   |


## ReverseRegistrar

Manages reverse records — mapping an Ethereum address to its claimed primary name.

**Address (Base Sepolia):** `0xa5d904401d5f3ed1eb19188ce9de28bef3c083b9`

### How it works

The `ReverseRegistrar` owns the `reverse` top-level node in the Registry. For each address, it creates a subnode under `addr.reverse` where the name text record is stored.

Reverse node for an address:

```
namehash("<lowercase_address>.addr.reverse")
```

### Setting a reverse record

The easiest way is to pass `reverseRecord: true` when registering via `RegistrarController`. This sets the reverse record atomically in the same transaction.

To set it separately:

```solidity
function setName(string calldata name) external returns (bytes32);
function setNameForAddr(
    address addr,
    address owner,
    address resolver,
    string calldata name
) external returns (bytes32);
```

### Verification

The indexer returns `verified: false` on all reverse lookups — clients are responsible for verifying that:

```
forward_resolve(reverse_record.name) == address
```

Only show the name as a verified identity if this check passes.

### Grace period

Reverse records are not automatically cleared when a name expires. If a name expires and is re-registered by someone else, the old reverse record will still exist but forward resolution will no longer match — clients will catch this via the verification step.


## GET /lookup/:address

Reverse lookup — resolve an Ethereum address to its claimed primary name.

:::warning
This returns the **claimed** name. Always verify that forward resolution of the returned name points back to the same address before displaying it as a verified identity.
:::

### Request

```
GET /lookup/0x11702b8eF5F882191Af862a7e27096C44A5e2B37
```

### Response

```json
{
    "address": "0x11702b8eF5F882191Af862a7e27096C44A5e2B37",
    "name": "kyy.web3",
    "reverseNode": "0x...",
    "verified": false
}
```

#### Fields

| Field         | Type             | Description                                                 |
| ------------- | ---------------- | ----------------------------------------------------------- |
| `address`     | `string`         | Input address (checksummed)                                 |
| `name`        | `string \| null` | Claimed primary name, or `null`                             |
| `reverseNode` | `string`         | The reverse node hash                                       |
| `verified`    | `boolean`        | `true` if forward resolution of `name` returns this address |

### Errors

| Status | Body                                      | Reason                                     |
| ------ | ----------------------------------------- | ------------------------------------------ |
| `400`  | `{ "error":" Name not found" }`           | Name not found for current registered data |
| `400`  | `{ "error": "Invalid Ethereum address" }` | Not a valid EVM address                    |
| `404`  | `{ "error": "No reverse record found" }`  | No reverse record set                      |
| `429`  | `{ "error": "Rate limit exceeded" }`      | Too many requests                          |


## GET /names/:address

List all names owned by an Ethereum address.

### Request

```
GET /names/0x11702b8eF5F882191Af862a7e27096C44A5e2B37
```

### Response

```json
{
  "address": "0x11702b8eF5F882191Af862a7e27096C44A5e2B37",
  "names": [
    {
      "name": "kyy.web3",
      "node": "0x...",
      "expiresAt": "1777179607",
      "expired": false
    },
    {
      "name": "kite.app",
      "node": "0x...",
      "expiresAt": "1779771607",
      "expired": false
    }
  ]
}
```

#### Fields

| Field     | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `address` | `string` | Input address                             |
| `names`   | `array`  | All names currently owned by this address |

#### Name object

| Field       | Type      | Description                      |
| ----------- | --------- | -------------------------------- |
| `name`      | `string`  | Full name e.g. `kyy.web3`        |
| `node`      | `string`  | Namehash of the name             |
| `expiresAt` | `string`  | Unix timestamp (seconds)         |
| `expired`   | `boolean` | Whether the registration expired |

### Errors

| Status | Body                                      | Reason                  |
| ------ | ----------------------------------------- | ----------------------- |
| `400`  | `{ "error": "Invalid Ethereum address" }` | Not a valid EVM address |
| `429`  | `{ "error": "Rate limit exceeded" }`      | Too many requests       |


## Indexer API

The Oniym indexer is a [Ponder](https://ponder.sh) application that reads on-chain events and exposes a REST API for fast off-chain queries.

### Base URL

| Environment            | URL                      |
| ---------------------- | ------------------------ |
| Local dev              | `https://api.oniym.xyz/` |
| Testnet (Base Sepolia) | Coming soon              |

### Rate limiting

100 requests per 60 seconds per IP (enforced via Redis). Returns `429` when exceeded.

### Endpoints

| Method | Path                              | Description                              |
| ------ | --------------------------------- | ---------------------------------------- |
| `GET`  | [`/resolve/:name`](/api/resolve)  | Resolve a name to all its records        |
| `GET`  | [`/lookup/:address`](/api/lookup) | Reverse lookup — address to claimed name |
| `GET`  | [`/names/:address`](/api/names)   | List all names owned by an address       |

### Caching

Responses are cached in Redis for 60 seconds. Expired names are never cached.


## GET /resolve/:name

Resolve a name to all its on-chain records.

### Request

```
GET /resolve/kyy.web3
```

### Response

```json
{
  "name": "kyy.web3",
  "node": "0xf7d7c4fb47297d0f2106ac50d24c93063bc0fe50d559ed65e99edb91cc86f8a2",
  "owner": "0x11702b8ef5f882191af862a7e27096c44a5e2b37",
  "resolver": "0xe951ce73da1d75730e56df79844bfa745fa589d3",
  "expiresAt": "1808715608",
  "expired": false,
  "addresses": {
    "60": "0x11702b8ef5f882191af862a7e27096c44a5e2b37",
    "501": "7xKb3n36GAJ5jG5aG9Q8p6H3r4Y2Z1WjK9nLcXdE5gTf",
    "0": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  },
  "texts": {
    "twitter": "@kyy"
  },
  "contenthash": null
}
```

#### Fields

| Field         | Type                     | Description                                                                                                                                                                                                       |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | `string`                 | Full name with TLD                                                                                                                                                                                                |
| `node`        | `string`                 | ENSIP-1 namehash (bytes32 hex)                                                                                                                                                                                    |
| `owner`       | `string`                 | Current owner address                                                                                                                                                                                             |
| `resolver`    | `string \| null`         | Resolver contract address                                                                                                                                                                                         |
| `expiresAt`   | `string`                 | Unix timestamp of expiry                                                                                                                                                                                          |
| `expired`     | `boolean`                | Whether the name is expired                                                                                                                                                                                       |
| `addresses`   | `Record<string, string>` | SLIP-0044 coin type → human-readable address. ETH (coinType `60`) is a checksummed hex address; all other chains (SOL `501`, BTC `0`, SUI `784`, BNB `714`) are their native string format (base58, bech32, etc.) |
| `texts`       | `Record<string, string>` | Text record key → value map                                                                                                                                                                                       |
| `contenthash` | `string \| null`         | Raw contenthash hex                                                                                                                                                                                               |

#### Address encoding

On-chain, all addresses are stored as raw bytes in `PublicResolver.setAddr()`. The indexer decodes them before serving:

* **ETH (coinType 60):** 20-byte EVM address → returned as `0x`-prefixed hex
* **All other chains:** bytes decoded as UTF-8 → returned as the original human-readable string (Solana base58, Bitcoin bech32, etc.)

### Errors

| Status | Body                                                     | Reason                         |
| ------ | -------------------------------------------------------- | ------------------------------ |
| `400`  | `{ "error": "Invalid name format. Expected label.tld" }` | Malformed name                 |
| `404`  | `{ "error": "Name not found" }`                          | Name not registered or indexed |
| `429`  | `{ "error": "Rate limit exceeded" }`                     | Too many requests              |


## ADR-002: ENSIP-1 namehash compatibility

* **Status:** Accepted
* **Date:** 2026-04-22
* **Deciders:** Core team

### Context

Every name in Oniym is keyed by a 32-byte node identifier. The algorithm for deriving this identifier from a human-readable name must be chosen up front — changing it later breaks every integration.

Two approaches were considered:

1. **ENSIP-1 namehash** — the algorithm used by ENS (recursive right-to-left keccak256).
2. **Custom algorithm** — e.g. flat keccak256 of the full name, or a Merkle-based scheme.

### Decision

**Adopt ENSIP-1 namehash unchanged.**

### Rationale

1. **Zero learning curve for developers** — anyone who has worked with ENS can integrate Oniym immediately. The resolver interface, node derivation, and subdomain semantics are all identical.

2. **Tooling compatibility** — existing libraries (viem, ethers, web3.py) already ship namehash implementations. We inherit test vectors, edge-case handling, and battle-testing.

3. **Hierarchical subdomains are trivially supported** — `wallet.kyy.id` is a natural extension, and subdomain ownership can be delegated without custom logic.

4. **Future L1 interop** — if we ever expose Oniym names as `.eth` via CCIP-Read, the node format must match ENS.

5. **Cryptographic soundness is already established** — keccak256 collision resistance plus recursive structure = well-understood security properties.

### Consequences

#### Positive

* Interoperable with any ENS-compatible wallet, library, or dApp
* Reuses standard normalization (UTS-46) — we don't reinvent it
* Shared mental model reduces documentation burden

#### Negative

* We inherit ENS's choices, including some minor inefficiencies (e.g. recursive hashing is not the tightest possible encoding)
* If ENS updates the spec, we may need to track changes

#### Mitigations

* Implementation is in a small, pure library (`Namehash.sol`) — easy to audit
* Test vectors are pinned to ENS canonical values; any drift is caught in CI

### Reference implementation

See `contracts/src/lib/Namehash.sol` and `sdk/src/namehash.ts`. A parity test ensures Solidity and TypeScript produce identical output.

### References

* [ENSIP-1](https://docs.ens.domains/ensip/1)
* [UTS-46 name normalization](https://unicode.org/reports/tr46/)


## ADR-003: Monorepo with pnpm workspaces

* **Status:** Accepted
* **Date:** 2026-04-22
* **Deciders:** Core team

### Context

Oniym has four deliverable artifacts:

1. **Smart contracts** — Solidity + Foundry
2. **Indexer** — TypeScript + Ponder + Postgres
3. **SDK** — TypeScript library for developers
4. **Web app** — Next.js frontend

These artifacts share types, ABIs, and constants. Options:

* **Multi-repo** — one repo per artifact, publish shared packages to npm
* **Monorepo (pnpm)** — all artifacts in one repo, use workspace protocol
* **Monorepo (Turborepo/Nx)** — heavier orchestration tooling

### Decision

**Single monorepo with pnpm workspaces. No Turborepo/Nx initially.**

### Rationale

1. **Type safety across boundaries** — generated contract ABIs and types flow directly from `contracts/` → `sdk/` → `web/` without a publish cycle.

2. **Atomic changes** — a contract change + matching SDK update + UI update is one PR, not three.

3. **Simpler for a solo/small team** — no cross-repo PR coordination, no version skew.

4. **pnpm is fast enough** — for our project size, we don't need Turborepo's caching. We can add it later if build times grow.

5. **Standard tooling** — `pnpm -r build` orchestrates all workspaces. No custom task runner config.

### Consequences

#### Positive

* Single `pnpm install` bootstraps everything
* Shared `tsconfig`, `prettier`, `eslint` config at root
* Contract ABIs consumed directly via workspace protocol (`workspace:*`)
* CI can test the whole system in one job

#### Negative

* Repo is larger (clone takes longer)
* Contributors see all artifacts even if they only care about one
* Published packages need careful `files` field in `package.json` to avoid leaking internal code

#### Mitigations

* `files` allowlist in each package's `package.json`
* Clear README in each workspace explaining its scope
* GitHub CODEOWNERS (future) for per-area review

### Structure

```
oniym/
├── contracts/       # Foundry project (not a pnpm workspace)
├── indexer/         # Workspace
├── sdk/             # Workspace (published to npm as @oniym/sdk)
├── web/             # Workspace (not published)
├── examples/*       # Workspaces (not published)
├── docs/
├── security/
├── package.json     # Root, workspaces config
├── pnpm-workspace.yaml
└── .github/workflows/
```

Note: `contracts/` is managed by Foundry (not pnpm) — it has its own dependency system via `forge install`. We coordinate via build scripts.

### References

* [pnpm workspaces](https://pnpm.io/workspaces)


## ADR-004: Foundry as contract toolchain

* **Status:** Accepted
* **Date:** 2026-04-22
* **Deciders:** Core team

### Context

Every Solidity project needs a build + test + deploy toolchain. The two mainstream options are:

1. **Foundry** — Rust-based, tests written in Solidity, extremely fast, native fuzzing
2. **Hardhat** — Node.js-based, tests written in JS/TS, large plugin ecosystem

### Decision

**Foundry as the primary contract toolchain. No Hardhat.**

### Rationale

1. **Tests in Solidity** — contract tests written in the same language as the contracts means no type juggling, no ABI serialization in tests, and full access to cheatcodes (`vm.prank`, `vm.expectRevert`, `vm.warp`). This is a meaningful correctness win.

2. **Speed** — `forge test` runs 10-100× faster than Hardhat for equivalent suites. For a project with fuzz + invariant tests running tens of thousands of cases, this matters.

3. **Native fuzzing and invariant testing** — property-based testing is first-class in Foundry. For a naming protocol where "no one can steal another user's name" is an invariant, this is essential.

4. **Gas snapshots built in** — `forge snapshot` tracks gas usage per test, catching regressions in CI automatically.

5. **Active development** — Foundry is the modern default for serious protocols (Uniswap v4, Morpho, Optimism, ENS tooling) and continues to ship improvements.

6. **Simpler mental model** — no separate JS test runner, no `hardhat.config.ts` with plugin juggling. Just `foundry.toml` and `.sol` files.

### Consequences

#### Positive

* Fast iteration loop (tests run in under a second for unit suites)
* Property-based testing as a first-class citizen
* Gas benchmarks automated in CI
* Smaller dependency footprint

#### Negative

* Deployment scripts written in Solidity can be awkward for complex orchestration
* Less mature plugin ecosystem vs Hardhat (e.g. no equivalent to OpenZeppelin Defender integration)
* Rust toolchain requirement may be novel for some contributors

#### Mitigations

* For multi-chain orchestrated deploys, we can supplement with a thin TypeScript deploy script using viem directly — no need to pull in Hardhat
* `foundryup` installer is a single command and well-documented
* Our CI pins a specific Foundry nightly version to avoid drift

### Scope note

This ADR applies to the `contracts/` workspace. TypeScript tooling (for indexer, SDK, web) is unaffected.

### References

* [Foundry Book](https://book.getfoundry.sh)
* [Foundry vs Hardhat comparison (Paradigm)](https://www.paradigm.xyz/2021/12/introducing-the-foundry-ethereum-development-toolbox)


## ADR-005: Playriglabs-first branding

* **Status:** Accepted
* **Date:** 2026-04-22
* **Deciders:** Core team

### Context

Oniym is being built by [Playriglabs](https://playriglabs.fun), a Web3 & AI product consultancy. At the point of public launch, we need to decide how Oniym is branded and attributed:

1. **Oniym as standalone brand** — Playriglabs invisible in public surface
2. **Oniym by Playriglabs** — co-branded, both visible
3. **Playriglabs-first** — Oniym as a product line within the Playriglabs portfolio

This affects:

* GitHub org and repo URL
* NPM scope
* Copyright attribution
* Landing page messaging
* Social presence and launch narrative

### Decision

**Playriglabs-first: Oniym is positioned as a product line within the Playriglabs portfolio.**

* Repo lives at `github.com/playriglabs/oniym`
* Copyright held by Playriglabs
* Landing page and README explicitly attribute to Playriglabs
* NPM scope remains `@oniym/*` for product-level discoverability
* Domain `oniym.xyz` is retained for product identity

### Rationale

1. **Builds Playriglabs as a "builder, not just consultant" brand.** Shipping a real production protocol is the strongest possible proof point for a consultancy. Clients evaluating Playriglabs see evidence of shipped work, not just deck-ware.

2. **Unifies future products under one umbrella.** If Playriglabs ships additional products in the future, they fit cleanly into the same portfolio without fragmenting brand equity.

3. **Simplifies legal and operational surface area.** One copyright holder, one liability boundary, one set of legal documents reusable across products.

4. **Enhances the team's storytelling.** Public narrative becomes "Playriglabs ships Oniym" rather than "solo side project." This matters for team credibility, hiring, and client trust.

5. **Preserves product-level identity where it matters.** NPM scope `@oniym/*` and domain `oniym.xyz` ensure developers and users still interact with the product on its own terms. Branding attribution happens at the README, landing page, and footer level — not at the import path.

#### Positive

* Playriglabs gains a concrete case study
* Oniym benefits from Playriglabs' professional association
* Clear hierarchy for future products under the same org
* Single legal entity simplifies revenue handling and contracts

#### Negative

* Users must make two connections ("Oniym" and "Playriglabs") to understand provenance
* If Oniym outgrows Playriglabs as a standalone venture, a future brand split requires migration work

#### Mitigations

* Co-branding at visible surfaces (README, landing page footer, launch posts) keeps both identities clear
* NPM scope and domain are independent of company — future spin-off is possible without changing developer-facing identifiers
* ADR is revisited if product traction warrants separation

### References

* [Playriglabs](https://playriglabs.fun)
* [Oniym product site](https://oniym.xyz)


## ADR-006: Pricing model and controller design

* **Status:** Accepted
* **Date:** 2026-04-22
* **Deciders:** Core team

### Context

Oniym's economic and operational model requires decisions on four axes:

1. **Pricing tiers** — flat-rate vs length-based premiums (ENS-style)
2. **Emergency controls** — should the controller be pausable?
3. **Registration atomicity** — single tx or multi-tx setup?
4. **Reverse resolution** — opt-in at registration, or post-registration only?

Each choice affects user experience, security posture, and protocol positioning.

### Decisions

#### 1. Two-tier pricing for all registrable lengths

* Minimum length: 3 characters
* **Monthly rate:** $3.00 per 30 days — for registrations under 1 year
* **Annual rate:** $15.00 per year — for registrations of 1 year or more (saves $21 vs 12× monthly)
* All prices paid in ETH at Chainlink spot, regardless of name length
* Billed by duration in seconds — users can register for any duration
* No post-expiry premium decay (future work)

#### 2. OpenZeppelin Pausable on ETHRegistrarController only

* `commit()`, `register()`, `renew()` are pausable
* `Registry` and `BaseRegistrar` are NOT pausable
* Pause controlled by protocol owner (multisig initially, DAO later)

#### 3. Multicall resolver data in registration

* `register()` accepts `bytes[] resolverData` to batch setAddr/setText calls
* Empty array → no resolver setup (user handles later)
* Non-empty → controller loops and calls resolver atomically

#### 4. Opt-in reverse record at registration

* `register()` accepts `bool reverseRecord`
* If true, controller sets reverse record via `IReverseRegistrar.setNameForAddr`
* If false, user can set reverse record later (or not at all)

### Rationale

#### Two-tier pricing

**Positioning:** ENS charges $5/$160/$640 for 5+/4/3-char names. Oniym's $3/month and $15/year is a clear differentiator — "the affordable multichain alternative." This matters for Base's price-sensitive user base and emerging-market targeting.

**Why two tiers:** A single flat annual rate forces users to commit $15 upfront to try the protocol. A $3/month entry point lowers the trial barrier significantly. Users who commit annually save $21 vs paying monthly — rewarding loyalty without penalizing newcomers.

**Squatting reality:** Short names will be squatted on launch regardless of tier. Premium pricing only shifts *who* squats (capitalized squatters) vs *when* they squat. Accept the outcome and move on.

**Revenue expectations:** With 1000 annual registrations at $15/year, annual revenue is \~$15K. With mixed monthly/annual registrations the blended rate is higher. Pricing is intentionally accessible to maximize adoption over revenue.

**Future flexibility:** The `IPriceOracle` interface preserves the `Price` struct with `base + premium`. Owner can update `monthlyPriceUsd` and `annualPriceUsd` at any time via `setMonthlyPrice()` and `setAnnualPrice()` without redeploying the controller.

#### Pausable on controller

**Defense layering:** Combined with `removeController()` on the registrar, this gives three response modes for bugs:

| Severity                 | Response                         | Time    |
| ------------------------ | -------------------------------- | ------- |
| Bug in controller logic  | Pause, fix, unpause              | hours   |
| Severe bug in controller | `removeController()`, deploy new | \~1 day |
| Bug in ownership layer   | No recovery — immutable          | —       |

**Why not pause Registry/Registrar:** The ownership layer must remain functional even during incidents. Users must always be able to transfer or resolve their names. Pausing ownership = bricking user assets temporarily, which is unacceptable.

**Governance constraint:** The pause power is a centralization trade-off. Mitigation: multisig with timelock on the owner role, visible pause events, published criteria for when pause will be used.

#### Multicall resolver data

**UX impact:** Without it, registration is a 6-tx flow:

1. `commit()`
2. `register()`
3. `setAddr()` for ETH
4. `setAddr()` for Solana
5. `setAddr()` for Bitcoin
6. `setText()` for avatar

With it, steps 3-6 collapse into step 2. User experiences it as "register and I'm done." For a naming protocol, this is a major UX win.

**Gas cost:** \~5-10K extra gas per extra call (mostly calldata). Total registration cost stays under 250K gas on Base, still well under $0.50 at typical gas prices.

**Security consideration:** The controller performs `bytes` multicall to the resolver. Implementation MUST validate that the resolver address matches the one set in the Registry to prevent cross-contract privilege escalation. Documented in threat model.

#### Opt-in reverse record at registration

**Why not default-true:** Users on shared wallets (team multisigs, smart accounts) may not want the wallet address to resolve to a personal name. Opt-in respects user choice.

**Why not default-false:** The large majority of users *want* reverse resolution and won't know to set it manually later. Exposing as a flag makes it discoverable and one-click.

**ENS precedent:** ENS registrar v0.3+ uses this same pattern. Copying proven UX is valuable.

### Consequences

#### Positive

* Simpler pricing logic reduces oracle attack surface
* Pausable is industry-standard and reviewer-friendly
* Atomic registration is competitive with ENS's latest UX
* Opt-in reverse respects user autonomy

#### Negative

* Flat pricing leaves premium revenue on the table for short names
* Pausable introduces centralization surface (addressed via timelock)
* Multicall increases complexity slightly and requires careful validation
* Reverse record requires deploying `ReverseRegistrar` and wiring controller authorization (additional scope)

#### Mitigations

* Pause power ownership transitions to multisig before mainnet, DAO after
* Reserve ability to migrate to tiered pricing post-launch (oracle swap)
* Multicall validation is unit-tested with malicious resolver inputs
* Reverse record flag defaults to false if resolver is not set

### References

* [ENSIP-16: Record Versioning](https://docs.ens.domains/ensip/16)
* [ENS ETHRegistrarController v0.3](https://github.com/ensdomains/ens-contracts/blob/main/contracts/ethregistrar/ETHRegistrarController.sol)
* [OpenZeppelin Pausable](https://docs.openzeppelin.com/contracts/5.x/api/utils#Pausable)


## ADR-007: Multi-TLD naming and Clusters-style identity

* **Status:** Accepted
* **Date:** 2026-04-24
* **Deciders:** Core team
* **Supersedes:** Parts of ADR-002, ADR-005 (drops `.oniym` as the single TLD)

### Context

The original design committed to a single proprietary TLD — `.oniym` — following the ENS/Basenames playbook. After reviewing the competitive landscape, two products demonstrate a superior model:

* **[Space.ID](https://www.space.id/tld)** — aggregates multiple TLDs (`.bnb`, `.arb`, `.eth`) under one protocol and one SDK. Users pick the TLD that matches their primary chain identity.
* **[Clusters](https://clusters.xyz)** — a chain-agnostic name (`kyy`, no TLD) that maps to all chain addresses at once. SDK is minimal: `clusters.getName(address)` returns the name.

A single `.oniym` TLD has three weaknesses:

1. **Cold brand with no community.** `.oniym` carries zero recognition. Web-style TLDs like `.id`, `.degen`, `.wagmi` are immediately legible to web3 users — no onboarding cost.
2. **Forces brand-first identity over personal identity.** Users want to express *who they are*, not what protocol they use. `.wagmi.id` says something; `.wagmi.oniym` is just an ad.
3. **Misses the multi-TLD aggregation opportunity.** Space.ID already proves the model works at scale.

### Decision

**Drop `.oniym` as the sole TLD. Adopt a multi-TLD model inspired by Space.ID, with a unified-identity resolver and simplified SDK inspired by Clusters.**

#### TLDs offered (protocol-controlled)

62 web-style, chain-neutral labels — max 5 characters each:

```
.id   .one  .me   .xyz  .web3 .io   .app  .dev  .onm  .go
.ape  .fud  .hodl .fomo .moon .rekt .wagmi .ngmi .degen .whale
.buidl .dyor .pump .alpha .safu .gm  .lfg  .ser  .fren .goat
.cope .pepe .mint .bear .gas  .dao  .ath  .dex  .cex  .burn
.node .swap .yield .bag  .bags .seed .drop .stake .pool .wrap
.farm .shill .xxx  .regs .main .test .exit .fair .guh  .bots
.vcs  .keys
```

TLD labels are intentionally **not** chain names. TLD choice is a pure identity preference — any TLD name resolves addresses for all supported chains (ETH, SOL, BTC, SUI, BNB) via SLIP-0044 coin type in the resolver.

Additional TLDs can be added via `ITLDManager.addTld()` without touching the Registry or Resolver.

#### Key design principles (Clusters-style)

* **TLD is an identity preference, not a chain restriction.** A `.degen` name stores ETH, SOL, BTC, SUI, and BNB addresses in the same resolver node. Any TLD resolves across all chains.
* **One resolver, all TLDs.** The existing `Resolver.sol` is already node-based (`bytes32`) — it handles every TLD with no changes.
* **Simplified SDK API.** `new Oniym()` exposes `getName(address)`, `getAddress(name, chain)`, `getAddresses(name)` — the same ergonomics as the Clusters SDK.

#### New contract: `ITLDManager`

Protocol-owned contract managing the live set of TLDs. Owns each TLD's root node in the Registry. Authorizes per-TLD `ITLDRegistrar` deployments. New TLDs are added via a single `addTld()` call — no Registry or Resolver changes needed. Constants: `maxTldCount() = 62`, `maxTldLabelLength() = 5`.

#### Renamed / refactored contracts

| Old                       | New                    | Reason                                             |
| ------------------------- | ---------------------- | -------------------------------------------------- |
| `IBaseRegistrar`          | `ITLDRegistrar`        | Generic; parameterized by TLD node at construction |
| `IETHRegistrarController` | `IRegistrarController` | `ETH` prefix implied chain-specificity             |

`RegisterRequest` gains a `tld` field (`bytes32`, the namehash of the TLD label) so one controller can service all TLDs.

### Rationale

1. **Web-style TLDs are chain-neutral by design.** `.id`, `.one`, `.wagmi` carry no chain assumption — a Solana-native and an ETH-native user are both comfortable picking from this list.
2. **Multi-TLD aggregation is the winning model.** Space.ID at scale proves that a single SDK over multiple TLDs is more valuable than any one naming service.
3. **Clusters proves simplified API drives adoption.** `getName(address)` is a one-liner that any dApp can drop in. Lower integration friction = more integrations.
4. **Registry and Resolver are already TLD-agnostic.** Core on-chain logic uses `bytes32` node everywhere — the pivot costs almost nothing in contract changes.
5. **Timing is right.** Contracts are in Week 1 (interface-only). No implementation to rewrite.
6. **No ENS collision risk.** Using web-style labels (not `.eth`, `.sol`) eliminates any namespace confusion with existing naming services.

### Consequences

#### Positive

* No collision with ENS, SNS, or any existing naming service — all TLD labels are novel
* Any future TLD is addable via `addTld()` without touching Registry or Resolver
* SDK API is simpler and more adoptable than the original design
* No proprietary `.oniym` cold-start — web-style TLDs feel familiar across all web3 communities
* Culture-first TLDs (`.degen`, `.wagmi`, `.hodl`) create natural community identity

#### Negative

* Web-style TLDs don't carry chain-native recognition (trade-off vs. the original chain-TLD model)
* 62 TLDs increase `ITLDManager` admin surface
* `kyy.id` and `kyy.one` are distinct registry records — no automatic cross-TLD identity linking in v1

#### Mitigations

* Docs and UI make chain resolution explicit: any name resolves all chains regardless of TLD label
* `ITLDManager` owner is a multisig from day one
* Cross-TLD identity bundle (`kyy.*`) is a planned post-launch feature

### References

* [Space.ID TLD model](https://www.space.id/tld)
* [Clusters](https://clusters.xyz) · [Clusters docs](https://docs.clusters.xyz)
* [ADR-002: ENSIP-1 Namehash](/adr/002)
* [ADR-005: Playriglabs-first branding](/adr/005)
* [ADR-006: Pricing and controller design](/adr/006)


## ADR-008: Dual-payment support (ETH + USDC)

* **Status:** Accepted
* **Date:** 2026-04-28
* **Deciders:** Core team

### Context

`RegistrarController` currently accepts only native ETH (`msg.value`) for registration and renewal. `PriceOracle` quotes prices in wei via a Chainlink ETH/USD feed.

Three problems with ETH-only payments on Base:

1. **Price volatility for users.** A $3/month registration costs different amounts of ETH week to week. Users who think in dollars must check the ETH price before every transaction.
2. **Base is a USDC-native ecosystem.** Circle's native USDC is widely held on Base. Many Base users hold USDC as their primary spending asset, not ETH.
3. **UX friction for non-crypto-native users.** Target users (emerging markets, newcomers) are more familiar with stable dollar amounts than fluctuating ETH values.

### Decision

**Add USDC as a parallel payment option alongside ETH. ETH remains the default. Neither removes the other.**

#### How it works

`register()` and `renew()` accept an optional `paymentToken` parameter:

* `address(0)` → ETH path (current behavior, unchanged)
* `USDC_ADDRESS` → USDC path (new)

```solidity
function register(
    RegisterRequest calldata req,
    address paymentToken   // address(0) = ETH, USDC address = stablecoin
) external payable whenNotPaused {
    uint256 total = _totalPrice(req.name, req.tld, req.duration);

    if (paymentToken == address(0)) {
        // ETH path — existing behavior
        if (msg.value < total) revert InsufficientValue(total, msg.value);
        if (msg.value > total) _refundExcess(msg.sender, msg.value - total);
    } else if (paymentToken == USDC) {
        // USDC path — price in 6-decimal USD units
        uint256 usdcAmount = _toUsdc(total);
        IERC20(USDC).transferFrom(msg.sender, address(this), usdcAmount);
    } else {
        revert UnsupportedPaymentToken(paymentToken);
    }
    // ... rest of registration logic unchanged
}
```

#### Price conversion for USDC

`PriceOracle` already calculates `basePriceUsd` in 1e8 units. For USDC (6 decimals):

```
usdcAmount = basePriceUsd * duration / (YEAR * 1e2)
```

No Chainlink feed needed for USDC — it is already denominated in USD. This eliminates oracle risk for the USDC path entirely.

#### User flow (USDC)

1. User approves USDC spend: `USDC.approve(controller, amount)`
2. User calls `register(req, USDC_ADDRESS)` — no `msg.value` needed
3. Controller calls `transferFrom` → pulls USDC from user
4. Name minted, records set — identical to ETH path from here

**Or with EIP-2612 Permit (single tx):**

1. User signs an off-chain permit message (no approve tx)
2. Web app calls `USDC.permit(...)` then `register(req, USDC_ADDRESS)` in one batched call via multicall wrapper

#### Withdraw

Protocol owner can withdraw both ETH and USDC via separate `withdraw()` functions:

```solidity
function withdrawEth(address to) external onlyOwner { ... }
function withdrawToken(address token, address to) external onlyOwner { ... }
```

### Rationale

#### Why USDC specifically

* Native Circle USDC on Base — no bridging, maximum liquidity
* 1:1 USD peg removes all oracle risk on the payment path
* Already the dominant stablecoin for on-chain commerce on Base
* No additional price feed required — price is exact, not approximate

#### Why keep ETH

* ETH holders should not be forced to acquire USDC to use the protocol
* ETH path requires zero approvals — simpler UX for crypto-native users
* Removing ETH would break any existing integrations and SDK usage

#### Why not support arbitrary ERC-20 tokens

* Price oracle complexity explodes (need feed for every token)
* Smart contract attack surface grows with each whitelisted token
* USDC covers the stablecoin use case completely

#### Why not wrap ETH into USDC automatically on-chain

* Requires on-chain DEX integration (Uniswap / Aerodrome)
* Adds swap slippage, MEV risk, and smart contract dependency
* Out of scope for v1 — can be added as a frontend convenience layer later

### Consequences

#### Positive

* Users can pay exact dollar amounts with zero ETH price exposure
* Widens addressable market to USDC holders on Base
* USDC path has no oracle dependency — simpler and safer
* ETH and USDC revenue flows are separate and independently withdrawable

#### Negative

* USDC path requires one extra `approve` transaction (or EIP-2612 permit complexity)
* Contract size and logic surface increases slightly
* `RegistrarController` must be redeployed — existing testnet deployments invalidated
* SDK `register()` and `renew()` need a `paymentToken` option added

#### Mitigations

* Default `paymentToken` to `address(0)` — all existing SDK and script callers are unaffected
* Add `permit2` support in a follow-up (Uniswap Permit2 on Base is already deployed)
* Redeploy is already planned for mainnet — testnet redeploy has low cost

### References

* [Circle Native USDC on Base](https://www.circle.com/blog/usdc-now-available-natively-on-base)
* [EIP-2612: Permit Extension for ERC-20](https://eips.ethereum.org/EIPS/eip-2612)
* [Uniswap Permit2](https://github.com/Uniswap/permit2)
* [ADR-006: Pricing and controller design](/adr/006)