spare-sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesús Chávez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# spare-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Add a per-transaction USDC micro-donation to any Stellar app. The donation goes straight to the foundation's account; Spare never holds funds. Circle USDC only, domain-verified foundations only.
+
+```
+pnpm add spare-sdk @stellar/stellar-sdk
+```
+
+## Classic transaction: `addDonation`
+
+```ts
+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` returns a new unsigned tx (new hash, fee raised by one operation, memo set only if it was empty and no destination requires one). Nothing is added without the user's explicit yes.
+
+`@stellar/stellar-sdk` is a peer dependency: install it next to `spare-sdk` (one copy shared with your app).
+
+### Round-up
+
+Only when the whole tx is a Circle-USDC purchase (payments, `pathPaymentStrictSend`, sell offers). The SDK reports what it used, so show these instead of recomputing: `result.donation.purchase` / `purchaseStroops` (the USDC purchase) and `roundedTotal` / `roundedTotalStroops` (purchase + donation). They are set on round-up only.
+
+- Already whole (e.g. 5.00): `round-up-already-whole`.
+- `pathPaymentStrictReceive`, XLM or other-asset ops, or unmodelled ops in the same tx: `round-up-needs-usdc-purchase` (the real spend is unknown up front, so Spare never rounds `sendMax`).
+
+### Reason codes
+
+`passthrough` (tx untouched): `fee-bump`, `already-signed`, `soroban`, `multiple-sources`, `multisig` (the master key alone cannot meet the tx's threshold: medium, or high with `setOptions`/`accountMerge`), `extra-signers` (CAP-21 `extraSigners` precondition).
+
+`not-offered`: `invalid-options` (incl. malformed `baseFee`), `invalid-app-id`, `invalid-amount`, `invalid-foundation`, `amount-over-cap`, `round-up-needs-usdc-purchase`, `round-up-already-whole`, `foundation-not-verified`, `foundation-trustline-missing`, `foundation-trustline-unauthorized`, `foundation-trustline-full` (no room under the trustline limit), `user-trustline-missing`, `user-trustline-unauthorized`, `unsupported-operation` (the tx has ops that can spend funds in ways Spare does not model, e.g. `manageBuyOffer`, `createClaimableBalance`, `liquidityPoolDeposit`, `accountMerge`), `insufficient-balance` (USDC, or XLM for the fee plus any XLM the tx sends), `account-lookup-failed`, `main-tx-not-successful`, and, from `donateAfter` only, `multisig`.
+
+### Memo and SEP-29
+
+If a payment, path payment or merge destination has `config.memo_required` set, Spare does not set its memo, so your app's own `checkMemoRequired` still fires. The donation is still offered, with `donation.attributed === false`. A destination that cannot be read is treated as memo-required.
+
+### Fees
+
+`baseFee` is per operation, digits only, minimum 100 stroops. A malformed value gives `not-offered` / `invalid-options`; it never throws. A tx with a fee of 0 is raised to 100 per operation, and the same number is used for the balance check and the built tx.
+
+## Soroban call: `donateAfter`
+
+A Soroban tx holds one operation, so the donation is a separate payment after success. It needs a second signature: tell the user before they accept.
+
+```ts
+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 */ }
+```
+
+The follow-up is a single payment (medium threshold). If the user's account needs more than its master key to sign that, nothing is offered (`multisig`).
+
+## Account port
+
+`AccountPort.loadAccount(id)` returns an `AccountSnapshot`: `sequence`, `xlmAvailable`, `usdc` (`{ balance, authorized, headroom }` or `null`), `masterWeight`, `thresholds` (`{ low, medium, high }`) and `memoRequired`. `HorizonAccountPort` fills it from Horizon (`headroom` = limit - balance - buying liabilities; `memoRequired` from the `config.memo_required` data entry). `requiresMultipleSignatures` is gone: Spare decides from `masterWeight` and `thresholds` per transaction.
+
+## Helpers
+
+`verifyFoundation(foundation)`, `listVerifiedFoundations(candidates)` (SEP-1 `ACCOUNTS` check: https only, no redirects, 5 s timeout, body capped at 100 KB), `parseUsdc`, `formatStroops`, `roundUpToWholeDollar`. Network access (`fetch`, `AccountPort`) is injectable.

package/dist/add-donation.d.ts

@@ -0,0 +1,15 @@
+import { FeeBumpTransaction, Transaction } from "@stellar/stellar-sdk";
+import type { CommonOptions, DonationResult } from "./types.js";
+/** Provide exactly one of `amount` (fixed USDC) or `roundUp: true` (USDC purchases only). */
+export type AddDonationOptions = CommonOptions & {
+    amount?: string;
+    roundUp?: boolean;
+};
+/**
+ * Appends a USDC donation to an unsigned classic tx, if (and only if) every check passes.
+ * Never throws for ineligible input: inspect `status`.
+ *  - "offered": `transaction` is a new unsigned tx (new hash, higher fee); show `donation.amount` to the user.
+ *  - "not-offered": tx is fine, but no donation should be shown. Use the original.
+ *  - "passthrough": Spare cannot safely modify this tx. Use the original.
+ */
+export declare function addDonation(tx: Transaction | FeeBumpTransaction, opts: AddDonationOptions): Promise<DonationResult>;

package/dist/add-donation.js

@@ -0,0 +1,143 @@
+import { Asset, FeeBumpTransaction, Memo, Operation, TransactionBuilder, } from "@stellar/stellar-sdk";
+import { formatStroops, parseUsdc, roundUpToWholeDollar, toStroops } from "./amount.js";
+import { memoFor } from "./app-id.js";
+import { USDC_CODE, USDC_ISSUER } from "./constants.js";
+import { checkEligibility } from "./eligibility.js";
+import { perOpFee } from "./fee.js";
+import { canSignAlone, requiredThreshold } from "./signing.js";
+import { analyzeSpend } from "./spend.js";
+const SOROBAN_OPS = new Set(["invokeHostFunction", "extendFootprintTtl", "restoreFootprint"]);
+/** Why Spare must not touch this tx, or null when it is an unsigned, single-source classic tx. */
+function structuralPassthrough(tx) {
+    if (tx instanceof FeeBumpTransaction)
+        return "fee-bump";
+    if (tx.signatures.length > 0)
+        return "already-signed";
+    if (tx.extraSigners && tx.extraSigners.length > 0)
+        return "extra-signers"; // CAP-21 precondition
+    if (tx.operations.some((op) => SOROBAN_OPS.has(op.type)))
+        return "soroban";
+    if (tx.operations.some((op) => op.source !== undefined && op.source !== tx.source))
+        return "multiple-sources";
+    return null;
+}
+/** Destinations that receive funds from the tx: where a SEP-29 memo may be required. */
+function destinations(ops) {
+    const out = new Set();
+    for (const op of ops) {
+        if (op.type === "payment" || op.type === "pathPaymentStrictSend" ||
+            op.type === "pathPaymentStrictReceive" || op.type === "accountMerge")
+            out.add(op.destination);
+    }
+    return [...out];
+}
+/**
+ * True unless every destination is known not to require a memo (SEP-29). Fails closed: a
+ * destination we cannot read counts as requiring one. A missing account does not.
+ */
+async function anyMemoRequired(accounts, ops) {
+    const checks = await Promise.all(destinations(ops).map(async (d) => {
+        try {
+            return (await accounts.loadAccount(d))?.memoRequired === true;
+        }
+        catch {
+            return true;
+        }
+    }));
+    return checks.some(Boolean);
+}
+/**
+ * Appends a USDC donation to an unsigned classic tx, if (and only if) every check passes.
+ * Never throws for ineligible input: inspect `status`.
+ *  - "offered": `transaction` is a new unsigned tx (new hash, higher fee); show `donation.amount` to the user.
+ *  - "not-offered": tx is fine, but no donation should be shown. Use the original.
+ *  - "passthrough": Spare cannot safely modify this tx. Use the original.
+ */
+export async function addDonation(tx, opts) {
+    const pass = structuralPassthrough(tx);
+    if (pass)
+        return { status: "passthrough", reason: pass, transaction: tx };
+    const t = tx;
+    const no = (reason) => ({ status: "not-offered", reason, transaction: t });
+    if ((opts.amount === undefined) === (opts.roundUp !== true))
+        return no("invalid-options");
+    const feeFallback = (BigInt(t.fee) + BigInt(t.operations.length) - 1n) / BigInt(t.operations.length);
+    const perOp = perOpFee(opts.baseFee, feeFallback);
+    if (perOp === null)
+        return no("invalid-options");
+    const spend = analyzeSpend(t.operations);
+    if (spend.unsupported)
+        return no("unsupported-operation");
+    let amount;
+    if (opts.roundUp === true) {
+        if (spend.other || spend.uncertain || spend.usdc === 0n)
+            return no("round-up-needs-usdc-purchase");
+        amount = roundUpToWholeDollar(spend.usdc);
+        if (amount === 0n)
+            return no("round-up-already-whole");
+    }
+    else {
+        amount = parseUsdc(opts.amount);
+        if (amount === null)
+            return no("invalid-amount");
+    }
+    let user;
+    try {
+        user = await opts.accounts.loadAccount(t.source);
+    }
+    catch {
+        return no("account-lookup-failed");
+    }
+    if (!user)
+        return no("account-lookup-failed");
+    if (!canSignAlone(user, requiredThreshold(t.operations)))
+        return { status: "passthrough", reason: "multisig", transaction: t };
+    // Fee: one extra operation at the tx's own per-op rate (ceil, min 100), unless overridden.
+    const newFee = perOp * (BigInt(t.operations.length) + 1n);
+    const reason = await checkEligibility({
+        accounts: opts.accounts,
+        ...(opts.fetch && { fetch: opts.fetch }),
+        foundation: opts.foundation,
+        appId: opts.appId,
+        amount,
+        cap: toStroops(opts.maxAmount),
+        source: t.source,
+        user,
+        usdcSpend: spend.usdc,
+        fee: newFee,
+        xlmSpend: spend.xlm,
+    });
+    if (reason)
+        return no(reason);
+    // Our memo would bypass a destination's SEP-29 memo_required check: leave the memo unset so
+    // the app's own checkMemoRequired still fires.
+    const attributed = t.memo.type === "none" && !(await anyMemoRequired(opts.accounts, t.operations));
+    const builder = TransactionBuilder.cloneFrom(t, {
+        fee: perOp.toString(),
+        ...(attributed && { memo: Memo.text(memoFor(opts.appId)) }),
+    });
+    builder.addOperation(Operation.payment({
+        destination: opts.foundation.account,
+        asset: new Asset(USDC_CODE, USDC_ISSUER),
+        amount: formatStroops(amount),
+    }));
+    const out = builder.build();
+    return {
+        status: "offered",
+        transaction: out,
+        fee: BigInt(out.fee),
+        donation: {
+            amount: formatStroops(amount),
+            amountStroops: amount,
+            foundation: opts.foundation.account,
+            attributed,
+            ...(opts.roundUp === true && {
+                purchase: formatStroops(spend.usdc),
+                purchaseStroops: spend.usdc,
+                roundedTotal: formatStroops(spend.usdc + amount),
+                roundedTotalStroops: spend.usdc + amount,
+            }),
+        },
+    };
+}
+//# sourceMappingURL=add-donation.js.map

package/dist/add-donation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-donation.js","sourceRoot":"","sources":["../src/add-donation.ts"],"names":[],"mappings":"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"}

package/dist/amount.d.ts

@@ -0,0 +1,11 @@
+/** Decimal string ("0.5", up to 7 decimals) to stroops. No floats. Returns null if malformed. */
+export declare function toStroops(s: string): bigint | null;
+/** Like {@link toStroops} but also rejects zero: a donation must be positive. */
+export declare function parseUsdc(s: string): bigint | null;
+/** Stroops to the 7-decimal string Stellar operations expect. */
+export declare function formatStroops(v: bigint): string;
+/**
+ * Gap between `purchase` and the next whole dollar.
+ * A purchase that is already a whole dollar yields 0n (no donation); we never default to a full $1.
+ */
+export declare function roundUpToWholeDollar(purchase: bigint): bigint;

package/dist/amount.js

@@ -0,0 +1,30 @@
+import { MAX_STROOPS, STROOPS_PER_UNIT } from "./constants.js";
+const AMOUNT_RE = /^\d+(\.\d{1,7})?$/;
+/** Decimal string ("0.5", up to 7 decimals) to stroops. No floats. Returns null if malformed. */
+export function toStroops(s) {
+    if (!AMOUNT_RE.test(s))
+        return null;
+    const [int = "0", frac = ""] = s.split(".");
+    const v = BigInt(int) * STROOPS_PER_UNIT + BigInt(frac.padEnd(7, "0"));
+    return v > MAX_STROOPS ? null : v;
+}
+/** Like {@link toStroops} but also rejects zero: a donation must be positive. */
+export function parseUsdc(s) {
+    const v = toStroops(s);
+    return v === null || v === 0n ? null : v;
+}
+/** Stroops to the 7-decimal string Stellar operations expect. */
+export function formatStroops(v) {
+    const int = v / STROOPS_PER_UNIT;
+    const frac = (v % STROOPS_PER_UNIT).toString().padStart(7, "0");
+    return `${int}.${frac}`;
+}
+/**
+ * Gap between `purchase` and the next whole dollar.
+ * A purchase that is already a whole dollar yields 0n (no donation); we never default to a full $1.
+ */
+export function roundUpToWholeDollar(purchase) {
+    const rem = purchase % STROOPS_PER_UNIT;
+    return rem === 0n ? 0n : STROOPS_PER_UNIT - rem;
+}
+//# sourceMappingURL=amount.js.map

package/dist/amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.js","sourceRoot":"","sources":["../src/amount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE/D,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC,iGAAiG;AACjG,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,CAAC,GAAG,GAAG,GAAG,EAAE,IAAI,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACvE,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IACvB,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,CAAS;IACrC,MAAM,GAAG,GAAG,CAAC,GAAG,gBAAgB,CAAC;IACjC,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAChE,OAAO,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,MAAM,GAAG,GAAG,QAAQ,GAAG,gBAAgB,CAAC;IACxC,OAAO,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,GAAG,GAAG,CAAC;AAClD,CAAC"}

package/dist/app-id.d.ts

@@ -0,0 +1,3 @@
+/** 1-22 printable ASCII chars (no spaces) so `spare:<appId>` fits a 28-byte text memo. */
+export declare function isValidAppId(appId: string): boolean;
+export declare function memoFor(appId: string): string;

package/dist/app-id.js

@@ -0,0 +1,9 @@
+import { MAX_APP_ID_BYTES, MEMO_PREFIX } from "./constants.js";
+/** 1-22 printable ASCII chars (no spaces) so `spare:<appId>` fits a 28-byte text memo. */
+export function isValidAppId(appId) {
+    return appId.length <= MAX_APP_ID_BYTES && /^[\x21-\x7E]+$/.test(appId);
+}
+export function memoFor(appId) {
+    return `${MEMO_PREFIX}${appId}`;
+}
+//# sourceMappingURL=app-id.js.map

package/dist/app-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-id.js","sourceRoot":"","sources":["../src/app-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE/D,0FAA0F;AAC1F,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,KAAK,CAAC,MAAM,IAAI,gBAAgB,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,GAAG,WAAW,GAAG,KAAK,EAAE,CAAC;AAClC,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+/** Circle's USDC issuer on Stellar. Spare accepts no other USDC. */
+export declare const USDC_ISSUER = "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN";
+export declare const USDC_CODE = "USDC";
+export declare const STROOPS_PER_UNIT = 10000000n;
+/** Stellar's max int64 amount, in stroops. */
+export declare const MAX_STROOPS = 9223372036854775807n;
+export declare const MEMO_PREFIX = "spare:";
+export declare const MAX_APP_ID_BYTES = 22;
+export declare const DEFAULT_BASE_FEE = "100";
+export declare const MIN_BASE_FEE = 100n;
+/** SEP-1: stellar.toml must not exceed 100KB. */
+export declare const MAX_TOML_BYTES: number;

package/dist/constants.js

@@ -0,0 +1,13 @@
+/** Circle's USDC issuer on Stellar. Spare accepts no other USDC. */
+export const USDC_ISSUER = "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN";
+export const USDC_CODE = "USDC";
+export const STROOPS_PER_UNIT = 10000000n;
+/** Stellar's max int64 amount, in stroops. */
+export const MAX_STROOPS = 9223372036854775807n;
+export const MEMO_PREFIX = "spare:";
+export const MAX_APP_ID_BYTES = 22; // 28-byte text memo minus "spare:"
+export const DEFAULT_BASE_FEE = "100";
+export const MIN_BASE_FEE = 100n;
+/** SEP-1: stellar.toml must not exceed 100KB. */
+export const MAX_TOML_BYTES = 100 * 1024;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,CAAC,MAAM,WAAW,GAAG,0DAA0D,CAAC;AACtF,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC;AAEhC,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAW,CAAC;AAC5C,8CAA8C;AAC9C,MAAM,CAAC,MAAM,WAAW,GAAG,oBAA0B,CAAC;AAEtD,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AACpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC,CAAC,mCAAmC;AACvE,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AACtC,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AACjC,iDAAiD;AACjD,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,GAAG,IAAI,CAAC"}

package/dist/donate-after.d.ts

@@ -0,0 +1,33 @@
+import { Transaction } from "@stellar/stellar-sdk";
+import type { CommonOptions, DonationInfo, NotOfferedReason } from "./types.js";
+/** Outcome of the user's main (Soroban) transaction. */
+export interface MainTxResult {
+    successful: boolean;
+    /** Account that signed the main tx and will pay the donation. */
+    sourceAccount: string;
+    hash?: string;
+}
+export type DonateAfterOptions = CommonOptions & {
+    /** Fixed amount in USDC. Round-up is not available on this path. */
+    amount: string;
+    networkPassphrase: string;
+    /** Seconds the follow-up tx stays valid. Default 300. */
+    timeoutSeconds?: number;
+};
+export type DonateAfterResult = {
+    status: "offered";
+    transaction: Transaction;
+    donation: DonationInfo;
+    fee: bigint;
+    /** Always true: the UI must say so before the user accepts. */
+    requiresSecondSignature: true;
+} | {
+    status: "not-offered";
+    reason: NotOfferedReason;
+};
+/**
+ * Soroban path: an InvokeHostFunction tx holds a single operation, so the donation is a separate
+ * payment tx, built only after the main tx succeeded. Needs a second signature. Never throws for
+ * ineligible input.
+ */
+export declare function donateAfter(result: MainTxResult, opts: DonateAfterOptions): Promise<DonateAfterResult>;

package/dist/donate-after.js

@@ -0,0 +1,75 @@
+import { Account, Asset, Memo, Operation, TransactionBuilder, } from "@stellar/stellar-sdk";
+import { formatStroops, parseUsdc, toStroops } from "./amount.js";
+import { memoFor } from "./app-id.js";
+import { USDC_CODE, USDC_ISSUER } from "./constants.js";
+import { checkEligibility } from "./eligibility.js";
+import { perOpFee } from "./fee.js";
+import { canSignAlone } from "./signing.js";
+/**
+ * Soroban path: an InvokeHostFunction tx holds a single operation, so the donation is a separate
+ * payment tx, built only after the main tx succeeded. Needs a second signature. Never throws for
+ * ineligible input.
+ */
+export async function donateAfter(result, opts) {
+    const no = (reason) => ({ status: "not-offered", reason });
+    if (!result.successful)
+        return no("main-tx-not-successful");
+    const amount = parseUsdc(opts.amount);
+    if (amount === null)
+        return no("invalid-amount");
+    const baseFee = perOpFee(opts.baseFee);
+    if (baseFee === null)
+        return no("invalid-options");
+    let user;
+    try {
+        user = await opts.accounts.loadAccount(result.sourceAccount);
+    }
+    catch {
+        return no("account-lookup-failed");
+    }
+    if (!user)
+        return no("account-lookup-failed");
+    // The follow-up is a single payment: medium threshold. If the master key is not enough the
+    // user would need other signers, which this flow cannot collect.
+    if (!canSignAlone(user, "medium"))
+        return no("multisig");
+    const reason = await checkEligibility({
+        accounts: opts.accounts,
+        ...(opts.fetch && { fetch: opts.fetch }),
+        foundation: opts.foundation,
+        appId: opts.appId,
+        amount,
+        cap: toStroops(opts.maxAmount),
+        source: result.sourceAccount,
+        user,
+        usdcSpend: 0n, // the main tx already settled
+        fee: baseFee,
+    });
+    if (reason)
+        return no(reason);
+    const tx = new TransactionBuilder(new Account(result.sourceAccount, user.sequence), {
+        fee: baseFee.toString(),
+        networkPassphrase: opts.networkPassphrase,
+        memo: Memo.text(memoFor(opts.appId)),
+    })
+        .addOperation(Operation.payment({
+        destination: opts.foundation.account,
+        asset: new Asset(USDC_CODE, USDC_ISSUER),
+        amount: formatStroops(amount),
+    }))
+        .setTimeout(opts.timeoutSeconds ?? 300)
+        .build();
+    return {
+        status: "offered",
+        transaction: tx,
+        fee: BigInt(tx.fee),
+        requiresSecondSignature: true,
+        donation: {
+            amount: formatStroops(amount),
+            amountStroops: amount,
+            foundation: opts.foundation.account,
+            attributed: true,
+        },
+    };
+}
+//# sourceMappingURL=donate-after.js.map

package/dist/donate-after.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"donate-after.js","sourceRoot":"","sources":["../src/donate-after.ts"],"names":[],"mappings":"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"}

