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.

CIRustSorobanLicense: 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

FunctionDescription
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:

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]fnpay_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.