Bitcoin Payment Streaming Protocol

A Clarity smart contract enabling continuous Bitcoin (STX) payments over time on the Stacks blockchain. Stream payments to recipients who can withdraw funds as they accrue, with full cancellation and refund capabilities.

Overview

This protocol allows users to create payment streams that distribute funds continuously over a specified duration. Recipients can withdraw earned funds at any time, and senders can cancel streams to recover unstreamed amounts.

Key Features

• Continuous Payment Streams: Distribute payments block-by-block over any duration
• Flexible Withdrawals: Recipients withdraw anytime without waiting for stream completion
• Cancellation & Refunds: Senders can cancel and recover unstreamed funds
• Batch Operations: Withdraw from multiple streams in a single transaction
• Stream Top-ups: Add more funds to existing active streams
• Tracking & Analytics: Monitor stream progress, status, and withdrawal history
• Protocol Fees: Built-in fee mechanism (1% default) for protocol sustainability

Core Functions

Creating Streams

(create-stream recipient total-amount duration)

• recipient: Principal address receiving the stream
• total-amount: Total STX to stream (minimum: 1,000 micro-STX)
• duration: Stream length in blocks (minimum: 1 block)
• Returns: Stream ID
• Fee: 1% of total amount (adjustable by contract owner)

Withdrawing Funds

(withdraw stream-id)

• Withdraws all earned funds up to current block
• Only callable by stream recipient
• Calculates earnings based on elapsed blocks × rate-per-block

Batch Withdrawals

(batch-withdraw (list stream-id-1 stream-id-2 ...))

• Withdraw from up to 20 streams simultaneously
• Failed withdrawals return 0, successful ones return amount

Cancelling Streams

(cancel-stream stream-id)

• Only callable by stream sender
• Transfers earned amount to recipient
• Refunds unstreamed amount to sender
• Cannot cancel already-completed streams

Top-up Streams

(top-up-stream stream-id additional-amount)

• Add more funds to active stream
• Only callable by original sender
• Subject to protocol fee

Read-Only Functions

Get Stream Details

(get-stream stream-id)

Returns complete stream information including sender, recipient, amounts, blocks, and status.

Calculate Withdrawable Amount

(calculate-withdrawable stream-id)

Returns exact amount available for withdrawal at current block.

Get Stream Status

(get-stream-status stream-id)

Returns:

• active: Boolean indicating if stream is currently active
• progress: Completion percentage (0-10000 basis points)
• withdrawn-percent: Percentage of total amount withdrawn

List User Streams

(get-user-streams principal)
(get-recipient-streams principal)

Returns list of stream IDs for sender or recipient.

Payment Calculation

Streams distribute funds linearly:

Amount per block = Total Amount ÷ Duration
Earned Amount = Blocks Elapsed × Amount per Block
Withdrawable = Earned Amount - Already Withdrawn

Example:

• Total: 100,000 STX
• Duration: 1,000 blocks
• Rate: 100 STX/block
• After 250 blocks: 25,000 STX earned

Error Codes

Code	Error	Description
u100	ERR_UNAUTHORIZED	Caller not authorized for action
u101	ERR_STREAM_NOT_FOUND	Stream ID doesn't exist
u102	ERR_INSUFFICIENT_BALANCE	Not enough balance for operation
u103	ERR_INVALID_PARAMS	Invalid input parameters
u104	ERR_STREAM_ENDED	Stream already completed
u105	ERR_STREAM_CANCELLED	Stream was cancelled
u106	ERR_NOTHING_TO_WITHDRAW	No funds available to withdraw
u107	ERR_ALREADY_EXISTS	Resource already exists

Usage Examples

Create a 30-day salary stream

;; Stream 30,000 STX over ~30 days (4,320 blocks at 10min/block)
(contract-call? .payment-stream create-stream 
  'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7
  u30000000000  ;; 30,000 STX in micro-STX
  u4320)        ;; ~30 days

Withdraw earned funds

(contract-call? .payment-stream withdraw u0)

Cancel and refund

(contract-call? .payment-stream cancel-stream u0)

Security Considerations

1. Authorization: All state-changing functions verify caller identity
2. Input Validation: Minimum amounts and durations enforced
3. Safe Math: Prevents overflow/underflow in calculations
4. Atomic Operations: State updates occur atomically with transfers
5. No Reentrancy: Uses Clarity's built-in protection mechanisms

Admin Functions

Contract owner can:

• Update protocol fee (max 10%): (update-protocol-fee new-fee)
• Withdraw collected fees: (withdraw-fees)

Limitations

• Maximum 100 streams per user/recipient (list size limit)
• Maximum 20 streams in batch operations
• Minimum stream amount: 1,000 micro-STX
• Minimum duration: 1 block

Use Cases

• Payroll: Stream employee salaries continuously
• Subscriptions: Pay for services over time
• Vesting: Token or payment vesting schedules
• Grants: Distribute funding progressively
• Rent/Leases: Automated recurring payments
• Freelance: Milestone-based continuous payments