@wikialisalabs/ans-resolver 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2026 wikialisalabs (https://github.com/wikialisalabs)
+Author & Founder: Nguyen Thi Thu Huong (wikialisa)
+Technical Contact: wiki@axvn.vn
+Organization: wikialisalabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+### Tóm tắt ý nghĩa của giấy phép MIT đối với tổ chức wikialisalabs:
+
+* **Chuyển giao toàn diện bản quyền:** Quyền sở hữu trí tuệ và thương hiệu mã nguồn thuộc về tổ chức **wikialisalabs** do tác giả Nguyễn Thị Thu Hương sáng lập.
+* **Tự do thương mại hóa tối đa:** Bất kỳ cá nhân hoặc tổ chức nào cũng có thể sử dụng, tích hợp và thương mại hóa mã nguồn của hệ sinh thái mà không bị rào cản BSL hay bản quyền đóng.
+* **Tự do tùy biến & Đóng góp:** Cộng đồng được quyền fork, phát triển module mở rộng, tối ưu hóa các thành phần kiến trúc và đóng góp lại cho `wikialisalabs`.
+* **Miễn trừ trách nhiệm pháp lý:** Tổ chức `wikialisalabs` và tác giả được miễn trừ toàn bộ trách nhiệm pháp lý đối với bất kỳ rủi ro vận hành hoặc tổn thất tài chính nào phát sinh từ việc sử dụng phần mềm.

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@wikialisalabs/ans-resolver",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "ANS Domain Resolver SDK — resolve .axq/.vpx/.sqx/.kpx/.vrq names on-chain via ANSRegistry contract",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "license": "MIT",
+  "dependencies": {
+    "viem": "^2.17.0"
+  },
+  "devDependencies": {
+    "jest": "^30.5.2"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/src/__tests__/**/*.test.js"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.js",
+      "!src/__tests__/**"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "lines": 60
+      }
+    }
+  },
+  "author": "wikialisa (Nguyen Thi Thu Huong) <wiki@axvn.vn>",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wikialisalabs/ans-resolver.git"
+  },
+  "scripts": {
+    "build": "echo 'ANS Resolver: JS-only, no build step needed'",
+    "typecheck": "echo 'ANS Resolver: no TypeScript yet — Phase 5 migration'",
+    "test": "jest --forceExit",
+    "test:ci": "jest --forceExit --ci --coverage",
+    "clean": "rm -rf dist coverage"
+  }
 }

package/src/__tests__/ans-resolver.test.js

