CONTRACTS: Implement Token Renewal System

[truthixify]

Description

Add functionality to renew membership tokens before they expire, including automatic renewal options and grace periods for expired tokens.

Files to Modify

• contracts/manage_hub/src/membership_token.rs - Add renewal functions
• contracts/manage_hub/src/lib.rs - Add renewal endpoints
• contracts/manage_hub/src/types.rs - Add renewal data structures
• contracts/manage_hub/src/errors.rs - Add renewal-specific errors
• contracts/common_types/src/types.rs - Add renewal status enum

Key Changes Required

1. Renewal Data Structures - Add renewal tracking structures to types.rs and common_types/src/types.rs
2. Token Renewal Logic - Implement renewal functions in membership_token.rs with grace period handling
3. Renewal Configuration - Add configurable renewal settings (grace periods, fees, limits) with admin management
4. Payment Integration - Integrate renewal fees with the existing payment system in the subscription module
5. Renewal History - Track all renewal attempts and history for each token with proper storage management
6. Auto-Renewal System - Implement automatic renewal checking and processing capabilities
7. Renewal Validation - Add comprehensive validation for renewal eligibility and limits

Acceptance Criteria

• Add renew_token function to membership contract
• Implement grace period for expired tokens (configurable, default 7 days)
• Add automatic renewal configuration and checking
• Include payment validation for renewals with configurable fees
• Add renewal history tracking with renewal count limits
• Update tests for renewal scenarios including edge cases
• Add renewal eligibility checking functions
• Implement renewal notification events

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 100 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[JerryIdoko]

@JerryIdoko has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi there,

I would like to apply to work on this issue. I have reviewed the requirements for the Token Renewal System and have a clear plan to implement the functionality across the manage_hub and common_types crates.

Implementation Plan

Based on the description, here is how I plan to approach the implementation:

Data Structures (types.rs & common_types/src/types.rs):

Define the RenewalStatus enum (Active, GracePeriod, Expired).

Create structs for RenewalConfig (fees, grace period duration, limits) and RenewalRecord to track history.

Core Logic (membership_token.rs):

Implement the renew_token function.

Add logic to check if a token is within the renewable window or grace period (defaulting to 7 days).

Implement validations to ensure renewal limits are not exceeded.

Configuration & Admin (lib.rs):

Add storage items for renewal configurations.

Implement admin endpoints to update grace periods and renewal fees.

Payment & History:

Integrate with the subscription module to verify payment receipt before finalizing renewal.

Ensure every renewal attempt is logged in the RenewalHistory storage map.

Emit relevant events (TokenRenewed, GracePeriodEntered, RenewalFailed).

Testing:

I will add comprehensive unit tests covering:

Successful renewal within the standard window.

Successful renewal during the grace period.

Failure scenarios (expired beyond grace period, insufficient funds, limit reached).
Could you please assign this issue to me?

Thanks!

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

[Sandijigs]

@Sandijigs has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

hi My name is Sandra.
I have reviewed the issue and understand what needs to be done
I am a fullstack software/ Blockchain Engineer with over 6years of experience web2 experience(Fullstack) and 2 year web3 experience (JavaScript,TypeScript, Rust ,Python, Soroban,Solidity,(Backend, frontend, Mobile and smart contracts) ). I have contributed to several projects in the stellar ecosystem. . please Assign this Issue to me

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

[ayomideadeniran]

@ayomideadeniran has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’m a smart contract developer, and I’d like to implement the membership token renewal system, including manual and automatic renewals, grace period handling, renewal fees, renewal history tracking, and notification events. I’ll add the required data structures, validation logic, payment integration, and comprehensive tests covering edge cases.

ETA: 3–4 days

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

[ryzen-xp]

@ryzen-xp has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi maintainers 👋
I’m a blockchain developer with strong expertise in Stellar, Rust,TS and Stellar SDK integrations. I’ve worked on multiple Stellar-based smart contract and backend systems.

I understand the scope of this issue and can deliver a reliable, production-quality solution with proper tests and documentation.
Plz assign me !!

ETA: 24 hours

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

[ussyalfaks]

@ussyalfaks has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi! I’d like to contribute to this issue by adding membership token renewal functionality, including grace periods and automatic renewal support. I’m ready to implement renewal logic with configurable settings, integrate renewal payments, track renewal history, handle eligibility validation, emit renewal events, and add tests covering all renewal and edge-case scenarios.

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

[soma-enyi]

@soma-enyi has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

GM GM Maintainer!!!
I would like to work on this issue!!!

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

[ReinaMaze]

@ReinaMaze has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hello,
I’d like to apply for this issue and kindly request to be assigned.
I’ve reviewed the requirements and I’m confident I can deliver the solution as described. I have open-source contribution experience and I’ll follow the project guidelines to ensure the implementation is clean, tested, and meets the acceptance criteria.

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

[Rampop01]

@Rampop01 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I would like to work on this issue . I understand the assignment and the requirements, and I’m confident in the approach needed to deliver the best solution. Kindly assign this task to me.

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

[Lansa-18]

@Lansa-18 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I'd like to work on this issue.

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

[drips-wave]

Congratulations, @Lansa-18! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on January 31, 2026.

🧑‍💻 @Lansa-18: 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 issued 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 🌊