W3MSG SDK - Complete VC Verification System

Overview

The W3MSG SDK includes a comprehensive Verifiable Credential (VC) verification system that provides flexible, configurable verification with trust management, verification hooks, and relay service integration. This system addresses both high-security requirements and adoption-friendly messaging scenarios.

Design Philosophy

Original Challenge: Automatic VC verification could block legitimate messages, creating adoption barriers.

Solution: Complete verification infrastructure with configurable modes, trust management, and event-driven UI updates that preserve security benefits while providing flexibility for different use cases.

Core Components

1. Verification Modes

vcConfig: {
  verificationMode: 'strict' | 'lenient' | 'off'
}

strict Mode

• Behavior: Blocks messages with missing or invalid VCs
• Use Cases: High-stakes scenarios (DAO governance, DeFi alerts from official platforms)
• Result: Messages without valid VCs are rejected entirely

lenient Mode (Default)

• Behavior: Warns about missing/invalid VCs but allows messages through
• Use Cases: General messaging with optional trust indicators
• Result: Messages show warnings like "This alert is from an unverified sender—proceed with caution"

off Mode

• Behavior: Disables VC verification completely
• Use Cases: Development, testing, or scenarios where VCs aren't needed
• Result: All messages are allowed without VC checks

2. Trust Management System

vcConfig: {
  exemptSenders: ['0x123...', '0xabc...'],  // Addresses that bypass VC checks
  trustedIssuers: ['did:polygon:mumbai:0x...'], // Trusted VC issuers
  trustEvaluation: {
    enableReputationScoring: true,
    progressiveTrustThreshold: 0.7,
    staticListExpiry: 86400 // 24 hours
  }
}

3. Verification Hooks

// Pre-send hooks for custom business logic
sdk.addPreSendHook('custom-verification', async (context) => {
  if (context.message.content.includes('sensitive')) {
    return { action: 'block', reason: 'Sensitive content detected' };
  }
  return { action: 'allow' };
});

// Post-receive hooks for additional processing
sdk.addPostReceiveHook('audit-logging', async (context) => {
  console.log('Message received:', context.message.id);
  return { action: 'allow' };
});

4. Event-Driven Verification UI

// Listen to verification events for real-time UI updates
sdk.on('verification:started', (data) => {
  console.log('Verification started for:', data.senderAddress);
});

sdk.on('verification:passed', (data) => {
  console.log('Verification passed:', data.credentials);
});

sdk.on('verification:failed', (data) => {
  console.log('Verification failed:', data.reason);
});

sdk.on('verification:warning', (data) => {
  console.log('Verification warning:', data.warnings);
});

5. Relay Service Integration

// Configure external verification endpoint
await sdk.configureRelayService({
  endpoint: 'https://relay.w3msg.app/api/verify',
  apiKey: 'your-api-key',
  batchSize: 10, // Batch verification for performance
  cacheTTL: 300 // 5 minutes cache
});

// Batch verify multiple credentials
const results = await sdk.batchVerifyCredentials([
  { type: 'dao-member', issuer: 'did:polygonid:...' },
  { type: 'token-holder', issuer: 'did:polygonid:...' }
]);

Example Configurations

High-Security DAO Notifications

const sdk = new W3MSGSDK({
  vcConfig: {
    verificationMode: 'strict',
    defaultRequirements: ['governance_token_holder'],
    trustedIssuers: ['did:polygon:mainnet:0xdao123'],
    trustEvaluation: {
      enableReputationScoring: true,
      progressiveTrustThreshold: 0.9
    }
  }
});

// Add custom verification hook
sdk.addPreSendHook('dao-governance', async (context) => {
  if (context.message.content.includes('proposal')) {
    // Require additional verification for governance proposals
    const hasGovernanceVC = await sdk.verifyCredentialType('governance_token_holder');
    if (!hasGovernanceVC) {
      return { action: 'block', reason: 'Governance proposal requires governance token holder VC' };
    }
  }
  return { action: 'allow' };
});

General DeFi Platform

