Stellar Identity and Verifiable Credentials SDK

A comprehensive SDK for building decentralized identity and verifiable credentials solutions on the Stellar network using Soroban smart contracts.

🌟 Features

Core Identity Management

• DID Registry: W3C-compliant decentralized identifier management using did:stellar method
• Verifiable Credentials: Complete VC 2.0 implementation for issuing, verifying, and managing credentials
• Reputation System: On-chain reputation scoring based on transaction history and credential validity
• Zero-Knowledge Proofs: Privacy-preserving attestations and selective disclosure
• Compliance Integration: Built-in sanctions screening and risk assessment

Developer Tools

• Interactive CLI: Full-featured terminal tool for deploying and managing all contracts without writing code
• TypeScript SDK: Full-featured client library for web and Node.js environments
• React Components: Pre-built UI components for identity management
• Smart Contracts: Production-ready Soroban contracts
• Examples: Comprehensive use cases and implementation guides

🖥️ CLI Tool

The interactive CLI lets you deploy, manage, and interact with all contracts without writing any code.

Install

npm install
npm install --save-dev ts-node@10.9.2

Launch

# Interactive guided menu (recommended)
npm run cli

# Automated feature walkthrough
npm run cli:demo

# Show all commands and options
npm run cli:help

Opening screen

  ╔══════════════════════════════════════════════════════════╗
  ║   ⭐  Stellar Identity Credentials SDK                  ║
  ║       Interactive CLI — v1.0.0                          ║
  ╠══════════════════════════════════════════════════════════╣
  ║  Deploy contracts  ·  Manage DIDs  ·  Issue credentials ║
  ║  Reputation scoring  ·  ZK proofs  ·  Compliance        ║
  ╚══════════════════════════════════════════════════════════╝

Command categories

Category	What it does
Contract Deployment Wizard	Guided deploy of all 5 contracts to testnet / futurenet / mainnet
DID Management	Create, resolve, update, deactivate did:stellar identifiers
Credential Management	Issue KYC / education / employment credentials; verify; revoke
Reputation Management	View scores, update tx/credential reputation, query trust graphs
Zero-Knowledge Proofs	Generate age, income, range, and selective-disclosure proofs
Compliance & Screening	Screen addresses, generate reports, FATF Travel Rule payloads
Configuration	Switch networks, set RPC URL, update contract addresses
Keypair Manager	Generate, import, and persist signing keypairs

Quick start flow

Opening menu → Quick Start
  [1] Generate keypair   → saved to ~/.stellar-identity-cli.json
  [2] Create DID         → did:stellar:<G…address>
  [3] Initialize reputation → base score 100 (Seedling tier)

Contract deployment (guided wizard)

Contract Deployment Wizard → Deploy all contracts
  [1] Select network  (testnet / futurenet / mainnet)
  [2] Set RPC URL     (defaults auto-filled)
  [3] Choose keypair  (deployer)
  [4] Review plan     (5 contracts listed with fee estimates)
  [5] Confirm         → deploys + initializes all contracts
  [6] Export manifest → deployment-testnet-<ts>.json

See docs/cli-guide.md for the full command reference.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Frontend Layer                        │
├─────────────────────────────────────────────────────────────┤
│  React Components  │  TypeScript SDK  │  Examples      │
├─────────────────────────────────────────────────────────────┤
│                   Stellar Network                         │
├─────────────────────────────────────────────────────────────┤
│  DID Registry  │  Credentials  │  Reputation  │  ZK     │
│  Contract      │  Contract     │  Contract    │  Proof   │
│               │               │              │  Contract│
└─────────────────────────────────────────────────────────────┘

📋 Table of Contents

• Installation
• Quick Start
• CLI Tool
• Architecture
• Smart Contracts
• TypeScript SDK
• React Components
• Examples
• DID Method Specification
• API Reference
• Contributing
• License

🚀 Installation

Prerequisites

• Node.js 18+
• Rust 1.70+ (for contract development)
• Stellar CLI (soroban-cli)

Install the SDK

# Using npm
npm install @stellar-identity/sdk

# Using yarn
yarn add @stellar-identity/sdk

# Using pnpm
pnpm add @stellar-identity/sdk

The SDK ships with dual ESM + CommonJS support and full TypeScript type declarations:

// ESM (recommended)
import { StellarIdentitySDK, DEFAULT_CONFIGS } from '@stellar-identity/sdk';