package/dist/eligibility.d.ts

@@ -0,0 +1,24 @@
+import type { AccountPort, AccountSnapshot, FetchLike, Foundation } from "./ports.js";
+import type { NotOfferedReason } from "./types.js";
+export interface EligibilityInput {
+    accounts: AccountPort;
+    fetch?: FetchLike;
+    foundation: Foundation;
+    appId: string;
+    amount: bigint;
+    cap: bigint | null;
+    /** Account that will sign and pay. */
+    source: string;
+    user: AccountSnapshot;
+    /** Circle-USDC the same tx already spends (0 when none or when it is already settled). */
+    usdcSpend: bigint;
+    /** Total fee the user will pay, in stroops (XLM). */
+    fee: bigint;
+    /** XLM the same tx already spends (payments, createAccount...), stroops. Default 0. */
+    xlmSpend?: bigint;
+}
+/**
+ * Cheap, offline checks first; network checks after. Returns the first failing reason,
+ * or null when a donation may be offered. Fails closed on any lookup error.
+ */
+export declare function checkEligibility(i: EligibilityInput): Promise<NotOfferedReason | null>;

package/dist/eligibility.js

@@ -0,0 +1,42 @@
+import { StrKey } from "@stellar/stellar-sdk";
+import { isValidAppId } from "./app-id.js";
+import { verifyFoundation } from "./stellar-toml.js";
+/**
+ * Cheap, offline checks first; network checks after. Returns the first failing reason,
+ * or null when a donation may be offered. Fails closed on any lookup error.
+ */
+export async function checkEligibility(i) {
+    if (!isValidAppId(i.appId))
+        return "invalid-app-id";
+    if (!StrKey.isValidEd25519PublicKey(i.foundation.account) || i.foundation.account === i.source)
+        return "invalid-foundation";
+    if (i.cap === null)
+        return "invalid-amount";
+    if (i.amount > i.cap)
+        return "amount-over-cap";
+    if (!(await verifyFoundation(i.foundation, i.fetch)))
+        return "foundation-not-verified";
+    let foundation;
+    try {
+        foundation = await i.accounts.loadAccount(i.foundation.account);
+    }
+    catch {
+        return "account-lookup-failed";
+    }
+    if (!foundation?.usdc)
+        return "foundation-trustline-missing";
+    if (!foundation.usdc.authorized)
+        return "foundation-trustline-unauthorized";
+    if (foundation.usdc.headroom < i.amount)
+        return "foundation-trustline-full";
+    if (!i.user.usdc)
+        return "user-trustline-missing";
+    if (!i.user.usdc.authorized)
+        return "user-trustline-unauthorized";
+    if (i.user.usdc.balance < i.usdcSpend + i.amount)
+        return "insufficient-balance";
+    if (i.user.xlmAvailable < i.fee + (i.xlmSpend ?? 0n))
+        return "insufficient-balance";
+    return null;
+}
+//# sourceMappingURL=eligibility.js.map

