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)