Starknetid.js

Starknetid.js

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-goerli.g.alchemy.com/v2/${process.env.NEXT_PUBLIC_ALCHEMY_KEY}`,
        },
      }),
      constants.StarknetChainId.SN_GOERLI
    );
  }, []);
 
  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;

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:

NameTypeDescription
domainstringThe StarkName to resolve

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:

NameTypeDescription
addressstringThe address to resolve

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:

NameTypeDescription
addressesstring[]The addresses to resolve
multicallContract?stringOptional multicall contract

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:

NameTypeDescription
domainstringThe domain to resolve

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:

NameTypeDescription
idDomainOrAddrstringstarknet id, domain or hexadecimal address
fieldstringThe field to fetch

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:

NameTypeDescription
idDomainOrAddrstringThe domain or id to resolve
fieldstringThe field to fetch
lengthnumberSize of field to fetch

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:

NameTypeDescription
idDomainOrAddrstringstarknet id, domain or hexadecimal address
fieldstringThe field to fetch

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:

NameTypeDescription
idDomainOrAddrstringstarknet id, domain or hexadecimal address
fieldstringThe field to fetch
verifier?stringOptional verifier contract address

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:

NameTypeDescription
idDomainOrAddrstringstarknet id, domain or hexadecimal address
fieldstringThe field to fetch
lengthnumberThe size of the field
verifier?stringOptional verifier contract address

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:

NameTypeDescription
idDomainOrAddrstringstarknet id, domain or hexadecimal address
fieldstringThe field to fetch
verifier?stringOptional verifier contract address

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:

NameTypeDescription
idDomainOrAddrstringstarknet id, domain or hexadecimal address
verifier?stringOptional verifier contract address

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:

NameTypeDescription
addressstringHexadecimal account address
useDefaultPfpbooleanGet default pfp url if none was set by the user
verifier?stringOptional contract address for social networks verifier
pfp_verifier?stringOptional contract address for profile picture verifier
pop_verifier?stringOptional contract address for proof of personhood verifier

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.

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

NameTypeDescription
encodedBigInt[]Array of big integers to decode

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

NameTypeDescription
domainstring | undefined | nulldomain to encode

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

NameTypeDescription
domainstringdomain to check

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

NameTypeDescription
domainstring | undefineddomain to check

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

NameTypeDescription
domainstring | undefineddomain to check

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

NameTypeDescription
domainstring | undefineddomain to check

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

NameTypeDescription
domainstring | undefineddomain to check

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

NameTypeDescription
chainIdStarknetChainIdchain on which the contract was deployed

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

NameTypeDescription
chainIdStarknetChainIdchain on which the contract was deployed

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

NameTypeDescription
chainIdStarknetChainIdchain on which the contract was deployed

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

NameTypeDescription
chainIdStarknetChainIdchain on which the contract was deployed

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

NameTypeDescription
chainIdStarknetChainIdchain on which the contract was deployed

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

NameTypeDescription
chainIdStarknetChainIdchain on which the contract was deployed

Returns:

A string representing the multicall contract address.