package/dist/eligibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.js","sourceRoot":"","sources":["../src/eligibility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAqBrD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,CAAmB;IACxD,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC;QAAE,OAAO,gBAAgB,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM;QAC5F,OAAO,oBAAoB,CAAC;IAC9B,IAAI,CAAC,CAAC,GAAG,KAAK,IAAI;QAAE,OAAO,gBAAgB,CAAC;IAC5C,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG;QAAE,OAAO,iBAAiB,CAAC;IAE/C,IAAI,CAAC,CAAC,MAAM,gBAAgB,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,yBAAyB,CAAC;IAEvF,IAAI,UAAkC,CAAC;IACvC,IAAI,CAAC;QACH,UAAU,GAAG,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,uBAAuB,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,UAAU,EAAE,IAAI;QAAE,OAAO,8BAA8B,CAAC;IAC7D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU;QAAE,OAAO,mCAAmC,CAAC;IAC5E,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,2BAA2B,CAAC;IAE5E,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI;QAAE,OAAO,wBAAwB,CAAC;IAClD,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU;QAAE,OAAO,6BAA6B,CAAC;IAClE,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,sBAAsB,CAAC;IAChF,IAAI,CAAC,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC;QAAE,OAAO,sBAAsB,CAAC;IACpF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/fee.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Per-op fee from user input: `undefined` -> `fallback` (DEFAULT_BASE_FEE when not given),
+ * malformed -> null. Never below {@link MIN_BASE_FEE}, so eligibility and build use one number.
+ */
+export declare function perOpFee(input: string | undefined, fallback?: bigint): bigint | null;

