@x1ns/sdk

TypeScript SDK for X1 Name Service (X1NS) - Decentralized domain name service on the X1 blockchain.

X1NS provides human-readable domain names (.x1, .xnt, .xen) for X1 blockchain addresses, making Web3 interactions more user-friendly.

Installation

npm install @x1ns/sdk
# or
pnpm add @x1ns/sdk

Usage

Basic Domain Resolution

import { createClient } from "@x1ns/sdk";

const client = createClient({ network: "testnet" });

// Resolve a domain
const domain = await client.resolveDomain("example.x1");
if (domain) {
  console.log("Owner:", domain.owner.toBase58());
}

// Check availability
const available = await client.isDomainAvailable("myname.x1");
console.log("Available:", available);

// Get pricing (async - fetches from on-chain config)
await client.fetchPricingConfig(); // Optional: pre-fetch pricing config
const price = await client.getFormattedPrice("myname");
console.log("Price:", price); // e.g., "1 XNT"

// Or use sync method (uses cached config or defaults)
const syncPrice = client.getFormattedPriceSync("myname");
console.log("Price:", syncPrice);

Network Configuration

import { createClient } from "@x1ns/sdk";

// Testnet (default)
const client = createClient({ network: "testnet" });

// Mainnet
const mainnetClient = createClient({ network: "mainnet" });

// Custom RPC
const customClient = createClient({
  network: "testnet",
  rpcUrl: "https://my-custom-rpc.xyz",
});

Features

• ✅ Domain Resolution - Resolve .x1, .xnt, and .xen domains to addresses
• ✅ Availability Checking - Check if domains are available for registration
• ✅ Dynamic Pricing - Fetch real-time pricing from on-chain configuration
• ✅ Domain Registration - Build transaction instructions for domain registration
• ✅ Domain Transfer - Transfer domains between addresses
• ✅ Domain Deletion - Delete domains and free up accounts
• ✅ Reverse Lookup - Find domains owned by an address
• ✅ TLD Validation - Validate domain names and TLDs
• ✅ Multi-Network Support - Works with testnet, mainnet, and devnet
• ✅ TypeScript - Full TypeScript support with type definitions

API Reference

createClient(options?)

Creates an X1NS client instance.

Parameters:

• options.network - Target network ("testnet" | "mainnet" | "devnet" | "localnet")
• options.rpcUrl - Custom RPC endpoint (optional)

Returns: X1NSClient

client.resolveDomain(domain)

Resolves a domain to its owner and data.

Parameters:

• domain - Full domain name (e.g., "example.x1")

Returns: Promise<DomainInfo | null>

client.isDomainAvailable(domain)

Checks if a domain is available for registration.

Parameters:

• domain - Full domain name

Returns: Promise<boolean>

client.fetchPricingConfig()

Fetches pricing configuration from on-chain account. Automatically called by pricing methods if not cached.

Returns: Promise<PricingConfig | null>

client.getDomainPrice(name, useCache?)

Gets registration price based on name length. Fetches from on-chain config if not cached.

Parameters:

• name - Domain name without TLD
• useCache - Whether to use cached pricing config (default: true)

Returns: Promise<bigint> (price in lamports)

client.getFormattedPrice(name, useCache?)

Gets human-readable price string. Fetches from on-chain config if not cached.

Parameters:

• name - Domain name without TLD
• useCache - Whether to use cached pricing config (default: true)

Returns: Promise<string> (e.g., "1 XNT")

client.getDomainPriceSync(name)

Synchronous version that uses cached pricing config or defaults.

Parameters:

• name - Domain name without TLD

Returns: bigint (price in lamports)

client.getFormattedPriceSync(name)

Synchronous version that uses cached pricing config or defaults.

Parameters:

• name - Domain name without TLD

Returns: string (e.g., "1 XNT")

client.registerDomain(domain, buyer, space?)

Builds transaction instructions for domain registration.

Parameters:

• domain - Full domain name (e.g., "example.x1")
• buyer - Buyer's public key (signer)
• space - Space to allocate (default: 1000 bytes)

Returns: Promise<TransactionInstruction[]>

Pricing

Pricing is dynamically fetched from on-chain configuration. Current testnet pricing:

• 1 character: 20 XNT
• 2 characters: 15 XNT
• 3 characters: 10 XNT
• 4 characters: 3 XNT
• 5+ characters: 1 XNT

The SDK automatically fetches pricing from the on-chain PricingConfig account and caches it for 1 minute. If the config is not found, it falls back to default pricing.

Supported TLDs

X1NS supports three top-level domains:

• .x1 - Premium namespace for X1 blockchain
• .xnt - Native token themed TLD
• .xen - Community TLD

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0.0 (for TypeScript projects)

Contributing

Contributions are welcome! For questions or contributions, please contact [email protected].

License

MIT License - see LICENSE file for details.

Links

• 🌐 Website: x1ns.xyz
• 🔗 X1 Blockchain: x1.xyz
• 🐦 Twitter: @x1ns_xnt

Support

• 📧 Email: [email protected]