# Heartbeat & Subscription

The heartbeat system validates your subscription status with the vendor Console. It runs automatically and requires no action from you during normal operation.

## How It Works

The ledger binary contacts the vendor Console once every 24 hours to validate that your subscription is active. The response determines whether the system continues operating or shuts down.

### Startup Validation

On every startup, **before accepting any HTTP traffic**, the system validates the subscription:

| Condition                      | Action                              |
| ------------------------------ | ----------------------------------- |
| Fresh install (no prior data)  | Contacts Console — starts if ACTIVE |
| Subscription is ACTIVE, recent | Starts normally                     |
| Subscription is ACTIVE, stale  | Contacts Console to refresh         |
| Subscription is not ACTIVE     | Shuts down                          |

### Daily Check

After startup, the system checks the subscription every 24 hours:

| Condition                         | Action                               |
| --------------------------------- | ------------------------------------ |
| Console reachable, ACTIVE         | Updates status, schedules next check |
| Console reachable, not ACTIVE     | Updates status, shuts down           |
| Console unreachable, within grace | Logs warning, schedules next check   |
| Console unreachable, past grace   | Shuts down                           |

## Grace Period

If the Console is unreachable (network issues, Console maintenance, etc.), the system continues operating normally for up to **30 days**. After 30 days without a successful Console contact, the system shuts down on the next check.

### Alert Notifications

The Console sends email alerts at key intervals:

| Day | Alert                                           |
| --- | ----------------------------------------------- |
| 7   | Warning — Console contact has been lost         |
| 14  | Reminder — subscription validation pending      |
| 21  | Urgent — shutdown approaching                   |
| 28  | Final warning — 2 days until shutdown           |
| 30  | Shutdown — system stops on next heartbeat check |

## Shutdown Policy

The system either runs fully or stops completely — there is no partial degradation mode.

| Condition                                    | Behavior      |
| -------------------------------------------- | ------------- |
| Console responds with non-ACTIVE status      | Shutdown      |
| 30 days without successful Console contact   | Shutdown      |
| Console unreachable but within 30-day window | Runs normally |

{% hint style="info" %}
When the system shuts down due to subscription issues, your data remains fully accessible via direct database access. You can query balances, ledger lines, and all historical data directly from RDS.
{% endhint %}

## Security

The heartbeat communication is secured against tampering:

* **Request signing** — only valid ledger instances can contact the Console
* **Response signing** — only the real Console can produce valid responses
* **Replay prevention** — responses include a date component, preventing replay of old responses
* **Local integrity** — the heartbeat record in the database is protected by a cryptographic hash, preventing direct modification

### What Cannot Be Tampered

| Attack                         | Defence                                            |
| ------------------------------ | -------------------------------------------------- |
| Modify heartbeat in database   | Detected by cryptographic hash — system shuts down |
| Delete heartbeat from database | Detected on startup — system shuts down            |
| Replay old Console response    | Rejected — responses are date-specific             |
| Block network to Console       | 30-day grace period, then shutdown                 |
| Forge Console response         | Rejected — requires cryptographic key to sign      |

## Plans

| Plan     | Description                    |
| -------- | ------------------------------ |
| Free     | Basic tier, monthly billing    |
| Standard | Full features, monthly billing |

Plan details and billing are managed through the vendor Console at `https://console.entrytarget.com/`.

## Troubleshooting

### System Won't Start

* **"Environment mismatch"** — the license file is missing, invalid, expired, or the AWS account does not match the license
* **Subscription not ACTIVE** — check your subscription status in the Console
* **Console unreachable on fresh install** — ensure network connectivity to the Console URL

### System Shut Down Unexpectedly

* Check the Console for subscription status
* Verify network connectivity to `LEDGER_CONSOLE_URL`
* Review logs for heartbeat-related messages
* If your subscription is active and the Console is reachable, restart the service


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://entrytarget.gitbook.io/docs/security-and-integrity/heartbeat.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.