package/dist/fee.js

@@ -0,0 +1,17 @@
+import { DEFAULT_BASE_FEE, MIN_BASE_FEE } from "./constants.js";
+/** Digits only, at most 15 of them: the total fee always stays far below int64. */
+const FEE_RE = /^\d{1,15}$/;
+/**
+ * Per-op fee from user input: `undefined` -> `fallback` (DEFAULT_BASE_FEE when not given),
+ * malformed -> null. Never below {@link MIN_BASE_FEE}, so eligibility and build use one number.
+ */
+export function perOpFee(input, fallback = BigInt(DEFAULT_BASE_FEE)) {
+    let v = fallback;
+    if (input !== undefined) {
+        if (!FEE_RE.test(input))
+            return null;
+        v = BigInt(input);
+    }
+    return v < MIN_BASE_FEE ? MIN_BASE_FEE : v;
+}
+//# sourceMappingURL=fee.js.map

package/dist/fee.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fee.js","sourceRoot":"","sources":["../src/fee.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEhE,mFAAmF;AACnF,MAAM,MAAM,GAAG,YAAY,CAAC;AAE5B;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAyB,EAAE,WAAmB,MAAM,CAAC,gBAAgB,CAAC;IAC7F,IAAI,CAAC,GAAG,QAAQ,CAAC;IACjB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACrC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/horizon.d.ts