@@ -0,0 +1,155 @@
+'use strict';
+/**
+ * @axioledger/ans-resolver — unit tests
+ * All on-chain calls are mocked via jest — no real RPC required.
+ */
+
+jest.mock('viem', () => {
+  const mockReadContract = jest.fn();
+  const mockCreatePublicClient = jest.fn(() => ({ readContract: mockReadContract }));
+  return {
+    createPublicClient: mockCreatePublicClient,
+    http:              jest.fn((url) => ({ url })),
+    keccak256:         jest.fn((data) => `0x${'a'.repeat(64)}`),
+    encodePacked:      jest.fn(() => `0x${'b'.repeat(64)}`),
+    isAddress:         jest.fn((addr) => /^0x[0-9a-fA-F]{40}$/.test(addr)),
+    __readContract:    mockReadContract,
+  };
+});
+
+jest.mock('viem/chains', () => ({
+  sepolia:  { id: 11155111, name: 'Sepolia' },
+  mainnet:  { id: 1,        name: 'Ethereum' },
+}));
+
+const REGISTRY = '0x' + 'C'.repeat(40);
+const { ANSResolver, SUPPORTED_TLDS, parseName, computeNameHash } = require('../index');
+
+function getReadMock() {
+  return require('viem').__readContract;
+}
+
+describe('parseName', () => {
+  it('parses "alice.axq"', () => {
+    const r = parseName('alice.axq');
+    expect(r).toEqual({ label: 'alice', tld: 'axq' });
+  });
+
+  it('parses subdomain "bob.vpx"', () => {
+    const r = parseName('bob.vpx');
+    expect(r.tld).toBe('vpx');
+  });
+
+  it('throws on unsupported TLD', () => {
+    expect(() => parseName('alice.eth')).toThrow('Unsupported TLD');
+  });
+
+  it('throws on no TLD', () => {
+    expect(() => parseName('alice')).toThrow('Invalid ANS name');
+  });
+});
+
+describe('SUPPORTED_TLDS', () => {
+  it('contains all 5 pillars', () => {
+    expect(SUPPORTED_TLDS).toEqual(expect.arrayContaining(['axq','vpx','sqx','kpx','vrq']));
+    expect(SUPPORTED_TLDS).toHaveLength(5);
+  });
+});
+
+describe('ANSResolver constructor', () => {
+  it('throws without rpcUrl', () => {
+    expect(() => new ANSResolver({ registryAddress: REGISTRY })).toThrow('rpcUrl');
+  });
+
+  it('throws without registryAddress', () => {
+    expect(() => new ANSResolver({ rpcUrl: 'http://x' })).toThrow('registryAddress');
+  });
+
+  it('throws on invalid address', () => {
+    expect(() => new ANSResolver({ rpcUrl: 'http://x', registryAddress: 'notanaddress' }))
+      .toThrow('invalid registryAddress');
+  });
+
+  it('constructs successfully with valid config', () => {
+    const r = new ANSResolver({ rpcUrl: 'http://localhost:8545', registryAddress: REGISTRY });
+    expect(r).toBeInstanceOf(ANSResolver);
+    expect(r.registryAddress).toBe(REGISTRY);
+  });
+});
+
+describe('ANSResolver.resolve', () => {
+  let resolver;
+  beforeEach(() => {
+    resolver = new ANSResolver({ rpcUrl: 'http://localhost:8545', registryAddress: REGISTRY });
+    getReadMock().mockReset();
+  });
+
+  it('returns owner address for a registered name', async () => {
+    const expected = '0x' + 'A'.repeat(40);
+    getReadMock().mockResolvedValue(expected);
+
+    const result = await resolver.resolve('alice', 'axq');
+    expect(result).toBe(expected);
+    expect(getReadMock()).toHaveBeenCalledWith(expect.objectContaining({
+      functionName: 'resolve',
+      args: ['alice', 'axq'],
+    }));
+  });
+
+  it('resolveToAddress parses and resolves "alice.axq"', async () => {
+    const expected = '0x' + 'B'.repeat(40);
+    getReadMock().mockResolvedValue(expected);
+
+    const result = await resolver.resolveToAddress('alice.axq');
+    expect(result).toBe(expected);
+  });
+});
+
+describe('ANSResolver.getRecord', () => {
+  let resolver;
+  beforeEach(() => {
+    resolver = new ANSResolver({ rpcUrl: 'http://localhost:8545', registryAddress: REGISTRY });
+    getReadMock().mockReset();
+  });
+
+  it('returns structured record', async () => {
+    const owner    = '0x' + 'D'.repeat(40);
+    const resolver_= '0x' + '0'.repeat(40);
+    const expiry   = BigInt(Math.floor(Date.now() / 1000) + 86400);
+    getReadMock().mockResolvedValue([owner, resolver_, expiry, false]);
+
+    const rec = await resolver.getRecord('alice.axq');
+    expect(rec.owner).toBe(owner);
+    expect(rec.expiry).toBe(expiry);
+    expect(rec.locked).toBe(false);
+  });
+});
+
+describe('ANSResolver.isRegistered', () => {
+  let resolver;
+  beforeEach(() => {
+    resolver = new ANSResolver({ rpcUrl: 'http://localhost:8545', registryAddress: REGISTRY });
+    getReadMock().mockReset();
+  });
+
+  it('returns true for active name', async () => {
+    const owner  = '0x' + 'E'.repeat(40);
+    const expiry = BigInt(Math.floor(Date.now() / 1000) + 86400);
+    getReadMock().mockResolvedValue([owner, '0x' + '0'.repeat(40), expiry, false]);
+
+    expect(await resolver.isRegistered('alice.axq')).toBe(true);
+  });
+
+  it('returns false for expired name', async () => {
+    const owner  = '0x' + 'F'.repeat(40);
+    const expiry = BigInt(Math.floor(Date.now() / 1000) - 100); // expired
+    getReadMock().mockResolvedValue([owner, '0x' + '0'.repeat(40), expiry, false]);
+
+    expect(await resolver.isRegistered('alice.axq')).toBe(false);
+  });
+
+  it('returns false when readContract throws', async () => {
+    getReadMock().mockRejectedValue(new Error('not registered'));
+    expect(await resolver.isRegistered('unknown.axq')).toBe(false);
+  });
+});

