> 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/how-it-works.md).

# How it works

A Plimsoll line is the mark on a ship's hull. If the water is above it, the ship is overloaded, and anyone on the dock can see it. Plimsoll draws that line for issued assets: liabilities on one side, reserves on the other, the line at 100%.

## Three parts

| Part        | Where it runs | Job                                                                                            |
| ----------- | ------------- | ---------------------------------------------------------------------------------------------- |
| Contracts   | Soroban       | Store listings, supply snapshots and reserve reports; compute coverage                         |
| Indexer     | A server (Go) | Count supply from Horizon and post it; copy events into Postgres; read issuers' `stellar.toml` |
| App and SDK | Browser       | Show coverage; let issuers and auditors post reports; let anyone list an asset                 |

```
            Horizon ──supply──▶ Indexer ──post_supply──▶ ┌──────────────────┐
                                                         │  coverage-ledger │◀── is_covered ── your contract
 Issuer / auditor ──(wallet)── App ──post_reserve──────▶ │                  │
                                                         └────────┬─────────┘
                                                                  │ role_of
                                                         ┌────────▼─────────┐
                                                         │ reporter-registry│
                                                         └──────────────────┘
```

## Two halves, two sources

**Supply is public.** Every holding of a classic Stellar asset is on the ledger. The indexer adds six buckets: trustlines in each of the three authorisation states, claimable balances, liquidity-pool reserves, and balances held by contracts. It posts the total with the SHA-256 of the breakdown. The breakdown itself is served by the indexer byte for byte, so anyone can hash it and compare.

**Reserves are off-chain, so someone must sign.** The signer decides the tier:

| Tier               | Signer                     | Why it is trusted                             |
| ------------------ | -------------------------- | --------------------------------------------- |
| Auditor-signed (3) | Registered auditor         | Independent; registered by the admin          |
| Issuer-signed (2)  | The asset's issuer account | Only the issuer can produce this signature    |
| Transcribed (1)    | Registered transcriber     | Copied from a published report; lowest weight |

Each report stores the SHA-256 and URL of its source document. If the document is changed later, the hash no longer matches.

## Why this needs Stellar

* **Issued assets are part of the protocol.** Supply can be counted for any asset without the issuer's cooperation.
* **The issuer's classic account can authorise a Soroban call.** That is what makes the Issuer-signed tier unforgeable.
* **Every asset has a built-in Stellar Asset Contract (SAC)** whose `name()` is `CODE:ISSUER`. Listing accepts only genuine SACs and reads the code and issuer from that name, so a look-alike token cannot be listed under a real issuer.
* **SEP-1 already has an `attestation_of_reserve` field** in `stellar.toml`. The indexer reads it and shows it next to the on-chain figure.


---

# 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/how-it-works.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.