@@ -0,0 +1,38 @@
+import { Horizon } from "@stellar/stellar-sdk";
+import type { AccountPort, AccountSnapshot } from "./ports.js";
+/** The subset of Horizon's account record that Spare reads. */
+export interface HorizonAccountRecord {
+    account_id: string;
+    sequence: string;
+    subentry_count: number;
+    num_sponsoring: number;
+    num_sponsored: number;
+    thresholds: {
+        low_threshold: number;
+        med_threshold: number;
+        high_threshold: number;
+    };
+    signers: {
+        key: string;
+        weight: number;
+    }[];
+    /** Account data entries, base64-encoded values. */
+    data_attr?: Record<string, string>;
+    balances: {
+        asset_type: string;
+        asset_code?: string;
+        asset_issuer?: string;
+        balance: string;
+        limit?: string;
+        buying_liabilities?: string;
+        selling_liabilities?: string;
+        is_authorized?: boolean;
+    }[];
+}
+export declare function toAccountSnapshot(r: HorizonAccountRecord): AccountSnapshot;
+/** AccountPort backed by a Horizon server. */
+export declare class HorizonAccountPort implements AccountPort {
+    private readonly server;
+    constructor(horizon?: string | Horizon.Server);
+    loadAccount(accountId: string): Promise<AccountSnapshot | null>;
+}

package/dist/horizon.js

