02. GGS-1 Identity MW API

Identity Management

GGS-1 Identity provides user profile management with privacy-preserving merkle tree verification and blockchain anchoring.

Overview

Purpose: Create and manage verifiable user identities with configurable field privacy levels.

Key Features:

• Customizable profile fields (name, bio, social links, etc.)

• Privacy levels per field (private, community, public)

• Merkle tree for verifiable credentials

• Blockchain anchoring for tamper-proof verification

• Profile image upload

Location: src/packages/identity/

---

API Endpoints

Get Current User's Identity

Fetch the authenticated user's identity profile.

Endpoint: GET /identity/

Authentication: Required (JWT)

Implementation:

import axiosInstance from '@/packages/identity/api/axiosInstance'
import type { Identity } from '@/packages/identity/types'

export const getIdentity = async () => {
  try {
    const response = await axiosInstance.get<Identity>('/identity/')
    return response.data
  } catch (error) {
    console.error('Error fetching identity:', error)
    throw error
  }
}

Response:

interface Identity {
  name?: string
  bio?: string
  location?: string
  email?: string
  phone?: string
  website?: string
  x?: string // Twitter/X
  telegram?: string
  discord?: string
  linkedin?: string
  instagram?: string
  medium?: string
  youtube?: string
  git?: string
  mastodon?: string
  image?: string // Profile image URL
  custom_fields?: { [key: string]: string }
  custom_fields_order?: Array<string>
  field_configurations?: {
    [key: string]: {
      visibility?: 'private' | 'community' | 'public'
      pepper: string
    }
  }
}

Example Response:

{
  "name": "Alice Smith",
  "bio": "Blockchain developer",
  "email": "[email protected]",
  "x": "@alice",
  "custom_fields": {
    "company": "Web3 Corp"
  },
  "custom_fields_order": ["company"],
  "field_configurations": {
    "name": {
      "visibility": "public",
      "pepper": "abc123..."
    },
    "email": {
      "visibility": "private",
      "pepper": "def456..."
    }
  }
}

Usage:

import { useQuery } from '@tanstack/react-query'
import { getIdentity } from '@/packages/identity/api/queries/identity'

function ProfilePage() {
  const { data: identity, isLoading } = useQuery({
    queryKey: ['identity'],
    queryFn: getIdentity
  })

  if (isLoading) return <div>Loading...</div>

  return (
    <div>
      <h1>{identity?.name}</h1>
      <p>{identity?.bio}</p>
    </div>
  )
}

---

Get Public Identity by ID

Fetch another user's public identity information.

Endpoint: GET /identity/public/{id}

Authentication: Not required

Parameters:

• id (path): Identity UUID

Implementation:

export const getIdentityById = async (id: string) => {
  try {
    const response = await axiosInstance.get<Identity>(`/identity/public/${id}`)
    return response.data
  } catch (error) {
    console.error(`Error fetching identity with id ${id}:`, error)
    throw error
  }
}

Response: Same structure as GET /identity/ but only includes fields with visibility: 'public'

---

Get Identity Profile Image

Download the profile image for a specific identity.

Endpoint: GET /identity/public/{id}/image

Authentication: Not required

Parameters:

• id (path): Gen6 Address

Implementation:

export const getIdentityImage = async (id: string) => {
  const response = await axiosInstance.get<Blob>(
    `/identity/public/${id}/image`,
    {
      responseType: 'blob'
    }
  )
  // Convert blob to object URL
  const imageUrl = URL.createObjectURL(response.data)
  return imageUrl
}

Response: Image object URL string

Usage:

import { useQuery } from '@tanstack/react-query'

function ProfileImage({ identityId }: { identityId: string }) {
  const { data: imageUrl } = useQuery({
    queryKey: ['identityImage', identityId],
    queryFn: () => getIdentityImage(identityId)
  })

  return imageUrl ? <img src={imageUrl} alt="Profile" /> : null
}

---

Calculate Identity Merkle Tree

Generate a merkle tree hash for identity verification.

Endpoint: POST /identity/merkle

Authentication: Not required

Purpose: Calculate the root hash before creating/updating identity to ensure data integrity.

Request:

export const calculateIdentityMerkle = async (data: IdentityMerkleRequest) => {
  const response = await axiosInstance.post<IdentityMerkleResponse>(
    '/identity/merkle',
    data,
    {
      headers: { 'Content-Type': 'application/json' }
    }
  )
  return response.data
}

Request Body:

interface IdentityMerkleRequest {
  identity: IdentityData & { g6_address: string }
  field_configurations: IdentityFieldConfigurations
}

Response:

interface IdentityMerkleResponse {
  root_hash: string
  total_nodes: number
  total_levels: number
  all_nodes: string[]
  levels: Array<Record<string, unknown>>
}

Example Request:

