# Expiry keeper

The package ships an example keeper for the window after your options expire. It finds your open positions, exercises the ones worth exercising and releases the rest once their window closes. It needs your own RPC, your addresses and, to send for real, a key.

> [!WARNING]
> It is an example, not a production keeper. Its default price source is a public, rate-limited API. Replace it before you let the keeper spend from your vault. See [Replace the price source](#replace-the-price-source).

## What the program allows

| Instruction | Who signs | When (the chain's Clock) |
| --- | --- | --- |
| `exercise_v3` | Your Maker authority, or its operator | `expiry <= now < expiry + window` |
| `release_v3` | No one: any fee payer may send it | `now >= expiry + window` |

- Exercise pays the strike in USDC from your vault to the customer. In the same transaction the JitoSOL goes to your **authority's** token account. If the vault is short, the whole transaction fails.
- Nobody can release before the window closes. So when an exercise is not worth it, the keeper waits for the window to close, then releases.
- Release returns the JitoSOL to the customer and frees your exposure and mint usage. Anyone may send it, the customer included.
- Both need the position to be open. A position settles once: a second exercise or release fails and costs only its fee.

## What a pass does

1. **Lists your open positions.** One `getProgramAccounts` on the covr program, at finalized commitment, filtered to your Maker's open positions.
2. **Reads each one.** One finalized `getMultipleAccounts` of the position, your Maker, its market, your USDC vault and the Clock, so all five come from the same slot. A position that fails to decode is reported, never acted on.
3. **Decides.** The exported, pure `decide()` picks one action:
   - **wait**: before expiry; or in the window with no price, a stale price, or spot below the strike plus your edge;
   - **exercise**: in the window, JitoSOL collateral, a fresh price at least `MIN_EXERCISE_EDGE_BPS` above the strike, and the strike free in your vault;
   - **release**: the window has closed;
   - **report**: worth exercising but the vault cannot pay the strike; a restricted position; collateral other than JitoSOL; Token-2022 collateral.
4. **Checks before an exercise.** The signer must be your authority or your operator. Your authority's JitoSOL token account must exist, not be frozen, have no delegate and no other close authority. Otherwise every attempt would fail, so it reports instead.
5. **Builds.** Exercise uses `exerciseV3Instructions`, release `releaseV3Instructions`, with rent read from your RPC each pass.
6. **Sends, when live.** It signs with `KEEPER_KEYPAIR` and sends with preflight simulation. It holds a sent transaction, and does not act on that position again, until the transaction lands, fails or its blockhash expires. A held exercise keeps its strike promised, so a second exercise from the same vault sees the USDC that is really left.

## Safety defaults

- **Dry run by default.** With `DRY_RUN` unset, the keeper prints `DRY_RUN would exercise ...` or `DRY_RUN would release ...` with the exact instructions (program, accounts and roles, data in hex) and sends nothing.
- **No built-in RPC URL or key.** Everything comes from the environment. The only built-in URL is the default price source, which you replace.
- **No price, no exercise.** It never exercises without a fresh spot price, and never unless the strike is free in your vault.
- **Right desk only.** It refuses to start if your Maker account does not exist or names another authority.

## Settings

| Variable | Required | Meaning |
| --- | --- | --- |
| `RPC_URL` | yes | Your RPC. Positions, accounts and the Clock are read at finalized commitment; it must serve `getProgramAccounts` |
| `MAKER_ETH_ADDRESS` | yes | Your registered quote key address (`0x…`). Your Maker account and positions are keyed by it |
| `MAKER_AUTHORITY` | yes | Your Maker authority. The keeper refuses to start if your Maker account names another |
| `MIN_EXERCISE_EDGE_BPS` | yes | Exercise only when spot >= strike × (1 + bps / 10000) |
| `KEEPER_KEYPAIR` | live only | Path to a `solana-keygen` JSON keypair file. To exercise it must be your authority or your operator (`configureMaker`); any key can release. It signs alone, as fee payer |
| `MAX_PRICE_AGE_SECONDS` | no | Default 60. A spot observation older than this is no price |
| `POLL_SECONDS` | no | Default 15 |
| `ONCE` | no | `1`: run one pass and exit |
| `DRY_RUN` | no | `0` sends for real. Anything else, or unset, is a dry run |

## Decision rules

### The window

| Chain time | Action |
| --- | --- |
| Before `expiry` | Wait. |
| From `expiry` until `expiry + window` | Exercise if every check below passes. Otherwise wait. |
| At or after `expiry + window` | Release. Nobody can exercise any more, and nobody could release before. |

### When it exercises

All of these must hold:

- The position is an ordinary JitoSOL position. Restricted (stock) positions and other collateral are reported.
- A fresh spot price puts the JitoSOL at least `MIN_EXERCISE_EDGE_BPS` above the strike: spot >= strike × (1 + bps / 10000).
- Your vault holds the strike, free. Free means the vault's USDC minus the strikes of exercises the keeper has sent that have not settled yet. If the vault is short, the keeper reports and does not exercise.
- The clocks and the price are inside the bounds below.

### Clocks and price freshness

The decision Clock is the finalized Clock sysvar, read with the position. The keeper exercises only when all of these hold:

| Check | Bound |
| --- | --- |
| Chain Clock ahead of this machine | At most 5 s. More is clock skew on one side. |
| Chain Clock behind this machine | At most 35 s: 5 s of skew plus 30 s for finality lag. More is a stale snapshot or a lagging RPC. |
| Price dated after the Clock | At most 30 s. The default source dates prices by confirmed blocks, which lead the finalized Clock. |
| Price dated before the Clock | At most `MAX_PRICE_AGE_SECONDS`, 60 s by default. An older price is no price. |
| Decision to submission | At most 10 s. |

The 10 s budget is checked twice: once after the exercise is built, and again last, after the blockhash read and signing, immediately before submission. Elapsed time is the larger of the wall clock and a monotonic clock, so setting the wall clock back cannot stretch it. An exercise stopped here was never sent and holds nothing. The next pass decides again on fresh reads.

Release does not depend on these bounds. The program checks its timing itself. Keep this machine's clock synced (NTP).

### Reads never go back in time

Every scan and every read carries `minContextSlot`: the highest slot the keeper has seen, starting with its startup read of your Maker. A lagging node refuses instead of hiding positions. An answer below that slot is refused too.

A position missing from a later scan does **not** free its hold. Absence proves nothing: the node may lag, or the account may have closed. The keeper frees a hold only on positive evidence: the position read at or after that slot and decoded as no longer open, or the held transaction's own signature failed, finalized, or never landed before its blockhash expired. A restart forgets held transactions. The worst case is a duplicate that fails and costs its fee.

Reads are at finalized commitment, about 13 s behind the tip. A release goes out a little after the window closes. An exercise sent in the window's last seconds can fail.

## Replace the price source

> [!CAUTION]
> Replace the default price source before you set `DRY_RUN=0`. `getSpotUsd()` in `keeper/index.ts`, marked `PRICE SOURCE`, reads Jupiter's public Price API v3 for the JitoSOL mint, without credentials. It is rate limited and best effort.

The default source dates each price by the block Jupiter priced from, read from your RPC, never by the time of the request. It returns `null` on any doubt: a failed request, a missing or malformed row, a block your node has not confirmed. Jupiter updates JitoSOL roughly once a minute, so some reads are older than 60 s and the keeper waits for the next pass.

Put your own feed there. It must return `null` when unsure: the keeper never exercises without a price.

## Flash exercise is not in the SDK yet

The program can also exercise without vault USDC: a [flash exercise](https://docs.covr.markets/concepts/flash-exercise.md) sells the JitoSOL for USDC in the same transaction and pays the strike from the proceeds. The SDK has no builder for it, and the keeper does not attempt it. A position worth exercising whose strike your vault cannot pay is reported. Deposit USDC before the window closes, or let it lapse.

## Run it

Set up a folder as in the [Quickstart](https://docs.covr.markets/quickstart.md#2-install). Then copy the keeper out of the installed package and run it with `tsx`:

```sh
cp -r node_modules/@covrfun/maker-sdk/examples/keeper ./keeper
RPC_URL=https://<your own Solana RPC> \
MAKER_ETH_ADDRESS=0x<your quote key address> MAKER_AUTHORITY=<your Solana authority> \
MIN_EXERCISE_EDGE_BPS=100 ONCE=1 \
npx tsx keeper/index.ts
```

This runs one dry pass and exits. It prints what it would do for each open position. To send for real, set `KEEPER_KEYPAIR` and `DRY_RUN=0`. Without `ONCE=1` it runs a pass every `POLL_SECONDS`.

`keeper/README.md`, in the same folder, lists every setting and what each pass checks.

## Costs

An exercise creates two fresh token accounts for the customer (USDC and JitoSOL). A release creates one. Only your signer can create them in that transaction, so it pays their rent and the customer keeps it: about 0.002 SOL per account at today's rate. Choose `MIN_EXERCISE_EDGE_BPS` so that small positions still clear that rent and the fee.

## Not handled

- Restricted (stock) positions, Token-2022 collateral and collateral other than JitoSOL are reported, not settled.
- Priority fees. Under congestion, add a `SetComputeUnitPrice` instruction to the transaction. Never add a second compute unit limit.

## Next

- [Withdraw USDC](https://docs.covr.markets/guides/withdraw.md): take USDC out of your vault without leaving strikes unpaid.
- [Fills and exercise](https://docs.covr.markets/guides/fills-and-exercise.md): find fills and build an exercise yourself.

---

Source: https://docs.covr.markets/guides/expiry-keeper · Part of covr Docs, https://docs.covr.markets/llms.txt
