npm package: @pharosnames/pnsjs
Description: Pharos Name Service (PNS) JavaScript library
Author: Pharos Domains
Latest version: 1.0.4

# @pharosnames/pnsjs

The Pharos Name Service (PNS) JavaScript library provides a comprehensive interface for interacting with the Pharos Name Service, a decentralized naming system built on the Pharos blockchain. PNSJS is built on top of the popular ENSJS library, adapted specifically for the Pharos network using `.phrs` domains.

## Features

- 🔗 Resolve PNS names to addresses and vice versa
- 📝 Manage text records (email, url, description, etc.)
- 🌐 Multi-coin address resolution
- 🛠️ Full TypeScript support
- 📦 Built on proven ENSJS architecture with ENSJS compatibility
- ⚡ Pharos testnet support
- 🔐 Address encoder for 100+ cryptocurrencies

## Installation

```bash
npm install @pharosnames/pnsjs
```

## Quick Start

```javascript
import { http } from "viem";
import { createEnsPublicClient } from "@pharosnames/pnsjs";
import { pharosTestnetChain } from "@pharosnames/pnsjs/contracts";
import { evmCoinNameToTypeMap } from "@pharosnames/address-encoder";

const PHAROS_COIN_TYPE = evmCoinNameToTypeMap["phrs"];

const client = createEnsPublicClient({
  chain: pharosTestnetChain,
  transport: http(),
});

(async () => {
  // Check if a name is available
  const available = await client.getAvailable({
    name: "test.phrs",
  });
  console.log("Available:", available);

  // Get address record
  const address = await client.getAddressRecord({
    name: "test.phrs",
    coin: PHAROS_COIN_TYPE,
  });
  console.log("Address:", address);

  // Reverse resolution - get name from address
  const name = await client.getName({
    address: "0x1234567890123456789012345678901234567890",
  });
  console.log("Name:", name);
})();
```

## API Reference

### Creating a Client

Create a public client for read operations:

```javascript
import { createEnsPublicClient } from "@pharosnames/pnsjs";
import { pharosTestnetChain } from "@pharosnames/pnsjs/contracts";

const client = createEnsPublicClient({
  chain: pharosTestnetChain,
  transport: http("https://your-rpc-url"),
});
```

### Core Functions

#### Name Availability

Check if a `.phrs` name is available for registration:

```javascript
const available = await client.getAvailable({
  name: "example.phrs",
});
console.log(available); // true/false
```

#### Address Resolution

Get address for a name and reverse resolution:

```javascript
import { evmCoinNameToTypeMap } from "@pharosnames/address-encoder";

const PHAROS_COIN_TYPE = evmCoinNameToTypeMap["phrs"];

// Get Pharos address for a name
const address = await client.getAddressRecord({
  name: "example.phrs",
  coin: PHAROS_COIN_TYPE,
});

// Get name for an address (reverse resolution)
const name = await client.getName({
  address: "0x1234567890123456789012345678901234567890",
});
```

#### Multi-Coin Support

Get addresses for different cryptocurrencies:

```javascript
import { evmCoinNameToTypeMap } from "@pharosnames/address-encoder";

// Get Bitcoin address
const btcAddress = await client.getAddressRecord({
  name: "example.phrs",
  coin: evmCoinNameToTypeMap["btc"],
});

// Get Ethereum address
const ethAddress = await client.getAddressRecord({
  name: "example.phrs",
  coin: evmCoinNameToTypeMap["eth"],
});
```

#### Text Records and Multiple Records

Get text records and multiple record types at once:

```javascript
// Get multiple records in one call
const records = await client.getRecords({
  name: "example.phrs",
  texts: ["description", "url", "email"],
  coins: [PHAROS_COIN_TYPE],
});

console.log(records.texts); // { description: "...", url: "...", email: "..." }
console.log(records.coins); // [{ id: 2148172336, name: "phrs", value: "0x..." }]
```

## Address Encoder Integration

PNSJS includes full address encoder functionality with built-in support for Pharos and 100+ other cryptocurrencies:

```javascript
import {
  getCoderByCoinName,
  getCoderByCoinType,
  coinTypeToNameMap,
  coinNameToTypeMap,
  evmCoinNameToTypeMap,
} from "@pharosnames/address-encoder";

// Get Pharos coin type
const PHAROS_COIN_TYPE = evmCoinNameToTypeMap["phrs"]; // 2148172336

// Get coder by coin name
const pharosCoder = getCoderByCoinName("phrs");
console.log(pharosCoder.coinType); // 2148172336
console.log(pharosCoder.name); // "phrs"

// Access coin type mappings
console.log(coinTypeToNameMap["2148172336"]); // ["phrs", "Pharos"]
console.log(coinNameToTypeMap["phrs"]); // 2148172336
```

## Network Configuration

### Pharos Testnet

The library comes with Pharos testnet configuration:

```javascript
import { pharosTestnetChain } from "@pharosnames/pnsjs/contracts";

const client = createEnsPublicClient({
  chain: pharosTestnetChain,
  transport: http("https://pharos-testnet-rpc-url"),
});
```

## Examples

### Complete Example

```javascript
import { http } from "viem";
import { createEnsPublicClient } from "@pharosnames/pnsjs";
import { pharosTestnetChain } from "@pharosnames/pnsjs/contracts";
import { evmCoinNameToTypeMap } from "@pharosnames/address-encoder";

const PHAROS_COIN_TYPE = evmCoinNameToTypeMap["phrs"];

// continue to use createEnsPublicClient for better compatibility with ensjs
const client = createEnsPublicClient({
  chain: pharosTestnetChain,
  transport: http(),
});

async function demonstratePNS() {
  try {
    // Check if a name is available
    const available = await client.getAvailable({
      name: "myname.phrs",
    });
    console.log("Available:", available);

    // Get address record
    const address = await client.getAddressRecord({
      name: "myname.phrs",
      coin: PHAROS_COIN_TYPE,
    });
    console.log("Address Record:", address);

    // Reverse resolution
    const name = await client.getName({
      address: "0x1234567890123456789012345678901234567890",
    });
    console.log("Name:", name);

    // Get multiple records
    const records = await client.getRecords({
      name: "myname.phrs",
      texts: ["description", "url"],
      coins: [PHAROS_COIN_TYPE],
    });
    console.log("Text Records:", records.texts);
    console.log("Coin Records:", records.coins);
  } catch (error) {
    console.error("Error:", error);
  }
}

demonstratePNS();
```

### Multi-Coin Address Resolution

```javascript
import { evmCoinNameToTypeMap } from "@pharosnames/address-encoder";

async function getMultiCoinAddresses() {
  const name = "example.phrs";

  // Get addresses for different cryptocurrencies
  const pharosAddress = await client.getAddressRecord({
    name,
    coin: evmCoinNameToTypeMap["phrs"],
  });

  const bitcoinAddress = await client.getAddressRecord({
    name,
    coin: evmCoinNameToTypeMap["btc"],
  });

  const ethereumAddress = await client.getAddressRecord({
    name,
    coin: evmCoinNameToTypeMap["eth"],
  });

  const polygonAddress = await client.getAddressRecord({
    name,
    coin: evmCoinNameToTypeMap["matic"],
  });

  console.log({
    pharos: pharosAddress,
    bitcoin: bitcoinAddress,
    ethereum: ethereumAddress,
    polygonAddress: polygonAddress,
  });
}

getMultiCoinAddresses();
```

## License

MIT License