// CommonJS
const { StellarIdentitySDK, DEFAULT_CONFIGS } = require('@stellar-identity/sdk');

Install React Components

# Additional dependencies for React components
npm install @stellar-identity/ui react react-dom

Clone the Repository

git clone https://github.com/Kevin737866/stellar-identity-credentials-sdk.git
cd stellar-identity-credentials-sdk

⚡ Quick Start

Basic Identity Setup

import { StellarIdentitySDK, DEFAULT_CONFIGS } from '@stellar-identity/sdk';
import { Keypair } from 'stellar-sdk';

// Initialize SDK
const sdk = new StellarIdentitySDK(DEFAULT_CONFIGS.testnet);

// Generate user keypair
const userKeypair = Keypair.random();

// Create DID
const did = await sdk.did.createDID(userKeypair, {
  verificationMethods: [{
    id: '#key-1',
    type: 'Ed25519VerificationKey2018',
    controller: userKeypair.publicKey(),
    publicKey: userKeypair.publicKey()
  }],
  services: [{
    id: '#hub',
    type: 'IdentityHub',
    endpoint: 'https://identity-hub.example.com'
  }]
});

console.log('DID created:', did);

Issue a Credential

// Issue KYC credential
const kycCredentialId = await sdk.credentials.issueKYCCredential(
  issuerKeypair,
  userKeypair.publicKey(),
  {
    firstName: 'John',
    lastName: 'Doe',
    dateOfBirth: '1990-01-15',
    nationality: 'US',
    documentType: 'Passport',
    documentNumber: '123456789'
  }
);

console.log('KYC Credential issued:', kycCredentialId);

Verify a Credential

// Verify credential
const verification = await sdk.credentials.verifyCredential(kycCredentialId);
console.log('Credential valid:', verification.valid);

Zero-Knowledge Age Proof

// Create age proof without revealing actual age
const ageProofId = await sdk.zkProofs.createAgeProof(
  'age_verification',
  ageCommitment,
  18, // Prove age >= 18
  proofBytes
);

// Verify age proof
const isAdult = await sdk.zkProofs.verifyAgeProof(ageProofId, 18);
console.log('User is adult:', isAdult);

🏗️ Smart Contracts

Contract Structure

The SDK includes five core Soroban contracts:

1. DID Registry (src/did_registry.rs)

   • DID creation, resolution, and management
   • Verification method management
   • Service endpoint management

2. Credential Issuer (src/credential_issuer.rs)

   • Verifiable credential issuance
   • Credential verification and revocation
   • Status tracking

3. Reputation Score (src/reputation_score.rs)

   • Reputation calculation and storage
   • Transaction and credential-based scoring
   • Historical tracking

4. ZK Attestation (src/zk_attestation.rs)

   • Zero-knowledge proof verification
   • Circuit management
   • Selective disclosure

5. Compliance Filter (src/compliance_filter.rs)

   • Sanctions screening
   • Risk assessment
   • Compliance monitoring

Building Contracts

# Build all contracts
cargo build --target wasm32-unknown-unknown --release

# Build specific contract
soroban contract build

# Deploy contract
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/did_registry.wasm \
  --source alice \
  --network testnet

Contract Interactions

use soroban_sdk::{contractimpl, Address, Env};

#[contractimpl]
impl DIDRegistry {
    pub fn create_did(
        env: Env,
        controller: Address,
        verification_methods: Vec<VerificationMethod>,
        services: Vec<Service>,
    ) -> Result<(), DIDRegistryError> {
        // Implementation
    }
}

💻 TypeScript SDK

Core Clients

The SDK provides specialized clients for each identity component:

// DID Management
const didClient = new DIDClient(config);
await didClient.createDID(keypair, options);
await didClient.resolveDID(did);

// Credential Management
const credentialClient = new CredentialClient(config);
await credentialClient.issueCredential(issuer, options);
await credentialClient.verifyCredential(credentialId);

// Reputation Management
const reputationClient = new ReputationClient(config);
await reputationClient.getReputationScore(address);
await reputationClient.updateTransactionReputation(address, success, amount);

// Zero-Knowledge Proofs
const zkClient = new ZKProofsClient(config);
await zkClient.createAgeProof(circuitId, commitment, minAge, proof);
await zkClient.verifyProof(proofId);

Configuration