@@ -0,0 +1,52 @@
+import { Horizon } from "@stellar/stellar-sdk";
+import { toStroops } from "./amount.js";
+import { USDC_CODE, USDC_ISSUER } from "./constants.js";
+const RESERVE_UNIT = 5000000n; // 0.5 XLM
+const net = (balance, liabilities) => (balance > liabilities ? balance - liabilities : 0n);
+export function toAccountSnapshot(r) {
+    const native = r.balances.find((b) => b.asset_type === "native");
+    const reserve = BigInt(2 + r.subentry_count + r.num_sponsoring - r.num_sponsored) * RESERVE_UNIT;
+    const nativeNet = net(toStroops(native?.balance ?? "0") ?? 0n, (toStroops(native?.selling_liabilities ?? "0") ?? 0n) + reserve);
+    const line = r.balances.find((b) => b.asset_code === USDC_CODE && b.asset_issuer === USDC_ISSUER && b.asset_type !== "native");
+    const masterWeight = r.signers.find((s) => s.key === r.account_id)?.weight ?? 0;
+    // SEP-29: data entry config.memo_required = "1" (base64 "MQ==").
+    const memoRequired = r.data_attr?.["config.memo_required"] === "MQ==";
+    return {
+        sequence: r.sequence,
+        xlmAvailable: nativeNet,
+        usdc: line
+            ? {
+                balance: net(toStroops(line.balance) ?? 0n, toStroops(line.selling_liabilities ?? "0") ?? 0n),
+                authorized: line.is_authorized === true,
+                // A missing limit is unknown: zero headroom keeps us from donating into a full line.
+                headroom: net(toStroops(line.limit ?? "0") ?? 0n, (toStroops(line.balance) ?? 0n) + (toStroops(line.buying_liabilities ?? "0") ?? 0n)),
+            }
+            : null,
+        masterWeight,
+        thresholds: {
+            low: r.thresholds.low_threshold,
+            medium: r.thresholds.med_threshold,
+            high: r.thresholds.high_threshold,
+        },
+        memoRequired,
+    };
+}
+/** AccountPort backed by a Horizon server. */
+export class HorizonAccountPort {
+    server;
+    constructor(horizon = "https://horizon.stellar.org") {
+        this.server = typeof horizon === "string" ? new Horizon.Server(horizon) : horizon;
+    }
+    async loadAccount(accountId) {
+        try {
+            const rec = await this.server.accounts().accountId(accountId).call();
+            return toAccountSnapshot(rec);
+        }
+        catch (e) {
+            if (e.response?.status === 404)
+                return null;
+            throw e;
+        }
+    }
+}
+//# sourceMappingURL=horizon.js.map

