Decentralized Background Check Service

A secure, blockchain-based platform for conducting and managing background checks with verifiable results stored on the Stacks blockchain.

Overview

This smart contract enables a trustless background check system where:

• Requesters can order background checks on subjects
• Verifiers conduct checks and submit results
• Subjects control access to their check results
• All transactions and results are immutably recorded on-chain

Key Features

🔐 Privacy & Access Control

• Subjects control who can view their background check results
• Permission-based access system with grant/revoke capabilities
• Only authorized parties (requester, subject, verifier) can access check details

✅ Verifier Management

• Open registration for verifiers
• Owner-approved verification system
• Reputation scoring based on completed checks
• Track performance metrics per verifier

💰 Economic Model

• Fixed fee system (default: 1 STX per check)
• Upfront payment from requesters
• Automatic payment to verifiers upon completion
• Refund mechanism for cancelled checks

⚖️ Dispute Resolution

• Subjects or requesters can dispute results
• Owner-mediated dispute resolution process
• Transparent status tracking

⏱️ Expiration Management

• Automatic expiry after 1,440 blocks (~10 days)
• Prevents stale check requests
• Protects against indefinite pending states

Contract Architecture

Data Structures

Verifiers Map

{
  verified: bool,
  reputation-score: uint,
  checks-completed: uint,
  registration-block: uint
}

Background Checks Map

{
  subject: principal,
  requester: principal,
  verifier: optional principal,
  status: string-ascii 20,
  check-type: string-ascii 50,
  result-hash: optional buff 32,
  requested-at: uint,
  completed-at: optional uint,
  expiry-block: uint,
  fee-paid: uint
}

Check Lifecycle

┌─────────┐    ┌─────────────┐    ┌───────────┐    ┌───────────┐
│ Pending │───▶│ In-Progress │───▶│ Completed │───▶│ Disputed  │
└─────────┘    └─────────────┘    └───────────┘    └───────────┘
     │                                                      │
     │                                                      │
     └──────────────────▶ Cancelled                        │
                                                           │
                                                           ▼
                                                    ┌──────────┐
                                                    │ Resolved │
                                                    └──────────┘

Functions Reference

Verifier Functions

register-verifier

Register as a verifier on the platform.

• Access: Public
• Returns: (ok true) on success

approve-verifier (verifier principal)

Approve a registered verifier (owner only).

• Access: Contract owner
• Parameters:
  • verifier: Principal address of verifier to approve
• Returns: (ok true) on success

Check Management Functions

request-background-check (subject principal) (check-type string-ascii)

Request a background check on a subject.

• Access: Public
• Parameters:
  • subject: Principal address of the person to check
  • check-type: Type of background check (e.g., "employment", "criminal")
• Payment: Requires check fee in STX
• Returns: (ok check-id) on success
• Restrictions: Cannot check yourself or contract owner

assign-verifier (check-id uint)

Assign yourself as the verifier for a pending check.

• Access: Approved verifiers only
• Parameters: check-id: ID of the check to assign
• Returns: (ok true) on success

submit-check-result (check-id uint) (result-hash buff)

Submit results for an assigned check.

• Access: Assigned verifier only
• Parameters:
  • check-id: ID of the check
  • result-hash: 32-byte hash of the check results
• Returns: (ok true) on success
• Effects: Releases payment to verifier, updates reputation

cancel-check (check-id uint)

Cancel a pending check and receive refund.

• Access: Original requester only
• Parameters: check-id: ID of check to cancel
• Returns: (ok true) on success
• Effects: Refunds fee to requester

Access Control Functions

grant-access (check-id uint) (viewer principal)

Grant viewing permission to a third party.

• Access: Subject only
• Parameters:
  • check-id: ID of the check
  • viewer: Principal to grant access to
• Returns: (ok true) on success

revoke-access (check-id uint) (viewer principal)

Revoke viewing permission from a third party.

• Access: Subject only
• Parameters:
  • check-id: ID of the check
  • viewer: Principal to revoke access from
• Returns: (ok true) on success

Dispute Functions

dispute-check (check-id uint)

Raise a dispute for a completed check.

