Pocketbook Docs

Appearance

Certificate Management Guide

Overview ​

The Pocketbook certificate management system provides a comprehensive platform for creating, managing, and verifying digital certificates backed by blockchain technology. This guide covers all aspects of certificate management including creation, deployment, gifting, warranty integration, and revocation.

Key Features ​

  • Blockchain-backed ownership: Certificates are minted as NFTs on Polygon blockchain
  • QR code verification: Public proof of ownership accessible to anyone
  • Warranty integration: Product warranties with auto-calculation and status tracking
  • Certificate gifting: Secure transfer system with encrypted notifications
  • Burn functionality: Authorized revocation and permanent destruction
  • Hybrid architecture: Fast database queries with blockchain verification
  • Public transparency: Verification pages accessible without authentication

System Architecture ​

Production Architecture ​

The certificate system operates across multiple layers:

Frontend Layer

  • Location: www.pocketbook.studio (Vercel-hosted static site)
  • Components: React-based certificate viewer, creation forms, public verification pages
  • Routing: Client-side routing with certificate-specific routes

API Server Layer

  • Location: api.pocketbook.studio (separate server deployment)
  • Endpoints: RESTful API for certificate operations
  • Authentication: JWT tokens and API key support

Blockchain Layer

  • Network: Polygon (for production)
  • Smart Contract: NFT contract with burn, transfer, and admin functions
  • Verification: Immutable ownership records

Database Layer

  • Storage: MongoDB for certificate metadata and rich information
  • Purpose: Fast queries, analytics, and enhanced user experience
  • Integrity: Includes transactionHash, blockNumber, and tokenId for verification

Data Flow ​

User Action → Frontend → API Server → Database + Blockchain → Response
                                    ↓
                            Certificate Record Created
                                    ↓
                        QR Code Generated → Public Verification

Hybrid Approach Benefits ​

Performance: Database queries (sub-100ms) vs blockchain queries (3-5 seconds) Scalability: Handle 100K+ certificates efficiently Rich Metadata: Store detailed information not possible on-chain Reliability: Defense in depth - if blockchain RPC fails, certificates still load Analytics: Track certificate views, geographic distribution, and usage patterns

Certificate Creation and Deployment ​

Creating Standard Certificates ​

Via SingleMint Component:

  1. Navigate to enterprise dashboard
  2. Click "Create Certificate"
  3. Fill in certificate details:
    • Name and description
    • Category selection
    • Upload images
  4. Select template (optional) for custom fields
  5. Click "Mint" to create on blockchain

Via SingleMintVoucher Component:

  1. Navigate to enterprise dashboard
  2. Click "Create Voucher"
  3. Configure voucher parameters
  4. Set redemption conditions
  5. Create voucher for future minting

Deployment to Production ​

When deploying certificate features to production:

Step 1: Deploy API Server Updates

bash
# On the API server (api.pocketbook.studio)
git pull origin main
npm run build:server
npm run restart:prod

Step 2: Deploy Frontend Updates

bash
# Frontend deployment triggers automatically via Vercel
git push origin main

Step 3: Verify Deployment

Test critical endpoints:

bash
# API Health Check
curl https://api.pocketbook.studio/api/certificate/health

# Certificate Public API
curl https://api.pocketbook.studio/api/certificate/public/0

# Frontend Route
https://www.pocketbook.studio/certificate/0

Database Integration ​

Certificate data is automatically stored in MongoDB when minting occurs:

Certificate Model Structure:

typescript
{
  id: string;
  tokenId: number;
  name: string;
  imageUrl: string;
  metadata: {
    name: string;
    artist: string;
    category: string;
    description: string;
    tokenId?: string;
    warranty?: WarrantyMetadata;
    // ... other fields
  };
  provenance: Array<ProvenanceEntry>;
  transactionHash: string;
  blockNumber: number;
  createdAt: Date;
  updatedAt: Date;
}

QR Code Verification ​

Overview ​

Certificates include QR codes that allow anyone to verify ownership and view certificate details without authentication.

