feat: adds the token-distribution an benefit-marketplace contract file

[Airstarr]

Employee Benefits Marketplace & Token Distribution Contracts

Overview

The Employee Benefits Marketplace and Employee Token Distribution smart contracts work together to create a decentralized and transparent ecosystem where employers can offer, manage, and reward employees with various benefits using blockchain technology. The system allows employees to use tokens to select from a variety of benefits, request refunds, and transfer or trade their benefits in a seamless and secure manner.

This README provides a detailed explanation of both the Employee Benefits Marketplace Contract and the Employee Token Distribution Contract, outlining the functions, usage, and architecture of the contracts.

---

Contracts Description

1. Employee Benefits Marketplace Contract

The Employee Benefits Marketplace contract manages a range of functionalities related to the listing, purchase, refund, and management of employee benefits. It allows employers (vendors) to list benefits, dynamically adjust prices based on demand and season, and enables employees to purchase, refund, and track their benefits.

Key Features:

• Vendor Registration: Employers (vendors) can register on the platform to list their benefits.
• Benefit Listing: Vendors can list various employee benefits such as healthcare, fitness, insurance, and wellness services, specifying a price and other details.
• Dynamic Pricing: Benefits can have seasonal and demand-based price multipliers, which are calculated and updated automatically.
• Benefit Purchase: Employees can purchase benefits using tokens, with payments transferred directly to the vendor.
• Refund Requests: Employees can request refunds within a specified period after purchasing a benefit, provided certain conditions are met.
• Benefit Stats: The contract tracks the number of benefits purchased and total sales by the vendor, providing transparency to both employees and employers.
• Benefit Management: Vendors can update their benefits’ availability, price multipliers, and other details as needed.

Core Functions:

1. Register Vendor: Allows vendors to register and offer benefits.

   • Function: register-vendor(name)

2. List Benefit: Vendors list new benefits by providing details like name, description, and base price.

   • Function: list-benefit(name, description, benefit-type, base-price)

3. Update Multipliers: Vendors can adjust seasonal and demand-based multipliers to influence benefit prices.

   • Function: update-multipliers(benefit-id, seasonal-mult, demand-mult)

4. Purchase Benefit: Employees can purchase benefits using tokens. The contract automatically handles token transfer and updates the employee’s benefits list.

   • Function: purchase-benefit(benefit-id)

5. Request Refund: Employees can request refunds for purchased benefits within a specific period (e.g., 30 days).

   • Function: request-refund(benefit-id)

6. Dynamic Price Calculation: Calculates the final price of a benefit based on seasonal and demand-based price multipliers.

   • Private Function: calculate-price(benefit-id)

7. Benefit Lookup: Retrieve benefit details by ID, and check purchase or vendor information.

   • Function: get-benefit(benefit-id), get-purchase-info(benefit-id, purchaser), get-vendor-info(vendor)

8. Seasonal Adjustment: Admin can update the current season (e.g., Q1, Q2, etc.) to influence benefit prices.

   • Function: update-season(new-season)

---

2. Employee Token Distribution Contract

The Employee Token Distribution Contract allows authorized employers to manage the distribution of tokens to employees, enabling a rewards system based on company performance, employee milestones, or other criteria. The contract handles token allocation, transfers, expiration, and burning of tokens to ensure that they are used effectively within a given time period.

Key Features:

• Token Allocation: Authorized employers can allocate tokens to employees as rewards, performance bonuses, or benefits.
• Token Transfer: Employees can transfer tokens between themselves, allowing for peer-to-peer exchanges of rewards.
• Token Expiration: Tokens allocated to employees have an expiration period, after which they are considered expired and are burned.
• Top-up Tokens: Employers can top-up or increase the number of tokens allocated to employees for special events, performance, or other criteria.
• Balance Management: The contract manages the balances of each employee and allows them to check their token holdings.
• Authorized Employers: Only authorized employers can allocate, transfer, or manage tokens for employees.

Core Functions:

1. Add Authorized Employer: Admin can add new employers who are authorized to distribute tokens.

   • Function: add-employer(employer)

2. Remove Authorized Employer: Admin can remove employers from the list of authorized distributors.

   • Function: remove-employer(employer)

3. Allocate Tokens: Employers allocate tokens to employees, specifying the amount and expiration period.

   • Function: allocate-tokens(employee, amount)

4. Transfer Tokens: Employees can transfer tokens to others, ensuring balances are updated accordingly.

   • Function: transfer(recipient, amount)

5. Burn Expired Tokens: Tokens that have expired are burned from the employee's balance and the total supply.

   • Function: burn-expired-tokens(employee)

6. Top-Up Tokens: Employers can increase the number of tokens allocated to an employee as a special reward.

   • Function: top-up-tokens(employee, amount)

7. Balance Lookup: Retrieve an employee’s current token balance.

   • Function: get-balance(account)

8. Token Metadata Lookup: Retrieve metadata about tokens, such as last allocation and expiration height.

   • Function: get-token-metadata(employee)

9. Get Total Supply: Get the total number of tokens in circulation.

   • Function: get-total-supply

---

Architecture & Flow

The architecture of the Employee Benefits Marketplace and Token Distribution Contracts relies on the interaction between two key components:

1. Marketplace Contract: This contract handles the listing, purchasing, and refunding of employee benefits. It manages dynamic pricing, vendor registration, and tracks the purchase history for each employee.

2. Token Distribution Contract: This contract manages the allocation, transfer, and expiration of tokens. Authorized employers allocate tokens to employees as rewards or benefits, and employees can use these tokens within the marketplace to purchase benefits.

---

Error Handling

Both contracts have built-in error handling to ensure smooth and secure interactions:

• ERR-NOT-AUTHORIZED: Raised when an unauthorized user attempts to access restricted functionality.
• ERR-INVALID-PRICE: Raised when a price is not within the acceptable range.
• ERR-BENEFIT-NOT-FOUND: Raised when the requested benefit ID does not exist.
• ERR-ALREADY-PURCHASED: Raised when an employee attempts to purchase a benefit they have already purchased.
• ERR-REFUND-EXPIRED: Raised when an employee tries to request a refund after the refund period has passed.
• ERR-NOT-PURCHASER: Raised when a refund request is made by someone who is not the purchaser.
• ERR-EXPIRED-TOKENS: Raised when an employee attempts to transfer or use expired tokens.

---

Usage Examples

Employee Benefits Marketplace Contract

1. Vendor Registration

(register-vendor "HealthCo")

2. List Benefit

(list-benefit "Premium Health Insurance" "Comprehensive coverage with low deductible." TYPE-HEALTHCARE 500)

3. Purchase Benefit

(purchase-benefit 0) ;; Purchase benefit with ID 0

4. Request Refund

(request-refund 0) ;; Request refund for benefit with ID 0

5. Update Price Multipliers

(update-multipliers 0 120 150) ;; Update seasonal and demand multipliers for benefit ID 0

---

Employee Token Distribution Contract

1. Allocate Tokens

(allocate-tokens "employee1" 1000) ;; Allocate 1000 tokens to employee1

2. Transfer Tokens

(transfer "employee2" 500) ;; Transfer 500 tokens from tx-sender to employee2

3. Burn Expired Tokens

(burn-expired-tokens "employee1") ;; Burn expired tokens for employee1

---

Conclusion

These smart contracts together form a comprehensive and flexible system for managing employee benefits and rewards. They provide a secure, transparent, and efficient way for employers to offer, manage, and track employee benefits while utilizing blockchain-based tokenization for rewards and incentives. The modular design ensures scalability and adaptability to various business needs.