> For the complete documentation index, see [llms.txt](https://plimsoll-protocol.gitbook.io/plimsoll-protocol-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plimsoll-protocol.gitbook.io/plimsoll-protocol-docs/protocol/lifecycle.md).

# Lifecycle of a reading

An asset moves through four states. Coverage exists only in the last two.

```
 unlisted ──list_asset──▶ listed ──post_supply──▶ supply known ──post_reserve──▶ covered reading
                            │                                                       │
                            └──post_reserve──▶ report known ──post_supply──────────┘
```

| State           | Has                                                       | `coverage()` returns                             |
| --------------- | --------------------------------------------------------- | ------------------------------------------------ |
| Unlisted        | nothing                                                   | `None`; posts are rejected with `AssetNotListed` |
| Listed          | `AssetRecord`                                             | `None`                                           |
| One side known  | supply **or** a report                                    | `None`                                           |
| Covered reading | supply **and** at least one report at or above `min_tier` | `Some(Coverage)`                                 |

## Step by step

### 1. List

Anyone calls `list_asset(sac)`. The contract checks that `sac` is a genuine Stellar Asset Contract, reads `name()` (for example `PUSD:GBIE3ANCRVCBWETUZXWYKRMP27LQVJHX757XXAQUT3LYHVTNFPPPXEY4`), splits it into code and issuer, and stores the record. Native XLM is rejected: it has no issuer and no reserves.

### 2. Post supply

The indexer's poster account (registered with the `SupplyPoster` role) calls `post_supply(poster, sac, amount, ledger, breakdown_hash)`. `ledger` must be newer than the stored snapshot and not newer than the current ledger.

The poster posts when supply changes, and at least every 6 hours otherwise. That keeps `is_covered` freshness checks passing for consumers that use a short `max_age`.

### 3. Post reserves

A reporter calls `post_reserve(reporter, sac, amount, as_of, doc_hash, doc_uri)`. The contract sets the tier from who the reporter is. `as_of` must not be in the future, and must be later than the last report **at the same tier**. Different tiers have independent histories.

### 4. Read

`coverage(sac, min_tier)` takes the latest supply snapshot and, among tiers at or above `min_tier`, the report with the latest `as_of`. A tie goes to the stronger tier. `is_covered` adds two checks: freshness of both inputs, and the ratio.

## What happens over time

Readings do not expire on-chain; they age. `coverage()` keeps returning the last figures, and the caller decides how old is too old through `max_age`. The app labels a reading **stale** when the report is more than 31 days old, which matches a monthly reporting cycle.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://plimsoll-protocol.gitbook.io/plimsoll-protocol-docs/protocol/lifecycle.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.