spare-sdk

Instalar

pnpm add spare-sdk @stellar/stellar-sdk

@stellar/stellar-sdk es una peer dependency: instálala junto a spare-sdk (una sola copia compartida con tu app).

Transacción clásica: addDonation

import { addDonation, HorizonAccountPort } from "spare-sdk";

const result = await addDonation(unsignedTx, {
  foundation: { account: "G...", domain: "foundation.org" }, // must be listed in its stellar.toml
  amount: "0.50",            // or: roundUp: true (only when the purchase is USDC)
  appId: "my-app",           // <= 22 ASCII bytes, memo becomes "spare:my-app"
  maxAmount: "5",            // your cap per donation
  accounts: new HorizonAccountPort("https://horizon.stellar.org"),
});

switch (result.status) {
  case "offered":      // ask the user "Add US$<result.donation.amount>?", then sign result.transaction
  case "not-offered":  // sign the original tx; result.reason says why (e.g. "insufficient-balance")
  case "passthrough":  // signed / fee-bump / multisig / extra signers / Soroban: sign the original tx
}

offered devuelve una transacción nueva sin firmar (hash nuevo, comisión subida en una operación, memo puesto solo si estaba vacío y ningún destino exige uno). No se agrega nada sin el sí explícito de la persona.

Redondeo

Solo cuando toda la transacción es una compra en USDC de Circle (pagos, pathPaymentStrictSend, ofertas de venta). El SDK informa lo que usó, así que muestra estos valores en vez de recalcular: donation.purchase / purchaseStroops (la compra en USDC) y roundedTotal / roundedTotalStroops (compra más donación). Solo vienen definidos en el redondeo.

• Ya es entero (por ejemplo 5.00): round-up-already-whole.
• pathPaymentStrictReceive, operaciones en XLM u otro activo, o operaciones no modeladas en la misma transacción: round-up-needs-usdc-purchase (el gasto real no se conoce de antemano, así que Spare nunca redondea sendMax).

Llamada Soroban: donateAfter

Una transacción Soroban tiene una sola operación, así que la donación es un pago aparte después del éxito. Necesita una segunda firma: avísale a la persona antes de que acepte.

import { donateAfter } from "spare-sdk";

const follow = await donateAfter(
  { successful: true, sourceAccount: userAccount, hash },
  { foundation, amount: "0.50", appId: "my-app", maxAmount: "5",
    accounts, networkPassphrase: Networks.PUBLIC },
);
if (follow.status === "offered") { /* confirm, then sign follow.transaction */ }

El seguimiento es un único pago (umbral medio). Si la cuenta de la persona necesita más que su llave maestra para firmarlo, no se ofrece nada (multisig).

Resultados y códigos de motivo

Motivos de passthrough

Motivos de not-offered

DonationInfo

Opciones

Puerto de cuenta

AccountPort.loadAccount(id) devuelve un AccountSnapshot, o null cuando la cuenta no existe. HorizonAccountPort lo llena desde Horizon (headroom = límite - saldo - pasivos de compra; memoRequired desde la entrada de datos config.memo_required). Spare decide sobre múltiples firmas con masterWeight y thresholds por transacción.

Memo, SEP-29 y comisiones

Si el destino de un pago, pago con ruta o merge tiene config.memo_required, Spare no pone su memo, así que el checkMemoRequired de tu app sigue funcionando. La donación igual se ofrece, con donation.attributed === false. Un destino que no se puede leer se trata como memo requerido.

baseFee es por operación, solo dígitos, mínimo 100 stroops. Un valor mal formado da not-offered / invalid-options; nunca lanza error. Una transacción con comisión 0 sube a 100 por operación, y el mismo número se usa para la revisión de saldo y para la transacción construida.

Utilidades

• verifyFoundation(foundation) y listVerifiedFoundations(candidates): la revisión SEP-1 de ACCOUNTS (solo https, sin redirecciones, 5 s de timeout, cuerpo limitado a 100 KB).
• parseUsdc, formatStroops, roundUpToWholeDollar: utilidades de montos.
• isValidAppId, memoFor: validación del app id y el memo.
• USDC_ISSUER, USDC_CODE: las constantes de USDC de Circle.
• El acceso a la red (fetch, AccountPort) es inyectable.