Roommate Utility Splitter Smart Contract

A Clarity smart contract for managing shared utility expenses among roommates on the Stacks blockchain. This contract enables transparent tracking of bills, payments, and balances in shared living arrangements.

Features

🏠 House Management

• Create houses with unique identifiers
• Each house has an owner who manages members
• Track active/inactive status of houses

👥 Roommate Management

• Add roommates to houses with custom names
• Remove roommates when they move out
• Track join dates and member status
• Owner has administrative control

💰 Bill Splitting

• Create bills with descriptions (e.g., "Electric", "Water", "Internet")
• Automatically split bills among specified number of roommates
• Track who paid the bill initially
• Record individual payment status

📊 Balance Tracking

• Real-time balance tracking for each member
• Automatic balance updates when payments are recorded
• Manual balance adjustments by house owner
• Track who owes money and who is owed

Contract Functions

Public Functions

create-house

(create-house (name (string-ascii 50)))

Creates a new house and automatically adds the creator as owner and first member.

• Returns: House ID
• Access: Anyone

add-roommate

(add-roommate (house uint) (member principal) (name (string-ascii 50)))

Adds a new roommate to the house.

• Returns: true on success
• Access: House owner only

remove-roommate

(remove-roommate (house uint) (member principal))

Removes a roommate from the house (sets status to inactive).

• Returns: true on success
• Access: House owner only

create-bill

(create-bill (house uint) (description (string-ascii 100)) (total uint) (split uint))

Creates a new bill to be split among roommates.

• Parameters:
  • house: House ID
  • description: Bill description (e.g., "Electric - January")
  • total: Total amount in microSTX
  • split: Number of people to split among
• Returns: Bill ID
• Access: House members only

record-payment

(record-payment (bill uint) (member principal))

Records that a member has paid their share of a bill. Automatically updates balances.

• Returns: true on success
• Access: House members only

settle-bill

(settle-bill (bill uint))

Marks a bill as fully settled.

• Returns: true on success
• Access: Bill creator only

update-balance

(update-balance (house uint) (member principal) (amount uint) (add bool))

Manually adjusts a member's balance.

• Parameters:
  • add: true to add to balance, false to subtract
• Returns: true on success
• Access: House owner only

Read-Only Functions

• get-house - Retrieve house information
• get-roommate - Get roommate details
• get-bill - Retrieve bill information
• get-payment-status - Check if a member paid a specific bill
• get-member-balance - Get member's current balance
• get-bill-counter - Get total number of bills created
• is-roommate - Check if address is an active member

Usage Example

1. Create a House

(contract-call? .roommate-splitter create-house "Apartment 5B")
;; Returns: (ok u1)

2. Add Roommates

(contract-call? .roommate-splitter add-roommate u1 'SP2... "Alice")
(contract-call? .roommate-splitter add-roommate u1 'SP3... "Bob")

3. Create a Bill

;; Electric bill of 300 STX split 3 ways
(contract-call? .roommate-splitter create-bill u1 "Electric - Oct 2025" u300000000 u3)
;; Returns: (ok u1) - Bill ID 1, each person owes 100 STX

4. Record Payments

(contract-call? .roommate-splitter record-payment u1 'SP2...)
(contract-call? .roommate-splitter record-payment u1 'SP3...)

5. Check Balances

(contract-call? .roommate-splitter get-member-balance u1 'SP2...)
;; Returns balance (negative = owes money, positive = is owed money)

Error Codes

Code	Constant	Description
u100	err-owner-only	Only house owner can perform this action
u101	err-not-member	Address is not a house member
u102	err-already-member	Member already exists in house
u103	err-invalid-amount	Bill amount must be greater than 0
u104	err-already-paid	Payment already recorded
u105	err-bill-not-found	Bill ID doesn't exist
u106	err-insufficient-balance	Insufficient balance for operation
u107	err-no-roommates	No roommates in house
u108	err-invalid-split	Split count must be greater than 0

Security Features

• Access Control: Owner-only functions for sensitive operations
• Validation: Input validation on all parameters
• Member Verification: Only active members can create bills and record payments
• Duplicate Prevention: Prevents duplicate payment records
• Safe Math: Balance calculations prevent underflow (minimum balance is 0)

Best Practices

1. Bill Creation: Always specify accurate split counts
2. Payment Recording: Record payments promptly to keep balances accurate
3. Regular Settlements: Use settle-bill to mark completed bills
4. Balance Checks: Regularly check balances to ensure fairness
5. Member Management: Remove inactive roommates to keep data clean

Development & Testing

Deploy this contract to testnet before mainnet:

clarinet contract deploy roommate-splitter

Run tests:

clarinet test