G

sdk.identity

sdk.identity

Resolve .gao domains, verify ownership, and validate signatures. All reads are public and verifiable without authentication.


Resolve a Domain#

const record = await sdk.identity.resolve('alice.gao')
interface DomainRecord {
  domain:          string    // "alice.gao"
  owner_address:   string    // EVM wallet address
  public_key:      string    // Ed25519 public key (for signature verification)
  records:         Record<string, string>  // custom DNS-style records
  agent_metadata?: AgentMeta               // if domain has linked agents
  chain:           string    // "base"
  updated_at:      number    // unix timestamp
}

Returns null if domain not registered.


Get Address for a Chain#

const address = await sdk.identity.getAddress('alice.gao', 'base')
// → "0x1234abcd..."

const address = await sdk.identity.getAddress('alice.gao', 'ethereum')
// → "0x1234abcd..." (same address if EVM-compatible)

Verify Domain Ownership#

const isOwner = await sdk.identity.isOwner('alice.gao', '0x1234abcd...')
// → true | false

Use this to gate features to verified domain owners.


Verify a Signature#

Challenge-response pattern for domain-based auth:

// 1. Your server issues a challenge
const challenge = `gao_auth_${crypto.randomUUID()}_${Date.now()}`

// 2. User signs with their wallet / Passkey
// (this happens client-side)
const signature = await userWallet.signMessage(challenge)

// 3. Verify on your server
const valid = await sdk.identity.verifySignature(
  'alice.gao',     // claimed domain
  challenge,       // original message
  signature        // user's signature
)

if (valid) {
  // User proved they control alice.gao
  issueSession('alice.gao')
}

Agent Metadata (AIP-01)#

Domains can publish agent metadata — discoverable by other services.

// Read agent metadata
const meta = await sdk.identity.getAgentMeta('merchant.gao')
// meta.agent_id, meta.capabilities, meta.endpoint, meta.version

// Publish metadata (requires domain ownership)
await sdk.identity.publishAgentMeta('myapp.gao', {
  agent_id: 'booking-agent',
  capabilities: ['intelligence:agent:run'],
  endpoint: 'https://myapp.gao/agent',
  version: '1.0.0',
})

React Hook#

import { useIdentity } from '@gao/system-sdk/react'

function ProfileCard({ domain }: { domain: string }) {
  const { resolve, identity, loading } = useIdentity(sdk)

  useEffect(() => { resolve(domain) }, [domain])

  if (loading) return <Skeleton />
  if (!identity) return <NotFound />

  return (
    <div>
      <h2>{identity.domain}</h2>
      <p>{identity.owner_address}</p>
    </div>
  )
}

Common Patterns#

Domain-Gated Content

async function checkAccess(userDomain: string, walletAddress: string): Promise<boolean> {
  const record = await sdk.identity.resolve(userDomain)
  if (!record) return false
  return sdk.identity.isOwner(userDomain, walletAddress)
}

DAO Member Verification

async function isDAOMember(domain: string): Promise<boolean> {
  const record = await sdk.identity.resolve(domain)
  if (!record) return false
  // Check if domain address holds DAO membership NFT or token
  return checkMembership(record.owner_address)
}

Login with Gao Domain

// Server-side login handler
async function handleLogin(domain: string, signature: string, challenge: string) {
  const valid = await sdk.identity.verifySignature(domain, challenge, signature)
  if (!valid) throw new Error('Authentication failed')

  const record = await sdk.identity.resolve(domain)
  return { domain, address: record.owner_address }
}

Notes#

  • All resolve() calls are read-only and publicly verifiable — no auth required

  • Domain resolution is cached for 5 minutes in the SDK — subsequent calls within TTL are instant

  • verifySignature() supports both wallet signatures (ECDSA) and Passkey signatures (EdDSA)


PreviousCapability TokensNextsdk.settlement