Starknet ID SDK

Starknetid.js is a JavaScript library that facilitates interaction with the Starknet ID protocol. Whether you're a dApp developer or a blockchain enthusiast, this library provides utility functions to seamlessly integrate Starknet ID into your projects.

🔗 View the source code on GitHub (opens in a new tab)

Installation

Please note: Use version 3.0.2 of starknetid.js for compatibility with both testnet and mainnet.

# using npm
npm install starknetid.js starknet@next
 
# using yarn
yarn install starknetid.js starknet@next

Note: The latest version of starknetid.js is compatible with starknet@1.5.3. For older versions, use starknetid.js@0.1.5.

Usage for dApp developers

Basic usage

Import StarknetIdNavigator to access various Starknet ID functions. Initialize it with a provider and a chain ID.

With Starknet.js

import { StarknetIdNavigator } from "starknetid.js";
import { Provider, constants } from "starknet";
 
const provider = new Provider();
const starknetIdNavigator = new StarknetIdNavigator(
  provider,
  constants.StarknetChainId.SN_MAIN
);
const addr = await starknetIdNavigator.getAddressFromStarkName("test.stark");

With Starknet-react

import { StarknetIdNavigator } from "starknetid.js";
import { useProvider, useNetwork, useAccount } from "starknet";
import { constants } from "starknet";
 
const { provider } = useProvider();
const { chain } = useNetwork();
const { address } = useAccount();
const starknetIdNavigator = new StarknetIdNavigator(
  provider,
  chain.id as constants.StarknetChainId
);
const starkname = await starknetIdNavigator.getStarkName(address ?? "");

Button Component

ConnectButton is a React component that allows users to connect their wallets to Starknet. It leverages starknet.js and get-starknet for blockchain interactions and starknetid.js for user profile data retrieval.

import { FunctionComponent, useEffect, useMemo, useState } from "react";
import {
  type ConnectOptions,
  type DisconnectOptions,
  connect,
  disconnect,
} from "get-starknet";
import { Provider, constants } from "starknet";
import { StarknetIdNavigator, type StarkProfile } from "starknetid.js";
 
const ConnectButton: FunctionComponent = () => {
  const [isConnected, setIsConnected] = useState(false);
  const [address, setAddress] = useState("");
  const [profile, setProfile] = useState<StarkProfile>();
 
  const starknetIdNavigator = useMemo(() => {
    return new StarknetIdNavigator(
      new Provider({
        rpc: {
          nodeUrl: `https://starknet-sepolia.g.alchemy.com/v2/${process.env.NEXT_PUBLIC_ALCHEMY_KEY}`,
        },
      }),
      constants.StarknetChainId.SN_SEPOLIA
    );
  }, []);
 
  useEffect(() => {
    if (!starknetIdNavigator || !address) return;
    (async () => {
      const data = await starknetIdNavigator?.getProfileData(address);
      if (!data) return;
      if (data) setProfile(data);
    })();
  }, [address, starknetIdNavigator]);
 
  function handleConnect(options?: ConnectOptions) {
    return async () => {
      const res = await connect(options);
      setIsConnected(true);
      setAddress(res?.selectedAddress || "");
    };
  }
 
  function handleDisconnect(options?: DisconnectOptions) {
    return async () => {
      await disconnect(options);
      setIsConnected(false);
      setAddress("");
    };
  }
 
  return !isConnected ? (
    <button
      onClick={handleConnect({ modalMode: "alwaysAsk" })}
      className="relative w-[200px] h-12 text-black font-bold uppercase border-2 m-1 px-8 py-0 rounded-md"
    >
      Connect
    </button>
  ) : (
    <button
      onClick={handleDisconnect()}
      className="relative w-[300px] h-12 leading-10 text-black font-bold uppercase block text-center border-2 m-1 px-8 py-0 rounded-md"
    >
      <div className="flex items-center justify-between">
        <div className="flex flex-row gap-1.5 items-center justify-around">
          <p className="capitalize font-bold text-base font-bold mr-8">
            {profile?.name}
          </p>
          <div className="absolute self-stretch w-px right-16 inset-y-0 bg-black" />
        </div>
        <div>
          <img
            src={profile?.profilePicture}
            width="32"
            height="32"
            className="rounded-full"
          />
        </div>
      </div>
    </button>
  );
};
 
