Reduce Contract Parameters

[roconnor-blockstream]

Among the current set of parameters are the three parameters: CONTRACT_SIZE, STRIKE_PRICE, and GRANTOR_TOKEN_STRIKE_PRICE. However these three parameters are constrained such that you only need two of these parameters.

I recommend replacing these three parameters with just two parameters:

1. The CONTRACT_SIZE COLLATERAL_PER_CONTRACT, which is the amount of COLLATERAL_ASSET manipulated per token. This is what is currently called CONTRACT_SIZE.

2. What I would call SETTLEMENT_ASSET_SIZE, or something similar SETTLEMENT_PER_CONTRACT. This is what you are currently calling the GRANTOR_TOKEN_STRIKE_PRICE, which is not a great name, though I do understand why you choose it. This is the amount of TARGET_ASSET (which I also suggest renaming to SETTLEMENT_ASSET) manipulated per token.

In particular in the Exercise path code the line

divmod_eq(collateral_amount_to_get, param::ASSET_STRIKE_PRICE, asset_amount_to_pay);

would be replace with the mathematically equivalent line

divmod_eq(asset_amount_to_pay, param::GRANTOR_TOKEN_STRIKE_PRICE, option_amount_to_burn);

or

divmod_eq(asset_amount_to_pay, param::SETTLEMENT_PER_CONTRACT, option_amount_to_burn);

under my proposed name.

Worked Example

Let's do some unit analysis here with a worked example for a call option to purchase (Liquid) Bitcoin (the collatoral asset) using USDT (the settlement asset) at some particular price.

COLLATERAL_PER_CONTRACT would typically be something like 1 000 000 sats / contract (which would be displayed as 0.01 L-BTC / contract) and for call options is typically a round number.

SETTLEMENT_PER_CONTRACT could be something like 115 024 360 000 μ¢ / contract (microcents are units of USDT on liquid, though this would be displayed as $1 150.2436 / contract) and for call options is typically less round than the COLLATERAL_PER_CONTRACT.

The advantage of selecting these two parameters is that these two values are always integers, because the amounts of collatoral asset and settlement asset being manipulated is always an integer multiple of the COLLATERAL_PER_CONTRACT and the SETTLEMENT_PER_CONTRACT.

These two values together imply the strike price, which, for call options, is SETTLEMENT_PER_CONTRACT / COLLATERAL_PER_CONTRACT. In our worked example this is 115 024.36 μ¢ / sats, (which, after changing to more reasonable units would be displayed as $115 024.36 / L-BTC). Notice that this strike price isn't necessarily an integer. Thankfully the options contract can and should be written in a way that avoids directly working with this non-integer value. Instead the strike price would only appear in wallet UX.

A couple of further notes, what your code currently calls the ASSET_STRIKE_PRICE is actually the inverse of the strike price I've defined above; the ASSET_STRIKE_PRICE is constrained to be the CONTRACT_SIZE / GRANTOR_TOKEN_STRIKE_PRICE. The fact that ASSET_STRIKE_PRICE is constrained to be an integer is a big problem for the current implementation which would render the above call option impossible to build on Liquid. Thankfully we can eliminate the use of ASSET_STRIKE_PRICE in the contract without too much difficulty.

Also I'd like to note that what that the options white paper calls "strike price" is actually the SETTLEMENT_PER_CONTRACT and not actually what tradfi people would call the strike price. So definitely be aware of that pitfall when reading that document.

Lastly, I'll note for put options the roles of settlement and collateral are reversed, with USDT held has collateral and LBTC as settlement. So for put options it is the SETTLEMENT_PER_CONTRACT that is usually a round number, and for put options the strike price is now COLLATERAL_PER_CONTRACT / SETTLEMENT_PER_CONTRACT in order to still get units of USDT/LBTC.