const sdk = new W3MSGSDK({
  vcConfig: {
    verificationMode: 'lenient',
    fallbackBehavior: 'warn',
    exemptSenders: ['0xUniswapRouter', '0xCompoundProtocol'],
    trustEvaluation: {
      enableReputationScoring: true,
      progressiveTrustThreshold: 0.7
    }
  }
});

// Listen to verification events for UI updates
sdk.on('verification:warning', (data) => {
  showWarningBanner(`Unverified sender: ${data.senderAddress}`);
});

Development/Testing

const sdk = new W3MSGSDK({
  vcConfig: {
    verificationMode: 'off'
  }
});

// Disable all verification for testing
sdk.disableVerification();

Verification Flow

flowchart TD
    A[Message Received] --> B{VC Enabled?}
    B -->|No| H[Allow Message]
    B -->|Yes| C{Sender Exempt?}
    C -->|Yes| H
    C -->|No| D{Mode?}
    D -->|off| H
    D -->|strict| E{Valid VC?}
    D -->|lenient| F{Valid VC?}
    E -->|Yes| H
    E -->|No| I[Block Message]
    F -->|Yes| H
    F -->|No| G{Trust Evaluation}
    G -->|High Trust| H
    G -->|Low Trust| J[Show with Warning]
    G -->|No Trust| K[Tag as Unverified]
    
    L[Pre-Send Hooks] --> M{Hook Result}
    M -->|allow| N[Send Message]
    M -->|block| O[Block Message]
    M -->|quarantine| P[Quarantine Message]
    
    Q[Post-Receive Hooks] --> R{Hook Result}
    R -->|allow| S[Display Message]
    R -->|block| T[Hide Message]
    R -->|quarantine| U[Quarantine Message]

API Reference

Core Verification Methods

// Configure verification settings
await sdk.configureVCVerification(config: VCVerificationConfig);

// Verify a single message
const result = await sdk.verifyMessage(message: W3MSGMessage);

// Batch verify multiple credentials
const results = await sdk.batchVerifyCredentials(credentials: CredentialInput[]);

// Add verification hooks
sdk.addPreSendHook(name: string, hook: PreSendHook);
sdk.addPostReceiveHook(name: string, hook: PostReceiveHook);

// Remove hooks
sdk.removePreSendHook(name: string);
sdk.removePostReceiveHook(name: string);

Trust Management

// Configure trust evaluation
await sdk.configureTrustManagement(config: TrustManagementConfig);

// Evaluate trust for a sender
const trustResult = await sdk.evaluateTrust(senderAddress: string);

// Add/remove exempt senders
sdk.addExemptSender(address: string, reason?: string);
sdk.removeExemptSender(address: string);

// Add/remove trusted issuers
sdk.addTrustedIssuer(issuer: string, credentialTypes?: string[]);
sdk.removeTrustedIssuer(issuer: string);

Event System

// Verification events
sdk.on('verification:started', (data: VCVerificationEventData) => {});
sdk.on('verification:passed', (data: VCVerificationEventData) => {});
sdk.on('verification:failed', (data: VCVerificationEventData) => {});
sdk.on('verification:warning', (data: VCVerificationEventData) => {});

// Trust evaluation events
sdk.on('trust:evaluated', (data: TrustEventData) => {});
sdk.on('trust:exempted', (data: TrustEventData) => {});

// Hook events
sdk.on('hook:pre-send', (data: HookEventData) => {});
sdk.on('hook:post-receive', (data: HookEventData) => {});

Relay Service Integration

// Configure relay service
await sdk.configureRelayService(config: RelayServiceConfig);

// Verify via relay service
const result = await sdk.verifyViaRelay(credentials: CredentialInput[]);

// Get relay service status
const status = await sdk.getRelayServiceStatus();

Use Case Examples

DeFi Liquidation Alerts

Scenario: Uniswap wants to send liquidation warnings to users.

Configuration:

const sdk = new W3MSGSDK({
  vcConfig: {
    verificationMode: 'lenient',
    fallbackBehavior: 'warn',
    exemptSenders: ['0xUniswapRouter'],  // Official Uniswap contract
    trustedIssuers: ['did:polygon:mainnet:0xuniswap'],
    trustEvaluation: {
      enableReputationScoring: true,
      progressiveTrustThreshold: 0.7
    }
  }
});

// Add custom hook for liquidation alerts
sdk.addPreSendHook('liquidation-alert', async (context) => {
  if (context.message.content.includes('liquidation')) {
    // Require additional verification for liquidation alerts
    const hasDeFiVC = await sdk.verifyCredentialType('defi_user');
    if (!hasDeFiVC) {
      return { action: 'warn', reason: 'Liquidation alert from unverified sender' };
    }
  }
  return { action: 'allow' };
});

// Listen to verification events
sdk.on('verification:warning', (data) => {
  showWarningBanner(`⚠️ Unverified liquidation alert from ${data.senderAddress}`);
});

Exclusive DAO Communications

Scenario: DAO wants only verified token holders to receive governance updates.

Configuration:

const sdk = new W3MSGSDK({
  vcConfig: {
    verificationMode: 'strict',
    defaultRequirements: ['governance_token_holder'],
    trustedIssuers: ['did:polygon:mainnet:0xdao'],
    trustEvaluation: {
      enableReputationScoring: true,
      progressiveTrustThreshold: 0.9
    }
  }
});

// Add governance-specific hook
sdk.addPreSendHook('governance-verification', async (context) => {
  if (context.message.content.includes('proposal') || context.message.content.includes('vote')) {
    const hasGovernanceVC = await sdk.verifyCredentialType('governance_token_holder');
    if (!hasGovernanceVC) {
      return { action: 'block', reason: 'Governance messages require governance token holder VC' };
    }
  }
  return { action: 'allow' };
});

// Listen to verification events for UI updates
sdk.on('verification:passed', (data) => {
  showSuccessIndicator('✅ Verified governance message');
});

sdk.on('verification:failed', (data) => {
  showErrorIndicator('❌ Unverified governance message blocked');
});

Testing in Browser Demo

The enhanced browser demo includes comprehensive VC verification testing:

1. Configuration Panel:

   • Verification mode selection (strict/lenient/off)
   • Trust management settings
   • Exempt senders and trusted issuers
   • Relay service configuration

2. Test Scenarios:

   • Valid VC messages with different credential types
   • Invalid VC messages with various failure reasons
   • Missing VC messages with fallback behaviors
   • Trusted sender messages with exemption logic
   • Hook execution with custom business logic

3. Real-time UI Updates:

   • Event-driven verification status indicators
   • Trust evaluation results with confidence scores
   • Hook execution results with action details
   • Relay service integration status

Migration Notes

Backward Compatibility: Existing code continues to work with default lenient mode.

Recommended Migration Path:

1. Start with lenient mode for existing applications
2. Gradually identify high-value message types that need strict mode
3. Build trust lists of verified senders/issuers
4. Implement custom hooks for business-specific verification logic
5. Add event listeners for real-time UI updates
6. Configure relay service for external verification capabilities
7. Provide user controls for verification preferences

Performance Considerations

• Verification Time: ~50-200ms per credential verification
• Trust Evaluation: ~10-50ms per trust assessment
• Relay Service: ~100-300ms API response time
• Caching: Intelligent caching with Cloudflare KV for performance
• Batch Processing: Support for batch verification of multiple credentials

Future Enhancements

• User-configurable modes: Let users choose their own verification level
• Advanced reputation scoring: Combine VC verification with sender reputation
• Dynamic trust lists: Automatically update trusted senders based on community consensus
• VC type-specific rules: Different verification modes for different credential types
• Machine learning integration: AI-powered trust evaluation and fraud detection
• Cross-chain trust: Trust evaluation across multiple blockchain networks

---

This comprehensive system preserves W3MSG's key differentiator (VC-enhanced trust) while providing the flexibility needed for broad adoption. The combination of configurable modes, trust management, verification hooks, and relay service integration creates a powerful foundation for secure, scalable Web3 messaging.