Difficulty forwards

A difficulty forward is a bet between two people on Ergo's average mining difficulty over a window of epochs. Both sides post LIT, and when the window ends the side the difficulty moved toward is paid out of the other side's margin. This page explains how a forward runs, what it pays, how to make and fill one in the web panel, and what can go wrong.

It does not cover the API endpoints behind the panel, which are in the API reference under Difficulty Forwards, or the batching settings your client uses to record and settle forwards, which are in Batching and orders.

What a forward is#

A forward is a single on-chain position with two sides:

Every forward has these terms:

On chain the size is stored as a notional of five times the margin. You only meet it in the API and in one setting; the web panel works in margin throughout.

A difficulty epoch is 128 blocks, about 4.3 hours at Ergo's 2-minute block time. Ergo only changes difficulty at the first block of each epoch, so every block in an epoch has the same difficulty.

There is no pool and no price oracle. The difficulty comes from Ergo's own block headers, and the two sides are always two people.

How a forward runs#

A forward goes through four steps:

1. Offer. A maker picks a side and the terms, and locks their margin plus 7.5 LIT of fees in an offer.
2. Fill. A taker takes the other side and locks the same margin and fees. The offer becomes a position holding both margins.
3. Record. Once per epoch, a transaction writes that epoch's difficulty into the difficulty accumulator, a single on-chain box holding the last 128 epochs. Whoever records earns 5 LIT from the accumulator's balance.
4. Settle. Once the window's last epoch is recorded, anyone can settle the position. Each side is paid in the same transaction, and whoever settles keeps 5 LIT.

Lithos clients record each epoch and settle finished positions on their own, so you do not need to do steps 3 or 4 yourself. Each side's 7.5 LIT of fees funds this work and is not returned:

What a position pays#

Every 1% the window's average ends above the strike moves 5% of the margin from the short side to the long side. Every 1% below it moves 5% the other way. At a 20% move the whole margin has moved, and a bigger move pays the same:

average = average difficulty over the window's epochs
move    = average / strike - 1
payout  = 5 x margin x move, held between -margin and +margin

The long side receives its margin plus the payout, and the short side its margin minus it. The most either side can lose is its own margin plus the 7.5 LIT of fees.

For a 2,000 LIT margin, each 1% move is worth 100 LIT, and a position pays the following:

Choosing a window#

A window must start between 2 and 120 epochs after the epoch of the block before the fill. The next epoch is never allowed in a window, because its difficulty can already be computed from block timestamps before it starts. The web panel shows that computed figure, labelled Next epoch, so nobody trades against it with information the other side lacks.

Two consequences for you:

• A fill has a deadline. A window starting at epoch E can only be filled while the chain is at least 2 epochs before it. The panel shows each offer's last fill height as Fill by.
• You choose when an offer expires. The panel sets each new offer to expire 128 blocks after you post it, about 4.3 hours, or at its last fill height if that comes first. Drag Expiry to keep the offer open longer, up to the last fill height. A longer expiry gives takers more chances: each difficulty change makes the window easier to forecast, and a taker fills only an offer that has turned in their favour.

Short windows are cheap to move. A miner with a tenth of Ergo's hashrate who mines elsewhere for one epoch lowers that epoch's difficulty by about 7.5%, which can decide a 1-epoch window. Your client therefore refuses to make or fill a window shorter than 8 epochs with more than 2,000 LIT of margin. The limit is a setting, described in Settings.

Hedging mining income#

Mining income per hash is proportional to 1 / difficulty, so a long position pays out when your income falls. Suppose you expect 10,000 LIT from mining over the next 80 epochs, and go long with 2,000 LIT of margin at the strike. Each 1% move then pays 100 LIT, about what a 1% change in difficulty does to 10,000 LIT of income. In other words, size the hedge so its notional, five times the margin, matches the income you expect. Your combined result is roughly the following:

Beyond a 20% move the payout stops growing, so the hedge stops covering the loss.

Trading from the web panel#

Open Extensions in the top bar and choose Difficulty Forwards. The section has four views:

Reading the market needs no API key. Filling, offering, cancelling, settling and your portfolio all need it. The panel holds the key in memory, so you enter it again after a page refresh, unless you chose to remember it in this browser.

The panel counts time in epochs. Tick Block heights next to Settings to see every window, start and deadline as block heights instead. The panel remembers the choice in this browser.

Filling an offer#

To take the other side of an offer:

1. Open Market and filter the order book. You go long and You go short pick the side you would take, and clicking a column of the strike chart narrows the book to that range of strikes.
2. Click an offer to open its quote. Check Your margin, Most you can lose and the payout curve.
3. Enter your API key if asked, then click Fill.

The fill locks your margin and 7.5 LIT, plus 0.002 ERG for the position and a 0.001 ERG network fee. The quote is read again when you open it, so the amounts you confirm are the offer's current ones.

Making an offer#

To post your own offer:

1. Open Make an offer and pick Long or Short.
2. Set the window start, the window length, the strike, your margin and the expiry. The chips next to the strike set it relative to the next epoch's difficulty.
3. Read the quote on the right, including any warnings, then click Post offer.

Your offer locks its margin, 7.5 LIT and 0.002 ERG until a taker fills it or you cancel it from Portfolio. An expired offer stays locked until you cancel it.

Settlement and refunds#

Lithos clients settle a finished position on their own. A Lithos block can carry the settlement from the third block of the window's last epoch. Once the fourth block is on chain, clients broadcast the settlement by default. You can also settle any finished position yourself from Portfolio, which pays the 0.001 ERG fee out of the position and gives you the 5 LIT the settler keeps, or 10 LIT if the same transaction records the current epoch.

The accumulator only holds the last 128 epochs. If nobody settles a position before its window's first epoch is 128 epochs old, the window can no longer be read, and settling returns each side's margin instead. Because clients settle finished positions automatically, this only happens if no client does for weeks.

Risks#

Read these before you trade:

• LIT price. Margins and payouts are LIT, so a position's value in ERG moves with the LIT price.
• Short windows. Hashrate that can move away for an epoch can decide a short window. Keep short windows small.
• Whole fills only. An offer is filled in full or not at all.
• Fixed fees. The 7.5 LIT each side pays is a constant, whatever the margin.

Settings#

The size limit on short windows is a client setting. It is shipped as follows in conf/application.conf:

forwards {
  offers {
    shortWindowEpochs = 8
    shortWindowMaxNotionalLit = 10000
  }
}

The two keys mean the following:

Next steps#

• Mining on Lithos: how difficulty shapes what you earn.
• Batching and orders: the settings your client uses to record and settle forwards.
• API reference: the endpoints behind the web panel.