Skip to content

README.md

Latest commit

 

History

History
133 lines (104 loc) · 4.97 KB

README.md

File metadata and controls

133 lines (104 loc) · 4.97 KB
Raw

stackpay-contracts 🪨

Soroban smart contracts that power StackPay — on-chain payment requests, escrowed settlement, and payment proofs on Stellar.

CI Rust Soroban License: MIT

This is the on-chain layer of StackPay, written in Rust and compiled to WebAssembly for Soroban.

Table of contents

Why StackPay

Stellar is one of the best networks for moving money — but the ecosystem has no simple, standard way to request a payment and prove it settled. Sending is easy; asking someone to pay you (an invoice, a donation, a subscription, a split) still means copy-pasting addresses and hoping.

StackPay adds that missing primitive:

  • A payment request is a tiny on-chain record: who's owed, what asset, how much, and a memo.
  • The payer pays; the contract settles and records a payment proof.
  • The requester shares one link; the payer pays from any Stellar wallet.

Use cases: freelancer invoices, creator tips, DAO bounty payouts, event tickets, donation jars — all natively on Stellar.

Architecture

 requester ──create_request──▶  PaymentRequest (Soroban)
                                      │ emits RequestCreated
                                      ▼
 payer ─────────pay──────────▶  contract pulls asset (token transfer)
                                      │ emits RequestPaid  (payment proof)
                                      ▼
                            stackpay-backend (indexes events)
                                      │
                                      ▼
                            stackpay-frontend (dApp: links, status)
  • PaymentRequest holds requests and performs the asset transfer via the Stellar Asset Contract (SAC) token client.
  • Events are indexed off-chain by stackpay-backend and surfaced in the dApp.

Contract: PaymentRequest

Function Description
create_request(payee, asset, amount, memo, expires_in) Create a new request; returns request_id.
pay(request_id) Payer transfers amount of asset to payee; marks Paid, emits RequestPaid.
cancel(request_id) Requester cancels an unpaid, unexpired request.
get_request(request_id) View: full request state.
status(request_id) View: Open / Paid / Cancelled / Expired.

All amounts use Stroops (7 decimals) for XLM and the asset's own decimals. asset is the Stellar Asset Contract address for the asset being requested.

Core concepts

  • Request — { id, payee, asset, amount, memo, status, created_at, expires_at }.
  • Payment proof — once pay succeeds, the RequestPaid event + on-chain Paid status is the immutable receipt.
  • Expiry — requests can auto-expire; only unpaid, unexpired requests are payable.

Getting started

Prerequisites:

  • Rust with wasm32-unknown-unknown.
  • Stellar CLI (includes Soroban support):
rustup target add wasm32-unknown-unknown

Clone & build:

git clone https://github.com/Stack-Rocks/stackpay-contracts.git
cd stackpay-contracts
make build

Building

make build        # -> target/wasm32-unknown-unknown/release/stackpay_contracts.wasm
make optimize     # smaller wasm

Testing

Unit tests use soroban-sdk testutils (in-memory ledger):

make test

Example:

#[test]
fn pay_marks_paid() {
    // create request, pay with token client, assert status == Paid
}

Local network

stellar network container start        # local sandbox
stellar contract deploy --wasm target/.../stackpay_contracts.wasm --network local

Deployment

  1. Build + optimize wasm.
  2. Deploy to Testnet for staging, then Mainnet.
  3. Publish the contract id to stackpay-backend via its .env.

Security

  • Asset transfers use the official SAC token client (no custom token logic).
  • require_auth on every state-changing call.
  • Intended for audit before mainnet (see docs/security.md, WIP).

Contributing

Part of the Stellar Wave Program on Drips. Look for Stellar Wave / Good first issue labels. Run make test && make lint before a PR.

License

MIT.