How It Works ​

QR Code Generation:

  • Automatically generated when certificate is created
  • Links to: www.pocketbook.studio/certificate/{id}
  • Accessible via "Show QR Code" button in Certificate Viewer

Public Verification Flow:

  1. User scans QR code with any smartphone camera
  2. Browser opens public certificate page
  3. API fetches certificate data: api.pocketbook.studio/api/certificate/public/{id}
  4. Public viewer displays:
    • Certificate image and metadata
    • Ownership information (if available)
    • Provenance history
    • Warranty information (if applicable)
    • Blockchain verification link

Security Features ​

  • No Authentication Required: Public access for viewing only
  • No Sensitive Data: Only certificate metadata exposed
  • CORS Headers: Proper cross-origin access configuration
  • Rate Limiting: Applied via existing middleware
  • Export Restrictions: PDF export only available to certificate owners

Implementation Files ​

API Routes:

  • src/server/routes/certificateRoutes.ts - Certificate API endpoints

Frontend Components:

  • src/pages/PublicCertificate.tsx - Public certificate viewer page
  • src/components/CertificateViewer.tsx - QR code modal

Router Configuration:

  • src/App.tsx - Public certificate route registration
  • src/server.ts - API route registration

Warranty Integration ​

Overview ​

Comprehensive product warranty support integrated into the certificate system with auto-calculation, validation, and visual status tracking.

Creating Warranty Certificates ​

Step 1: Create Warranty Template

  1. Open Template Manager (click "Manage" button in SingleMint or SingleMintVoucher)
  2. At the top, locate "Product Warranty Template" card
  3. Click "Create Warranty Template" button
  4. Template is instantly created with 9 pre-configured fields

Step 2: Fill in Warranty Details

  1. Select "Product Warranty Certificate" from template dropdown

  2. Complete required fields:

    • Warranty Period (dropdown): 1 year, 2 years, 3 years, 5 years, 10 years, Lifetime
    • Warranty Type (dropdown): Manufacturer, Extended, Limited, Full Coverage, Parts Only, Labor Only
    • Warranty Start Date (date picker): When coverage begins
    • Warranty End Date (auto-calculated): Automatically computed from period + start date
    • Coverage Details (textarea): What is covered
    • Exclusions (optional): What is NOT covered
    • Claim Process (textarea): How to file a claim
    • Contact Information (text): Email or phone for warranty service
    • Terms & Conditions URL (optional): Link to full terms

  3. Upload product images

  4. Mint certificate

Auto-calculation Features ​

End Date Calculation:

  • Watches warranty period and start date fields
  • Automatically calculates end date (e.g., "2 years" = start + 2 years)
  • Supports "Lifetime" warranties (set to 100 years)
  • Allows manual override if needed

Implementation:

typescript
// File: src/utils/warrantyCalculations.ts

// Calculate end date from period
calculateWarrantyEndDate(startDate: string, period: string): string

// Check warranty status
isWarrantyExpired(endDate: string): boolean
getWarrantyStatus(startDate: string, endDate: string): 'active' | 'expired' | 'future'

// Display helpers
formatWarrantyPeriod(period: string): string
getDaysRemaining(endDate: string): number

Warranty Display ​

Certificate Viewer:

  • Collapsible "Product Warranty" section in Details tab
  • Status chip with color coding:
    • Green: Active warranty
    • Red: Expired or less than 1 hour remaining
    • Blue: Future/Not yet active
  • Expandable view shows all warranty details

Public Verification:

  • Warranty information visible on public certificate pages
  • Same collapsible interface for transparency
  • No authentication required to view

Validation and Warnings ​

Before minting, the system checks for expired warranties:

  • If warranty end date has passed, displays confirmation dialog
  • Warns user but allows proceeding (non-blocking)
  • Helps prevent accidental creation of expired warranty certificates

Warranty Metadata Structure ​

