# Reserve coverage (reserve_coverage)

Desk: Digital assets. Page: https://hedgefund.md/models/reserve_coverage

**What it asks.** Do these reserves cover the tokens at par, and on which day does cash run short at this redemption rate?

Tests a reserve against redemptions at par: coverage after haircuts, cash available by day against cumulative redemptions, the first shortfall day and the largest daily redemption rate with no shortfall, plus net income on the reserve yield. All balances and rates come from the caller. Not an audit, an attestation or advice.

Results are hypothetical: arithmetic on the numbers sent, a made-up template or a stated default. Nobody achieved them, and they aren't a forecast, a recommendation, an offer or a record of real trading. Don't show any output to investors or clients, or use it to market an investment. Terms: https://hedgefund.md/terms

## Inputs

| Input | Type | Range | Required | What it is |
| --- | --- | --- | --- | --- |
| `tokens_outstanding` | number | 0.01 to 100000000000000 | yes | Tokens outstanding, redeemable at par of 1. |
| `reserves` | array | 1 to 30 items | yes | The reserve ladder. Up to 30 lines. |
| `reserves[].name` | string |  | yes | A label, such as Bill 90d. |
| `reserves[].amount` | number | 0 to 100000000000000 | yes | Face amount of this reserve. |
| `reserves[].haircut_pct` | number | 0 to 100 | yes | Loss on turning it into cash. 5 means 5%. |
| `reserves[].days_to_cash` | whole number | 0 to 3650 | yes | Days until it's cash. 0 means today. |
| `daily_redemption_pct` | number | 0 to 100 | yes | Share of tokens still outstanding redeemed each day. 2 means 2%. |
| `horizon_days` | whole number | 1 to 730 | yes | Days to test. |
| `reserve_yield_pct` | number | -10 to 100 | no | Yearly yield on the reserve's face amount. 4 means 4%. Default 0. |
| `fee_bps` | number | 0 to 2000 | no | Yearly fee on the reserve's face amount, in basis points. Default 0. |

## Template

Made-up numbers that run as they stand, so you can see the shape of a result. They aren't market levels, typical values or estimates, and the names in them don't exist. Replace every number before you read anything into a run.

```json
{
  "tokens_outstanding": 100000000,
  "reserves": [
    {
      "name": "Bank cash",
      "amount": 10000000,
      "haircut_pct": 0,
      "days_to_cash": 0
    },
    {
      "name": "Bill 30d",
      "amount": 30000000,
      "haircut_pct": 0.5,
      "days_to_cash": 3
    },
    {
      "name": "Bill 90d",
      "amount": 30000000,
      "haircut_pct": 1,
      "days_to_cash": 5
    },
    {
      "name": "Loan note",
      "amount": 25000000,
      "haircut_pct": 5,
      "days_to_cash": 30
    },
    {
      "name": "Property note",
      "amount": 10000000,
      "haircut_pct": 15,
      "days_to_cash": 120
    }
  ],
  "daily_redemption_pct": 5,
  "horizon_days": 60,
  "reserve_yield_pct": 4,
  "fee_bps": 30
}
```

## What the template gives

On these numbers, reserves cover 101.8% of tokens after haircuts, and at 5% a day cash first runs short on day 24. The largest daily rate with no shortfall over 60 days is 4.0173%.

- Coverage after haircuts: 101.8%
- First shortfall day: 24 day (breach)
- Shortfall on that day: 1,251,098
- Largest daily rate with no shortfall: 4.0174% a day (breach)
- Net income per year: 3,885,000
- Net income over the horizon: 203,070

Where it flips, with the other inputs held:

- `daily_redemption_pct` at 4.017365659: The largest daily rate with no shortfall over 60 days. Just above it, cash first runs short on day 29.

## Formula

Coverage = sum(amount * (1 - haircut)) / tokens. Cumulative redemptions by day t = tokens * (1 - (1 - r)^t), since each day redeems r of what's left. Cash by day t = sum of amount * (1 - haircut) over reserves with days_to_cash <= t. A shortfall is cumulative redemptions above cash on any day. Net income = face * (yield - fee).

## Assumptions

