@hoodfi/sdk 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@hoodfi/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Resolve, reverse-look-up and register *.hoodfi.eth names on Robinhood Chain. Typed, keyless, viem-based.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:live": "npm run build && node --test test/live.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": ["hoodfi", "ens", "names", "robinhood-chain", "viem", "web3", "identity"],
+  "homepage": "https://www.hoodfi.name",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RWA-ID/hoodfi-eth.git",
+    "directory": "sdk"
+  },
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "peerDependencies": {
+    "viem": "^2.21.0"
+  },
+  "dependencies": {
+    "@ensdomains/address-encoder": "^1.1.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2",
+    "viem": "^2.47.10"
+  },
+  "publishConfig": { "access": "public" }
+}

package/src/abi.ts

@@ -0,0 +1,35 @@
+/** Only the parts of each ABI this SDK actually calls. */
+
+export const registrarAbi = [
+  { type: 'function', name: 'register', stateMutability: 'payable', inputs: [{ name: 'label', type: 'string' }], outputs: [] },
+  { type: 'function', name: 'registerWithUsdc', stateMutability: 'nonpayable', inputs: [{ name: 'label', type: 'string' }], outputs: [] },
+  // 0 = available, 1 = taken, 2 = locked, 3 = invalid, 4 = blocked.
+  { type: 'function', name: 'status', stateMutability: 'view', inputs: [{ name: 'label', type: 'string' }], outputs: [{ type: 'uint8' }] },
+  {
+    type: 'function',
+    name: 'priceOf',
+    stateMutability: 'view',
+    inputs: [{ name: 'label', type: 'string' }],
+    outputs: [{ name: 'weiPrice', type: 'uint256' }, { name: 'usdcPrice', type: 'uint256' }],
+  },
+  { type: 'function', name: 'paused', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+] as const
+
+export const registryAbi = [
+  { type: 'function', name: 'ownerOf', stateMutability: 'view', inputs: [{ name: 'tokenId', type: 'uint256' }], outputs: [{ type: 'address' }] },
+  {
+    type: 'function',
+    name: 'addr',
+    stateMutability: 'view',
+    inputs: [{ name: 'node', type: 'bytes32' }, { name: 'coinType', type: 'uint256' }],
+    outputs: [{ type: 'bytes' }],
+  },
+  {
+    type: 'function',
+    name: 'text',
+    stateMutability: 'view',
+    inputs: [{ name: 'node', type: 'bytes32' }, { name: 'key', type: 'string' }],
+    outputs: [{ type: 'string' }],
+  },
+  { type: 'function', name: 'contenthash', stateMutability: 'view', inputs: [{ name: 'node', type: 'bytes32' }], outputs: [{ type: 'bytes' }] },
+] as const

package/src/client.ts

@@ -0,0 +1,478 @@
+import {
+  type Address,
+  type Hex,
+  type PublicClient,
+  createPublicClient,
+  encodeFunctionData,
+  erc20Abi,
+  fallback,
+  getAddress,
+  http,
+  isAddress,
+  namehash,
+} from 'viem'
+
+import { registrarAbi, registryAbi } from './abi.js'
+import { CHAINS, type SendChain, paymentCaveat } from './coins.js'
+import {
+  CONTRACTS,
+  DEFAULT_API_URL,
+  DEFAULT_ROBINHOOD_RPC,
+  FALLBACK_ROBINHOOD_RPC,
+  ROBINHOOD_CHAIN_ID,
+  ROBINHOOD_EXPLORER,
+  robinhoodChain,
+} from './constants.js'
+import { type ContentHash, contentGatewayUrl, decodeContenthash } from './contenthash.js'
+import { type NameStatus, STATUS_TEXT, checkHoodfiName, checkLabel, fullName, tierOf } from './labels.js'
+
+export type HoodfiErrorCode =
+  /** The input isn't a valid hoodfi.eth name. Nothing was read. */
+  | 'INVALID_NAME'
+  /** The name exists, or can't be minted right now. `checkName` explains why. */
+  | 'UNAVAILABLE'
+  /** The name has never been minted. */
+  | 'NOT_REGISTERED'
+  /** The name has no record for the chain asked about. Do NOT fall back to another one. */
+  | 'NO_RECORD'
+  /**
+   * The chain or API didn't answer. This says nothing about the name: never show it as
+   * "not registered" or "no names". Retry.
+   */
+  | 'UNREADABLE'
+
+export class HoodfiError extends Error {
+  readonly code: HoodfiErrorCode
+  constructor(code: HoodfiErrorCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'HoodfiError'
+    this.code = code
+  }
+}
+
+export interface HoodfiClientOptions {
+  /**
+   * Robinhood Chain RPC URLs, tried in order before the public defaults. The public RPC
+   * throttles per IP; a server doing volume should pass its own endpoint here.
+   */
+  rpcUrls?: string[]
+  /** Bring your own viem client instead. It must be connected to chain 4663. */
+  publicClient?: PublicClient
+  /** HoodFi gateway base URL, for reverse lookups. */
+  apiUrl?: string
+  /** Override `fetch` (tests, proxies). */
+  fetch?: typeof fetch
+}
+
+export interface NameCheck {
+  name: string
+  label: string
+  length: number
+  /** 0-3 for 1, 2, 3 and 4+ characters. */
+  tier: 0 | 1 | 2 | 3
+  status: NameStatus
+  /** True only when status is available AND minting isn't paused. */
+  available: boolean
+  paused: boolean
+  /** Why it can't be registered, in a sentence you can show. Undefined when available. */
+  reason?: string
+  price: {
+    /** ETH price in wei, from the registrar's live price feed. */
+    wei: bigint
+    /** USDG price, 6 decimals. */
+    usdg: bigint
+  }
+}
+
+export interface NameProfile {
+  name: string
+  node: Hex
+  owner: Address
+  /**
+   * Robinhood Chain and Ethereum are separate records. They normally hold the same
+   * address, but reported apart so a name where they differ is visible.
+   */
+  addresses: Record<SendChain, string | null>
+  /** Text records that are set: avatar, description, url, com.twitter, com.github, email. */
+  records: Partial<Record<TextKey, string>>
+  /** The name's website, or null when it has none (or one in a namespace not decoded here). */
+  website: (ContentHash & { url: string; gateway: string }) | null
+  explorer: string
+}
+
+export interface SendAddress {
+  name: string
+  chain: SendChain
+  address: string
+  /** E.g. the Robinhood and Ethereum records disagree. Show these to the sender. */
+  warnings: string[]
+  /** What a well-formed record can't prove (Solana has no checksum, XRP r-addresses no tag). */
+  caveat: string | null
+}
+
+export interface OwnedName {
+  name: string
+  node: Hex
+  /** The name's ETH address record, or null when unset. */
+  addr: Address | null
+  /** True when the name's record points back at this address. Only these may be shown as "this wallet is X". */
+  resolves: boolean
+  avatar: string | null
+}
+
+export interface AddressLookup {
+  address: Address
+  /** The name to display for this address: it resolves back to it. Null when none does. */
+  primary: string | null
+  /** "ens": the holder set it as their ENS primary. "inferred": shortest name that resolves back. */
+  primarySource: 'ens' | 'inferred' | null
+  /** Every hoodfi name this address holds now, resolving ones first. */
+  names: OwnedName[]
+}
+
+export interface TxStep {
+  description: string
+  to: Address
+  data: Hex
+  value: bigint
+  chainId: typeof ROBINHOOD_CHAIN_ID
+}
+
+export interface Registration {
+  name: string
+  label: string
+  payWith: 'eth' | 'usdg'
+  /** The price at quote time. ETH steps send `price.wei` plus the overpay buffer. */
+  price: { wei: bigint; usdg: bigint }
+  /** Send in order; wait for each receipt (and check its status) before the next. */
+  steps: TxStep[]
+  /** E.g. the account can't afford it yet. The steps still build. */
+  warnings: string[]
+}
+
+const TEXT_KEYS = ['avatar', 'description', 'url', 'com.twitter', 'com.github', 'email'] as const
+export type TextKey = (typeof TEXT_KEYS)[number]
+
+const UNREADABLE_MSG =
+  'Could not read Robinhood Chain: the reads failed rather than coming back empty, so this says nothing about the name. Try again shortly.'
+
+function unavailableReason(status: number, label: string): string | undefined {
+  switch (status) {
+    case 0:
+      return undefined
+    case 1:
+      return `${fullName(label)} is already registered.`
+    case 2:
+      return `${fullName(label)} is locked and not on sale right now.`
+    case 3:
+      return `${label} is not a valid label.`
+    case 4:
+      return `${label} is reserved and can never be registered.`
+    default:
+      return `${fullName(label)} is not available (status ${status}).`
+  }
+}
+
+/**
+ * A batch where nothing succeeded is a dead connection, not an answer.
+ *
+ * With `allowFailure: true`, a failed aggregate call (a 429 from a throttled RPC) marks
+ * every entry as failed, exactly like each one reverting. For a never-minted name only
+ * `ownerOf` reverts; `addr`/`text`/`contenthash` return empty successfully. So "all
+ * failed" can only mean the transport.
+ */
+function batchFailed(results: readonly { status: 'success' | 'failure' }[]): boolean {
+  return results.every((r) => r.status === 'failure')
+}
+
+function requireName(input: string): { name: string; labels: string[] } {
+  if (typeof input !== 'string') throw new HoodfiError('INVALID_NAME', 'Name must be a string.')
+  const checked = checkHoodfiName(input)
+  if (!checked.ok) throw new HoodfiError('INVALID_NAME', checked.reason)
+  return checked
+}
+
+function requireLabel(input: string): string {
+  if (typeof input !== 'string') throw new HoodfiError('INVALID_NAME', 'Name must be a string.')
+  const checked = checkLabel(input)
+  if (!checked.ok) throw new HoodfiError('INVALID_NAME', checked.reason)
+  return checked.label
+}
+
+function requireAddress(value: string): Address {
+  if (typeof value !== 'string' || !isAddress(value, { strict: false }))
+    throw new HoodfiError('INVALID_NAME', 'Expected a 0x-prefixed 20-byte address.')
+  return getAddress(value)
+}
+
+export interface HoodfiClient {
+  checkName(name: string): Promise<NameCheck>
+  resolve(name: string): Promise<NameProfile | null>
+  getSendAddress(name: string, chain: SendChain): Promise<SendAddress>
+  lookupAddress(address: string): Promise<AddressLookup>
+  buildRegistration(args: { name: string; account: string; payWith?: 'eth' | 'usdg'; overpayBps?: number }): Promise<Registration>
+  /** The viem client in use, e.g. for `waitForTransactionReceipt`. */
+  publicClient: PublicClient
+}
+
+export function createHoodfiClient(options: HoodfiClientOptions = {}): HoodfiClient {
+  const client: PublicClient =
+    options.publicClient ??
+    (createPublicClient({
+      chain: robinhoodChain,
+      transport: fallback(
+        [...(options.rpcUrls ?? []), DEFAULT_ROBINHOOD_RPC, FALLBACK_ROBINHOOD_RPC].map((url) =>
+          http(url, { retryCount: 2, retryDelay: 200, timeout: 8_000 })
+        ),
+        // Ranking probes every endpoint in the background, spending the rate limit
+        // this fallback exists to conserve.
+        { rank: false }
+      ),
+    }) as PublicClient)
+  const apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, '')
+  const doFetch = options.fetch ?? globalThis.fetch
+
+  async function readRegistrar(label: string) {
+    try {
+      // allowFailure: false: none of these can revert for a valid label, so a failure
+      // is the RPC, and must not be folded into an answer.
+      const [status, prices, paused] = await client.multicall({
+        contracts: [
+          { address: CONTRACTS.registrar, abi: registrarAbi, functionName: 'status', args: [label] },
+          { address: CONTRACTS.registrar, abi: registrarAbi, functionName: 'priceOf', args: [label] },
+          { address: CONTRACTS.registrar, abi: registrarAbi, functionName: 'paused' },
+        ],
+        allowFailure: false,
+      })
+      return { status, wei: prices[0], usdg: prices[1], paused }
+    } catch (cause) {
+      throw new HoodfiError('UNREADABLE', UNREADABLE_MSG, { cause })
+    }
+  }
+
+  /** Is a name free, and what does it cost? Prices are live from the registrar. */
+  async function checkName(name: string): Promise<NameCheck> {
+    const label = requireLabel(name)
+    const { status, wei, usdg, paused } = await readRegistrar(label)
+    const reason = paused ? 'Minting is paused by the registrar owner.' : unavailableReason(status, label)
+    return {
+      name: fullName(label),
+      label,
+      length: label.length,
+      tier: tierOf(label),
+      status: STATUS_TEXT[status] ?? 'invalid',
+      available: status === 0 && !paused,
+      paused,
+      ...(reason !== undefined && { reason }),
+      price: { wei, usdg },
+    }
+  }
+
+  /**
+   * Everything a name holds, in one RPC round-trip. Returns null when the name was never
+   * minted. Throws UNREADABLE (never null) when the chain didn't answer.
+   *
+   * Accepts `gm`, `gm.hoodfi.eth` or a subname like `jack.gm.hoodfi.eth`. Does not accept
+   * `gm.eth`: that's a different name on Ethereum.
+   */
+  async function resolve(name: string): Promise<NameProfile | null> {
+    const checked = requireName(name)
+    const node = namehash(checked.name)
+    const r = CONTRACTS.registry
+    const addrAt = (coinType: bigint) =>
+      ({ address: r, abi: registryAbi, functionName: 'addr', args: [node, coinType] }) as const
+    const text = (key: TextKey) => ({ address: r, abi: registryAbi, functionName: 'text', args: [node, key] }) as const
+
+    let results
+    try {
+      results = await client.multicall({
+        contracts: [
+          { address: r, abi: registryAbi, functionName: 'ownerOf', args: [BigInt(node)] },
+          addrAt(CHAINS.robinhood.coinType),
+          addrAt(CHAINS.ethereum.coinType),
+          addrAt(CHAINS.bitcoin.coinType),
+          addrAt(CHAINS.solana.coinType),
+          addrAt(CHAINS.xrp.coinType),
+          { address: r, abi: registryAbi, functionName: 'contenthash', args: [node] },
+          text('avatar'),
+          text('description'),
+          text('url'),
+          text('com.twitter'),
+          text('com.github'),
+          text('email'),
+        ],
+        allowFailure: true,
+        // viem splits a multicall past 1024 bytes of calldata by default; these 13 reads
+        // are ~1.2 KB. One request is the point: two is the shape public RPCs throttle.
+        batchSize: 0,
+      })
+    } catch (cause) {
+      throw new HoodfiError('UNREADABLE', UNREADABLE_MSG, { cause })
+    }
+    if (batchFailed(results)) throw new HoodfiError('UNREADABLE', UNREADABLE_MSG)
+
+    const [owner, rh, eth, btc, sol, xrp, contenthash, ...texts] = results
+    if (!owner || owner.status === 'failure') return null
+
+    const stored = (e: (typeof results)[number] | undefined): Hex =>
+      e && e.status === 'success' && typeof e.result === 'string' ? (e.result as Hex) : '0x'
+
+    const records: Partial<Record<TextKey, string>> = {}
+    TEXT_KEYS.forEach((key, i) => {
+      const e = texts[i]
+      if (e && e.status === 'success' && typeof e.result === 'string' && e.result) records[key] = e.result
+    })
+
+    const content = decodeContenthash(stored(contenthash))
+    return {
+      name: checked.name,
+      node,
+      owner: getAddress(owner.result as Address),
+      addresses: {
+        robinhood: CHAINS.robinhood.decode(stored(rh)),
+        ethereum: CHAINS.ethereum.decode(stored(eth)),
+        bitcoin: CHAINS.bitcoin.decode(stored(btc)),
+        solana: CHAINS.solana.decode(stored(sol)),
+        xrp: CHAINS.xrp.decode(stored(xrp)),
+      },
+      records,
+      website: content
+        ? { ...content, url: `https://${checked.name}.link/`, gateway: contentGatewayUrl(content) }
+        : null,
+      explorer: `${ROBINHOOD_EXPLORER}/token/${r}/instance/${BigInt(node).toString()}`,
+    }
+  }
+
+  /**
+   * The address to pay `name` at on `chain`, or a HoodfiError.
+   *
+   * Reads that chain's own record and nothing else. An empty Robinhood Chain record is
+   * NOT filled from the Ethereum one (or vice versa): a contract wallet like a Safe only
+   * exists on chains it was deployed to, and funds sent to its address elsewhere are
+   * stuck. Empty means ask the recipient.
+   */
+  async function getSendAddress(name: string, chain: SendChain): Promise<SendAddress> {
+    const spec = CHAINS[chain]
+    if (!spec) throw new HoodfiError('INVALID_NAME', `Unknown chain "${String(chain)}".`)
+    const profile = await resolve(name)
+    if (!profile) throw new HoodfiError('NOT_REGISTERED', `${requireName(name).name} is not registered.`)
+
+    const address = profile.addresses[chain]
+    const sibling = chain === 'robinhood' ? 'ethereum' : chain === 'ethereum' ? 'robinhood' : null
+    const other = sibling ? profile.addresses[sibling] : null
+
+    if (!address)
+      throw new HoodfiError(
+        'NO_RECORD',
+        `${profile.name} has no ${spec.label} address set, so it can't be paid there. Don't send to one of its other addresses instead.` +
+          (other && sibling ? ` It does have a ${CHAINS[sibling].label} address; the owner should set both.` : '')
+      )
+
+    const warnings: string[] = []
+    if (other && sibling && other !== address)
+      warnings.push(
+        `${profile.name}'s two ETH records disagree: ${spec.label} → ${address}, ${CHAINS[sibling].label} → ${other}. This uses the ${spec.label} one; confirm with the recipient.`
+      )
+    return { name: profile.name, chain, address, warnings, caveat: paymentCaveat(chain, address) }
+  }
+
+  /**
+   * The hoodfi names an address holds, and which one to display for it.
+   *
+   * Served by the HoodFi gateway (it indexes Transfer logs; the registry isn't
+   * enumerable), cached ~60s. Throws UNREADABLE on a failed read: an empty `names` list
+   * really means none.
+   */
+  async function lookupAddress(address: string): Promise<AddressLookup> {
+    const checksummed = requireAddress(address)
+    let response: Response
+    try {
+      response = await doFetch(`${apiUrl}/owner/${checksummed}/names`, { headers: { accept: 'application/json' } })
+    } catch (cause) {
+      throw new HoodfiError('UNREADABLE', 'Could not reach the HoodFi API. Try again shortly.', { cause })
+    }
+    if (!response.ok)
+      throw new HoodfiError('UNREADABLE', `The HoodFi API answered ${response.status}. This says nothing about the address; try again shortly.`)
+    return (await response.json()) as AddressLookup
+  }
+
+  /**
+   * Unsigned transactions that register `name` for `account`.
+   *
+   * The registrar mints to whoever SENDS the transaction: there is no recipient
+   * argument. Sign with `account` or the name goes to the actual signer.
+   *
+   * `payWith: 'usdg'` adds an approve step when the allowance is short. `overpayBps`
+   * (ETH only, default 100 = 1%) absorbs price-feed movement between quote and send;
+   * the registrar refunds anything above the price to the sender.
+   */
+  async function buildRegistration(args: {
+    name: string
+    account: string
+    payWith?: 'eth' | 'usdg'
+    overpayBps?: number
+  }): Promise<Registration> {
+    const label = requireLabel(args.name)
+    const account = requireAddress(args.account)
+    const payWith = args.payWith ?? 'eth'
+    if (payWith !== 'eth' && payWith !== 'usdg') throw new HoodfiError('INVALID_NAME', 'payWith must be "eth" or "usdg".')
+    const overpayBps = args.overpayBps ?? 100
+    if (!Number.isInteger(overpayBps) || overpayBps < 0 || overpayBps > 10_000)
+      throw new HoodfiError('INVALID_NAME', 'overpayBps must be an integer from 0 to 10000.')
+
+    const { status, wei, usdg, paused } = await readRegistrar(label)
+    if (paused) throw new HoodfiError('UNAVAILABLE', 'Minting is paused by the registrar owner.')
+    const reason = unavailableReason(status, label)
+    if (reason) throw new HoodfiError('UNAVAILABLE', reason)
+
+    const name = fullName(label)
+    const steps: TxStep[] = []
+    const warnings: string[] = []
+
+    try {
+      if (payWith === 'eth') {
+        const value = wei + (wei * BigInt(overpayBps)) / 10_000n
+        const balance = await client.getBalance({ address: account })
+        if (balance < value) warnings.push(`${account} holds less ETH on Robinhood Chain than the ${value} wei this sends.`)
+        steps.push({
+          description: `Register ${name}`,
+          to: CONTRACTS.registrar,
+          data: encodeFunctionData({ abi: registrarAbi, functionName: 'register', args: [label] }),
+          value,
+          chainId: ROBINHOOD_CHAIN_ID,
+        })
+      } else {
+        const [allowance, balance] = await client.multicall({
+          contracts: [
+            { address: CONTRACTS.usdg, abi: erc20Abi, functionName: 'allowance', args: [account, CONTRACTS.registrar] },
+            { address: CONTRACTS.usdg, abi: erc20Abi, functionName: 'balanceOf', args: [account] },
+          ],
+          allowFailure: false,
+        })
+        if (balance < usdg) warnings.push(`${account} holds less USDG than the price.`)
+        if (allowance < usdg)
+          steps.push({
+            description: 'Approve the registrar to spend the USDG price',
+            to: CONTRACTS.usdg,
+            data: encodeFunctionData({ abi: erc20Abi, functionName: 'approve', args: [CONTRACTS.registrar, usdg] }),
+            value: 0n,
+            chainId: ROBINHOOD_CHAIN_ID,
+          })
+        steps.push({
+          description: `Register ${name}`,
+          to: CONTRACTS.registrar,
+          data: encodeFunctionData({ abi: registrarAbi, functionName: 'registerWithUsdc', args: [label] }),
+          value: 0n,
+          chainId: ROBINHOOD_CHAIN_ID,
+        })
+      }
+    } catch (cause) {
+      throw new HoodfiError('UNREADABLE', UNREADABLE_MSG, { cause })
+    }
+
+    return { name, label, payWith, price: { wei, usdg }, steps, warnings }
+  }
+
+  return { checkName, resolve, getSendAddress, lookupAddress, buildRegistration, publicClient: client }
+}
+