typescript
warranty?: {
  period: string;              // e.g., "2 years", "5 years", "Lifetime"
  type: string;                // e.g., "Manufacturer", "Extended"
  startDate: string;           // ISO date string
  endDate: string;             // ISO date string (calculated or manual)
  coverage: string;            // Coverage details
  exclusions: string;          // What's not covered
  claimProcess: string;        // How to file a claim
  contactInfo: string;         // Warranty service contact
  termsUrl?: string;           // Link to full warranty terms
}

Key Files ​

Components:

  • src/components/WarrantyInfoSection.tsx - Display component
  • src/components/DynamicCustomFields.tsx - Auto-calculation logic
  • src/components/CertificateViewer.tsx - Viewer integration
  • src/pages/VerifyCertificate.tsx - Public view integration

Utilities:

  • src/utils/warrantyCalculations.ts - Calculation functions

Template:

  • src/server/scripts/seedWarrantyTemplate.ts - Template seed script

API:

  • src/server/routes/enterpriseTemplateRoutes.ts - Initialization endpoint

Certificate Gifting ​

Overview ​

Certificate gifting allows users to securely transfer certificates to recipients via email or SMS notifications with encrypted contact information and blockchain-verified transfers.

Prerequisites ​

Server Configuration:

  • SERVER_WALLET_ENCRYPTION_KEY - For encrypting smart account credentials
  • Smart account credential stored for sender
  • SMTP/Twilio credentials configured for notifications
  • RESEND_API_KEY - For email delivery fallback

Database Setup:

bash
npm run db:sync-gift-indexes

Creating a Gift ​

From Dashboard:

  1. Navigate to certificate you want to gift
  2. Click "Gift" button
  3. Fill in recipient information:
    • Recipient email address (required)
    • Recipient phone number (optional, for SMS notifications)
    • Personal message (optional)
  4. Choose delivery method (email/SMS)
  5. Confirm gift creation

API Response:

  • Returns 201 status with transferId
  • Creates record in pendingcertificatetransfers collection
  • Initial status: pending

Notification Delivery ​

Email Delivery:

  • Primary: SMTP server (if configured)
  • Fallback: Resend API (if SMTP fails)
  • Contains unique claim link: /claim/:token
  • Encrypted contact data stored in database

SMS Delivery:

  • Twilio integration (if phone number provided)
  • Logs delivery status
  • Same claim link as email

Resend Functionality:

  • Gift creator can resend notifications
  • Contact data remains encrypted
  • Security logs capture resend events

Claiming a Gift ​

Recipient Flow:

  1. Open claim link from notification: /claim/:token
  2. Authenticate with wallet (or create account)
  3. Click "Claim Gift" button
  4. System executes blockchain transfer

API Process:

POST /api/certificates/gift/claim/:token

Response:
{
  transactionHash: "0x...",
  userOperationHash: "0x...",
  status: "claimed"
}

Database Updates:

  • pendingcertificatetransfers.status → claimed
  • Certificate provenance updated with transfer event
  • Ownership transferred to recipient address

Security Features ​

Rate Limiting:

  • giftTokenAttemptRateLimit: Prevents brute force on single token (HTTP 429)
  • giftClaimRateLimit: Limits claims per IP address
  • Protection against abuse and malicious actors

Data Protection:

  • Recipient contact information encrypted in database
  • Phone numbers hashed for privacy
  • No PII persisted in plaintext
  • Security audit logs for all operations

Token Security:

  • Unique, cryptographically secure claim tokens
  • Single-use tokens (marked as claimed)
  • Expiration mechanism for unclaimed gifts

Gift Lifecycle Management ​

Expiration:

bash
# Automated cleanup process
processExpiredGifts()
  • Removes expired transfer records
  • Notifies sender of expiration
  • Certificate remains with original owner

Revocation:

  • Gift creator can revoke before claim
  • Status transitions to revoked
  • Claim link becomes invalid
  • Certificate stays with sender

Testing Checklist ​

