Verifiable Credentials

@bsv/simple supports W3C Verifiable Credentials backed by BSV MasterCertificate cryptography. Credentials can be issued, verified, and revoked on-chain.

Overview

Component	Role
CredentialSchema	Defines the fields, validation, and computed values for a credential type
CredentialIssuer	Issues, verifies, and revokes credentials
MemoryRevocationStore	Stores revocation secrets in memory (browser/tests)
FileRevocationStore	Stores revocation secrets on disk (server only)
toVerifiableCredential()	Wraps a BSV certificate into W3C VC format
toVerifiablePresentation()	Wraps VCs into a W3C VP

Defining a Schema

import { CredentialSchema } from '@bsv/simple/browser'

const schema = new CredentialSchema({
  id: 'employee-badge',
  name: 'EmployeeBadge',
  description: 'Company employee verification',
  fields: [
    { key: 'name', label: 'Full Name', type: 'text', required: true },
    { key: 'email', label: 'Email', type: 'email', required: true },
    { key: 'department', label: 'Department', type: 'select', options: [
      { value: 'engineering', label: 'Engineering' },
      { value: 'design', label: 'Design' },
      { value: 'sales', label: 'Sales' }
    ]},
    { key: 'startDate', label: 'Start Date', type: 'date' }
  ],
  validate: (values) => {
    if (!values.email?.includes('@')) return 'Invalid email'
    return null
  },
  computedFields: (values) => ({
    ...values,
    issuedAt: new Date().toISOString(),
    verified: 'true'
  })
})

Schema Methods

// Validate field values
const error = schema.validate({ name: '', email: 'bad' })
// 'Full Name is required'

// Add computed fields
const all = schema.computeFields({ name: 'Alice', email: '[email protected]' })
// { name: 'Alice', email: '[email protected]', issuedAt: '2024-...', verified: 'true' }

// Get info
const info = schema.getInfo()
// { id: 'employee-badge', name: 'EmployeeBadge', certificateTypeBase64: '...', fieldCount: 4 }

Field Types

Type	Description
text	Free-form text
email	Email address
date	Date string
number	Numeric value
textarea	Multi-line text
checkbox	Boolean flag
select	Dropdown with predefined options

Creating an Issuer

import { CredentialIssuer, MemoryRevocationStore } from '@bsv/simple/browser'

const issuer = await CredentialIssuer.create({
  privateKey: issuerPrivateKeyHex,
  schemas: [schema.getConfig()],
  revocation: {
    enabled: true,
    wallet: walletInstance.getClient(),    // for creating revocation UTXOs
    store: new MemoryRevocationStore()
  }
})

console.log('Issuer DID:', issuer.getInfo().did)
console.log('Schemas:', issuer.getInfo().schemas)

Issuer Configuration

Parameter	Type	Required	Description
privateKey	string	Yes	Hex-encoded private key
schemas	CredentialSchemaConfig[]	No	Schema definitions
revocation.enabled	boolean	No	Enable on-chain revocation
revocation.wallet	WalletInterface	If enabled	Wallet for creating revocation UTXOs
revocation.store	RevocationStore	No	Custom store (default: MemoryRevocationStore)

Issuing a Credential

const vc = await issuer.issue(
  subjectIdentityKey,
  'employee-badge',
  { name: 'Alice Smith', email: '[email protected]', department: 'engineering' }
)

console.log('VC type:', vc.type)
// ['VerifiableCredential', 'EmployeeBadge']

console.log('Subject:', vc.credentialSubject.id)
// 'did:bsv:02abc...'

console.log('Issuer:', vc.issuer)
// 'did:bsv:03def...'

What Happens During Issuance

1. Fields are validated against the schema

2. Computed fields are merged in

3. If revocation is enabled:

   • A random 32-byte secret is generated

   • The SHA-256 hash of the secret creates a hash-lock script: OP_SHA256 <hash> OP_EQUAL

   • A 1-satoshi UTXO is created with this script

   • The secret is saved to the revocation store

4. A MasterCertificate is issued using the BSV SDK

5. The certificate is wrapped in a W3C Verifiable Credential envelope

Verifiable Credential Structure

