Commercial Registry Smart Contract

A decentralized platform built on the Stacks blockchain for registering, managing, and reviewing commercial enterprises. This smart contract enables transparent business registration with built-in reputation management through customer feedback.

Overview

The Commercial Registry allows entrepreneurs to register their businesses on-chain, customers to leave verified reviews, and administrators to certify legitimate entities. All data is stored immutably on the blockchain, ensuring transparency and trust.

Key Features

For Business Owners

• Entity Registration: Register commercial entities with comprehensive details (name, description, sector, contact info)
• Profile Management: Update entity information at any time
• Status Control: Activate or deactivate entities as needed
• Ownership Transfer: Transfer entity ownership to another principal

For Customers

• Feedback System: Submit ratings (1-5 stars) and reviews for entities
• One Review Per Entity: Each user can only review an entity once
• Public Ratings: All reviews are permanently recorded on-chain

For Administrators

• Entity Certification: Verify legitimate businesses
• Fee Management: Adjust registration fees (capped at 100 STX)
• Quality Control: Revoke certifications when necessary

Technical Specifications

Constants

• Admin: Contract deployer (immutable)
• Registration Fee: 1 STX (adjustable by admin)
• Maximum Fee: 100 STX hard cap

Error Codes

Code	Constant	Description
u100	err-admin-only	Only admin can perform this action
u101	err-not-found	Entity or feedback not found
u102	err-already-exists	User has already reviewed this entity
u103	err-unauthorized	Caller is not the entity owner
u104	err-invalid-score	Rating must be between 1-5
u105	err-entity-inactive	Entity is not operational
u106	err-invalid-input	Invalid input parameters
u107	err-invalid-fee	Invalid fee amount

Public Functions

enroll-entity

Register a new commercial entity on the platform.

Parameters:

• title (string-ascii 100): Entity name
• details (string-ascii 500): Business description
• sector (string-ascii 50): Business category/industry
• address (string-ascii 200): Physical location
• phone (string-ascii 100): Contact number
• url (string-ascii 200): Website URL

Returns: Entity ID (uint)

Fee: Current registration fee in STX

modify-entity

Update entity information (owner only).

Parameters:

• entity-id (uint): ID of entity to update
• title, details, address, phone, url: New values

Requirements: Must be entity owner and entity must be operational

toggle-entity-status

Activate or deactivate an entity (owner only).

Parameters:

• entity-id (uint): Entity to toggle

submit-feedback

Leave a review for an entity.

Parameters:

• entity-id (uint): Entity being reviewed
• score (uint): Rating from 1-5
• message (string-ascii 500): Review text

Requirements:

• Entity must be operational
• User hasn't reviewed this entity before
• Score must be 1-5

certify-entity

Mark an entity as verified (admin only).

Parameters:

• entity-id (uint): Entity to certify

revoke-certification

Remove verification status (admin only).

Parameters:

• entity-id (uint): Entity to decertify

adjust-registration-fee

Change the registration fee (admin only).

Parameters:

• new-fee (uint): New fee in microSTX

Constraints: Must be > 0 and ≤ 100 STX

reassign-entity-ownership

Transfer entity ownership to another user.

Parameters:

• entity-id (uint): Entity to transfer
• new-proprietor (principal): New owner address

Read-Only Functions

• fetch-entity: Get entity details by ID
• fetch-feedback: Get feedback details by ID
• fetch-entity-score: Calculate average rating for an entity
• fetch-entities-by-proprietor: List all entities owned by a principal
• fetch-entities-by-sector: List all entities in a specific sector
• check-certification: Check if an entity is verified
• fetch-registration-fee: Get current registration fee
• fetch-entity-counter: Get total number of registered entities
• check-customer-feedback: Check if a user has reviewed an entity

Data Structures

Commercial Entity

{
  proprietor: principal,
  title: (string-ascii 100),
  details: (string-ascii 500),
  sector: (string-ascii 50),
  address: (string-ascii 200),
  phone: (string-ascii 100),
  url: (string-ascii 200),
  operational: bool,
  score-total: uint,
  score-count: uint,
  registered-at: uint
}

Feedback

{
  entity-id: uint,
  author: principal,
  score: uint,
  message: (string-ascii 500),
  posted-at: uint
}

Usage Example

;; Register a new business
(contract-call? .commercial-registry enroll-entity
  "Mike's Coffee Shop"
  "Artisanal coffee and fresh pastries in downtown"
  "Food & Beverage"
  "123 Main Street, Lagos"
  "+234-123-4567"
  "https://mikescoffee.com"
)

;; Submit a review
(contract-call? .commercial-registry submit-feedback
  u1  ;; entity-id
  u5  ;; 5-star rating
  "Amazing coffee and friendly service!"
)

;; Check entity rating
(contract-call? .commercial-registry fetch-entity-score u1)

Security Considerations

• All monetary transactions are handled through native STX transfers
• Entity ownership is verified for all update operations
• Reviews are immutable once submitted
• Admin privileges are limited to certification and fee management
• Input validation prevents empty or oversized strings
• One review per user per entity prevents spam

Deployment

1. Deploy the contract to Stacks blockchain
2. The deploying address becomes the admin
3. Initial registration fee is set to 1 STX
4. Users can immediately start registering entities