Happy Path:

  • [ ] Create gift from dashboard (expect 201 with transferId)
  • [ ] Verify pendingcertificatetransfers record created
  • [ ] Confirm email/SMS delivery
  • [ ] Open claim link and authenticate
  • [ ] Execute claim (verify transactionHash returned)
  • [ ] Inspect blockchain transaction
  • [ ] Verify status updated to claimed

Failure Scenarios:

  • [ ] Invalid token triggers rate limit (HTTP 429)
  • [ ] Multiple tokens from same IP hits rate limit
  • [ ] Missing sender credential returns 502
  • [ ] SMTP outage triggers Resend fallback
  • [ ] Resend audit logs security event

Regression Checks:

  • [ ] Gift revocation flows function correctly
  • [ ] Expiration flows work as expected
  • [ ] processExpiredGifts() removes expired transfers
  • [ ] No PII persisted in plaintext

Burn Functionality ​

Overview ​

The burn functionality allows authorized users to permanently destroy (burn) NFTs from the blockchain. This is an irreversible operation with proper authorization checks and safety measures.

Authorization ​

Smart Contract Authorization Logic:

solidity
function burn(uint256 tokenId) external {
    require(_isAuthorized(_msgSender(), tokenId), "Not authorised");
    _burn(tokenId, true);
}

Authorized users include:

  • Token owner
  • Approved address for the specific token
  • Operator approved for all tokens of the owner
  • Contract admins
  • Contract owner

Frontend Implementation ​

Components:

BurnService (src/services/burnService.ts)

  • Handles smart contract interactions
  • Authorization checking
  • Transaction execution and error handling

useBurnNFT Hook (src/hooks/useBurnNFT.ts)

  • React hook for burn functionality
  • Loading states and error handling
  • Integrates with Dynamic wallet context

BurnButton Component (src/components/ui/BurnButton.tsx)

  • User-friendly burn button with confirmation dialog
  • Supports variants: danger, warning, default
  • Loading states and error feedback

Integration with Certificate Viewer ​

The burn button appears when:

  • User is authenticated (has connected wallet)
  • Certificate has valid tokenId in metadata
  • User is not in public/unauthorized view
tsx
{/* Burn Button - Only for authenticated users */}
{primaryWallet && certificate.metadata?.tokenId && (
  <BurnButton
    tokenId={certificate.metadata.tokenId}
    tokenName={certificate.name}
    onBurnSuccess={(transactionHash) => {
      console.log('NFT burned successfully:', transactionHash);
      onClose();
    }}
    variant="danger"
    size="sm"
  />
)}

User Experience Flow ​

Step-by-Step Burn Process:

  1. Authentication Check: User must have connected wallet
  2. Authorization Check: System verifies user can burn the token
  3. Confirmation Dialog:
    • Warning message about permanent destruction
    • User must confirm action
    • Option to cancel
  4. Transaction Execution:
    • Smart contract burn function called
    • Loading state displayed
    • Transaction submitted to blockchain
  5. Success Feedback:
    • Confirmation message shown
    • Certificate viewer closes
    • UI updated to reflect burned state

Safety Features ​

Confirmation Dialog:

  • Prevents accidental burns
  • Clear warning about irreversibility
  • Requires explicit user confirmation

Authorization Checks:

  • Multiple layers of validation
  • Smart contract-level verification
  • Frontend authorization preview

Error Handling:

  • Graceful handling of failed transactions
  • Clear error messages
  • User-friendly feedback

Loading States:

  • Visual feedback during processing
  • Prevents duplicate submissions
  • Transaction status updates

Usage Examples ​

Basic Implementation:

tsx
<BurnButton
  tokenId="123"
  tokenName="My NFT"
  onBurnSuccess={(txHash) => console.log('Burned:', txHash)}
/>

Custom Styling:

tsx
<BurnButton
  tokenId="123"
  tokenName="My NFT"
  variant="warning"
  size="lg"
  className="custom-burn-button"
/>

With Custom Success Handler:

tsx
<BurnButton
  tokenId="123"
  tokenName="My NFT"
  onBurnSuccess={(txHash) => {
    setNftBurned(true);
    showToast('success', 'NFT burned successfully!');
    navigate('/dashboard');
  }}