package/dist/horizon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"horizon.js","sourceRoot":"","sources":["../src/horizon.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { addDonation, type AddDonationOptions } from "./add-donation.js";
+export { donateAfter, type DonateAfterOptions, type DonateAfterResult, type MainTxResult } from "./donate-after.js";
+export { verifyFoundation, listVerifiedFoundations } from "./stellar-toml.js";
+export { HorizonAccountPort, toAccountSnapshot, type HorizonAccountRecord } from "./horizon.js";
+export { parseUsdc, formatStroops, roundUpToWholeDollar } from "./amount.js";
+export { isValidAppId, memoFor } from "./app-id.js";
+export { USDC_ISSUER, USDC_CODE } from "./constants.js";
+export type { AccountPort, AccountSnapshot, FetchLike, Foundation } from "./ports.js";
+export type { CommonOptions, DonationInfo, DonationResult, NotOfferedReason, PassthroughReason, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { addDonation } from "./add-donation.js";
+export { donateAfter } from "./donate-after.js";
+export { verifyFoundation, listVerifiedFoundations } from "./stellar-toml.js";
+export { HorizonAccountPort, toAccountSnapshot } from "./horizon.js";
+export { parseUsdc, formatStroops, roundUpToWholeDollar } from "./amount.js";
+export { isValidAppId, memoFor } from "./app-id.js";
+export { USDC_ISSUER, USDC_CODE } from "./constants.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAsE,MAAM,mBAAmB,CAAC;AACpH,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAA6B,MAAM,cAAc,CAAC;AAChG,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/ports.d.ts

@@ -0,0 +1,37 @@
+/** Injectable fetch (same shape as the global one). */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** What Spare needs to know about an account. All amounts in stroops. */
+export interface AccountSnapshot {
+    /** Current sequence number (the next tx uses sequence + 1). */
+    sequence: string;
+    /** XLM spendable on fees: balance minus reserve and selling liabilities. */
+    xlmAvailable: bigint;
+    /** Circle-USDC trustline, or null when there is none. */
+    usdc: {
+        /** Spendable balance: balance minus selling liabilities. */
+        balance: bigint;
+        authorized: boolean;
+        /** Room left before the trustline limit: limit - balance - buying liabilities (0 when full). */
+        headroom: bigint;
+    } | null;
+    /** Weight of the account's own (master) key; 0 when it is disabled. */
+    masterWeight: number;
+    /** Signing thresholds (0-255). The domain decides whether the master key alone is enough. */
+    thresholds: {
+        low: number;
+        medium: number;
+        high: number;
+    };
+    /** SEP-29: the account has `config.memo_required` = "1" and expects a memo on incoming payments. */
+    memoRequired: boolean;
+}
+export interface AccountPort {
+    /** Resolves null when the account does not exist. May throw on network errors. */
+    loadAccount(accountId: string): Promise<AccountSnapshot | null>;
+}
+export interface Foundation {
+    /** Stellar G... account that receives donations. */
+    account: string;
+    /** Bare hostname whose stellar.toml must list `account`. */
+    domain: string;
+}

package/dist/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":""}

package/dist/signing.d.ts

@@ -0,0 +1,10 @@
+import type { Transaction } from "@stellar/stellar-sdk";
+import type { AccountSnapshot } from "./ports.js";
+export type Threshold = "medium" | "high";
+/**
+ * Threshold category the tx needs. Any payment is medium; setOptions and accountMerge are
+ * treated as high (conservative: setOptions is only high when it touches signers/thresholds).
+ */
+export declare function requiredThreshold(ops: Transaction["operations"]): Threshold;
+/** True when the account's master key alone meets the threshold (a signature needs weight >= 1). */
+export declare function canSignAlone(account: AccountSnapshot, needed: Threshold): boolean;

package/dist/signing.js

@@ -0,0 +1,14 @@
+const HIGH_OPS = new Set(["setOptions", "accountMerge"]);
+/**
+ * Threshold category the tx needs. Any payment is medium; setOptions and accountMerge are
+ * treated as high (conservative: setOptions is only high when it touches signers/thresholds).
+ */
+export function requiredThreshold(ops) {
+    return ops.some((op) => HIGH_OPS.has(op.type)) ? "high" : "medium";
+}
+/** True when the account's master key alone meets the threshold (a signature needs weight >= 1). */
+export function canSignAlone(account, needed) {
+    const required = Math.max(account.thresholds[needed], 1);
+    return account.masterWeight >= required;
+}
+//# sourceMappingURL=signing.js.map

package/dist/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAKA,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC,CAAC;AAEzD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAA8B;IAC9D,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrE,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,YAAY,CAAC,OAAwB,EAAE,MAAiB;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC,YAAY,IAAI,QAAQ,CAAC;AAC1C,CAAC"}

package/dist/spend.d.ts

@@ -0,0 +1,20 @@
+import type { Asset, Transaction } from "@stellar/stellar-sdk";
+export declare const isCircleUsdc: (a: Asset) => boolean;
+export interface Spend {
+    /** Circle-USDC the tx can spend, stroops (an upper bound for strictReceive). */
+    usdc: bigint;
+    /** Native XLM the tx can spend through payments, path payments, offers and createAccount, stroops. */
+    xlm: bigint;
+    /** True if the tx also spends or does anything not modelled as Circle USDC (XLM, lookalikes, unknown ops). */
+    other: boolean;
+    /** True when the USDC spend is only a ceiling (pathPaymentStrictReceive): round-up cannot know it. */
+    uncertain: boolean;
+    /** True when an op can spend funds in a way Spare does not model. Never guess: offer nothing. */
+    unsupported: boolean;
+}
+/**
+ * What the tx's operations spend. Modelled: payment, createAccount, path payments and sell offers.
+ * Ops that can spend but are not modelled are flagged `unsupported`; any other unknown op type
+ * sets `other` so a purchase is never mistaken for a pure USDC one.
+ */
+export declare function analyzeSpend(ops: Transaction["operations"]): Spend;

package/dist/spend.js

@@ -0,0 +1,60 @@
+import { toStroops } from "./amount.js";
+import { USDC_CODE, USDC_ISSUER } from "./constants.js";
+export const isCircleUsdc = (a) => a.getCode() === USDC_CODE && a.getIssuer() === USDC_ISSUER;
+/** Ops that move no funds out of the source for our purposes. */
+const NO_SPEND = new Set([
+    "changeTrust", "allowTrust", "setTrustLineFlags", "setOptions", "manageData", "bumpSequence",
+    "claimClaimableBalance", "beginSponsoringFutureReserves", "endSponsoringFutureReserves",
+    "revokeSponsorship",
+]);
+/** Ops that can spend USDC/XLM in ways we do not model (amounts depend on the book, a pool or the whole balance). */
+const UNSUPPORTED = new Set([
+    "manageBuyOffer", "createClaimableBalance", "liquidityPoolDeposit", "accountMerge",
+]);
+/**
+ * What the tx's operations spend. Modelled: payment, createAccount, path payments and sell offers.
+ * Ops that can spend but are not modelled are flagged `unsupported`; any other unknown op type
+ * sets `other` so a purchase is never mistaken for a pure USDC one.
+ */
+export function analyzeSpend(ops) {
+    const s = { usdc: 0n, xlm: 0n, other: false, uncertain: false, unsupported: false };
+    const add = (asset, amount) => {
+        const v = toStroops(amount) ?? 0n;
+        if (isCircleUsdc(asset))
+            s.usdc += v;
+        else {
+            s.other = true;
+            if (asset.isNative())
+                s.xlm += v;
+        }
+    };
+    for (const op of ops) {
+        switch (op.type) {
+            case "payment":
+                add(op.asset, op.amount);
+                break;
+            case "pathPaymentStrictSend":
+                add(op.sendAsset, op.sendAmount);
+                break;
+            case "pathPaymentStrictReceive":
+                add(op.sendAsset, op.sendMax);
+                s.uncertain = true;
+                break;
+            case "manageSellOffer":
+            case "createPassiveSellOffer":
+                add(op.selling, op.amount);
+                break;
+            case "createAccount":
+                s.other = true;
+                s.xlm += toStroops(op.startingBalance) ?? 0n;
+                break;
+            default:
+                if (UNSUPPORTED.has(op.type))
+                    s.unsupported = true;
+                else if (!NO_SPEND.has(op.type))
+                    s.other = true;
+        }
+    }
+    return s;
+}
+//# sourceMappingURL=spend.js.map

package/dist/spend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend.js","sourceRoot":"","sources":["../src/spend.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAExD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAQ,EAAW,EAAE,CAChD,CAAC,CAAC,OAAO,EAAE,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,EAAE,KAAK,WAAW,CAAC;AAe7D,iEAAiE;AACjE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC;IACvB,aAAa,EAAE,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc;IAC5F,uBAAuB,EAAE,+BAA+B,EAAE,6BAA6B;IACvF,mBAAmB;CACpB,CAAC,CAAC;AAEH,qHAAqH;AACrH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;IAC1B,gBAAgB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,cAAc;CACnF,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAA8B;IACzD,MAAM,CAAC,GAAU,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IAC3F,MAAM,GAAG,GAAG,CAAC,KAAY,EAAE,MAAc,EAAE,EAAE;QAC3C,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,YAAY,CAAC,KAAK,CAAC;YAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;aAChC,CAAC;YACJ,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC;YACf,IAAI,KAAK,CAAC,QAAQ,EAAE;gBAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACnC,CAAC;IACH,CAAC,CAAC;IACF,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,SAAS;gBAAE,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;gBAAC,MAAM;YAChD,KAAK,uBAAuB;gBAAE,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC;gBAAC,MAAM;YACtE,KAAK,0BAA0B;gBAC7B,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;gBAC9B,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC;gBACnB,MAAM;YACR,KAAK,iBAAiB,CAAC;YACvB,KAAK,wBAAwB;gBAAE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;gBAAC,MAAM;YACjE,KAAK,eAAe;gBAClB,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC;gBACf,CAAC,CAAC,GAAG,IAAI,SAAS,CAAC,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;gBAC7C,MAAM;YACR;gBACE,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC;oBAAE,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC;qBAC9C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC;oBAAE,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC;QACpD,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/stellar-toml.d.ts

@@ -0,0 +1,10 @@
+import type { FetchLike, Foundation } from "./ports.js";
+/**
+ * SEP-1 domain verification: true only if `foundation.account` appears in the
+ * ACCOUNTS list of https://<domain>/.well-known/stellar.toml. Fails closed:
+ * no redirects, 5s timeout, body capped at 100KB (checked on Content-Length and while streaming).
+ * "Verified" means exactly this, nothing more.
+ */
+export declare function verifyFoundation(foundation: Foundation, fetchImpl?: FetchLike): Promise<boolean>;
+/** Filters candidates down to those whose stellar.toml lists their account. */
+export declare function listVerifiedFoundations(candidates: readonly Foundation[], fetchImpl?: FetchLike): Promise<Foundation[]>;

package/dist/stellar-toml.js

@@ -0,0 +1,59 @@
+import { parse } from "smol-toml";
+import { MAX_TOML_BYTES } from "./constants.js";
+const HOSTNAME_RE = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+/** Reads the body as UTF-8 text, giving up (null) as soon as it exceeds `max` bytes. */
+async function readCapped(res, max) {
+    const declared = res.headers.get("content-length");
+    if (declared !== null && Number(declared) > max)
+        return null;
+    if (!res.body)
+        return "";
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let received = 0;
+    let text = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > max) {
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        text += decoder.decode(value, { stream: true });
+    }
+    return text + decoder.decode();
+}
+/**
+ * SEP-1 domain verification: true only if `foundation.account` appears in the
+ * ACCOUNTS list of https://<domain>/.well-known/stellar.toml. Fails closed:
+ * no redirects, 5s timeout, body capped at 100KB (checked on Content-Length and while streaming).
+ * "Verified" means exactly this, nothing more.
+ */
+export async function verifyFoundation(foundation, fetchImpl = globalThis.fetch) {
+    if (!HOSTNAME_RE.test(foundation.domain))
+        return false;
+    try {
+        const res = await fetchImpl(`https://${foundation.domain}/.well-known/stellar.toml`, {
+            redirect: "error",
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok || res.redirected)
+            return false;
+        const text = await readCapped(res, MAX_TOML_BYTES);
+        if (text === null)
+            return false;
+        const accounts = parse(text)["ACCOUNTS"];
+        return Array.isArray(accounts) && accounts.includes(foundation.account);
+    }
+    catch {
+        return false;
+    }
+}
+/** Filters candidates down to those whose stellar.toml lists their account. */
+export async function listVerifiedFoundations(candidates, fetchImpl = globalThis.fetch) {
+    const checks = await Promise.all(candidates.map((c) => verifyFoundation(c, fetchImpl)));
+    return candidates.filter((_, i) => checks[i]);
+}
+//# sourceMappingURL=stellar-toml.js.map

package/dist/stellar-toml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stellar-toml.js","sourceRoot":"","sources":["../src/stellar-toml.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+import type { FeeBumpTransaction, Transaction } from "@stellar/stellar-sdk";
+import type { AccountPort, FetchLike, Foundation } from "./ports.js";
+/** The tx is left untouched: Spare cannot safely modify it. */
+export type PassthroughReason = "fee-bump" | "already-signed" | "soroban" | "multiple-sources" | "multisig" | "extra-signers";
+/** The tx is fine but a donation must not be offered. */
+export type NotOfferedReason = "invalid-options" | "invalid-app-id" | "invalid-amount" | "invalid-foundation" | "amount-over-cap" | "round-up-needs-usdc-purchase" | "round-up-already-whole" | "foundation-not-verified" | "foundation-trustline-missing" | "foundation-trustline-unauthorized" | "foundation-trustline-full" | "user-trustline-missing" | "user-trustline-unauthorized" | "unsupported-operation" | "multisig" | "insufficient-balance" | "account-lookup-failed" | "main-tx-not-successful";
+export interface DonationInfo {
+    /** Amount in USDC, 7 decimals. Show this to the user before signing. */
+    amount: string;
+    amountStroops: bigint;
+    foundation: string;
+    /** False when the tx already had a memo, so the donation cannot be tagged for the app. */
+    attributed: boolean;
+    /**
+     * Round-up only (addDonation): the USDC purchase the tx already makes, and that plus the
+     * donation. Show these instead of recomputing them.
+     */
+    purchase?: string;
+    purchaseStroops?: bigint;
+    roundedTotal?: string;
+    roundedTotalStroops?: bigint;
+}
+export type DonationResult = {
+    status: "offered";
+    transaction: Transaction;
+    donation: DonationInfo;
+    fee: bigint;
+} | {
+    status: "not-offered";
+    reason: NotOfferedReason;
+    transaction: Transaction;
+} | {
+    status: "passthrough";
+    reason: PassthroughReason;
+    transaction: Transaction | FeeBumpTransaction;
+};
+export interface CommonOptions {
+    foundation: Foundation;
+    appId: string;
+    /** App-set cap per donation, in USDC. */
+    maxAmount: string;
+    accounts: AccountPort;
+    /** Defaults to global fetch. */
+    fetch?: FetchLike;
+    /**
+     * Per-operation fee rate in stroops (digits only, minimum 100). Defaults to the tx's own
+     * per-op rate (addDonation) or 100 (donateAfter). Total fee = rate x operation count.
+     * Anything malformed yields `not-offered` / `invalid-options`.
+     */
+    baseFee?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "spare-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Add a per-transaction USDC micro-donation to any Stellar app.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "smol-toml": "^1.9.1"
+  },
+  "peerDependencies": {
+    "@stellar/stellar-sdk": "^17.4.0"
+  },
+  "devDependencies": {
+    "@stellar/stellar-sdk": "^17.4.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  },
+  "author": "Jesús Chávez Chávez",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thesatieofcoding/Spare.git",
+    "directory": "packages/spare-sdk"
+  },
+  "homepage": "https://github.com/thesatieofcoding/Spare/tree/main/packages/spare-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/thesatieofcoding/Spare/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "stellar",
+    "donations",
+    "usdc",
+    "soroban",
+    "wallets-kit"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "tsc --noEmit -p tsconfig.json"
+  }
 }