- Each day redeems the daily rate of the tokens still outstanding that morning, at par. The redemptions shrink as tokens leave.
- A reserve becomes cash only on its days_to_cash, in full, after its haircut. Unused cash carries forward, so the test compares running totals, not one day's flows.
- A shortfall is a day-end running total of redemptions above the running total of cash. Days are 1 to the horizon.
- Coverage counts every reserve, including any that reach cash after the horizon. The ladder counts only what has reached cash by that day.
- Yield isn't added to the cash ladder. Net income per year is face * (yield - fee), on the reserves as they stand.
- Income over the horizon scales that by the tokens left at the start of each day, over a 365-day year, as if reserves shrink in step with tokens.
- The largest daily rate comes from a bisection between 0 and 100 percent, cut at the tenth digit to a rate that passes when sent back. A shortfall can't get smaller as the rate rises. If no rate up to 100 gives a shortfall, the largest is 100.
- The sleeve is per 100 of tokens. Tail is the haircut loss, liquidity days the last reserve's days to cash, and carry the yearly net income.

## Not modeled

- Haircuts that widen as more is sold, and forced-sale price impact.
- Selling a reserve early for less than the stated haircut, or borrowing against it.
- Any legal claim on the reserves, custody or banking failure, and whether the reserves exist as stated.
- Contract, chain or bridge failures, paused redemptions, gates and redemption fees.
- Weekends and holidays. Every day counts as a settlement day.
- The token's price away from par in a secondary market.
- Taxes.

## Call it

Every result has the same fields: summary, readings, tables, charts, flags, flips, formula, assumptions, not_modeled, hypothetical and inputs_hash. Read flags, flips and not_modeled with the summary, and pass them along together.

### HTTP

No key. The tools keep nothing you send. Send positions by POST, because a URL can land in a server log.

```bash
curl -s https://hedgefund.md/api/v1/reserve_coverage \
  -H 'content-type: application/json' \
  -d '{"tokens_outstanding":100000000,"reserves":[{"name":"Bank cash","amount":10000000,"haircut_pct":0,"days_to_cash":0},{"name":"Bill 30d","amount":30000000,"haircut_pct":0.5,"days_to_cash":3},{"name":"Bill 90d","amount":30000000,"haircut_pct":1,"days_to_cash":5},{"name":"Loan note","amount":25000000,"haircut_pct":5,"days_to_cash":30},{"name":"Property note","amount":10000000,"haircut_pct":15,"days_to_cash":120}],"daily_redemption_pct":5,"horizon_days":60,"reserve_yield_pct":4,"fee_bps":30}' \
  | jq '{summary, flags, flips, not_modeled, inputs_hash}'
```

### MCP

The tool is `reserve_coverage` on the server at https://hedgefund.md/mcp.

```bash
curl -s https://hedgefund.md/mcp \
  -H 'content-type: application/json' -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"reserve_coverage","arguments":{"tokens_outstanding":100000000,"reserves":[{"name":"Bank cash","amount":10000000,"haircut_pct":0,"days_to_cash":0},{"name":"Bill 30d","amount":30000000,"haircut_pct":0.5,"days_to_cash":3},{"name":"Bill 90d","amount":30000000,"haircut_pct":1,"days_to_cash":5},{"name":"Loan note","amount":25000000,"haircut_pct":5,"days_to_cash":30},{"name":"Property note","amount":10000000,"haircut_pct":15,"days_to_cash":120}],"daily_redemption_pct":5,"horizon_days":60,"reserve_yield_pct":4,"fee_bps":30}}}' \
  | jq '.result.structuredContent | {summary, flags, flips, not_modeled, inputs_hash}'
```

### The library

The same code on your own machine, with no dependencies, and nothing is sent anywhere.

```bash
curl -fsSL https://hedgefund.md/hedgefund.mjs -o hedgefund.mjs   # read it before you run it
node hedgefund.mjs template reserve_coverage > mine.json           # replace every number in it
node hedgefund.mjs run reserve_coverage mine.json | jq '{summary, flags, flips, not_modeled, inputs_hash}'
```

In a script:

```js
import { run, template } from "./hedgefund.mjs";

const inputs = template("reserve_coverage"); // replace every number in it
const { summary, flags, flips, not_modeled } = run("reserve_coverage", inputs);
```