/>

Configuration ​

Environment Variables:

  • NFT_CONTRACT_ADDRESS: Smart contract address
  • Network configuration for transactions

Dependencies:

  • ethers: Smart contract interactions
  • @dynamic-labs/sdk-react-core: Wallet integration
  • React hooks for state management

User Flows and UI Access ​

Enterprise User Flow ​

Creating Certificates:

  1. Login → Enterprise dashboard
  2. Navigate → Create Certificate or Create Voucher
  3. Choose Template (optional):
    • Open Template Manager
    • Select existing template or create new
    • For warranties, use "Product Warranty Certificate"
  4. Fill Details:
    • Certificate name and description
    • Upload images
    • Complete custom fields (if template selected)
  5. Mint → Create on blockchain
  6. View → Certificate appears in dashboard

Managing Certificates:

  1. View Certificate → Click to open Certificate Viewer
  2. Available Actions:
    • Show QR Code → Display verification QR
    • Gift Certificate → Transfer to recipient
    • Burn Certificate → Permanently destroy (if authorized)
    • Export PDF → Download certificate
  3. View Details:
    • Details Tab → Metadata, warranty, provenance
    • History Tab → Blockchain transactions
    • Transfer Tab → Ownership history

Customer/Recipient Flow ​

Receiving Certificates:

  1. Notification → Email or SMS with claim link
  2. Open Link → /claim/:token
  3. Authenticate → Connect wallet or create account
  4. Claim → Execute blockchain transfer
  5. Confirmation → Certificate appears in wallet

Verifying Certificates:

  1. Scan QR Code → Opens public verification page
  2. View Information:
    • Certificate image and details
    • Ownership information
    • Warranty status (if applicable)
    • Blockchain verification link
  3. No Authentication Required → Public access

Administrator Flow ​

System Management:

  1. Monitor → Dashboard analytics
  2. Review → Pending transfers and gifts
  3. Support → Assist with failed transactions
  4. Burn → Revoke fraudulent certificates (if authorized)

Testing Procedures ​

Certificate Creation Testing ​

Local Testing:

  • [ ] Create certificate with mock data
  • [ ] Verify database record created
  • [ ] Check blockchain transaction
  • [ ] Confirm metadata stored correctly
  • [ ] Test with various templates

Production Testing:

  • [ ] Deploy to staging environment
  • [ ] Test with real blockchain network
  • [ ] Verify API endpoints respond
  • [ ] Check database persistence
  • [ ] Monitor transaction costs

QR Code Verification Testing ​

Functionality Tests:

  • [ ] Generate QR code for certificate
  • [ ] Scan QR code with mobile device
  • [ ] Verify public page loads correctly
  • [ ] Check API response format
  • [ ] Test error handling for invalid IDs

Cross-browser Testing:

  • [ ] Test on Chrome, Firefox, Safari
  • [ ] Mobile browser compatibility
  • [ ] QR code scanning apps
  • [ ] Deep link handling

Warranty Testing ​

Auto-calculation:

  • [ ] Select warranty period and start date
  • [ ] Verify end date auto-populates
  • [ ] Test "Lifetime" warranty calculation
  • [ ] Confirm manual override works
  • [ ] Test various period options

Status Display:

  • [ ] Create active warranty certificate
  • [ ] Create expired warranty certificate
  • [ ] Create future warranty certificate
  • [ ] Verify status chip colors
  • [ ] Test collapsible section

Validation:

  • [ ] Attempt to mint expired warranty
  • [ ] Confirm warning dialog appears
  • [ ] Verify can proceed with expired warranty
  • [ ] Check validation for required fields

Gifting Testing ​