package/src/index.js

@@ -0,0 +1,240 @@
+'use strict';
+/**
+ * @axioledger/ans-resolver — AXIOLEDGER Name Service (ANS) TypeScript client
+ *
+ * Resolves .axq / .vpx / .sqx / .kpx / .vrq names to addresses on-chain.
+ * Reads from the deployed ANSRegistry smart contract via viem.
+ *
+ * @example
+ * import { ANSResolver } from '@axioledger/ans-resolver';
+ *
+ * const resolver = new ANSResolver({
+ *   rpcUrl: 'https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY',
+ *   registryAddress: '0x...',
+ * });
+ *
+ * const owner = await resolver.resolve('alice', 'axq');
+ * const addr  = await resolver.resolveToAddress('alice.axq');
+ */
+
+const { createPublicClient, http, keccak256, encodePacked, isAddress } = require('viem');
+const { sepolia, mainnet } = require('viem/chains');
+
+// ── ABI (minimal — only functions we call) ────────────────────────────────────
+const ANS_REGISTRY_ABI = [
+  {
+    name: 'resolve',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'label', type: 'string' },
+      { name: 'tld',   type: 'string' },
+    ],
+    outputs: [{ name: '', type: 'address' }],
+  },
+  {
+    name: 'getResolver',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'label', type: 'string' },
+      { name: 'tld',   type: 'string' },
+    ],
+    outputs: [{ name: '', type: 'address' }],
+  },
+  {
+    name: 'records',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [{ name: 'nameHash', type: 'bytes32' }],
+    outputs: [
+      { name: 'owner',    type: 'address' },
+      { name: 'resolver', type: 'address' },
+      { name: 'expiry',   type: 'uint64'  },
+      { name: 'locked',   type: 'bool'    },
+    ],
+  },
+  {
+    name: 'tldFees',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [{ name: 'tldHash', type: 'bytes32' }],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+  {
+    name: 'supportedTlds',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [{ name: 'tldHash', type: 'bytes32' }],
+    outputs: [{ name: '', type: 'bool' }],
+  },
+];
+
+// ── Supported TLDs ────────────────────────────────────────────────────────────
+
+const SUPPORTED_TLDS = ['axq', 'vpx', 'sqx', 'kpx', 'vrq'];
+
+const CHAIN_MAP = {
+  mainnet: { chain: mainnet, id: 1 },
+  sepolia: { chain: sepolia, id: 11155111 },
+};
+
+// ── Helper: compute nameHash matching ANSRegistry._nameHash() ─────────────────
+function computeNameHash(label, tld) {
+  const labelHash = keccak256(new TextEncoder().encode(label));
+  const tldHash   = keccak256(new TextEncoder().encode(tld));
+  return keccak256(encodePacked(['bytes32', 'bytes32'], [labelHash, tldHash]));
+}
+
+// ── Parse "alice.axq" → { label: "alice", tld: "axq" } ───────────────────────
+function parseName(name) {
+  const parts = name.trim().toLowerCase().split('.');
+  if (parts.length < 2) throw new Error(`Invalid ANS name: "${name}" — expected "label.tld"`);
+  const tld   = parts[parts.length - 1];
+  const label = parts.slice(0, -1).join('.');
+  if (!SUPPORTED_TLDS.includes(tld)) {
+    throw new Error(`Unsupported TLD ".${tld}" — supported: ${SUPPORTED_TLDS.map(t => `.${t}`).join(', ')}`);
+  }
+  return { label, tld };
+}
+
+// ── ANSResolver class ─────────────────────────────────────────────────────────
+
+class ANSResolver {
+  /**
+   * @param {object} config
+   * @param {string} config.rpcUrl            — EVM JSON-RPC endpoint
+   * @param {string} config.registryAddress   — Deployed ANSRegistry contract address
+   * @param {'mainnet'|'sepolia'} [config.network='sepolia']
+   */
+  constructor(config) {
+    if (!config.rpcUrl)          throw new Error('ANSResolver: rpcUrl is required');
+    if (!config.registryAddress) throw new Error('ANSResolver: registryAddress is required');
+    if (!isAddress(config.registryAddress)) {
+      throw new Error(`ANSResolver: invalid registryAddress "${config.registryAddress}"`);
+    }
+
+    const network    = config.network || 'sepolia';
+    const chainInfo  = CHAIN_MAP[network];
+    if (!chainInfo) throw new Error(`ANSResolver: unknown network "${network}"`);
+
+    this.registryAddress = config.registryAddress;
+    this.client = createPublicClient({
+      chain:     chainInfo.chain,
+      transport: http(config.rpcUrl),
+    });
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /**
+   * Resolve "alice.axq" → owner address.
+   * Throws if name is expired or not registered.
+   * @param {string} name  e.g. "alice.axq"
+   * @returns {Promise<string>} checksummed Ethereum address
+   */
+  async resolveToAddress(name) {
+    const { label, tld } = parseName(name);
+    return this.resolve(label, tld);
+  }
+
+  /**
+   * Resolve label + tld separately → owner address.
+   * @param {string} label  e.g. "alice"
+   * @param {string} tld    e.g. "axq"
+   * @returns {Promise<string>} checksummed Ethereum address
+   */
+  async resolve(label, tld) {
+    const address = await this.client.readContract({
+      address:      this.registryAddress,
+      abi:          ANS_REGISTRY_ABI,
+      functionName: 'resolve',
+      args:         [label.toLowerCase(), tld.toLowerCase()],
+    });
+    return address;
+  }
+
+  /**
+   * Get resolver contract address for extended records.
+   * @param {string} name  e.g. "alice.axq"
+   * @returns {Promise<string>} resolver contract address (may be zero address)
+   */
+  async getResolver(name) {
+    const { label, tld } = parseName(name);
+    return this.client.readContract({
+      address:      this.registryAddress,
+      abi:          ANS_REGISTRY_ABI,
+      functionName: 'getResolver',
+      args:         [label.toLowerCase(), tld.toLowerCase()],
+    });
+  }
+
+  /**
+   * Fetch full record details (owner, resolver, expiry, locked).
+   * @param {string} name  e.g. "alice.axq"
+   * @returns {Promise<{owner: string, resolver: string, expiry: bigint, locked: boolean}>}
+   */
+  async getRecord(name) {
+    const { label, tld } = parseName(name);
+    const nameHash = computeNameHash(label.toLowerCase(), tld.toLowerCase());
+
+    const [owner, resolver, expiry, locked] = await this.client.readContract({
+      address:      this.registryAddress,
+      abi:          ANS_REGISTRY_ABI,
+      functionName: 'records',
+      args:         [nameHash],
+    });
+
+    return { owner, resolver, expiry, locked };
+  }
+
+  /**
+   * Check whether a name is registered and not expired.
+   * @param {string} name  e.g. "alice.axq"
+   * @returns {Promise<boolean>}
+   */
+  async isRegistered(name) {
+    try {
+      const record = await this.getRecord(name);
+      const now    = BigInt(Math.floor(Date.now() / 1000));
+      return record.owner !== '0x0000000000000000000000000000000000000000'
+          && record.expiry > now;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get registration fee for a TLD (in wei).
+   * @param {string} tld  e.g. "axq"
+   * @returns {Promise<bigint>}
+   */
+  async getRegistrationFee(tld) {
+    const tldHash = keccak256(new TextEncoder().encode(tld.toLowerCase()));
+    return this.client.readContract({
+      address:      this.registryAddress,
+      abi:          ANS_REGISTRY_ABI,
+      functionName: 'tldFees',
+      args:         [tldHash],
+    });
+  }
+
+  /**
+   * Check whether a TLD is supported by the registry.
+   * @param {string} tld  e.g. "axq"
+   * @returns {Promise<boolean>}
+   */
+  async isTldSupported(tld) {
+    const tldHash = keccak256(new TextEncoder().encode(tld.toLowerCase()));
+    return this.client.readContract({
+      address:      this.registryAddress,
+      abi:          ANS_REGISTRY_ABI,
+      functionName: 'supportedTlds',
+      args:         [tldHash],
+    });
+  }
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+module.exports = { ANSResolver, SUPPORTED_TLDS, computeNameHash, parseName };

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.