export default ConnectButton;

Leaderboard

With the getStarkProfiles (opens in a new tab) function, you can retrieve the starkname and profile picture URL of a list of addresses. This is useful for displaying a leaderboard with user stark names and profile pictures.

const addresses = [
  "0x061b6c0a78f9edf13cea17b50719f3344533fadd470b8cb29c2b4318014f52d3",
  "0x0302de76464d4e2447F2d1831fb0A1AF101B18F80964fCfff1aD831C0A92e1fD",
];
const starknetIdNavigator = new StarknetIdNavigator(
  new Provider({
    rpc: {
      nodeUrl: `https://starknet-sepolia.g.alchemy.com/v2/${process.env.NEXT_PUBLIC_ALCHEMY_KEY}`,
    },
  }),
  constants.StarknetChainId.SN_SEPOLIA
);
const profiles: StarkProfile[] = await starknetIdNavigator?.getStarkProfiles(
  addresses
);

Using custom contracts

You can also use starknetid.js with your custom naming and identity contracts.

import { StarknetIdNavigator } from "starknetid.js";
 
const starknetIdNavigator = new StarknetIdNavigator(
  provider,
  constants.StarknetChainId.SN_MAIN,
  {
    naming: customNamingContract,
    identity: customIdentityContract,
  }
);

Util functions

Utility functions can be accessed directly through the utils namespace.

import { utils } from "starknetid.js";
 
const encodedDomain = utils.encodeDomain("test.stark");

SDK

Resolving domains

getAddressFromStarkName

Retrieves the address corresponding to the provided StarkName.

▸ StarknetIdNavigator.getAddressFromStarkName(domain: string) => Promise<string>

Parameters:

Returns:

Promise<string> representing the address as hexadecimal. Throws an error if the domain is invalid.

Example usage:

const address = await starknetIdNavigator.getAddressFromStarkName("test.stark");

getStarkName

Get Starkname from address.

▸ StarknetIdNavigator.getStarkName(address: string) => Promise<string>

Parameters:

Returns:

A Promise<string> representing the domain. Throws an error if the address is invalid.

Example usage:

const domain = await starknetIdNavigator.getStarkName(
  "0x061b6c0a78f9edf13cea17b50719f3344533fadd470b8cb29c2b4318014f52d3"
);

getStarkNames

Get Stark names from addresses.

▸ StarknetIdNavigator.getStarkNames(addresses: string[], multicallContract?: string) => Promise<string[]>

Parameters:

Returns:

A Promise<string[]> representing the domains. If an address is invalid or does not have a stark name, it will return an empty string.

Example usage:

const domains = await starknetIdNavigator.getStarkNames([
  "0x061b6c0a78f9edf13cea17b50719f3344533fadd470b8cb29c2b4318014f52d3",
  "0x0302de76464d4e2447F2d1831fb0A1AF101B18F80964fCfff1aD831C0A92e1fD",
]);

getStarknetId

Get Starknet id from domain.

▸ StarknetIdNavigator.getStarknetId(domain: string) => Promise<string>

Parameters:

Returns:

A Promise<string> representing the id. Throws an error if the domain is invalid.

Example usage:

const id = await starknetIdNavigator.getStarknetId("fricoben.stark");

Resolving user data

getUserData

Get user data from starknet id, domain or address.

▸ StarknetIdNavigator.getUserData(idDomainOrAddr: string, field: string) => Promise<BigInt>

Parameters:

Returns:

A Promise<BigInt> representing the user data. Throws an error if the idDomainOrAddr is invalid.

getExtentedUserData

Get user data from starknet id, address or domain. Use this function to retrieve an array knowing its size. It will return zeros if not written.

