Deployment Guide for Finchippay-Solution Streaming Payment Contract

Overview

This guide provides step-by-step instructions for deploying the Finchippay-Solution streaming payment contract to the Stellar network and creating a pull request to the forked repository.

Prerequisites

Rust and Soroban SDK: Install Rust and add Soroban target

rustup target add wasm32v1-none
cargo install soroban-cli

Stellar Account: Have a funded Stellar account for deployment
Git: For version control and PR creation

Build Instructions

1. Build the Contract

# Navigate to project directory
cd Finchippay-Solution

# Build for WebAssembly target
cargo build --release --target wasm32v1-none

# The contract will be available at:
# target/wasm32v1-none/release/finchippay_contract.wasm

2. Run Tests

# Run all tests to verify implementation
cargo test

# Run specific test
cargo test test_open_stream

Contract Deployment

1. Setup Environment

# Set network (testnet or mainnet)
export STELLAR_NETWORK="testnet"

# Set contract parameters
export SOROBAN_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"

2. Deploy Contract

# Deploy the contract
soroban contract deploy \
  --wasm target/wasm32v1-none/release/finchippay_contract.wasm \
  --source <YOUR_STELLAR_SECRET_KEY> \
  --network $STELLAR_NETWORK

# Note the contract ID for future use

3. Initialize Contract (if needed)

# Initialize contract with any required parameters
soroban contract invoke \
  --id <CONTRACT_ID> \
  --source <YOUR_STELLAR_SECRET_KEY> \
  --network $STELLAR_NETWORK \
  -- function_name \
  --args ...

Usage Examples

Opening a Stream

soroban contract invoke \
  --id <CONTRACT_ID> \
  --source <PAYER_SECRET_KEY> \
  --network $STELLAR_NETWORK \
  open_stream \
  --args \
    "<PAYER_ADDRESS>" \
    "<RECIPIENT_ADDRESS>" \
    "1000" \
    "1000000"

Claiming from a Stream

soroban contract invoke \
  --id <CONTRACT_ID> \
  --source <RECIPIENT_SECRET_KEY> \
  --network $STELLAR_NETWORK \
  claim_stream \
  --args \
    "1" \
    "<RECIPIENT_ADDRESS>"

Topping Up a Stream

soroban contract invoke \
  --id <CONTRACT_ID> \
  --source <PAYER_SECRET_KEY> \
  --network $STELLAR_NETWORK \
  top_up_stream \
  --args \
    "1" \
    "<PAYER_ADDRESS>" \
    "500000"

Closing a Stream

soroban contract invoke \
  --id <CONTRACT_ID> \
  --source <PAYER_SECRET_KEY> \
  --network $STELLAR_NETWORK \
  close_stream \
  --args \
    "1" \
    "<PAYER_ADDRESS>"

Creating a Pull Request

1. Fork the Repository

Go to the original repository: https://github.com/FinChippay/Finchippay-Solution
Click "Fork" to create your own copy

Clone your fork locally:

git clone https://github.com/<YOUR_USERNAME>/Finchippay-Solution.git
cd Finchippay-Solution

2. Add Your Changes

Copy the implementation files to your local repository

Stage and commit your changes:

git add .
git commit -m "Implement streaming payment channels using Soroban"

3. Create Pull Request

Push to your fork:
```
git push origin main
```

Create a pull request on GitHub with:

Title: "Implement streaming payment channels using Soroban"

Description:

This PR implements streaming payment channels using Soroban smart contracts.

## Features Implemented
- ✅ Stream struct with all required fields (payer, recipient, rate_per_ledger, deposited, claimed, start_ledger)
- ✅ open_stream function for creating new payment streams
- ✅ claim_stream function for recipients to claim available funds
- ✅ top_up_stream function for adding more funds to existing streams
- ✅ close_stream function for stopping streams and refunding unstreamed portions
- ✅ Comprehensive test suite covering all functionality
- ✅ Proper authorization and validation checks
- ✅ Accurate claim calculations at any ledger offset

## Acceptance Criteria Met
- ✅ cargo test passes for all streaming tests
- ✅ Claim amount calculated correctly at any ledger offset
- ✅ Top-up increases the stream duration
- ✅ Close refunds the correct unclaimed amount
- ✅ Only the recipient can claim, only the payer can close

## Testing
All tests pass and cover edge cases including:
- Basic stream operations
- Multiple claims over time
- Deposit limits and overflow handling
- Authorization validation
- Error conditions

## Files Modified
- `contracts/finchippay-contract/src/lib.rs` - Main contract implementation
- `Cargo.toml` - Workspace configuration
- `contracts/finchippay-contract/Cargo.toml` - Contract dependencies
- `README.md` - Documentation
- `DEPLOYMENT_GUIDE.md` - Deployment instructions

Contract Features Summary

Core Functionality

Stream Creation: Create payment streams with custom rates and deposits
Claim Payments: Recipients can claim available funds based on ledger progression
Stream Management: Top-up existing streams or close them for refunds
Query Functions: Get stream information and calculate claimable amounts

Security Features

Authorization: Only designated recipients can claim, only payers can manage streams
Input Validation: Positive rates and deposits required
Overflow Protection: Safe arithmetic operations
Access Control: Proper authentication for all operations

Mathematical Accuracy

Ledger-based Calculation: Claims calculated using ledger progression
Deposit Limits: Cannot claim more than deposited amount
Refund Logic: Accurate refund calculations for unstreamed portions
Multiple Claims: Proper tracking of claimed amounts over time

Testing Coverage

The implementation includes 13 comprehensive test functions:

test_open_stream - Basic stream creation
test_claim_stream_basic - Single claim operation
test_claim_stream_multiple_times - Multiple claims over time
test_claim_stream_exceeds_deposit - Deposit limit enforcement
test_top_up_stream - Stream top-up functionality
test_close_stream_with_refund - Stream closure with refund
test_close_stream_after_claims - Closure after partial claims
test_get_claimable - Query claimable amount
test_claim_nonexistent_stream - Error handling for invalid streams
test_unauthorized_claim - Authorization for claims
test_unauthorized_close - Authorization for closures
test_invalid_rate - Input validation for rates
test_invalid_deposit - Input validation for deposits

Security Features (v2 Contract)

The FinchippayContract v2 includes:

Emergency pause: admin can freeze all value-transferring operations
Upgradability: admin can hot-patch the contract WASM without state migration
Deposit/timelock bounds: prevents griefing and permanent fund lock-up
Cumulative top-up caps: stream deposit limits enforced across top-ups
Version tracking: on-chain version counter incremented on each upgrade

Next Steps

Deploy to Testnet: Test the contract on Stellar testnet
Integration Testing: Test with real Stellar accounts
Security Audit: Review for potential vulnerabilities
Mainnet Deployment: Deploy to production after testing
Documentation: Create user guides and API documentation

Support

For questions or issues:

Review the contract implementation in lib.rs
Check the test cases for usage examples
Refer to Soroban documentation: https://docs.rs/soroban-sdk/latest/soroban_sdk/
Stellar documentation: https://developers.stellar.org/

FilesExpand file tree

DEPLOYMENT_GUIDE.md

Latest commit

History