{
  "identity": {
    "name": "Alice Smith",
    "bio": "Developer",
    "email": "[email protected]"
  },
  "field_configurations": {
    "name": { "visibility": "public", "pepper": "abc123" },
    "bio": { "visibility": "public", "pepper": "def456" },
    "email": { "visibility": "private", "pepper": "ghi789" }
  }
}

Example Response:

{
  "root_hash": "0x7f8a9b3c...",
  "total_nodes": 7,
  "total_levels": 3,
  "all_nodes": ["0xabc...", "0xdef...", "0x789..."],
  "levels": [{ "0": "0xabc..." }, { "0": "0xdef...", "1": "0x123..." }]
}

Usage Flow:

1. User fills out identity form

2. Frontend calculates merkle tree via /identity/merkle

3. Frontend stores hash on blockchain

4. Frontend creates identity via /identity/ with the same root_hash

---

Create Identity

Create a new identity profile for the authenticated user.

Endpoint: POST /identity/

Authentication: Required (JWT)

Request:

export const createIdentity = async (data: IdentityCreateUpdateRequest) => {
  const response = await axiosInstance.post<Identity>('/identity/', data)
  return response.data
}

Request Body:

interface IdentityCreateUpdateRequest {
  identity: IdentityData
  field_configurations: Record<string, FieldConfiguration>
  root_hash: string // From /identity/merkle
  custom_fields_order?: string[] // Order for custom fields
}

Response: Created Identity object

Usage:

import { useMutation } from '@tanstack/react-query'
import { createIdentity } from '@/packages/identity/api/mutations/identity'

function CreateIdentityForm() {
  const createMutation = useMutation({
    mutationFn: createIdentity,
    onSuccess: () => {
      toast.success('Identity created!')
    }
  })

  const handleSubmit = async (formData) => {
    // 1. Calculate merkle tree
    const merkleResult = await calculateIdentityMerkle(formData)

    // 2. Store on blockchain (see Blockchain section)
    await storeOnBlockchain(merkleResult.root_hash)

    // 3. Create identity with same root_hash
    await createMutation.mutateAsync({
      ...formData,
      root_hash: merkleResult.root_hash
    })
  }

  return <form onSubmit={handleSubmit}>...</form>
}

Important: Always calculate merkle tree and store on blockchain before creating identity.

---

Update Identity

Update an existing identity profile.

Endpoint: PUT /identity/

Authentication: Required (JWT)

Request:

export const updateIdentity = async (data: IdentityCreateUpdateRequest) => {
  const response = await axiosInstance.put<Identity>('/identity/', data)
  return response.data
}

Request Body: Same as create

Response: Updated Identity object

Note: Updating identity requires recalculating the merkle tree and storing the new hash on blockchain.

---

Upload Profile Image

Upload or update the user's profile image.

Endpoint: PUT /identity/image

Authentication: Required (JWT)

Request:

export const uploadIdentityImage = async (file: File) => {
  const formData = new FormData()
  formData.append('image', file)

  const response = await axiosInstance.put<{ image_url: string }>(
    '/identity/image',
    formData
  )
  return response.data
}

Request Body: FormData with image file

Supported Formats: JPEG, PNG, GIF, WebP

File Size Limit: Check backend configuration (typically 5MB)

Response:

interface ImageUploadResponse {
  image_url: string // URL to access the uploaded image
}

Usage:

import { useMutation } from '@tanstack/react-query'

function ImageUpload() {
  const uploadMutation = useMutation({
    mutationFn: uploadIdentityImage,
    onSuccess: (data) => {
      toast.success('Image uploaded!')
      console.log('Image URL:', data.image_url)
    }
  })

  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0]
    if (file) {
      uploadMutation.mutate(file)
    }
  }

  return (
    <input
      type="file"
      accept="image/*"
      onChange={handleFileChange}
      disabled={uploadMutation.isPending}
    />
  )
}

---

Blockchain Integration

Store Identity Hash On-Chain

Anchor the identity data hash on the blockchain for tamper-proof verification.

Extrinsic: api.tx.dataRegistry.storeData()

Parameters:

• projectId: 20250923 (Identity project ID)

• dataHash: Blake2 hash of the full identity object (from deterministicObjectBlake2Hash)

Implementation:

import { useGen6 } from '@/contexts/gen6-context'
import { useSigner } from '@/hooks/useSigner'
import { deterministicObjectBlake2Hash } from '@/packages/identity/utils/deterministicHash'

export function useIdentityBlockchain() {
  const { api, currentAccount } = useGen6()
  const { getSigner } = useSigner()

  const storeIdentityOnChain = async (identityPayload: Identity) => {
    const projectId = 20250923
    const dataHash = deterministicObjectBlake2Hash(identityPayload)

    const signerResult = await getSigner()

    const extrinsic = api.tx.dataRegistry.storeData(projectId, dataHash)

    return new Promise<string>((resolve, reject) => {
      extrinsic
        .signAndSend(
          currentAccount.address,
          { signer: signerResult.signer },
          ({ status, dispatchError, txHash }) => {
            if (status.isFinalized) {
              if (dispatchError) {
                reject(new Error('Transaction failed'))
              } else {
                resolve(txHash.toString())
              }
            }
          }
        )
        .catch(reject)
    })
  }

  return { storeIdentityOnChain }
}

