# Official Documentation on Coretime Renewal is live on Polkadot Docs

Link: https://docs.polkadot.com/develop/parachains/deployment/coretime-renewal/

## How to enable/disable the Coretime Auto-Renewal feature on Polkadot/Kusama for parachains

This document explains the functionality introduced in [Polkadot SDK Pull Request #4424](https://github.com/paritytech/polkadot-sdk/pull/4424) and provides additional context on the `enable_auto_renew` extrinsic. It also addresses common examples encountered during implementation.

---

## **Overview of Coretime Auto-Renewal**

The Coretime auto-renewal feature simplifies the process of renewing coretime for tasks running on specific cores. Previously, parachains had to manually renew their cores for each bulk period. Renewals are automatically processed at the start of each sale. How this works:
- Checks each auto-renewal record.
- Attempts to renew cores from the task's sovereign account.
- On success, emits `Renewed`.
- Emits `AutoRenewalFailed` event if payment fails, but maintains the auto-renewal setting for subsequent sales even if this happens. In such case the parachains soverign account will need to renew manually and top up the account for future auto renewals to be successful.

After enabling the auo=to renewal functionality update:
- Only the sovereign account of the task (parachain) can enable or disable auto-renewal for its assigned cores.
- Renewals are executed automatically at the start of each bulk period.
- The sovereign account of the task is charged for renewal costs.
- The core must be eligible for renewal either:
-- Immediately in the next bulk period
-- At a future specified timeslice (`workload_end_hint`)

There is a total number of auto-renewals allowed, specified at the runtime level (`T::MaxAutoRenewals`)

---

## **New Extrinsics**

### **1. `enable_auto_renew`**
This extrinsic allows a task's sovereign account to enable auto-renewal for a specific core.

#### **Details**
- **Origin:** Must be the sovereign account of the task.
- **Parameters:**
- `core`: The core currently assigned to the task.
- `task`: The task for which auto-renewal is being enabled.
- `workload_end_hint`: Used when the core is not expiring in the current bulk period (e.g., due to a lease). This allows you to enable auto-renewal in advance, instead of needing to wait for the sale in which your core will expire.

---

### **2. `disable_auto_renew`**
This extrinsic disables auto-renewal for a given task on a specified core.

Details
`Origin`: Must be the sovereign account of the task.
Parameters:
`core`: The core currently assigned to the task.
`task`: The task for which auto-renewal is enabled.

Auto-renewal must be currently enabled for the core/task pair.

---

## **Example of Enabling Auto-Renewal**

The `enable_auto_renew` extrinsic provides flexibility for different scenarios where auto-renewal is required. Below are three examples demonstrating how to use the `workload_end_hint` parameter effectively in various situations.

### **1. Enabling Auto-Renewal for Immediate Renewal (Current Sale)**

If the renewal is due in the current sale, you can enable auto-renewal without specifying a `workload_end_hint`. In this case, the system will automatically handle the renewal at the start of the next bulk period.

#### **Example**

enable_auto_renew(
    origin: SovereignAccount,
    core: CoreIndex,
    task: TaskId,
    workload_end_hint: None // No hint needed for immediate renewal
)

- **Use Case:** You want to renew a task that is about to expire in the current sale.
- **Behavior:** The system processes the renewal automatically at the start of the next bulk period.

---

### **2. Enabling Auto-Renewal for an Upcoming Renewal (Next Sale)**

If you assign a core and want to immediately enable auto-renewal for a task that will expire in the next sale, you need to set `workload_end_hint` to the end of the region that was just purchased. This ensures that auto-renewal is scheduled correctly for when the current allocation ends.

#### **Example**

enable_auto_renew(
    origin: SovereignAccount,
    core: CoreIndex,
    task: TaskId,
    workload_end_hint: Some(end_timeslice) // The end of the region just purchased
)

- **Use Case:** You’ve just assigned a core and want to ensure it renews automatically after its initial allocation ends.
- **Behavior:** The system schedules auto-renewal for when the current allocation expires.

---

## **Key Notes**

- The behavior described above is not an issue but rather intended functionality. By correctly configuring `workload_end_hint`, users can handle various scenarios efficiently.
- Always ensure that your sovereign account has sufficient funds to cover renewal costs at each bulk period start.
- Use tools like Polkadot.js Apps or on-chain queries to determine `end_timeslice` and calculate `region_end` where necessary.

---

## **Key Events**

The following events are emitted during auto-renewal operations:

1. **`AutoRenewalEnabled(core_index, task_id)`**
Indicates that auto-renewal has been successfully enabled for a core.

2. **`AutoRenewalFailed(core_index, payer_account)`**
Indicates failure due to insufficient funds or other issues.

3. **`AutoRenewalLimitReached()`**
Triggered if the maximum number of allowed auto-renewals is exceeded.

---

## **Best Practices**

1. **Efficient Scheduling:** Use `workload_end_hint` when enabling auto-renewals for tasks with extended leases to avoid unnecessary lookups.
2. **Account Funding:** Ensure that the sovereign account has sufficient funds to cover renewal costs at each bulk period start.

---