Happy Path (E2E):

  • [ ] Create gift from dashboard (verify 201 response with transferId)
  • [ ] Check pendingcertificatetransfers record (status=pending)
  • [ ] Confirm email delivery (SMTP logs)
  • [ ] Confirm SMS delivery (Twilio logs)
  • [ ] Open claim link and authenticate
  • [ ] Execute claim (POST /api/certificates/gift/claim/:token)
  • [ ] Verify JSON response includes transactionHash
  • [ ] Check Polygon explorer for transaction
  • [ ] Confirm status updated to "claimed"
  • [ ] Verify provenance updated

Failure Scenarios:

  • [ ] Invalid token triggers rate limit (HTTP 429)
  • [ ] Brute force/IP abuse hits giftClaimRateLimit
  • [ ] Missing credential returns 502 with helpful message
  • [ ] SMTP outage triggers Resend fallback
  • [ ] Resend audit logs security event

Edge Cases:

  • [ ] Gift revocation before claim
  • [ ] Gift expiration handling
  • [ ] Duplicate claim attempts
  • [ ] Network failure during transfer

Burn Testing ​

Authorization Tests:

  • [ ] Token owner can burn their token
  • [ ] Admin can burn any token
  • [ ] Contract owner can burn any token
  • [ ] Approved addresses can burn tokens
  • [ ] Unauthorized users cannot burn

Event Tests:

  • [ ] Transfer events emitted correctly
  • [ ] Events contain correct parameters
  • [ ] Event logs accessible

State Tests:

  • [ ] Token balances updated correctly
  • [ ] Approvals cleared when burned
  • [ ] Token no longer queryable after burn

Integration Tests:

  • [ ] Multiple burns work correctly
  • [ ] UI updates after burn
  • [ ] Error handling for failed burns

API Reference ​

Certificate Public API ​

Get Certificate by ID

GET /api/certificate/public/:id

Response:
{
  "id": "0",
  "name": "Certificate Name",
  "imageUrl": "https://...",
  "metadata": {
    "name": "Certificate Name",
    "artist": "Artist Name",
    "category": "Category",
    "description": "Description...",
    "warranty": { ... }
  },
  "provenance": [...]
}

Health Check

GET /api/certificate/health

Response:
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00Z"
}

Gift API ​

Create Gift

POST /api/certificates/gift/create

Body:
{
  "certificateId": "123",
  "recipientEmail": "recipient@example.com",
  "recipientPhone": "+1234567890",
  "message": "Personal message"
}

Response:
{
  "transferId": "transfer_123",
  "status": "pending",
  "claimToken": "abc123..."
}

Claim Gift

POST /api/certificates/gift/claim/:token

Response:
{
  "transactionHash": "0x...",
  "userOperationHash": "0x...",
  "status": "claimed"
}

Resend Notification

POST /api/certificates/gift/resend/:transferId

Response:
{
  "status": "sent",
  "method": "email"
}

Warranty Template API ​

Initialize Warranty Template

POST /api/enterprise/templates/init-warranty

Response:
{
  "id": "template_123",
  "name": "Product Warranty Certificate",
  "fields": [...]
}

Get Template

GET /api/enterprise/templates/:id

Response:
{
  "id": "template_123",
  "name": "Product Warranty Certificate",
  "fields": [...],
  "createdAt": "2024-01-01T00:00:00Z"
}

Best Practices ​

Certificate Creation ​

Naming Conventions:

  • Use descriptive, unique names
  • Include version or edition numbers
  • Follow consistent formatting

Metadata:

  • Provide complete, accurate information
  • Include high-quality images (recommended: 1000x1000px minimum)
  • Use appropriate categories
  • Add relevant tags for searchability

Templates:

  • Create reusable templates for common certificate types
  • Document template purpose and fields
  • Test templates before production use
  • Version control template changes

Warranty Certificates ​

For Manufacturers:

  • Clearly define coverage details
  • Specify exclusions explicitly
  • Provide clear claim process
  • Include accessible contact information
  • Link to full terms and conditions
  • Set realistic warranty periods
  • Test with sample products first

For Enterprise Users:

  • Use warranty template for consistency
  • Verify auto-calculated dates
  • Review warranty before minting
  • Keep warranty records in database
  • Monitor warranty expiration dates