• Access: Subject or requester
• Parameters: check-id: ID of check to dispute
• Returns: (ok true) on success

resolve-dispute (check-id uint) (resolution string-ascii)

Resolve a disputed check (owner only).

• Access: Contract owner
• Parameters:
  • check-id: ID of disputed check
  • resolution: New status (e.g., "resolved", "completed")
• Returns: (ok true) on success

Read-Only Functions

get-check-fee

Get the current fee for background checks.

• Returns: (ok uint) fee in microSTX

get-verifier-info (verifier principal)

Get information about a verifier.

• Returns: (ok (optional {...})) verifier data

get-background-check (check-id uint)

Get details of a specific background check.

• Returns: (ok (optional {...})) check data

get-subject-checks (subject principal)

Get all check IDs for a subject.

• Returns: (ok (list uint)) list of check IDs

get-requester-checks (requester principal)

Get all check IDs requested by a principal.

• Returns: (ok (list uint)) list of check IDs

has-permission (check-id uint) (viewer principal)

Check if a principal has permission to view check results.

• Returns: (ok bool) permission status

Admin Functions

update-check-fee (new-fee uint)

Update the fee for background checks (owner only).

• Access: Contract owner
• Parameters: new-fee: New fee in microSTX
• Returns: (ok true) on success

Error Codes

Code	Constant	Description
u100	err-owner-only	Action requires contract owner privileges
u101	err-not-found	Requested resource not found
u102	err-unauthorized	Caller not authorized for this action
u103	err-already-exists	Resource already exists
u104	err-invalid-status	Invalid status for requested operation
u105	err-expired	Check has expired
u106	err-insufficient-payment	Payment amount insufficient
u107	err-invalid-params	Invalid parameters provided

Usage Examples

1. Becoming a Verifier

;; Register as verifier
(contract-call? .background-check register-verifier)

;; Owner approves verifier
(contract-call? .background-check approve-verifier 'ST1VERIFIER...)

2. Requesting a Background Check

;; Request employment background check
(contract-call? .background-check 
  request-background-check 
  'ST1SUBJECT... 
  "employment")

3. Completing a Check

;; Verifier assigns themselves
(contract-call? .background-check assign-verifier u1)

;; Submit results with hash
(contract-call? .background-check 
  submit-check-result 
  u1 
  0x1234567890abcdef...)

4. Managing Access

;; Subject grants access to employer
(contract-call? .background-check 
  grant-access 
  u1 
  'ST1EMPLOYER...)

;; Subject revokes access later
(contract-call? .background-check 
  revoke-access 
  u1 
  'ST1EMPLOYER...)

Security Considerations

Input Validation

• All user inputs are validated before processing
• Prevents self-checks and checks on contract owner
• Validates status transitions in check lifecycle

Access Control

• Role-based permissions (owner, verifier, requester, subject)
• Multi-level permission checks for sensitive operations
• Subjects maintain control over their data

Economic Security

• Upfront payment prevents spam
• Automatic payment on completion incentivizes verifiers
• Refund mechanism for legitimate cancellations

Data Privacy

• Results stored as hashes, not raw data
• Off-chain storage recommended for sensitive information
• Permission system controls data access

Best Practices

For Verifiers

1. Only accept checks you can complete within the expiry period
2. Store actual check results off-chain, only submit hashes
3. Maintain high reputation by completing checks accurately

For Requesters

1. Ensure you have sufficient STX before requesting checks
2. Specify clear check types
3. Monitor expiry dates for pending checks

For Subjects

1. Review completed checks promptly
2. Use the dispute mechanism if results are inaccurate
3. Manage access permissions carefully

For Contract Owners

1. Vet verifiers thoroughly before approval
2. Set reasonable check fees
3. Mediate disputes fairly and promptly

Deployment

1. Deploy contract to Stacks blockchain
2. Initialize with appropriate check fee
3. Onboard and approve initial verifiers
4. Monitor contract activity and handle disputes

Future Enhancements

• Multi-signature dispute resolution
• Tiered verifier system with different fee structures
• Automated verifier reputation decay
• Integration with external identity systems
• Batch check requests
• Verifier staking mechanism