Skip to content
/ sdk Public

A JavaScript/TypeScript SDK for interacting with Self Crypto names and their metadata.

Notifications You must be signed in to change notification settings

selfcrypto/sdk

Repository files navigation

Self SDK

A JavaScript/TypeScript SDK for interacting with Self Crypto names and their metadata.

Installation

npm install @selfcrypto/sdk [email protected]

or

yarn add @selfcrypto/sdk [email protected]

or

pnpm add @selfcrypto/sdk [email protected]

Quick Start

import { SelfSDK } from "@selfcrypto/sdk";
const sdk = new SelfSDK();

// Resolve a name to its BSC address
const address = await sdk.resolveName("ricomaverick");
console.log(address); // 0x383D8ee00c3Ea31dd4eb6e5eCf649Bc9C08D8e31

// Get cross-chain address
const ethAddress = await sdk.resolveCrossChain("ricomaverick", "eth");
console.log(ethAddress); // 0x383D8ee00c3Ea31dd4eb6e5eCf649Bc9C08D8e31

// Get complete metadata
const metadata = await sdk.resolveMetadata("ricomaverick");
console.log(metadata);

Configuration

You can customize the SDK with your own RPC URL and IPFS gateway:

const sdk = new SelfSDK({
rpcUrl: "https://your-rpc-url",
ipfsGateway: "https://your-ipfs-gateway/ipfs/"
});

API Reference

resolveName(name: string): Promise<string>

Resolves a SELF name to default address i.e owner of the name(NFT).

resolveCrossChain(name: string, chain: string): Promise<string>

Resolves a SELF name to its address on a specific chain.

resolveMetadata(name: string): Promise<Metadata>

Resolves a SELF name to its metadata.

The metadata includes:

  • Name
  • Description
  • Profile image
  • Email (if available)
  • Cross-chain addresses

Utility Functions

hashName(name: string): string

Utility method to hash a name.

isValidName(name: string): boolean

Utility method to validate a name.

Types

interface ResolverOptions {
  rpcUrl?: string;
  ipfsGateway?: string;
}

interface Metadata {
  name: string;
  description: string;
  image: string;
  email?: string;
  foreignAddresses: {
    [key in ChainIntegrationKey]?: {
      address: string;
    };
  };
}

type ChainIntegrationKey = "eth" | "bsc" | "btc" | /* ... other chains ... */;

Error Handling

The SDK throws errors in these cases:

  • Invalid name format
  • Non-existent name
  • Network errors
  • Invalid RPC URL
  • Failed metadata resolution

Supported chains:

  • EVM: eth, bsc, polygon, avax, arb
  • Non-EVM: btc, ltc, xmr, trx, nim, ada, sol, xlm, xrp, eos, klv, dot
  • Other: bnb, strk

Upcoming Features

The following features are planned for future releases:

  • hasChainAddress() - Check if name has an address for a specific chain
  • getConfiguredChains() - Get all chains with configured addresses
  • getSummary() - Get a quick summary of name metadata
  • getDescription() - Get name description
  • getEmail() - Get associated email
  • getImage() - Get profile image URL

Development

Prerequisites

  • Node.js 16+
  • pnpm (npm install -g pnpm)

Setup

# Install dependencies
pnpm install

Development Workflow

# Watch mode - rebuilds on file changes
pnpm dev

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Type checking
pnpm lint

Building

# Build the package
pnpm build

Publishing

This package uses changesets for versioning and publishing.

# Create a new changeset
pnpm changeset

# Push your changes
git push origin main

The publishing process is automated through GitHub Actions:

  1. After pushing changes with a changeset:

    • GitHub Actions will build and test the code
    • If tests pass, it creates a "Version Packages" PR
    • The PR includes version bumps and CHANGELOG updates
  2. When the PR is merged:

    • GitHub Actions automatically publishes to npm
    • Creates a new git tag
    • Updates the CHANGELOG.md

Note: Make sure your changes include a changeset file (created with pnpm changeset) describing the changes. This is required for the automated release process.

Environment Variables

  • NPM_TOKEN - Required for publishing to npm

Project Structure

src/
├── constants/     # Constants and configuration
├── resolvers/     # Core resolver implementations
├── types/        # TypeScript type definitions
├── utils/        # Internal utilities
└── index.ts      # Main entry point

Testing

Tests are written using Jest. Each resolver has its own test file in a __tests__ directory.

src/
├── resolvers/
│   ├── __tests__/
│   │   ├── nameResolver.test.ts
│   │   ├── metadataResolver.test.ts
│   │   └── integration.test.ts
└── utils/
    └── __tests__/
        └── utils.test.ts