For Customers:

  • Save claim link and QR code
  • Note warranty start and end dates
  • Understand coverage and exclusions
  • Keep proof of purchase
  • File claims within warranty period

Certificate Gifting ​

Security:

  • Verify recipient information before sending
  • Use secure communication channels
  • Monitor pending transfers
  • Set appropriate expiration dates
  • Review gift activity regularly

User Experience:

  • Provide clear claiming instructions
  • Send timely notifications
  • Follow up on unclaimed gifts
  • Handle errors gracefully

Burn Operations ​

Safety:

  • Always use confirmation dialogs
  • Clearly warn about irreversibility
  • Log all burn operations
  • Implement proper authorization
  • Monitor for suspicious activity

Governance:

  • Document burn policies
  • Require multiple approvals for high-value items
  • Keep audit trail
  • Review burn activity regularly

Performance Optimization ​

Database:

  • Index frequently queried fields
  • Implement caching for public certificates
  • Use pagination for large result sets
  • Regular database maintenance

Blockchain:

  • Batch operations when possible
  • Monitor gas costs
  • Implement retry logic for failed transactions
  • Use appropriate gas limits

Frontend:

  • Lazy load images
  • Implement infinite scroll
  • Cache API responses
  • Optimize bundle size

Security ​

Authentication:

  • Use JWT tokens with appropriate expiration
  • Implement refresh token rotation
  • Validate all inputs server-side
  • Use HTTPS everywhere

Authorization:

  • Verify ownership before sensitive operations
  • Implement role-based access control
  • Log authorization failures
  • Use blockchain verification for ownership

Data Protection:

  • Encrypt sensitive data at rest
  • Hash personal information
  • Implement rate limiting
  • Monitor for abuse patterns

Troubleshooting ​

Certificate Creation Issues ​

"Transaction failed" error:

  • Check wallet has sufficient balance for gas
  • Verify network connection
  • Ensure contract address is correct
  • Check if wallet is connected

"Database error" message:

  • Verify MongoDB connection
  • Check database credentials
  • Ensure database indexes exist
  • Review server logs

Images not uploading:

  • Check file size (limit: usually 10MB)
  • Verify file format (PNG, JPG, GIF)
  • Test network connection
  • Check storage service status

QR Code Issues ​

QR code not generating:

  • Verify certificate has valid ID
  • Check certificate exists in database
  • Review API endpoint accessibility
  • Clear browser cache

Public page not loading:

  • Verify URL format: /certificate/{id}
  • Check API server status
  • Test API endpoint directly
  • Review CORS configuration

"Certificate not found" error:

  • Verify certificate ID is correct
  • Check database record exists
  • Ensure proper API routing
  • Review server logs

Warranty Issues ​

End date not auto-calculating:

  • Ensure both period and start date selected
  • Check JavaScript console for errors
  • Verify warrantyCalculations.ts is loaded
  • Try manually entering end date

Warranty section not visible:

  • Confirm certificate has warranty data
  • Check if warranty template was used
  • Verify WarrantyInfoSection component loaded
  • Review certificate metadata structure

Status showing incorrectly:

  • Verify dates are in correct format (ISO 8601)
  • Check system time/timezone
  • Review warrantyCalculations logic
  • Clear browser cache

Gifting Issues ​

"Not authorised" error during burn:

  • Verify user owns the token
  • Check wallet connection
  • Ensure user has proper permissions
  • Review smart contract authorization

Gift notification not delivered:

  • Check email address is correct
  • Verify SMTP/Resend configuration
  • Review email service logs
  • Check spam folder
  • Test with resend function

Claim link invalid:

  • Verify token hasn't expired
  • Check if gift was revoked
  • Ensure token format is correct
  • Review rate limiting (HTTP 429)

Blockchain transfer failed:

  • Check sender credential exists
  • Verify sufficient gas in sender wallet
  • Review smart contract state
  • Check network congestion

Burn Issues ​

