Allowance Automation Smart Contract

A robust Clarity smart contract for automating periodic allowance distributions on the Stacks blockchain. Perfect for managing recurring payments, stipends, subscriptions, or automated transfers.

Overview

This contract enables sponsors to set up automated, time-based allowances for recipients. Recipients can claim their allowances at regular intervals without requiring manual approval from sponsors.

Key Features

Core Functionality

• Automated Distributions: Set up recurring allowances with custom amounts and frequencies
• Time-Based Claims: Recipients claim allowances based on block-height intervals
• Multi-Sponsor Support: Multiple sponsors can manage their own recipients independently
• Flexible Management: Update amounts, frequencies, or pause allowances anytime

Security Features

• Sponsor-only access control for allowance management
• Prevention of self-allowances
• Duplicate allowance protection
• Contract pause mechanism for emergencies
• Comprehensive error handling with 10 distinct error codes

Tracking & Analytics

• Complete claim history for each recipient
• Sponsor statistics (total sponsored, active recipients, distributed amounts)
• Global contract metrics
• Individual claim counts and timestamps

Contract Functions

Setup & Management

setup-allowance

(setup-allowance (recipient principal) (amount uint) (frequency uint))

Create a new allowance for a recipient.

• recipient: Address receiving the allowance
• amount: STX amount per claim (in microSTX)
• frequency: Blocks between claims (e.g., 144 blocks ≈ 1 day)
• Returns: (ok true) on success

update-allowance-amount

(update-allowance-amount (recipient principal) (new-amount uint))

Update the allowance amount. Only callable by the sponsor.

update-allowance-frequency

(update-allowance-frequency (recipient principal) (new-frequency uint))

Update the claim frequency. Only callable by the sponsor.

toggle-allowance-status

(toggle-allowance-status (recipient principal))

Activate or deactivate an allowance. Only callable by the sponsor.

remove-allowance

(remove-allowance (recipient principal))

Completely remove an allowance. Only callable by the sponsor.

Claiming

claim-allowance

(claim-allowance)

Claim your available allowance. Must be called by the recipient.

• Automatically checks if enough time has passed
• Transfers STX from sponsor to recipient
• Updates claim history and statistics
• Returns: (ok amount) on success

Read-Only Functions

get-allowance

Returns complete allowance details for a recipient.

is-claim-available

Check if a recipient can claim their allowance now.

get-time-until-claim

Get the number of blocks until the next claim is available.

get-sponsor-info

Retrieve statistics for a specific sponsor.

get-claim-history

Get historical claim data by recipient and index.

get-contract-stats

View global contract statistics.

Admin Functions (Contract Owner Only)

pause-contract

Pause all contract operations.

resume-contract

Resume contract operations after pause.

emergency-withdraw

Emergency STX withdrawal (owner only).

Usage Examples

Setting Up an Allowance

;; Set up a 100 STX allowance every 1000 blocks
(contract-call? .allowance-automation setup-allowance 
    'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7 
    u100000000  ;; 100 STX in microSTX
    u1000       ;; Every 1000 blocks
)

Claiming an Allowance

;; Recipient claims their allowance
(contract-call? .allowance-automation claim-allowance)

Checking Claim Availability

;; Check if claim is available
(contract-call? .allowance-automation is-claim-available 
    'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7
)

Updating Allowance Amount

;; Sponsor increases allowance to 150 STX
(contract-call? .allowance-automation update-allowance-amount 
    'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7 
    u150000000
)

Error Codes

Code	Constant	Description
u100	err-owner-only	Action requires contract owner
u101	err-not-found	Allowance not found
u102	err-insufficient-balance	Insufficient balance for transfer
u103	err-invalid-amount	Invalid amount (must be > 0)
u104	err-invalid-frequency	Invalid frequency (must be > 0)
u105	err-already-exists	Allowance already exists
u106	err-not-active	Allowance is not active
u107	err-too-early	Cannot claim yet
u108	err-invalid-recipient	Invalid recipient address
u109	err-paused	Contract is paused

Use Cases

1. Family Allowances: Parents can set up automatic weekly/monthly allowances for children
2. Employee Stipends: Companies can automate recurring stipend payments
3. Content Subscriptions: Creators can receive regular payments from subscribers
4. Grant Distributions: Organizations can automate periodic grant disbursements
5. Recurring Donations: Set up automated charitable contributions
6. Salary Payments: Automate regular salary distributions

Important Notes

• All amounts are in microSTX (1 STX = 1,000,000 microSTX)
• Frequency is measured in blocks (≈144 blocks per day on Stacks)
• Sponsors must have sufficient STX balance when recipients claim
• Recipients cannot claim before the specified frequency has elapsed
• Contract owner can pause all operations in emergencies
• Each sponsor manages their allowances independently

Security Considerations

• ✅ Only sponsors can modify their allowances
• ✅ Recipients cannot claim more frequently than specified
• ✅ Contract includes comprehensive input validation
• ✅ Emergency pause mechanism available
• ✅ No self-allowances permitted
• ✅ Complete audit trail of all claims

Testing Recommendations

1. Test allowance setup with various amounts and frequencies
2. Verify claim restrictions before frequency elapses
3. Test sponsor permission controls
4. Verify emergency pause functionality
5. Test edge cases (zero amounts, duplicate setups)
6. Verify proper STX transfers and balance checks

Contract Deployment

Deploy using Clarinet or Stacks CLI:

clarinet deploy