Documentación
Introducción
Spare es un kit de código abierto para que cualquier app de Stellar ofrezca una donación en USDC por transacción al momento de firmar. La donación va directo a la fundación. Spare nunca retiene fondos y no cobra comisión.
Por qué
En las farmacias y supermercados de Chile la persona en caja pregunta “¿Dona su vuelto?”. Los montos chicos suman plata real para las fundaciones. En Stellar las comisiones son tan bajas que vale la pena enviar una donación de US$0,50, pero ningún paquete permite que una app existente la sume al firmar.
Cómo funciona
Antes de firmar, tu app pregunta “¿Sumar US$0,50 para [fundación]?” o “¿Redondear al próximo dólar?”. Si la persona dice que sí, la donación viaja junto con su pago.
| Tipo de transacción | Qué hace Spare | Firmas |
|---|---|---|
| Clásica (pagos, pagos con ruta, cualquier operación clásica) | Agrega un pago en USDC a la fundación en la misma transacción. La compra y la donación resultan bien o fallan juntas. | Una |
Soroban (InvokeHostFunction) | Una transacción Soroban solo puede tener una operación, así que Spare envía un pago de seguimiento etiquetado cuando la llamada resulta bien. El modal lo avisa antes de que la persona acepte. | Dos |
| Ledger (con Stellar Wallets Kit) | La donación es su propia operación de pago, así que el dispositivo muestra “Payment 0.50 USDC to …” antes de aprobar. | Una |
Cada donación de Spare lleva el memo spare:<appId>, así que se puede rastrear en la cadena y atribuir a la app que la envió.
Las fundaciones se verifican solas con un estándar de Stellar: la fundación registra su cuenta en el contrato de registro de Spare y lista la misma cuenta en el campo ACCOUNTS del stellar.toml de su sitio (SEP-1). Nadie lo aprueba a mano.
Garantías
- La persona siempre decide. No se agrega nada sin un sí explícito. Si dice que no, se firma la transacción original, byte por byte.
- Sin custodia. Los fondos van de la persona a la fundación en un pago normal de Stellar.
- Solo USDC de Circle (
GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN). Los activos parecidos se rechazan. - Solo fundaciones con dominio verificado. “Dominio verificado” significa que la cuenta está listada en el
stellar.tomlde ese sitio, nada más. - Nunca bloquea un pago. Si falla una verificación (sin trustline, saldo bajo, sobre tu tope, fundación sin verificar) no se ofrece donación. Si algo dentro de Spare da error, se firma la transacción original.
- Paso directo seguro. Las transacciones parcialmente firmadas, multisig, fee-bump y Soroban nunca se modifican.
- Privado por diseño. El tablero público agrega por app y por fundación y nunca lista direcciones de donantes.
Paquetes
| Paquete | Descripción | Estado |
|---|---|---|
spare-sdk | Biblioteca TypeScript central: agrupación en transacciones clásicas, seguimiento Soroban, revisiones de elegibilidad, verificación de stellar.toml. | Listo |
spare-wallets-kit | Envoltorio de Stellar Wallets Kit con un modal de confirmación accesible (EN/ES, claro/oscuro). | Listo |
| Contrato de registro | Registro de fundaciones en Soroban. Sin admin, sin función de actualización, sin fondos. | Listo, sin desplegar |
| Indexador y tablero | Eventos del registro y pagos USDC etiquetados, mostrados por fundación. | Planificado |
Fuera de alcance
Juntar o dividir donaciones, elegir o evaluar causas, recibos tributarios, rampas de entrada y salida de dinero fiat, y extensiones de navegador que modifiquen las transacciones de otras wallets.