"Not authorised" error:

  • Verify user owns token
  • Check wallet connection
  • Ensure user has proper permissions
  • Review smart contract authorization

Transaction fails:

  • Check gas fees and wallet balance
  • Verify network connection
  • Ensure contract is accessible
  • Review transaction logs

UI issues:

  • Verify tokenId exists in metadata
  • Check wallet connection status
  • Ensure proper component imports
  • Clear browser cache

General Debugging ​

Enable Debug Logging:

javascript
// In browser console
localStorage.setItem('debug', 'pocketbook:*');

Check API Health:

bash
curl https://api.pocketbook.studio/api/certificate/health

Verify Database Connection:

bash
npm run db:check

Review Server Logs:

bash
# On production server
tail -f /var/log/pocketbook/api.log

Core Documentation ​

Feature-Specific Guides ​

System Documentation ​

  • Billing System - Pricing and billing
  • Deployment Guide (internal documentation) - Production deployment procedures
  • Security Guide (internal documentation) - Security best practices

Enterprise Features ​

Technical References ​

  • Smart Contract ABI - Contract interaction reference
  • Database Schema - MongoDB collection structures
  • Event System - Webhook event types and payloads

External Resources ​

Support and Community ​

Getting Help ​

Technical Support:

Community:

Contributing ​

We welcome contributions! Please see our contributing guidelines for:

  • Bug reports
  • Feature requests
  • Code contributions
  • Documentation improvements

Appendix ​

Glossary ​

NFT (Non-Fungible Token): Unique digital asset on blockchain representing certificate ownership

Provenance: Historical record of certificate ownership and transfers

Smart Contract: Self-executing code on blockchain that governs certificate operations

QR Code: Scannable code linking to public certificate verification page

Warranty Period: Duration of warranty coverage (e.g., "2 years", "Lifetime")

Claim Token: Unique, secure token used for claiming gifted certificates

Burn: Permanent destruction of NFT certificate from blockchain

CORS: Cross-Origin Resource Sharing - security feature for API access

JWT: JSON Web Token - authentication token format

Rate Limiting: Protection mechanism to prevent API abuse

Version History ​

v1.0.0 - Initial certificate system release

  • Basic certificate creation and viewing
  • Blockchain integration
  • Database storage

v1.1.0 - QR code verification

  • Public certificate pages
  • QR code generation
  • No-auth verification

v1.2.0 - Warranty integration

  • Warranty templates
  • Auto-calculation
  • Status tracking

v1.3.0 - Certificate gifting

  • Transfer system
  • Email/SMS notifications
  • Claim process

v1.4.0 - Burn functionality

  • Authorized revocation
  • Safety features
  • UI integration

File Structure Reference ​

src/
├── components/
│   ├── CertificateViewer.tsx              # Main viewer component
│   ├── SingleMint.tsx                     # Certificate creation
│   ├── SingleMintVoucher.tsx              # Voucher creation
│   ├── DynamicCustomFields.tsx            # Custom field handling
│   ├── WarrantyInfoSection.tsx            # Warranty display
│   ├── TemplateManagerDrawer.tsx          # Template management
│   └── ui/
│       └── BurnButton.tsx                 # Burn button component
├── pages/
│   ├── PublicCertificate.tsx              # Public verification
│   └── VerifyCertificate.tsx              # Certificate verification
├── server/
│   ├── routes/
│   │   ├── certificateRoutes.ts           # Certificate API
│   │   └── enterpriseTemplateRoutes.ts    # Template API
│   ├── models/
│   │   └── Certificate.ts                 # Database model
│   └── scripts/
│       └── seedWarrantyTemplate.ts        # Warranty template seed
├── services/
│   └── burnService.ts                     # Burn service
├── hooks/
│   └── useBurnNFT.ts                      # Burn hook
└── utils/
    └── warrantyCalculations.ts            # Warranty utilities

Last updated: 2024For the latest documentation, visit: https://docs.pocketbook.studio

Released under the MIT License.

Copyright © 2025 Pocketbook Studio