Uçtan Uca Kimlik Bilgisi Akışı

Bu kılavuz, Solidus’ta bir Doğrulanabilir Kimlik Bilgisinin tam yaşam döngüsünü baştan sona anlatır: bir kimlik oluşturmaktan, KYC doğrulaması ve kimlik bilgisi düzenlemesinden, sunuma, doğrulamaya ve iptale kadar. Her adım, kod ve zincir üzerinde mi yoksa zincir dışında mı gerçekleştiğinin bir açıklamasını içerir.

Genel Bakış


Create DID ──> Complete KYC ──> Receive Credential ──> Store
                                                         │
                            Revoke <── Verify <── Present

1. Bir DID Oluşturun

Her kimlik bilgisi sahibinin bir Merkeziyetsiz Kimlik Tanımlayıcısına ihtiyacı vardır. Bir DID oluşturmak, bir Ed25519 anahtar çifti üretir ve açık anahtarı Solidus blok zincirinde kaydeder.


import * as ed25519 from '@noble/ed25519'
import { createSdk } from '@solidus-network/sdk'
 
// Generate a key pair
const privateKey = ed25519.utils.randomPrivateKey()
const publicKey = await ed25519.getPublicKeyAsync(privateKey)
const privateKeyHex = Buffer.from(privateKey).toString('hex')
const publicKeyHex = Buffer.from(publicKey).toString('hex')
 
// Create the SDK instance
const sdk = createSdk({
  mode: 'testnet',
  rpcUrl: 'https://rpc.solidus.network',
  signerPrivateKey: privateKeyHex,
})
 
// Register the DID on-chain (for the signer's own public key)
const did = await sdk.did.create(publicKeyHex)
 
console.log('DID:', did.id)
// => did:solidus:testnet:7Hk3mRtQZv...

Zincir üzerinde: Bir DID Belgesi, Solidus DID Kayıt Defterine yazılır. Belge, açık anahtarı ve doğrulama yöntemlerini içerir. DID adresi, açık anahtarın bir BLAKE3 hash’inden türetilir.

Zincir dışında: Özel anahtar kullanıcının cihazında kalır. Hiçbir zaman ağa gönderilmez.

2. KYC Doğrulamasını Tamamlayın

Kullanıcı, Solidus Verify hizmeti aracılığıyla kimlik doğrulamasını tamamlar. Bu, programatik olarak veya kullanıcıyı barındırılan doğrulama sayfasına yönlendirerek başlatılabilir.


// Create a verification session via the Verify API
const session = await fetch('https://verify.solidus.network/v1/verifications', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
  },
  body: JSON.stringify({
    subjectDid: did.id,
    level: 1,
    redirectUrl: 'https://myapp.com/verification-complete',
  }),
})
 
const { sessionToken, hostedUrl } = await session.json()
 
// Redirect the user to the verification page
// hostedUrl => https://verify.solidus.network/v/s/<sessionToken>

Oturum oluşturmada bir webhook alanı yoktur — webhook’lar ayrı bir kaynaktır. POST /webhooks üzerinden bir uç noktayı bir kez kaydedin ve bu, gelecekteki tüm oturumlar için olayları alır; bkz. Webhook’lar kılavuzu.

Zincir üzerinde: Henüz hiçbir şey olmuyor. KYC doğrulaması zincir dışı bir süreçtir.

Zincir dışında: Kullanıcı kimlik belgelerini (pasaport, kimlik kartı veya ehliyet) yükler, bir canlılık kontrolünü tamamlar ve Verify hizmeti OCR, yüz eşleştirme ve belge özgünlük kontrolleri çalıştırır.

3. Kimlik Bilgisini Alın

Başarılı doğrulamadan sonra, Verify hizmeti kullanıcının DID’ine bir Doğrulanabilir Kimlik Bilgisi düzenler. Kimlik bilgisi, Solidus Verify düzenleyici DID’i tarafından imzalanır ve hash’i zincir üzerinde sabitlenir.