(Edited based on the conversation below up to #5 (comment))

[roconnor-blockstream]

cc @apoelstra

[apoelstra]

FWIW users expect to see the strike price and for it to be an integer (more than an integer, they expect it to be an exact multiple of $2500 or some large quantity like this). If we force the strike price to be some non-integer quantity in order that some internal quantites be integral, that is a bad user experience and not something we can ship without embarassment. Especially since in practice, non-integral strike prices will always occur as a result of a contract writer choosing an integer and then encountering rounding issues defining contract parameters, resulting in strikes like $49 999.97.

My vote would be to use CONTRACT_SIZE and STRIKE_PRICE as the two quantities, since these correspond to quantites that users will interact with.

[apoelstra]

Note that, by your own equations, SETTLEMENT_ASSET_SIZE = STRIKE * CONTRACT_SIZE so if the latter are integers, so will SETTLEMENT_ASSET_SIZE. So I believe that using the strike and contract size will force everything to be an integer.

[roconnor-blockstream]

I extremely strongly disagree. There are loads of assets, on liquid with very weird unit subdivisions, and we cannot rely on SETTLEMENT_ASSET_SIZE / CONTRACT_SIZE being integer.

In particular we will want to simulate put options by the exact same smart contract, but with the roles of the COLLATERAL_ASSET and the SETTLEMENT_ASSET reversed. In which case, for a simulated put option the SETTLEMENT_ASSET_SIZE / CONTRACT_SIZE becomes the inverse of the strike price due to the reversal of the asset positions.

And once we have options between DOGE coins and PEPE coins, whose to say whether it is a call option or a put option?

[apoelstra]

In which case, for a simulated put option the SETTLEMENT_ASSET_SIZE / CONTRACT_SIZE becomes the inverse of the strike price

Yes, and in real life when writing cash-secured puts (for puts the term "cash secured" is used for "fully collateralized", for reasons that sorta-but-not-really make sense) you simply round up the amount of collateral that you need.

Changing these things for the sake of contract code feels like we're deviating from the rest of the industry, in ways that force rounding issues up to the level of user-visible contract parameters, in order to make our own code simpler.

[roconnor-blockstream]

Let's do a worked example of a put option again with contract size 0.01 L-BTC, aka 1 000 000 sats and a strike price of $125 000 / L-BTC, aka 125 000 μ¢ / sats, a nice round number.

For a put option it is the SETTLEMENT_ASSET_SIZE that is now 1 000 000 sats. By multiplying the strike price by the settlement asset size we get a contract size of CONTRACT_SIZE of 125 000 000 000 μ¢. This is the amount of USDT that needs to be depositing into the smart contract. Then, if the put option holder want to exercise the right to sell their L-BTC, the run the exercise operation and deposit 1 000 000 sats (0.01 LBTC) into a settlement covenant, and withdraw the locked collateral of 125 000 000 000 μ¢, which is $1 250. That's all fine

My point here is that SETTLEMENT_ASSET_SIZE / CONTRACT_SIZE, the thing you are proposing being a always an integer is 1 000 000 / 125 000 000 000 = 0.000008.

Okay, so we could have two different contracts, one that forces SETTLEMENT_ASSET_SIZE / CONTRACT_SIZE to be an integer for "call options" and another forcing CONTRACT_SIZE / SETTLEMENT_ASSET_SIZE to be an integer for "put options", but I don't really understand why we are doubling our smart contract complexity here when we have a perfectly good universal smart contract that just doesn't make any restrictions on the ratio of SETTLEMENT_ASSET_SIZE to CONTRACT_SIZE at all.

I'm not forcing rounding issues onto the user-visible contract parameter. The user visible UX can, and should, force the use of round numbers, and then derive the addresses of the covenants from that. Any covenants that deviate from the standard will simply be unrecognizable to the wallet, just like any of a million other ways an improperly or properly modified smart contract could become unrecognizable to a wallet.

[apoelstra]

Ok, after discussing with @roconnor-blockstream I understand the issue and have come to agree with him. The problem here is that I would like to use traditional terminology, but the traditional terminology is badly asymmetric between calls and puts (and therefore dangerously ambiguous when it comes to things like DOGE/PEPE options where neither asset is "cash" and the option is not really a call/put).

In particular, let's consider the difference between a 2025-12-31 $50k Bitcoin option, if it is a put or a call, as it would be presented in a traditional options market. Let's say the contract size is 0.1 BTC, as was done on LedgerX/MIAX until they shut down their options market.

For a $50k call option:

• If the option is fully collateralized we say it's "fully collateralized"
• BTC is the "collateral asset" (our term, but would be understood in tradfi)
• The "contract size" (us, and tradfi) is 0.1 BTC (denominated in the collateral asset)
• Cash is the "settlement asset" (our term, would cause confusion in tradfi since our options are "physically settled", a term which refers to BTC changing hands when exercise happens)
• What we call the "settlement asset size" is 0.1 * $50000 = $500 and represents the cost to exercise one contract. There isn't a word for this quantity in tradfi.

For a $50k put option:

• If the option is fully collateralized we say it is "cash secured"
• BTC is the "settlement asset" (our term, which would be less confusing to a tradfi person)
• The "contract size" in tradfi is still 0.1 BTC (now in terms of the "settlement asset") but in our terms would be $500 (still in terms of "collateral asset")
• Cash is the "collateral asset" (our term, now less confusing to tradfi)
• What we call the "settlement asset size" is 0.1 BTC, equal to the tradfi "contract size"

In summary we should stop using the term "contract size" entirely because its tradfi meaning is completely different for puts and calls, and only matches our terminology for calls, pretty-much guaranteeing confusion and bugs.

I'm not forcing rounding issues onto the user-visible contract parameter. The user visible UX can, and should, for the use of round numbers, and then derive the addresses of the covenants from that

Ok, great, this was a misunderstanding on my part.

[apoelstra]

I propose using COLLATERAL_ASSET_SIZE and SETTLEMENT_ASSET_SIZE, which is the same as @roconnor-blockstream's proposal except that I renamed CONTRACT_SIZE to COLLATERAL_ASSET_SIZE.

We should have a detailed block comment at the top of the file defining these terms, showing how they correspond to the traditional terminology used for calls and puts, and showing an example.

[roconnor-blockstream]

We should maybe rename COLLATERAL_ASSET_SIZE as COLLATERAL_PER_CONTRACT and similarly SETTLEMENT_PER_CONTRACT.

[coremoon]

In summary I agree fully to @apoelstra
BUT I also see new challenges

If tradfi terms for calls and puts are already occupied it would be best to invent new terms ( well well :-) )

