Documentation
Introduction
Spare is an open-source kit that lets any Stellar app offer a per-transaction USDC donation at signing time. The donation goes straight to the foundation. Spare never holds funds and takes no cut.
Why
At Chilean pharmacies and supermarkets the cashier asks “¿Dona su vuelto?”: would you like to donate your change? Small amounts add up to real money for foundations. On Stellar, fees are low enough to make a US$0.50 donation worth sending, but no package lets an existing app add one at signing time.
How it works
Before the user signs, your app asks “Add US$0.50 for [foundation]?” or “Round up to the next dollar?”. If they say yes, the donation rides along with their payment.
| Transaction type | What Spare does | Signatures |
|---|---|---|
| Classic (payments, path payments, any classic operation) | Appends a USDC payment to the foundation in the same transaction. Purchase and donation succeed or fail together. | One |
Soroban (InvokeHostFunction) | A Soroban transaction can hold only one operation, so Spare sends a tagged follow-up payment after the call succeeds. The modal says so before the user accepts. | Two |
| Ledger (via Stellar Wallets Kit) | The donation is its own payment operation, so the device shows “Payment 0.50 USDC to …” before approval. | One |
Every Spare donation carries the memo spare:<appId>, so it is traceable on-chain and attributable to the app that sent it.
Foundations verify themselves with a Stellar standard: a foundation registers its account in the Spare registry contract and lists the same account in the ACCOUNTS field of its website's stellar.toml (SEP-1). Nobody approves it by hand.
Guarantees
- The user always decides. Nothing is added without an explicit yes. Declining signs the original transaction, byte for byte.
- No custody. Funds go from the user to the foundation in a normal Stellar payment.
- Circle USDC only (
GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN). Look-alike assets are rejected. - Domain-verified foundations only. “Domain-verified” means the account is listed on that website's
stellar.toml, nothing more. - Never blocks a payment. If a check fails (no trustline, low balance, over your cap, unverified foundation) no donation is offered. If anything inside Spare errors, the original transaction is signed.
- Safe pass-through. Partly signed, multisig, fee-bump and Soroban transactions are never modified.
- Private by design. The public dashboard aggregates by app and foundation and never lists donor addresses.
Packages
| Package | Description | Status |
|---|---|---|
spare-sdk | Core TypeScript library: classic bundling, Soroban follow-up, eligibility checks, stellar.toml verification. | Built |
spare-wallets-kit | Stellar Wallets Kit wrapper with an accessible confirmation modal (EN/ES, light/dark). | Built |
| Registry contract | Soroban foundation registry. No admin, no upgrade function, no funds. | Built, not deployed |
| Indexer and dashboard | Registry events and tagged USDC payments, shown per foundation. | Planned |
Out of scope
Pooling or splitting donations, choosing or vetting charities, tax receipts, fiat on/off-ramps, and browser extensions that modify other wallets' transactions.