package/src/coins.ts

@@ -0,0 +1,76 @@
+/**
+ * Decoding the address records a name can carry.
+ *
+ * ENSIP-9 stores an address as its chain's own bytes, not the text people copy (Bitcoin
+ * keeps its scriptPubKey, Solana its raw ed25519 key), so each record is re-derived
+ * through a per-chain codec rather than echoed. Same codecs as mcp/src/coins.ts and
+ * frontend/lib/ens.ts: `@ensdomains/address-encoder`.
+ */
+
+import { encodeBtcAddress, encodeSolAddress } from '@ensdomains/address-encoder/coders'
+import { type Hex, getAddress, hexToBytes } from 'viem'
+
+import { BTC_COIN_TYPE, ETH_COIN_TYPE, ROBINHOOD_COIN_TYPE, SOL_COIN_TYPE, XRP_COIN_TYPE } from './constants.js'
+import { encodeXrpRecord } from './xrp.js'
+
+/** Where a payment goes. `robinhood` and `ethereum` are separate records on purpose. */
+export type SendChain = 'robinhood' | 'ethereum' | 'bitcoin' | 'solana' | 'xrp'
+
+export type Verification = 'checksummed' | 'if-mixed-case' | 'length-only'
+
+interface Chain {
+  label: string
+  symbol: string
+  coinType: bigint
+  /**
+   * How much a well-formed record proves. Bitcoin and XRP carry a checksum. An EVM
+   * record is checksummed when written in EIP-55 case, which this SDK always returns.
+   * Solana has none: any 32 bytes is a valid-looking key, so a typo at write time is
+   * undetectable at read time.
+   */
+  verification: Verification
+  decode(stored: Hex): string | null
+}
+
+const ZERO = '0x0000000000000000000000000000000000000000'
+
+function evm(stored: Hex): string | null {
+  if (!stored || stored.length !== 42) return null
+  const address = getAddress(stored)
+  return address === ZERO ? null : address
+}
+
+function via(toText: (bytes: Uint8Array) => string) {
+  return (stored: Hex): string | null => {
+    if (!stored || stored === '0x') return null
+    try {
+      return toText(hexToBytes(stored))
+    } catch {
+      return null
+    }
+  }
+}
+
+// The library names directions from the address text's side: `encode…` turns stored
+// bytes INTO text, which is the only direction a reader needs.
+export const CHAINS: Record<SendChain, Chain> = {
+  robinhood: { label: 'Robinhood Chain', symbol: 'ETH', coinType: ROBINHOOD_COIN_TYPE, verification: 'if-mixed-case', decode: evm },
+  ethereum: { label: 'Ethereum', symbol: 'ETH', coinType: ETH_COIN_TYPE, verification: 'if-mixed-case', decode: evm },
+  bitcoin: { label: 'Bitcoin', symbol: 'BTC', coinType: BTC_COIN_TYPE, verification: 'checksummed', decode: via(encodeBtcAddress) },
+  solana: { label: 'Solana', symbol: 'SOL', coinType: SOL_COIN_TYPE, verification: 'length-only', decode: via(encodeSolAddress) },
+  xrp: { label: 'XRP Ledger', symbol: 'XRP', coinType: XRP_COIN_TYPE, verification: 'checksummed', decode: via(encodeXrpRecord) },
+}
+
+export const SEND_CHAINS = Object.keys(CHAINS) as SendChain[]
+
+/**
+ * What to tell a user before they pay this address, or null when the record itself
+ * proves it is well-formed. Relay it; don't report the address as "validated".
+ */
+export function paymentCaveat(chain: SendChain, address: string): string | null {
+  if (chain === 'xrp' && address.startsWith('r'))
+    return 'Classic XRP Ledger address (r…): it carries no destination tag. Fine for a personal wallet; an exchange deposit sent without its tag can be lost.'
+  if (chain === 'solana')
+    return 'Solana addresses carry no checksum, so a mistyped record looks exactly like a valid one. Confirm it with the recipient before a large payment.'
+  return null
+}

