Quickstart

In this guide you will find the address that holds a GitHub handle, and then the GitHub handle that address publishes. You only read from the chain, so you need no wallet and no tokens.

Set up

You need Node.js 20 or later, and a network that runs libID with some identities bound. Start the local chain first: it binds known handles, including octocat. When local.env is loaded, RPC_URL and IDENTITY_REGISTRY are set.

Create a project and install viem and the libID contracts package:

mkdir libid-quickstart && cd libid-quickstart
npm init -y
npm install viem @libid/contracts

Connect to IdentityRegistry

IdentityRegistry is the contract that stores which address holds which identity: a platform account it has proved.

Create index.mjs:

import { createPublicClient, http } from 'viem';
import { platformId, resolveHandle, publishedHandleOf } from '@libid/contracts';

const registry = {
  client: createPublicClient({ transport: http(process.env.RPC_URL) }),
  address: process.env.IDENTITY_REGISTRY,
};

const github = platformId('github');

Every platform has an id. platformId('github') is the keccak256 hash of the string github. The other platforms are 'x' and 'google'.

Find the holder of a handle

Add this to index.mjs:

const holder = await resolveHandle(registry, github, 'octocat');
console.log(holder);

resolveHandle returns the address that proved it holds the handle, or null if nobody has. Handles are matched the way the platform matches them, so octocat, Octocat and @octocat are the same GitHub handle.

Find the handle of a holder

Now go the other way:

if (holder) {
  const handle = await publishedHandleOf(registry, holder, github);
  console.log(handle);
}

publishedHandleOf returns the handle the holder published on that platform. It returns null if the holder has not published one, or if the handle now belongs to someone else.

Run it

node index.mjs

On the local chain you will see:

0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC
octocat

Without code

You can make the same call with Foundry’s cast:

cast call $IDENTITY_REGISTRY 'resolveHandle(bytes32,string)(address)' \
  $(cast keccak github) octocat --rpc-url $RPC_URL

On a public network

Set RPC_URL to the network’s RPC, and IDENTITY_REGISTRY to the address IdentityRegistry has there:

Networks	IDENTITY_REGISTRY
Ethereum mainnet	0xbefd300aff7d4a67fb381afe8b3596793d3e9a83
Sepolia, Eden testnet	0x25f29c8c765db2f27d1e2b23987a7b0655c7d640

See Addresses for the other contracts.

Next steps

• Resolve a handle covers what else you can learn about a handle, such as when it was last proved.
• Look up a wallet lists every identity an address holds.
• Gate a contract does the same checks from Solidity.