const config: StellarIdentityConfig = {
  network: 'testnet',
  contracts: {
    didRegistry: 'CONTRACT_ADDRESS_HERE',
    credentialIssuer: 'CONTRACT_ADDRESS_HERE',
    reputationScore: 'CONTRACT_ADDRESS_HERE',
    zkAttestation: 'CONTRACT_ADDRESS_HERE',
    complianceFilter: 'CONTRACT_ADDRESS_HERE'
  },
  rpcUrl: 'https://horizon-testnet.stellar.org',
  horizonUrl: 'https://horizon-testnet.stellar.org'
};

🎨 React Components

Usage

import { DIDManager, CredentialWallet, ReputationBadge } from '@stellar-identity/ui';
import { useStellarIdentity } from '@stellar-identity/ui/hooks';

function IdentityApp() {
  const { sdk, address, keypair, connect } = useStellarIdentity({
    config: DEFAULT_CONFIGS.testnet,
    autoConnect: true
  });

  if (!sdk) return <div>Loading...</div>;

  return (
    <div className="identity-dashboard">
      <DIDManager sdk={sdk} address={address} keypair={keypair} />
      <CredentialWallet sdk={sdk} address={address} keypair={keypair} />
      <ReputationBadge sdk={sdk} address={address} keypair={keypair} />
    </div>
  );
}

Available Components

• DIDManager: Create and manage decentralized identifiers
• CredentialWallet: Store and display verifiable credentials
• ProofRequest: Request and generate zero-knowledge proofs
• ReputationBadge: Display trust scores and verification status
• ComplianceCheck: Real-time sanctions and risk screening

📚 Examples

Running Examples

# Install dependencies
npm install

# Run KYC flow example
npm run example:kyc

# Run reputation builder example
npm run example:reputation

# Run privacy-preserving age check
npm run example:age-check

# Run business verification
npm run example:business

Available Examples

1. KYC Flow (examples/kyc-flow.ts)

   • Complete KYC credential issuance and verification
   • DID creation and management
   • Reputation building
   • Zero-knowledge age verification

2. Reputation Builder (examples/reputation-builder.ts)

   • Build reputation through transaction history
   • Credential-based reputation enhancement
   • Reputation analysis and optimization

3. Privacy-Preserving Age Check (examples/privacy-preserving-age-check.ts)

   • Zero-knowledge age proofs
   • Selective disclosure
   • Privacy compliance

4. Business Verification (examples/business-verification.ts)

   • Corporate credential issuance
   • Multi-jurisdictional verification
   • Compliance monitoring

🆔 DID Method Specification

DID Method: did:stellar

The did:stellar method uses Stellar account addresses as DID identifiers.

DID Format

did:stellar:<stellar_account_address>

Example:

did:stellar:GD5DJQDKEJXGYQTELBQJXG2QFQHZXJN5T2YGF4Y4A3K5Z2Q2B4F5

DID Document Structure

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:stellar:GD5DJQDKEJXGYQTELBQJXG2QFQHZXJN5T2YGF4Y4A3K5Z2Q2B4F5",
  "controller": "GD5DJQDKEJXGYQTELBQJXG2QFQHZXJN5T2YGF4Y4A3K5Z2Q2B4F5",
  "verificationMethod": [{
    "id": "#key-1",
    "type": "Ed25519VerificationKey2018",
    "controller": "did:stellar:GD5DJQDKEJXGYQTELBQJXG2QFQHZXJN5T2YGF4Y4A3K5Z2Q2B4F5",
    "publicKey": "GD5DJQDKEJXGYQTELBQJXG2QFQHZXJN5T2YGF4Y4A3K5Z2Q2B4F5"
  }],
  "authentication": ["#key-1"],
  "service": [{
    "id": "#hub",
    "type": "IdentityHub",
    "endpoint": "https://identity-hub.example.com"
  }],
  "created": 1640995200000,
  "updated": 1640995200000
}

Resolution

DID resolution can be performed through:

1. On-chain contract calls
2. Stellar TOML configuration
3. HTTP endpoint (if configured)

📖 API Reference

DID Client

class DIDClient {
  async createDID(keypair: Keypair, options: CreateDIDOptions): Promise<string>
  async resolveDID(did: string): Promise<DIDResolutionResult>
  async updateDID(keypair: Keypair, options: UpdateDIDOptions): Promise<void>
  async deactivateDID(keypair: Keypair): Promise<void>
  async addAuthentication(keypair: Keypair, method: string): Promise<void>
  async removeAuthentication(keypair: Keypair, method: string): Promise<void>
}

