feat: Fee-bump / sponsored transactions (gasless registration & claim)

[joelpeace48-cell]

Background & current state

New users without XLM cannot pay transaction fees, so their very first action (register/claim) fails. Trivela has no fee-sponsorship path; the wallet abstraction (frontend/src/lib/wallet) assumes the user funds their own fees.

Goal

Provide a backend fee-sponsorship service that wraps user transactions in fee-bump transactions (operator pays fees) with strict abuse controls, enabling gasless registration/claim for first-time users.

Technical design

• Endpoint POST /api/v1/sponsor/fee-bump accepts a signed inner tx; server validates it (only allows Trivela contract ops to known contract IDs), wraps it in a FeeBumpTransaction signed by the sponsor account, and submits.
• Abuse controls: per-IP + per-identity quotas via the existing rate limiter; allowlist of permitted operations; max fee cap; daily budget with a circuit breaker.
• Sponsor account health monitored (NEW-016).

Edge cases

• Inner tx contains non-Trivela ops → reject.
• Quota exceeded → 429 with Retry-After.
• Sponsor budget exhausted → 503 + alert; fall back to user-paid.
• Replay of the same inner tx → dedupe (idempotency, NEW-031).
• Fee spikes → cap + reject above max.

Task breakdown

• Fee-bump endpoint + op allowlisting + validation.
• Quota/budget controls + circuit breaker.
• Frontend: auto-route first action through sponsorship when user XLM is insufficient.
• Tests: valid sponsor, disallowed op, quota/budget exhaustion, replay.

Acceptance criteria

• A user with 0 XLM completes registration via a sponsored tx within quota.
• Non-Trivela ops and over-quota requests are rejected.

Testing & verification

• Integration test on testnet with a zero-balance account; quota exhaustion returns 429.

Out of scope

• Account creation/reserve sponsorship (NEW-021).

Dependencies / related

• Pairs with NEW-021, NEW-019 (passkeys), NEW-016, NEW-031.

References

• Stellar fee-bump transactions (CAP-15).

Difficulty: medium · Effort: M · stellar

[Properprogress1]

@Properprogress1 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Let I work on this please

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Properprogress1 to this issue.

[elijahbok14-sudo]

@elijahbok14-sudo has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi, can i work on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @elijahbok14-sudo to this issue.

[aliyuHabibu]

@aliyuHabibu has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi, Please assign the issue to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @aliyuHabibu to this issue.

[Truphile]

@Truphile has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I've implemented similar transaction sponsorship and secure backend signing flows before, including transaction validation, operation allowlisting, rate limiting, idempotency, and budget controls. I'm familiar with Stellar transaction handling and designing fee-sponsorship services that balance usability with strong abuse prevention.

For this task, I'll implement a secure fee-bump sponsorship endpoint that validates and wraps eligible Trivela transactions, enforce quotas, fee caps, and budget circuit breakers, integrate the frontend fallback for first-time users without XLM, and add comprehensive integration tests covering successful sponsorship, invalid operations, quota exhaustion, replay protection, and sponsor budget limits.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Truphile to this issue.

[Turawa2]

@Turawa2 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I can work on the issue perfectly and deliver a proper solution.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Turawa2 to this issue.

[Jayy4rl]

@Jayy4rl has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would like to work on this. please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Jayy4rl to this issue.

[osasfaith]

@osasfaith has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would love to work on this issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @osasfaith to this issue.

[drips-wave]

Congratulations, @Jayy4rl! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Jayy4rl: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🦊 GrantFox — @Jayy4rl has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #555)
2. Your PR will be reviewed by the FinesseStudioLab maintainers

Good luck! Track your progress on GrantFox.