// After KYC passes, query the issued credential
const verification = await fetch(
  \`https://verify.solidus.network/v1/verifications/${sessionId}\`,
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  }
)
 
const result = await verification.json()
 
// The credential object
const credential = result.credential
console.log('Credential ID:', credential.id)
console.log('Type:', credential.type)
// => ["VerifiableCredential", "KYCCredential"]
console.log('Issuer:', credential.issuer)
// => did:solidus:testnet:verify-service
console.log('Claims:', credential.credentialSubject)
// => { id: "did:solidus:testnet:7Hk3...", level: 1, country: "US" }

Kimlik bilgisi, W3C Doğrulanabilir Kimlik Bilgileri Veri Modelini izler. Yapısı şöyle görünür:


{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "id": "urn:solidus:credential:credential-id-here",
  "type": ["VerifiableCredential", "KYCCredential"],
  "issuer": "did:solidus:testnet:verify-service",
  "validFrom": "2026-05-07T12:00:00Z",
  "validUntil": "2027-05-07T12:00:00Z",
  "credentialSubject": {
    "id": "did:solidus:testnet:7Hk3mRtQZv...",
    "level": 1,
    "country": "US",
    "verifiedAt": "2026-05-07T12:00:00Z"
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2026-05-07T12:00:00Z",
    "verificationMethod": "did:solidus:testnet:verify-service#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3FXQje2Y..."
  }
}

Zincir üzerinde: Kimlik bilgisinin bir BLAKE3 hash’i, yerel bir CredentialIssue işlemi aracılığıyla yazılır — Solidus’ta bugün bir akıllı sözleşme sanal makinesi yoktur (bkz. Mimari). Bu, herhangi bir kişisel veriyi zincir üzerinde saklamadan kimlik bilgisinin belirli bir zamanda düzenlendiğini kanıtlayan değişmez bir sabitleme oluşturur.

Zincir dışında: Tam kimlik bilgisi (kişisel veriyle birlikte) yalnızca kullanıcıya döndürülür ve cüzdanında saklanır.

4. Kimlik Bilgisini Saklayın

Kullanıcı, kimlik bilgisini Solidus Identity cüzdanında veya uyumlu herhangi bir depoda saklar.


// Option A: Store in the Solidus Identity app
// The credential is automatically saved when the user completes
// verification through the hosted flow.
 
// Option B: Store locally in your application
import fs from 'fs'
 
// Save the credential to a secure local store
fs.writeFileSync(
  './credentials/kyc-credential.json',
  JSON.stringify(credential, null, 2)
)
 
// Option C: Store in an encrypted database
await db.credentials.create({
  did: did.id,
  type: 'KYCCredential',
  credential: JSON.stringify(credential),
  issuedAt: new Date(credential.validFrom),
  expiresAt: credential.validUntil ? new Date(credential.validUntil) : null,
})

Zincir üzerinde: Hiçbir şey. Kimlik bilgisi saklama tamamen zincir dışıdır.

Zincir dışında: Kimlik bilgisi, sahibi tarafından saklanır. Yalnızca sahip, onu ne zaman ve nerede sunacağına karar verir.

5. Kimlik Bilgisini Sunun

Bir güvenen taraf (bir DeFi protokolü veya bir borsa gibi) kimlik kanıtı istediğinde, kullanıcı bir Doğrulanabilir Sunum oluşturur. Bu, bir veya daha fazla kimlik bilgisini, sunanın DID’i kontrol ettiğine dair bir kanıtla bir araya getirir.

@solidus-network/auth, düz fonksiyonlar dışa aktarır (createChallenge, verifyPresentation) — bir istemci/doğrulayıcı sınıfı yoktur ve sizin için bir sunum oluşturmaz veya imzalamaz. Güvenen taraf bir meydan okuma çıkarır; uygulama, sahibinin özel anahtarını kullanarak VerifiablePresentation nesnesini kendisi oluşturur ve imzalar (aşağıdaki şekle göre).


import { createChallenge } from '@solidus-network/auth'
 
// The relying party creates a challenge for the user's DID
const challengeResponse = await fetch('https://relying-party.com/api/auth/challenge', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ did: did.id }),
})
const challenge = await challengeResponse.json()
// challenge = { id, did, nonce, issuedAt, expiresAt }
 
// The user builds and signs a presentation over challenge.nonce with their
// private key, then sends it to the relying party for verification
const verifyResponse = await fetch('https://relying-party.com/api/auth/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ challengeId: challenge.id, presentation }),
})

Sunum yapısı şöyle görünür:


{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiablePresentation"],
  "holder": "did:solidus:testnet:7Hk3mRtQZv...",
  "verifiableCredential": [
    { "...the full KYC credential..." }
  ],
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2026-05-07T14:30:00Z",
    "challenge": "<the challenge nonce>",
    "verificationMethod": "did:solidus:testnet:7Hk3...#key-1",
    "proofPurpose": "authentication",
    "jws": "<detached JWS signature>"
  }
}

Tam JWS imzalama biçimi için @solidus-network/auth referansına bakın.

Zincir üzerinde: Sunum sırasında hiçbir şey. Güvenen taraf, bir sonraki adımda zincir üzerinde doğrulayacaktır.

Zincir dışında: Kullanıcı, sunumu özel anahtarıyla imzalar ve kimlik bilgilerini belirli meydan okuma ve alan adına bağlar. Bu, yeniden oynatma saldırılarını önler.

6. Kimlik Bilgisini Doğrulayın

Güvenen taraf sunumu doğrular (kullanıcının DID’i kontrol ettiğini kanıtlar) ve içinde referans verilen her kimlik bilgisini ayrıca doğrular. Kimlik bilgisi doğrulaması üç şeyi kontrol eder: imza (gönderim sırasında zincir tarafından doğrulanır), son kullanma (Solidus kimlik bilgileri zincir üzerinde sona ermez) ve iptal durumu.


import { createSdk } from '@solidus-network/sdk'
import { verifyPresentation } from '@solidus-network/auth'
 
const sdk = createSdk({
  mode: 'testnet',
  rpcUrl: 'https://rpc.solidus.network',
})
 
// Verify the presentation (proves the user controls the DID) — resolve the
// holder's DID document to get the public key that signed it
const presentationResult = await verifyPresentation(
  challenge,
  presentation,
  async (verificationMethodId) => {
    const doc = await sdk.did.resolve(presentation.holder)
    // ...decode the matching verificationMethod's publicKeyMultibase to raw bytes
    return publicKeyBytes
  },
)
console.log('Presentation valid:', presentationResult.valid)
 
// Verify each credential referenced in the presentation, by ID
for (const cred of presentation.verifiableCredential ?? []) {
  const result = await sdk.credentials.verify(cred.id)
  console.log(\`Credential ${cred.id}:\`)
  console.log('  Valid:', result.valid)
  console.log('  Checks:', result.checks)
  // => { signature: true, expiry: true, revocation: true }
}

Zincir üzerinde: Doğrulayan, sahibinin açık anahtarını almak için DID Kayıt Defterini okur, ardından mevcut olduğunu ve iptal edilmediğini onaylamak için kimlik bilgisi kaydını kimliğine göre okur. Bunlar salt okunur sorgulardır.

Zincir dışında: Sunum üzerindeki imza ve meydan okuma/nonce kontrolleri bellekte gerçekleşir. Doğrulayan hiçbir zaman doğrudan düzenleyiciyle iletişime geçmez.

7. Bir Kimlik Bilgisini İptal Edin

Bir kimlik bilgisinin geçersiz kılınması gerekirse (örneğin, bir kullanıcının kimlik bilgisi değiştiğinde veya dolandırıcılık tespit edildiğinde), düzenleyici onu zincir üzerinde iptal edebilir. revoke(), kimlik bilgisi kimliğini ve düzenleyicinin özel anahtarını alır ve onaylandıktan sonra herhangi bir dönüş değeri olmadan sonuçlanır.


// Only the original issuer can revoke a credential
const issuerSdk = createSdk({
  mode: 'testnet',
  rpcUrl: 'https://rpc.solidus.network',
  signerPrivateKey: process.env.ISSUER_PRIVATE_KEY!,
})
 
// Revoke the credential
await issuerSdk.credentials.revoke(credential.id, process.env.ISSUER_PRIVATE_KEY!)
 
// After revocation, verification will fail the revocation check
const result = await sdk.credentials.verify(credential.id)
console.log('Valid:', result.valid) // => false
console.log('Checks:', result.checks)
// { signature: true, expiry: true, revocation: false }

Zincir üzerinde: Bir iptal girdisi, yerel bir CredentialRevoke işlemi aracılığıyla yazılır. Kimlik bilgisi iptal edilmiş olarak işaretlenir ve gelecekteki doğrulama sorguları bu durumu görecektir.

Zincir dışında: Kimlik bilgisi verisinin kendisi değiştirilmez. Sahip hâlâ kimlik bilgisine sahiptir, ancak zincir üzerinde kontrol eden herhangi bir doğrulayan onun iptal edildiğini görecektir.

Özet

Step	On-chain	Off-chain
DID oluşturma	DID Belgesi kayıt defterine yazılır	Özel anahtar yerel olarak saklanır
KYC’yi tamamlama	Hiçbir şey	Belge yükleme, OCR, canlılık kontrolü
Kimlik bilgisini alma	Kimlik bilgisi hash’i sabitlenir	Tam kimlik bilgisi sahibine döndürülür
Kimlik bilgisini saklama	Hiçbir şey	Sahip cüzdana/veritabanına kaydeder
Kimlik bilgisini sunma	Hiçbir şey	Sahip bir Doğrulanabilir Sunum imzalar
Kimlik bilgisini doğrulama	DID Kayıt Defterini + Kimlik Bilgisi Deposunu okuma	İmza ve son kullanma kontrolleri
Kimlik bilgisini iptal etme	İptal girdisi yazılır	Hiçbir şey

Sonraki Adımlar

KYC Entegrasyonu — doğrulama akışını uygulamanıza gömün
Webhook’lar — doğrulama tamamlandığında bildirimler alın
Solidus Nasıl Çalışır — protokol mimarisi ve konsensüs