See this example for a cross-asset Option contract:

Scenario: Alice buys an option on BTC to receive DOGE upon exercise

• Option type: Call option (right to buy DOGE by paying BTC)
• Strike price: 100 BTC per 10,000 DOGE (implying 1 DOGE costs 0.01 BTC at strike)
• Contract size: 10,000 DOGE (Collateral Asset: DOGE, Settlement Asset: BTC)
• Collateral Asset: DOGE (held by option writer as locked collateral)
• Settlement Asset: BTC (paid by option holder to exercise)
• Premium: 10 BTC upfront paid by Alice to Bob

Interpretation of terms:

• Collateral Asset: DOGE coins locked by Bob to secure his obligation to deliver DOGE if Alice exercises.
• Settlement Asset: BTC coins Alice must pay to acquire DOGE upon exercise.
• Contract Size: 10,000 DOGE (quantity of DOGE to be delivered).

Numerical Illustration (simplified):

Asset	Market Price (Spot)	Value in BTC
DOGE	0.02 BTC / DOGE	10,000 × 0.02 = 200 BTC
Strike Price	0.01 BTC / DOGE	10,000 × 0.01 = 100 BTC

Market movement conflict:

• At inception, strike price implies 100 BTC needed to buy 10,000 DOGE.
• Current market price is 0.02 BTC/DOGE, so 10,000 DOGE worth 200 BTC — significantly higher.

Conflicts and Challenges:

1. Collateral insufficiency risk:

   • Bob locked 10,000 DOGE as collateral.
   • But market price doubled; delivering 10,000 DOGE at 0.01 BTC/DOGE strike means Bob incurs a theoretical loss if DOGE’s market value is 0.02 BTC/DOGE.
   • If DOGE price rises further, collateral value remains fixed quantity, less able to cover Bob’s exposure.

2. Settlement asset liquidity and valuation:

   • Alice must pay BTC to exercise.
   • Volatility in BTC price impacts how much BTC Alice effectively pays (if BTC price fluctuates against fiat). These are two digital assets with volatile relative value.

3. Terminology confusion:

   • Traditional terms like “contract size” shift meaning depending on whether DOGE or BTC is collateral or settlement asset.
   • Collateral asset is DOGE, settlement asset is BTC, unlike classic options where “cash” is always fiat.

4. No intrinsic 'cash' asset:

   • Both DOGE and BTC are volatile digital assets, complicating margining, risk management, and collateral valuation.

5. Cross-chain operational issues:

   • DOGE and BTC exist on different blockchains.
   • Atomic settlement and collateral locking require cross-chain protocols, increasing complexity and risk.

Hence, this cross-asset contract illustrates upcoming conflicts including collateral value mismatch, ambiguous terminology, and operational challenges resulting from two different digital assets acting as collateral vs settlement assets.
A demand for clearer, symmetric terminology and robust cross-chain mechanisms to mitigate risks and user confusion (to me) arises.

[apoelstra]

This comment is very confused (and is written in a somewhat grating LLM dialect).

• A BTC/DOGE option is completely unaffected by either asset's exchange rate relative to cash.
• The collateral requirements of an option are unaffected by exchange rates between the two assets (all options we are considering are always fully collateralized)
• None of this has to do with the general option parameters discussed in this issue
• Cross-chain settlement issues are irrelevant options that are implemented entirely on Liquid

[KyrylR]

Addressed the issue here: #10

Thanks a lot for comments and review!