Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion crates/core/src/scenarios/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Protocols that are natively supported by Surfpool will have their IDLs included
- **Pump v1** - Bonding curve launchpad with curve reserve and global config override templates
- **Phoenix Eternal** - Perpetuals venue with trader collateral, mark price, maintenance margin, market fee, withdraw limit, trader capability, stop-loss trigger and delegated permission templates. See [protocols/phoenix-eternal/README.md](./protocols/phoenix-eternal/README.md)
- **PumpSwap v1** - Constant-product AMM with pool state and global config override templates, including canonical pool derivation for migrated pump.fun coins
- **Tessera V** - Proprietary market maker (no published IDL), with price, freshness, ladder depth, ladder curve and halt templates; callers choose the market account. See [protocols/tessera/v1/README.md](./protocols/tessera/v1/README.md)
- **Tessera V** - Proprietary market maker (no published IDL), with price, ladder depth, ladder curve and halt templates; its quote is kept alive. Callers choose the market account. See [protocols/tessera/v1/README.md](./protocols/tessera/v1/README.md)

For custom protocols, an IDL can be registered at runtime using the [`surfnet_registerIdl`](https://docs.surfpool.run/rpc/cheatcodes#surfnet-registeridl) RPC cheatcode.

Expand Down
95 changes: 36 additions & 59 deletions crates/core/src/scenarios/protocols/tessera/v1/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Tessera V

A proprietary market maker (PMM), not an AMM. Five templates control its price, quote freshness,
ladder depth, ladder curve and a full halt.
A proprietary market maker (PMM), not an AMM. Four templates control its price, ladder depth,
ladder curve and a full halt. Surfpool keeps the quote current on its own once a scenario overrides a
market.

Tessera does not derive its price from vault ratios. Its maker writes one price per swap direction
into the market account, and two directional ladders of twenty levels decide how much fills at
Expand All @@ -15,7 +16,6 @@ Program: `TessVdML9pBGgG9yGks7o4HewRaXVAMuoVj4x83GLQH`.
| Template | Overrides |
| ------------------- | ------------------------------------------------------ |
| `tessera-price` | the price Tessera uses for each swap direction |
| `tessera-freshness` | whether Tessera's quote is current or stale |
| `tessera-depth` | how much each ladder level fills before the next one |
| `tessera-curve` | the output factor applied at each ladder level |
| `tessera-halt` | whether any level quotes at all |
Expand All @@ -29,7 +29,6 @@ Program: `TessVdML9pBGgG9yGks7o4HewRaXVAMuoVj4x83GLQH`.
| `*_level_N_amount` | capacity in atoms of the swap's input token | sell side of SOL/USDC: `1000000000` = 1 SOL |
| `*_level_N_factor` | output factor in millionths, below `1000000` | `990000` pays 1% less than the bare price |
| `*_levels_enabled` | enabled flag of all twenty levels on one side | `0` halts that side |
| `last_update_slot` | offset from the materialization slot | `0` = updated now, `-20` = twenty slots old |

Price conversion, with both decimals taken from the two mints:

Expand All @@ -45,8 +44,8 @@ sell output = floor(base_in × quote_atoms_per_base_atom_x1e15 × sell_level_0_
buy output = floor(quote_in × base_atoms_per_quote_atom_x1e15 × buy_level_0_factor / 10^21)
```

The formulas hold for a quote younger than its grace period (see
[How a quote ages](#how-a-quote-ages)) and with neutral quote-start configs. The five quote-start configs at offset 1136 can lower a fill or make it skip leading levels. Which
The formulas hold for a quote younger than its grace period, which keep-alive keeps it (see

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar: "younger than its grace period, which keep-alive keeps it". Suggest: "…a quote younger than its grace period, as keep-alive keeps it (see …)". The same phrasing appears in overrides.yaml in the tessera-price llm_context.

[How a quote ages](#how-a-quote-ages)), and with neutral quote-start configs. The five quote-start configs at offset 1136 can lower a fill or make it skip leading levels. Which
one applies depends on how many slots ago the config account
`BAT1Ndpu5gbLTp2AZkSXP79LJBZfCH4B3zGhi6LtvdhK` was updated. A surfnet never updates it, so after
about 300 slots the last config applies. Configs that each hold `0`, `1000000` and `0` change
Expand All @@ -58,11 +57,13 @@ The market account is 1264 bytes. Offsets not listed are not written by any temp

| Offset | Field | Encoding | Unit |
| --------- | -------------------------------------- | ----------------- | ------------------------ |
| 0 | buy depth used since the publication | u64, keep-alive | quote atoms |
| 8 | sell depth used since the publication | u64, keep-alive | base atoms |
| 24 | base mint | pubkey, read-only | - |
| 56 | quote mint | pubkey, read-only | - |
| 88 | freshness limit | u64, read-only | slots |
| 96 | grace period | u64, read-only | slots |
| 120 | last update slot | `slot` | slot offset |
| 120 | last update slot | u64, keep-alive | slot |
| 128 | quote atoms per base atom | u128 | × 10^15 |
| 144 | base atoms per quote atom | u128 | × 10^15 |
| 160 + 24n | sell level n capacity | u64 | base atoms |
Expand Down Expand Up @@ -100,23 +101,31 @@ Use `fetchBeforeUse: true` so the selected market is loaded into the local VM fr
datasource before its bytes are changed. A later override that builds on an earlier one in the same
scenario uses `false`, or the re-fetch undoes the earlier write.

## Two rules that prevent misleading scenarios
## Keep-alive (Surfpool handles it)

**1. Keep the quote fresh.** Tessera rejects a quote whose last update is at least the market's
freshness limit old with custom error 65535, so a correct price or depth change can appear to do
nothing. Before that, an ageing quote fills worse; see [How a quote ages](#how-a-quote-ages). Apply
`tessera-freshness` with `last_update_slot: 0` alongside every price, depth or curve change, and
schedule it again, with `fetchBeforeUse: false`, at least every 4 slots where a quote is needed.
On mainnet the maker republishes each market's quote every slot or two. Each publication writes the
slot (offset 120) and clears the depth swaps have used since the last one (offsets 0 and 8). Nobody
runs the maker against a surfnet, so Surfpool republishes the quote every slot
([keep-alive](../../README.md#keep-alive)): the quote stays 0 slots old, and every slot starts with
the full ladder. Swaps in one slot still use up the ladder as on mainnet; the next slot gives it back.
There is nothing to schedule.

**2. Change a ladder as a whole.** The stored ladder has a different number of enabled levels on
Every template keeps the market it writes quoting. Keep-alive starts in the slot the override plays
and runs until the network is reset.

## A rule that prevents misleading scenarios

**Change a ladder as a whole.** The stored ladder has a different number of enabled levels on
each market and side, and the maker can pull a side at any moment. Read the selected market account
first, scale every enabled level on the side you stress by one ratio, and keep factors descending.

## How a quote ages

A quote younger than the market's grace period (offset 96, 5 slots on the featured markets) fills
at the formula. From then on each slot lowers the fill by a growing amount, in both directions,
until the quote rejects at its freshness limit. Measured on SOL / USDC:
Keep-alive keeps a market a scenario overrides 0 slots old. A market no override names is not
republished, and ages like this. A quote younger than the market's grace period (offset 96, 5 slots
on the featured markets) fills at the formula. From then on each slot lowers the fill by a growing
amount, in both directions, until the quote rejects at its freshness limit (offset 88). Measured on
SOL / USDC:

| Slots since the update | Fill |
| ---------------------- | ----------- |
Expand All @@ -129,8 +138,7 @@ until the quote rejects at its freshness limit. Measured on SOL / USDC:
| 15 to 19 | -0.5% (cap) |
| 20 | rejected (`65535`) |

cbBTC / USDC loses half as much per slot. Schedule `tessera-freshness` at least every 4 slots for a
stable price.
cbBTC / USDC loses half as much per slot.

## Scenario ideas

Expand All @@ -141,8 +149,7 @@ Use this to test whether a router or strategy reacts when Tessera's SOL price mo
1. Choose **SOL / USDC** in `tessera-price`.
2. Set both price fields from the formula. $100 per SOL is `100000000000000` and
`10000000000000000`.
3. Add `tessera-freshness` with `last_update_slot: 0`.
4. Compare both swap directions before and after. Doubling the price doubles a sell's output and
3. Compare both swap directions before and after. Doubling the price doubles a sell's output and
halves a buy's.

### Maker widens one side
Expand All @@ -152,7 +159,7 @@ Use this to test a maker that still quotes but pays less in one direction.
1. Choose the market in `tessera-curve`.
2. Multiply all twenty sell factors by one ratio to make selling base worse, or the buy factors to
make buying base worse. The other side is unaffected.
3. Keep the quote fresh and compare equal-size swaps in both directions.
3. Compare equal-size swaps in both directions.

### Thin liquidity for large orders

Expand All @@ -162,15 +169,6 @@ Use this to test order splitting when Tessera's depth drops.
2. Multiply every enabled capacity on one side by one ratio, for example 10%.
3. Swap a small and a large amount. The small fill is unchanged; the large one gets worse.

### Stale maker

Use this to test fallback routing when Tessera stops updating.

1. Choose the market in `tessera-freshness`.
2. Set `last_update_slot` to minus the market's freshness limit (the u64 at bytes 88..96), for
example `-20` on SOL / USDC.
3. Confirm both directions fail with custom error 65535 and that one slot younger still fills.

### Maker pulls all liquidity

1. Apply `tessera-halt` with both fields `0`.
Expand All @@ -180,8 +178,9 @@ Use this to test fallback routing when Tessera stops updating.

Use this to test a router's slippage limit when Tessera reprices after the router quoted it.

1. Add `tessera-freshness` with `last_update_slot: 0` at the first slot, so the stored price quotes.
2. Two slots later, add `tessera-price` 1% lower in both directions and `tessera-freshness` again.
1. Add `tessera-price` at the first slot with the stored price, so keep-alive keeps the market
quoting.
2. Two slots later, add `tessera-price` 1% lower in both directions.
3. Quote a swap in the first slot and fill it after the move. The fill pays 1% less, and a tight
slippage limit must reject it.

Expand All @@ -190,7 +189,7 @@ Use this to test a router's slippage limit when Tessera reprices after the route
Use this to test an arbitrage bot across Tessera and an AMM pool.

1. Read the SOL / USDC price of an AMM pool, for example Orca Whirlpool.
2. Set Tessera's SOL / USDC price 2% above it with `tessera-price` and keep the quote fresh.
2. Set Tessera's SOL / USDC price 2% above it with `tessera-price`.
3. Buying SOL on the AMM and selling it into Tessera should clear both venues' fees.

# Recipes
Expand All @@ -206,27 +205,6 @@ base_atoms_per_quote_atom_x1e15: "10000000000000000"
Set both fields. Offset 128 alone moves only sells and offset 144 alone moves only buys, so a
single-field write creates a one-sided price.

## Keep the quote current

```text
template: tessera-freshness
last_update_slot: 0
```

A fresh quote fills at the formula for its grace period and is rejected at its freshness limit.
Schedule the template again, with `fetchBeforeUse: false`, at least every 4 slots where a quote is
needed.

## Make the quote stale

```text
template: tessera-freshness
last_update_slot: -20 # the SOL / USDC freshness limit is 20 slots
```

The boundary is exclusive: `-19` still fills in the slot it lands, `-20` rejects, and every later
slot ages the quote by one more. Do not schedule a fresh override after it.

## Reduce depth

```text
Expand Down Expand Up @@ -263,7 +241,7 @@ Tessera fills swaps only through a router. A direct call must carry the DFlow se
`8xeaWCsJYxRoudEZGJWURdfrtFhLYZz9b4iHJnW5tb3d` as a signer. To send one on a local surfnet:

1. Start surfpool with `--skip-signature-verification`, so the sentinel needs no key.
2. Play the scenario. Studio pauses the clock, so the quote stays fresh until Complete.
2. Play the scenario. Keep-alive keeps the quote fresh.
3. Simulate the swap before sending it. On a fresh surfnet the send otherwise fails with
"Failed to fetch accounts from remote".

Expand All @@ -279,13 +257,12 @@ one per mint, and the USDC vault is shared by every USDC market.

| Symptom | Fix |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `Custom(65535)` after a price, depth or curve change | The quote is stale. Add `tessera-freshness` with `last_update_slot: 0` in that slot |
| `Custom(65535)` on a market you did not override | Expected: nothing republishes a market no override names, so it went stale |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This row and the next one both start with Custom(65535) on a market…, but each gives a different cause. A reader matching on the symptom has to read both. Consider one row: "Custom(65535): the market was never overridden, so it aged past its limit, or the maker pulled that side upstream."

| `Custom(65535)` on a market you did not halt | The maker pulled that side upstream; every level on it is disabled |
| `Custom(8)` | A curve factor is not lower than the level before it; scale all factors by one ratio |
| `Custom(7)` | A curve factor is `1000000` or more; factors stay below it |
| A fill lands below the formula without an error | The quote is past its grace period; refresh it with `tessera-freshness` |
| A second swap in one slot fills worse than the first | Not a bug: swaps use up the ladder; the next slot's republication gives it back |
| Only one direction repriced | Set both price fields; 128 prices sells and 144 prices buys |
| A depth change has no visible effect | The fill was smaller than the first level; use a larger swap |
| A price change lands on the wrong account | No owner or size check exists on raw writes; pick a featured market or check that a typed address is a Tessera market account |
| `buy_levels_enabled: 1` re-enabled maker-disabled levels | Only 0 is supported; 1 makes the program quote levels the maker had pulled |
| A stale override stops rejecting | A later `tessera-freshness` with a non-negative offset refreshed it; remove it |
33 changes: 33 additions & 0 deletions crates/core/src/scenarios/protocols/tessera/v1/keep-alive.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
protocol: Tessera
version: v1
account_type: MarketState

raw_layout: true

templates:
- id: tessera-quote-publication
name: Quote publication
description: The maker republishing a market's quote
idl_account_name: MarketState
address:
type: pubkey
properties:
- path: last_update_slot
offset: 120
encoding: u64
description: >-
Slot the quote was published in. A quote younger than the market's grace period (offset
96) fills at the price formula, an older one fills worse, and one as old as the market's
limit (offset 88) rejects with custom error 65535.
- path: buy_depth_used
offset: 0
encoding: u64
description: >-
Quote atoms buys have taken from the buy ladder since the last publication. Swaps add to
it and a publication clears it, so a later buy starts at the first level again.
- path: sell_depth_used
offset: 8
encoding: u64
description: >-
Base atoms sells have taken from the sell ladder since the last publication. Swaps add to
it and a publication clears it.
Loading
Loading