{
  '@context': ['https://www.w3.org/2018/credentials/v1'],
  type: ['VerifiableCredential', 'EmployeeBadge'],
  issuer: 'did:bsv:03def...',
  issuanceDate: '2024-02-01T12:00:00.000Z',
  credentialSubject: {
    id: 'did:bsv:02abc...',
    name: 'Alice Smith',
    email: '[email protected]',
    department: 'engineering',
    issuedAt: '2024-02-01T12:00:00.000Z',
    verified: 'true'
  },
  credentialStatus: {
    id: 'bsv:txid123.0',
    type: 'BSVHashLockRevocation2024'
  },
  proof: {
    type: 'BSVMasterCertificateProof2024',
    created: '2024-02-01T12:00:00.000Z',
    proofPurpose: 'assertionMethod',
    verificationMethod: 'did:bsv:03def...#key-1',
    signatureValue: 'signature_hex'
  },
  _bsv: {
    certificate: { /* full CertificateData */ }
  }
}

Verifying a Credential

const result = await issuer.verify(vc)

console.log('Valid:', result.valid)
console.log('Revoked:', result.revoked)
console.log('Errors:', result.errors)
console.log('Issuer:', result.issuer)
console.log('Subject:', result.subject)

Verification checks:

1. W3C @context is present

2. VerifiableCredential type is present

3. Proof and signature are present

4. BSV certificate data is present

5. Revocation status (if applicable)

Revoking a Credential

const { txid } = await issuer.revoke(cert.serialNumber)
console.log('Revoked, txid:', txid)

Revocation spends the hash-lock UTXO by revealing the secret. Once spent, the credential is permanently revoked on-chain.

// Check revocation status
const isRevoked = await issuer.isRevoked(cert.serialNumber)
console.log('Is revoked:', isRevoked)

Wallet-Side: Acquiring Credentials

Wallets acquire credentials from remote issuers:

const vc = await wallet.acquireCredential({
  serverUrl: 'https://issuer.example.com',
  schemaId: 'employee-badge',
  fields: { name: 'Alice', email: '[email protected]' },
  replaceExisting: true
})

List Credentials

const vcs = await wallet.listCredentials({
  certifiers: [issuerPublicKey],
  types: [schema.getInfo().certificateTypeBase64]
})

for (const vc of vcs) {
  console.log(vc.credentialSubject)
}

Create a Presentation

Bundle credentials for sharing:

const presentation = wallet.createPresentation(vcs)

console.log('Holder:', presentation.holder)
console.log('Credentials:', presentation.verifiableCredential.length)

Server-Side Revocation Store

For production servers, use FileRevocationStore to persist secrets to disk:

const { FileRevocationStore } = await import('@bsv/simple/server')

const issuer = await CredentialIssuer.create({
  privateKey: key,
  schemas: [schema.getConfig()],
  revocation: {
    enabled: true,
    wallet: serverWallet.getClient(),
    store: new FileRevocationStore('.revocation-secrets.json')
  }
})

Important: Add .revocation-secrets.json to .gitignore. These secrets control credential revocation.

Complete Example

import { createWallet, CredentialSchema, CredentialIssuer, MemoryRevocationStore } from '@bsv/simple/browser'

const wallet = await createWallet()

// Define schema
const schema = new CredentialSchema({
  id: 'age-check',
  name: 'AgeVerification',
  fields: [
    { key: 'name', label: 'Name', type: 'text', required: true },
    { key: 'over18', label: 'Over 18', type: 'checkbox', required: true }
  ]
})

// Create issuer (in production, this runs on a server)
const issuer = await CredentialIssuer.create({
  privateKey: 'a1b2c3...',
  schemas: [schema.getConfig()],
  revocation: { enabled: false }
})

// Issue credential
const vc = await issuer.issue(
  wallet.getIdentityKey(),
  'age-check',
  { name: 'Alice', over18: 'true' }
)

// List from wallet
const vcs = await wallet.listCredentials({
  certifiers: [issuer.getInfo().publicKey],
  types: [schema.getInfo().certificateTypeBase64]
})

// Create presentation
const vp = wallet.createPresentation(vcs)
console.log('Presentation holder:', vp.holder)