package/src/constants.ts

@@ -0,0 +1,41 @@
+import { type Chain, defineChain } from 'viem'
+
+export const PARENT = 'hoodfi.eth'
+export const ROBINHOOD_CHAIN_ID = 4663
+export const DEFAULT_ROBINHOOD_RPC = 'https://rpc.mainnet.chain.robinhood.com'
+/** Used when the public RPC rate-limits. It's throttled too, but on a separate budget. */
+export const FALLBACK_ROBINHOOD_RPC = 'https://robinhoodchain.blockscout.com/api/eth-rpc'
+export const ROBINHOOD_EXPLORER = 'https://robinhoodchain.blockscout.com'
+/** Base URL of the HoodFi gateway that serves the reverse lookup. */
+export const DEFAULT_API_URL = 'https://ccip.hoodfi-mcp.com'
+
+/** Live contracts. Owners and sources: contracts/README.md in the repository. */
+export const CONTRACTS = {
+  registry: '0xf2bABA012244bdD7445129597350054E1B3aEe5C',
+  registrar: '0x56be5565acc823f4195c2cf3b9046C083633209a',
+  partnerRouter: '0xb7bd5f2c7c445ddc5d55ebd9b8f6a20c2e6e4b5d',
+  usdg: '0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168',
+  /** HoodfiL1Resolver on Ethereum mainnet. */
+  l1Resolver: '0x37215Dd89D0Fd4ea0Dbce690bDe58490fB7f7cF2',
+} as const
+
+/**
+ * The ENSIP-11 coinType for Robinhood Chain, 0x80000000 | 4663.
+ *
+ * It's written as a literal on purpose. In JS, `0x80000000 | 4663` is a signed 32-bit
+ * operation and comes out negative, so every addr read silently returns nothing.
+ */
+export const ROBINHOOD_COIN_TYPE = 2147488311n
+export const ETH_COIN_TYPE = 60n
+export const BTC_COIN_TYPE = 0n
+export const SOL_COIN_TYPE = 501n
+export const XRP_COIN_TYPE = 144n
+
+export const robinhoodChain: Chain = defineChain({
+  id: ROBINHOOD_CHAIN_ID,
+  name: 'Robinhood Chain',
+  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+  rpcUrls: { default: { http: [DEFAULT_ROBINHOOD_RPC] } },
+  blockExplorers: { default: { name: 'Blockscout', url: ROBINHOOD_EXPLORER } },
+  contracts: { multicall3: { address: '0xcA11bde05977b3631167028862bE2a173976CA11' } },
+})