Split the Bill - Smart Contract

A robust Clarity smart contract for managing shared expenses on the Stacks blockchain. Split bills fairly among groups with automated payment tracking, escrow functionality, and built-in dispute prevention.

Overview

This contract enables groups to split expenses transparently on-chain. One person pays a bill upfront, then participants pay their share directly through the smart contract with automatic fee handling and payment verification.

Key Features

🎯 Core Functionality

• Create Bills: Set up shared expenses with description, total amount, and up to 20 participants
• Automatic Splitting: Evenly divides amounts among participants, fairly distributing remainders
• Direct Payments: Participants pay their share directly to the person who paid upfront
• Payment Tracking: Real-time visibility of who has paid and who hasn't
• Bill Management: Open/close bills with settlement timestamps

💰 Financial Features

• Platform Fee: Configurable fee (default 0.25%) for contract sustainability
• Custom Shares: Adjust individual participant amounts before payment
• User Statistics: Track payment history, bills created, and participation
• Fee Protection: Platform fee capped at maximum 10%

🔒 Security Features

• Authorization checks on all sensitive operations
• Double-payment prevention
• Payment validation (no zero or negative amounts)
• Status management (can't modify closed bills)
• Safe STX transfers with error handling

Contract Functions

Public Functions

create-bill

Create a new bill to split among participants.

(create-bill 
  (description (string-ascii 256))
  (total-amount uint)
  (participants (list 20 principal))
  (paid-by principal)
)

Parameters:

• description: Bill description (e.g., "Team Dinner at Restaurant")
• total-amount: Total bill amount in microSTX
• participants: List of participant wallet addresses (max 20)
• paid-by: Address of person who paid the bill upfront

Returns: Bill ID (uint)

Example:

(contract-call? .split-bill create-bill 
  "Dinner at Luigi's" 
  u10000000 
  (list 'ST1... 'ST2... 'ST3...)
  'ST1...
)

---

pay-share

Pay your portion of a bill.

(pay-share (bill-id uint))

Parameters:

• bill-id: The ID of the bill to pay

Actions:

• Transfers your share amount (minus platform fee) to the person who paid
• Transfers platform fee to contract owner
• Marks your share as paid
• Updates user statistics

Example:

(contract-call? .split-bill pay-share u1)

---

update-custom-share

Adjust a participant's share amount (creator only, before payment).

(update-custom-share 
  (bill-id uint) 
  (participant principal) 
  (new-amount uint)
)

Use Case: When someone had extra items or should pay a different amount

Restrictions:

• Only bill creator can call
• Bill must be open
• Participant must not have paid yet

---

close-bill

Close a bill to prevent further payments (creator only).

(close-bill (bill-id uint))

Use Case: After everyone has paid or to finalize the bill

---

Read-Only Functions

get-bill

Retrieve complete bill information.

(get-bill (bill-id uint))

Returns:

{
  creator: principal,
  description: (string-ascii 256),
  total-amount: uint,
  participants: (list 20 principal),
  paid-by: principal,
  status: (string-ascii 20),
  created-at: uint,
  settled-at: (optional uint)
}

---

get-participant-share

Check a participant's share details.

(get-participant-share (bill-id uint) (participant principal))

Returns:

{
  share-amount: uint,
  paid: bool,
  paid-at: (optional uint)
}

---

get-user-stats

View user's payment history and statistics.

(get-user-stats (user principal))

Returns:

{
  bills-created: uint,
  bills-participated: uint,
  total-paid: uint,
  total-received: uint
}

---

calculate-split-amounts

Preview how an amount would be split among people.

(calculate-split-amounts (total uint) (num-people uint))

Returns:

{
  base-share: uint,
  remainder: uint
}

---

Usage Workflow

Typical Bill Split Process

1. Create Bill

   Alice pays $100 dinner for 4 friends
   → Alice creates bill with 4 participants
   → Contract calculates: $25 per person
   

2. Participants Pay

   Bob calls pay-share → Sends $25 to Alice
   Carol calls pay-share → Sends $25 to Alice
   Dave calls pay-share → Sends $25 to Alice
   

3. Close Bill

   Alice calls close-bill → Marks bill as settled
   

Custom Split Example

Scenario: Pizza night, Alice ordered extra items

1. Alice creates bill: $60 total, 3 people
   Auto-split: $20 each

2. Alice updates shares:
   - Alice: $30 (had extra items)
   - Bob: $15
   - Carol: $15

3. Bob and Carol pay their custom amounts

Error Codes

Code	Constant	Description
u100	err-owner-only	Only contract owner can perform this action
u101	err-not-found	Bill or participant not found
u102	err-unauthorized	Not authorized for this action
u103	err-already-exists	Resource already exists
u104	err-invalid-amount	Invalid amount (zero or negative)
u105	err-already-paid	Share already paid
u106	err-not-paid	Share not yet paid
u107	err-invalid-split	Invalid split configuration
u108	err-bill-closed	Bill is closed
u109	err-insufficient-balance	Insufficient balance
u110	err-transfer-failed	Transfer failed

Technical Specifications

• Language: Clarity (Stacks Blockchain)
• Max Participants: 20 per bill
• Max Description Length: 256 ASCII characters
• Default Platform Fee: 0.25% (25 basis points)
• Max Platform Fee: 10% (1000 basis points)
• Currency: STX (microSTX for precision)

Security Considerations

• ✅ All payments are atomic (succeed or fail completely)
• ✅ No partial payment states possible
• ✅ Bill creator cannot modify shares after payment
• ✅ Participants cannot pay twice
• ✅ Platform fee enforced automatically
• ✅ Only contract owner can adjust fee rate
• ✅ All actions timestamped with block height

Use Cases

1. Restaurant Bills: Split dinner checks among friends
2. Group Travel: Divide accommodation and transport costs
3. Shared Subscriptions: Split Netflix, Spotify, etc.
4. Event Expenses: Manage party or event costs
5. Roommate Bills: Split utilities and rent fairly
6. Team Lunches: Handle workplace meal expenses

Future Enhancements

• Multi-currency support
• Recurring bill functionality
• Partial payment support
• Dispute resolution mechanism
• Bill templates for common scenarios
• Integration with payment reminders