Credential Client

class CredentialClient {
  async issueCredential(issuer: Keypair, options: IssueCredentialOptions): Promise<string>
  async verifyCredential(credentialId: string): Promise<CredentialVerificationResult>
  async revokeCredential(issuer: Keypair, credentialId: string, reason?: string): Promise<void>
  async getCredential(credentialId: string): Promise<VerifiableCredential>
  async createPresentation(credentials: VerifiableCredential[], holder: Keypair): Promise<any>
  async verifyPresentation(presentation: any): Promise<boolean>
}

Reputation Client

class ReputationClient {
  async getReputationScore(address: string): Promise<number>
  async getReputationAnalysis(address: string): Promise<ReputationScoreResult>
  async updateTransactionReputation(address: string, success: boolean, amount: number): Promise<number>
  async updateCredentialReputation(address: string, valid: boolean, type: string): Promise<number>
  async getReputationTier(score: number): ReputationTier
}

ZK Proofs Client

class ZKProofsClient {
  async createAgeProof(circuitId: string, commitment: string, minAge: number, proof: string): Promise<string>
  async verifyAgeProof(proofId: string, minAge: number): Promise<boolean>
  async createIncomeProof(circuitId: string, commitment: string, minIncome: number, proof: string): Promise<string>
  async verifyProof(proofId: string): Promise<ZKVerificationResult>
  async generateCommitment(data: string, salt?: string): string
}

🔧 Development

Setup Development Environment

# Clone repository
git clone https://github.com/stellar-identity/sdk.git
cd stellar-identity-credentials-sdk

# Install Rust dependencies
cargo build

# Install Node.js dependencies
npm install

# Build contracts
npm run build:contracts

# Build SDK
npm run build:sdk

# Build UI components
npm run build:ui

Testing

# Run contract tests
cargo test

# Run SDK tests
npm test

# Run integration tests
npm run test:integration

# Run example tests
npm run test:examples

Code Quality

# Format Rust code
cargo fmt

# Lint Rust code
cargo clippy

# Format TypeScript code
npm run format

# Lint TypeScript code
npm run lint

# Type checking
npm run type-check

🌐 Network Configuration

Supported Networks

• Mainnet: Production Stellar network
• Testnet: Public test network
• Futurenet: Experimental test network

Contract Addresses

Contract addresses vary by network. Update your configuration accordingly:

const MAINNET_CONFIG = {
  network: 'mainnet',
  contracts: {
    didRegistry: 'MAINNET_DID_REGISTRY_ADDRESS',
    credentialIssuer: 'MAINNET_CREDENTIAL_ISSUER_ADDRESS',
    reputationScore: 'MAINNET_REPUTATION_SCORE_ADDRESS',
    zkAttestation: 'MAINNET_ZK_ATTESTATION_ADDRESS',
    complianceFilter: 'MAINNET_COMPLIANCE_FILTER_ADDRESS'
  }
};

🔒 Security Considerations

Key Management

• Store private keys securely
• Use hardware wallets for production
• Implement proper key rotation

Contract Security

• All contracts include access controls
• Input validation on all functions
• Reentrancy protection where applicable

Privacy

• Zero-knowledge proofs for sensitive data
• Selective disclosure mechanisms
• GDPR compliance features

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Code of Conduct

Please follow our Code of Conduct.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🆘 Support

• Documentation: docs.stellar-identity.org
• Discord: Stellar Identity Discord
• Issues: GitHub Issues
• Email: support@stellar-identity.org

🗺️ Roadmap

v0.2.0 (Q2 2024)

• Enhanced ZK circuit library
• Mobile SDK support
• Advanced compliance features
• Multi-sig DID support

v0.3.0 (Q3 2024)

• Cross-chain identity bridging
• Decentralized reputation oracle
• Enterprise compliance tools
• Advanced analytics dashboard

v1.0.0 (Q4 2024)

• Production audit completion
• Mainnet deployment
• Full API documentation
• Developer certification program

📊 Metrics

• Contracts Deployed: 5 core contracts
• SDK Functions: 50+ API methods
• React Components: 6 major components
• Examples: 4 comprehensive use cases
• Test Coverage: 95%+

🙏 Acknowledgments

• Stellar Development Foundation for the Soroban platform
• W3C DID and VC working groups
• Zero-knowledge proof research community
• Our amazing contributors and users

---

Built with ❤️ for the Stellar ecosystem