▸ StarknetIdNavigator.getExtentedUserData(idDomainOrAddr: string, field: string, length: number) => Promise\<BigInt[]`>

Parameters:

Returns:

A Promise<BigInt[]> representing the user extended data. Throws an error if the idDomainOrAddr is invalid.

getUnboundedUserData

Get User unbounded data from starknet id, address or domain. Use this function to retrieve an array up to zero (not included).

▸ StarknetIdNavigator.getUnboundedUserData(idDomainOrAddr: string, field: string) => Promise<BigInt[]>

Parameters:

Returns:

A Promise<BigInt[]> representing the user unbounded data. Throws an error if the idDomainOrAddr is invalid.

Resolving verifier data

getVerifierData

Get verifier data from starknet id, address or domain. If no verifier contract is provided, it will return the Starknet ID verifier contract address deployed on the StarknetIdNavigator provider chain id.

▸ StarknetIdNavigator.getVerifierData(idDomainOrAddr: string, field: string, verifier?: string) => Promise<BigInt>

Parameters:

Returns:

A Promise<BigInt[]> representing the user verifier data.

Errors:

• Throws an error if the idDomainOrAddr is invalid.
• Returns 0x0 when field in custom verifier contract does not exist or id does not exists.

Example usage:

const data = await starknetIdNavigator.getVerifierData(
  "fricoben.stark",
  "discord"
);

getExtendedVerifierData

Get extended verifier data from starknet id, address or domain. Use this function to retrieve an array knowing its size. It will return zeros if not written. If no verifier contract is provided, it will return the Starknet ID verifier contract address deployed on the StarknetIdNavigator provider chain id.

▸ StarknetIdNavigator.getExtendedVerifierData(idDomainOrAddr: string, field: string, length: number, verifier?: string) => Promise<BigInt[]>

Parameters:

Returns:

A Promise<BigInt[]> representing the user extended verifier data. Throws an error if the idDomainOrAddr is invalid.

Errors:

• Throws an error if the idDomainOrAddr is invalid.
• Returns 0x0 when field in custom verifier contract does not exist or id does not exists.

Example usage:

const data = await starknetIdNavigator.getExtendedVerifierData(
  "fricoben.stark",
  "discord",
  1
);

getUnboundedVerifierData

Get User unbounded data from starknet id, address or domain. Use this function to retrieve an array up to zero (not included). If no verifier contract is provided, it will return the Starknet ID verifier contract address deployed on the StarknetIdNavigator provider chain id.

▸ StarknetIdNavigator.getUnboundedVerifierData(idDomainOrAddr: string, field: string, verifier?: string) => Promise<BigInt[]>

Parameters:

Returns:

A Promise<BigInt[]> representing the user unbounded verifier data. Throws an error if the idDomainOrAddr is invalid.

Errors:

• Throws an error if the idDomainOrAddr is invalid.
• Returns 0x0 when field in custom verifier contract does not exist or id does not exists.

getPfpVerifierData

Get User profile picture verifier data from starknet id, address or domain. Use this function to retrieve an array containing user domain, NFT contract address and NFT token id. If no verifier contract is provided, it will return the Starknet ID verifier contract address deployed on the StarknetIdNavigator provider chain id.

▸ StarknetIdNavigator.getPfpVerifierData(idDomainOrAddr: string, verifier?: string) => Promise<BigInt[]>

Parameters:

Returns:

A Promise<BigInt[]> representing the user profile picture verifier data. Throws an error if the idDomainOrAddr is invalid.

Errors:

• Throws an error if the idDomainOrAddr is invalid.
• Returns an array of 0x0 when user has not set a profile picture or id does not exists.

getProfileData

Get user Starknet profile data from their address. This function retrieves a user's starkname, profile picture URL, social networks IDs, and proof of personhood verification status. If no specific verifiers are provided, it defaults to using the Starknet ID verifiers contract addresses. You can disable getting the default profile picture by setting useDefaultPfp to false.

▸ StarknetIdNavigator.getProfileData(address: string, useDefaultPfp?: boolean, verifier?: string, pfp_verifier?: string, pop_verifier?: string) => Promise<StarkProfile>

Parameters:

Returns:

A Promise<StarkProfile> representing the Starknet profile data of the user. The StarkProfile includes starkname, profile picture URL, social networks IDs, and proof of personhood verification status.

type StarkProfile = {
  name?: string;
  profilePicture?: string;
  discord?: string;
  twitter?: string;
  github?: string;
  proofOfPersonhood?: boolean;
};

Errors:

• Throws an error if address is invalid.

getStarkProfiles

Get the starkname and profile picture url of a list of addresses. If no specific verifiers are provided, it defaults to using the starknet.id profile picture verifier contract address. You can disable getting the default profile picture by setting useDefaultPfp to false.

▸ StarknetIdNavigator.getStarkProfiles(address: string, useDefaultPfp?: boolean, pfp_verifier?: string) => Promise<StarkProfile[]>

Parameters:

Returns:

A Promise<StarkProfile[]> representing the Starknet profile data of the user. The StarkProfile includes starkname and profile picture URL.

type StarkProfile = {
  name?: string;
  profilePicture?: string;
};

Errors:

• If the address is invalid, or the address doesn't own a domain it will return a StarkProfile with name and profilePicture as undefined.
• If the address doesn't have a profile picture set, it will return a StarkProfile with profilePicture as undefined if useDefaultPfp is set to false.

Utils

Encoding and Decoding

decodeDomain

Converts an encoded Starknet ID domain represented as an array of big integers into a string representation.

▸ utils.decodeDomain(encoded: BigInt[]) => string

Parameters

Returns:

A string representing the decoded domain.

encodeDomain

Convert a domain or subdomain to its encoded form as an array of big integers.

▸ utils.encodeDomain(domain: string | undefined | null) => BigInt[]

Parameters

Returns:

A BigInt[] representing the encoded domain.

Domain Type Checks

isStarkDomain

Checks if a domain is a Starknet ID domain.

▸ utils.isStarkDomain(domain: string) => boolean

Parameters

Returns:

A boolean representing if the domain is a .stark domain.

isStarkRootDomain

Checks if a domain is a Starknet ID root domain.

▸ utils.isStarkRootDomain(domain: string | undefined) => boolean

Parameters

Returns:

A boolean representing if the domain is a .stark root domain.

isSubdomain

Checks if a domain is a Starknet ID subdomain.

▸ utils.isSubdomain(domain: string | undefined) => boolean

Parameters

Returns:

A boolean representing if the domain is a .stark subdomain.

isBraavosSubdomain

Checks if domain is a Braavos subdomain.

▸ utils.isBraavosSubdomain(domain: string | undefined) => boolean

Parameters

Returns:

A boolean representing if the domain is a Braavos subdomain.

isXplorerSubdomain

Checks if domain is a Xplorer subdomain

▸ utils.isXplorerSubdomain(domain: string | undefined) => boolean

Parameters

Returns:

A boolean representing if the domain is a Xplorer subdomain.

Contract Address Retrieval

getNamingContract

Retrieve the Starknet ID naming contract address based on the chain ID.

▸ utils.getNamingContract(chainId: StarknetChainId) => string

Parameters

Returns:

A string representing the naming contract address.

getIdentityContract

Retrieve the Starknet ID identity contract address based on the chain ID.

▸ utils.getIdentityContract(chainId: StarknetChainId) => string

Parameters

Returns:

A string representing the identity contract address.

getVerifierContract

Retrieve the Starknet ID verifier contract address based on the chain ID.

▸ utils.getVerifierContract(chainId: StarknetChainId) => string

Parameters

Returns:

A string representing the verifier contract address.

getPfpVerifierContract

Retrieve the Starknet ID profile picture verifier contract address based on the chain ID.

▸ utils.getPfpVerifierContract(chainId: StarknetChainId) => string

Parameters

Returns:

A string representing the profile picture verifier contract address.

getPopVerifierContract

Retrieve the Starknet ID proof of personhood verifier contract address based on the chain ID.

▸ utils.getPopVerifierContract(chainId: StarknetChainId) => string

Parameters

Returns:

A string representing the proof of personhood verifier contract address.

getMulticallContract

Retrieve the multicall contract address based on the chain ID.

🔗 View the source code on GitHub (opens in a new tab)

▸ utils.getMulticallContract(chainId: StarknetChainId) => string

Parameters

Returns:

A string representing the multicall contract address.