Usage:

function IdentityForm() {
  const { storeIdentityOnChain } = useIdentityBlockchain()

  const handleSubmit = async (identityPayload) => {
    // 1. Calculate merkle tree for database storage
    const merkleResult = await calculateIdentityMerkle({
      identity: identityPayload,
      field_configurations: fieldConfigurations
    })

    // 2. Store identity hash on blockchain
    const txHash = await storeIdentityOnChain(identityPayload)

    // 3. Create identity in database with merkle root
    await createIdentity({
      identity: identityPayload,
      field_configurations: fieldConfigurations,
      root_hash: merkleResult.root_hash
    })

    toast.success('Identity created and verified on blockchain!')
  }

  return <form onSubmit={handleSubmit}>...</form>
}

Transaction Flow:

1. User submits identity form

2. Frontend calculates Blake2 hash of full identity object for blockchain

3. Frontend calculates merkle root for database verification

4. Frontend stores hash on blockchain

5. Frontend creates identity in database with merkle root

Verification: Anyone can verify the identity by:

1. Recalculating the Blake2 hash from the identity data

2. Comparing with the on-chain hash

3. Additionally, the merkle root in the database can be used for field-level verification

---

Privacy Levels

Identity fields support three visibility levels:

Private

• Who can see: Only the identity owner

• Use case: Sensitive data (email, phone, private notes)

• Merkle tree: Included in hash but not revealed

Community

• Who can see: Gen6 community members (authenticated users)

• Use case: Semi-public data (Discord, Telegram handles)

• Merkle tree: Included in hash and partially revealed

Public

• Who can see: Everyone (no authentication required)

• Use case: Public profile (name, bio, social links)

• Merkle tree: Included in hash and fully revealed

Configuration Example:

const fieldConfigurations = {
  name: { visibility: 'public', pepper: generatePepper() },
  email: { visibility: 'private', pepper: generatePepper() },
  telegram: { visibility: 'community', pepper: generatePepper() }
}

---

Custom Fields

Add arbitrary key-value pairs to identity profiles.

Implementation:

const identity = {
  name: 'Alice',
  custom_fields: {
    'Favorite Color': 'Blue',
    'Programming Language': 'Rust',
    'Years of Experience': '5'
  }
}

const customFieldsOrder = [
  'Favorite Color',
  'Programming Language',
  'Years of Experience'
]

Privacy: Each custom field has its own visibility configuration.

Ordering: Use custom_fields_order to control display order.

---

Complete Identity Creation Flow

Step-by-Step Guide

Step 1: Prepare Identity Data

const identityData = {
  name: 'Alice Smith',
  bio: 'Blockchain developer',
  email: '[email protected]',
  x: '@alice'
}

const fieldConfigurations = {
  name: { visibility: 'public', pepper: generatePepper() },
  bio: { visibility: 'public', pepper: generatePepper() },
  email: { visibility: 'private', pepper: generatePepper() },
  x: { visibility: 'public', pepper: generatePepper() }
}

Step 2: Calculate Merkle Tree for Database

const merkleResult = await calculateIdentityMerkle({
  identity: identityData,
  field_configurations: fieldConfigurations
})

console.log('Merkle root hash:', merkleResult.root_hash)

Step 3: Store Identity Hash on Blockchain

const txHash = await storeIdentityOnChain(identityData)
console.log('Blockchain transaction hash:', txHash)

Step 4: Create Identity in Database

await createIdentity({
  identity: identityData,
  field_configurations: fieldConfigurations,
  root_hash: merkleResult.root_hash
})

Step 5: Upload Profile Image (Optional)

if (profileImage) {
  await uploadIdentityImage(profileImage)
}

---

Query Keys

TanStack Query Keys:

// Current user's identity
;['identity'][
  // Public identity by ID
  ('identity', 'public', id)
][
  // Identity image
  ('identityImage', id)
][
  // Merkle calculation
  ('identityMerkle', data)
]

---

Error Handling

Common Errors

"Identity already exists"

• Cause: User already has an identity

• Solution: Use updateIdentity() instead of createIdentity()

"Transaction failed"

• Cause: Blockchain transaction rejected

• Solution: Check wallet balance and network status

---

Best Practices

1. Always calculate merkle tree first - Ensures data integrity

2. Store on blockchain before database - Prevents orphaned hashes

3. Set appropriate visibility levels - Protect sensitive data

4. Handle errors gracefully - Show user-friendly messages

---

Next Steps

• Real-Seal - Sign documents with verified identity

• Ncrypt - Send messages with identity verification